Inspect statically
Read configs, safetensors headers, project files, licenses, and remote-code risks before trusting any model code.
Apple MLX porting runbook
Port PyTorch to MLX. Inspect existing MLX. Prove every speedup.
MLX Porter gives engineers and agents a concrete path from PyTorch modules, checkpoints, and local MLX code to verified Apple Silicon implementations.
Paste PyTorch or point at MLX
Start from a module, checkpoint, model folder, or already-running local port.
Get a runnable plan
Architecture route, inspection report, parity gates, and common fixes in one path.
Ship measured MLX wins
Apple Silicon optimizations only after source parity and benchmark receipts.
A runbook for the messy middle.
MLX Porter turns model archaeology, checkpoint mapping, parity debugging, and Apple Silicon tuning into an ordered workflow an agent can execute without inventing the plan from scratch.
Pick the family
Route the work to the right playbook: decoder, ASR, diffusion, audio, VLM, SSM, MoE, graph, CV, or a new gap.
Build the oracle
Freeze source behavior, capture intermediate tensors, and make correctness debuggable before the MLX rewrite begins.
Port eager MLX
Start with the smallest readable MLX graph. Keep compile, kernels, quantization, and batching out until parity holds.
Validate and optimize
Account for every weight, pass parity, profile the real bottleneck, then change one optimization dimension at a time.
Already have MLX running? Turn it into an inspection report.
Point the skill at a local port, served app, notebook, or converted checkpoint. It maps what is already there, what is still unproven, and what is worth improving next.
What is running
Find MLX packages, module surfaces, eval boundaries, compile regions, fast attention, caches, quantization, custom kernels, and risk flags.
What can improve
Name the missing proof first: source oracle, parity evidence, benchmark metadata, cache policy, quantization path, or intake blocker.
What can be contributed
Promote novel local patterns only when they come with fixtures, parity checks, benchmark receipts, rollback notes, and an affected runbook.
Inspector command
Run this against a local project. Add --model when the checkpoint should be inspected 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
Strong enough for frontier agents. Simple enough for small ones.
A large cloud model may discover these moves on the fly. MLX Porter packages them into a step-by-step runbook that smaller open models and local agents can follow reliably.
Load one compact contract
mlx-model-porting/SKILL.md stays small and routes 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 where agents can read them.
Fail loud, not clever
Unsupported formats, missing keys, unreviewed remote code, and parity drift are blockers, not excuses to improvise.
CLI first. The site is just the doorway.
MLX Porter lives in the repo: a skill contract, reference runbooks, structured assets, and scripts that generate 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 vibes.
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 claiming an optimization.
Typical command path
Use the generated artifacts as handoff packets for an agent or as a checklist for a human 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 engineers actually have.
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, KV cache, and fast SDPA once tensor parity is clean.
Checkpoint loading
Static safetensors intake, deterministic transforms, and no silent missing keys.
Whisper-style ASR
Waveform, log-mel, encoder states, token IDs, WER/CER, and timestamp checks.
Diffusion blocks
One denoiser timestep, scheduler math, and a fixed-seed latent trajectory.
Docs that point back to executable proof.
Humans can skim the path; agents can run it. Start with the skill contract, then follow the family runbook, inspector, and validation scripts.
Offline smoke path
Test the routing, planning, recommendation, 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 bring back proof.
Source provenance, project inspection, eager MLX, parity, profiling, and measured Apple Silicon optimization in one repeatable path.