/foundation-models

name: foundation-models
description: On-device LLM integration using Apple's Foundation Models framework. Use when implementing AI text generation, structured output, or tool calling.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Foundation Models

Integrate Apple's on-device LLM into your apps for privacy-preserving AI features. Companion references: **safety-and-guardrails.md** (model limits, prompt design, the four-layer safety stack), **models-and-agents.md** (Private Cloud Compute, `LanguageModel` protocol, vision input, `DynamicProfile` agentic sessions — the iOS 27 wave), and **utilities-package.md** (Apple's open-source utilities package: OpenAI-compatible endpoints, just-in-time Skills, history compression).

When This Skill Activates

• User wants AI text generation features
• User needs structured data from natural language
• User asks about prompting or LLM integration
• User wants to implement AI assistants or agentic features (tool loops, multi-profile sessions)
• User needs content summarization or extraction
• User asks about Private Cloud Compute, guardrails, or model safety

Model Fit — Check Before Building

The on-device model is ~3B parameters (2-bit quantized): built for **summarization, extraction, classification, tagging, revision, short chat** — not math, code generation, facts, or world knowledge (WWDC25 248). For capability boundaries, prompt-design rules, and the safety stack, read `safety-and-guardrails.md` first. For anything bigger, `PrivateCloudComputeLanguageModel` (32k context, reasoning) and third-party backends are in `models-and-agents.md`.

Quick Start

1. Check Availability

import FoundationModels

struct IntelligentView: View {
    private var model = SystemLanguageModel.default

    var body: some View {
        switch model.availability {
        case .available:
            ContentView()
        case .unavailable(.deviceNotEligible):
            UnsupportedDeviceView()
        case .unavailable(.appleIntelligenceNotEnabled):
            EnableIntelligenceView()
        case .unavailable(.modelNotReady):
            ModelDownloadingView()
        case .unavailable(let reason):
            ErrorView(reason: reason)
        }
    }
}

2. Create a Session

// Simple session
let session = LanguageModelSession()

// Session with instructions
let session = LanguageModelSession(instructions: """
    You are a helpful cooking assistant.
    Provide concise, practical advice for home cooks.
    """)

3. Generate Response

let response = try await session.respond(to: "What's a quick dinner idea?")
print(response.content)

Prompt Engineering Best Practices

The Instruction Formula

Instructions set the model's persona and constraints. They're prioritized over prompts.

[Role] + [Task] + [Style] + [Safety]

**Example:**

let instructions = """
    You are a fitness coach specializing in home workouts.
    Help users create exercise routines based on their equipment and goals.
    Keep responses under 100 words and use bullet points for exercises.
    Decline requests for medical advice and suggest consulting a doctor.
    """

Instruction Components

| Component | Purpose | Example | |-----------|---------|---------| | **Role** | Define persona | "You are a travel expert" | | **Task** | What to do | "Help plan itineraries" | | **Style** | Output format | "Use bullet points, be concise" | | **Safety** | Boundaries | "Don't provide medical advice" |

Effective Prompts

Prompts are user inputs. Make them:

| Principle | Bad | Good | |-----------|-----|------| | **Specific** | "Help with cooking" | "Suggest a 30-minute vegetarian dinner" | | **Constrained** | "Tell me about dogs" | "Describe Golden Retrievers in 3 sentences" | | **Focused** | "I need help with many things" | "What ingredients substitute for eggs in baking?" |

Prompt Patterns

**Question Pattern:**

let prompt = "What are three ways to reduce food waste at home?"

**Command Pattern:**

let prompt = "Create a weekly meal plan for a family of four, budget-friendly."

**Extraction Pattern:**

let prompt = """
    Extract the following from this email:
    - Sender name
    - Meeting date
    - Action items

    Email: \(emailContent)
    """

**Transformation Pattern:**

let prompt = "Rewrite this text to be more formal: \(casualText)"

Structured Output with @Generable

Get typed Swift data instead of raw strings.

Define Generable Types

@Generable(description: "A recipe suggestion")
struct Recipe {
    var name: String

    @Guide(description: "Cooking time in minutes", .range(5...180))
    var cookingTime: Int

    @Guide(description: "Difficulty level", .options(["Easy", "Medium", "Hard"]))
    var difficulty: String

    @Guide(description: "List of ingredients", .count(3...15))
    var ingredients: [String]

    @Guide(description: "Step-by-step instructions")
    var instructions: [String]
}

@Guide Constraints

| Constraint | Use Case | Example | |------------|----------|---------| | `.range(min...max)` | Numeric bounds | `.range(1...100)` | | `.options([...])` | Enum-like choices | `.options(["Low", "Medium", "High"])` | | `.count(n)` | Exact array length | `.count(5)` | | `.count(min...max)` | Array length range | `.count(3...10)` |

Two Rules the Macro Hides (WWDC25 301)

• **Don't re-describe your schema in the prompt.** The framework injects your `@Generable` type's details "in a specific format that the model has been trained on" — hand-written "respond in JSON with fields…" text duplicates it and wastes tokens. Constrained decoding masks invalid tokens per-step, so structural correctness is guaranteed, not prompted for.
• **Property order is generation order.** "Properties are generated in the order