# threshold()

The soak-to-verify outcome contract — iterate on commodity hardware until a target rate is verified on the escalation tier.

Every other primitive sells measurement. `roborama.threshold()` sells an
outcome: iterate until verified at the target. You declare the rate you need,
the task, and a monthly cap; Roborama manages the embodiment ladder
underneath and calls your webhook when the number is real.

## The call

*Example: roborama.threshold()*

**Python**

```python
import roborama  # reads ROBORAMA_API_KEY from the environment

contract = roborama.threshold(
    policy_stream=roborama.PolicyStream(webhook="https://acme.ai/ckpt"),
    target={"success_rate": 0.99, "ci": 0.95, "task": "bin_pick@v1"},
    iterate_on="soak",               # commodity tier, e.g. nori-a3 pods
    escalate_to="g1-edu-pro@fw2.3",  # verification tier on crossing
    monthly_cap_usd=12_000,
)

contract.on_verified(webhook="https://acme.ai/release-gate")
print(contract.id, contract.status)
```

**TypeScript**

```typescript
import Roborama from "@roborama/sdk"; // reads ROBORAMA_API_KEY

const roborama = new Roborama();

const contract = await roborama.runs.create({
  kind: "threshold",
  policy_stream: { webhook: "https://acme.ai/ckpt" },
  target: { success_rate: 0.99, ci: 0.95, task: "bin_pick@v1" },
  iterate_on: "soak", // commodity tier, e.g. nori-a3 pods
  escalate_to: "g1-edu-pro@fw2.3", // verification tier on crossing
  monthly_cap_usd: 12000,
});

await contract.onVerified({ webhook: "https://acme.ai/release-gate" });
console.log(contract.id, contract.status);
```

**cURL**

```bash
curl https://api.roborama.com/v1/runs \
  -H "Authorization: Bearer $ROBORAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "threshold",
    "policy_stream": { "webhook": "https://acme.ai/ckpt" },
    "target": { "success_rate": 0.99, "ci": 0.95, "task": "bin_pick@v1" },
    "iterate_on": "soak",
    "escalate_to": "g1-edu-pro@fw2.3",
    "monthly_cap_usd": 12000,
    "on_verified": { "webhook": "https://acme.ai/release-gate" }
  }'
```

**Agent (tool-use payload)**

```json
{
  "type": "tool_use",
  "name": "roborama_threshold",
  "input": {
    "policy_stream": { "webhook": "https://acme.ai/ckpt" },
    "target": { "success_rate": 0.99, "ci": 0.95, "task": "bin_pick@v1" },
    "iterate_on": "soak",
    "escalate_to": "g1-edu-pro@fw2.3",
    "monthly_cap_usd": 12000,
    "on_verified": { "webhook": "https://acme.ai/release-gate" }
  }
}
```

## The contract, field by field

`policy_stream` is the input side: a `PolicyStream` whose webhook receives
checkpoints straight from your training loop. Every checkpoint you push enters
the evaluation queue — no human packaging step between a training run and
physical episodes.

`target={"success_rate": 0.99, "ci": 0.95, "task": "bin_pick@v1"}` is the
outcome being bought: the contract completes when a checkpoint is verified at
0.99 on `bin_pick@v1` with 95% confidence, not when a point estimate grazes
the number.

`iterate_on="soak"` sets where the grinding happens: the commodity tier —
nori-a3 pods at $7/robot-hour — cheap enough to evaluate checkpoints
continuously as training produces them.

`escalate_to="g1-edu-pro@fw2.3"` is the verification tier. When a checkpoint
crosses the target on soak — canonically 0.992 (n=1188, ci95 0.985–0.995) —
it escalates to the target embodiment, where the verdict that gates your
release is actually measured.

`monthly_cap_usd=12_000` is a hard cap, metered live. The contract pauses at
the cap with `monthly_budget_exceeded` and resumes next period; it never
quietly overruns.

> **Soak crossing is a trigger, not a verdict:** The soak tier decides *when* to spend verification-tier hours, not whether the
> target is met. The number your release gate hears comes from the escalation
> embodiment.

## The embodiment ladder

The ladder is the price structure. Training noise — checkpoints that were
never going to cross — burns $7/robot-hour pods, not verification-tier
humanoids. Only a checkpoint that earns escalation touches
`g1-edu-pro@fw2.3`. You stop choosing between statistical rigor and iteration
volume, because the cheap tier buys volume and the expensive tier buys the
verdict.

## Agent-native by design

No human is required anywhere in this loop. A training run pushes a
checkpoint at 3 a.m.; soak episodes accumulate; `threshold.crossed` fires when
a checkpoint crosses; the escalation run schedules itself; and the URL you
registered with `on_verified` hears the physical verdict — programmatically,
with n and interval attached. Wire that webhook to your release gate and the
loop closes: train, push, verify, ship, without a meeting.

Tier rates and the burst/standard/soak multipliers are on
[/pricing/](/pricing/); caps and metering are covered in
[billing and budgets](/docs/guides/billing-and-budgets/).