@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/coreml/references/coreml-swift-integration.md

@@ -1,810 +1,807 @@
-# Core ML Swift Integration Reference
+# Core ML in Swift: extended patterns
 
-Complete implementation patterns for loading, configuring, and running Core ML
-models in Swift. All patterns target iOS 26+ with Swift 6.3, backward-compatible
-to iOS 14 unless noted.
+Companion to `../SKILL.md`. Baseline iOS 26 and Swift 6.3; lower floors are
+called out per API, and most of this works back to iOS 14 when the newer calls
+are left out.
 
 ## Contents
-- Actor-Based Model Loading and Caching
-- Auto-Generated Class Usage
-- Manual MLFeatureProvider
-- Prediction in Async Workflows
-- MLBatchProvider for Batch Inference
-- Stateful Predictions with MLState (iOS 18+)
-- Image Preprocessing
-- MLMultiArray Creation and Manipulation
-- MLTensor Advanced Operations
-- Vision + Core ML Pipelines
-- NaturalLanguage Integration
-- MLComputePlan Detailed Usage (iOS 17.4+)
-- Background Loading and Memory Management
-- Error Handling Patterns
-- Testing Patterns
-
-## Actor-Based Model Loading and Caching
-
-Use an actor to manage model lifecycle, prevent concurrent loading, and cache
-compiled models persistently.
+
+- [An actor that owns models](#an-actor-that-owns-models)
+- [Generated classes](#generated-classes)
+- [A hand-written feature provider](#a-hand-written-feature-provider)
+- [Predictions in async code](#predictions-in-async-code)
+- [Batch inference](#batch-inference)
+- [Stateful sessions with MLState (iOS 18+)](#stateful-sessions-with-mlstate-ios-18)
+- [Pixel buffers](#pixel-buffers)
+- [MLMultiArray](#mlmultiarray)
+- [MLTensor (iOS 18+)](#mltensor-ios-18)
+- [Vision and Core ML together](#vision-and-core-ml-together)
+- [NaturalLanguage models](#naturallanguage-models)
+- [MLComputePlan in detail (iOS 17.4+)](#mlcomputeplan-in-detail-ios-174)
+- [Lifecycle: warm up and release](#lifecycle-warm-up-and-release)
+- [Errors](#errors)
+- [Tests with Swift Testing](#tests-with-swift-testing)
+- [Memory practices](#memory-practices)
+
+## An actor that owns models
+
+An actor serializes loading, guarantees one instance per model, and keeps
+compiled models on disk between launches.
 
 ```swift
 import CoreML
 
-actor ModelManager {
-    private var loadedModels: [String: MLModel] = [:]
-    private let cacheDirectory: URL
+enum ModelStoreError: Error {
+    case missing(String)
+    case predictionFailed(String)
+}
+
+actor ModelStore {
+    static let shared = ModelStore()
+
+    private var loaded: [String: MLModel] = [:]
+    private let compiledFolder: URL
 
     init() {
-        let appSupport = FileManager.default.urls(
-            for: .applicationSupportDirectory, in: .userDomainMask
-        ).first!
-        cacheDirectory = appSupport.appendingPathComponent("CompiledModels", isDirectory: true)
-        try? FileManager.default.createDirectory(at: cacheDirectory, withIntermediateDirectories: true)
+        compiledFolder = URL.applicationSupportDirectory.appending(path: "CompiledModels", directoryHint: .isDirectory)
+        try? FileManager.default.createDirectory(at: compiledFolder, withIntermediateDirectories: true)
     }
 
-    func model(named name: String, configuration: MLModelConfiguration = .init()) async throws -> MLModel {
-        if let cached = loadedModels[name] {
-            return cached
-        }
+    func prepare(_ name: String, settings: sending MLModelConfiguration = MLModelConfiguration()) async throws {
+        _ = try await model(name, settings: settings)
+    }
 
-        let compiledURL = try await compiledModelURL(for: name)
-        let model = try await MLModel.load(contentsOf: compiledURL, configuration: configuration)
-        loadedModels[name] = model
-        return model
+    func predict(_ name: String, from input: sending MLFeatureProvider) async throws -> sending MLFeatureProvider {
+        nonisolated(unsafe) let engine = try await model(name)
+        return try await engine.prediction(from: input)
     }
 
-    func unloadModel(named name: String) {
-        loadedModels.removeValue(forKey: name)
+    func release(_ name: String) {
+        loaded[name] = nil
     }
 
-    func unloadAll() {
-        loadedModels.removeAll()
+    func releaseEverything() {
+        loaded.removeAll()
     }
 
-    private func compiledModelURL(for name: String) async throws -> URL {
-        // Check for pre-compiled model in cache
-        let cachedURL = cacheDirectory.appendingPathComponent("\(name).mlmodelc")
-        if FileManager.default.fileExists(atPath: cachedURL.path) {
-            return cachedURL
+    private func model(_ name: String, settings: sending MLModelConfiguration = MLModelConfiguration()) async throws -> MLModel {
+        if let ready = loaded[name] {
+            return ready
         }
+        let location = try await compiledLocation(for: name)
+        let fresh = try await MLModel.load(contentsOf: location, configuration: settings)
+        loaded[name] = fresh
+        return fresh
+    }
 
-        // Check for pre-compiled model in bundle
-        if let bundledCompiledURL = Bundle.main.url(forResource: name, withExtension: "mlmodelc") {
-            return bundledCompiledURL
+    private func compiledLocation(for key: String) async throws -> URL {
+        let files = FileManager.default
+        let cached = compiledFolder.appending(path: key + ".mlmodelc")
+        if files.fileExists(atPath: cached.path()) {
+            return cached
         }
-
-        // Compile from .mlpackage and cache
-        guard let packageURL = Bundle.main.url(forResource: name, withExtension: "mlpackage") else {
-            throw ModelManagerError.modelNotFound(name)
+        if let shipped = Bundle.main.url(forResource: key, withExtension: "mlmodelc") {
+            return shipped
         }
-        let tempCompiledURL = try await MLModel.compileModel(at: packageURL)
-
-        // Move compiled model to persistent cache
-        if FileManager.default.fileExists(atPath: cachedURL.path) {
-            try FileManager.default.removeItem(at: cachedURL)
+        guard let package = Bundle.main.url(forResource: key, withExtension: "mlpackage") else {
+            throw ModelStoreError.missing(key)
         }
-        try FileManager.default.moveItem(at: tempCompiledURL, to: cachedURL)
-        return cachedURL
+        let temporary = try await MLModel.compileModel(at: package)
+        try? files.removeItem(at: cached)
+        try files.moveItem(at: temporary, to: cached)
+        return cached
     }
 }
-
-enum ModelManagerError: Error {
-    case modelNotFound(String)
-    case predictionFailed(String)
-}
 ```
 
-### Usage with SwiftUI
+Lookup order: a previously compiled copy in Application Support, then a
+`.mlmodelc` shipped in the bundle, then compiling a bundled `.mlpackage` and
+moving the result into the cache. Anything else is `missing`.
 
-```swift
-@MainActor
-@Observable
-final class ClassifierViewModel {
-    var classLabel: String = ""
-    var confidence: Double = 0
-    var isLoading = false
-    var errorMessage: String?
+`MLModel` is not `Sendable`, so the store never hands one out: returning it to
+a main-actor caller fails to compile under Swift 6. Callers warm a model with
+`prepare` and run it with `predict`. Inputs, outputs and the configuration are
+`sending`, so the caller passes a freshly built value and owns the result. The
+`nonisolated(unsafe)` copy in `predict` lets the cached model reach the async
+prediction call, which may run concurrently on one model (see "Predictions in
+async code" below). For downloaded
+models, put the version in the cache file name so a new version compiles once.
 
-    private let modelManager = ModelManager()
+### Driving it from SwiftUI
 
-    func classify(image: CGImage) async {
-        isLoading = true
-        defer { isLoading = false }
+Most examples below feed one image feature, so they share a tiny helper:
 
-        do {
-            let config = MLModelConfiguration()
-            config.computeUnits = .all
+```swift
+import CoreML
 
-            let model = try await modelManager.model(named: "ImageClassifier", configuration: config)
+func photoInput(_ frame: CVPixelBuffer) throws -> MLFeatureProvider {
+    try MLDictionaryFeatureProvider(dictionary: ["photo": MLFeatureValue(pixelBuffer: frame)])
+}
+```
 
-            let pixelBuffer = try createPixelBuffer(from: image, width: 224, height: 224)
-            let input = try MLDictionaryFeatureProvider(dictionary: [
-                "image": MLFeatureValue(pixelBuffer: pixelBuffer),
-            ])
-            let output = try model.prediction(from: input)
+```swift
+import Observation
+import CoreML
 
-            classLabel = output.featureValue(for: "classLabel")?.stringValue ?? "Unknown"
-            confidence = output.featureValue(for: "classLabelProbs")?
-                .dictionaryValue[classLabel]?
-                .doubleValue ?? 0
+@MainActor
+@Observable
+final class DishRecognizer {
+    var dish = ""
+    var certainty = 0.0
+    var working = false
+    var failure: String?
+
+    func recognize(_ picture: CGImage) async {
+        working = true
+        defer { working = false }
+        do {
+            let frame = try makeFrame(from: picture, width: 224, height: 224)
+            let answer = try await ModelStore.shared.predict("DishClassifier", from: photoInput(frame))
+            dish = answer.featureValue(for: "classLabel")?.stringValue ?? ""
+            certainty = answer.featureValue(for: "classLabelProbs")?.dictionaryValue[dish]?.doubleValue ?? 0
         } catch {
-            errorMessage = "Classification failed: \(error.localizedDescription)"
+            failure = error.localizedDescription
         }
     }
 }
 ```
 
-## Auto-Generated Class Usage
+`makeFrame(from:width:height:)` is defined in the pixel buffer section below.
+The frame is created inside `recognize`, which is what allows its feature
+provider to be sent to the store. The dictionary lookup reads the probability of the winning
+label out of the `classLabelProbs` feature.
 
-When you add a `.mlmodel` or `.mlpackage` to your Xcode project, Xcode
-generates a Swift class with typed inputs and outputs.
+## Generated classes
+
+For a model file named `SceneTagger`, Xcode generates `SceneTagger`,
+`SceneTaggerInput` and `SceneTaggerOutput`.
 
 ```swift
 import CoreML
+import Vision
 
-// Xcode generates: MyImageClassifier, MyImageClassifierInput, MyImageClassifierOutput
-
-// Synchronous prediction with generated types
-func classifyWithGeneratedClass(pixelBuffer: CVPixelBuffer) throws -> (label: String, confidence: Double) {
-    let config = MLModelConfiguration()
-    config.computeUnits = .all
-
-    let classifier = try MyImageClassifier(configuration: config)
-    let input = MyImageClassifierInput(image: pixelBuffer)
-    let output = try classifier.prediction(input: input)
+func bestDish(_ frame: CVPixelBuffer, using classifier: SceneTagger) throws -> (name: String, probability: Double) {
+    let verdict = try classifier.prediction(input: SceneTaggerInput(image: frame))
+    return (verdict.classLabel, verdict.classLabelProbs[verdict.classLabel] ?? 0)
+}
 
-    let topLabel = output.classLabel
-    let topConfidence = output.classLabelProbs[topLabel] ?? 0
-    return (topLabel, topConfidence)
+func legacyVisionModel(for classifier: SceneTagger) throws -> VNCoreMLModel {
+    try VNCoreMLModel(for: classifier.model)
 }
 ```
 
-### Accessing the Underlying MLModel
-
-```swift
-// Get the underlying MLModel from a generated class
-let classifier = try MyImageClassifier(configuration: config)
-let mlModel = classifier.model
-
-// Useful for Vision integration
-let vnModel = try VNCoreMLModel(for: mlModel)
-```
+The generated class exposes the underlying `MLModel` as `.model`, which is
+what `VNCoreMLModel(for:)` and `CoreMLModelContainer(model:)` expect.
 
-## Manual MLFeatureProvider
+## A hand-written feature provider
 
-Implement `MLFeatureProvider` when you need custom input construction.
+Implement `MLFeatureProvider` when the input is assembled in code:
 
 ```swift
 import CoreML
 
-final class CustomImageInput: MLFeatureProvider {
-    let image: CVPixelBuffer
-    let confidenceThreshold: Double
+final class GlareCheckInput: MLFeatureProvider {
+    let frame: CVPixelBuffer
+    let sensitivity: Double
 
-    var featureNames: Set<String> {
-        ["image", "confidence_threshold"]
+    init(frame: CVPixelBuffer, sensitivity: Double = 0.5) {
+        self.frame = frame
+        self.sensitivity = sensitivity
     }
 
-    func featureValue(for featureName: String) -> MLFeatureValue? {
-        switch featureName {
-        case "image":
-            return MLFeatureValue(pixelBuffer: image)
-        case "confidence_threshold":
-            return MLFeatureValue(double: confidenceThreshold)
-        default:
-            return nil
-        }
+    var featureNames: Set<String> {
+        ["photo", "sensitivity"]
     }
 
-    init(image: CVPixelBuffer, confidenceThreshold: Double = 0.5) {
-        self.image = image
-        self.confidenceThreshold = confidenceThreshold
+    func featureValue(for requested: String) -> MLFeatureValue? {
+        if requested == "sensitivity" {
+            return MLFeatureValue(double: sensitivity)
+        }
+        return requested == "photo" ? MLFeatureValue(pixelBuffer: frame) : nil
     }
 }
 
-// Usage
-let input = CustomImageInput(image: pixelBuffer, confidenceThreshold: 0.7)
-let output = try model.prediction(from: input)
+func hasGlare(_ frame: CVPixelBuffer, model: MLModel) async throws -> Bool {
+    let verdict = try await model.prediction(from: GlareCheckInput(frame: frame))
+    return verdict.featureValue(for: "glare")?.int64Value == 1
+}
 ```
 
-## Prediction in Async Workflows
+Unknown feature names return `nil`.
+
+## Predictions in async code
 
-`MLModel.prediction(...)` is synchronous. Use Swift concurrency to keep loading,
-preprocessing, and caller coordination off the main actor, then call prediction
-without `await`.
+Keep loading, preprocessing and coordination off the main actor.
 
-### Single Prediction from an Actor
+- iOS 17 and later: `prediction(from:options:) async throws` is the natural
+  call in async code and may run concurrently on one model. The compiler
+  picks it inside `async` functions, so write `try await`.
+- The synchronous `prediction(from:)` is for synchronous contexts and for
+  deployment targets below iOS 17.
 
 ```swift
-actor PredictionService {
-    private let model: MLModel
+import CoreML
+
+actor InferenceService {
+    nonisolated(unsafe) private let engine: MLModel
 
-    init(model: MLModel) {
-        self.model = model
+    init(engine: MLModel) {
+        self.engine = engine
     }
 
-    func predict(input: any MLFeatureProvider) async throws -> any MLFeatureProvider {
-        try model.prediction(from: input)
+    func run(_ features: sending MLFeatureProvider) async throws -> sending MLFeatureProvider {
+        try await engine.prediction(from: features)
+    }
+
+    func runBlocking(_ features: MLFeatureProvider) throws -> MLFeatureProvider {
+        try engine.prediction(from: features)
     }
 }
 ```
 
-### Streaming Predictions
+`runBlocking` is a synchronous actor method, so the synchronous overload
+applies there. Calling the async overload hands the non-`Sendable` model and
+input to a nonisolated method, which Swift 6 rejects for plain actor state
+("sending 'self.engine' risks causing data races"). The model is therefore
+stored `nonisolated(unsafe)`, relying on the async API being safe to call
+concurrently, and `run` takes and returns `sending` values.
+
+### Streaming frames
 
 ```swift
-func classifyFrames(_ frames: AsyncStream<CVPixelBuffer>) async throws -> AsyncThrowingStream<String, Error> {
-    let model = try await ModelManager().model(named: "Classifier")
-
-    return AsyncThrowingStream { continuation in
-        Task {
-            do {
-                for await frame in frames {
-                    let input = try MLDictionaryFeatureProvider(dictionary: [
-                        "image": MLFeatureValue(pixelBuffer: frame),
-                    ])
-                    let output = try model.prediction(from: input)
-                    let label = output.featureValue(for: "classLabel")?.stringValue ?? "unknown"
-                    continuation.yield(label)
-                }
-                continuation.finish()
-            } catch {
-                continuation.finish(throwing: error)
+import CoreML
+
+func liveLabels(from frames: AsyncStream<CameraSample>, model: sending MLModel) -> AsyncThrowingStream<String, Error> {
+    let (labels, sink) = AsyncThrowingStream<String, Error>.makeStream()
+    let worker = Task {
+        do {
+            for await sample in frames {
+                let verdict = try await model.prediction(from: photoInput(sample.buffer))
+                sink.yield(verdict.featureValue(for: "classLabel")?.stringValue ?? "")
             }
+            sink.finish()
+        } catch {
+            sink.finish(throwing: error)
         }
     }
+    sink.onTermination = { _ in worker.cancel() }
+    return labels
+}
+
+struct CameraSample: @unchecked Sendable {
+    let buffer: CVPixelBuffer
 }
 ```
 
-## MLBatchProvider for Batch Inference
+`CVPixelBuffer` is not `Sendable`; the wrapper is acceptable only when nothing
+touches the buffer after it is handed over. The model parameter is `sending`
+for the same reason: the worker task takes it over, and the caller must not use
+that instance again. The stream comes from `makeStream()` rather than the
+closure initializer, because a `Task` started inside that closure cannot
+capture the model under Swift 6.
+
+## Batch inference
 
 ```swift
 import CoreML
 
-func batchClassify(images: [CVPixelBuffer], model: MLModel) throws -> [(label: String, confidence: Double)] {
-    let batchInputs = try MLArrayBatchProvider(array: images.map { buffer in
-        try MLDictionaryFeatureProvider(dictionary: [
-            "image": MLFeatureValue(pixelBuffer: buffer),
-        ])
-    })
-
-    let batchOutput = try model.predictions(fromBatch: batchInputs)
-
-    var results: [(String, Double)] = []
-    for i in 0..<batchOutput.count {
-        let features = batchOutput.features(at: i)
-        let label = features.featureValue(for: "classLabel")?.stringValue ?? "unknown"
-        let probs = features.featureValue(for: "classLabelProbs")?.dictionaryValue ?? [:]
-        let confidence = (probs[label] as? NSNumber)?.doubleValue ?? 0
-        results.append((label, confidence))
-    }
-    return results
+func labelBatch(_ frames: [CVPixelBuffer], model: MLModel) throws -> [(String, Double)] {
+    let rows = try frames.map(photoInput)
+    let results = try model.predictions(fromBatch: MLArrayBatchProvider(array: rows))
+    var pairs: [(String, Double)] = []
+    for index in 0..<results.count {
+        let row = results.features(at: index)
+        let top = row.featureValue(for: "classLabel")?.stringValue ?? ""
+        let table = row.featureValue(for: "classLabelProbs")?.dictionaryValue
+        pairs.append((top, (table?[top] as? NSNumber)?.doubleValue ?? 0))
+    }
+    return pairs
 }
-```
 
-Batch prediction has two valid API labels:
-
-```swift
-// No explicit prediction options
-let output = try model.predictions(fromBatch: batchInputs)
-
-// Explicit prediction options
-let options = MLPredictionOptions()
-let outputWithOptions = try model.predictions(from: batchInputs, options: options)
+func labelBatchWithOptions(_ batch: MLBatchProvider, model: MLModel) throws -> MLBatchProvider {
+    let options = MLPredictionOptions()
+    return try model.predictions(from: batch, options: options)
+}
 ```
 
-Do not write `predictions(from:)` for the no-options batch path; the `from:`
-label belongs to the overload that also takes `options:`.
+The two correct spellings: `predictions(fromBatch:)` without options and
+`predictions(from:options:)` with them. `predictions(from:)` alone is not the
+options-free batch call.
 
-## Stateful Predictions with MLState (iOS 18+)
+## Stateful sessions with MLState (iOS 18+)
 
-`MLState` enables models that maintain internal state across predictions. This is
-essential for sequence models (text generation, audio classification, time-series)
-where each prediction depends on previous context.
+Text generation, audio classification and time-series models carry context
+from one call to the next. `MLState` holds that context.
 
 ```swift
 import CoreML
 
-/// Audio classification that accumulates context over time
-actor AudioClassifier {
-    private let model: MLModel
-    private var state: MLState?
+enum ListeningError: Error {
+    case notListening
+}
 
-    init(model: MLModel) {
-        self.model = model
-    }
+actor ChirpDetector {
+    private let engine: MLModel
+    private var memory: MLState?
 
-    /// Start a new classification session
-    func beginSession() {
-        state = model.makeState()
+    init(engine: MLModel) {
+        self.engine = engine
     }
 
-    /// Classify the next audio frame using accumulated state
-    func classify(audioFeatures: MLMultiArray) async throws -> String {
-        guard let state else {
-            throw ClassifierError.noActiveSession
-        }
-
-        let input = try MLDictionaryFeatureProvider(dictionary: [
-            "audio_features": MLFeatureValue(multiArray: audioFeatures)
-        ])
-
-        let output = try model.prediction(from: input, using: state)
-        return output.featureValue(for: "label")?.stringValue ?? "unknown"
+    func startListening() {
+        memory = engine.makeState()
     }
 
-    /// End the session and release state
-    func endSession() {
-        state = nil
+    func detect(_ window: MLMultiArray) throws -> String? {
+        guard let memory else { throw ListeningError.notListening }
+        let input = try MLDictionaryFeatureProvider(dictionary: ["samples": MLFeatureValue(multiArray: window)])
+        let heard = try engine.prediction(from: input, using: memory)
+        return heard.featureValue(for: "species")?.stringValue
     }
-}
 
-enum ClassifierError: Error {
-    case noActiveSession
+    func stopListening() {
+        memory = nil
+    }
 }
 ```
 
-### Key Rules for MLState
+Rules:
 
-- **Serialized use:** `MLState` is `Sendable`, but predictions that use the same
-  state must be serialized. `Sendable` permits transfer across concurrency
-  domains; it does not permit concurrent predictions on one state. Do not read or
-  write state buffers while a prediction is in flight.
-- **Async options overload:** Use the synchronous `prediction(from:using:)`
-  overload for simple serialized loops. If you need `MLPredictionOptions`, iOS
-  18+ also provides async `prediction(from:using:options:)`; keep one in-flight
-  prediction per state.
-- **Independent streams:** Call `model.makeState()` per stream when processing
-  multiple concurrent sequences (e.g., multiple audio channels).
-- **Resettable:** Create a new state to reset accumulated context. There is no
-  explicit reset method -- just discard the old state and create fresh.
-- **Memory:** State holds model-specific internal buffers. Release it when the
-  session ends to free memory.
+- One prediction at a time per state. Being `Sendable` means a state may be
+  handed to another task or actor; overlapping calls on it are still unsafe,
+  and its buffers stay untouched until the current call returns.
+- In plain serial code, such as the synchronous actor method above, call
+  `prediction(from:using:)` without `await`. In async code, or when you need
+  `MLPredictionOptions`, use `prediction(from:using:options:) async` (iOS 18);
+  still one call in flight per state.
+- Concurrent sequences, such as several audio channels, get one
+  `makeState()` each.
+- There is no reset call. Throw the state away and make a new one.
+- A state holds buffers specific to its model; drop it once the session is over.
 
-## Image Preprocessing
+## Pixel buffers
 
-### CVPixelBuffer from CGImage
+A throwing version of the conversion helper:
 
 ```swift
-import CoreVideo
 import CoreGraphics
+import CoreVideo
 
-func createPixelBuffer(from cgImage: CGImage, width: Int, height: Int) throws -> CVPixelBuffer {
-    let attrs: [CFString: Any] = [
-        kCVPixelBufferCGImageCompatibilityKey: true,
-        kCVPixelBufferCGBitmapContextCompatibilityKey: true,
-    ]
+enum FrameError: Error {
+    case bufferAllocation
+    case drawingContext
+}
 
-    var pixelBuffer: CVPixelBuffer?
-    let status = CVPixelBufferCreate(
-        kCFAllocatorDefault,
-        width, height,
-        kCVPixelFormatType_32ARGB,
-        attrs as CFDictionary,
-        &pixelBuffer
-    )
-    guard status == kCVReturnSuccess, let buffer = pixelBuffer else {
-        throw ImageError.pixelBufferCreationFailed
-    }
+func makeFrame(from picture: CGImage, width: Int, height: Int) throws -> CVPixelBuffer {
+    let attributes = [
+        kCVPixelBufferCGImageCompatibilityKey: true,
+        kCVPixelBufferCGBitmapContextCompatibilityKey: true
+    ] as CFDictionary
+    var created: CVPixelBuffer?
+    let format = kCVPixelFormatType_32ARGB
+    guard CVPixelBufferCreate(nil, width, height, format, attributes, &created) == kCVReturnSuccess,
+          let frame = created else {
+        throw FrameError.bufferAllocation
+    }
+
+    CVPixelBufferLockBaseAddress(frame, [])
+    defer { CVPixelBufferUnlockBaseAddress(frame, []) }
+
+    let base = CVPixelBufferGetBaseAddress(frame)
+    let stride = CVPixelBufferGetBytesPerRow(frame)
+    let layout = CGImageAlphaInfo.noneSkipFirst.rawValue
+    let rgb = CGColorSpaceCreateDeviceRGB()
+    guard let canvas = CGContext(data: base, width: width, height: height, bitsPerComponent: 8,
+                                 bytesPerRow: stride, space: rgb, bitmapInfo: layout) else {
+        throw FrameError.drawingContext
+    }
+    canvas.draw(picture, in: CGRect(origin: .zero, size: CGSize(width: width, height: height)))
+    return frame
+}
+```
 
-    CVPixelBufferLockBaseAddress(buffer, [])
-    defer { CVPixelBufferUnlockBaseAddress(buffer, []) }
+From a `CIImage`, create a `kCVPixelFormatType_32BGRA` buffer and render into it
+with `CIContext.render(_:to:)`:
 
-    guard let context = CGContext(
-        data: CVPixelBufferGetBaseAddress(buffer),
-        width: width,
-        height: height,
-        bitsPerComponent: 8,
-        bytesPerRow: CVPixelBufferGetBytesPerRow(buffer),
-        space: CGColorSpaceCreateDeviceRGB(),
-        bitmapInfo: CGImageAlphaInfo.noneSkipFirst.rawValue
-    ) else {
-        throw ImageError.contextCreationFailed
-    }
-
-    context.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
-    return buffer
-}
+```swift
+import CoreImage
+import CoreVideo
 
-enum ImageError: Error {
-    case pixelBufferCreationFailed
-    case contextCreationFailed
+func makeFrame(from image: CIImage, renderer: CIContext) -> CVPixelBuffer? {
+    var created: CVPixelBuffer?
+    CVPixelBufferCreate(kCFAllocatorDefault, Int(image.extent.width), Int(image.extent.height),
+                        kCVPixelFormatType_32BGRA, nil, &created)
+    guard let frame = created else { return nil }
+    renderer.render(image, to: frame)
+    return frame
 }
 ```
 
-For `CIImage` sources, use `CIContext.render(_:to:)` into a `CVPixelBuffer`
-created with `kCVPixelFormatType_32BGRA`.
+Center-crop before scaling when the model expects a square and the photo is
+not: `image.cropped(to:)` with a square rect centered on `image.extent`, then
+scale to the model's side length. Per-channel normalization is shown in the
+tensor section.
 
-## MLMultiArray Creation and Manipulation
+## MLMultiArray
 
 ```swift
 import CoreML
 
-let array = try MLMultiArray(shape: [1, 3, 224, 224], dataType: .float32)
-for i in 0..<array.count { array[i] = NSNumber(value: Float.random(in: 0...1)) }
-
-let values: [Float] = [1.0, 2.0, 3.0, 4.0, 5.0]
-let mlArray = try MLMultiArray(values)
+func planarImageTensor() throws -> MLMultiArray {
+    let planes = try MLMultiArray(shape: [1, 3, 256, 256], dataType: .float32)
+    for offset in 0..<planes.count {
+        planes[offset] = NSNumber(value: Float(offset % 255) / 255)
+    }
+    return planes
+}
 
-// Access elements
-let element = array[[0, 0, 112, 112] as [NSNumber]].floatValue
+func features(from values: [Float]) throws -> MLFeatureValue {
+    let array = try MLMultiArray(values)
+    return MLFeatureValue(multiArray: array)
+}
 
-// Convert to Swift array
-func toFloatArray(_ multiArray: MLMultiArray) -> [Float] {
-    let pointer = multiArray.dataPointer.assumingMemoryBound(to: Float.self)
-    return Array(UnsafeBufferPointer(start: pointer, count: multiArray.count))
+func pixelValue(_ planes: MLMultiArray, channel: Int, row: Int, column: Int) -> Float {
+    planes[[0, channel, row, column] as [NSNumber]].floatValue
 }
 
-let featureValue = MLFeatureValue(multiArray: array)
+func floats(from array: MLMultiArray) -> [Float] {
+    MLShapedArray<Float>(array).scalars
+}
 ```
 
-## MLTensor Advanced Operations (iOS 18+)
+Linear subscripts (`planes[offset]`) walk the whole buffer; index arrays
+address one element. Converting through `MLShapedArray<Float>` avoids raw
+pointer work; if you do use `dataPointer.assumingMemoryBound(to: Float.self)`
+with `UnsafeBufferPointer`, keep the array alive for the whole access.
+
+Tokenized text arrives as an `[Int32]` of token ids shaped `[1, sequence]`;
+audio features as `[1, frames, bins]`. Both follow the same create, fill,
+wrap-in-`MLFeatureValue(multiArray:)` pattern.
+
+## MLTensor (iOS 18+)
 
 ```swift
 import CoreML
 
-// Creation patterns
-let tensor1D = MLTensor([1.0, 2.0, 3.0, 4.0])
-let zeros = MLTensor(zeros: [3, 224, 224], scalarType: Float.self)
-let ones = MLTensor(ones: [2, 2], scalarType: Float.self)
-
-// Reshaping
-let reshaped = tensor1D.reshaped(to: [2, 2])
-let expanded = tensor1D.expandingShape(at: 0)   // [1, 4]
+func tensorTour() async -> (MLShapedArray<Float>, MLMultiArray) {
+    let readings = MLTensor([1.5, 3.0, 4.5, 6.0, 7.5, 9.0] as [Float])
+    let blank = MLTensor(zeros: [2, 3], scalarType: Float.self)
+    let unit = MLTensor(ones: [2, 3], scalarType: Float.self)
+
+    let square = readings.reshaped(to: [2, 3])
+    let row = readings.expandingShape(at: 0)
+    let summed = square + unit + blank
+    let average = readings.mean()
+    let winner = readings.argmax()
+    let odds = row.softmax(alongAxis: -1)
+    let joined = MLTensor(concatenating: [square, summed], alongAxis: 0)
+
+    _ = (average, winner, joined)
+    let materialized = await odds.shapedArray(of: Float.self)
+    return (materialized, MLMultiArray(materialized))
+}
 
-// Arithmetic and reduction
-let sum = tensor1D + ones.reshaped(to: [4])
-let mean = tensor1D.mean()
-let argmax = tensor1D.argmax()
+func imageNetNormalized(_ pixels: MLTensor) -> MLTensor {
+    let mean = MLTensor([0.485, 0.456, 0.406] as [Float]).reshaped(to: [1, 3, 1, 1])
+    let spread = MLTensor([0.229, 0.224, 0.225] as [Float]).reshaped(to: [1, 3, 1, 1])
+    return (pixels - mean) / spread
+}
 
-// Activation functions
-let softmaxed = tensor1D.softmax(alongAxis: -1)
+func tensorFromArray(_ array: MLMultiArray) -> MLTensor {
+    MLTensor(MLShapedArray<Float>(array))
+}
+```
 
-// Interop with MLShapedArray / MLMultiArray
-let shaped = await tensor1D.shapedArray(of: Float.self) // MLShapedArray<Float>
-let multiArray = try MLMultiArray(shaped)
-let shapedAgain = MLShapedArray<Float>(multiArray)
+`expandingShape(at: 0)` turns shape `[6]` into `[1, 6]`. Values only exist
+after `await shapedArray(of:)`. Keep to operations Apple documents: no
+`MLTensor(multiArray)`, no `std()` or `standardDeviation()`, no peeking into
+the lazy storage and no blocking read, unless Apple's documentation names the
+exact API and its availability. A standard deviation can be built from documented parts:
 
-// Concatenation
-let a = MLTensor([1.0, 2.0])
-let b = MLTensor([3.0, 4.0])
-let concatenated = MLTensor(concatenating: [a, b], alongAxis: 0)
+```swift
+import CoreML
 
-// Normalization pattern (e.g., ImageNet preprocessing)
-func normalize(_ tensor: MLTensor, mean: [Float], std: [Float]) -> MLTensor {
-    let meanTensor = MLTensor(mean)
-    let stdTensor = MLTensor(std)
-    return (tensor - meanTensor) / stdTensor
+func spread(of values: MLTensor) -> MLTensor {
+    let centered = values - values.mean()
+    return (centered * centered).mean().squareRoot()
 }
 ```
 
-## Vision + Core ML Pipelines
+## Vision and Core ML together
 
-### Modern API (iOS 18+)
+### Swift-native Vision (iOS 18+)
 
 ```swift
-import Vision
 import CoreML
+import Observation
+import Vision
 
-@MainActor
 @Observable
-final class ObjectDetectionViewModel {
-    var detections: [Detection] = []
-    var isProcessing = false
-
-    struct Detection: Identifiable {
+@MainActor
+final class ShelfDetector {
+    struct Finding: Identifiable {
         let id = UUID()
-        let label: String
-        let confidence: Float
-        let boundingBox: CGRect
+        let name: String
+        let score: Float
+        let box: NormalizedRect
     }
 
-    func detect(in image: CGImage) async {
-        isProcessing = true
-        defer { isProcessing = false }
+    var findings: [Finding] = []
+    private let detector: MLModel
+
+    init(detector: MLModel) {
+        self.detector = detector
+    }
 
+    func scan(_ photo: CGImage) async {
         do {
-            let config = MLModelConfiguration()
-            config.computeUnits = .all
-
-            let detector = try MyObjectDetector(configuration: config)
-            let request = CoreMLRequest(model: .init(detector.model))
-
-            let results = try await request.perform(on: image)
-            detections = results.compactMap { observation in
-                guard let object = observation as? RecognizedObjectObservation,
-                      let topLabel = object.labels.first else { return nil }
-                return Detection(
-                    label: topLabel.identifier,
-                    confidence: topLabel.confidence,
-                    boundingBox: object.boundingBox
-                )
+            let request = CoreMLRequest(model: try CoreMLModelContainer(model: detector))
+            let raw = try await request.perform(on: photo)
+            findings = raw.compactMap { item in
+                guard let object = item as? RecognizedObjectObservation,
+                      let best = object.labels.first else { return nil }
+                return Finding(name: best.identifier, score: best.confidence, box: object.boundingBox)
             }
         } catch {
-            detections = []
+            findings = []
         }
     }
 }
-```
-
-```swift
-func classifyImage(_ image: CGImage) async throws -> [(label: String, confidence: Float)] {
-    let classifier = try MyImageClassifier(configuration: .init())
-    let request = CoreMLRequest(model: .init(classifier.model))
 
-    let results = try await request.perform(on: image)
-    return results.compactMap { observation in
-        guard let classification = observation as? ClassificationObservation else { return nil }
-        return (classification.identifier, classification.confidence)
-    }
+func topClasses(in photo: CGImage, model: MLModel) async throws -> [(String, Float)] {
+    let request = CoreMLRequest(model: try CoreMLModelContainer(model: model))
+    return try await request.perform(on: photo)
+        .compactMap { $0 as? ClassificationObservation }
+        .map { ($0.identifier, $0.confidence) }
 }
 ```
 
-### Legacy API (Pre-iOS 18)
+With a generated class, pass `generated.model` into `CoreMLModelContainer`.
+
+### Legacy Vision (before iOS 18)
 
 ```swift
-import Vision
 import CoreML
+import Vision
 
-func detectLegacy(in image: CGImage) async throws -> [VNRecognizedObjectObservation] {
-    let config = MLModelConfiguration()
-    config.computeUnits = .all
-
-    let detector = try MyObjectDetector(configuration: config)
-    let vnModel = try VNCoreMLModel(for: detector.model)
+actor LegacyShelfDetector {
+    private let visionModel: VNCoreMLModel
 
-    let request = VNCoreMLRequest(model: vnModel)
-    request.imageCropAndScaleOption = .scaleFill
+    init(model: MLModel) throws {
+        visionModel = try VNCoreMLModel(for: model)
+    }
 
-    let handler = VNImageRequestHandler(cgImage: image)
-    return try await Task.detached {
-        try handler.perform([request])
-        return request.results as? [VNRecognizedObjectObservation] ?? []
-    }.value
+    func objects(in photo: CGImage) throws -> [(label: String, confidence: Float, box: CGRect)] {
+        let request = VNCoreMLRequest(model: visionModel)
+        request.imageCropAndScaleOption = .scaleFill
+        try VNImageRequestHandler(cgImage: photo).perform([request])
+        let found = request.results as? [VNRecognizedObjectObservation] ?? []
+        return found.compactMap { object in
+            object.labels.first.map { ($0.identifier, $0.confidence, object.boundingBox) }
+        }
+    }
 }
-```
 
-```swift
-func classifyImageLegacy(_ image: CGImage) async throws -> [(label: String, confidence: Float)] {
-    let classifier = try MyImageClassifier(configuration: .init())
-    let vnModel = try VNCoreMLModel(for: classifier.model)
-    let request = VNCoreMLRequest(model: vnModel)
+func legacyTopFive(in photo: CGImage, model: MLModel) throws -> [VNClassificationObservation] {
+    let request = VNCoreMLRequest(model: try VNCoreMLModel(for: model))
     request.imageCropAndScaleOption = .centerCrop
-
-    let handler = VNImageRequestHandler(cgImage: image)
-    return try await Task.detached {
-        try handler.perform([request])
-        guard let results = request.results as? [VNClassificationObservation] else { return [] }
-        return results.prefix(5).map { ($0.identifier, $0.confidence) }
-    }.value
+    try VNImageRequestHandler(cgImage: photo).perform([request])
+    let ranked = request.results as? [VNClassificationObservation] ?? []
+    return Array(ranked.prefix(5))
 }
 ```
 
-## NaturalLanguage Integration
+The legacy handler blocks while it works, so it runs inside an actor (or a
+`Task.detached` whose captures are all `Sendable`) rather than on the main
+actor. Vision observation classes are not `Sendable`; convert them to plain
+values before they leave the actor. `.scaleFill` stretches the whole image into the model's input; `.centerCrop`
+keeps the middle square, which suits most classifiers.
+
+## NaturalLanguage models
 
-Use `NLModel` to load Core ML models trained for NLP tasks.
+Text classifiers trained with Create ML load through `NLModel`:
 
 ```swift
+import CoreML
 import NaturalLanguage
 
-func analyzeSentiment(text: String) throws -> (label: String, confidence: Double)? {
-    let modelURL = Bundle.main.url(forResource: "SentimentClassifier", withExtension: "mlmodelc")!
-    let nlModel = try NLModel(contentsOf: modelURL)
-
-    guard let label = nlModel.predictedLabel(for: text) else { return nil }
-    let hypotheses = nlModel.predictedLabelHypotheses(for: text, maximumCount: 1)
-    let confidence = hypotheses[label] ?? 0
-    return (label, confidence)
+func ticketCategory(for message: String, modelURL: URL) throws -> (String, Double)? {
+    let classifier = try NLModel(contentsOf: modelURL)
+    guard let category = classifier.predictedLabel(for: message) else { return nil }
+    let score = classifier.predictedLabelHypotheses(for: message, maximumCount: 1)[category] ?? 0
+    return (category, score)
 }
 ```
 
-## MLComputePlan Detailed Usage (iOS 17.4+)
+## MLComputePlan in detail (iOS 17.4+)
+
+A logging pass over every operation of an ML Program, run with the compute
+units you intend to ship:
 
 ```swift
 import CoreML
-
-func profileModel(at url: URL) async throws {
-    let config = MLModelConfiguration()
-    config.computeUnits = .all
-    let computePlan = try await MLComputePlan.load(contentsOf: url, configuration: config)
-
-    guard case let .program(program) = computePlan.modelStructure,
-          let mainFunction = program.functions["main"] else {
-        print("Model is not an ML program or has no main function")
+import OSLog
+
+func auditDispatch(of packageURL: URL, units: MLComputeUnits) async throws {
+    let log = Logger(subsystem: "app.inference", category: "compute-plan")
+    let settings = MLModelConfiguration()
+    settings.computeUnits = units
+    let plan = try await MLComputePlan.load(contentsOf: packageURL, configuration: settings)
+    guard case .program(let program) = plan.modelStructure else {
+        log.info("Per-operation dispatch is reported only for ML Program models")
         return
     }
-
-    for operation in mainFunction.block.operations {
-        let opName = operation.operatorName
-        if let deviceUsage = computePlan.deviceUsage(for: operation) {
-            print("  \(opName): \(deviceUsage.preferred)")
-        }
-        if let cost = computePlan.estimatedCost(of: operation) {
-            print("    Estimated weight: \(cost.weight)")
-        }
+    guard let entry = program.functions["main"] else {
+        log.info("No main function in the program")
+        return
+    }
+    for op in entry.block.operations {
+        let device = plan.deviceUsage(for: op).map { "\($0.preferred)" } ?? "unknown"
+        let weight = plan.estimatedCost(of: op)?.weight ?? 0
+        log.debug("\(op.operatorName, privacy: .public) on \(device, privacy: .public) weight \(weight)")
     }
 }
 ```
 
-### Interpreting MLComputePlan Results
+Reading the result:
 
-| Device | Meaning | Action |
-|---|---|---|
-| Neural Engine | Best efficiency and speed for supported ops | Ideal -- no changes needed |
-| GPU | Runs on Metal GPU | Good for large matrix ops |
-| CPU | Fallback for unsupported operations | Investigate if many ops fall here |
-
-If many critical operations fall back to CPU, try `.cpuAndGPU` compute units,
-check for unsupported ANE operations, or re-convert with a different deployment target.
+- **Neural Engine**: the fastest and most efficient place; nothing to do.
+- **GPU**: runs through Metal; good for large matrix work.
+- **CPU**: the fallback for operations the accelerators cannot run. A handful
+  is normal; many, especially heavy ones, deserve investigation.
 
-## Background Model Loading and App Lifecycle
+If critical operations land on the CPU: try `.cpuAndGPU`, look up which
+operations the Neural Engine does not support, or convert again with a
+different minimum deployment target.
 
-Manage model loading and memory across app lifecycle transitions.
+## Lifecycle: warm up and release
 
 ```swift
-@MainActor
+import SwiftUI
+import Observation
+import CoreML
+
 @Observable
-final class AppModelState {
-    var isModelReady = false
-    private let modelManager = ModelManager()
+@MainActor
+final class InferenceLifecycle {
+    private(set) var ready = false
 
-    func warmup() async {
-        do {
-            let config = MLModelConfiguration()
-            config.computeUnits = .all
-            _ = try await modelManager.model(named: "MainClassifier", configuration: config)
-            isModelReady = true
-        } catch {
-            isModelReady = false
-        }
+    func warmUp() async {
+        ready = (try? await ModelStore.shared.prepare("DishClassifier")) != nil
     }
 
-    func handleBackground() async {
-        await modelManager.unloadAll()
-        isModelReady = false
+    func enteredBackground() async {
+        await ModelStore.shared.releaseEverything()
+        ready = false
     }
 }
 
-// SwiftUI integration
-@main
-struct MyApp: App {
-    @State private var modelState = AppModelState()
-    @Environment(\.scenePhase) private var scenePhase
+struct PantryApp: App {
+    @State private var lifecycle = InferenceLifecycle()
+    @Environment(\.scenePhase) private var phase
 
     var body: some Scene {
         WindowGroup {
-            ContentView()
-                .environment(modelState)
-                .task { await modelState.warmup() }
-                .onChange(of: scenePhase) { _, newPhase in
-                    Task {
-                        if newPhase == .background {
-                            await modelState.handleBackground()
-                        } else if newPhase == .active {
-                            await modelState.warmup()
-                        }
-                    }
+            Text(lifecycle.ready ? "Ready" : "Loading")
+                .environment(lifecycle)
+                .task { await lifecycle.warmUp() }
+        }
+        .onChange(of: phase) { _, newPhase in
+            Task {
+                switch newPhase {
+                case .background: await lifecycle.enteredBackground()
+                case .active: await lifecycle.warmUp()
+                default: break
                 }
+            }
         }
     }
 }
 ```
 
-## Error Handling
+In a real app this type carries `@main`; it is omitted here so the snippet
+stays self-contained.
+
+## Errors
 
 ```swift
 import CoreML
 
-func loadAndPredict(modelName: String, input: any MLFeatureProvider) async -> (any MLFeatureProvider)? {
-    let config = MLModelConfiguration()
-    config.computeUnits = .all
-
+func guardedPrediction(_ features: MLFeatureProvider, resource: String) async -> MLFeatureProvider? {
+    guard let location = Bundle.main.url(forResource: resource, withExtension: "mlmodelc") else {
+        return nil
+    }
     do {
-        guard let url = Bundle.main.url(forResource: modelName, withExtension: "mlmodelc") else {
-            print("Model \(modelName) not found in bundle")
-            return nil
-        }
-        let model = try await MLModel.load(contentsOf: url, configuration: config)
-        return try model.prediction(from: input)
+        let engine = try await MLModel.load(contentsOf: location)
+        return try await engine.prediction(from: features)
     } catch {
-        print("Model error: \(error)")
         return nil
     }
 }
 ```
 
-### Common Error Types
-
-| Error | Cause | Fix |
+| Symptom | Usual cause | Fix |
 |---|---|---|
-| `MLModel` file not found | Wrong bundle path or missing target membership | Verify file is in correct target |
-| Compilation failure | Corrupted `.mlpackage` or unsupported ops | Re-export from coremltools |
-| Input shape mismatch | Wrong image dimensions or tensor shape | Match model's expected input shape |
-| Out of memory | Model too large for device | Use smaller model or `.cpuOnly` compute |
-| Compute unit fallback | Ops unsupported on requested device | Use `.all` or check `MLComputePlan` |
+| Model file not found | Wrong path, or the file is not a member of the target | Check target membership and the resource name |
+| Compilation fails | Corrupt `.mlpackage` or operations the OS does not support | Export again from coremltools |
+| Input shape mismatch | Image size or tensor shape differs from the model's description | Match `modelDescription.inputDescriptionsByName` |
+| Memory exhausted | The device cannot hold the model | Smaller or compressed model, or `.cpuOnly` as a last resort |
+| Unexpected CPU fallback | Operations unsupported on the chosen device | Stay on `.all` and inspect `MLComputePlan` |
 
-For MLTensor preprocessing, keep examples to source-confirmed operations. Do not
-use `MLTensor(multiArray)`, `tensor.std()`, `tensor.standardDeviation()`, direct
-lazy-buffer access, or synchronous extraction unless Apple documents that exact
-API and availability.
+MLTensor code should use only operations confirmed in Apple's documentation
+(see the tensor section); invented helpers compile nowhere.
 
-## Testing Patterns
+## Tests with Swift Testing
 
 ```swift
-import Testing
 import CoreML
+import Testing
 
-struct ModelLoadingTests {
-    @Test func loadModelSucceeds() async throws {
-        let config = MLModelConfiguration()
-        config.computeUnits = .cpuOnly // CPU for test stability
-        let model = try MyImageClassifier(configuration: config)
-        #expect(model.model.modelDescription.inputDescriptionsByName.count > 0)
+struct DishClassifierTests {
+    private func model(units: MLComputeUnits) async throws -> MLModel {
+        let url = try #require(Bundle.main.url(forResource: "DishClassifier", withExtension: "mlmodelc"))
+        let settings = MLModelConfiguration()
+        settings.computeUnits = units
+        return try await MLModel.load(contentsOf: url, configuration: settings)
     }
 
-    @Test func predictionReturnsValidOutput() async throws {
-        let config = MLModelConfiguration()
-        config.computeUnits = .cpuOnly
-
-        let model = try MyImageClassifier(configuration: config)
-        let input = try createTestInput(width: 224, height: 224)
-        let output = try model.prediction(input: input)
-
-        #expect(!output.classLabel.isEmpty)
-        #expect(output.classLabelProbs.values.allSatisfy { $0 >= 0 && $0 <= 1 })
+    private func blankFrame() throws -> CVPixelBuffer {
+        var created: CVPixelBuffer?
+        CVPixelBufferCreate(kCFAllocatorDefault, 224, 224, kCVPixelFormatType_32ARGB, nil, &created)
+        return try #require(created)
     }
 
-    @Test func predictionLatencyUnderThreshold() async throws {
-        let config = MLModelConfiguration()
-        config.computeUnits = .all
-
-        let model = try MyImageClassifier(configuration: config)
-        let input = try createTestInput(width: 224, height: 224)
-
-        _ = try model.prediction(input: input) // Warm up
-
-        let start = ContinuousClock.now
-        for _ in 0..<10 {
-            _ = try model.prediction(input: input)
-        }
-        let avgMs = (ContinuousClock.now - start) / 10
+    @Test func loadsWithInputs() async throws {
+        let model = try await model(units: .cpuOnly)
+        #expect(!model.modelDescription.inputDescriptionsByName.isEmpty)
+    }
 
-        #expect(avgMs < .milliseconds(50), "Average prediction time \(avgMs) exceeds 50ms")
+    @Test func producesProbabilities() async throws {
+        let model = try await model(units: .cpuOnly)
+        let verdict = try await model.prediction(from: photoInput(try blankFrame()))
+        let winner = verdict.featureValue(for: "classLabel")?.stringValue ?? ""
+        let probabilities = verdict.featureValue(for: "classLabelProbs")?.dictionaryValue.values.map { $0.doubleValue } ?? []
+        #expect(!winner.isEmpty)
+        #expect(probabilities.allSatisfy { (0...1).contains($0) })
     }
-}
 
-private func createTestPixelBuffer(width: Int, height: Int) throws -> CVPixelBuffer {
-    var pixelBuffer: CVPixelBuffer?
-    let status = CVPixelBufferCreate(
-        kCFAllocatorDefault, width, height,
-        kCVPixelFormatType_32ARGB, nil, &pixelBuffer
-    )
-    guard status == kCVReturnSuccess, let buffer = pixelBuffer else {
-        throw ImageError.pixelBufferCreationFailed
+    @Test func staysUnderLatencyBudget() async throws {
+        let model = try await model(units: .all)
+        let probe = try photoInput(try blankFrame())
+        _ = try await model.prediction(from: probe)
+        let clock = ContinuousClock()
+        let rounds = 10
+        let elapsed = try await clock.measure {
+            for _ in 0..<rounds {
+                _ = try await model.prediction(from: probe)
+            }
+        }
+        #expect(elapsed / rounds < .milliseconds(50))
     }
-    return buffer
 }
 ```
 
-## Memory Management Best Practices
-
-1. **Unload on background.** Unload models when `scenePhase == .background`
-   and reload on return to foreground. iOS reclaims memory aggressively.
-2. **Choose compute units by context.** Use `.all` by default. Consider
-   `.cpuOnly` only when profiling or app policy shows accelerator contention,
-   thermal state, energy budget, deterministic testing, or a legitimate
-   background execution constraint makes CPU the right tradeoff.
-   Do not claim GPU or Neural Engine are categorically unavailable for every
-   background-adjacent task; background behavior depends on app mode, suspension,
-   system policy, thermal state, energy, and contention.
-3. **Prefer compiled models.** `.mlmodelc` loads faster and uses less transient
-   memory than compiling `.mlpackage` at runtime. If a model is downloaded as
-   `.mlmodel` or `.mlpackage`, compile once with `MLModel.compileModel(at:)`,
-   move the `.mlmodelc` out of Core ML's temporary location, and cache it by
-   model version. Do not call `compileModel(at:)` on every launch for the same
-   model.
-4. **Validate on physical devices.** Measure model load, first prediction,
-   repeated predictions, background/foreground transitions, and low-memory
-   behavior on the lowest-memory supported device.
-5. **Share model instances.** Use an actor (like `ModelManager` above) to
-   ensure only one instance of each model exists.
-6. **Release batch providers promptly.** Large `MLArrayBatchProvider` instances
-   hold references to all input data.
+Load and output tests pin `.cpuOnly` for repeatable results. The latency test
+uses `.all`, discards one warm-up call, then averages ten timed runs against a
+50 ms budget; set the budget from the product requirement and run it on
+device, not in the simulator.
+
+## Memory practices
+
+- Unload when `scenePhase` becomes `.background` and reload in the foreground;
+  the system reclaims memory from background apps aggressively.
+- Choose compute units by context: `.all` normally; `.cpuOnly` only when
+  profiling or policy shows contention, thermal limits, energy pressure,
+  deterministic testing or a real background-execution need. Whether a
+  backgrounded app gets the accelerators at all is decided by the system: its
+  execution mode, whether it is suspended, heat, battery and competing work.
+- Ship or cache compiled `.mlmodelc`: it loads faster and needs less transient
+  memory than compiling at run time. Compile downloads once, move them out of
+  the temporary directory, key the cache by version, never recompile the same
+  model on every launch.
+- Measure on real hardware, beginning with the device that has the least
+  RAM: model load, the first call, sustained calls, trips to the background
+  and back, and behavior under memory pressure.
+- One instance per model, shared through an actor.
+- Release large `MLArrayBatchProvider` values promptly; they hold every input
+  in the batch.