onnxruntime-ep-mlx 0.27.6__tar.gz

onnxruntime_ep_mlx-0.27.6/.gitignore

@@ -0,0 +1,80 @@
+# Xcode
+#
+# gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
+
+## User settings
+xcuserdata/
+
+## Obj-C/Swift specific
+*.hmap
+
+## App packaging
+*.ipa
+*.dSYM.zip
+*.dSYM
+
+# CocoaPods
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# Pods/
+#
+# Add this line if you want to avoid checking in source code from the Xcode workspace
+# *.xcworkspace
+
+# Carthage
+#
+# Add this line if you want to avoid checking in source code from Carthage dependencies.
+# Carthage/Checkouts
+
+Carthage/Build/
+
+# fastlane
+#
+# It is recommended to not store the screenshots in the git repo.
+# Instead, use fastlane to re-generate the screenshots whenever they are needed.
+# For more information about the recommended setup visit:
+# https://docs.fastlane.tools/best-practices/source-control/#source-control
+
+fastlane/report.xml
+fastlane/Preview.html
+fastlane/screenshots/**/*.png
+fastlane/test_output
+
+# --- ONNX Runtime MLX EP (Rust) ---
+# Cargo build output (the plugin dylib is rebuilt from source: `cargo build`).
+/rust/target/
+build/
+# Scratch reference material downloaded during development.
+.ref/
+build-mlx/
+.vscode/
+
+# Bundled runtime artifacts dropped into the wheel package by the build hook
+# (python/hatch_build.py). Rebuilt on every wheel build; never committed.
+python/src/onnxruntime_ep_mlx/*.dylib
+python/src/onnxruntime_ep_mlx/*.metallib
+
+# --- Python (op tests, tooling) ---
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+*.egg-info/
+.eggs/
+dist/
+# Virtual environments
+.venv/
+venv/
+env/
+.python-version
+scratch/
+.DS_Store

onnxruntime_ep_mlx-0.27.6/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.5
+Name: onnxruntime-ep-mlx
+Version: 0.27.6
+Summary: MLX-native ONNX Runtime execution provider (plugin EP) for Apple Silicon
+Project-URL: Homepage, https://github.com/justinchuby/onnxruntime-mlx
+Project-URL: Repository, https://github.com/justinchuby/onnxruntime-mlx
+Author: onnxruntime-ep-mlx
+License: MIT
+Keywords: apple-silicon,coreml,execution-provider,metal,mlx,onnxruntime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: onnxruntime>=1.22
+Description-Content-Type: text/markdown
+
+# onnxruntime-mlx
+
+> **PyPI package: [`onnxruntime-ep-mlx`](https://pypi.org/project/onnxruntime-ep-mlx/)** — `pip install onnxruntime-ep-mlx`, `import onnxruntime_ep_mlx`. (Formerly published as `onnxruntime-mlx`, now renamed.)
+
+An **MLX-native execution provider** for ONNX Runtime on Apple Silicon, built as an out-of-tree
+**plugin EP** (ORT plugin-EP C ABI, ORT 1.27 / `ORT_API_VERSION 27`). It ships as a standalone
+`libonnxruntime_mlx_ep.dylib` loaded by a stock prebuilt `libonnxruntime.dylib` via
+`RegisterExecutionProviderLibrary` — **no ONNX Runtime fork required**.
+
+The EP translates fused ONNX subgraphs into [MLX](https://github.com/ml-explore/mlx) graphs for
+encoders, LLM prefill, and token-at-a-time decode.
+
+## How it works
+
+`ONNX fused subgraph → MLX graph → mlx_compile → mlx_eval → ORT outputs`
+
+The EP translates supported ONNX regions into MLX, compiles reusable closures, and leaves unsupported
+ops on ORT CPU. It covers common encoder and decoder operators, including quantized matmul, GQA/MHA,
+PagedAttention, RoPE, normalization, convolution, pooling, reductions, and shape operations. See
+[`docs/OP_ARCHITECTURE.md`](docs/OP_ARCHITECTURE.md) for the coverage table.
+
+Large, fully claimed regions are fastest. Dynamic shapes are compiled per shape key; autoregressive
+decode uses a shapeless path so growing KV length does not retrace. Use
+`ONNXRUNTIME_EP_MLX_VERBOSE=1` or `ONNXRUNTIME_EP_MLX_CLAIM_DEBUG=1` to diagnose fallback and
+fragmentation.
+
+## Requirements
+
+- macOS on Apple Silicon, ORT 1.27 prebuilt (`ORT_API_VERSION >= 27`)
+- **`mlx-c` (and `mlx`) — a HARD build dependency**: `brew install mlx-c`
+- A **Rust toolchain** (`rustup`) to build the EP from source
+
+## Versioning (ORT compatibility)
+
+A plugin EP targets one ORT C-ABI version. Package versions use
+`0.<ORT_API_VERSION>.<patch>`:
+
+| onnxruntime-ep-mlx | ONNX Runtime | `ORT_API_VERSION` |
+|---|---|---|
+| `0.27.x` | 1.27.x | 27 |
+
+For example, ORT 1.28 moves the EP to `0.28.x`.
+
+## Build
+
+The EP is a Rust `cdylib` crate under [`rust/`](rust/). Point it at an ONNX Runtime C-API
+include directory and `cargo build`:
+
+```sh
+brew install mlx-c                                  # HARD dependency (mlx-c + mlx)
+cd rust
+# Either point ORT_INCLUDE_DIR at the ORT headers directly, or set ORT_HOME to an
+# ONNX Runtime release root (build.rs will look in $ORT_HOME/include):
+export ORT_INCLUDE_DIR=/path/to/onnxruntime/include   # or: export ORT_HOME=/path/to/onnxruntime-osx-arm64-1.27.0
+cargo build --release
+# => rust/target/release/libonnxruntime_mlx_ep.dylib  (registers the EP as "MLXExecutionProvider")
+```
+
+Set `MLX_PREFIX` and `MLXC_PREFIX` to link and bundle a custom MLX runtime
+instead of the Homebrew installation. Each prefix must contain `include/` and
+`lib/`; the wheel builder also bundles `mlx.metallib` and an optional
+`libjaccl.dylib` from `MLX_PREFIX/lib`.
+
+The crate binds the ORT plugin-EP C ABI and `mlx-c` directly via `bindgen`; it does **not** link
+`libonnxruntime` (ORT is reached through the `OrtApi` function-pointer table passed to
+`CreateEpFactories`).
+
+## Install & use
+
+### Python (recommended)
+
+```sh
+pip install -U onnxruntime-ep-mlx        # macOS/Apple-Silicon wheel; bundles the mlx runtime
+```
+
+```python
+import onnxruntime as ort
+import onnxruntime_ep_mlx
+
+# Register the plugin EP once, then select it (with CPU fallback) like any provider.
+onnxruntime_ep_mlx.register_execution_provider_library()          # name: "MLXExecutionProvider"
+sess = ort.InferenceSession(
+    "model.onnx",
+    providers=["MLXExecutionProvider", "CPUExecutionProvider"],
+)
+out = sess.run(None, feeds)
+```
+
+`onnxruntime_ep_mlx` also exposes `library_path()`, `ep_name()`, `version()`, and
+`append_to_session_options(so)`.
+
+### C / C++ (or any onnxruntime binding)
+
+Point onnxruntime at the built dylib and select the provider by name:
+
+```c
+// 1. Register the plugin library with the environment (once).
+RegisterExecutionProviderLibrary(env, "MLXExecutionProvider",
+                                 "/abs/path/libonnxruntime_mlx_ep.dylib");
+// 2. Append it to a session's options (falls back to CPU for unclaimed ops).
+const char* ep = "MLXExecutionProvider";
+SessionOptionsAppendExecutionProvider_V2(options, env, &ep, /*count*/ 1, ...);
+```
+
+From Rust via **onnx-genai**: `ONNX_GENAI_EP=metal` +
+`ONNX_GENAI_METAL_EP_LIB=/abs/path/libonnxruntime_mlx_ep.dylib`.
+
+## Large-decoder partition metadata
+
+The EP automatically infers residual layer boundaries from graph topology for decoders of about 24
+layers or larger. Exporters can make the boundaries explicit with the
+ONNX custom metadata key `onnxruntime_ep_mlx.layer_boundary_outputs`. Its value is a JSON array of
+residual output tensor names, one per transformer layer:
+
+```python
+import json
+import onnx
+
+model = onnx.load("decoder/model.onnx", load_external_data=False)
+entry = model.metadata_props.add()
+entry.key = "onnxruntime_ep_mlx.layer_boundary_outputs"
+entry.value = json.dumps(["layer.0.output", "layer.1.output", "layer.2.output"])
+onnx.save(model, "decoder/model.onnx")
+```
+
+Metadata takes precedence over inference and does not rely on node names. The EP chooses a dynamic
+group size of 4-8 layers, targeting about seven partitions. Override it with
+`ONNXRUNTIME_EP_MLX_LAYER_PARTITIONS=<layers>`; use `0` or `off` to disable partitioning.
+
+## Performance (M1 Max, warm)
+
+Real end-to-end models, median of 10 runs, MLX EP vs the ORT **CPU** EP on the same machine — top-1
+identical and max abs diff ≤ 6e-5 in every case:
+
+| Model | Workload | CPU EP | MLX EP | Speedup |
+|---|---|---:|---:|---:|
+| Perch v2 | audio encoder (with DFT front-end) | 64.0 ms | 12.0 ms | **5.3×** |
+| Perch v2 (no DFT) | audio encoder | 56.5 ms | 12.0 ms | **4.7×** |
+| BirdNET | audio classifier (CNN) | 14.9 ms | 7.3 ms | **2.0×** |
+| gemma-4-E2B | vision encoder (fp16 ViT) | 267 ms | 47 ms | **5.7×** |
+
+Feed-forward encoders (audio / CNN / vision) are the EP's sweet spot: the whole graph fuses into a
+single MLX closure that is traced + `mlx_compile`d once and replayed, so a static-shape model runs
+end-to-end on the GPU with one dispatch (e.g. Perch: 725/725 nodes claimed, 1 fused subgraph).
+
+Eligible BF16 INT4/INT8 prefill matmuls (block size 32/64/128, at least 32 rows) explicitly use stock
+MLX's FP16 compute path by default. Set `ONNXRUNTIME_EP_MLX_BF16_QMM_FP16=0` to disable it.
+
+The **Foundry Local** q4f16 decoders below run on the same M1 Max, warm, MLX EP vs the ORT CPU EP
+(decode = 1 token with 128 past; prefill = 128-token step):
+
+| Model | Arch | Prefill | Decode |
+|---|---|---:|---:|
+| Qwen2.5-0.5B | GQA, external rotary | **5.2×** | dispatch-bound (CPU-favored) |
+| Phi-3.5-mini | Phi3, GQA | **5.29×** | 1.19× |
+| Phi-4-mini | Phi4, long-context RoPE | **5.78×** | 1.10× |
+| Mistral-7B-Instruct | GQA, growing KV | **11.89×** | **3.30×** |
+| gemma-4-E2B | Gemma3n, 15-layer | 3.3× | **3.3×** |
+
+Muse-Glimmer-30B INT4, with the optimized bundled MLX runtime and automatic 8-layer groups, reaches
+**138.67 prefill tok/s** at 512 tokens and **14.79 decode tok/s** over 200 generated tokens. The
+same-quantization llama.cpp baseline reaches **137.84 / 13.50 tok/s**.
+
+Decode is weight-bandwidth-bound: small models can favor CPU, while larger q4 decoders benefit from
+MLX. Unclaimed ops fall back to ORT CPU.
+
+## Profiling & tracing (Perfetto)
+
+The EP ships a built-in tracer (compiled in by default, **near-zero cost when off**). Recording is
+gated entirely by environment variables — set one, run your model, and inspect the result.
+
+**Get a Perfetto/Chrome trace.** Point `ONNXRUNTIME_EP_MLX_TRACE` at an output path; the JSON trace is
+written when the inference session is torn down:
+
+```bash
+ONNXRUNTIME_EP_MLX_TRACE=/tmp/mlx_trace.json python your_script.py
+# then open https://ui.perfetto.dev  (or chrome://tracing) and load /tmp/mlx_trace.json
+```
+
+The timeline shows one span per fused subgraph (`mlx.subgraph`), a nested span around the synchronous
+`mlx_eval` (`mlx.eval` — its CPU wall time is the GPU-inclusive time of the whole fused subgraph),
+per-op build spans with shapes/dtype/bytes, and counter tracks for GPU memory / utilisation. Ops that
+fell back to a slower *composed* path (despite a fused kernel existing) are coloured distinctly with a
+`reason=…`, and a top-10 slowest-ops summary is emitted at teardown.
+
+**Lighter options** (no JSON file):
+
+| Env var | Effect |
+|---|---|
+| `ONNXRUNTIME_EP_MLX_VERBOSE=1` | Print the end-of-run session summary (claim rate, compute-path breakdown, time attribution) to stderr. |
+| `ONNXRUNTIME_EP_MLX_CLAIM_DEBUG=1` | Print each unclaimed node + the actionable reason (why the graph fragmented). |
+| `ONNXRUNTIME_EP_MLX_SIGNPOST=1` | Emit `os_signpost` intervals so an Instruments *Metal System Trace* correlates. |
+| `ONNXRUNTIME_EP_MLX_NO_STABLE_CROSS_CACHE=1` | Disable per-generation MLX reuse of immutable MHA cross-attention K/V inputs for performance A/B. |
+
+**Per-kernel GPU detail (Xcode).** MLX hides its Metal command buffers inside one fused `mlx_eval`, so
+the JSON trace times the fused eval as a whole. To see *inside* it, capture a boundary eval to a
+`.gputrace` bundle (full per-kernel timing / occupancy / bandwidth) and open it in Xcode:
+
+```bash
+MTL_CAPTURE_ENABLED=1 \
+ONNXRUNTIME_EP_MLX_GPU_CAPTURE=/tmp/mlx.gputrace \
+ONNXRUNTIME_EP_MLX_GPU_CAPTURE_EVAL=5 \
+python your_script.py
+```
+
+`MTL_CAPTURE_ENABLED=1` must be set before process start. `…_GPU_CAPTURE_EVAL` picks which eval to
+capture (0-based, default 0); for decode, eval 0 is prefill/warmup, so pick a steady-state token.
+
+## Concurrency
+
+MLX evaluation is thread-affine. Use one `InferenceSession` per thread; do not call `Run()` on one
+shared session from multiple threads.
+
+## Numerical accuracy
+
+Outputs are tolerance-matched against ORT CPU but are not bit-identical. Long greedy generations can
+diverge after near-tied logits because MLX and CPU use different floating-point reduction orders.
+
+## Layout
+
+```
+docs/     design docs (DESIGN, OP_ARCHITECTURE, COMPILED_CAPTURE, MLX_EVALUATION)
+rust/     the Rust EP: plugin-EP C-ABI vtables (factory/ep) + the modular ONNX->MLX
+          translator (engine, registry, ops/*.rs) over a mlx-c RAII layer (mlx.rs)
+python/   pure-Python pip package (onnxruntime-ep-mlx): a locator that bundles + registers
+          the cargo-built dylib (hatchling build hook, hatch_build.py)
+tests/    MLX op-correctness (tests/ops, pytest) + ONNX-standard conformance (tests/conformance)
+.github/  CI (cargo build + op tests) and PyPI trusted-publishing workflows
+```
+
+## Testing
+
+Build the EP (above), then run the pytest op-correctness suite (MLX vs ORT CPU reference):
+
+```sh
+export ONNXRUNTIME_MLX_EP_LIB=$PWD/rust/target/release/libonnxruntime_mlx_ep.dylib
+export DYLD_LIBRARY_PATH=<ort-prebuilt/lib>
+python -m pytest tests/ops -q
+```
+
+- `tests/ops` — each translated decoder op via MLX vs. ORT CPU reference (tolerance-gated, pytest)
+- `tests/conformance` — opt-in fuzz-conformance of the MLX EP against the ONNX standard
+  (`cbourjau/onnx-tests`); see [`tests/conformance/README.md`](tests/conformance/README.md)

onnxruntime_ep_mlx-0.27.6/README.md

@@ -0,0 +1 @@
+../README.md

onnxruntime_ep_mlx-0.27.6/hatch_build.py

@@ -0,0 +1,199 @@
+"""Hatchling build hook for onnxruntime-ep-mlx.
+
+Builds the Rust execution provider (`cargo build --release` in ../rust), then
+bundles the resulting `libonnxruntime_mlx_ep.dylib` together with its mlx-c/mlx
+runtime dependencies into the wheel package, relinked so they load from
+``@loader_path`` (a self-contained wheel). Finally it forces a platform wheel
+tag: the package ships no CPython-ABI extension, so a single
+``py3-none-macosx_*_arm64`` wheel installs on 3.12, 3.13 and the free-threaded
+builds alike.
+
+The onnxruntime dependency is intentionally NOT bundled — it is resolved at
+runtime from the host ``onnxruntime`` package (two-level namespace), matching the
+EP's design.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import sysconfig
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+PLUGIN_DYLIB = "libonnxruntime_mlx_ep.dylib"
+
+
+def _brew_prefix(pkg: str) -> Path:
+    out = subprocess.run(
+        ["brew", "--prefix", pkg],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return Path(out.stdout.strip())
+
+
+def _dependency_prefix(env_name: str, brew_pkg: str) -> Path:
+    value = os.environ.get(env_name)
+    return Path(value) if value else _brew_prefix(brew_pkg)
+
+
+def _linked_dependency(binary: Path, basename: str) -> str | None:
+    out = subprocess.run(
+        ["otool", "-L", str(binary)],
+        check=True,
+        capture_output=True,
+        text=True,
+    ).stdout
+    for line in out.splitlines()[1:]:
+        dependency = line.strip().split(" ", 1)[0]
+        if Path(dependency).name == basename:
+            return dependency
+    return None
+
+
+def _run(cmd: list[str], **kw) -> None:
+    print("[onnxruntime-ep-mlx build] $", " ".join(cmd), flush=True)
+    subprocess.run(cmd, check=True, **kw)
+
+
+def _resolve_ort_include() -> str:
+    """Mirror rust/build.rs: ORT_INCLUDE_DIR, else $ORT_HOME/include."""
+    inc = os.environ.get("ORT_INCLUDE_DIR")
+    if not inc:
+        home = os.environ.get("ORT_HOME")
+        if home:
+            inc = str(Path(home) / "include")
+    if inc and (Path(inc) / "onnxruntime_c_api.h").is_file():
+        return inc
+    raise RuntimeError(
+        "Could not locate the ONNX Runtime headers. Set ORT_INCLUDE_DIR to the "
+        "ORT C-API include dir, or ORT_HOME to an ONNX Runtime release root "
+        "(expects $ORT_HOME/include/onnxruntime_c_api.h)."
+    )
+
+
+class CustomBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        if sys.platform != "darwin":
+            raise RuntimeError("onnxruntime-ep-mlx only builds on macOS (Apple Silicon).")
+
+        project_root = Path(self.root)          # the python/ dir
+        # In a repository checkout the crate is ../rust. In an sdist it is
+        # included as ./rust so installers can build the wheel from source.
+        rust_dir = project_root / "rust"
+        if not (rust_dir / "Cargo.toml").is_file():
+            rust_dir = project_root.parent / "rust"
+        if not (rust_dir / "Cargo.toml").is_file():
+            raise RuntimeError(
+                "Rust crate not found. Expected ./rust in an sdist or ../rust "
+                "in a repository checkout."
+            )
+
+        pkg_dir = project_root / "src" / "onnxruntime_ep_mlx"
+
+        # 1) Build the Rust EP dylib.
+        env = dict(os.environ)
+        env["ORT_INCLUDE_DIR"] = _resolve_ort_include()
+        _run(["cargo", "build", "--release"], cwd=str(rust_dir), env=env)
+
+        built = rust_dir / "target" / "release" / PLUGIN_DYLIB
+        if not built.is_file():
+            raise RuntimeError(f"cargo did not produce {built}")
+
+        # 2) Copy the plugin into the package.
+        dest_plugin = pkg_dir / PLUGIN_DYLIB
+        shutil.copy2(built, dest_plugin)
+        os.chmod(dest_plugin, 0o755)
+
+        # 3) Bundle + relink the mlx runtime next to the plugin (self-contained).
+        self._bundle_mlx(pkg_dir, dest_plugin)
+
+        # 4) This is a platform wheel with no Python-ABI extension: force a
+        #    py3-none-macosx_*_arm64 tag so ONE wheel serves every interpreter
+        #    (CPython 3.10+, free-threaded 3.13t/3.14t, ...).
+        plat = sysconfig.get_platform().replace("-", "_").replace(".", "_")
+        # Honour MACOSX_DEPLOYMENT_TARGET for the platform floor: the bundled
+        # dylibs (and mlx) target it, so the tag should advertise it rather than
+        # whatever floor the running interpreter was built against.
+        dep_target = os.environ.get("MACOSX_DEPLOYMENT_TARGET")
+        if dep_target and plat.startswith("macosx_"):
+            arch = plat.rsplit("_", 1)[-1]
+            major, _, minor = dep_target.partition(".")
+            plat = f"macosx_{major}_{minor or '0'}_{arch}"
+        build_data["pure_python"] = False
+        build_data["infer_tag"] = False
+        build_data["tag"] = f"py3-none-{plat}"
+
+    # -- mlx bundling ---------------------------------------------------------
+    def _bundle_mlx(self, pkg_dir: Path, plugin: Path) -> None:
+        mlxc_pfx = _dependency_prefix("MLXC_PREFIX", "mlx-c")
+        mlx_pfx = _dependency_prefix("MLX_PREFIX", "mlx")
+        mlxc_src = mlxc_pfx / "lib" / "libmlxc.dylib"
+        mlx_src = mlx_pfx / "lib" / "libmlx.dylib"
+        metallib_src = mlx_pfx / "lib" / "mlx.metallib"
+        for f in (mlxc_src, mlx_src, metallib_src):
+            if not f.is_file():
+                raise RuntimeError(f"Required mlx artifact missing: {f} (brew install mlx-c)")
+
+        mlxc_dst = pkg_dir / "libmlxc.dylib"
+        mlx_dst = pkg_dir / "libmlx.dylib"
+        for src, dst in ((mlxc_src, mlxc_dst), (mlx_src, mlx_dst), (metallib_src, pkg_dir / "mlx.metallib")):
+            shutil.copy2(src, dst)
+            os.chmod(dst, 0o644)
+        os.chmod(mlxc_dst, 0o755)
+        os.chmod(mlx_dst, 0o755)
+
+        jaccl_src = mlx_pfx / "lib" / "libjaccl.dylib"
+        jaccl_dst = pkg_dir / "libjaccl.dylib"
+        if jaccl_src.is_file():
+            shutil.copy2(jaccl_src, jaccl_dst)
+            os.chmod(jaccl_dst, 0o755)
+
+        def name_tool(*args: str) -> None:
+            _run(["install_name_tool", *args])
+
+        def resign(f: Path) -> None:
+            subprocess.run(["codesign", "--force", "--sign", "-", str(f)], check=False)
+
+        # Bundled mlx install ids -> @loader_path.
+        name_tool("-id", "@loader_path/libmlxc.dylib", str(mlxc_dst))
+        name_tool("-id", "@loader_path/libmlx.dylib", str(mlx_dst))
+        # Relink MLX dependencies by basename so both Homebrew absolute paths and
+        # custom-build @rpath install names work.
+        mlxc_mlx = _linked_dependency(mlxc_dst, "libmlx.dylib")
+        if mlxc_mlx:
+            name_tool("-change", mlxc_mlx, "@loader_path/libmlx.dylib", str(mlxc_dst))
+
+        # Plugin's mlx deps -> colocated copies.
+        plugin_mlxc = _linked_dependency(plugin, "libmlxc.dylib")
+        plugin_mlx = _linked_dependency(plugin, "libmlx.dylib")
+        if plugin_mlxc:
+            name_tool("-change", plugin_mlxc, "@loader_path/libmlxc.dylib", str(plugin))
+        if plugin_mlx:
+            name_tool("-change", plugin_mlx, "@loader_path/libmlx.dylib", str(plugin))
+
+        if jaccl_src.is_file():
+            name_tool("-id", "@loader_path/libjaccl.dylib", str(jaccl_dst))
+            mlx_jaccl = _linked_dependency(mlx_dst, "libjaccl.dylib")
+            if mlx_jaccl:
+                name_tool("-change", mlx_jaccl, "@loader_path/libjaccl.dylib", str(mlx_dst))
+
+        # The Rust EP does NOT link libonnxruntime — it reaches ORT purely through
+        # the OrtApi function-pointer table handed to CreateEpFactories (see
+        # rust/build.rs). So there is no onnxruntime dependency to relink here;
+        # ORT dlopen()s the plugin by the absolute path library_path() returns.
+
+        # Re-sign everything we mutated (install_name_tool voids the ad-hoc sig;
+        # dyld SIGKILLs unsigned/invalid arm64 images).
+        bundled = [mlxc_dst, mlx_dst, plugin]
+        if jaccl_src.is_file():
+            bundled.append(jaccl_dst)
+        for f in bundled:
+            resign(f)

onnxruntime_ep_mlx-0.27.6/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling>=1.24", "delocate>=0.11"]
+build-backend = "hatchling.build"
+
+[project]
+name = "onnxruntime-ep-mlx"
+version = "0.27.6"
+description = "MLX-native ONNX Runtime execution provider (plugin EP) for Apple Silicon"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "onnxruntime-ep-mlx" }]
+keywords = ["onnxruntime", "mlx", "execution-provider", "apple-silicon", "metal", "coreml"]
+dependencies = ["onnxruntime>=1.22"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS :: MacOS X",
+  "Programming Language :: Rust",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/justinchuby/onnxruntime-mlx"
+Repository = "https://github.com/justinchuby/onnxruntime-mlx"
+
+# --- Hatchling wheel build ----------------------------------------------------
+# The execution provider is a Rust `cdylib` (../rust). It is NOT a Python
+# extension module, so there is no compiled Python surface to build: the Python
+# layer (onnxruntime_ep_mlx/__init__.py) is a *pure-Python locator* that only finds
+# and registers the bundled dylib. The custom build hook (hatch_build.py):
+#   1. runs `cargo build --release` in ../rust (honouring ORT_INCLUDE_DIR / ORT_HOME),
+#   2. bundles the cargo-built libonnxruntime_mlx_ep.dylib + the mlx-c/mlx runtime
+#      (via delocate) into the package, relinked to @loader_path,
+#   3. forces a platform wheel tag (py3-none-macosx_*_arm64) — one wheel that
+#      installs on CPython 3.10-3.13 AND the free-threaded (3.13t/3.14t) builds,
+#      because it ships no CPython-ABI-bound extension. abi3audit has nothing to
+#      audit (no extension modules) so `abi3audit --strict` is trivially clean.
+#
+# Why pure-Python instead of maturin+pyo3: `_core` was only ever a locator
+# (ep_name/version/library_path). A compiled pyo3 abi3 extension cannot also be
+# free-threaded (abi3 wheels are unsupported under Py_GIL_DISABLED), so "abi3 AND
+# abi3t" would force *separate* per-version cp313t/cp314t wheels. Shipping zero
+# native Python code sidesteps that entirely: one platform wheel serves every
+# interpreter (GIL and free-threaded alike) and is abi3audit-clean by construction.
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/onnxruntime_ep_mlx"]
+# The dylibs / metallib are placed into the package dir by the build hook.
+artifacts = [
+  "src/onnxruntime_ep_mlx/*.dylib",
+  "src/onnxruntime_ep_mlx/*.metallib",
+]
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.sdist]
+# Carry the Rust crate too, so `pip wheel` can build the macOS wheel directly
+# from the PyPI sdist rather than requiring a full repository checkout.
+include = [
+  "src/onnxruntime_ep_mlx",
+  "hatch_build.py",
+  "README.md",
+]
+
+[tool.hatch.build.targets.sdist.force-include]
+"../rust/Cargo.toml" = "rust/Cargo.toml"
+"../rust/build.rs" = "rust/build.rs"
+"../rust/README.md" = "rust/README.md"
+"../rust/src" = "rust/src"
+"../rust/wrapper_mlx.h" = "rust/wrapper_mlx.h"
+"../rust/wrapper_ort.h" = "rust/wrapper_ort.h"

onnxruntime_ep_mlx-0.27.6/rust/Cargo.toml

@@ -0,0 +1,56 @@
+[package]
+name = "onnxruntime-ep-mlx"
+version = "0.27.6"
+edition = "2024"
+description = "MLX-native ONNX Runtime execution provider (plugin EP) for Apple Silicon — binds mlx-c directly, no mlx-rs."
+license = "MIT"
+repository = "https://github.com/justinchuby/onnxruntime-mlx"
+readme = "README.md"
+keywords = ["onnx", "onnxruntime", "mlx", "apple-silicon", "metal"]
+categories = ["science", "api-bindings", "hardware-support"]
+# Keep repo-only tooling out of the published crate: the *.py files are leak-check /
+# tracing scripts run by CI from the repo (not part of the Rust crate).
+exclude = ["*.py"]
+
+[lib]
+# Pin the lib (and therefore dylib) name so it stays `libonnxruntime_mlx_ep.dylib`
+# regardless of the crate name — the Python package, tests, CI and onnx-genai all
+# load the plugin by that exact filename.
+name = "onnxruntime_mlx_ep"
+crate-type = ["cdylib"]
+
+[dependencies]
+# Structured logging facade — zero-cost when the log level is disabled at
+# compile time (via `max_level_*` features) or when no logger is installed.
+# This is the FACADE only; the in-crate `logging` module provides the minimal
+# subscriber (a 20-line stderr logger gated by env vars). Using `log` rather
+# than `tracing` because this is a cdylib plugin loaded into someone else's
+# process: the `log` facade is lighter, has no global subscriber conflict risk,
+# and the plugin's statically-linked copy of `log` is fully independent of
+# whatever the host process uses.
+log = { version = "0.4", features = ["std"] }
+half = "2"
+serde_json = "1"
+image = { version = "0.25", default-features = false, features = ["bmp", "jpeg", "png", "pnm", "tiff", "webp"] }
+jpeg2k = { version = "0.10", default-features = true }
+
+# Pure-Rust Chrome/Perfetto tracer, from crates.io. `default-features = false`
+# drops the `perfetto` (prost) feature — we export Chrome Trace JSON only.
+#
+# Pinned to a release with the absolute UNIX-microsecond clock. Every copy of
+# the crate -- the host's and this dylib's, which has its own statics and so
+# could never have shared a process-global epoch -- reports the same instant as
+# the same number, which is what lets a trace from this plugin be laid over a
+# host trace with no offset to negotiate.
+onnx-runtime-tracer = { version = "0.1.0-dev.5", default-features = false }
+
+[build-dependencies]
+bindgen = "0.72"
+
+[profile.release]
+# Unwind (not abort) so panics can be caught at every C-ABI boundary (see
+# `guard_ffi_status` in lib.rs and the trace_thunk catch_unwind): a plugin loaded into a
+# host process must degrade to an error, never take the host down. Every extern-"C" entry
+# that runs real logic is wrapped, and the MLX trace callback catches locally, so a panic
+# never unwinds across the FFI boundary (which would be UB).
+panic = "unwind"