File size: 7,048 Bytes

---
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).