Metadata-Version: 2.4
Name: phantom-lang
Version: 0.1.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Dist: numpy>=1.21
Summary: Phantom ML compiler: declarative model definitions compiled to native code via LLVM. pip install phantom-lang; import phantom.
Author: Phantom contributors
License: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# phantom — Python bindings for Phantom

Idiomatic Python bindings for the [Phantom](https://github.com/menezzo/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

```bash
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

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

