# Advanced quickstart

The end-to-end flow — package a checkpoint, ship a kit, freeze the claim as espresso@v1, verify the sim's doubts, and prove it across embodiments.

The [quickstart](/docs/quickstart/) proves the plumbing with a catalogue
task. This is the real shape of an engagement: a policy trained elsewhere, a
claim involving your own hardware, and evidence strong enough to release on.
Seven calls, start to finish.

## The whole flow

*Example: one claim, proven end to end*

**Python**

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

# ── 1. Package the learnings ──────────────────────────────
policy = roborama.Policy.checkpoint(
    hf="pi/espresso-v7",                  # weights + config + norm stats
    runtime="openpi",
    inference={"action_horizon": 50, "chunk_size": 50, "temp": 0.0},
    action_space="joint_delta_50hz",
    observation_contract="droid-3cam",
)

# ── 2. Ship the hardware the claim depends on ─────────────
kit = roborama.kits.register(
    name="pi-breville", items=[{"desc": "Breville BES870", "qty": 2}])
kit.shipping_label()  # -> received -> tracked -> available

# ── 3. Formalize the claim as a Task Spec ──────────────────────────────
task = roborama.tasks.create(
    name="espresso", visibility="private",
    initial_conditions={
        "machine": {"object": "kit/pi-breville",
                    "pose": "P1", "tol_mm": 20},
        "cup": {"object": "catalogue/cup-std-08", "randomize": "zone-A"},
    },
    instructions={
        "sampled_per_episode": ["make an espresso", "brew me a coffee",
                                "fais un espresso"],
        "held_out": ["prepare a single shot"],
    },
    stages=[{"grasp_cup": "gt.pose(cup) in gripper"},
            {"cup_placed": "gt.pose(cup) within drip_zone"},
            {"extraction": "scale.delta > 0 within 60s"},
            {"served": "all success_predicates"}],
    success_predicates=[{"cup_on_tray": "gt.pose(cup) within tray_zone"},
                        {"liquid_mass": "scale.delta between 25 and 40 g"},
                        {"no_spill": "vision.spill_area < 2 cm2"},
                        {"t_complete": "episode.duration < 180 s"}],
    envelope={"lighting": ["3000K", "5600K"], "distractors": "set-B",
              "out_of_scope": ["oat_milk"]},
    baseline={"internal_trials": 30, "internal_rate": 0.87},
)

# ── 4. Agree on the method, then freeze it ──────────────────────────────
pilot = task.pilot(robot="g1-edu-pro@fw2.3", episodes=25)
print(pilot.stream_url)                    # watch the calibration live
task.freeze()  # -> espresso@v1, immutable, co-signed

# ── 5. Screen in your simulator; verify the flagged tail physically ─────
# the sim's uncertain slice, verified physically
scenarios = roborama.scenarios.from_file("sim_flagged_p1.json")
report = roborama.verify(
    policy=policy, task="espresso@v1",
    scenarios=scenarios,
    robots=["g1-edu-pro@fw2.3"],
    audit_sample=0.10, return_ground_truth=True,
)

# ── 6. Then prove the cross-embodiment claim itself ───────
job = roborama.matrix(
    policy=policy, task="espresso@v1",
    robots=["g1-edu-pro@fw2.3", "g1-edu-pro@fw2.4",
            "g1-edu-plus@fw2.3", "stretch3@fw1.9"],
    environments=["kitchen-std@v1.2", "kitchen-replica@v2.0"],
    episodes_per_cell="auto(ci=0.95, moe=0.05)",
    interventions="none",
)

# ── 7. The evidence ──────────────────────────────
r = job.result()
r.heatmap()                # embodiment × environment, rate ± CI per cell
r.stage_rates              # where in the task each embodiment degrades
r.instruction_breakdown    # held-out phrasings reported separately
r.verification_report(format="pdf")  # cites espresso@v1, fw pins,
                                     # out-of-scope verbatim
