Quickstart

This guide will have you running your first episode in under 5 minutes.

Prerequisites

An API key from the Labs Portal
Python 3.11+ (or any HTTP client)
An active subscription to at least one collection

Step 1: Get Your API Key

Log in to the Labs Portal
Navigate to API Keys
Click Create New Key
Copy and save your key (it won’t be shown again)

Step 2: Browse Available Scenarios

First, let’s see what collections you have access to:

curl -X GET "$LABS_URL/api/v1/catalog" \
  -H "Authorization: Bearer $LABS_API_KEY"

Step 3: Create an Episode

Pick a scenario and create a training episode:

# Create an episode
data = json.dumps({
    "collection_slug": "case-management",
    "scenario_slug": "back-injury-claim"
}).encode()

req = urllib.request.Request(
    f"{BASE_URL}/api/v1/episodes",
    data=data,
    headers={**headers, "Content-Type": "application/json"},
    method="POST"
)
with urllib.request.urlopen(req) as response:
    episode = json.loads(response.read())

episode_id = episode["episode_id"]
initial_obs = episode["initial_observation"]["content"]
tools = episode["tools"]

print(f"Episode ID: {episode_id}")
print(f"Initial observation: {initial_obs}")
print(f"Available tools: {len(tools)} tools")

curl -X POST "$LABS_URL/api/v1/episodes" \
  -H "Authorization: Bearer $LABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_slug": "case-management",
    "scenario_slug": "back-injury-claim"
  }'

Step 4: Submit Turns

Now submit your model’s responses and collect rewards:

done = False
turn = 0

while not done:
    turn += 1

    # Your model generates a response (simplified for demo)
    model_response = f"Turn {turn}: Tell me more about your symptoms."

    # Submit the turn
    data = json.dumps({
        "messages": [
            {"role": "assistant", "content": model_response}
        ]
    }).encode()

    req = urllib.request.Request(
        f"{BASE_URL}/api/v1/episodes/{episode_id}/turns",
        data=data,
        headers={**headers, "Content-Type": "application/json"},
        method="POST"
    )
    with urllib.request.urlopen(req) as response:
        result = json.loads(response.read())

    # Extract results
    observation = result["observation"]["content"]
    reward = result["reward"]
    done = result["episode_complete"]

    print(f"Turn {turn}:")
    print(f"  Reward: {reward:.2f}")
    print(f"  Observation: {observation[:100]}...")

    if done:
        print(f"  Episode complete! Reason: {result.get('terminal_reason', 'unknown')}")

curl -X POST "$LABS_URL/api/v1/episodes/{episode_id}/turns" \
  -H "Authorization: Bearer $LABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "assistant", "content": "Tell me more about your symptoms."}
    ]
  }'

Step 5: Use Tool Calls (Optional)

Some scenarios have tools (artifacts to create, decisions to make). Tool calls are attached to the assistant message:

# Submit a turn with a tool call (tool_calls attached to the message)
data = json.dumps({
    "messages": [
        {
            "role": "assistant",
            "content": "Based on our conversation, I'm creating an assessment.",
            "tool_calls": [
                {
                    "type": "artifact",
                    "name": "medical_assessment",
                    "input": {
                        "condition": "lower_back_strain",
                        "severity": "moderate",
                        "recommendation": "physical_therapy"
                    }
                }
            ]
        }
    ]
}).encode()

req = urllib.request.Request(
    f"{BASE_URL}/api/v1/episodes/{episode_id}/turns",
    data=data,
    headers={**headers, "Content-Type": "application/json"},
    method="POST"
)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read())

Complete Example

Here’s a full training loop (pseudocode - replace your_model with your actual model):

Next Steps

Integration Guides

Set up with TRL, OpenRLHF, or NeMo-Aligner

API Reference

Full endpoint documentation

Concepts

Understand episodes, rewards, and tools

Best Practices

Tips for effective training

Overview

Concepts

Integration

Best Practices

Troubleshooting

Prerequisites

Step 1: Get Your API Key

Step 2: Browse Available Scenarios

Step 3: Create an Episode

Step 4: Submit Turns

Step 5: Use Tool Calls (Optional)

Complete Example

Next Steps

Integration Guides

API Reference

Concepts

Best Practices

​Prerequisites

​Step 1: Get Your API Key

​Step 2: Browse Available Scenarios

​Step 3: Create an Episode

​Step 4: Submit Turns

​Step 5: Use Tool Calls (Optional)

​Complete Example

​Next Steps

Integration Guides

API Reference

Concepts

Best Practices

Prerequisites

Step 1: Get Your API Key

Step 2: Browse Available Scenarios

Step 3: Create an Episode

Step 4: Submit Turns

Step 5: Use Tool Calls (Optional)

Complete Example

Next Steps