phantom — Python bindings for Phantom

Idiomatic Python bindings for the Phantom compiler. Calls JIT-compiled Phantom shapes against numpy arrays in one function call — no ctypes, no manual buffer management, no dylib path juggling.

Install

pip install maturin
git clone https://github.com/menezzo/phantom
cd phantom/crates/phantom-pyo3
maturin develop --release

A pip install phantom wheel is the next ship; until then, maturin develop builds the extension module in-place against your active Python interpreter.

Quickstart

import numpy as np
import phantom

# Run a Phantom shape from a .ph file with a numpy float32 input.
out = phantom.run(
    "examples/two_host_pipeline.ph",
    np.array([1.0, 2.0, 3.0, 4.0], dtype=np.float32),
)
print(out)  # numpy array

# With pre-loaded weights from a directory of .npy files.
out = phantom.run(
    "examples/gpt2.ph",
    np.load("/tmp/phantom-gpt2-golden/input.npy"),
    weights_dir="/tmp/phantom-gpt2-golden",
)
print(out.shape)  # (32, 256)

# Or compile from a source string (for inline notebook use).
src = """
shape add_one =
  it ~> add 1.0
"""
out = phantom.run_source(src, np.array([1.0, 2.0, 3.0], dtype=np.float32))
print(out)  # [2., 3., 4.]

Contract

• f32 only: numpy arrays must be dtype=np.float32. Other dtypes raise TypeError at the boundary. Cast explicitly with .astype(np.float32) if you need to.
• C-contiguous only: non-contiguous arrays raise ValueError. Use np.ascontiguousarray(arr) to convert.
• Errors are Python exceptions: parse/resolve/typecheck/lower failures raise RuntimeError with the rendered diagnostic; runtime errors do the same. No status codes, no thread-local error strings.

What this wraps

phantom.run and phantom.run_source are thin wrappers over phantom_driver::run_pipeline::compile_and_invoke. The same JIT pipeline that powers phantom-driver run from the CLI also powers these calls, so the numerical results match bit-identical (or within floating-point noise) between the Python API and the CLI.

The Phantom GPT-2 model that matches PyTorch within 1.79e-07 via the C FFI also matches PyTorch via this API — same JIT, same MLIR, same LLVM codegen, just a different ergonomic shell.