LoRA and fuse

LoRA trains an adapter on a cached base model; fuse merges the adapter back into standalone weights.

Cache discovery honors HF_HUB_CACHE, then the legacy HUGGINGFACE_HUB_CACHE, then HF_HOME/hub, then XDG_CACHE_HOME/huggingface/hub. With none set, it uses ~/.cache/huggingface/hub. An explicit --hf-cache takes precedence. Training never downloads a missing base.

Train

Inspect prerequisites independently before preparing a training plan:

python3 scripts/mlx-agent lora inspect --repo <repo> --data ./my-dataset --batch-size 4 --json

The read-only report checks training executable availability, cached base architecture and both dataset splits. Each split records an example count and SHA-256 when valid, or a classified error and remediation. Missing optional --repo or --data inputs appear as blockers. Blockers are report data, so a successful inspection exits zero even when ready is false. Invalid command arguments still fail. Inspection loads no model, downloads nothing and creates no plan, output or receipt. It does not measure memory fit or authorize training; preview and confirmation recheck the inputs.

python3 scripts/mlx-agent lora start --repo <repo> --data ./my-dataset --iters 1000
python3 scripts/mlx-agent lora start --repo <repo> --data ./my-dataset --iters 1000 --confirm --preview-hash <hash>
python3 scripts/mlx-agent lora status

The dataset is validated before the preview even renders: both <dir>/train.jsonl and <dir>/valid.jsonl are required. Each line is a JSON object with a text string or a messages array of {role, content}. Each split must contain at least --batch-size examples (default 4); choose a smaller batch explicitly for smaller splits. Training and validation examples are supplied separately and are never generated by the planner. Bounded hyperparameters: --iters (1–100000), --batch-size (1–64), --learning-rate (1e-6–1e-2), --num-layers (-1–128).

For a cached base, preview reads config.json and checks its model_type against the MLX-LM model registry. Installed package sources take precedence over the bundled registry; no model weights or repository runtime code are loaded for this check. Unsupported architectures, malformed configs and standalone speculative drafters are refused before a job starts. The captured base identity records the model type, declared loader and registry source. This architecture check does not establish successful training or output quality.

--hf-cache /absolute/cache/path selects the same cache for base identity and the local-model gate. Keep this option identical between preview and confirmation.

Fuse

python3 scripts/mlx-agent fuse start --repo <repo> --adapter ./adapter
python3 scripts/mlx-agent fuse start --repo <repo> --adapter ./adapter --confirm --preview-hash <hash>
python3 scripts/mlx-agent fuse status

Fuse validates the adapter (adapter_config.json present and parseable) and renders the exact mlx_lm.fuse argv under the same gates: cached base, installed runtime, fresh output path, one job at a time.

Serve the result

Evaluation suites and reviews

The Lab workspace operations training-preview and training-evaluate accept either the legacy prompt and optional max_tokens, or a prompt_suite object with id, name, and prompts. Each prompt contains id, text, and max_tokens. Suites contain 1–16 uniquely identified text prompts, each limited to 8,000 characters and 1–512 output tokens. Mixing the two request forms is refused. Preview binds prompt order and settings to the training receipt and base/adapter identities before confirmation.

Each variant loads once and generates every prompt with temperature zero and seed 42 reset per prompt. A version-2 report retains all paired samples. Partial results or changed inputs are refused. Legacy version-1 reports keep their single-prompt format. New history rows record suite names and prompt counts.

training-review accepts evaluation_id, the retained artifact_sha256, prompt_id, a preference (baseline, adapter, tie, or neither), and optional notes up to 2,000 characters. Preferences are appended as separate records under the workspace reviewer identity; they never rewrite generation reports. Inspection returns the latest recorded preference per prompt alongside the verified report. Reviews do not establish model quality or training success.

python3 scripts/mlx-agent serve start --repo <repo> --runtime mlx_lm --adapter-path ./adapter

Train on a quantized base, fuse to keep the quant, serve either the adapter or the fused model.

The serve command above is a preview; review it and confirm with its hash to launch. Both training and fusion require local inputs, an installed runtime, and a fresh output path. Keep every argument identical between preview and confirmation. Inspect job status and logs before using outputs; starting a job does not establish successful training or fusion. These model jobs are not configuration rollback transactions. Training retains actual exit results, verified adapter content identity, and pinned base/dataset inputs. A completed adapter can produce a linked base-versus-adapter evaluation with matching prompt and sampling settings. See Experiments and training for retained evaluations and the separate video-training qualification gates.