coreai-onnx 1.1.0

Convert ONNX models to Apple Core AI (.aimodel) — the AI-first successor to Core ML on iOS 27. Validated, precision-checked, agent-friendly, with automatic float16 repair and an MCP server.

coreai-onnx

The missing ONNX path into Apple's next-generation Core AI runtime.

coreai-onnx converts existing ONNX exports directly into Apple's .aimodel format, helping teams bring high-performance AI workloads to the full Apple ecosystem — macOS, iOS, iPadOS, visionOS, watchOS, and tvOS — without custom export scripts or manual graph surgery.

Built for the Core AI era, it pairs a clean conversion pipeline with ONNX Runtime validation, numerical precision reports, fused graph optimizations, JSON-first CLI output, and MCP automation. Inspect coverage, convert with confidence, and help expand the supported-op surface for Apple's newest on-device AI stack.

Quickstart

from pathlib import Path

import coreai_onnx

program = coreai_onnx.convert("model.onnx", input_names=["x"], output_names=["y"])
program.optimize()
program.save_asset(Path("model.aimodel"))

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. The ONNX Runtime steps are skipped, with a note, when onnxruntime is not installed or you are not on macOS.

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

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 register coreai-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.

Install

pip install coreai-onnx                    # conversion only
pip install "coreai-onnx[verify]"          # + numerical verification via onnxruntime

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 — convert confirms 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 .aimodel against 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_attention composite, so the on-device GPU compiler runs its fused kernel instead of crashing on the raw MatMul → Softmax → MatMul pattern (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 inspect shows 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

Task	Platform
Convert ONNX → .aimodel	Any (macOS, Linux, Windows)
Execute .aimodel	macOS 27+ / iOS 27+ (Core AI framework)
Verify parity (verify subcommand)	macOS 27+ + onnxruntime

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

Package	Role
coreai-onnx	Convert ONNX models to .aimodel (this package)
coreai-torch	Export PyTorch models directly to Core AI via torch.export
coreai-opt	Post-conversion optimisation passes (quantisation, pruning)
coreai-models	Pre-converted .aimodel hub for common model families

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 If branches hang at runtime; single-output If works.

Versioning and CoreAI compatibility

coreai-onnx depends on coreai-core>=1.0.0b1,<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.

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.