MaatML

MaatML is where a small, task-specific model is built, weighed, and packaged, across text, vision, and vision-language. One declarative model.yml drives prepare → train → evaluate → export → serve. The runtime is where the model answers.

What makes it different: correctness is checked outside the model by validators. The same validator gates your synthetic data and your evaluation, and can guard your live inference: maatml serve runs it per request on /predict?validate=1, and on every response under --enforce, where a failing output is rejected with HTTP 422. So a MaatML model ships with a contract, not just weights. That validator-gated data → eval → serving loop, now across modalities, is what general fine-tuning tools leave out.

Install a released package from PyPI:

pip install maatml
pip install "maatml[ml]"       # training stack
pip install "maatml[ml,vision]"  # + torchvision and ONNX (vision / VLM examples)

• Site: maatml.pages.dev
• PyPI: pypi.org/project/maatml
• Source: github.com/Moralfish-Labs/maatml

Documentation

• Get started: install, smoke-test, train and serve a model
• The validator-gated lifecycle: the core idea, end to end
• The data flywheel: generation, distillation, ingestion and reviewed captures
• CLI reference and model.yml reference
• Troubleshooting: installation, data, gates and recovery
• Contributing: development and documentation checks
• Evidence: derived floors, the ship decision, operating points, named populations, licences, portable runs
• Orchestration and recovery: CLI ownership, remote workers, checkpoint continuation and portable evidence
• Rollouts: environment verification and DAgger collection
• Serving & deployment: maatml serve, ONNX/edge, and vLLM (VLMs)
• Plugin author guide: register trainers, validators, metrics, exporters, generators
• Examples: four reference models, from support-ticket triage to a vLLM-servable VLM

Canonical references in the repo:

• README.md: install, CLI overview, examples
• ROADMAP.md: tranche status
• CHANGELOG.md: release notes

Quick CLI map

Command	Purpose
maatml prepare	Build train/val/test splits
maatml train	Fine-tune (LoRA / QLoRA / full / DPO / ORPO / vision / VLM)
maatml evaluate	Validator + metrics + eval gates (--gate fails CI; --cache, --blind)
maatml gates derive / ship-check / operating-point derive	Floors from reports, the release verdict, the val-derived threshold (evidence)
maatml runs / report	The run registry (--pack / --adopt to move a run); the evidence document from the records alone
maatml export	Bundle checkpoint (safetensors / gguf / mlx / onnx) + manifest.json
maatml compile / manifest amend	Target compilation and checksummed additions to an export
maatml verify	Recompute sha256 of manifest files
maatml serve	JSON inference API, validator inline (/predict?validate=1)
maatml datagen / distill / ingest / mint	Validator-gated data flywheel
maatml run / plan	Fixed lifecycle and freshness planning
maatml rollout	Environment-verified episodes and optional teacher labels

See the Plugin author guide for registering generators, exporters, validators, and metrics.

Release boundary

These docs describe 0.14.0, including rollouts, train-only rows, tool-call chat training and corrected multi-turn masking. Upgrade older installations to use these features. The repository changelog distinguishes shipped releases from future Unreleased work. Model recipes and task plugins remain independent of the framework, while external orchestrators manage compute, storage and monitoring.