OpSafari / laborix

# laborix
`laborix` is a **fully offline** orchestrator for autonomous experiment
pipelines, in the spirit of Agent-Laboratory-style research automation. It
implements and verifies the **mechanics** of automated research programs —
versioned plan schemas, dependency-safe deterministic execution, tamper-evident
provenance ledgers, budget-respecting scheduling under uncertainty, ablation
bookkeeping, and report synthesis — rather than the creativity of any
particular language model.
At runtime the package depends only on NumPy. PyTorch (CPU-only) is an optional
extra powering the trainable surrogate-scheduling demos. Every default test and
example runs without network access; "experiment steps" in the demos execute
real NumPy computations on synthetic data.
## Installation
 [code] 
## Quick start
 [code] 
The demo executes a complete synthetic research program offline — plan →
schedule → run → ablate → report — and prints measured regret against the
oracle, ablation coverage, and the artifact ledger summary (for example
`{"coverage": {"method": true, "seed": true}, "regret": 4.5, "runs": 24,
"synthetic": true}`). Everything it produces is reproducible from the printed
seeds and config hashes.
## CLI
The `laborix` command-line tool provides one subcommand per lifecycle stage:
| Subcommand | Purpose |
| --- | --- |
| `validate` | Statically validate a research plan: schema version, dependency DAG (cycle detection, dangling refs), typed step inputs/outputs, resource annotations — with precise error messages |
| `plan` | Emit example/templated research plans in the versioned JSON schema |
| `run` | Execute a plan deterministically: topological step order, bounded parallelism with ordering guarantees, retries with jitter and attempt ceilings, timeouts, cancellation with clean partial-state semantics |
| `resume` | Resume a crashed or cancelled run from the ledger — completed steps replay from recorded artifacts instead of recomputing; final artifacts are byte-identical to a straight run |
| `schedule` | Run the bandit-based experiment scheduler (UCB1 / Thompson sampling) over candidate configurations under budget constraints, reporting cumulative regret vs. the oracle |
| `ablate` | Generate and execute an ablation matrix from a factor grid with coverage checks (every factor varied while others are fixed at least once) and missing-cell detection |
| `ledger` | Inspect and verify the append-only provenance ledger, including the chained-hash tamper-evidence check |
| `verify` | Re-verify recorded artifact hashes and ledger integrity for a run directory |
| `report` | Synthesize a Markdown/self-contained-HTML research report from ledger + result tables, with paired comparisons, deterministic bootstrap CIs, embedded reproducibility metadata, and a limitations section generated from actual coverage/budget facts |
| `demo` | The full offline end-to-end demonstration described above |
Exit codes are documented in docs/exit-codes.md.
## Common commands
| Comman