Getting started

This project uses an uv-only workflow and a small Makefile wrapper to run everything consistently.

Prerequisites

You need:

  • Python 3.14

  • uv on your PATH

  • GNU Make

Windows notes

  • Install GNU Make (e.g., via Chocolatey).

  • You can run everything from cmd.exe, PowerShell, or from WSL.

Verify tools

From the repository root:

make uv-check
make python-check
make python-info

First-time setup

Create a virtual environment and install dependencies:

make venv
make install-dev
make install-docs

Run the full development chain

make final

make final runs:

  • formatting (Ruff)

  • linting (Ruff)

  • type checking (mypy)

  • tests (pytest)

  • documentation (sphinx)

Documentation can be built separately via:

make docs

Run an experiment

Example (E001):

make run EXP=e001 ARGS="--seed 1"

See the experiment overview here: Experiments Gallery.

Build documentation locally

make docs

Output:

  • docs/_build/html

Troubleshooting

error: Failed to spawn: sphinx-build

Sphinx is not installed in the uv environment.

Fix:

make install-docs
make docs

make python-check fails

The repo enforces Python 3.14. Install Python 3.14, then recreate the environment:

make clean-venv
make venv
make install-dev
make install-docs