Code and data

Quick start

make fetch
make setup
make check

make fetch downloads the 1.10 GB RoboBallet Zenodo release and checksum-verifies it into vendor/roboballet/data/start_states/ (cached, re-run safe). make setup builds a Python 3.10 venv inside the repo at .venv with the pinned jax/mujoco stack — it never writes into a shared venv. make check is the merge gate: the changed-files lint/type/shellcheck ratchet plus the unit lane (tests/test_allocate.py, tests/test_cli.py, tests/test_agent_llm.py, tests/test_bench_runner.py, tests/test_bench_controllers.py, tests/test_census.py, tests/test_rss_guard.py, tests/test_ship_video.py, tests/test_usd_finite.py; 153 tests) — the same command CI runs on every pull request. The simulator-backed tests are in make test-full.

Other targets

target	meaning
make test-full	this repo's whole suite (tests/), including the slow referee/motion tests
make test	the vendored upstream suite (vendor/roboballet), i.e. the V0 baseline — red by design at 44 pass / 42 known upstream failures (SPEC.md:52)
make gpu	smoke-test that jax sees a CUDA device (needs a GPU; nothing else here does)
make coverage	full suite under the coverage floor configured in pyproject.toml
make lint-all / make types-all	whole-tree ruff / mypy (the nightly lane; make check only judges changed files)
make format	manual ruff format pass — not enforced, because a repo-wide reformat collides with branches in flight

Prerequisites

Python 3.10, uv, aria2c and unzip on PATH, plus disk for the upstream data: the 1.10 GB Zenodo tarball (measured: 1,097,095,126 bytes, cached outside the repo by default) and the 1.6 GB data/start_states/ set it extracts into vendor/ (that size from upstream/MANIFEST.md), on top of the wheel set and the venv. Everything here is CPU-only except make gpu.

Running the pipeline

.venv/bin/python scripts/d0_eval_cell.py --set 0 --out runs/d0
.venv/bin/python scripts/d1_reach.py --set 0 --restarts 8 --seed 0 --out runs/d1
.venv/bin/python scripts/d2_allocate.py runs/d1/reach_set0.npz
.venv/bin/python scripts/d3_run.py runs/d1/reach_set0.npz --set 0 --out runs/d3

D1 is the expensive stage (252 s of IK for set 0 at 8 restarts, plus ~20 s of env build). The one-command form is make repro: it chains these four stages into runs/repro/, asserting each stage exits 0 with a non-empty receipt, d3's criteria all pass, and the README set-0 oracle holds -- scripts/repro_check.py re-reads the d3 receipt and requires solved 37/37, 0 collisions and every criterion true (D3's own exit code accepts 35/37) (~6-8 min, D1 dominates; kept out of make check). D3 reads a saved reachability artifact, so tests/test_motion.py resolves its fixture as $D3_REACH_NPZ first and then the committed tests/data/reach_set0.npz; set D3_REACH_NPZ to point the suite at a fresh D1 run instead of the fixture.

multiarm-agent (Hecaton)

Agentic CAM research for multi-arm cells: from a task description to a verified, collision-free plan for three or more robot arms, simulation first, no RL training. The human is on the loop, not in it — the LLM picks allocation and priorities, deterministic tools do IK, reachability, routing, motion planning and collision checking, and a vendor referee scores the result.

This repository reproduces and extends the RoboBallet 8-arm evaluation cell (Lai et al., Science Robotics 2025) with our agentic stack instead of their trained GNN. The pipeline is four stages, each a script that leaves a receipt on disk:

stage	what it produces	measured on eval set 0
D0 cell	the exact vendored PlanningEnv eval cell (8 Panda arms, 40 targets)	8 arms, 40 targets, 30 obstacle primitives, 42 s referee timeout
D1 reach	per (arm, target) collision-free IK + reachability matrix	63 / 320 pairs, 37 / 40 targets reachable by some arm (16, 30, 32 by none)
D2 allocate	greedy baseline vs OR-Tools multi-vehicle routing (makespan)	OR-Tools 9.36 s vs greedy 11.22 s (16.5 % better)
D3 motion + execute	space-time reserved per-arm trajectories, run in the referee	37 / 37 reachable targets solved, 0 collisions, makespan 36.3 s

Goal, scope and acceptance oracles: SPEC.md. Demo plans: docs/DEMO1-PLAN.md (M1, RoboBallet reproduction) and docs/DEMO2-PLAN.md (M2, Iron Man suit-up). Surgery bench — vision, plan and measured status: docs/surgery/BENCH.md. Vendored upstream release: upstream/MANIFEST.md.

Quick start

make fetch
make setup
make check

make fetch downloads the 1.10 GB RoboBallet Zenodo release and checksum-verifies it into vendor/roboballet/data/start_states/ (cached, re-run safe). make setup builds a Python 3.10 venv inside the repo at .venv with the pinned jax/mujoco stack — it never writes into a shared venv. make check is the merge gate: the changed-files lint/type/shellcheck ratchet plus the unit lane (tests/test_allocate.py, tests/test_cli.py, tests/test_agent_llm.py, tests/test_bench_runner.py, tests/test_bench_controllers.py, tests/test_census.py, tests/test_rss_guard.py, tests/test_ship_video.py, tests/test_usd_finite.py; 153 tests) — the same command CI runs on every pull request. The simulator-backed tests are in make test-full.

Other targets

target	meaning
make test-full	this repo's whole suite (tests/), including the slow referee/motion tests
make test	the vendored upstream suite (vendor/roboballet), i.e. the V0 baseline — red by design at 44 pass / 42 known upstream failures (SPEC.md:52)
make gpu	smoke-test that jax sees a CUDA device (needs a GPU; nothing else here does)
make coverage	full suite under the coverage floor configured in pyproject.toml
make lint-all / make types-all	whole-tree ruff / mypy (the nightly lane; make check only judges changed files)
make format	manual ruff format pass — not enforced, because a repo-wide reformat collides with branches in flight

Prerequisites

Python 3.10, uv, aria2c and unzip on PATH, plus disk for the upstream data: the 1.10 GB Zenodo tarball (measured: 1,097,095,126 bytes, cached outside the repo by default) and the 1.6 GB data/start_states/ set it extracts into vendor/ (that size from upstream/MANIFEST.md), on top of the wheel set and the venv. Everything here is CPU-only except make gpu.

Running the pipeline

.venv/bin/python scripts/d0_eval_cell.py --set 0 --out runs/d0
.venv/bin/python scripts/d1_reach.py --set 0 --restarts 8 --seed 0 --out runs/d1
.venv/bin/python scripts/d2_allocate.py runs/d1/reach_set0.npz
.venv/bin/python scripts/d3_run.py runs/d1/reach_set0.npz --set 0 --out runs/d3

D1 is the expensive stage (252 s of IK for set 0 at 8 restarts, plus ~20 s of env build). The one-command form is make repro: it chains these four stages into runs/repro/, asserting each stage exits 0 with a non-empty receipt, d3's criteria all pass, and the README set-0 oracle holds -- scripts/repro_check.py re-reads the d3 receipt and requires solved 37/37, 0 collisions and every criterion true (D3's own exit code accepts 35/37) (~6-8 min, D1 dominates; kept out of make check). D3 reads a saved reachability artifact, so tests/test_motion.py resolves its fixture as $D3_REACH_NPZ first and then the committed