coreai-onnx
ONNX → Apple Core AI (.aimodel) converter for on-device inference.
Bring ONNX models exported from PyTorch and other ONNX-compatible frameworks
to Apple's Core AI runtime on Apple silicon. coreai-onnx converts models into
.aimodel bundles with 143 built-in ONNX operator lowerings, graph
optimization, and numerical verification against ONNX Runtime.
Use the Python API, command-line interface (CLI), or Model Context Protocol (MCP) server to inspect operator coverage, convert models, and check output precision in your development or AI agent workflow.
Documentation · Supported ONNX operators · MCP server · PyPI · Releases
Install
pip install coreai-onnx # conversion only
pip install "coreai-onnx[verify]" # + numerical verification via onnxruntime
Requires Python 3.11–3.14. Conversion runs on macOS, Linux, and Windows.
Executing .aimodel bundles requires macOS 27+ / iOS 27+ with the Core AI
framework; precision verification runs on macOS 27+.
Quickstart
from pathlib import Path
import coreai_onnx
program = coreai_onnx.convert("model.onnx", input_names=["x"], output_names=["y"])
program.save_asset(Path("model.aimodel"))
convert() returns an optimized program. Pass optimize=False to inspect the
IR before optimization.
Or from the command line:
coreai-onnx inspect model.onnx # check coverage before converting
coreai-onnx convert model.onnx -o model.aimodel # validates on ONNX Runtime, converts, then reports precision
coreai-onnx verify model.onnx model.aimodel # re-check precision of an existing .aimodel
coreai-onnx schema --json # machine-readable capability dump
convert runs an end-to-end pipeline: it first confirms the model loads and runs
on ONNX Runtime (and stops with a clear error if it does not), converts and
optimises it, then prints a precision comparison of the saved .aimodel against
ONNX Runtime. Input validation runs when onnxruntime is installed; the
precision comparison also requires macOS 27+ with the Core AI runtime. Skipped
steps are reported with a warning.
A real session on torchvision's MobileNetV3-Small (opset 18):
$ coreai-onnx inspect mobilenet_v3_small.onnx
┃ Op ┃ Count ┃ Status ┃
│ Add │ 6 │ supported │
│ Conv │ 52 │ supported │
│ Gemm │ 2 │ supported │
│ GlobalAveragePool │ 10 │ supported │
│ HardSwish │ 19 │ supported │
│ ... │ │ │
Total nodes: 159 | convertible: yes
$ coreai-onnx convert mobilenet_v3_small.onnx -o mobilenet_v3_small.aimodel
Converted successfully
Nodes: 159
Output: mobilenet_v3_small.aimodel
Precision: ONNX Runtime vs .aimodel
┃ Output ┃ Max abs error ┃ Max rel error ┃ PSNR ┃ Pass ┃
│ 400 │ 7.7716e-16 │ 9.1514e-03 │ 136.28 │ PASS │
Precision check passed
Architecture
A high-level map of the conversion path: the three entry surfaces (Python API,
CLI, and MCP server) over a shared command core, the preprocess → fuse → lower
pipeline that emits the .aimodel, and the ONNX Runtime validation and precision
checks that gate it. See docs/cli.md for the JSON envelope and the
frozen error/warning/exit-code contracts.
For AI agents
coreai-onnx is built to be driven by agents: every command takes --json and
returns one stable envelope with documented error and exit codes.
- AGENTS.md — the agent playbook: workflow, error recovery, exit codes.
- MCP server —
pip install "coreai-onnx[mcp]", then registercoreai-onnx-mcp(stdio); tools return the same JSON envelope (docs). coreai-onnx schema --json— the full machine-readable capability contract.- llms.txt — the llms.txt index, served from the docs site.
Features
-
143 built-in op lowerings supported out of the box — elementwise, reductions, matrix math, convolutions, normalisation, quantization, control flow, shape manipulation, and more.
-
Parity-verified — every built-in lowering is tested against ONNX Runtime on randomised inputs.
-
Validated, precision-checked conversion —
convertconfirms the input model actually runs on ONNX Runtime before converting (failing fast with a clear error on a broken model), then reports the precision of the saved.aimodelagainst ONNX Runtime so you see the numerical gap up front. -
Automatic attention fusion — scaled-dot-product attention chains are rewritten into the Core AI
scaled_dot_product_attentioncomposite, so the on-device GPU compiler runs its fused kernel instead of crashing on the rawMatMul → Softmax → MatMulpattern (the cause of Xcode Performance-report failures on transformer/YOLO models). -
Automatic activation fusion — decomposed GELU and SiLU/Swish chains, including chains inside ONNX control-flow branches, are collapsed to fused Core AI primitives for fewer full-tensor kernels and better runtime quality.
-
Inspect before you convert —
coreai-onnx inspectshows op coverage and a node histogram so you know what to expect before running the full conversion. -
Custom lowering escape hatch — register a Python function to lower any op your model needs, including custom-domain ops:
@converter.register_onnx_lowering("mycompany::MyOp") def lower_my_op(values_map, node, loc): ... -
Conversion runs anywhere — macOS, Linux, or Windows; no Apple hardware needed for the conversion step itself.
Runtime requirements
CI scope
Public GitHub CI is intentionally lightweight. GitHub-hosted runners do not currently provide the macOS 27 / iOS 27 SDK / Xcode 27 beta environment needed to validate Apple Core AI compiler/runtime behavior, so the CI badge covers only cross-platform safety checks:
ruff check .
python -m compileall src tests
pytest -m "not apple and not integration"
python -m build
twine check dist/*
Hosted CI does not run real Core AI conversion, GPU compilation, .aimodel
generation, or Apple SDK integration tests. Full Core AI conversion and runtime
validation must be run locally on macOS 27 + Xcode 27 beta.
Ecosystem
Documentation
Full documentation including the supported ops table and custom lowering guide is published at https://devin-lai.github.io/coreai-onnx/.
Known limitations
The Core AI runtime has a few confirmed quirks. See CONTRIBUTING.md — Known runtime quirks for the current list, which includes:
- Float16 graph inputs trigger a runtime crash (cast at the boundary as a workaround).
- Multi-output
Ifbranches hang at runtime; single-outputIfworks.
Versioning and CoreAI compatibility
coreai-onnx depends on coreai-core>=1.0.0b2,<2. Public GitHub CI validates the
linting, packaging, bytecode-compilation, and pure-Python test surface only.
Release validation against the supported Core AI environment is performed
locally on macOS 27 + Xcode 27 beta. The CLI JSON envelope
(schema_version: 1), error/warning codes, and exit codes are a frozen,
append-only contract — see docs/cli.md.
Contributing
See CONTRIBUTING.md for dev setup, the op-lowering workflow, and the PR checklist.
- Request an ONNX operator — include the op, opset, and model use case.
- Report a conversion or verification bug — include a minimal model and the command output.
- Add a custom lowering — extend coverage for the operators your model needs.
Attribution
coreai-onnx is free to use — including in commercial and closed-source products — under the BSD-3-Clause license. In return, please give credit: clearly attribute the project and cite its source wherever you build on it — in applications, research, derived tools, and automated or agent workflows alike:
coreai-onnx — https://github.com/devin-lai/coreai-onnx
And if coreai-onnx is useful to you, please ⭐ star the repository — real stars from real users are what help other people discover the project.
License
BSD-3-Clause. See LICENSE.