Contribute · Authoring guides

Add an environment backend

An environment backend has two halves. The worker half, ora/environment/backends/<sim>/, runs inside the simulator's own interpreter: it builds the scene, publishes observations, executes admitted actions and reads the official verdict. The host half, ora/orchestrator/backends/<kind>/, runs in ORA's interpreter: it owns the backend's RunSpec fields, preflight, qualification and evaluation hooks behind the registry. Follow environment compatibility authoring before adding prompts, tools or embodiment assets.

  1. Audit the upstream task/evaluator source, units, frames, public constants, reset/step/termination and official verdict. Record the source and asset versions you read. If a required input (a unit, a frame, a constant) cannot be confirmed from the upstream source, leave out the capability that needs it until it can.
  2. Do not write motion for the backend. Planning, IK, the collision world, timing, the wrist-unwind guard and the refusal vocabulary are the shared base (ora/environment/controllers/motion_*, ora/environment/planners/; architecture). The backend supplies its robot configuration (registered in ROBOTS, controllers/motion_planner.py, and in planners/curobo_v2/robots.py), which must pass a forward-kinematics parity check against the simulator (controllers/fk_parity.py: at session start and from a recorded fixture under tests/data/fk-parity/; backends/robodojo/shared_motion.py is the worked example), an execution adapter, and calibration for a real robot. A backend-local IK solver or planner needs a written reason, an owner and an expiry beside its code.
  3. Put task identities, suite expansion and source versions in ora/environment/benchmarks/<sim>.py, and the embodiment's control constants in ora/environment/controllers/, which must import without the simulator installed. Simulator imports belong in the worker half only.
  4. Write the worker half: a session class in ora/environment/backends/<sim>/session.py that implements the environment session contract (ora/environment/base.py) with public observations, action execution and measured receipts. Register the environment in ora/environment/definitions.py (its transports, embodiment, action schemas, capabilities and worker_loader), give ora/environment/worker.py the branch that builds the session and ora/environment/factory.py the builder that starts the worker. Route every state change through the Supervisor; never expose private evaluator state to the policy. worker.py and factory.py are pinned members of the RoboDojo worker kernel, so this step re-signs the RoboDojo qualification records (repository structure); say so in the pull request.
  5. Write the host half: ora/orchestrator/backends/<kind>/backend.py declaring BACKEND with its two required hooks (resolve_runtime, preflight_runtime), its capabilities and the optional hooks it needs (qualification, evaluation, play scenes, its ora run cell, its spec and qualify tools), and an entry in BACKENDS in ora/orchestrator/backends/registry.py. The orchestrator core never imports a backend module, so a backend difference becomes a capability or a hook, not a kind check in the core (backends README).
  6. Bind the reviewed embodiment, prompt bundle and ToolSurface, including units, refusal constraints and context projection. If the backend belongs in the default composition, add it to the default baseline (ora baselines --explain shows the result), describe it under docs/reference/ and add its default RunSpec as a cell of matrix() in scripts/dev/compare-model-visible, so later changes are compared on it, in the same pull request.
  7. Add contract tests that drive the session against a fake worker, so they run without the simulator, under tests/ora/environment/backends/<sim>/ and tests/ora/orchestrator/backends/<kind>/. Then run a short episode on the real simulator and state in the pull request the simulator and asset versions, tasks and seeds you ran. Run it again after any change to the controller, the assets or the simulator version; an earlier result does not carry over.
  8. Add a README to each half in the five-section form the other backends use, an environment page under docs/environments/ with installation and a one-task run, ora doctor discovery of its interpreter and assets, a row in the support matrix, and guidance in the New environment issue template.

Use the Synthetic backend as the reference for transport and lifecycle, and an existing robot backend such as LIBERO for the isolated-interpreter pattern (environment README). Before opening the pull request, run the checks in Contributing: the relevant tests, ./scripts/ora lock when ora/policy/ changed, and scripts/dev/compare-model-visible.