Metadata-Version: 2.2
Name: kestrel-mps-torch-ext
Version: 0.1.1
Summary: PyTorch-minor-specific Kestrel MPS native op loader
Requires-Python: <3.15,>=3.10
Requires-Dist: packaging
Description-Content-Type: text/markdown

# 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 such as `torch29`, `torch210`,
`torch211`, and `torch212`. 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:

```bash
python -m pip install "torch==2.12.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:

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

No Kestrel source checkout is required.

## Runtime

```python
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.
