kestrel-mps-torch-ext

Small ABI-specific sidecar for Kestrel's native MPS tensor/stream handles.

This package follows the same basic pattern as torch-c-dlpack-ext: the Python loader selects a native library whose filename includes the runtime PyTorch major/minor version and loads it with ctypes.CDLL. The native library still links against libtorch, so this is not a stable ABI. It just isolates the torch-version-sensitive part into a small package.

Wheels are published per Python ABI (cp310, cp311, ...). Each wheel can bundle multiple PyTorch-minor-specific dylibs. Current wheels cover torch 2.9 through 2.14 (torch29, torch210, torch211, torch212, torch213, and torch214). Patch versions do not get separate dylibs: torch 2.12.0 and 2.12.1 both resolve to torch212.

This package does not ship Metal kernel source, a metallib, or Kestrel torch op registrations. It only exports a narrow C ABI for:

• resolving a torch.Tensor Python object to its MTLBuffer plus shape/stride metadata;
• accessing the current PyTorch MPS stream, command buffer, device, and queue;
• ending PyTorch kernel coalescing and committing the stream.

The main kestrel-kernels package remains responsible for loading kestrel_mps.metallib and dispatching the actual Metal kernels.

Build

Install the exact PyTorch version you want this wheel to target, then build without PEP 517 isolation so CMake sees that same torch install:

python -m pip install "torch==2.14.0" scikit-build-core cmake ninja packaging wheel
python -m pip wheel --no-build-isolation .

The build backend defaults MACOSX_DEPLOYMENT_TARGET to 13.0, so a build on macOS 15 still produces a macosx_13_0_arm64 wheel. Override the target only when intentionally changing the runtime support floor:

MACOSX_DEPLOYMENT_TARGET=14.0 python -m pip wheel --no-build-isolation .

No Kestrel source checkout is required.

Runtime

import kestrel_mps_torch_ext

kestrel_mps_torch_ext.load_torch_mps_bridge()

After that call, the ABI-matched dylib is loaded with RTLD_GLOBAL, so the main Kestrel native library can find KestrelMPSTorchExtAPI_v1 with dlsym.

Unsupported PyTorch Minors

If the installed PyTorch minor is not bundled in the wheel, import fails before any native code is used. The error lists the installed torch version, the supported torch minors, and the missing dylib name.

Use one of the listed PyTorch minors, install a newer kestrel-mps-torch-ext wheel that includes your minor, or email contact@moondream.ai for help.