job.export(format="lerobot")  # episodes back into training
```

**TypeScript**

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

const roborama = new Roborama();

// ── 1. Package the learnings ──────────────────────────────
const policy = Roborama.Policy.checkpoint({
  hf: "pi/espresso-v7", // weights + config + norm stats
  runtime: "openpi",
  inference: { action_horizon: 50, chunk_size: 50, temp: 0.0 },
  action_space: "joint_delta_50hz",
  observation_contract: "droid-3cam",
});

// ── 2. Ship the hardware the claim depends on ────────────
const kit = await roborama.kits.register({
  name: "pi-breville",
  items: [{ desc: "Breville BES870", qty: 2 }],
});
await kit.shippingLabel(); // -> received -> tracked -> available

// ── 3. Formalize the claim as a Task Spec ──────────────────────────────
const task = await roborama.tasks.create({
  name: "espresso",
  visibility: "private",
  initial_conditions: {
    machine: { object: "kit/pi-breville", pose: "P1", tol_mm: 20 },
    cup: { object: "catalogue/cup-std-08", randomize: "zone-A" },
  },
  instructions: {
    sampled_per_episode: ["make an espresso", "brew me a coffee",
                          "fais un espresso"],
    held_out: ["prepare a single shot"],
  },
  stages: [
    { grasp_cup: "gt.pose(cup) in gripper" },
    { cup_placed: "gt.pose(cup) within drip_zone" },
    { extraction: "scale.delta > 0 within 60s" },
    { served: "all success_predicates" },
  ],
  success_predicates: [
    { cup_on_tray: "gt.pose(cup) within tray_zone" },
    { liquid_mass: "scale.delta between 25 and 40 g" },
    { no_spill: "vision.spill_area < 2 cm2" },
    { t_complete: "episode.duration < 180 s" },
  ],
  envelope: {
    lighting: ["3000K", "5600K"],
    distractors: "set-B",
    out_of_scope: ["oat_milk"],
  },
  baseline: { internal_trials: 30, internal_rate: 0.87 },
});

// ── 4. Agree on the method, then freeze it ──────────────────────────────
const pilot = await task.pilot({ robot: "g1-edu-pro@fw2.3", episodes: 25 });
console.log(pilot.stream_url); // watch the calibration live
await task.freeze(); // -> espresso@v1, immutable, co-signed

// ── 5. Screen in your simulator; verify the flagged tail physically ─────
const scenarios = await roborama.scenarios.fromFile("sim_flagged_p1.json");
const report = await roborama.verifications.create({
  policy,
  task: "espresso@v1",
  scenarios,
  robots: ["g1-edu-pro@fw2.3"],
  audit_sample: 0.1,
  return_ground_truth: true,
});
console.log(report.sim_agreement);

// ── 6. Then prove the cross-embodiment claim itself ──────
const job = await roborama.matrices.create({
  policy,
  task: "espresso@v1",
  robots: ["g1-edu-pro@fw2.3", "g1-edu-pro@fw2.4",
           "g1-edu-plus@fw2.3", "stretch3@fw1.9"],
  environments: ["kitchen-std@v1.2", "kitchen-replica@v2.0"],
  episodes_per_cell: "auto(ci=0.95, moe=0.05)",
  interventions: "none",
});

// ── 7. The evidence ──────────────────────────────
const r = await job.result();
console.log(r.heatmap); // embodiment × environment, rate ± CI per cell
console.log(r.stage_rates); // where in the task each embodiment degrades
console.log(r.instruction_breakdown); // held-out phrasings, separate rows
await job.verificationReport({ format: "pdf" }); // cites espresso@v1, pins,
await job.export({ format: "lerobot" }); // episodes back into training
```

**cURL**

