Skip to content

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

Use the same --n-agents value at every stage for Gathering, Pursuit, or Congestion. The Training Pipeline explains the artifacts and the Configuration reference lists the common CLI keys.

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.