Skip to main content
◆ FORGE · concepts
The forge has one unit of work (the campaign) and one rule underneath everything: nothing is fabricated, and nothing advances on your behalf. This page is the mental model behind the quickstart’s calls.

​
Campaign

A campaign is one walk of a dataset through the pipeline: an owner-scoped record tying the source dataset, its health report, the sampled episodes, the transform plan, the run jobs, your review verdicts, and the delivery state.
  • Per-user tenancy. Campaigns belong to the account that created them. A campaign id that isn’t yours reads as 404: the API never confirms a foreign resource exists (see errors).
  • Monotonic stage. stage is the furthest step you’ve reached; it never rolls back. You can leave and re-enter anywhere; re-saving an earlier step doesn’t undo a later one.
  • Three ways to start one: open a curated sample, upload a LeRobot dataset, or point at a Hugging Face repo_id.

​
The six-step spine

​
Target class and eligibility

Health detects the dataset’s classes and measures everything against one target class (the engine’s certified default, or one you switch to, switching recomputes health for that class). Per episode, eligibility for new-trajectory work requires a clean grasp → carry → place arc:
  • on-target class: off-target episodes are excluded outright;
  • grasp on the certified arm: the wrong arm is an exclusion, with the arm named;
  • a real release: no place event means no splice point;
  • travel above the jitter threshold: a “release” that barely moved is noise, not a placement.
Every exclusion carries its exact reason in the funnel and on the episode grid. The detected annotations, grasp_frame, splice_frame (the release), pre_release_frame, travel_deg, are yours to read per episode at …/episodes/{ep}/actions.json, overlaid on the native action stream.

​
The miner

New trajectories are head × tail splices: episode A’s scene, reach, and grasp continued with episode B’s carry and place. The miner scores every eligible (A, B) pair of the target class on three axes:
  • divergence: how differently the two post-grasp arm paths move (RMS joint distance over time-resampled paths). Candidates must sit inside the engine’s divergence band: different enough to be a new behavior, close enough that the render model obeys.
  • end_divergence: how differently the two episodes place (distance between placement configurations). Within the band, pairs are ranked by this: it’s the visible drama.
  • n_blend: seam feasibility: the minimum blend frames so no action dimension jumps faster than the dataset’s own 99th-percentile step.
Results are de-duplicated under per-head and per-tail caps, and, when the campaign has prior runs, re-weighted toward heads that historically pass the gates. The playground’s precise splice is this same miner pinned to one head; its partners records are full pair dicts you POST back verbatim.

​
Machine verdict and gates

Every rendered candidate is scored by an action-consistency verifier: does the video’s implied motion match the trajectory that was asked for? Three readings, each against a per-engine calibrated threshold: Two more checks ride along: a task gate (did the pick-and-place actually complete?) and an identity gate (zero frames of object-identity drift). The machine verdict is accept only when all five hold. A task check that can’t run abstains, recorded as not-run, never counted as a failure. A render that fails outright is rejected with the reason recorded; garbage is never gated. Thresholds and readings are on every episode and in its delivered certificate.

​
Confirm, overrule, and the kept set

Verdicts exist only for graded episodes (machine accept or reject); reviewing an ungraded one returns 409. Two verbs:
  • confirm: you agree with the machine;
  • overrule: you flip it: keeping a machine-reject, or dropping a machine-accept. Overrules are recorded as yours, with a timestamp, on the campaign record (the certificate carries the machine’s readings).
The kept set is the machine verdict with your overrules applied. Unreviewed episodes trust the machine: an unreviewed machine-accept is kept. Reviewing is free, so grade honestly, not strategically.

​
Delivery and the billed set

Deliver freezes the kept set at request time, drops any episode whose render artifacts are no longer on disk (billing you for a phantom would be worse than a 409), then debits 1 credit per kept episode that has never been billed on this campaign, atomically, before anything is exported. The paid set persists on the campaign as billed_episodes, so re-delivering after new keeps charges only the additions, and nothing ever bills twice. The archive contains exactly the billed set: per-view mp4s, action streams at both fps, and a provenance certificate per episode. Full rules in billing.

​
Playground refs: wb/<campaign>/<episode>

A described change in the playground becomes a real scenario batch bound to its exact source episode by reference:
wb/ marks a workbench campaign episode; the campaign id scopes it to you; the trailing integer is the episode index. Batches carrying a wb/ ref render with the campaign’s engine and verify like any campaign run.

​
What runs today

Honestly, per transform:
  • New trajectories: live end to end: mine, compose, render, verify, deliver. This is the engine both playground verbs use.
  • Object swap: preview. The shared action verifier applies, but the general video swap backend isn’t connected to the workbench yet; the Transform step shows the exact readiness steps.
  • Environment restyle: blocked on a fidelity floor: on our reference batch, restyled output scored below the verifier’s acceptance line. We show that reading instead of shipping it.
The Transform step’s readiness checklist is the source of truth per deployment: a run that isn’t ready is refused with the missing step named, not queued and quietly failed.