```bash
# ── 2. Ship the hardware the claim depends on ─────────────
curl https://api.roborama.com/v1/kits \
  -H "Authorization: Bearer $ROBORAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "pi-breville",
       "items": [{"desc": "Breville BES870", "qty": 2}]}'

# ── 3. Formalize the claim as a Task Spec ──────────────────────────────
curl https://api.roborama.com/v1/tasks \
  -H "Authorization: Bearer $ROBORAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "espresso",
    "visibility": "private",
    "initial_conditions": {
      "machine": {"object": "kit/pi-breville", "pose": "P1", "tol_mm": 20},
      "cup": {"object": "catalogue/cup-std-08", "randomize": "zone-A"}
    },
    "instructions": {
      "sampled_per_episode": ["make an espresso", "brew me a coffee",
                              "fais un espresso"],
      "held_out": ["prepare a single shot"]
    },
    "stages": [
      {"grasp_cup": "gt.pose(cup) in gripper"},
      {"cup_placed": "gt.pose(cup) within drip_zone"},
      {"extraction": "scale.delta > 0 within 60s"},
      {"served": "all success_predicates"}
    ],
    "success_predicates": [
      {"cup_on_tray": "gt.pose(cup) within tray_zone"},
      {"liquid_mass": "scale.delta between 25 and 40 g"},
      {"no_spill": "vision.spill_area < 2 cm2"},
      {"t_complete": "episode.duration < 180 s"}
    ],
    "envelope": {
      "lighting": ["3000K", "5600K"],
      "distractors": "set-B",
      "out_of_scope": ["oat_milk"]
    },
    "baseline": {"internal_trials": 30, "internal_rate": 0.87}
  }'

# ── 4. Pilot, then freeze the method as espresso@v1 ───────
curl https://api.roborama.com/v1/tasks/task_espresso_01/pilot \
  -H "Authorization: Bearer $ROBORAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"robot": "g1-edu-pro@fw2.3", "episodes": 25}'

curl https://api.roborama.com/v1/tasks/task_espresso_01/freeze \
  -H "Authorization: Bearer $ROBORAMA_API_KEY" \
  -X POST

# ── 5. Verify the sim-flagged tail physically (policy from step 1) ──────
curl https://api.roborama.com/v1/runs \
  -H "Authorization: Bearer $ROBORAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "verify",
    "task": "espresso@v1",
    "policy": {
      "type": "checkpoint", "hf": "pi/espresso-v7", "runtime": "openpi",
      "inference": {"action_horizon": 50, "chunk_size": 50, "temp": 0.0},
      "action_space": "joint_delta_50hz",
      "observation_contract": "droid-3cam"
    },
    "scenarios": {"format": "layout-replay",
                  "url": "https://acme.ai/sim_flagged_p1.json"},
    "robots": ["g1-edu-pro@fw2.3"],
    "audit_sample": 0.10,
    "return_ground_truth": true
  }'

# ── 6. Prove the cross-embodiment claim itself ────────────
curl https://api.roborama.com/v1/runs \
  -H "Authorization: Bearer $ROBORAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "matrix",
    "task": "espresso@v1",
    "policy": {
      "type": "checkpoint", "hf": "pi/espresso-v7", "runtime": "openpi",
      "inference": {"action_horizon": 50, "chunk_size": 50, "temp": 0.0},
      "action_space": "joint_delta_50hz",
      "observation_contract": "droid-3cam"
    },
    "robots": ["g1-edu-pro@fw2.3", "g1-edu-pro@fw2.4",
               "g1-edu-plus@fw2.3", "stretch3@fw1.9"],
    "environments": ["kitchen-std@v1.2", "kitchen-replica@v2.0"],
    "episodes_per_cell": "auto(ci=0.95, moe=0.05)",
    "interventions": "none"
  }'

# ── 7. The evidence ──────────────────────────────
curl "https://api.roborama.com/v1/runs/run_9110/report?format=pdf" \
  -H "Authorization: Bearer $ROBORAMA_API_KEY"
curl "https://api.roborama.com/v1/runs/run_9110/export?format=lerobot" \
  -H "Authorization: Bearer $ROBORAMA_API_KEY"
```

**Agent (tool-use payload)**

```json
[
  {
    "type": "tool_use",
    "name": "roborama_kits_register",
    "input": {
      "name": "pi-breville",
      "items": [{ "desc": "Breville BES870", "qty": 2 }]
    }
  },
  {
    "type": "tool_use",
    "name": "roborama_tasks_create",
    "input": {
      "name": "espresso",
      "visibility": "private",
      "initial_conditions": {
        "machine": { "object": "kit/pi-breville", "pose": "P1",
                     "tol_mm": 20 },
        "cup": { "object": "catalogue/cup-std-08", "randomize": "zone-A" }
      },
      "instructions": {
        "sampled_per_episode": ["make an espresso", "brew me a coffee",
                                "fais un espresso"],
        "held_out": ["prepare a single shot"]
      },
      "stages": [
        { "grasp_cup": "gt.pose(cup) in gripper" },
        { "cup_placed": "gt.pose(cup) within drip_zone" },
        { "extraction": "scale.delta > 0 within 60s" },
        { "served": "all success_predicates" }
      ],
      "success_predicates": [
        { "cup_on_tray": "gt.pose(cup) within tray_zone" },
        { "liquid_mass": "scale.delta between 25 and 40 g" },
        { "no_spill": "vision.spill_area < 2 cm2" },
        { "t_complete": "episode.duration < 180 s" }
      ],
      "envelope": {
        "lighting": ["3000K", "5600K"],
        "distractors": "set-B",
        "out_of_scope": ["oat_milk"]
      },
      "baseline": { "internal_trials": 30, "internal_rate": 0.87 }
    }
  },
  {
    "type": "tool_use",
    "name": "roborama_tasks_pilot",
    "input": { "task_id": "task_espresso_01", "robot": "g1-edu-pro@fw2.3",
               "episodes": 25 }
  },
  {
    "type": "tool_use",
    "name": "roborama_tasks_freeze",
    "input": { "task_id": "task_espresso_01" }
  },
  {
    "type": "tool_use",
    "name": "roborama_verify",
    "input": {
      "task": "espresso@v1",
      "policy": {
        "type": "checkpoint",
        "hf": "pi/espresso-v7",
        "runtime": "openpi",
        "inference": {"action_horizon": 50, "chunk_size": 50, "temp": 0.0},
        "action_space": "joint_delta_50hz",
        "observation_contract": "droid-3cam"
      },
      "scenarios": { "format": "layout-replay",
                     "url": "https://acme.ai/sim_flagged_p1.json" },
      "robots": ["g1-edu-pro@fw2.3"],
      "audit_sample": 0.1,
      "return_ground_truth": true
    }
  },
  {
    "type": "tool_use",
    "name": "roborama_matrix",
    "input": {
      "task": "espresso@v1",
      "policy": {
        "type": "checkpoint",
        "hf": "pi/espresso-v7",
        "runtime": "openpi",
        "inference": {"action_horizon": 50, "chunk_size": 50, "temp": 0.0},
        "action_space": "joint_delta_50hz",
        "observation_contract": "droid-3cam"
      },
      "robots": ["g1-edu-pro@fw2.3", "g1-edu-pro@fw2.4",
                 "g1-edu-plus@fw2.3", "stretch3@fw1.9"],
      "environments": ["kitchen-std@v1.2", "kitchen-replica@v2.0"],
      "episodes_per_cell": "auto(ci=0.95, moe=0.05)",
      "interventions": "none"
    }
  }
]
```

