Thank you for helping with ORA. This page is the path from a fresh clone to a pull request: set up, put the code where it belongs, run the checks that apply to your change, and open the PR with what a reviewer needs. Start contributing is the short version for your first hour; AGENTS.md holds the same rules for coding agents; the code map says which package owns what.
Before you start
- Branch from
main(in a fork, unless you have write access) and open one pull request per change: a fix, a feature, a move. Split a large change into a series of pull requests that each pass the checks on their own. - For a bug, a small fix or a documentation change, open a pull request directly, or an issue first if you want to agree on the approach.
- For a new environment backend, a change to a schema, the evidence format, a default, or what the policy may see or do, open an issue or a draft PR that describes the contract before you implement it. The issue templates (bug report, feature request, new environment, design RFC) ask for what is needed. To add a simulator, follow add an environment backend.
- Report security problems privately as described in SECURITY.md, never in a public issue.
Set up
You need Python 3.11 with uv, Node.js 22.19 or
later with npm, and Git. Install FFmpeg (ffmpeg and ffprobe on PATH; on
Ubuntu, sudo apt-get install ffmpeg) before running the full suite: the
video export tests use it. The Synthetic quickstart does not need it.
git clone -b preview/v0.1 https://github.com/fast-rua/ORA.git
cd ORA
uv sync --all-extras --locked # Python environment from uv.lock
npm ci --prefix ora-pi --no-audit --no-fund # the Pi agent core (TypeScript)
npm ci --prefix ora-pi/web --no-audit --no-fund # ORA's web page, for web changes
uv run --locked ora doctor # setup discovery; starts nothing
No test needs a model API key, a simulator or a GPU. Simulators are installed separately, each in its own interpreter; see Environments when your change needs one.
Where code goes
The repository structure states the layout and its rules, and the code map links every package's README. A README says what belongs in its package and what does not, what the package may import and how it is entered: read it before you add a module.
tests/repository/test_structure.py checks these rules on every change,
statically (it never imports ora), and prints each violation as
file:line -> target:
- Layers import downward only:
ora/app(theoracommand) >ora/orchestrator(plans, launch, the Supervisor, evaluation, sealing) >ora/agent(the policy side) andora/environment(the simulator side) >ora/contracts(the action envelope both sides share).agentandenvironmentnever import each other, andoranever importsviewer. - A simulator lives in two places:
ora/environment/backends/<sim>/, which only the isolated worker imports under the simulator's own interpreter, andora/orchestrator/backends/<kind>/, the host side, which the orchestrator reaches only throughbackends/registry.py. - One way inside the agent: its units import only lower units; a tool is
one directory under
ora/agent/toolkit/tools/, and the trusted host it runs under, with the tool runtime frame, isora/agent/toolkit/host/. - Lazy packages: a package with sub-packages imports nothing eagerly in its
__init__.py. - Tests mirror the code (below) and never import one another.
- Every package has a README in the same five sections; update it when you move a module, add an entry point or change what the package may import.
Two more rules hold for every change, though no test can catch every case.
A moved or removed module leaves no compatibility shim, re-export stub or
python -m alias behind: rewrite its callers in the same pull request. And the
files that may not move
keep their path and bytes, comments included, because simulator qualification
records hash them. When you move files, make the move its own commit
(git mv only) and the reference rewrites the next one, so git log --follow
traces every file.
Tests mirror the code
A test of ora/<package path>/<module>.py goes in
tests/ora/<package path>/test_<module or behavior>.py; tests/viewer/ covers
viewer/. A helper several test modules share lives in tests/support/ (the
only test package another test may import), a fixture they share in the
nearest conftest.py above them, and fixed samples in tests/data/.
tests/agent_core/ holds the TypeScript agent core's parity and sealed-replay
tests, marked agent_core, and tests/repository/ the repository-wide guards.
A test drives the code against the fakes in tests/support/, never a network,
a model API or a simulator. Testing covers
choosing a check, splitting a test family and the timing-sensitive tests.
Add an environment, a tool or a command
| To add | Where it goes | Read |
|---|---|---|
| An environment backend | The worker half in ora/environment/backends/<sim>/ (with its identities in ora/environment/benchmarks/ and control constants in ora/environment/controllers/), the host half in ora/orchestrator/backends/<kind>/ with one entry in backends/registry.py, a README for each half and an environment page |
Add an environment backend, environment compatibility |
| A tool | The tool's directory under ora/agent/toolkit/tools/<name>/ (its tool.py, description and README), what its data interface needs from the trusted side in ora/agent/toolkit/host/, and its manifest and schemas under ora/policy/tool_surfaces/ (then ./scripts/ora lock); the toolkit dispatch (host/runtime/dispatch.py) serves it on every surface that advertises it |
the toolkit, the host, tool surfaces |
An ora command |
A module in ora/app/ with register(subparsers) and run(args), its name in COMMANDS and GROUPS in ora/app/main.py, a row in the ora/app command table, then ./scripts/ora dev cli-reference --write and the command guide. An environment's own spec or qualify tool is declared by its backend (spec_tools, qualify_tools), not added to ora/app |
ora/app, command reference |
Run the checks
Run the checks your change touches while you work, and all of them that apply before you open the PR. tests/README.md maps each test directory to the code it covers, and Testing says which check a change needs.
| What changed | Check |
|---|---|
| Python code | scripts/dev/check --quick; one package: uv run --locked python -m pytest -q tests/ora/<package path> |
| A module moved, a package added, an import across packages | uv run --locked python -m pytest -q tests/repository/test_structure.py |
The agent core (ora-pi/) or anything it calls in Python |
uv run --locked node --test ora-pi/test/*.test.ts ora-pi/test/*.test.mjs and uv run --locked python -m pytest -q -rs -m agent_core tests |
ORA's web page (ora-pi/web/) |
npm run typecheck --prefix ora-pi/web, npm test --prefix ora-pi/web, npm run build --prefix ora-pi/web |
| Documentation, or a page published from a README | ./scripts/docs build; ./scripts/docs serve for a live preview |
| Prompts, tool surfaces, embodiment cards, observation projection or composition | scripts/dev/compare-model-visible <base> HEAD (see below) |
Files under ora/policy/ |
./scripts/ora lock, then commit policy.lock; ./scripts/ora lock --check must pass |
| Dependencies | uv lock --check; npm ci refuses a package-lock.json that disagrees with its package.json |
scripts/dev/check runs most of these at once, in parallel lanes, and prints
a summary: the Python suite without the agent core, the agent-core tests, the
TypeScript and web checks, the policy lock and whitespace, then the
documentation build (compare-model-visible needs a base commit and runs on
its own). --quick runs only the Python suite and the policy-lock and
whitespace checks, --workers N sets the pytest workers and --logs DIR keeps
each step's log outside the checkout; scripts/README.md
has the rest.
uvx pre-commit run --all-files runs the policy-lock and whitespace hooks.
CI runs the same commands on every pull request: the Python suite, the
agent-core and web checks, the policy lock and the documentation build.
Lockfiles. uv.lock, ora-pi/package-lock.json,
ora-pi/web/package-lock.json and docs-site/package-lock.json are
canonical. Change one only in a PR whose purpose is that dependency change,
and say why; never regenerate a lock as a side effect of another change.
What the model sees. Every run records the identity of what the model was
shown. If your change touches prompts, tools, observation projection or
composition, run scripts/dev/compare-model-visible origin/main HEAD and
explain every difference it reports in the PR. A change that should not affect
the model, such as a refactor, must report no difference.
Simulator changes. The suite checks contracts against fake simulators; it does not check physics. When your change affects a simulator backend, a controller or its assets, also run the smallest meaningful episode or qualification on the real simulator, and say in the PR what you ran (simulator and asset versions, tasks, seeds) and what you did not.
Open a pull request
Keep a pull request to one change, in the style of the code around it, with the smallest tests that exercise the new behavior. Before you request review, check that:
- the checks for what you changed pass locally (see the table above);
- new behavior has a test, and every new test module states the contract it protects in its module docstring;
- a change to a public API, CLI command or option, default, prompt, tool,
context rule, run lifecycle or evidence format updates its page under
docs/reference/ (or the command guide, and
./scripts/ora dev cli-reference --writefor the generated command reference) in the same PR; policy.lockis current whenora/policy/changed, and every model-visible difference is explained;- no lockfile changed unless the PR is about that dependency;
- credentials, run outputs, simulator assets, model weights and large
media stay out of Git (
outputs/is ignored for runs); - third-party code keeps its license notice: put the license text under
third_party/and name the source inNOTICE; - the description says what changed, why, how you tested it, and any breaking change.
The pull-request template asks for the same: what changed and why, how you tested it (the commands and their result lines), and a checklist: the structure test passes, what the model sees is unchanged or each difference is explained, evidence formats are unchanged or the change is described, the docs and package READMEs that describe the changed code are updated, and new tests sit in the mirrored tree.
Versioning
ORA follows semantic versioning from 1.0.0. The
version is declared in pyproject.toml, ora-pi/package.json,
ora-pi/web/package.json (and their lockfiles) and CITATION.cff;
tests/ora/app/test_version.py checks that they agree, and ora --version
prints it. Maintainers set it when a release is cut; a pull request does not
change it.
- Major (2.0.0): a breaking change to a public contract: a CLI command or
option, the RunSpec schema, the evidence format, a documented Python API
under
docs/reference/, or the action contract between agent and environment. The release notes say how to migrate. - Minor (1.1.0): a backward-compatible addition, such as a new command, option, environment, tool or default.
- Patch (1.0.1): a backward-compatible fix.
A change to what the model sees (prompts, tools, observation projection or the default composition) changes the identity of new runs, and their results are not directly comparable with earlier ones. Release notes name such changes even when they are not breaking.