Inspect statically
Read configs, safetensors headers, source files, licenses, and remote-code risks before executing model code.
Apple MLX runbook for agents
Port PyTorch projects to MLX without runtime guesswork.
A doc-friendly landing page for the MLX Porter skill: inspect the source, prove parity, then apply Apple Silicon optimizations with receipts.
agent:
SKILL.md -> oracle -> eager MLX -> parity -> optimize
no silent speed claims
The runbook is the product.
MLX Porter turns scattered MLX, Metal, checkpoint, parity, and benchmark knowledge into a sequence an agent can execute without improvising a new conversion strategy every time.
Pick the family
Route to dense decoder, ASR, diffusion, audio codec, VLM, SSM, MoE, graph, CV, or another runbook.
Build the oracle
Freeze deterministic source fixtures and capture the right intermediate tensors before porting.
Port eager MLX
Implement the smallest readable MLX graph first. Keep compile, kernels, quantization, and batching out.
Validate and optimize
Account for weights, pass parity, profile real bottlenecks, then change one optimization dimension at a time.
Built for frontier agents and tiny local models.
A GPT-5.6-class system can discover many of these paths dynamically. The point here is to distill that work so a smaller open model can follow the same checklist with fewer wrong turns.
Load one compact contract
`mlx-model-porting/SKILL.md` stays small and routes the agent to the exact reference files and scripts needed for the current model.
Use structured assets
Architecture families, technique states, evidence depth, and benchmark receipts live in machine-readable files.
Fail loud, not clever
Unsupported source formats, missing keys, unreviewed remote code, and parity drift are blockers, not prompts to hand-wave.
MLX-specific color system.
The palette is named after the things the runbook actually cares about: tensors, kernels, unified memory, parity, checkpoints, and metal surfaces.
Tensor Lime#B7F34F
Kernel Cyan#21D6C7
Memory Blue#5B8CFF
Parity Coral#FF7A66
Metal Violet#A78BFA
Checkpoint Gold#F1B84B
Common starts become exact routes.
Instead of a generic "convert this" answer, each entry point maps to a concrete oracle, weight map, parity ladder, and optimization gate.
Transformer attention
QKV maps, RoPE, masks, KV cache, and fast SDPA only after parity.
Checkpoint loading
Safetensors/static intake, deterministic transforms, and no silent missing keys.
Whisper-style ASR
Waveform, log-mel, encoder states, token IDs, WER/CER, and timestamps.
Diffusion blocks
One denoiser timestep, scheduler math, and fixed-seed latent trajectory.
Docs path for humans and agents.
The repo is designed so a human can skim it and an agent can execute it. Start with the skill contract, then follow the exact family runbook and validation scripts.
Offline smoke path
Exercise routing, planning, recommendation, source validation, and the golden scenario suite without downloading a real model.
python3 mlx-model-porting/scripts/inspect_model.py tests/fixtures/models/decoder --output /tmp/inspection.json python3 mlx-model-porting/scripts/make_port_plan.py /tmp/inspection.json --output /tmp/PORT_PLAN.md python3 mlx-model-porting/scripts/recommend_optimizations.py /tmp/inspection.json --markdown /tmp/OPTIMIZATIONS.md python3 mlx-model-porting/scripts/audit_skill.py --strict mlx-model-porting python3 -m unittest discover -s tests -v
Give an agent a PyTorch module. Make it prove the MLX port.
The runbook keeps the promise sharp: source provenance, eager MLX, parity, profiling, then measured Apple Silicon optimization.