@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/apple-on-device-ai/references/foundation-models.md

@@ -1,528 +1,418 @@
-# Foundation Models API Reference
-
-Complete reference for Apple's Foundation Models framework (iOS 26+ / macOS 26+).
-On-device language model optimized for Apple Silicon. No app-managed API key,
-model hosting, or network round trip for generation; still handle Apple
-Intelligence and system model asset availability.
+# Foundation Models reference
 
 ## Contents
 
-- [Framework Overview](#framework-overview)
-- [Availability Checking](#availability-checking)
-- [Use Cases](#use-cases)
-- [Session Management](#session-management)
-- [Generating Responses](#generating-responses)
-- [Structured Output with `@Generable`](#structured-output-with-generable)
-- [Tool Calling](#tool-calling)
-- [Error Handling](#error-handling)
-- [Generation Options](#generation-options)
-- [Safety and Guardrails](#safety-and-guardrails)
-- [Custom Adapters](#custom-adapters)
-- [Context Management](#context-management)
-- [Serialized Model Access](#serialized-model-access)
-- [Prompt Design Best Practices](#prompt-design-best-practices)
-- [Feedback](#feedback)
-
-## Framework Overview
-
-- On-device language model optimized for Apple Silicon
-- Context window: limited total token budget (input + output combined); check
-  `SystemLanguageModel.default.contextSize` for the current limit
-- Prefer `SystemLanguageModel.default.supportsLocale(_:)` before generation;
-  use `supportedLanguages` only when listing broad language support
-- Capabilities: Summarization, entity extraction, text understanding, short
-  dialog, creative content, content tagging
-- Limitations: Not suited for complex math, code generation, or factual accuracy
-
-### SystemLanguageModel Properties
-
-- `contextSize`: Returns the model's maximum context window in tokens
-- `supportedLanguages`: `Set<Locale.Language>` values the model supports
-- `supportsLocale(_ locale: Locale) -> Bool`: Preferred locale check before generating because it accounts for fallbacks
-
-## Availability Checking
-
-Always check before using. Never crash on unavailability.
+- [What the framework is for](#what-the-framework-is-for)
+- [SystemLanguageModel](#systemlanguagemodel)
+- [Availability and locale](#availability-and-locale)
+- [Use cases and guardrails](#use-cases-and-guardrails)
+- [Sessions](#sessions)
+- [Prewarming](#prewarming)
+- [Text responses](#text-responses)
+- [Generable types](#generable-types)
+- [Tools](#tools)
+- [Runtime schemas](#runtime-schemas)
+- [Handling errors](#handling-errors)
+- [Sampling and length](#sampling-and-length)
+- [Safety](#safety)
+- [Adapters](#adapters)
+- [Long conversations](#long-conversations)
+- [One coordinator for all calls](#one-coordinator-for-all-calls)
+- [Writing prompts](#writing-prompts)
+- [Sending feedback](#sending-feedback)
+
+## What the framework is for
+
+The framework gives apps the system language model on iOS 26+ and macOS 26+.
+Generation needs no key, hosting or network access from the app, but the app
+must handle Apple Intelligence being off and model assets not being present.
+
+Input and output share one context window; its size is
+`SystemLanguageModel.default.contextSize`.
+
+Good at: summaries, entity extraction, understanding and rewriting text, short
+dialog, creative writing, content tagging. Weak at: complex math, generating
+code, and anything that must be factually accurate.
+
+## SystemLanguageModel
+
+| Member | Meaning |
+|---|---|
+| `contextSize` | Maximum tokens in the context window |
+| `supportedLanguages` | `Set<Locale.Language>` the model supports |
+| `supportsLocale(_ locale: Locale) -> Bool` | Whether a locale works, including fallbacks; prefer this |
+| `isAvailable` | Quick `Bool` availability check |
+| `availability` | Detailed status with an unavailability reason |
+
+Use `supportsLocale(_:)` to decide whether to generate. Use
+`supportedLanguages` only to show which languages are broadly supported.
+
+## Availability and locale
 
 ```swift
+import Foundation
 import FoundationModels
 
-// Quick boolean check
-if SystemLanguageModel.default.isAvailable {
-    // Proceed
+enum AssistantRoute {
+    case generate(Locale)
+    case askToEnable
+    case waitForAssets
+    case fallback
 }
 
-// Detailed availability
-switch SystemLanguageModel.default.availability {
-case .available:
-    let candidates = [Locale.current] + Locale.preferredLanguages.map(Locale.init(identifier:))
-    guard let locale = candidates.first(where: SystemLanguageModel.default.supportsLocale) else {
-        // Route to fallback UI before generating
-        break
+func assistantRoute() -> AssistantRoute {
+    let model = SystemLanguageModel.default
+    switch model.availability {
+    case .available:
+        let candidates = [Locale.current]
+            + Locale.preferredLanguages.map(Locale.init(identifier:))
+        if let locale = candidates.first(where: model.supportsLocale) {
+            return .generate(locale)
+        }
+        return .fallback
+    case .unavailable(.appleIntelligenceNotEnabled):
+        return .askToEnable        // Settings > Apple Intelligence
+    case .unavailable(.modelNotReady):
+        return .waitForAssets      // downloading, or another temporary system reason
+    case .unavailable(.deviceNotEligible):
+        return .fallback
+    default:
+        return .fallback           // reasons added in future releases
     }
-    // Proceed with model usage
-case .unavailable(.appleIntelligenceNotEnabled):
-    // Guide user to Settings > Apple Intelligence
-case .unavailable(.modelNotReady):
-    // System model assets are downloading or unavailable for other system reasons
-case .unavailable(.deviceNotEligible):
-    // Device cannot run Apple Intelligence
-default:
-    // Graceful fallback for unknown or future unavailable reasons
 }
 ```
 
-## Use Cases
-
-Foundation Models supports specialized use cases:
+## Use cases and guardrails
 
 ```swift
-// General purpose (default)
-let model = SystemLanguageModel(useCase: .general, guardrails: .default)
-
-// Content tagging (optimized for categorization)
-let model = SystemLanguageModel(useCase: .contentTagging, guardrails: .default)
+let general = SystemLanguageModel(useCase: .general, guardrails: .default)
+let tagger = SystemLanguageModel(useCase: .contentTagging, guardrails: .default)
 ```
 
-## Session Management
+`.general` covers generation, summaries and dialog. `.contentTagging` is tuned
+for labelling and categorising text.
 
-### Creating Sessions
+## Sessions
 
 ```swift
-// Basic session (uses SystemLanguageModel.default)
+// Uses SystemLanguageModel.default
 let session = LanguageModelSession()
 
-// Session with system instructions
-let session = LanguageModelSession {
-    "You are a helpful cooking assistant."
-    "Focus on quick, healthy recipes."
+// Several instruction lines
+let coach = LanguageModelSession {
+    "You are a running coach."
+    "Answer in at most three sentences."
 }
 
-// Session with tools
-let session = LanguageModelSession(
-    tools: [weatherTool, recipeTool]
-) {
-    "You are a helpful assistant with access to tools."
+// A specific model plus tools
+let tagging = LanguageModelSession(model: tagger, tools: []) {
+    "Assign one topic label to each note."
 }
 
-// Session with specific model
-let model = SystemLanguageModel(useCase: .general, guardrails: .default)
-let session = LanguageModelSession(model: model, tools: []) {
-    "You are a helpful assistant."
-}
+// Continue a stored conversation
+let restored = LanguageModelSession(model: general, tools: [], transcript: storedTranscript)
 ```
 
-### Session Rules
-
-1. Sessions are stateful. Multi-turn conversations maintain context automatically.
-2. One request at a time per session. Check `session.isResponding` before new
-   requests.
-3. Prewarm with `session.prewarm()` before user interaction for faster first
-   response.
-4. Save and restore transcripts for session continuity:
-   `LanguageModelSession(model: model, tools: [], transcript: savedTranscript)`.
+- Sessions are stateful; each turn sees the earlier ones.
+- One request at a time; `isResponding` tells you if one is running.
+- Prewarm before use.
+- Save `session.transcript` to continue the conversation later.
 
-### Prewarming
+## Prewarming
 
 ```swift
-// Prewarm before user interaction
 session.prewarm()
-
-// Prewarm with a prompt prefix for faster specific responses
-session.prewarm(promptPrefix: Prompt("Summarize the following text:"))
+coach.prewarm(promptPrefix: Prompt("Plan a training week for"))
 ```
 
-## Generating Responses
+A prefix lets the system prepare for prompts that begin the same way.
 
-### Plain Text
+## Text responses
 
 ```swift
-// Simple text response
-let response = try await session.respond(to: "Summarize this article: \(text)")
-print(response.content) // String
-
-// With generation options
-let options = GenerationOptions(
-    sampling: .random(top: 40),
-    temperature: 0.7,
-    maximumResponseTokens: 512
-)
-let response = try await session.respond(to: prompt, options: options)
+let reply = try await coach.respond(to: "How should I taper before a 10K?")
+let text: String = reply.content
+
+let brief = try await coach.respond(to: "One tip for hills",
+                                    options: GenerationOptions(maximumResponseTokens: 80))
 ```
 
-### Streaming Text
+Streaming text:
 
 ```swift
-let stream = session.streamResponse(to: "Tell me a story")
-for try await snapshot in stream {
-    print(snapshot.content, terminator: "")
+let stream = coach.streamResponse(to: "Describe a tempo run")
+for try await partial in stream {
+    liveText = partial.content
 }
-
-// Or collect the full response
-let response = try await stream.collect()
+let complete = try await stream.collect()
 ```
 
-## Structured Output with `@Generable`
+## Generable types
 
-The `@Generable` macro creates compile-time JSON schemas for type-safe output.
-
-### Basic Usage
+`@Generable` turns a type into a JSON schema at compile time. Property types it
+accepts: `String`, `Int`, `Double`, `Float`, `Bool`, arrays of Generable or
+scalar values, optionals of those, nested `@Generable` structs and
+`@Generable` enums.
 
 ```swift
 @Generable
-struct Recipe {
-    @Guide(description: "The name of the recipe")
-    var name: String
-
-    @Guide(description: "A brief description of the dish")
-    var summary: String
-
-    @Guide(description: "Cooking steps", .count(3))
-    var steps: [String]
-
-    @Guide(description: "Prep time in minutes", .range(1...120))
-    var prepTime: Int
+enum Effort: String {
+    case easy, moderate, hard
 }
 
-let response = try await session.respond(
-    to: "Suggest a quick pasta recipe",
-    generating: Recipe.self
-)
-let recipe = response.content
-print(recipe.name)
-print(recipe.steps)
-```
-
-### Supported Types for `@Generable` Properties
-
-- `String`
-- `Int`, `Double`, `Float`
-- `Bool`
-- `[Element]` where Element is Generable or a supported scalar
-- `Optional<T>` where T is Generable or a supported scalar
-- Other `@Generable` structs (nested)
-- Enums conforming to `@Generable`
-
-### `@Guide` Constraints
-
-```swift
 @Generable
-struct ProductReview {
-    @Guide(description: "Product name")
-    var product: String
+struct WorkoutFeedback {
+    @Guide(.range(1...10))
+    var perceivedExertion: Int
 
-    @Guide(description: "Rating", .range(1...5))
-    var rating: Int
+    @Guide(.anyOf(["improving", "steady", "declining"]))
+    var trend: String
 
-    @Guide(description: "Sentiment", .anyOf(["positive", "neutral", "negative"]))
-    var sentiment: String
+    @Guide(description: "Actionable suggestions", .count(3))
+    var suggestions: [String]
 
-    @Guide(description: "Key themes", .count(3))
-    var themes: [String]
+    @Guide(.pattern(/^[A-Z][^.]*\.$/))
+    var headline: String
 
-    @Guide(description: "Summary in one sentence", .pattern(/^[A-Z].*\.$/))
-    var summary: String
+    @Guide(.constant("v1"))
+    var format: String
 
-    @Guide(description: "Always English", .constant("en"))
-    var language: String
+    var effort: Effort
 }
 ```
 
-Complete constraint list:
+Which guides apply to which types:
 
-| Constraint | Type | Purpose |
-|---|---|---|
-| `description:` | All | Natural language hint for generation |
-| `.anyOf([values])` | String | Restrict to enumerated values |
-| `.count(n)` | Array | Fixed array length |
-| `.minimumCount(n)` | Array | Minimum array length |
-| `.maximumCount(n)` | Array | Maximum array length |
-| `.range(min...max)` | Numeric | Closed numeric range |
-| `.minimum(n)` | Numeric | Lower bound |
-| `.maximum(n)` | Numeric | Upper bound |
-| `.constant(value)` | String | Always returns this value |
-| `.pattern(regex)` | String | Regex format enforcement |
-| `.element(guide)` | Array | Guide applied to each element |
+| Guide | Applies to |
+|---|---|
+| `description:` | Any property |
+| `.anyOf`, `.constant`, `.pattern` | `String` |
+| `.count`, `.minimumCount`, `.maximumCount`, `.element` | Arrays |
+| `.range`, `.minimum`, `.maximum` | Numbers |
 
-### Property Ordering
-
-Properties are generated in declaration order. Place foundational data before
-dependent data:
+Generation follows declaration order, and later fields are written with the
+earlier ones already in context. Order fields the way a person would reason:
 
 ```swift
 @Generable
-struct Summary {
-    var title: String       // Generated first
-    var keyPoints: [String] // Generated with title context
-    var conclusion: String  // Generated with full context
+struct RaceReport {
+    var headline: String       // first: sets the topic
+    var highlights: [String]   // then: details under that headline
+    var takeaway: String       // last: draws on both
 }
 ```
 
-### Streaming Structured Output
+Streaming a Generable type yields `PartiallyGenerated` values whose fields are
+all optional:
 
 ```swift
-let stream = session.streamResponse(
-    to: "Suggest a recipe",
-    generating: Recipe.self
-)
-for try await snapshot in stream {
-    // snapshot.content is Recipe.PartiallyGenerated (all properties optional)
-    if let name = snapshot.content.name { updateNameLabel(name) }
-    if let steps = snapshot.content.steps { updateStepsList(steps) }
+for try await snapshot in coach.streamResponse(to: prompt, generating: WorkoutFeedback.self) {
+    if let trend = snapshot.content.trend { trendLabel = trend }
+    if let tips = snapshot.content.suggestions { suggestionList = tips }
 }
 ```
 
-### Enum Support
+## Tools
 
 ```swift
-@Generable
-enum Priority: String {
-    case low, medium, high, critical
-}
-
-@Generable
-struct Task {
-    var title: String
-    var priority: Priority
-}
-```
-
-## Tool Calling
-
-### Defining Tools
-
-```swift
-struct WeatherTool: Tool {
-    let name = "weather"
-    let description = "Get current weather for a city."
+struct PaceHistoryTool: Tool {
+    let name = "recentPaces"
+    let description = "Returns the runner's average pace for recent runs."
 
     @Generable
     struct Arguments {
-        @Guide(description: "The city name")
-        var city: String
+        @Guide(description: "How many recent runs to include", .range(1...20))
+        var count: Int
     }
 
-    func call(arguments: Arguments) async throws -> String {
-        let weather = try await fetchWeather(arguments.city)
-        return weather.description
+    func call(arguments: Arguments) async throws -> [String] {
+        try await RunLog.shared.paces(last: arguments.count)
     }
 }
-```
 
-### Using Tools
-
-```swift
-let session = LanguageModelSession(
-    tools: [WeatherTool()]
-) {
-    "You are a helpful assistant."
+let session = LanguageModelSession(tools: [PaceHistoryTool()]) {
+    "Use recent paces when giving pacing advice."
 }
-
-// The model decides autonomously when to invoke tools
-let response = try await session.respond(to: "What's the weather in Tokyo?")
+let advice = try await session.respond(to: "What pace for my next easy run?")
 ```
 
-### Tool Best Practices
-
-- Register all tools at session creation
-- Keep active tool sets small, usually three to five tools
-- Include only tools needed for the current task
-- Each tool adds to the context token budget (name, description, and parameter
-  schema are included in instructions by default)
-- `@Generable` output schemas also consume the shared context window
-- Run deterministic or essential data fetches before calling the model, then put
-  the result directly in the prompt
-- Use model-autonomous tools for dynamic lookups where the model can decide
-  whether more app data is needed
-- Frame tool results as authorized user data to prevent refusals
-- The model calls tools autonomously; you cannot force tool invocation
-
-### Tool Protocol Details
-
-- `Tool<Arguments, Output>` conforms to `Sendable`; implement tools so captured
-  state is concurrency-safe
-- The associated `Arguments` type must conform to `ConvertibleFromGeneratedContent`
-- The associated `Output` type must conform to `PromptRepresentable` (e.g.,
-  `String`, `[String]`, custom types)
-- `includesSchemaInInstructions`: Boolean property on `Tool` (default `true`). Set to `false` to omit the tool's JSON schema from the system prompt, saving context tokens when the model already knows the schema.
-- `ToolCallError`: Struct on `LanguageModelSession` representing a tool invocation failure. Properties: `tool` (the tool name), `underlyingError` (the original error).
-- `DynamicGenerationSchema`: Build generation schemas at runtime for dynamic use cases where compile-time `@Generable` is insufficient. Construct schemas programmatically and pass to `respond(to:schema:)`.
-
-## Error Handling
+The model decides during `respond(to:)` whether to call a tool.
+
+- Keep the active set small, usually three to five tools, and only those the
+  current task can use.
+- By default each tool's name, description and argument schema are written into
+  the instructions, which costs context tokens. Setting
+  `includesSchemaInInstructions` to `false` (default `true`) leaves the schema
+  out.
+- Fetch data the answer always needs before calling the model and include it in
+  the prompt. Autonomous tool calls suit lookups that depend on the question.
+- A tool call cannot be forced.
+- `Tool` conforms to `Sendable`, so any state a tool captures must be
+  concurrency-safe.
+- `Arguments` conforms to `ConvertibleFromGeneratedContent` (a `@Generable`
+  struct does). `Output` conforms to `PromptRepresentable`: `String`,
+  `[String]` and your own conforming types work.
+- A failing tool surfaces as `LanguageModelSession.ToolCallError`, which holds
+  the `tool` and its `underlyingError`.
+
+## Runtime schemas
+
+When the shape is only known at runtime, build a `DynamicGenerationSchema` and
+pass the resulting schema to `respond(to:schema:)`:
 
 ```swift
-do {
-    let response = try await session.respond(to: prompt)
-} catch let error as LanguageModelSession.GenerationError {
-    switch error {
-    case .guardrailViolation:
-        // Content triggered safety filters; rephrase and retry
-    case .exceededContextWindowSize:
-        // Too many tokens; summarize earlier turns and create new session
-    case .concurrentRequests:
-        // Another request is already in progress on this session
-    case .rateLimited:
-        // Too many requests; back off and retry
-    case .unsupportedLanguageOrLocale:
-        // Current locale not supported by the model
-    case .unsupportedGuide:
-        // A @Guide constraint is not supported
-    case .assetsUnavailable:
-        // Model assets not available on device
-    case .decodingFailure:
-        // Failed to decode structured output
-    case .refusal(let refusal, _):
-        // Model refused the request
-        let explanation = try await refusal.explanation.content
-        print("Refused: \(explanation)")
-    default: break
-    }
+let fields = userChosenFields.map {
+    DynamicGenerationSchema.Property(name: $0, schema: DynamicGenerationSchema(type: String.self))
 }
+let form = DynamicGenerationSchema(name: "Form", properties: fields)
+let schema = try GenerationSchema(root: form, dependencies: [])
+let filled = try await session.respond(to: sourceText, schema: schema)
 ```
 
-## Generation Options
+## Handling errors
 
-```swift
-let options = GenerationOptions(
-    sampling: .greedy,              // Deterministic output
-    temperature: nil,               // Use default
-    maximumResponseTokens: 256      // Limit response length
-)
-
-// Random sampling with top-k
-let options = GenerationOptions(
-    sampling: .random(top: 40),
-    temperature: 0.7
-)
-
-// Random sampling with probability threshold
-let options = GenerationOptions(
-    sampling: .random(probabilityThreshold: 0.9)
-)
-```
+The `GenerationError` cases and the usual response are listed in SKILL.md. The
+recovery for each:
 
-Sampling modes accept an optional `seed` parameter for reproducible output:
-`.random(top: 40, seed: 42)`, `.random(probabilityThreshold: 0.9, seed: 42)`.
+- `guardrailViolation`: ask the user to rephrase, then retry.
+- `exceededContextWindowSize`: summarise the earlier turns into a new session
+  and continue there.
+- `rateLimited`: back off before retrying.
+- `refusal(let refusal, _)`: read the reason with
+  `try await refusal.explanation.content` and show it.
 
-## Safety and Guardrails
-
-### Guardrail Types
+## Sampling and length
 
 ```swift
-// Default guardrails (recommended)
-let model = SystemLanguageModel(useCase: .general, guardrails: .default)
-
-// Permissive content transformations (for text rewriting tasks)
-let model = SystemLanguageModel(
-    useCase: .general,
-    guardrails: .permissiveContentTransformations
-)
+let deterministic = GenerationOptions(sampling: .greedy)
+let defaultTemp = GenerationOptions(temperature: nil, maximumResponseTokens: 256)
+let topK = GenerationOptions(sampling: .random(top: 40))
+let nucleus = GenerationOptions(sampling: .random(probabilityThreshold: 0.9))
+let repeatable = GenerationOptions(sampling: .random(top: 40, seed: 7))
 ```
 
-### Safety Rules
+- `.greedy` always picks the most likely token, so output is deterministic.
+- `temperature: nil` keeps the system default.
+- `maximumResponseTokens` caps the reply length.
+- `.random(top:)` samples from the top k tokens; `.random(probabilityThreshold:)`
+  samples from the smallest set whose probability reaches the threshold.
+- Both random modes take `seed:` for reproducible output.
 
-- Guardrails are always enforced and cannot be disabled
-- Instructions take precedence over user prompts
-- Never include untrusted user content in instructions
-- Provide curated selections over free-form input when possible
-- Guardrails can produce false positives; handle gracefully
-- Frame tool results as authorized user data
+## Safety
 
-## Custom Adapters
+Guardrail settings:
 
-Load fine-tuned LoRA adapters for specialized model behavior:
+- `.default`: the recommended setting.
+- `.permissiveContentTransformations`: for rewriting or transforming text the
+  user supplied, where the default can be too strict.
 
-```swift
-// Requires com.apple.developer.foundation-model-adapter entitlement
-let adapter = try SystemLanguageModel.Adapter(name: "my-adapter")
-try await adapter.compile()
+Where you can, offer curated choices instead of free-form input. Keep user text
+out of instructions.
 
-let model = SystemLanguageModel(adapter: adapter, guardrails: .default)
-let session = LanguageModelSession(model: model)
-let response = try await session.respond(to: "Generate styled text")
-```
+## Adapters
 
-### Adapter Management
+Adapters are fine-tuned LoRA weights for the system model. They need the
+`com.apple.developer.foundation-model-adapter` entitlement.
 
 ```swift
-// Check compatible adapters
-let ids = SystemLanguageModel.Adapter.compatibleAdapterIdentifiers(name: "my-adapter")
+let adapter = try SystemLanguageModel.Adapter(name: "trail-guide")
+try await adapter.compile()
+let tuned = SystemLanguageModel(adapter: adapter, guardrails: .default)
+let session = LanguageModelSession(model: tuned)
 
-// Remove obsolete adapters
+let usable = SystemLanguageModel.Adapter.compatibleAdapterIdentifiers(name: "trail-guide")
 try SystemLanguageModel.Adapter.removeObsoleteAdapters()
 ```
 
-## Context Management
+`compatibleAdapterIdentifiers(name:)` lists adapter versions that match the
+installed system model; `removeObsoleteAdapters()` deletes the ones that no
+longer do.
 
-When conversations grow long:
+## Long conversations
 
-1. Monitor token usage against `SystemLanguageModel.default.contextSize`
-2. Use `SystemLanguageModel.default.tokenCount(for:)` to estimate usage
-3. Summarize earlier turns into new session instructions
-4. Create fresh sessions with summary context rather than overflowing
+A conversation grows until it no longer fits. Measure it against
+`contextSize`, estimate the cost of text with
+`SystemLanguageModel.default.tokenCount(for:)` (iOS 26.4+; `contextSize` is
+back-deployed to 26.0), and before it overflows, fold
+the history into a summary and start a fresh session with that summary in its
+instructions.
 
 ```swift
-if transcript.estimatedTokenCount > 3000 {
-    let summary = try await summarizeSession(session)
-    session = LanguageModelSession {
-        "Previous conversation summary: \(summary)"
-        "Continue helping the user."
+@available(iOS 26.4, macOS 26.4, visionOS 26.4, *)
+func continueOrCondense(_ session: LanguageModelSession,
+                        history: String) async throws -> LanguageModelSession {
+    let model = SystemLanguageModel.default
+    let used = try await model.tokenCount(for: history)
+    guard used > model.contextSize * 3 / 4 else { return session }
+
+    let summary = try await LanguageModelSession().respond(
+        to: "Summarise this conversation in five bullet points:\n\(history)"
+    ).content
+    return LanguageModelSession {
+        "You are a running coach."
+        "Earlier conversation, summarised: \(summary)"
     }
 }
 ```
 
-## Serialized Model Access
+The 75 percent threshold leaves room for the next reply; tune it to your
+typical answer length.
 
-When multiple parts of an app need the model:
+## One coordinator for all calls
+
+Route every request through one actor that owns the session, so two features
+never run the model at the same time and compete for the Neural Engine. Chain
+requests as shown in SKILL.md, because an actor alone does not serialise across
+`await`.
 
 ```swift
-actor FoundationModelCoordinator {
+actor CoachService {
     private var session: LanguageModelSession?
-
-    func respond(to prompt: String) async throws -> String {
-        if session == nil {
-            session = LanguageModelSession()
+    private var last: Task<Void, Never>?
+
+    func ask(_ prompt: String) async throws -> String {
+        let previous = last
+        let job = Task { () async throws -> String in
+            await previous?.value
+            let active = self.currentSession()
+            return try await active.respond(to: prompt).content
         }
-        guard let activeSession = session else {
-            throw FoundationModelError.sessionUnavailable
-        }
-        let response = try await activeSession.respond(to: prompt)
-        return response.content
+        last = Task { _ = try? await job.value }
+        return try await job.value
+    }
+
+    private func currentSession() -> LanguageModelSession {
+        if let session { return session }
+        let created = LanguageModelSession { "You are a running coach." }
+        session = created
+        return created
     }
 }
 ```
 
-Serialize all Foundation Model access through a single coordinator to prevent
-Neural Engine contention.
-
-## Prompt Design Best Practices
+## Writing prompts
 
-1. **Be concise.** The context window covers both input and output tokens.
-   Check `SystemLanguageModel.default.contextSize` for the current limit.
-2. **Use bracketed placeholders** in instructions: `[descriptive example]`.
-3. **Use "DO NOT" in all caps** for behavioral prohibitions.
-4. **Provide up to 5 few-shot examples** for consistent output.
-5. **Use length qualifiers:** "in a few words", "in three sentences".
-6. **Estimate token usage** with `SystemLanguageModel.default.tokenCount(for:)`
-   to avoid exceeding the context window.
+The rules in SKILL.md apply; in addition, estimate prompt size with
+`SystemLanguageModel.default.tokenCount(for:)` (iOS 26.4+) before sending long
+inputs.
 
-## Feedback
+## Sending feedback
 
-Log feedback for model improvement:
+Attach structured feedback to a report when output is wrong:
 
 ```swift
-let data = session.logFeedbackAttachment(
+let attachment = session.logFeedbackAttachment(
     sentiment: .negative,
     issues: [
-        LanguageModelFeedback.Issue(
-            category: .didNotFollowInstructions,
-            explanation: "Ignored the word count constraint"
-        )
+        LanguageModelFeedback.Issue(category: .incorrect,
+                                    explanation: "Recommended pace was faster than race pace.")
     ],
     desiredOutput: nil
 )
 ```
 
+The call returns data to include in a Feedback Assistant report.
+
 Issue categories: `.didNotFollowInstructions`, `.incorrect`,
 `.stereotypeOrBias`, `.suggestiveOrSexual`, `.tooVerbose`,
 `.triggeredGuardrailUnexpectedly`, `.unhelpful`, `.vulgarOrOffensive`.