PyTorch module
Freeze source behavior as an oracle, inventory parameter names and shapes, then build the smallest readable MLX graph.
Executable standard · v0.4.0
Port models to MLX with proof at every step.
Start with a PyTorch module, model directory, checkpoint, or existing MLX project. Leave with an architecture route, deterministic weight map, parity ladder, benchmark receipts, and an honest publication boundary.
PORT / VALIDATE / PROFILE
APPLE SILICONRECEIPT 01
17architecture families with golden routing scenarios
350catalogued live evidence sources with recorded review depth
65techniques separated by support status
0promotion-ready local speed claims after every gate
Start from the artifact
One intake contract. Four honest entry points.
The tool reads metadata and safe tensor headers first. It does not import repository code, execute remote model code, or pretend an unfamiliar architecture is a decoder-only Transformer.
Model directory
Inspect configs, tokenizer assets, safetensors headers, custom-code risks, provenance, and routing signals without importing the project.
Checkpoint or archive
Recognize safetensors, GGUF, ONNX, Keras, Flax/Orbax, TensorFlow, and Core ML shapes while keeping executable formats quarantined.
Existing MLX project
Inventory evaluation boundaries, runtime and fast-path hints, parity and benchmark signals, plus proof gaps. Static inspection does not validate numerical correctness.
Ambiguity blocks action
Weak identity, truncated inspection, unsafe files, or conflicting routes produce blockers—not a confident recommendation assembled from substrings.
Portable proof receipts
Local inspection emits portable relative paths, a complete artifact-tree fingerprint, and identity-bound license evidence by default. Promotion receipts bind exact experiments and controlled quality artifacts; rejected evidence stays visible.
The porting rail
Readable first. Fast only after parity.
Every phase creates evidence for the next. Optimization does not get to rewrite the history of a port that never matched its source.
Inspect
Inventory metadata, formats, lineage, custom-code risk, tensors, and architecture signals.
Route
Select a controlled family, traits, capabilities, workloads, and the matching runbook.
Oracle
Capture deterministic source intermediates, masks, caches, state, and task outputs.
Eager MLX
Implement the plain graph with explicit shapes, axes, state updates, and evaluation points.
Map weights
Record every rename, transpose, split, merge, reshape, dtype decision, and unmapped tensor.
Prove parity
Compare embeddings, blocks, logits or outputs, state transitions, and task behavior in stages.
Profile + optimize
Change one bottleneck at a time; keep experimental or lossy paths behind explicit consent.
Benchmark + publish
Bind workload, runner, quality, baseline, raw output, rollback, and model lineage into receipts.
python3 mlx-model-porting/scripts/inspect_model.py /path/to/model \
--output inspection.json \
--markdown inspection.md
Architecture-specific routes
Different graphs deserve different runbooks.
The registry covers dense and MoE Transformers, vision-language and audio-language systems, diffusion and flow, speech stacks, state-space hybrids, time series, graph models, codecs, vocoders, and CV backbones. Coverage means the routing and guard behavior is tested; it does not mean every checkpoint has been ported end to end.
The complete family list is available in the repository’s architecture registry. Interactive route cards require the local generated data file.
Evidence before adjectives
A number is not a claim until its lineage survives recomputation.
The catalog separates source-reported potential, historical observations, promotion-ready local measurements, and rejected configurations. Missing evidence is never inferred.
Current local benchmark status
11 receipts are retained: 10 performance observations, 1 rejected configuration, and 0 promotion-ready local speed claims.
The effective catalog withholds 9 of 9 numeric records. No source-reported range is currently profile-eligible.
Implementation-backed routeAn official API, Apple project, pinned third-party implementation, or release note supports a technical path—without turning it into a local performance promise.
Research candidateA primary paper can support considering an algorithm or architecture. It still needs an MLX implementation, source oracle, and parity before recommendation.
Source-reported observationA source number can justify a local experiment, never a portable recommendation. It stays held until an equivalent local run passes promotion.
ObservationA real historical measurement is preserved, but legacy schema, incomplete quality, incompatible baselines, or unstable metrics block promotion.
Promotion-readyAggregates, pinned lineage, runner semantics, workload, raw output, declarative quality, stability, rollback, baseline, and noise margin all pass.
Rejected / incompleteRegressions and invalid stacks remain visible as negative evidence. They cannot silently reappear as “measured together.”
Reliability boundary
What the offline suite proves—and what it does not.
- Golden scenarios prove routing, source-key coverage, seeded parity-bug detection, and recommendation policy—not real checkpoint support for every family. Broader tooling tests validate weight-map behavior.
- Static format inspection does not convert ONNX, GGUF, Flax/Orbax, TensorFlow/Keras, or Core ML graphs into executable MLX.
- Source-reported speed ranges are not portable guarantees across chips, versions, shapes, concurrency, precision, or quality constraints.
- Apple Silicon execution, external research agents, live links, and upstream pin drift remain separate hardware, live-execution, and network validation surfaces.
Use it, inspect it, improve it
Install one skill. Keep every judgment reviewable.
Client presets cover Claude Code, Codex, Cursor, Gemini CLI, Windsurf, and GitHub Copilot. The installer is atomic and idempotent; explicit destinations remain available when a client changes discovery conventions.
python3 mlx-model-porting/scripts/install_skill.py \
--client codex