apple/coreai-models: export recipes, Python primitives and a Swift runtime for on-device AI

The gap apple/coreai-models fills between a PyTorch checkpoint and an app

Getting a model onto an iPhone or a Mac is not one problem, it is four. You need an export path from the original checkpoint, a set of authoring rules that the on-device runtime will actually accept, a way to load the result inside an app, and a way to try it from a terminal. apple/coreai-models packages all four in a single repository. The models directory is a catalog with a README and an export recipe per model or model family. The python directory holds primitives for authoring custom models in PyTorch plus utilities for exporting them. The swift directory is a Swift package named coreai-models that wraps the Core AI framework for macOS and iOS apps. The skills directory contains plugins that let coding agents work with Core AI.

The intended reader is an engineer who has a model in mind and a shipping target on Apple silicon. The repository is explicit that exported models are standalone .aimodel files, and that some models need more than one file: language models need a tokenizer, and diffusion models run several models in sequence as one pipeline. For those cases the recipes emit a resource folder holding one or more .aimodel files plus the supporting resources. That folder layout is the part most people underestimate, because the app-side integration is not a single file copy.

How the export pipeline is structured

The data flow runs from Hugging Face or another source, through Python, into a Core AI artifact. The README describes the Python layer as building blocks for authoring custom Core AI models in PyTorch, and the export utilities as the piece that turns a model into Core AI format. The two named packages in the skills table are coreai-torch for export and coreai-opt for weight compression exploration, which tells you the toolchain is split between producing a model and shrinking it.

The compression skill is described as exploring quantization and palettization configurations for a PyTorch model. That is a search problem, not a one-line flag, and the repository treats it as a skill rather than a fixed recipe. The authoring skill lists the constraints it encodes: BC1S layout, op compatibility, KV cache patterns, precision rules and MoE. Those are the rules that decide whether a model exports cleanly or fails late.

On the runtime side, the Swift package sits on top of the Core AI framework and is the integration point for apps. Command line tools are also included for running exported models directly on a Mac, and the README points to each model's own README for the available tools and example invocations rather than documenting them centrally. That decentralised layout is a deliberate choice, and it means the top-level README is a map, not a manual.

Installing the toolchain and listing supported models

The Python side is managed with uv, and the README gives two install routes. Either works; the Homebrew route is shorter if you already use Homebrew.

brew install uv

If you prefer the installer script, the README offers the official one:

curl -LsSf https://astral.sh/uv/install.sh | sh

The workspace declares a required uv version of 0.9.0 or newer in pyproject.toml, so an older uv will refuse to run the workspace. Once uv is present, clone the repository and ask the registry what it knows about. This is the first real command most people run, because it answers the question of whether your model is covered before you read any recipe.

git clone https://github.com/apple/coreai-models.git && cd coreai-models
uv run coreai.model.registry --list-models

The README states that `uv run coreai.model.registry --help` prints the details of the command. After that, the next step is not a global command: you open the README.md inside the relevant folder under models and follow that family's export recipe. There is no single export invocation for the whole catalog, and the top-level README does not pretend otherwise.

For app integration the requirements are stricter than for export. Running exported models and integrating them into an app needs macOS and iOS 27.0 or later, and Xcode 27.0 or later. The CLI tools for running exported models on a Mac also require Xcode 27.0 or later.

Agent skills and how each coding agent installs them

The skills directory is the part of this repository that differs most from a conventional model zoo. Rather than documenting rules for humans to read, it ships them as plugins so a coding agent applies them while writing code. Three skills are listed: working-with-coreai for the end-to-end PyTorch to Apple silicon workflow, model-authoring for the empirical rules, and model-compression-exploration for quantization and palettization search.

Installation is per agent. For Claude Code the README registers a marketplace and then installs the plugin:

/plugin marketplace add git@github.com:apple/coreai-models.git
/plugin install coreai-skills@coreai-models

For Codex CLI the marketplace is registered with a URL and the plugin is installed through an interactive browser inside the session:

codex plugin marketplace add https://github.com/apple/coreai-models

