| # AGENTS.md |
|
|
| Canonical entry point for any agent (Claude Code, Codex, Cursor, Copilot, etc.) working in this repository. Read this first. |
|
|
| ## TL;DR |
|
|
| `mindxtrain` is a single-package Python framework that fine-tunes open-weight LLMs on AMD MI300X and serves them OpenAI-compatible. The differentiator is a **60-second AOT autotune probe** (`mindxtrain bench`) — the plan is fixed at training start; **JIT autotune is forbidden in the production loop**. |
|
|
| The base install is CPU-only and runs the CLI, Coach UI, `bench --dry-run`, manifest verify, and the operator FastAPI. Heavyweight paths gate on opt-in `--extra` groups. |
|
|
| ## Where to look |
|
|
| | You want to… | Read | |
| |---|---| |
| | Understand the architecture and invariants | [`CLAUDE.md`](CLAUDE.md), [`docs/architecture.md`](docs/architecture.md) | |
| | Take the repo from "code done" to "demo live" | [`HANDOFF.md`](docs/HANDOFF.md) (11 ordered steps) | |
| | Know what's real Python vs. what needs `--extra <group>` | [`docs/actualization_status.md`](docs/actualization_status.md) | |
| | Add a recipe / training backend / operator backend / training method | [`docs/development.md`](docs/development.md) §"Adding…" | |
| | Look up every CLI verb's options + exit codes | [`docs/cli.md`](docs/cli.md) | |
| | Look up every YAML field | [`docs/yaml_schema.md`](docs/yaml_schema.md) | |
| | Understand the autotune probe | [`docs/autotune.md`](docs/autotune.md) | |
| | Understand the Coach UI | [`docs/coach.md`](docs/coach.md) | |
| | Understand classroom / boardroom / dojo governance | [`docs/governance.md`](docs/governance.md) | |
| | See the frozen design briefs | [`docs/blueprints/`](docs/blueprints/) | |
|
|
| ## Verification gates (must all pass before pushing) |
|
|
| ```bash |
| uv run ruff check . |
| uv run mypy mindxtrain/config mindxtrain/provenance |
| uv run pytest -q # → 564 passed |
| ``` |
|
|
| CI runs the same three commands on Ubuntu 24.04 / Python 3.12 (CPU-only). |
|
|
| ## Non-negotiable invariants |
|
|
| These are encoded in the schema/recipes; violating them is a deployment bug. Full reasoning in [`docs/development.md`](docs/development.md). |
|
|
| 1. **AOT-only** — no `torch.compile(mode="max-autotune")`, no JIT autotune in vLLM. The YAML field `autotune.policy: aot_only` is the contract. |
| 2. **`hardware.gpus: Literal[1, 8]`** — 2/4-GPU MI300X FSDP groups hit asymmetric xGMI; schema rejects them at parse time. |
| 3. **Seven MI300X env vars** are defaults in every recipe's `train.env` (`PYTORCH_ROCM_ARCH=gfx942`, `HSA_NO_SCRATCH_RECLAIM=1`, `HIP_FORCE_DEV_KERNARG=1`, `GPU_MAX_HW_QUEUES=1`, `NVTE_CK_USES_BWD_V3=1`, `NVTE_CK_IS_V3_ATOMIC_FP32=1`, `PRIMUS_TURBO_ATTN_V3_ATOMIC_FP32=1`, `NCCL_MIN_NCHANNELS=112`). |
| 4. **`extra: forbid` + `frozen: true`** on every Pydantic model. |
| 5. **Solidity contracts are write-once** — no proxies, no `Ownable`, no admin keys, no setters. |
| 6. **Numpy pinned `<2.0`** against `torch==2.9.1+rocm7.2.1.lw`. |
| 7. **Lazy imports for optional deps** — `import mindxtrain.eval.harness` must succeed even without `--extra eval`. Error messages must include the exact `uv sync --extra <group>` to run. |
| 8. **Reuse boundaries** — Codephreak persona JSON loads at runtime via `MINDXTRAIN_PERSONA_PATH` from `/home/hacker/mindX/`, not by copying bytes. Never reuse `/home/hacker/aglm/` (broken per its own README). |
| 9. **Clean-room policy** — mindXtrain (and Coach) is a clean-room codebase: functionality from mindX or any external source is **reimplemented/adapted locally from behavior or spec, never copied byte-for-byte**. Consume foreign artifacts (dream corpus, persona) through runtime boundaries; do not vendor foreign code. mindXtrain and Coach **train models** — the dataset/persona/imprint machinery is mindXtrain-native. See [`CLAUDE.md`](CLAUDE.md) §"Clean-room policy". |
|
|
| ## Quick commands |
|
|
| ```bash |
| uv sync # base, CPU-only |
| uv sync --all-extras # everything except amd-quark |
| uv run mindxtrain --help # 9 verbs |
| uv run mindxtrain init --list # 12 built-in YAML recipes |
| uv run mindxtrain bench --dry-run --out plan.json # synthetic plan, no GPU |
| uv run mindxtrain receipt manifest.json --config run.yaml # BLAKE3 round-trip |
| uv run uvicorn mindxtrain.operator.app:app --port 8080 # → /coach/ UI |
| ``` |
|
|
| GPU verbs (`bench` without `--dry-run`, `train`, `quantize`, `serve`) require an AMD MI300X with ROCm 7.2.1 inside `rocm/primus:v26.2`. See [`HANDOFF.md`](docs/HANDOFF.md). |
|
|
| ## Available skills |
|
|
| For Algorand-related work (the provenance/x402/ASA paths) the following skills are available and should be preferred over ad-hoc patterns: |
|
|
| - `algorand-typescript`, `build-smart-contracts`, `test-smart-contracts`, `call-smart-contracts` — contract authoring/testing/deploy. |
| - `use-algokit-utils`, `use-algokit-cli`, `troubleshoot-errors`, `implement-arc-standards` — client-side AlgoKit work. |
| - `search-algorand-examples` — patterns from official Algorand repos. |
| - `algorand-ts-migration` — TEALScript / beta → Algorand TypeScript 1.0. |
| - `mindx` — for cross-cutting work that touches the broader mindX system. |
|
|
| For the Solidity side (`contracts/`): |
|
|
| - `foundry-framework`, `solidity-dev`, `solidity-style-guide`, `slither-analysis`, `echidna-fuzzer`, `gas-optimization`, `hardhat-framework`. |
|
|
| ## When in doubt |
|
|
| - The schema is the source of truth for "what's a valid YAML." Run `uv run python -c "from mindxtrain.config.loader import load_config; load_config('path/to.yaml')"`. |
| - The blueprints under `docs/blueprints/` are frozen — do not edit them; they are the historical specification. |
| - Per-module status: `docs/actualization_status.md`. If a module says "stub" there, do not silently turn it on; it's stubbed deliberately. |
|
|
