FoundationModels: On-Device LLM (iOS 26)
Patterns for integrating Apple's on-device language model into apps using the FoundationModels framework. Covers text generation, structured output with @Generable, custom tool calling, and snapshot streaming — all running on-device for privacy and offline support.
When to Activate
- Building AI-powered features using Apple Intelligence on-device
- Generating or summarizing text without cloud dependency
- Extracting structured data from natural language input
- Implementing custom tool calling for domain-specific AI actions
- Streaming structured responses for real-time UI updates
- Need privacy-preserving AI (no data leaves the device)
Core Pattern — Availability Check
Always check model availability before creating a session:
Core Pattern — Basic Session
Key points for instructions:
- Define the model's role ("You are a mentor")
- Specify what to do ("Help extract calendar events")
- Set style preferences ("Respond as briefly as possible")
- Add safety measures ("Respond with 'I can't help with that' for dangerous requests")
Core Pattern — Guided Generation with @Generable
Generate structured Swift types instead of raw strings:
1. Define a Generable Type
2. Request Structured Output
Supported @Guide Constraints
.range(0...20)— numeric range.count(3)— array element countdescription:— semantic guidance for generation
Core Pattern — Tool Calling
Let the model invoke custom code for domain-specific tasks:
1. Define a Tool
2. Create Session with Tools
3. Handle Tool Errors
Core Pattern — Snapshot Streaming
Stream structured responses for real-time UI with PartiallyGenerated types:
SwiftUI Integration
Key Design Decisions
Best Practices
- Always check
model.availabilitybefore creating a session — handle all unavailability cases - Use
instructionsto guide model behavior — they take priority over prompts - Check
isRespondingbefore sending a new request — sessions handle one request at a time - Access
response.contentfor results — not.output - Break large inputs into chunks — 4,096 token limit applies to instructions + prompt + output combined
- Use
@Generablefor structured output — stronger guarantees than parsing raw strings - Use
GenerationOptions(temperature:)to tune creativity (higher = more creative) - Monitor with Instruments — use Xcode Instruments to profile request performance
Anti-Patterns to Avoid
- Creating sessions without checking
model.availabilityfirst - Sending inputs exceeding the 4,096 token context window
- Attempting concurrent requests on a single session
- Using
.outputinstead of.contentto access response data - Parsing raw string responses when
@Generablestructured output would work - Building complex multi-step logic in a single prompt — break into multiple focused prompts
- Assuming the model is always available — device eligibility and settings vary
When to Use
- On-device text generation for privacy-sensitive apps
- Structured data extraction from user input (forms, natural language commands)
- AI-assisted features that must work offline
- Streaming UI that progressively shows generated content
- Domain-specific AI actions via tool calling (search, compute, lookup)


