The Apple Foundation Models framework is a Swift programming interface that gives third-party apps direct access to the on-device large language model behind Apple Intelligence, so text generation, extraction and classification run locally on the device, without a network connection or per-request fees. Introduced in 2025 with iOS 26, iPadOS 26, macOS 26 and visionOS 26, it belongs among the AI frameworks & tools that developers use to build features on top of an existing model rather than to train one.
The framework is deliberately narrow. It exposes a compact model of roughly 3 billion parameters, optimized for summarization, entity extraction, tagging and short-form generation, and it is not intended as a general chatbot or a source of world knowledge. Its value lies in privacy, zero inference cost and tight Swift integration, including typed structured output and tool calling.
How the framework runs the on-device model
The framework works by opening a language model session against the system model that the operating system already ships and manages. The app does not bundle model weights; it calls SystemLanguageModel.default, checks that the model is ready and then sends prompts through a LanguageModelSession object that keeps the conversation transcript.
Each session combines instructions, which the developer writes to define role and rules, with prompts, which carry the per-request input. The model gives instructions higher priority than prompts, a design that helps resist prompt injection when prompts contain user text. All prior turns count against a context window of 4,096 tokens, shared by instructions, history, tool output and the response.
The table below lists the main building blocks and what each one controls.
| Component | Role | Practical note |
|---|---|---|
| SystemLanguageModel | Represents the on-device model | Exposes availability and use case |
| LanguageModelSession | Holds instructions and transcript | One session per task or conversation |
| Generable macro | Defines a Swift type for typed output | Enables guided generation |
| Guide macro | Adds constraints to properties | Ranges, counts, patterns, descriptions |
| Tool protocol | Lets the model call app code | Returns data the model then uses |
| GenerationOptions | Sets sampling and temperature | Greedy sampling gives repeatable output |
Guided generation, streaming and tool calling
Guided generation is the feature that most distinguishes the framework from text-only model APIs. A developer marks a Swift struct or enum with the @Generable macro, and the framework uses constrained decoding so the model can only emit tokens that form a valid instance of that type. The app receives a typed value instead of a JSON string that must be parsed and validated.
Streaming works on the same types. Rather than delivering raw token deltas, the framework streams snapshots of partially generated values, in which properties fill in as the model produces them. SwiftUI views can bind to these snapshots directly, which makes progressive interfaces simple to build.
Tool calling lets the model request data it does not have. The developer implements the Tool protocol with a name, a description and Generable arguments; the model decides when to call the tool, the framework runs it and inserts the result into the transcript. Tools are the correct route to fresh or app-specific facts, such as calendar entries, local records or a web lookup that the app itself performs.
The following table compares the three output styles a session supports.
| Output style | What the app receives | Best fit |
|---|---|---|
| Plain text response | A complete string | Summaries and short replies |
| Guided generation | A typed Swift value | Extraction, tagging, form filling |
| Streamed snapshots | Partial values over time | Interactive interfaces with visible progress |
How it compares with other AI frameworks and tools
The Foundation Models framework is a high-level inference API for one fixed model, which separates it from runtimes that execute arbitrary models. Core ML runs models that the developer converts and bundles, llama.cpp and Ollama run open-weight models on general hardware, and cloud APIs reach far larger models at a usage price.
| Approach | Model source | Main strength | Main limitation |
|---|---|---|---|
| Foundation Models framework | Built into the operating system | Free, private, typed Swift output | Small model, Apple platforms only |
| Core ML | Model bundled by the app | Any converted model architecture | App size and conversion effort |
| llama.cpp | Open-weight files | Cross-platform and flexible | Manual tuning and memory management |
| Cloud model API | Remote provider | Strong reasoning and knowledge | Cost, latency and data transfer |
In practice, the choice depends on the task. Structured extraction and short text tasks fit the built-in model well; complex reasoning, coding or broad factual answers generally require a larger model, often in the cloud. Many apps combine both, routing light work locally and heavy work remotely.
Device requirements, availability and adapters
The framework only functions where Apple Intelligence is supported and enabled. That means recent hardware, such as iPhone 15 Pro and later models or Macs and iPads with M-series chips, a supported language and region, and a downloaded model. Apps must therefore check availability before showing any feature that depends on the model.
| Availability state | Cause | Recommended app behavior |
|---|---|---|
| Available | Model ready on a supported device | Enable the feature normally |
| Device not eligible | Hardware lacks Apple Intelligence support | Hide the feature or offer a fallback |
| Apple Intelligence not enabled | The user has turned it off | Explain the requirement briefly |
| Model not ready | Download or setup still in progress | Retry later and show a waiting state |
For specialized domains, Apple provides an adapter training toolkit that produces low-rank adapters for the system model. Adapters can raise quality on a narrow task, but each one is tied to a specific base model version and must be retrained when the operating system updates the model, so they carry a real maintenance cost. The framework also offers a built-in content tagging use case for topic and entity tagging without custom training.
Limitations and common mistakes
The most frequent error is treating the system model as a source of world knowledge. A model of this size can produce fluent but incorrect factual statements, so facts should come from tools or app data, not from the model alone. The second constraint is the small context window: long documents must be split, and long chat sessions eventually raise an exceeded-context error that the app has to handle.
| Symptom | Likely cause | Fix |
|---|---|---|
| Context size error | Transcript exceeds 4,096 tokens | Start a new session with a condensed summary |
| Invented facts | Question needs world knowledge | Supply data through a tool |
| Guardrail error on harmless text | Built-in safety filter triggered | Rephrase input and handle the error gracefully |
| Slow first response | Model not loaded into memory | Call prewarm before the user acts |
| Feature missing for some users | No availability check | Check availability and provide a fallback |
- Built-in guardrails filter both input and output; apps cannot disable them and should present a neutral message when they trigger.
- Output quality varies by language, so features should be tested in every supported locale.
- Model updates change behavior; prompts and adapters need regression tests after each major operating system release.
A plain-language summary
Newer iPhones, iPads and Macs carry a small AI model inside the operating system. The Apple Foundation Models framework is the doorway that lets any app use that model. Because the model lives on the device, a request never leaves the phone, works without internet and costs the developer nothing per use.
Think of it as a capable assistant who sits inside the device and is excellent at sorting, summarizing and filling in forms, but who has not read the whole internet. For broad questions, an app still needs a larger online model; for quick, private everyday tasks, the built-in model is often the simplest and cheapest choice.
An example from practice
A small team builds a personal expense app for iPhone. Users photograph receipts, and the app already extracts raw text with on-device text recognition. The team wants each receipt turned into a merchant name, a date, a total and one of twelve spending categories, without uploading financial data to any server.
The developers define a Receipt struct marked @Generable, constrain the category to an enum of twelve cases with @Guide, and pass the recognized text to a fresh LanguageModelSession for each receipt. Because a long receipt can approach the token limit, the app trims the text to price and total lines. A Tool looks up categories the user has assigned to the same merchant before, so the model follows personal habits.
The result is typed, validated data in about one second per receipt, with no server costs and no receipt leaving the device. On older iPhones without Apple Intelligence, the app detects the unavailable state and falls back to manual category selection.