AGENTS.md

This repository is managed with uv. Use uv run ... so the project environment and Cython extensions are built and loaded consistently.

Active project path

The active product and research path is JAX + PPO:

src/lost_cities_jax/: pure JAX rules, observations, PPO, evaluation, league, and human-play tools.
configs/jax_ppo/: active YAML configurations.
web/: static TypeScript client with the final JAX PPO ONNX policy.
web/public/models/jax-ppo.onnx: verified browser policy. Keep its manifest in sync and do not replace it without running the export validation.

Historical Deep CFR and ISMCTS implementations live under src/coolrl_lost_cities/games/classic/. Their configs are in legacy/; they are reproduction-only and must not be used as the default for new work. See docs/legacy.md.

Core commands

uv run ruff check .
uv run pytest -q tests/lost_cities_jax
uv run pytest -q
uv run lost-cities-jax-ppo --help

Web checks:

cd web
npm test
npm run build

JAX PPO workflow

CPU smoke runs write disposable artifacts under runs/tmp/:

uv run lost-cities-jax-ppo rollout-smoke --config configs/jax_ppo/smoke.yaml
uv run lost-cities-jax-ppo train --config configs/jax_ppo/smoke.yaml

GPU training must hold the shared compute lock. Use a real tmux session for long user-observable jobs:

flock -n .compute.lock uv run --with 'jax[cuda12]' lost-cities-jax-ppo train \
  --config configs/jax_ppo/balanced.yaml \
  --set run.artifact_root=runs/jax-ppo

Evaluation is deterministic and does not need the lock:

uv run lost-cities-jax-ppo eval \
  --config configs/jax_ppo/balanced.yaml \
  --checkpoint runs/jax-ppo/<run>/latest \
  --opponent heuristic_balanced --games 10000 --duplicate

Generated artifacts under runs/ are gitignored. Do not modify or delete runs/archive/.

Static browser policy

The checked-in ONNX policy is small enough for static distribution. To replace it, export a validated checkpoint and rebuild the web app:

uv run --with onnx scripts/export_jax_ppo_onnx.py \
  --checkpoint /path/to/checkpoint \
  --output web/public/models/jax-ppo.onnx
cd web && npm test && npm run build

Commit the ONNX file and its JSON manifest together. The app must continue to use a base-relative model URL so static subpath hosts work.

Documentation

Active plans: docs/plans/.
Retired plans and historical evidence: docs/plans/archive/, docs/archive/, and docs/research/.
Do not edit archival documents; add a new dated note or active plan instead.

When changing docs, run scripts/librarian.sh to validate Markdown links and file:line citations.

Git policy

Do not create git branches unless the user explicitly asks in the current task. Work on the checked-out branch. Before committing, run uv run ruff check . and the relevant tests. Never commit generated run artifacts.

2.9 KiB Raw Blame History