@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/apple-on-device-ai/SKILL.md

@@ -28,7 +28,8 @@ Use this decision tree to pick the right framework for your use case.
 
 **When to use:** Text generation, summarization, entity extraction, structured
 output, and short dialog on iOS 26+ / macOS 26+ devices with Apple Intelligence
-enabled. Zero setup -- no API keys, no network, no model downloads.
+enabled. No app-managed API key, network round trip, or model hosting; still
+handle system model asset readiness.
 
 **Best for:**
 - Generating text or structured data with `@Generable` types
@@ -77,7 +78,7 @@ deployments needing broad device support.
 
 | Scenario | Framework |
 |---|---|
-| Text generation, zero setup (iOS 26+) | Foundation Models |
+| Text generation on Apple Intelligence devices (iOS 26+) | Foundation Models |
 | Structured output from on-device LLM | Foundation Models (`@Generable`) |
 | Image classification, object detection | Core ML |
 | Custom model from PyTorch/TensorFlow | Core ML + coremltools |
@@ -94,7 +95,8 @@ On-device language model optimized for Apple Silicon. Available on devices
 supporting Apple Intelligence (iOS 26+, macOS 26+).
 
 - Token budget covers input + output; check `contextSize` for the limit
-- Check `supportedLanguages` for supported locales
+- Resolve locale before generation by checking `supportsLocale(_:)` against
+  `Locale.current` and preferred fallbacks; do not raw-match `supportedLanguages`
 - Guardrails always enforced, cannot be disabled
 
 ### Availability Checking (Required)
@@ -106,15 +108,19 @@ import FoundationModels
 
 switch SystemLanguageModel.default.availability {
 case .available:
+    guard SystemLanguageModel.default.supportsLocale(Locale.current) else {
+        // Use locale fallback before generating
+        break
+    }
     // Proceed with model usage
 case .unavailable(.appleIntelligenceNotEnabled):
     // Guide user to enable Apple Intelligence in Settings
 case .unavailable(.modelNotReady):
-    // Model is downloading; show loading state
+    // System model assets are not ready; show loading state
 case .unavailable(.deviceNotEligible):
     // Device cannot run Apple Intelligence; use fallback
-default:
-    // Graceful fallback for any other reason
+case .unavailable(let reason):
+    // Unknown or future unavailable reason; use fallback and log reason
 }
 ```
 
@@ -143,7 +149,7 @@ Key rules:
 - Call `session.prewarm()` before user interaction for faster first response
 - Save/restore transcripts: `LanguageModelSession(model: model, tools: [], transcript: savedTranscript)`
 
-### Structured Output with @Generable
+### Structured Output with `@Generable`
 
 The `@Generable` macro creates compile-time schemas for type-safe output:
 
@@ -167,7 +173,7 @@ let response = try await session.respond(
 print(response.content.name)
 ```
 
-#### @Guide Constraints
+#### `@Guide` Constraints
 
 | Constraint | Purpose |
 |---|---|
@@ -217,7 +223,10 @@ struct WeatherTool: Tool {
 }
 ```
 
-Register tools at session creation. The model invokes them autonomously.
+Register only necessary tools at session creation. `Tool` is `Sendable`; tool
+descriptors and `@Generable` schemas consume the shared context window. The
+model chooses when to call tools, so prefetch deterministic required data into
+the prompt and reserve autonomous tools for dynamic lookups.
 
 ### Error Handling
 
@@ -340,28 +349,11 @@ mlmodel.save("Model.mlpackage")
 | W8A8 (weights+activations) | ~4x | Low | ANE (A17 Pro/M4+) |
 | Pruning 75% | ~4x | Medium | CPU/ANE |
 
-### Swift Integration
-
-```swift
-let config = MLModelConfiguration()
-config.computeUnits = .all
-let model = try MLModel(contentsOf: modelURL, configuration: config)
-
-// Async prediction (iOS 17+)
-let output = try await model.prediction(from: input)
-```
-
-### MLTensor (iOS 18+)
-
-Swift type for multidimensional array operations:
+### Boundary with `coreml`
 
-```swift
-import CoreML
-
-let tensor = MLTensor([1.0, 2.0, 3.0, 4.0])
-let reshaped = tensor.reshaped(to: [2, 2])
-let result = tensor.softmax()
-```
+This skill owns Python-side conversion, compression, profiling, and framework
+selection. Use the sibling `coreml` skill for Swift app integration, prediction
+APIs, runtime configuration, Vision request wiring, and detailed model loading.
 
 > See [references/coreml-conversion.md](references/coreml-conversion.md) for the
 > full conversion pipeline and [references/coreml-optimization.md](references/coreml-optimization.md)
@@ -377,23 +369,16 @@ Apple Silicon via unified memory architecture.
 ```swift
 import MLX
 import MLXLLM
