Apple Foundation Models framework

Also known as: Foundation Models framework

On this page 7

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.

ComponentRolePractical note
SystemLanguageModelRepresents the on-device modelExposes availability and use case
LanguageModelSessionHolds instructions and transcriptOne session per task or conversation
Generable macroDefines a Swift type for typed outputEnables guided generation
Guide macroAdds constraints to propertiesRanges, counts, patterns, descriptions
Tool protocolLets the model call app codeReturns data the model then uses
GenerationOptionsSets sampling and temperatureGreedy sampling gives repeatable output
Core types of the Foundation Models framework

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 styleWhat the app receivesBest fit
Plain text responseA complete stringSummaries and short replies
Guided generationA typed Swift valueExtraction, tagging, form filling
Streamed snapshotsPartial values over timeInteractive interfaces with visible progress
Output styles and when each fits

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.

ApproachModel sourceMain strengthMain limitation
Foundation Models frameworkBuilt into the operating systemFree, private, typed Swift outputSmall model, Apple platforms only
Core MLModel bundled by the appAny converted model architectureApp size and conversion effort
llama.cppOpen-weight filesCross-platform and flexibleManual tuning and memory management
Cloud model APIRemote providerStrong reasoning and knowledgeCost, latency and data transfer
Comparison with related approaches

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 stateCauseRecommended app behavior
AvailableModel ready on a supported deviceEnable the feature normally
Device not eligibleHardware lacks Apple Intelligence supportHide the feature or offer a fallback
Apple Intelligence not enabledThe user has turned it offExplain the requirement briefly
Model not readyDownload or setup still in progressRetry later and show a waiting state
Availability states and recommended handling

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.

SymptomLikely causeFix
Context size errorTranscript exceeds 4,096 tokensStart a new session with a condensed summary
Invented factsQuestion needs world knowledgeSupply data through a tool
Guardrail error on harmless textBuilt-in safety filter triggeredRephrase input and handle the error gracefully
Slow first responseModel not loaded into memoryCall prewarm before the user acts
Feature missing for some usersNo availability checkCheck availability and provide a fallback
Typical problems, causes and fixes
  • 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.