f_torch(x; W_src)
pin graph, inputs, state
Porting system · executable standard · v0.6.0
Port the model. Prove the result.
Take a PyTorch or CUDA model from source inspection to a readable MLX graph, explicit weight mapping, staged parity, measured optimization, and a reviewable proof packet.
Need a fundamentals refresh? Use the LearnMLX module. Ready to work? Inspect the repository.
W_MLX = P(W_src)
map axes + rebuild runtime
Δ = ||y_src − y_MLX||
stop at first divergence
arg max phase_time
change one measured bottleneck
parity gate
unlock only when Δ ≤ ε
optimize → re-run proof
17architecture families with golden routing scenarios
356catalogued live evidence sources with recorded review depth
66techniques separated by support status
0promotion-ready local speed claims without an external trust root
Learn the system
See the whole port before you touch code.
Choose a representative model and trace the same proof rail through a different graph. The architecture branch changes. The rule does not: optimization stays locked until parity and a measured bottleneck exist.
Proven guided lab
Qwen2.5 dense decoder
Tokens → embedding → RoPE/RMSNorm/GQA blocks → KV state → logits
- 01InspectPin the exact dense-decoder checkpoint.
- 02Capture oracleFreeze IDs, blocks, state, and outputs.
- 03RebuildTranslate the readable eager MLX graph.
- 04Map weightsDeclare every transform and source key.
- 05Prove parityPass the ordered source-to-MLX ladder.
- 06ProfileSeparate load, prefill, and cached decode.
- 07OptimizeGated by parity · attention, cache, compile, or decode.
- 08PublishKeep the proof bound to this checkpoint.
Runbook simulation
Whisper-style ASR
Waveform → mel frontend → encoder → cross-attention decoder → transcript
- 01InspectSeparate speech modality from encoder-decoder architecture.
- 02Capture oracleFreeze waveform, mel, encoder, decoder, and timestamps.
- 03RebuildMake frontend and cache lifetimes explicit.
- 04Map weightsKeep encoder, cross-attention, and decoder transforms visible.
- 05Prove parityCheck features, state, logits, transcript, and timestamps.
- 06ProfileSeparate frontend, encoder, and autoregressive decode.
- 07OptimizeGated by parity · attention, compile, or evaluation boundaries.
- 08PublishKeep simulation status until task quality is reproduced.
Runbook simulation
FLUX-style diffusion/flow
Prompt encoder → latent + schedule → repeated flow step → VAE → image
- 01InspectInventory every pipeline component and scheduler.
- 02Capture oracleFreeze conditioning, latents, schedule, and decode.
- 03RebuildProve one readable flow or denoiser step.
- 04Map weightsAudit encoder, denoiser, and VAE separately.
- 05Prove parityCompare fixed-seed latent checkpoints and output quality.
- 06ProfileSeparate repeated steps, scheduler, and VAE work.
- 07OptimizeGated by parity · compile, eval, streaming, or spatial kernel.
- 08PublishSay FLUX-style until an exact port is proven.
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.
PyTorch module
Freeze source behavior as an oracle, inventory parameter names and shapes, then build the smallest readable MLX graph.
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. Dense decoders are the only generated architecture path and are proven by one real Qwen port. The other 16 families have tested routing and guards, not generated modules or completed checkpoint support.
The complete family list is available in the repository’s architecture registry. Interactive route cards require the local generated data file.
LearnMLX · optional depth module
Refresh the fundamentals when the port demands it.
The complete porting system works as a field manual. LearnMLX is the deeper companion for anyone who wants to revisit the execution model underneath it: lazy arrays, unified memory, modules, transforms, streams, and compilation.
NumPy-like, built for Apple silicon
mx.array, mlx.nn, and composable transforms give the port a readable native foundation.
Official Quick Start ↗One memory pool, explicit operations
Unified memory removes the usual tensor-transfer choreography, but framework bridges may still copy or force evaluation.
Learn unified memory ↗Build lazily, evaluate deliberately
Place mx.eval at dependency, comparison, and measurement boundaries—not after every operation.
Learn lazy evaluation ↗Compile the stable hot region
Prove an eager path first. Then compile pure, repeatedly used regions while keeping mutable state visible.
Learn compilation ↗
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
13 receipts are retained: 12 performance observations, 1 rejected configuration, and 0 promotion-ready local speed claims.
The effective catalog withholds 10 of 10 numeric records. The Qwen BF16 timing remains reproducibility-on-request evidence; no local or source-reported range is currently effective.
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-readyAll measurement gates pass and a protected Apple-Silicon signer authenticates commit/tree, challenge, dependencies, output, policy, and timing against an external trust root.
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.
- One Qwen2.5 dense-decoder port passed 29 parity rungs and exact greedy-token comparison. Golden scenarios prove routing, source-key coverage, seeded parity-bug detection, and recommendation policy for all families—not real checkpoint support for the other 16.
- 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.
- Exact output is the only controlled built-in task metric. Domain evaluation, other-model Apple Silicon execution, external research agents, live links, and upstream pin drift remain separate 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