Gemini CLI installs the extension from a local directory instead:

gemini extensions install /path/to/coreai-models/skills

The README notes that once installed, skills activate automatically based on task context, and that you can also invoke them explicitly. The practical consequence is that the authoring constraints live next to the code generator rather than in a wiki page, which is a reasonable bet if your team uses these agents, and dead weight if it does not.

Where apple/coreai-models is the wrong tool

The hard boundary is the platform floor. Running and integrating exported models requires macOS and iOS 27.0 or later, and the CLI tools require Xcode 27.0 or later. If your deployment target is older, or if any part of your inference path runs on Linux or Android, this repository does not address it. The Core AI framework it wraps is Apple's, and the Swift package is the integration surface.

The second limitation is scope control. The contributing section states plainly that the project is not accepting code contributions at this time, that pull requests will be closed, and that this is a deliberate scope decision for the release. Bug reports and model requests go through GitHub Issues using the issue templates. If your team's adoption criteria include the ability to carry a local patch upstream, this project fails that criterion by design. You can still fork it under BSD-3-Clause, but you will be maintaining the fork yourself.

The third limitation is that coverage is curated rather than exhaustive. The README describes a gallery of models, and the registry is the authority on what is included. A model that is not in the catalog has no recipe, and the primitives for authoring a custom model are a starting point, not a guarantee that an arbitrary architecture will export. The requirements section also flags that some models need extra resources, so the output is sometimes a folder rather than a file, and the app has to handle that.

How this differs from MLX and from Core ML

Two comparisons come up naturally. The first is MLX, Apple's other array and model framework. MLX is a general numerical and model framework with its own execution stack; apple/coreai-models is not a framework, it is a set of recipes and utilities that target the Core AI framework, and its Swift package is described as utilities built on top of Core AI rather than a runtime of its own. If you want to write and train models in a Python-first array library, that is a different job from exporting a checkpoint into an .aimodel file for an app.

The second comparison is Core ML, the older deployment format. The distinction visible here is the artifact and the toolchain: this project produces .aimodel files for the Core AI framework and ships export recipes plus authoring rules for them, including BC1S layout and KV cache patterns for language models. Whether Core AI supersedes Core ML for your use case is not something the README argues, and the repository does not present a migration guide. Treat them as separate targets until you have checked the Core AI documentation linked from the README.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-14, three days before this writing. Release 0.2.0 was tagged on 2026-07-08. That is a recent cadence, and the project is under Apple's stewardship rather than a single maintainer's.

The cost of upgrading is shaped by two version pins. The Python workspace requires uv 0.9.0 or newer, and pyproject.toml sets prerelease to allow and index-strategy to unsafe-best-match, which means dependency resolution may pull pre-release versions. That is a deliberate setting for a project tracking fast-moving model tooling, and it also means a lockfile refresh can move more than you expect. The uv.lock file at the repository root is the thing to diff between releases.

On the app side, the binding constraint is the OS and Xcode floor, not the package version. Moving to a newer coreai-models release will not help if your deployment target is below macOS or iOS 27.0. The Swift package declares its platform requirements in Package.swift, and the repository also carries a .spi.yml file, which is the Swift Package Index configuration.

Licensing is BSD-3-Clause, which is permissive and permits use in closed-source products with the licence and copyright notice retained. That covers the code in this repository. It does not tell you anything about the licences of the upstream model weights that the recipes download from Hugging Face, and those are separate terms you have to check per model. Nothing here is legal advice; the LICENSE file is the authoritative text.

Editorial conclusion

Adopt apple/coreai-models if you already target macOS or iOS 27.0 or later and want a maintained export path from Hugging Face checkpoints to .aimodel files, accepting that pull requests are closed and feedback goes through GitHub Issues. Do not adopt it if you need Linux inference, an older deployment target, or a project that accepts your patches. Before committing, verify the model you need appears in the registry output and that the export recipe for its family runs on your machine.

Frequently asked questions

Official sources

1. apple/coreai-models on GitHub
2. Issues
3. License: BSD-3-Clause
4. README
5. Releases