Inspect statically
Read configs, safetensors headers, project files, licenses, and remote-code risks before any model code gets a chance to lie.
A runbook from the part that usually breaks.
Most failed MLX ports do not fail loudly. A mask is flipped, a RoPE offset drifts, a checkpoint loads but the logits are wrong. This keeps the work boring enough to debug.
Pick the family
Pick the closest route from evidence: decoder, ASR, diffusion, audio, VLM, SSM, MoE, graph, CV, or a real gap.
Build the oracle
Freeze source behavior and capture intermediate tensors before the MLX rewrite has anywhere to hide drift.
Port eager MLX
Start with the smallest readable MLX graph. No compile, kernels, quantization, or batching until parity holds.
Validate and optimize
Account for every weight, pass parity, profile the bottleneck, then change one thing and keep the rollback path.
Already have MLX running? Make it show its receipts.
Point the skill at a local port, served app, notebook, or converted checkpoint. It separates code that merely runs from code that has source parity, quality checks, and benchmark metadata.
What is running
Find MLX packages, module surfaces, eval boundaries, compile regions, fast attention, caches, quantization, kernels, and risk flags.
What can improve
Name the missing proof before recommending work: source oracle, parity evidence, benchmark metadata, cache policy, or intake blocker.
What can be contributed
Promote local tricks only when they come with fixtures, parity checks, benchmark receipts, rollback notes, and the runbook they change.
Inspector command
Run this against a local project. Add --model when the checkpoint needs to be judged in the same report.
python3 mlx-model-porting/scripts/inspect_mlx_project.py /path/to/mlx-project \ --model /path/to/local-model \ --markdown MLX_INSPECTION.md \ --output inspection.json
Enough detail for big agents. Enough rails for small ones.
A frontier model can rediscover many of these checks at runtime. This distills them into a runbook that local and open models can follow without inventing the debugging strategy.
Load one compact contract
mlx-model-porting/SKILL.md stays small and sends the agent to the exact reference files and scripts for the current model.
Use structured assets
Architecture families, technique states, evidence depth, and benchmark receipts live in structured files agents can actually read.
Fail loud, not clever
Unsupported formats, missing keys, unreviewed remote code, and parity drift are blockers, not invitations to be clever.
CLI first. The page is only the map.
The useful parts live in the repo: the skill contract, runbooks, structured assets, and scripts that produce inspection reports, port plans, parity checks, and benchmark receipts.
Inspect
Point at a model folder or local MLX project and get JSON/Markdown evidence instead of a hunch.
Plan
Turn model metadata into a family route, runbook, weight-map requirements, and parity ladder.
Verify
Run source validation, tensor comparison, and benchmark commands before calling anything faster.
Typical command path
Use the generated artifacts as handoff packets for an agent or as the checklist I would want beside a real port.
S=mlx-model-porting/scripts python3 $S/inspect_model.py \ /path/to/model \ --output inspection.json python3 $S/make_port_plan.py \ inspection.json \ --output PORT_PLAN.md python3 $S/recommend_optimizations.py \ inspection.json \ --markdown OPTIMIZATIONS.md python3 $S/inspect_mlx_project.py \ /path/to/mlx-project \ --markdown MLX_INSPECTION.md
Start from what is actually on disk.
A pasted module, a checkpoint, an ASR block, or a diffusion component should not get generic advice. Each start maps to an oracle, weight map, parity ladder, and optimization gate.
Transformer attention
QKV maps, RoPE, masks, cache parity, then fast SDPA.
Checkpoint loading
Static safetensors intake, explicit transforms, no silent gaps.
Whisper-style ASR
Waveform, log-mel, encoder states, tokens, WER/CER, timestamps.
Diffusion blocks
One denoiser step, scheduler math, fixed-seed latent trajectory.
Docs that keep pointing back to proof.
Humans can skim the path; agents can run it. Start with the compact contract, then follow the family runbook, inspector, and validation scripts.
Offline smoke path
Test routing, planning, recommendations, source validation, and golden scenarios 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 the model. Make it come back with evidence.
Source provenance, eager MLX, parity, profiling, and measured Apple Silicon optimization in one repeatable path.