+import MLXLMCommon
+import MLXLMHFAPI
 
-let config = ModelConfiguration(id: "mlx-community/Mistral-7B-Instruct-v0.3-4bit")
-let model = try await LLMModelFactory.shared.loadContainer(configuration: config)
-
-try await model.perform { context in
-    let input = try await context.processor.prepare(
-        input: UserInput(prompt: "Hello")
-    )
-    let stream = try generate(
-        input: input,
-        parameters: GenerateParameters(temperature: 0.0),
-        context: context
-    )
-    for await part in stream {
-        print(part.chunk ?? "", terminator: "")
-    }
-}
+let container = try await LLMModelFactory.shared.loadContainer(
+    from: HubClient.default,
+    using: TokenizersLoader(),
+    configuration: .init(id: "mlx-community/Qwen3-4B-4bit")
+)
+let session = ChatSession(container)
+print(try await session.respond(to: "Hello"))
 ```
 
 ### Model Selection by Device
@@ -408,10 +393,12 @@ try await model.perform { context in
 ### Memory Management
 
 1. Never exceed 60% of total RAM on iOS
-2. Set GPU cache limits: `MLX.GPU.set(cacheLimit: 512 * 1024 * 1024)`
-3. Unload models on app backgrounding
+2. Set MLX cache limits: `Memory.cacheLimit = 512 * 1024 * 1024`
+3. Unload MLX and llama.cpp models on backgrounding or memory pressure; for MLX,
+   also call `Memory.clearCache()` after generation-heavy phases
 4. Use "Increased Memory Limit" entitlement for larger models
-5. Physical device required (no simulator support for Metal GPU)
+5. Validate MLX Swift and llama.cpp on physical Apple Silicon; Simulator cannot
+   exercise Metal-dependent inference, memory, or performance
 
 > See [references/mlx-swift.md](references/mlx-swift.md) for full MLX Swift
 > patterns and llama.cpp integration.
@@ -442,6 +429,11 @@ actor ModelCoordinator {
 }
 ```
 
