Get Started¶

This page takes a fresh checkout through installation, validation, a small baseline run, and the three-stage learned-shield workflow.

Requirements¶

Python 3.11 or newer
Astral uv for dependency and command execution
Graphviz and FFmpeg for diagrams and video workflows
a CUDA-capable setup for the configured JAX/PyTorch GPU dependencies when running the full training workloads

On Ubuntu, install the system tools with:

sudo apt-get update
sudo apt-get install -y graphviz ffmpeg

Install¶

git clone --depth=1 https://github.com/nightly/omsh
cd omsh
uv sync --all-groups --all-extras
uv run pre-commit install

All repository Python commands should run through uv run; this uses the locked project environment instead of an unrelated global interpreter.

Validate the Checkout¶

Run the broad non-slow test tier and the strict docs build:

uv run python scripts/run_tests.py fast
uv run zensical build --strict

For day-to-day development, use the changed-file selector instead:

uv run python scripts/run_tests.py changed

It reports when documentation validation is also required. See Testing for component and slow-test selections.

Run a Small Baseline¶

Chicken is a compact two-agent environment. Open its experiment notebook interactively:

uv run marimo edit notebooks/matrix/chicken/experiments_mo.py

Or run one short IPPO-only script pass. Algorithms are opt-in, so only IPPO needs to be selected:

uv run python notebooks/matrix/chicken/experiments_mo.py \
  --run-ippo=true \
  --num-runs=1 \
  --timesteps=64 \
  --rollouts=64 \
  --use-wandb=false

The first JAX execution may spend longer compiling than the nominal 64-step budget suggests.

Run the Learned-Shield Pipeline¶

The learned shield needs the world-model and opponent-model artifacts first:

uv run python notebooks/matrix/chicken/train_wm_mo.py --n-steps=25000
uv run python notebooks/matrix/chicken/train_om_mo.py
uv run python notebooks/matrix/chicken/experiments_mo.py \
  --run-ippo-shielded=true \
  --num-runs=1

The WM stage trains the default masked categorical successor kernel; pass --wm-variant=bit_mlp for the product-Bernoulli baseline. Use the same --n-agents value at every stage for Gathering, Pursuit, or Congestion. Pursuit's experiment stage defaults to max_risk=0.16, just above the successor model's reset demand (about 0.1515); pass --max-risk=0.11 only to reproduce the earlier product-Bernoulli campaign.

The Training Pipeline explains the artifacts and the Configuration reference lists the CLI keys.

Evaluate the Frozen Policy¶

Add frozen final-policy evaluation to any experiment run. It measures the policy at its last update on fresh seeds, separately from the training curve:

uv run python notebooks/matrix/chicken/experiments_mo.py \
  --run-ippo-shielded=true --run-cpo=true \
  --num-runs=1 --experiment-tag=chicken_smoke \
  --final-policy-eval-episodes=100

Reports land in exports/matrix/chicken/experiments/runs/chicken_smoke/final_policy/. See Final-Policy Evaluation.

Where to Go Next¶

Guarantees and Robustness explains what the shield's certificate does and does not promise, and how to check it.
Experiments lists every stage and the settings the published campaign uses.
Analysis and Audits catalogues the offline scripts.
The interactive field guide teaches probabilistic shielding with live calculations on a small MDP.

Preview the Docs¶

uv run zensical serve

Zensical writes generated HTML to the ignored site/ directory. Use uv run zensical build --strict before committing documentation changes.