Concepts

Architecture

ORA has two loops: the agent (the policy) decides what to try; the trusted runtime decides whether and how an action may execute. How ORA works walks through one turn and the interfaces that share it.

flowchart TB
    API[Model API] <--> N[Agent core: Pi by default]
    M[Task + manual + tool contracts] --> N
    O[Public observations + receipts] --> N
    N --> T[Tool call / action proposal]
    T --> S[Supervisor]
    S --> W[Isolated environment worker]
    W --> O
    W --> V[Official benchmark verdict]
    N --> E[Canonical evidence]
    S --> E
    V --> E
    E --> R[Evaluate + seal]
    R --> G[Viewer / export]

The agent can inspect public observations and propose actions. It cannot mutate simulator state directly, inspect privileged task state or set the official verdict. Read-only geometry/perception tools produce evidence; mutation tools submit versioned proposals to the Supervisor. Motion planning and simulator stepping remain behind the environment boundary.

The worker runs in the simulator's interpreter over local_rpc. Simulator imports stay out of the host-safe resolver, benchmark catalogs and contracts. Synthetic uses an in-process environment for infrastructure checks.

A RunSpec supplies task, provider, resources and budgets. Resolution selects a default baseline when applicable, binds policy assets and source identity, and produces a content-addressed RunPlan. Preflight checks fresh dependencies and admission before a resource lease is claimed. The supervisor executes the exact plan and attempts evaluation/sealing at landing.

The agent core's context assembly preserves the task, tool contract and current public state while managing tool history and recoverable artifacts. Context artifacts are episode evidence; they are not cross-episode Task Memory.

Layers

The Python package ora has four layers, and each imports only the layers below it:

ora/app            the `ora` command: parse, ask, print, draw
   |
ora/orchestrator   RunSpec to RunPlan, preflight, leases, launch, the
   |               Supervisor's episode loop, evaluation, sealing, reports
   +---------------------------+
   |                           |
ora/agent                   ora/environment
the policy side: tools,     sessions, the isolated worker,
composition, context,       Synthetic, the simulator backends
providers, the agent trace
   |                           |
   +---------------------------+
   |
ora/contracts      the action envelope and the contracts both sides share

ora/agent and ora/environment never import each other: they meet in ora/contracts, and the orchestrator binds a policy session to an environment session. Beside the layers sit ora/policy (data only, pinned by policy.lock) and ora/robot_client (standard library only). The TypeScript agent core in ora-pi/ reaches Python only over its RPC channel, and the read-only viewer/ imports ora while ora never imports it. tests/repository/test_structure.py checks these rules on every change.

Where a backend lives

Code that belongs to one simulator lives in exactly two places:

Location Runs Holds
ora/environment/backends/<sim>/ Inside the simulator's own interpreter, in the isolated worker Scene construction, observations, motion execution, the official verdict; ora/environment/definitions.py names its worker session as a "module:attr" string
ora/orchestrator/backends/<kind>/ On the host, in ORA's interpreter The kind's RunSpec fields, preflight, seed or lane qualification, evaluation hooks, play scenes and ora run cell; ora/orchestrator/backends/registry.py maps each runtime.kind to its backend as a "module:attr" string

The environment core loads a backend only in the worker (ora/environment/worker.py), and the orchestrator core reaches one only through the registry, so neither imports a simulator. The host-safe facts both sides need (task identities, pins, controller limits) are in ora/environment/benchmarks/ and ora/environment/controllers/. Add an environment walks through both halves, and the code map links every package's README.

One motion base for every backend

Motion planning, inverse kinematics, the collision world, path timing (TOPP-RA and Ruckig), the wrist-unwind guard and the refusal vocabulary are one simulator-independent base that every backend shares: ora/environment/controllers/motion_* and ora/environment/planners/. A backend supplies only three things: its robot configuration, which must pass a forward-kinematics parity check against the simulator's own kinematics; an execution adapter that writes the base's joint targets to the simulator or robot and reads the measured state back; and, for a real robot, its calibration. A backend-local IK solver or planner needs a written reason, an owner and an expiry beside its code: motion_exception.py in the backend's directory, which tests/repository/test_motion_exceptions.py requires of any backend that plans its own motions and fails once it has expired. The YAM station has one (its motion.py, until the shared planner and timing are qualified on the real cell).

Status on 2026-11-01: LIBERO, RoboDojo, RoboTwin, RoboCasa365 and RoboLab plan on the shared planner (cuRobo V2 behind controllers/motion_planner.py, in the public-depth collision world; for the two-arm X5 and ALOHA the other arm stands in that world) and time every route with the shared timing worker; shared_motion.py in environment/backends/{robodojo,robotwin,robocasa,robolab}/ is the whole of what each adds. The SDK's IK still answers RoboDojo's straight lines; RoboCasa's are the shared IK's, and its Panda plans as franka_panda, so the Omron base and torso are no robot links and count only where the cameras see them. RoboLab's servo stays for contact and short moves, under the shared step caps (motion speed). The vendored planner stays in RoboTwin's worker for the expert, the seed scans and a session with no bound planner, and takes a move when the shared worker errors; the exception's owner is the qualification pin (session.py, vendored/), and it ends when the seed scans re-qualify on the shared planner.

Status on 2026-11-15: the real YAM station plans its own IK lines (environment/backends/yam/motion.py) by default. A run may plan them on the shared planner instead (runtime.motion_planner, ora play --motion-planner, off by default; backends/yam/shared_planner.py) and time them with the shared timing worker (runtime.motion_timing, ora play --motion-timing, off by default; backends/yam/shared_motion.py); both stay off until they are qualified on the real cell with the operator present (motion speed).

controllers/fk_parity.py is the check every robot passes before a planner speaks for it: the planner's forward kinematics against the simulator's, at session start and from a recorded fixture in CI (tests/data/fk-parity/).

The real bimanual I2RT YAM cell is the exception still open: by default it plans with its own mink IK and planner (environment/backends/yam/motion.py). The shared planner has a robot for it, yam_linear_4310 (planners/curobo_v2/yam.py: one arm of i2rt's station URDF for either arm, the other arm in the world as for the X5 and the ALOHA), with its recorded parity fixture, and since 2026-11-15 the backend plans on it behind runtime.motion_planner (backends/yam/shared_planner.py): a free-space move is one collision-free plan in the public-depth world of the station's four calibrated cameras, a precision or contact move the station's straight line by the shared IK, checked in that world; the cell's calibration is carried as the planners README describes, and the station's timing, per-tick checks and refusal words stay. The exception ends when the switch is qualified on the real cell and made the default.

Runtime lifecycle · Interfaces · Configuration and evidence

Source: docs/architecture.md