--- license: apache-2.0 library_name: mindxtrain pipeline_tag: text-generation tags: - mindx - mindxtrain - training-framework - lora - cpu-training - proof-of-recall datasets: - PYTHAI/mindXascension - PYTHAI/mindX-docs --- > **mindXtrain for mindX — the Hugging Face fork.** This repository is the **mindX-specific** line of mindXtrain, > forked on 2026-09-14 from the agnostic upstream > [github.com/Professor-Codephreak/mindXtrain](https://github.com/Professor-Codephreak/mindXtrain) at commit > [`661bd41`](https://github.com/Professor-Codephreak/mindXtrain/commit/661bd411738d11e633b25c681bbd5676556bab7d) (provenance in [`FORK.json`](FORK.json)). > **mindXtrain continues here.** The GitHub repository is **archived for posterity** — the read-only record of the > pioneering work of [Professor Codephreak](https://github.com/Professor-Codephreak). All new work lands on the Hub: > > ```bash > git clone https://huggingface.co/PYTHAI/mindXtrain > ``` > > What this line trains for: the mindX lineage ([`PYTHAI/mindXascension`](https://huggingface.co/datasets/PYTHAI/mindXascension)), > built from mindX's doctrine ([`PYTHAI/mindX-docs`](https://huggingface.co/datasets/PYTHAI/mindX-docs), with > [the mapping](https://huggingface.co/datasets/PYTHAI/mindX-docs/blob/main/MAPPING.md)); the last accepted generation is > [`PYTHAI/mindXtrain39`](https://huggingface.co/PYTHAI/mindXtrain39). The Hub footprint is mapped in > [`examples/mindx/HUGGINGFACE_MAP.md`](examples/mindx/HUGGINGFACE_MAP.md). The upstream README follows unchanged. # mindxtrain Production training framework for fine-tuning open-weight LLMs on AMD MI300X and serving them through an OpenAI-compatible API. Single ordered package, canonical layout per [`docs/blueprints/mindXtrain2.md`](docs/blueprints/mindXtrain2.md) §Part 4. The single architectural feature that distinguishes mindxtrain from Axolotl, LLaMA-Factory, Unsloth, torchtune and Primus is its **60-second AOT autotune probe**: CK-vs-Triton attention, hipBLASLt heuristic, RCCL config — the plan is fixed at training start, JIT autotune is forbidden in the production loop. **Status**: production deployment in progress. The CPU-only base install passes its full pytest suite (ruff + mypy clean); with the training extras installed the suite is 672 green. Many modules ship as real Python on a CPU-only laptop; heavyweight training, eval, and quantization paths gate on opt-in extra dep groups. See [`docs/actualization_status.md`](docs/actualization_status.md) for the per-module map and [`HANDOFF.md`](docs/HANDOFF.md) for the operator checklist. ## Where this runs - **Operator + Coach UI:** [https://mindx.pythai.net/coach](https://mindx.pythai.net/coach) - **Public training-jobs API:** `https://mindx.pythai.net/v1/training/jobs` (bearer auth via `MINDXTRAIN_API_KEY`) - **mindX self-training loop:** mindX's dream cycle writes JSONL training data; this framework consumes it via the `mindx_dreams` data source and fine-tunes a small fallback model on a single MI300X. ## Prove it trains mindXtrain doesn't just assert that training works — it proves recall. The [**dcoach**](docs/dcoach.md) proof loop (`/coach/dcoach`) imprints a persona onto a tiny model on CPU, then measures whether the model *recalls* it: the **classroom** scores recall before vs after training, the **boardroom** rules success or failure, and the verdict feeds an **autotune feedback loop** that tunes the next run. A clean CPU run reports a positive imprint Δ (e.g. recall 0.07 → 0.28) and an approved verdict. [`docs/NAV.md`](docs/NAV.md) is the full documentation hub. ## Quickstart ```bash uv sync # base install uv run pytest -q # → 564 passed uv run mindxtrain --help # 9 verbs uv run mindxtrain init --template qwen3_8b_sft_lora --out run.yaml uv run mindxtrain bench --dry-run --out plan.json uv run uvicorn mindxtrain.operator.app:app --host 0.0.0.0 --port 8080 # open http://localhost:8080/coach/ for the interactive UI ``` To unlock training / eval / quantize / publish, install the matching dep group: ```bash uv sync --extra ml --extra eval --extra data # train + eval + curate # or uv sync --all-extras # everything except amd-quark ``` GPU steps (`bench` without `--dry-run`, `train`, `quantize`, `serve`) require an AMD MI300X with ROCm 7.2.1; run inside `rocm/primus:v26.2`. The full operator checklist lives in [`HANDOFF.md`](docs/HANDOFF.md). ## Layout ``` mindxtrain/{cli,config,data,models,train,eval,autotune, operator,storage,provenance,deploy,budget}/ # 99 modules contracts/ Foundry workspace for ERC-8004 attestation registry ops/ containerfiles, compose, k8s, vmm, gensyn tests/ pytest suite — 566 tests, CPU-only smoke examples/ demo YAML configs docs/ user-facing documentation + frozen blueprints scripts/ dev helpers ``` ## Documentation | Doc | What it covers | |-----|----------------| | [`HANDOFF.md`](docs/HANDOFF.md) | **Operator checklist** — ordered steps from local setup to live deployment. | | [`docs/quickstart.md`](docs/quickstart.md) | Install + base-vs-extras command tour. | | [`docs/architecture.md`](docs/architecture.md) | Canonical layout + 5-layer architecture + MI300X invariants. | | [`docs/actualization_status.md`](docs/actualization_status.md) | Per-module map of what's real vs. requires extras. | | [`docs/autotune.md`](docs/autotune.md) | The 60-second AOT probe — the architectural differentiator. | | [`docs/coach.md`](docs/coach.md) | Interactive `/coach/` web UI bundled in the operator. | | [`docs/dcoach.md`](docs/dcoach.md) | The dcoach proof loop — prove a CPU model recalls its training; decentralized-training fit. | | [`docs/cli.md`](docs/cli.md) | Every `mindxtrain` verb with synopsis, options, exit codes. | | [`docs/yaml_schema.md`](docs/yaml_schema.md) | Every field of the 10-section `XTrainConfig`. | | [`docs/benchmarks.md`](docs/benchmarks.md) | Target metrics + the 7-cell framework comparison. | | [`docs/development.md`](docs/development.md) | Toolchain, optional-deps, lazy-import pattern, invariants. | | [`docs/blueprints/`](docs/blueprints/) | Source design briefs (frozen specification). | | [`llm.txt`](llm.txt) | Orientation for another model — what is measured, what is not, the traps. | | [`examples/mindx/`](examples/mindx/HUGGINGFACE_MAP.md) | Example consumer — mindX on the Hugging Face Hub: its lineage, [docs dataset + mapping](https://huggingface.co/datasets/PYTHAI/mindX-docs/blob/main/MAPPING.md), Spaces and licence-pinned base models. The framework stays agnostic. | ## License Apache-2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE), and the upstream-license notices in [`LICENSE-MIT-upstream-glm51`](LICENSE-MIT-upstream-glm51) and [`LICENSE-NOTICE.md`](docs/LICENSE-NOTICE.md). Version history in [`CHANGELOG.md`](docs/CHANGELOG.md).