Metadata-Version: 2.4
Name: ax-engine
Version: 5.1.3
Requires-Dist: mlx-lm>=0.31 ; extra == 'download'
Requires-Dist: fastapi>=0.110 ; extra == 'openai'
Requires-Dist: tokenizers>=0.15 ; extra == 'openai'
Requires-Dist: uvicorn[standard]>=0.29 ; extra == 'openai'
Provides-Extra: download
Provides-Extra: openai
License-File: LICENSE
Summary: Python bindings for AX Engine
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# ax-engine-py

Python bindings for AX Engine.

This crate exposes the `ax_engine._ax_engine` extension module and stays aligned
with the AX Engine SDK contract rather than inventing a separate Python-only runtime
surface.

Current preview scope:

- SDK-backed `Session`
- fail-closed host validation (requires M2 Max or newer, macOS 14+, 32 GB RAM)
- runtime metadata reporting
- `mlx=True` selects the repo-owned MLX runtime
- `support_tier="mlx_lm_delegated"` selects explicit upstream `mlx-lm` text
  compatibility through `mlx_lm_server_url`
- non-MLX inference routes to `llama.cpp`
- text/chat convenience helpers over the same SDK-backed request contract
- stepwise request control via `submit(...)`, `step()`, `snapshot(...)`, and
  `cancel(...)`
- SDK-backed in-process `stream_generate(...)` lifecycle events emitted through
  a native incremental iterator
- mlx-lm compatibility via `mlx_lm_server_url`
- llama.cpp compatibility via `llama_model_path`, `llama_cli_path`, or
  `llama_server_url`
- `native_mode=True` is retired and returns an error

Current non-goals:

- text tokenization and decoding
- automatic model-aware chat templating
- transport-level remote streaming
- broad compatibility lifecycle parity across multiple delegated adapters

For Phase 1, stepwise request-control methods support MLX preview plus the
server-backed `llama.cpp` compatibility path. The `mlx_lm_delegated` path is
text-only blocking generation through `mlx_lm.server`; token prompts,
streaming, and lifecycle calls fail closed. One llama.cpp compatibility session
can now hold multiple active delegated requests while `step()` aggregates
progress across them.

Build from the repository root with `maturin`:

```bash
maturin develop
```

For a repo-owned integration smoke check that bootstraps a temporary virtual
environment, installs `maturin`, builds the extension, runs the checked-in
Python examples, and then runs both the installed-package preview tests and the
wrapper tests, use:

```bash
bash scripts/check-python-preview.sh
```

To verify the extension-module packaging path without installing it, build from
the repository root with:

```bash
cargo build -p ax-engine-py --no-default-features --features python-extension
```