## What each step buys you

1. **Package the learnings.** `Policy.checkpoint` pins more than weights:
   the `inference` dict (`action_horizon`, `chunk_size`, `temp`) is recorded
   with the run, because a decoding change can move a rate as much as a
   training change. Details in [Policies](/docs/concepts/policies/).
2. **Ship the hardware.** The espresso machine arrives as a
   [kit](/docs/concepts/tasks-and-method-transfer/): tracked (mocap markers,
   mass, mesh scan) and referenceable as `kit/pi-breville`.
3. **Formalize the claim.** The Task Spec turns "makes espresso" into
   instrument-bound predicates, a phrasing distribution with held-out
   paraphrases, staged progress scoring, and declared boundaries
   (`out_of_scope: ["oat_milk"]` appears verbatim on the report).
4. **Agree, then freeze.** The pilot is watched live; the freeze produces
   `espresso@v1` — immutable, mutually signed, cited by every report.
5. **Spend reality where the sim is unsure.** [verify()](/docs/primitives/verify/)
   runs the sim-flagged tail plus a random audit sample, and returns ground
   truth to recalibrate the simulator.
6. **Prove the claim itself.** A task-pinned [matrix()](/docs/primitives/matrix/)
   across four embodiments and two kitchens, `interventions="none"` declared
   up front so the statistics are untouched by helping hands.
7. **Collect the evidence.** Rate ± CI per cell, `stage_rates` showing where
   each embodiment degrades, `instruction_breakdown` with held-out phrasings
   separated, a citable verification report, and the episodes back in
   `lerobot` format for the next training round.

## Reading the espresso evidence

The canonical single-cell result, from
[/fixtures/runs.json](/fixtures/runs.json) — overall 0.850 (n=412,
ci95 0.812–0.881), zero interventions:

```text
stage_rates
  grasp_cup    0.966  n=412  ci95=(0.944, 0.980)
  cup_placed   0.932  n=412  ci95=(0.904, 0.953)
  extraction   0.893  n=412  ci95=(0.860, 0.919)
  served       0.850  n=412  ci95=(0.812, 0.881)

instruction_breakdown
  "make an espresso"       0.873  n=118  ci95=(0.801, 0.921)
  "brew me a coffee"       0.866  n=112  ci95=(0.791, 0.917)
  "fais un espresso"       0.848  n=99   ci95=(0.765, 0.906)
  "prepare a single shot"  0.795  n=83   ci95=(0.696, 0.868)   held-out
```

The stages localize the loss: grasping is nearly solved, extraction gives up
seven points, serving five more. The held-out phrasing runs about eight
points behind the sampled set — the gap between "understands the
instructions it trained on" and "understands the task."

> **Seven calls, one claim proven:** The learnings arrive as pinned weights, the claim leaves as a frozen
> protocol, and the evidence returns with error bars — on every body it names.

## Where next

- [Tasks & method transfer](/docs/concepts/tasks-and-method-transfer/) — the Task Spec in full.
- [CI gates](/docs/guides/ci-gates/) — make the matrix a release check.
- [threshold()](/docs/primitives/threshold/) — buy the outcome instead of the runs.