Get Started¶

This page gets you from a fresh clone to a local docs preview and the first experiment notebooks.

Requirements¶

The project uses Python 3.11 or newer and Astral's uv for environment management.

Some workflows render videos or Graphviz diagrams. On Ubuntu, the CI installs:

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

GPU-enabled JAX and PyTorch dependencies are declared in pyproject.toml. uv will resolve them from the configured package indexes.

Setup¶

Clone the project and install the environment:

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

Run the test suite when you want a full health check:

uv run pytest -v

Preview the Documentation¶

The docs source lives in docs/. Zensical writes the static HTML site to the ignored site/ directory.

Start a local preview server:

uv run zensical serve

Build the static site and fail on broken links:

uv run zensical build --strict

First Notebooks¶

The easiest way to understand the main pipeline is to start with a small matrix environment.

Recommended first pass:

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

The same notebooks can also run as scripts. For example:

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

For the full artifact chain, run the world-model notebook first, then the opponent-model notebook, then the experiment notebook.