Contribute

Code map

Every package carries a README that says what it is responsible for, what belongs in it and what does not, which way its imports go, how it is entered and which pages document it. Start from the table below and follow the README. Code that belongs to one simulator lives in only two places: ora/environment/backends/<sim>/, which runs in that simulator's own interpreter, and ora/orchestrator/backends/<kind>/, the host side of the same backend. Everything else is shared by every environment; the architecture page shows the layers.

Packages

Package What it owns README
ora/ The Python package and its import rules ora
ora/contracts/ The versioned action envelope and the pose, motion, refusal and receipt contracts the agent and the environment share contracts
ora/environment/ Environment sessions, the registry of environments, the isolated worker and its local RPC, Synthetic environment
ora/environment/benchmarks/ Host-safe benchmark identities, rosters, pins and play-scene registries benchmarks
ora/environment/controllers/ Host-safe motion-transaction, safety and per-embodiment control contracts controllers
ora/environment/planners/ Motion planner workers behind the planner-neutral contract (curobo_v2/) and the path timing worker (timing/), each under its own interpreter planners
ora/environment/backends/<sim>/ The simulator adapters, imported only by the isolated worker LIBERO, RoboTwin, RoboDojo, RoboCasa365, RoboLab
ora/agent/ The policy side: the Python half of the Pi core, providers, model services, the agent trace and its export agent
ora/agent/code_mode/ Code mode (policy.code_mode): the script contract, the code tools, the bubblewrap sandbox, the robot library and the extended library (ora_lib, the observation mount), the persistent workspace code_mode
ora/agent/toolkit/ Runtime/replay public data interface and tool authoring capabilities toolkit
ora/agent/toolkit/interface/ Classified data capabilities and runtime/replay wire adapters interface
ora/agent/toolkit/interface/perception/ Explicit external model service calls interface/perception
ora/agent/toolkit/interface/state_access/ Current state reads and tool namespace writes interface/state_access
ora/agent/toolkit/interface/sim_query/ Worker planner requests and snapshot refusals interface/sim_query
ora/agent/toolkit/interface/sim_exec/ Action submission and snapshot refusals interface/sim_exec
ora/agent/toolkit/interface/lifecycle/ Episode control and replay output intents interface/lifecycle
ora/agent/toolkit/interface/privileged/ RSI-only privileged state reads interface/privileged
ora/agent/toolkit/interface/artifacts/ Granted blob and tool artifact access interface/artifacts
ora/agent/toolkit/interface/compute/ Pure numeric calculation interface/compute
ora/agent/toolkit/interface/context/ Context attachment declarations interface/context
ora/agent/toolkit/state/ Supervisor-owned namespaces, permissions and publication snapshots state
ora/agent/toolkit/lib/ Immutable typed capabilities and pure geometry, accessing data only through the interface lib
ora/agent/toolkit/tools/ Atomic tool migration and local policy helpers; public data interface only tools
ora/agent/toolkit/tools/grasp_plan/ Public grasp candidate policy and review grasp_plan
ora/agent/toolkit/tools/grasp_execute/ Prepared commitment and one action proposal grasp_execute
ora/agent/toolkit/tools/move_pose/ Measured-frame pose compilation, IK references and one action proposal. move_pose
ora/agent/toolkit/tools/move_to/ Translation-only motion with the measured orientation held. move_to
ora/agent/toolkit/tools/compute/ Restricted numeric expressions over caller-supplied bindings. compute
ora/agent/toolkit/tools/check_task/ The sole capability-gated data route to official task judgment. check_task
ora/agent/toolkit/tools/finish_episode/ Episode exit policy and the existing finish publication format. finish_episode
ora/agent/toolkit/tools/observe/ Current annotated cameras and retained raw public camera images. observe
ora/agent/toolkit/examples/ Editable replay scripts outside the immutable lib examples
ora/agent/toolkit/host/ The trusted host the toolkit's tools run under: their data interfaces, I/O recording, and the tool runtime frame each episode builds (runtime/) host
ora/agent/composition/ ToolSurface, embodiment, prompt-layer and task-contract resolution composition
ora/agent/context/ What an observation and a tool result deliver to the policy context
ora/orchestrator/ RunSpec to RunPlan (spec/), preflight, leases and launch, the Supervisor's episode loop (episode/), evaluation and sealing, reports, the suite queue, play scenes orchestrator
ora/orchestrator/backends/ The host side of each runtime.kind: RunSpec fields, preflight, qualification, seed scans, evaluation hooks, run cells, behind one registry backends
ora/orchestrator/toolkit/ Recorded-call selection, perception binding and script evaluation (ora toolkit replay) toolkit replay
ora/app/ The ora command: one parser, one command table, the help topics, the terminal and web front ends app
ora/policy/ Prompt layers, ToolSurfaces, embodiment and environment assets and the default baseline, pinned by policy.lock policy
ora/robot_client/ The standard-library ora-robot client of a free-play run robot_client
ora/cell/ The real-cell kit (ora cell): the cell config and calibration, the cell lock, bus and camera checks, camera calibration, the depth service, the cell board and the operator verbs, written against a robot's CellAdapter cell
ora-pi/ The TypeScript agent core (provider loop, request assembly, context, agent evidence) and ORA's web page ora-pi
ora-pi/src/context/stages/ The context stage driver and the stages a scheme lists (v6 and v8) stages
viewer/ The read-only run viewer (ora-viewer) and run dashboard (ora-viewer dashboard, viewer/dashboard/), its own package viewer
tests/ The CPU-only suite, a tree that mirrors the code tests
scripts/ The ora, ora-remote and docs wrappers and the development checks scripts
examples/ The quickstart smoke, the official-suite cells and the host template examples
docs-site/ The documentation site's build docs-site

