Foundation Models
Apple's on-device AI framework providing access to a 3B parameter language model for summarization, extraction, classification, and content generation. Runs entirely on-device with no network required.
Overview
Foundation Models enable intelligent text processing directly on device without server round-trips, user data sharing, or network dependencies. The core principle: leverage on-device AI for specific, contained tasks (not for general knowledge).
Reference Loading Guide
ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.
| Reference |
Load When |
| Getting Started |
Setting up LanguageModelSession, checking availability, basic prompts |
| Structured Output |
Using @Generable for type-safe responses, @Guide constraints |
| Tool Calling |
Integrating external data (weather, contacts, MapKit) via Tool protocol |
| Streaming |
AsyncSequence for progressive UI updates, PartiallyGenerated types |
| Troubleshooting |
Context overflow, guardrails, errors, anti-patterns |
Core Workflow
- Check availability with
SystemLanguageModel.default.availability
- Create
LanguageModelSession with optional instructions
- Choose output type: plain String or @Generable struct
- Use streaming for long generations (>1 second)
- Handle errors: context overflow, guardrails, unsupported language
Model Capabilities
| Use Case |
Foundation Models? |
Alternative |
| Summarization |
Yes |
- |
| Extraction (key info) |
Yes |
- |
| Classification |
Yes |
- |
| Content tagging |
Yes (built-in adapter) |
- |
| World knowledge |
No |
ChatGPT, Claude, Gemini |
| Complex reasoning |
No |
Server LLMs |
Platform Requirements
- iOS 26+, macOS 26+, iPadOS 26+, visionOS 26+
- Apple Intelligence-enabled device (iPhone 15 Pro+, M1+ iPad/Mac)
- User opted into Apple Intelligence
Common Mistakes
Using Foundation Models for world knowledge — The 3B model is trained for on-device tasks only. It won't know current events, specific facts, or "who is X". Use ChatGPT/Claude for that. Keep prompts to: summarizing user's own content, extracting info, classifying text.
Blocking the main thread — LanguageModelSession calls must run on a background thread or async context. Blocking the main thread locks UI. Always use Task { } or background queue.
Ignoring context overflow — The model has finite context. If the user pastes a 50KB document, it will fail silently or truncate. Check input length and trim/truncate proactively.
Forgetting to check availability — Not all devices support Foundation Models. Check SystemLanguageModel.default.availability before using. Graceful degradation is required.
Ignoring guardrails — The model won't answer harmful queries. Instead of fighting it, design prompts that respect safety guidelines. Rephrasing requests usually works.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: foundation-models-33description: Use when implementing on-device AI with Apple's Foundation Models framework (iOS 26+), building summarization/extraction/classification features, or using @Generable for type-safe structured output.4---56# Foundation Models78Apple's on-device AI framework providing access to a 3B parameter language model for summarization, extraction, classification, and content generation. Runs entirely on-device with no network required.910## Overview1112Foundation Models enable intelligent text processing directly on device without server round-trips, user data sharing, or network dependencies. The core principle: leverage on-device AI for specific, contained tasks (not for general knowledge).1314## Reference Loading Guide1516**ALWAYS load reference files if there is even a small chance the content may be required.** It's better to have the context than to miss a pattern or make a mistake.1718| Reference | Load When |19|-----------|-----------|20| **[Getting Started](references/getting-started.md)** | Setting up LanguageModelSession, checking availability, basic prompts |21| **[Structured Output](references/structured-output.md)** | Using `@Generable` for type-safe responses, `@Guide` constraints |22| **[Tool Calling](references/tool-calling.md)** | Integrating external data (weather, contacts, MapKit) via Tool protocol |23| **[Streaming](references/streaming.md)** | AsyncSequence for progressive UI updates, PartiallyGenerated types |24| **[Troubleshooting](references/troubleshooting.md)** | Context overflow, guardrails, errors, anti-patterns |2526## Core Workflow27281. Check availability with `SystemLanguageModel.default.availability`292. Create `LanguageModelSession` with optional instructions303. Choose output type: plain String or @Generable struct314. Use streaming for long generations (>1 second)325. Handle errors: context overflow, guardrails, unsupported language3334## Model Capabilities3536| Use Case | Foundation Models? | Alternative |37|----------|-------------------|-------------|38| Summarization | Yes | - |39| Extraction (key info) | Yes | - |40| Classification | Yes | - |41| Content tagging | Yes (built-in adapter) | - |42| World knowledge | No | ChatGPT, Claude, Gemini |43| Complex reasoning | No | Server LLMs |4445## Platform Requirements4647- iOS 26+, macOS 26+, iPadOS 26+, visionOS 26+48- Apple Intelligence-enabled device (iPhone 15 Pro+, M1+ iPad/Mac)49- User opted into Apple Intelligence5051## Common Mistakes52531. **Using Foundation Models for world knowledge** — The 3B model is trained for on-device tasks only. It won't know current events, specific facts, or "who is X". Use ChatGPT/Claude for that. Keep prompts to: summarizing user's own content, extracting info, classifying text.54552. **Blocking the main thread** — LanguageModelSession calls must run on a background thread or async context. Blocking the main thread locks UI. Always use `Task { }` or background queue.56573. **Ignoring context overflow** — The model has finite context. If the user pastes a 50KB document, it will fail silently or truncate. Check input length and trim/truncate proactively.58594. **Forgetting to check availability** — Not all devices support Foundation Models. Check `SystemLanguageModel.default.availability` before using. Graceful degradation is required.60615. **Ignoring guardrails** — The model won't answer harmful queries. Instead of fighting it, design prompts that respect safety guidelines. Rephrasing requests usually works.6263---64> Converted and distributed by [TomeVault](https://tomevault.io/claim/johnrogers) — claim your Tome and manage your conversions.65<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io