+For custom Core ML models, name only the conversion/optimization handoff here:
+send Swift app integration, model loading, Vision wiring, and prediction
+lifecycle to `coreml`. Keep private user content, such as journals, on device
+unless product explicitly opts into a nonlocal fallback.
+
 ## Performance Best Practices
 
 1. Run outside debugger for accurate benchmarks (Xcode: Cmd-Opt-R, uncheck
@@ -450,14 +442,14 @@ actor ModelCoordinator {
 3. Pre-compile Core ML models to `.mlmodelc` for faster loading
 4. Use EnumeratedShapes over RangeDim for Neural Engine optimization
 5. Use 4-bit palettization for best Neural Engine memory/latency gains
-6. Batch Vision framework requests in a single `perform()` call
-7. Use async prediction (iOS 17+) in Swift concurrency contexts
-8. Neural Engine (Core ML) is most energy-efficient for compatible operations
+6. Hand off detailed Vision, Natural Language, and Swift Core ML runtime
+   integration to the sibling framework skills
 
 ## Common Mistakes
 
-1. **No availability check.** Calling `LanguageModelSession()` without checking
-   `SystemLanguageModel.default.availability` crashes on unsupported devices.
+1. **No availability check.** Starting generation without checking
+   `SystemLanguageModel.default.availability` leaves unsupported devices with
+   failures instead of fallback UI.
 2. **No fallback UI.** Users on pre-iOS 26 or devices without Apple Intelligence
    see nothing. Always provide a graceful degradation path.
 3. **Exceeding the context window.** The token budget covers input + output.
@@ -471,8 +463,9 @@ actor ModelCoordinator {
 7. **Using neuralnetwork format.** Always use `mlprogram` (.mlpackage) for new
    Core ML models. The legacy neuralnetwork format is deprecated.
 8. **Exceeding 60% RAM on iOS (MLX Swift).** Large models cause OOM kills.
-9. **Running MLX in simulator.** MLX requires Metal GPU -- use physical devices.
-10. **Not unloading models on background.** Unload in `scenePhase == .background`.
+9. **Trusting MLX simulator results.** Validate Metal-dependent behavior on
+   physical devices; Simulator is only a UI/control-flow smoke test.
+10. **Not clearing MLX caches.** Pair model unload with `Memory.clearCache()`.
 
 ## Review Checklist
 
@@ -480,21 +473,19 @@ actor ModelCoordinator {
 - [ ] Foundation Models: availability checked before every API call
 - [ ] Foundation Models: graceful fallback when model unavailable
 - [ ] Foundation Models: session prewarm called before user interaction
-- [ ] Foundation Models: @Generable properties in logical generation order
+- [ ] Foundation Models: `@Generable` properties in logical generation order
 - [ ] Foundation Models: token budget accounted for (check `contextSize`)
 - [ ] Core ML: model format is mlprogram (.mlpackage) for iOS 15+
-- [ ] Core ML: model.eval() called before tracing/exporting PyTorch models
-- [ ] Core ML: minimum_deployment_target set explicitly
-- [ ] Core ML: model accuracy validated after compression
+- [ ] Core ML: conversion, deployment target, and compression validated
 - [ ] MLX Swift: model size appropriate for target device RAM
-- [ ] MLX Swift: GPU cache limits set, models unloaded on backgrounding
+- [ ] MLX Swift: cache limits set, caches cleared, models unloaded
 - [ ] All model access serialized through coordinator actor
 - [ ] Concurrency: model types and tool implementations are `Sendable`-conformant or `@MainActor`-isolated
 - [ ] Physical device testing performed (not simulator)
 
 ## References
 
-- [Foundation Models API](references/foundation-models.md) -- LanguageModelSession, @Generable, tool calling, prompt design
+- [Foundation Models API](references/foundation-models.md) -- LanguageModelSession, `@Generable`, tool calling, prompt design
 - [Core ML Conversion](references/coreml-conversion.md) -- Model conversion from PyTorch, TensorFlow, other frameworks
 - [Core ML Optimization](references/coreml-optimization.md) -- Quantization, palettization, pruning, performance tuning
 - [MLX Swift & llama.cpp](references/mlx-swift.md) -- MLX Swift patterns, llama.cpp integration, memory management

package/pipeline/skills/shared/external/apple-on-device-ai/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "apple-on-device-ai",
+  "evals": [
+    {
+      "id": 0,
+      "name": "foundation-models-tool-calling-plan",
+      "prompt": "I'm adding an iOS 26 meal-planning feature that uses Apple's on-device Foundation Models to return a typed MealPlan, call a pantry lookup tool, stream partial results into SwiftUI, and fall back when Apple Intelligence is unavailable. Sketch the implementation plan and review checklist for another engineer.",
+      "expected_output": "A Foundation Models implementation outline that is availability-safe, locale-aware, schema-conscious, tool-calling-aware, and ready for SwiftUI streaming without overclaiming model readiness.",
+      "files": [],
+      "expectations": [
+        "Checks `SystemLanguageModel.default.availability` before generation and handles `appleIntelligenceNotEnabled`, `modelNotReady`, and `deviceNotEligible` with fallback UI.",
+        "Uses `LanguageModelSession`, `@Generable`, concise `@Guide` constraints, and structured streaming with partial generated content.",
+        "Prefers `supportsLocale(_:)` for locale gating and accounts for the shared input/output context window with `contextSize` or token counting.",
+        "Defines a small set of `Sendable` tools at session creation, notes that tool schemas consume context, and does not promise forced tool invocation.",
+        "Covers generation error handling for guardrails, context overflow, concurrent requests, unsupported guide or locale, assets unavailable, refusals, and rate limiting."
+      ]
+    },
+    {
+      "id": 1,
+      "name": "coreml-conversion-optimization-review",
+      "prompt": "Review this conversion plan before I hand it to an ML engineer: export a PyTorch vision transformer straight from training mode, convert it to a `.mlmodel` neuralnetwork with dynamic RangeDim inputs, quantize everything to INT4, and profile with MLComputePlan on iOS 17.0. Target devices are iPhone 15 Pro and M4 iPad.",
+      "expected_output": "A correction-focused Core ML conversion review that replaces stale or risky guidance with modern mlprogram, explicit deployment target, shape, compression, and profiling advice.",
+      "files": [],
+      "expectations": [
+        "Requires `model.eval()` before tracing/export and recommends validating outputs against the source model after conversion.",
+        "Uses mlprogram `.mlpackage` for new models with an explicit `minimum_deployment_target` instead of legacy neuralnetwork `.mlmodel` output.",
+        "Prefers `EnumeratedShapes` over broad `RangeDim` when valid shapes are known, especially for Neural Engine performance.",
+        "Warns that compression must be accuracy-tested and should avoid blindly quantizing every tensor.",
+        "Corrects `MLComputePlan` availability to iOS 17.4+ and distinguishes profiling from Swift app integration details."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "backend-selection-boundary",
+      "prompt": "We have a private journaling app that needs summarization on iOS 26 when possible, an open-source LLM fallback for some Apple Silicon devices, and a custom sentiment classifier we already trained. Decide which Apple on-device AI stack belongs to each piece, and call out what should be delegated to the sibling Core ML integration skill rather than explained here.",
+      "expected_output": "A boundary-aware backend selection answer that routes text generation to Foundation Models, custom classifier deployment to Core ML conversion/optimization, open-source fallback to MLX Swift or llama.cpp, and detailed Swift Core ML integration to the sibling Core ML skill.",
+      "files": [],
+      "expectations": [
+        "Selects Foundation Models for on-device summarization when Apple Intelligence is available and includes fallback behavior for unsupported devices.",
+        "Routes the trained sentiment classifier through Core ML conversion and optimization guidance rather than treating it as a Foundation Models prompt.",
+        "Chooses MLX Swift or llama.cpp for open-source LLM fallback based on Apple Silicon throughput, GGUF compatibility, device memory, and cross-platform needs.",
+        "Mentions MLX memory limits, background unloading, and physical-device validation for Metal-dependent behavior.",
+        "Keeps detailed Swift Core ML app integration, Vision request wiring, and model loading code as a handoff to the sibling Core ML skill."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/apple-on-device-ai/references/coreml-conversion.md

@@ -1,6 +1,10 @@
 # Core ML Model Conversion Reference
 
 Complete reference for converting models to Core ML format using coremltools.
+Use this reference for Python-side export, conversion, deployment-target,
+shape, and compression decisions. For Swift app runtime wiring, hand off to the
+sibling `coreml` skill; in conversion reviews, describe runtime availability in
+prose unless the user explicitly asks for Swift integration code.
 
 ## Contents
 
@@ -31,7 +35,9 @@ Complete reference for converting models to Core ML format using coremltools.
 pip install coremltools
 ```
 
-Current version: 9.0 (November 2025). Requires Python 3.10-3.13.
+Use a fresh virtual environment and verify the wheel matrix for your Python and
+source-framework versions. The 9.0 release publishes wheels through CPython
+3.13 and adds iOS 26 / macOS 26 deployment targets.
 
 ## Architecture Overview
 

package/pipeline/skills/shared/external/apple-on-device-ai/references/coreml-optimization.md

@@ -2,6 +2,9 @@
 
 Complete reference for optimizing Core ML models: quantization, palettization,
 pruning, performance tuning, and profiling.
+Keep conversion/optimization handoffs focused on Python-side tooling and
+profiling decisions. Defer Swift prediction/runtime wiring to the sibling
+`coreml` skill unless the user explicitly asks for app integration code.
 
 ## Contents
 
@@ -308,7 +311,7 @@ let matmulResult = tensorA.matmul(tensorB)
    compilation
 2. Cache compiled models to a fixed location after `MLModel.compileModel(at:)`
 3. Use `bisect_model()` for very large models that are slow to load
-4. Use `MLComputePlan` (iOS 17+) for programmatic profiling
+4. Use `MLComputePlan` (iOS 17.4+) for programmatic profiling
 
 ## Profiling
 

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

@@ -1,7 +1,9 @@
 # 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 API keys, no network, no cost.
+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.
 
 ## Contents
 
@@ -10,7 +12,7 @@ On-device language model optimized for Apple Silicon. No API keys, no network, n
 - [Use Cases](#use-cases)
 - [Session Management](#session-management)
 - [Generating Responses](#generating-responses)
-- [Structured Output with @Generable](#structured-output-with-generable)
+- [Structured Output with `@Generable`](#structured-output-with-generable)
 - [Tool Calling](#tool-calling)
 - [Error Handling](#error-handling)
 - [Generation Options](#generation-options)
@@ -26,7 +28,8 @@ On-device language model optimized for Apple Silicon. No API keys, no network, n
 - 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
-- Check `SystemLanguageModel.default.supportedLanguages` for supported locales
+- 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
@@ -34,8 +37,8 @@ On-device language model optimized for Apple Silicon. No API keys, no network, n
 ### SystemLanguageModel Properties
 
 - `contextSize`: Returns the model's maximum context window in tokens
-- `supportedLanguages`: Array of locale identifiers the model supports
-- `supportsLocale(_ locale: Locale) -> Bool`: Check if a specific locale is supported before generating
+- `supportedLanguages`: `Set<Locale.Language>` values the model supports
+- `supportsLocale(_ locale: Locale) -> Bool`: Preferred locale check before generating because it accounts for fallbacks
 
 ## Availability Checking
 
@@ -52,15 +55,20 @@ if SystemLanguageModel.default.isAvailable {
 // 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
+    }
     // Proceed with model usage
 case .unavailable(.appleIntelligenceNotEnabled):
     // Guide user to Settings > Apple Intelligence
 case .unavailable(.modelNotReady):
-    // Model downloading; show progress indicator
+    // System model assets are downloading or unavailable for other system reasons
 case .unavailable(.deviceNotEligible):
     // Device cannot run Apple Intelligence
 default:
-    // Graceful fallback
+    // Graceful fallback for unknown or future unavailable reasons
 }
 ```
 
@@ -154,7 +162,7 @@ for try await snapshot in stream {
 let response = try await stream.collect()
 ```
 
-## Structured Output with @Generable
+## Structured Output with `@Generable`
 
 The `@Generable` macro creates compile-time JSON schemas for type-safe output.
 
@@ -185,7 +193,7 @@ print(recipe.name)
 print(recipe.steps)
 ```
 
-### Supported Types for @Generable Properties
+### Supported Types for `@Generable` Properties
 
 - `String`
 - `Int`, `Double`, `Float`
@@ -195,7 +203,7 @@ print(recipe.steps)
 - Other `@Generable` structs (nested)
 - Enums conforming to `@Generable`
 
-### @Guide Constraints
+### `@Guide` Constraints
 
 ```swift
 @Generable
@@ -317,13 +325,25 @@ let response = try await session.respond(to: "What's the weather in Tokyo?")
 ### Tool Best Practices
 
 - Register all tools at session creation
-- Each tool adds to the context token budget (schema included in instructions by default)
+- 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
 
-- The `Tool` protocol's associated `Output` type must conform to `PromptRepresentable` (e.g., `String`, `[String]`, custom types)
+- `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:)`.

package/pipeline/skills/shared/external/apple-on-device-ai/references/mlx-swift.md

@@ -30,25 +30,28 @@ Apple Silicon via unified memory architecture.
 ```swift
 import MLX
 import MLXLLM
-
-let config = ModelConfiguration(
-    id: "mlx-community/Mistral-7B-Instruct-v0.3-4bit"
-)
-let model = try await LLMModelFactory.shared.loadContainer(
-    configuration: config
+import MLXLMCommon
+import MLXLMHFAPI
+import MLXLMTokenizers
+
+let container = try await LLMModelFactory.shared.loadContainer(
+    from: HubClient.default,
+    using: TokenizersLoader(),
+    configuration: .init(id: "mlx-community/Qwen3-4B-4bit")
 )
 
-try await model.perform { context in
-    let input = try await context.processor.prepare(
-        input: UserInput(prompt: "Hello")
-    )
-    let stream = try generate(
-        input: input,
-        parameters: GenerateParameters(temperature: 0.0),
-        context: context
-    )
-    for await part in stream {
-        print(part.chunk ?? "", terminator: "")
+let session = ChatSession(container)
+print(try await session.respond(to: "Hello"))
+
+// Use ModelContainer directly when you need streaming control.
+let input = try await container.prepare(input: UserInput(prompt: "Hello"))
+let stream = try await container.generate(
+    input: input,
+    parameters: GenerateParameters(temperature: 0.0)
+)
+for await event in stream {
+    if case .chunk(let text) = event {
+        print(text, terminator: "")
     }
 }
 ```
@@ -65,36 +68,37 @@ try await model.perform { context in
 ### Memory Management Rules
 
 1. Never exceed 60% of total RAM on iOS
-2. Set GPU cache limits:
+2. Set MLX cache limits:
    ```swift
-   MLX.GPU.set(cacheLimit: 512 * 1024 * 1024) // 512 MB
+   Memory.cacheLimit = 512 * 1024 * 1024 // 512 MB
    ```
-3. Monitor memory pressure and reduce cache under pressure
-4. Unload models on app backgrounding
+3. Monitor memory pressure with `Memory.snapshot()` and reduce cache under pressure
+4. Unload MLX and llama.cpp models on backgrounding or memory pressure; for MLX,
+   also call `Memory.clearCache()` after generation-heavy phases
 5. Use "Increased Memory Limit" entitlement for larger models on iOS
 6. Pre-flight memory checks before loading models
-7. Physical device required (no simulator support for Metal GPU)
+7. Validate MLX Swift and llama.cpp on physical Apple Silicon; Simulator cannot
+   exercise Metal-dependent inference, memory, or performance
 
 ### Model Lifecycle Management
 
 ```swift
 @Observable
 class ModelManager {
-    private var model: LLMModelContainer?
+    private var model: ModelContainer?
     private var generationCount = 0
 
     func loadModel() async throws {
-        let config = ModelConfiguration(
-            id: "mlx-community/Llama-3.2-3B-Instruct-4bit"
-        )
         model = try await LLMModelFactory.shared.loadContainer(
-            configuration: config
+            from: HubClient.default,
+            using: TokenizersLoader(),
+            configuration: .init(id: "mlx-community/Qwen3-4B-4bit")
         )
     }
 
     func unloadModel() {
         model = nil
-        MLX.GPU.set(cacheLimit: 0)
+        Memory.clearCache()
     }
 }
 ```
@@ -182,7 +186,7 @@ When an app needs multiple AI backends:
 
 ```swift
 func respond(to prompt: String) async throws -> String {
-    // Try Foundation Models first (zero setup, best integration)
+    // Try Foundation Models first when available (system-integrated backend)
     if SystemLanguageModel.default.isAvailable {
         return try await foundationModelsRespond(prompt)
     }
@@ -276,7 +280,7 @@ Training custom classifiers directly on device or Mac:
 - [ ] Model size appropriate for target device RAM
 - [ ] Memory pressure monitoring implemented
 - [ ] Models unloaded on app backgrounding
-- [ ] GPU cache limits set appropriately
+- [ ] MLX cache limits set appropriately
 - [ ] Pre-flight memory check before loading large models
 - [ ] Fallback strategy when model unavailable
 - [ ] All model access serialized through coordinator