Where a feature lives

Feature Location
Plan resolution, defaults and source identity ora/orchestrator/spec/ (run_spec.py and its section modules, defaults.py, source.py, source_overlay.py for runs on a base commit with replaced tool files); the compactor's own Provider binding in spec/context_compactor.py
The ora command ora/app/ (README): main.py (one parser, the command table and the grouped help) and one module per command group (plan.py, runs.py, evidence.py, run.py, setup.py, doctor.py, catalog.py, providers.py, services.py, and report.py, spec.py, qualify.py, suite.py, dev.py over the operator tools' own parsers)
Admission, leases and supervision preflight/ (gates.py, resources and host storage), leases.py, launch.py (launch, supervisor and landing seal), supervise.py (the supervisor process); ora/version.py (the version ora --version and the transcript headers show)
Terminal watch, interactive sessions and local CPU entry ora/agent/tui/ and ora-pi/src/watch/ (transcript and its pi-tui front end); ora/app/interactive.py, backend.py, task_catalog.py, local.py, local_setup.py, world.py, remote.py, remote_session.py, web.py, web_gateway.py, web_cell.py (a real cell's controls on the page), replay.py (a finished run's replay), replay_export.py (its video); ora/orchestrator/episode/operator_control.py; ora-pi/src/tui/, ora-pi/src/rpc/ (Pi RPC host, ora-rpc-attach), ora-pi/web/ (ORA's web page and its server, seeded from Watercol/pi-web-ui); ora/orchestrator/world_view.py; ora/environment/synthetic_capture.py; ora/agent/session_core/operator_messages.py
Episode coordination and official evaluation ora/orchestrator/episode/ (coordinator.py, loop.py, action_executor.py), ora/orchestrator/evaluation/ (evaluate.py and its checks); the run report in ora/orchestrator/reports/, the official-suite queue in ora/orchestrator/suite/; task files (ora task) in ora/orchestrator/task/
Free play (ora play): scenes, instructions in turn, Pi as a coding agent, its evidence ora/app/play.py, ora/orchestrator/spec/play.py, episode/play.py, evaluation/play.py, play/scenes.py; ora-pi/src/play/; ora/agent/evidence/play_trace.py; ora/policy/prompt_bundles/templates/episode-task-play-v2.md
native_api policy lifecycle and provider/tool loop (the Pi agent core) ora-pi/src/core/session.ts, dispatch.ts; its Python half in ora/agent/pi/
Context packs (policy.context_pack) ora/agent/composition/prompt/context_pack.py (pack, profile, texts, overlay, images), ora/orchestrator/spec/context_pack.py (plan binding), ora/agent/pi/context_pack_rpc.py (session RPC), ora-pi/src/context/context_pack.ts and compact_view.ts (delivery)
Provider protocols and credentials ora/agent/providers/; a bound rollout compactor's own provider in compactor_binding.py (Pi: ora/agent/pi/factory.py, ora-pi/src/core/context_wiring.ts)
Policy composition, embodiment and tool contracts ora/agent/composition/
The Python half of a native_api session on the Pi core: tool gateway and provider tool definitions, static prefix, observation and tool-result projections, receipt projection, the PolicySession wrapper ora/agent/session_core/
Context projection, compaction and delivery ora/agent/context/
Recoverable context artifact storage ora/agent/memory/ (historical package name; no Task Memory)
Policy-visible tools and closed skills ora/agent/toolkit/tools/ (the tools), ora/agent/toolkit/host/ (their host, with the runtime frame in host/runtime/)
Resident perception services ora/agent/model_services/
Trace and policy-state evidence ora/agent/evidence/
Action envelopes and shared validation ora/contracts/
Free-play robot scripting (ora-robot) ora/robot_client/ (standard-library client), ora/agent/pi/robot_socket.py (socket and script calls; script_stop.py, a real cell's stop ending a script), ora/orchestrator/episode/script_actions.py (Supervisor admission and execution)
Transport-neutral sessions and workers ora/environment/
Host-safe benchmark identities and task catalogs ora/environment/benchmarks/
Host-safe controller contracts ora/environment/controllers/
Motion planning: the planner-neutral contract, the public-depth world, the FK parity check, the host's copy of the planner's Panda spheres, the base-placement search and the base move's check (footprint and carried arm), the planner workers ora/environment/controllers/motion_planner.py, depth_world.py, depth_world_inputs.py, depth_esdf.py, fk_parity.py, robot_spheres.py, base_placement.py, held_depth.py; ora/environment/planners/
Simulator implementations ora/environment/backends/{robotwin,libero_pro,robodojo,robocasa,robolab}/
Host-side orchestration one backend owns: RunSpec builders, preflight, qualification, seed scans, evaluation, probes ora/orchestrator/backends/{robodojo,robotwin,libero_pro,robocasa,robolab}/; RoboDojo motion journals, metrics and control replay in backends/robodojo/motion/. The RoboDojo worker and play kernels, the scene and layout smokes, the lane revalidation checker and the play-scene audit stay at ora/orchestrator/robodojo_*.py: kernel history, checker identity and the play kernel's files name those paths
Versioned prompt/tool/environment assets ora/policy/; integrity in policy.lock
One-cell and official-suite examples examples/, ora/orchestrator/spec/benchmark.py, ora/orchestrator/backends/{robodojo,robocasa,robolab}/spec.py
Play scenes (a qualified scene without its task) ora/orchestrator/play/scenes.py (scenes, build_play_spec), ora/orchestrator/play/binding.py (bind_play_runtime) and each backend's play hook in ora/orchestrator/backends/<backend>/play.py; the backends' play bindings in backends/libero_pro/direct.py and backends/robotwin/session.py
ORA's own RoboTwin play scenes (--scene-set tabletop-v1) and their audit ora/environment/benchmarks/robotwin_play_scenes.py (host-safe registry: sets, scenes, source binding); ora/environment/backends/robotwin/play_scenes/ (worker-only base.py, tabletop_v1.py); backends/robotwin/play_scene_audit.py (the worker's build, settle and render checks); ora/orchestrator/backends/robotwin/play_audit.py (the audit command, its record and play_scene_admission)
ORA's own RoboDojo play scenes (ora play --env robodojo, isaac-tabletop-v1) and their audit ora/environment/benchmarks/robodojo_play_scenes.py (host-safe registry code: sets, index loading, per-scene source binding, validate_play_runtime, the audit's criteria), robodojo_play_layouts.py (host-safe per-seed layout generator); ora/environment/backends/robodojo/play_scenes/ (worker-only: scene YAMLs and each set's index.yml of scene entries, lifecycle.py reward-free TaskEnv, operator_view.py the operator's third-person camera, bootstrap.py Kit boot, session.py worker backend robodojo_play, audit.py checks); ora/environment/robodojo_play_factory.py (worker config); ora/orchestrator/robodojo_play_kernel.py (code-only play kernel identity), robodojo_play_audit.py (the audit command, its record and play_scene_admission), backends/robodojo/play_preflight.py (launch checks)
Read-only run registry and media inspection viewer/

Use the explicit canonical subpackages for imports. The package root does not re-export implementation classes. Add shared behavior to its owner rather than to a launcher or benchmark-specific example. Contributor instructions describe the required checks, and the repository structure states the import rules and the files that may not move.

Source: docs/code-map.md