AX Engine

High-performance local inference engine for Apple Silicon — Python bindings.

Installation

Python SDK (pip)

Use pip when your application imports ax_engine or needs AX Engine's optional Python integrations. Install the wheel in a dedicated Python 3.12 environment. The recommended uv path is:

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install --upgrade "ax-engine[download]>=7.5.2,<8"
python -c 'import importlib.metadata; print(importlib.metadata.version("ax-engine"))'
which -a ax-engine
ax-engine doctor

Without uv, use python3.12 -m venv .venv, activate it, and install with python -m pip. Keep one installation channel active per shell when Homebrew is installed too.

Requires macOS 26+, Apple Silicon (M2 or newer), Python 3.12+. 16 GB is enough for compact single models; 32 GB+ for multi-model / larger packs. The current macOS arm64 wheel also includes the ax-engine orchestration CLI plus bundled ax-engine-server and ax-engine-bench binaries when you need a wheel-only install.

Verify the installed command surface:

ax-engine doctor
ax-engine-server --help

Native CLI and server (Homebrew, primary)

For end users running the TUI, CLI, server, or benchmark tools, Homebrew is the primary installation channel:

brew tap defai-digital/ax-engine
brew trust --formula \
  defai-digital/ax-engine/ax-engine \
  defai-digital/ax-engine/mlx \
  defai-digital/ax-engine/mlx-c
brew install defai-digital/ax-engine/ax-engine
ax-engine doctor

If both channels are installed, an active virtual environment normally shadows Homebrew's commands. Use which -a ax-engine to identify every copy and avoid mixing versions in one shell. See the Getting Started installation guide for requirements, linkage details, and troubleshooting.

Quick start

import ax_engine

session = ax_engine.Session(mlx=True, mlx_model_artifacts_dir="/path/to/model")
result = session.generate([token_id, ...], max_output_tokens=128)
print(result.output_tokens)

Native Unlimited-OCR image requests

AX Engine 6.12 exposes native Unlimited-OCR global and high-resolution tile paths without model repository code. Tokenize a prompt containing exactly one literal <image>, then let the helper expand and attach one local path or Pillow image:

from tokenizers import Tokenizer
import ax_engine

model_dir = "/path/to/ax-unlimited-ocr"
tokenizer = Tokenizer.from_file(f"{model_dir}/tokenizer.json")
input_tokens = tokenizer.encode(
    "<image>Convert the document to markdown.",
    add_special_tokens=False,
).ids
request = ax_engine.prepare_unlimited_ocr_image_request(
    model_dir,
    [0, *input_tokens],
    ["page.png"],
)

with ax_engine.Session(
    model_id="unlimited_ocr",
    mlx=True,
    mlx_model_artifacts_dir=model_dir,
) as session:
    result = session.generate(
        request.input_tokens,
        multimodal_inputs=request.multimodal_inputs,
        max_output_tokens=8192,
        no_repeat_ngram_size=35,
        ngram_window=128,
    )

text = tokenizer.decode(result.output_tokens, skip_special_tokens=False)

The public path accepts exactly one bounded RGB source image. By default it selects the released processor's bounded 640px tile grid (up to 32 tiles) in addition to the 1024px global view; pass cropping=False only for an explicit global-only tradeoff. Resize, tiling, letterboxing, normalization, dual-vision projection, and BF16 conversion run in the native MLX implementation.

Or use the OpenAI-compatible shim:

python -m ax_engine.openai_server \
    --model-id my-model \
    --mlx-model-artifacts-dir /path/to/model \
    --tokenizer /path/to/tokenizer.json \
    --port 31418

Then point any OpenAI client at http://127.0.0.1:31418.

Optional dependencies

Install the OpenAI shim or image/audio helpers with the matching extra:

python3 -m pip install --upgrade "ax-engine[openai]>=7.5.2,<8"
python3 -m pip install --upgrade "ax-engine[multimodal]>=7.5.2,<8"

Requirements

macOS 26 (Tahoe) or later
Apple Silicon — M2 or newer (16 GB light / single compact model; 32 GB+ full stack)
Python 3.12+

Project

github.com/defai-digital/ax-engine

Metadata

Release files for ax-engine 7.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for ax-engine 7.5.2
File	Interpreter	ABI	Platform	Reset
ax_engine-7.5.2-cp312-abi3-macosx_26_0_arm64.whl 82.2 MB Sep 20, 2026	CPython 3.12	abi3	macOS 26.0+ ARM64	Details

Release files / ax_engine-7.5.2-cp312-abi3-macosx_26_0_arm64.whl

Download URL	ax_engine-7.5.2-cp312-abi3-macosx_26_0_arm64.whl
Size	82.2 MB
Tags	CPython 3.12 abi3 macOS 26.0+ ARM64
SHA-256 checksum How to use checksums	`a903980b3964c7e60f92a44094d9689dd7009531eba609fe20b3876e6029dc74`
BLAKE2b-256 checksum How to use checksums	`b103d0b88458acd155df4e0686caa525f5c8ac783849e45fdbc1680b02e4591a`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/defai-digital/ax-engine
Publishing commit: github.com/defai-digital/ax-engine/tree/f107d667942aa586f99ca79e7bc7aa0c2ef16be8

Workflow

Publishing configuration: github.com/defai-digital/ax-engine/blob/f107d667942aa586f99ca79e7bc7aa0c2ef16be8/.github/workflows/pypi.yml
Publishing logs: github.com/defai-digital/ax-engine/actions/runs/35542100249/attempts/1

Artifact

Subject: ax_engine-7.5.2-cp312-abi3-macosx_26_0_arm64.whl
SHA-256 checksum: a903980b3964c7e60f92a44094d9689dd7009531eba609fe20b3876e6029dc74 Verifying attestations