99 lines
2.9 KiB
Markdown
99 lines
2.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd web
|
|
npm test
|
|
npm run build
|
|
```
|
|
|
|
## JAX PPO workflow
|
|
|
|
CPU smoke runs write disposable artifacts under `runs/tmp/`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|