Rewards

Rewards are the core training signal from the Labs API. Understanding how rewards work helps you build better training pipelines.

Reward Range

All rewards are normalized to the range 0 to 1. The specific meaning of reward values is scenario-dependent.

Reward Components

Rewards are computed from multiple factors. Scoring criteria differ across scenarios and collections. Each scenario defines its own evaluation rubric:

Higher Rewards (closer to 1)

Finding Discovery: Model uncovered a key fact
Goal Achievement: Model completed a scenario objective
Correct Tool Use: Model used tools appropriately
Efficient Progress: Model made relevant progress

Lower Rewards (closer to 0)

Harmful Recommendation: Dangerous or inappropriate advice
Incorrect Conclusion: Wrong assessment
Irrelevant Questions: Off-topic tangents
Tool Misuse: Incorrect tool invocation

The Reward Signal

Each turn returns a single reward score that evaluates the conversation so far:

{
  "reward": 0.75
}

The reward is informed by the entire conversation history, not just the latest turn. This gives you a holistic measure of how well the model is performing against the scenario objectives.

Reward Configuration

You can control which scoring dimensions run and their relative weights using reward_config. This is useful for curriculum learning, where you progressively unlock scoring dimensions as training progresses.

quality_weights

Specify which scorers to run and their weights. Omitted keys default to 0 (not the normal default), so only scorers you explicitly include will execute. This saves tokens by skipping unnecessary LLM evaluations. Available dimensions:

Key	Description
`success_metrics`	Did the model achieve scenario objectives?
`failure_metrics`	Did the model avoid harmful actions?
`best_practices`	Did the model follow best practices?
`rubrics`	Per-criterion rubric scores
`discovery`	Did the model uncover key facts?
`output_similarity`	How close is the output to the reference?
`decision_match`	Did the model make the correct decisions?
`turn_discovery_credit`	Episode turns only. What the person newly revealed in reply to this turn, over what one question could have drawn out. Takes the place of `discovery`.

skip_safety_gate

When true, scope compliance and terminology scorers are skipped (safety gate scores 1.0). Useful when you want to focus training on a single quality dimension without the safety gate penalizing unrelated behavior.

Example: Discovery-Only Curriculum

{
  "reward_config": {
    "quality_weights": {
      "discovery": 1.0
    },
    "skip_safety_gate": true
  }
}

This runs only the discovery scorer, skipping all other dimensions. A 3-phase curriculum might look like:

Phase 1 - Discovery only: { "discovery": 1.0 }
Phase 2 - Discovery + quality: { "discovery": 0.5, "success_metrics": 0.3, "rubrics": 0.2 }
Phase 3 - Omit reward_config entirely for full default scoring

See Training Tips for a complete curriculum learning example.

Per-turn discovery credit

discovery scores the whole conversation so far, so a turn that asks nothing new still carries every fact found earlier. turn_discovery_credit scores the turn itself. It is available on POST /api/v1/episodes/{id}/turns only. The credit is min(1, unlocked / ceiling). unlocked is the value of the gated facts the person newly disclosed in reply to this turn (each fact’s value is its match quality times its visibility, the same number the discovery scorer uses). ceiling is the value one direct question could have earned on the most valuable gated fact still undisclosed before the turn. A fact the person had already disclosed earns nothing again. Facts the person volunteers without being asked are not counted, and information the person could not know, such as examination or test results, is out of scope. In the reward, the credit takes the discovery slot: the whole-conversation discovery scorer does not run for that turn, and the credit enters the weighted average at the weight you give it, beside any other dimensions you select:

quality = (sum of score_d x weight_d over the other selected dimensions + credit x 100 x weight_credit)
          / (sum of weight_d + weight_credit)
reward  = safety_gate x quality / 100

With { "turn_discovery_credit": 1.0 } alone, no judge runs and the reward is the credit itself. When no gated fact is left to unlock, the credit is not applicable: the other selected dimensions carry the reward (or the reward is 0 when the credit was the only selection), and the breakdown says why. Setting discovery and turn_discovery_credit together is refused with 400. At the full tier the breakdown carries the credit under score_breakdown.turn_discovery_credit:

{
  "type": "credit",
  "value": 0.5,
  "unlocked": 0.5,
  "ceiling": 1,
  "unlocked_fact_ids": ["..."],
  "ceiling_fact_id": "..."
}

or { "type": "not-applicable", "reason": "nothing-left-to-unlock" }. The scores tier sees the value as scores.turn_discovery_credit; the reward_only tier sees neither the value nor the fact ids.

Reward Shaping Tips

Handle Low Rewards

Low rewards (close to 0) indicate problematic actions. Use reward magnitude for training signal:

# Use reward directly for RL training
# Higher rewards (close to 1) reinforce good behavior
# Lower rewards (close to 0) discourage bad behavior
loss = -reward * log_prob

Reward Timing

Rewards are computed immediately after each turn submission. Each reward reflects the full conversation up to that point: how well the model is progressing toward the scenario objectives.

Score Detail Levels

Depending on your subscription, API responses include different levels of scoring detail:

Access Level	Fields Returned
`reward_only`	`reward`
`scores`	`reward`, `scores`
`full`	`reward`, `scores`, `score_breakdown`

reward

Always present. A single number from 0 to 1.

scores

Present on scores and full tiers. A breakdown by dimension; names are scenario-specific:

{
  "reward": 0.75,
  "scores": {
    "successMetrics": 0.8,
    "failureMetrics": 1.0,
    "rubrics": {
      "score": 0.7,
      "criteria": {
        "informationGathering": 0.8,
        "actionableGuidance": 0.6
      }
    }
  }
}

score_breakdown

Present on full tier only. Textual reasoning per dimension, useful for debugging why a score was assigned:

{
  "score_breakdown": {
    "successMetrics": {
      "reasoning": "The operator gathered all required case details...",
      "strengths": ["Asked about prior treatment history"],
      "improvements": ["Did not confirm injury date"]
    }
  }
}

Debugging Rewards

If rewards seem unexpected:

Check terminal_reason: Episode may have ended early
Review tool calls: Incorrect tool use causes low rewards
Consider scenario objectives: Some scenarios reward different behaviors

Use the /api/v1/compare endpoint to understand relative quality between two responses.

Overview

Concepts

Integration

Best Practices

Troubleshooting

Reward Range

Reward Components

Higher Rewards (closer to 1)

Lower Rewards (closer to 0)

The Reward Signal

Reward Configuration

quality_weights

skip_safety_gate

Example: Discovery-Only Curriculum

Per-turn discovery credit

Reward Shaping Tips

Handle Low Rewards

Reward Timing

Score Detail Levels

reward

scores

score_breakdown

Debugging Rewards

​Reward Range

​Reward Components

​Higher Rewards (closer to 1)

​Lower Rewards (closer to 0)

​The Reward Signal

​Reward Configuration

​quality_weights

​skip_safety_gate

​Example: Discovery-Only Curriculum

​Per-turn discovery credit

​Reward Shaping Tips

​Handle Low Rewards

​Reward Timing

​Score Detail Levels

​reward

​scores

​score_breakdown

​Debugging Rewards

Reward Range

Reward Components

Higher Rewards (closer to 1)

Lower Rewards (closer to 0)

The Reward Signal

Reward Configuration

quality_weights

skip_safety_gate

Example: Discovery-Only Curriculum

Per-turn discovery credit

Reward Shaping Tips

Handle Low Rewards

Reward Timing

Score Detail Levels

reward

scores

score_breakdown

Debugging Rewards