@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/coreml/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: coreml
-description: "Integrate and optimize Core ML models in iOS apps for on-device machine learning inference. Covers model loading (.mlmodelc, .mlpackage), predictions with auto-generated classes and MLFeatureProvider, compute unit configuration (CPU, GPU, Neural Engine), MLTensor, VNCoreMLRequest, MLComputePlan, multi-model pipelines, and deployment strategies. Use when loading Core ML models, making predictions, configuring compute units, or profiling model performance."
+description: "Integrate Core ML models in iOS apps for on-device machine learning inference. Covers model loading (.mlmodel, .mlpackage, .mlmodelc), predictions with auto-generated classes and MLFeatureProvider, compute unit configuration (CPU, GPU, Neural Engine), MLTensor, VNCoreMLRequest, MLComputePlan, multi-model pipelines, and deployment strategies. Use when loading Core ML models, making predictions, configuring compute units, or profiling model performance."
 ---
 
 # Core ML Swift Integration
 
 Load, configure, and run Core ML models in iOS apps. This skill covers the
 Swift side: model loading, prediction, MLTensor, profiling, and deployment.
-Target iOS 26+ with Swift 6.2, backward-compatible to iOS 14 unless noted.
+Target iOS 26+ with Swift 6.3, backward-compatible to iOS 14 unless noted.
 
 > **Scope boundary:** Python-side model conversion, optimization (quantization,
 > palettization, pruning), and framework selection live in the `apple-on-device-ai`
 > skill. This skill owns Swift integration only.
 
-See `references/coreml-swift-integration.md` for complete code patterns including
+See [references/coreml-swift-integration.md](references/coreml-swift-integration.md) for complete code patterns including
 actor-based caching, batch inference, image preprocessing, and testing.
 
 ## Contents
@@ -37,7 +37,7 @@ actor-based caching, batch inference, image preprocessing, and testing.
 
 ### Auto-Generated Classes
 
-When you drag a `.mlpackage` or `.mlmodelc` into Xcode, it generates a Swift
+When you add a `.mlmodel` or `.mlpackage` to an app target, Xcode generates a Swift
 class with typed input/output. Use this whenever possible.
 
 ```swift
@@ -61,7 +61,7 @@ let modelURL = Bundle.main.url(
 let model = try MLModel(contentsOf: modelURL, configuration: config)
 ```
 
-### Async Loading (iOS 16+)
+### Async Loading (iOS 15+)
 
 Load models without blocking the main thread. Prefer this for large models.
 
@@ -72,18 +72,22 @@ let model = try await MLModel.load(
 )
 ```
 
-### Compile at Runtime
+### Compile at Runtime (iOS 16+)
 
 Compile a `.mlpackage` or `.mlmodel` to `.mlmodelc` on device. Useful for
-models downloaded from a server.
+models downloaded from a server. Do this once per model version, not on every
+launch.
 
 ```swift
 let compiledURL = try await MLModel.compileModel(at: packageURL)
-let model = try MLModel(contentsOf: compiledURL, configuration: config)
+let model = try await MLModel.load(contentsOf: compiledURL, configuration: config)
 ```
 
-Cache the compiled URL -- recompiling on every launch wastes time. Copy
-`compiledURL` to a persistent location (e.g., Application Support).
+Cache the compiled URL -- recompiling on every launch is a bug. Copy
+`compiledURL` to a persistent location (e.g., Application Support). When
+reviewing runtime-loaded models, call out both facts together: async
+`MLModel.compileModel(at:)` is iOS 16+, and compiled models must be cached so the
+app does not recompile on every launch.
 
 ## Model Configuration
 
@@ -94,15 +98,15 @@ Cache the compiled URL -- recompiling on every launch wastes time. Copy
 | Value | Uses | When to Choose |
 |---|---|---|
 | `.all` | CPU + GPU + Neural Engine | Default. Let the system decide. |
-| `.cpuOnly` | CPU | Background tasks, audio sessions, or when GPU is busy. |
+| `.cpuOnly` | CPU | Deterministic tests, CPU-only fallbacks, or constrained work after profiling shows accelerator policy, contention, thermal state, or energy budget is the limiting factor. |
 | `.cpuAndGPU` | CPU + GPU | Need GPU but model has ops unsupported by ANE. |
-| `.cpuAndNeuralEngine` | CPU + Neural Engine | Best energy efficiency for compatible models. |
+| `.cpuAndNeuralEngine` (iOS 16+) | CPU + Neural Engine | Best energy efficiency for compatible models. |
 
 ```swift
 let config = MLModelConfiguration()
 config.computeUnits = .cpuAndNeuralEngine
 
-// Allow low-priority background inference
+// Optional fallback for constrained work after profiling and policy review
 config.computeUnits = .cpuOnly
 ```
 
@@ -141,10 +145,14 @@ let output = try model.prediction(from: inputFeatures)
 let label = output.featureValue(for: "classLabel")?.stringValue
 ```
 
-### Async Prediction (iOS 17+)
+### Prediction Inside Async Workflows
+
+`MLModel.prediction(...)` is synchronous. In async pipelines, keep model loading
+async, then run prediction from an actor or non-main task without adding `await`
+to the prediction call.
 
 ```swift
-let output = try await model.prediction(from: inputFeatures)
+let output = try model.prediction(from: inputFeatures)
 ```
 
 ### Batch Prediction
@@ -155,13 +163,18 @@ Process multiple inputs in one call for better throughput.
 let batchInputs = try MLArrayBatchProvider(array: inputs.map { input in
     try MLDictionaryFeatureProvider(dictionary: ["image": MLFeatureValue(pixelBuffer: input)])
 })
-let batchOutput = try model.predictions(from: batchInputs)
+let batchOutput = try model.predictions(fromBatch: batchInputs)
 for i in 0..<batchOutput.count {
     let result = batchOutput.features(at: i)
     print(result.featureValue(for: "classLabel")?.stringValue ?? "unknown")
 }
 ```
 
+Use `predictions(fromBatch:)` when batching without explicit
+`MLPredictionOptions`. Use `predictions(from:options:)` only when passing both an
+`MLBatchProvider` and `MLPredictionOptions`; `predictions(from:)` by itself is
+not the no-options batch API.
+
 ### Stateful Prediction (iOS 18+)
 
 Use `MLState` for models that maintain state across predictions (sequence models,
@@ -170,23 +183,28 @@ LLMs, audio accumulators). Create state once and pass it to each prediction call
 ```swift
 let state = model.makeState()
 
-// Each prediction carries forward the internal model state
+// Each synchronous prediction carries forward the internal model state
 for frame in audioFrames {
     let input = try MLDictionaryFeatureProvider(dictionary: [
         "audio_features": MLFeatureValue(multiArray: frame)
     ])
-    let output = try await model.prediction(from: input, using: state)
+    let output = try model.prediction(from: input, using: state)
     let classification = output.featureValue(for: "label")?.stringValue
 }
 ```
 
-State is not `Sendable` -- use it from a single actor or task. Call
-`model.makeState()` to create independent state for concurrent streams.
+`MLState` is `Sendable`, but `Sendable` does not make one state safe for
+concurrent inference. Predictions using the same state must be serialized; do
+not read or write state buffers while a prediction is in flight. Call
+`model.makeState()` for each independent concurrent stream. If you need
+`MLPredictionOptions`, iOS 18+ also provides the async
+`prediction(from:using:options:)` overload; the same one-in-flight-per-state rule
+still applies.
 
 ## MLTensor (iOS 18+)
 
 `MLTensor` is a Swift-native multidimensional array for pre/post-processing.
-Operations run lazily -- call `.shapedArray(of:)` to materialize results.
+Operations run lazily -- call `await tensor.shapedArray(of:)` to materialize results.
 
 ```swift
 import CoreML
@@ -199,15 +217,20 @@ let zeros = MLTensor(zeros: [3, 224, 224], scalarType: Float.self)
 let reshaped = tensor.reshaped(to: [2, 2])
 
 // Math operations
-let softmaxed = tensor.softmax()
-let normalized = (tensor - tensor.mean()) / tensor.standardDeviation()
+let softmaxed = tensor.softmax(alongAxis: -1)
+let centered = tensor - tensor.mean()
 
-// Interop with MLMultiArray
-let multiArray = try MLMultiArray([1.0, 2.0, 3.0, 4.0])
-let fromMultiArray = MLTensor(multiArray)
-let backToArray = tensor.shapedArray(of: Float.self)
+// Interop with MLShapedArray / MLMultiArray
+let shaped = await tensor.shapedArray(of: Float.self)
+let multiArray = try MLMultiArray(shaped)
+let shapedAgain = MLShapedArray<Float>(multiArray)
 ```
 
+Do not invent `MLTensor` APIs for statistics or bridging. Avoid examples such as
+`MLTensor(multiArray)`, `tensor.std()`, `tensor.standardDeviation()`, direct
+lazy-buffer access, or synchronous extraction; perform unsupported DSP/statistics
+outside the tensor pipeline or with source-confirmed tensor operations.
+
 ## Working with MLMultiArray
 
 `MLMultiArray` is the primary data exchange type for non-image model inputs and
@@ -225,15 +248,12 @@ for i in 0..<128 {
 // Read values
 let value = array[[0, 0, 0] as [NSNumber]].floatValue
 
-// Create from data pointer for zero-copy interop
 let data: [Float] = [1.0, 2.0, 3.0]
-let fromData = try MLMultiArray(dataPointer: UnsafeMutableRawPointer(mutating: data),
-                                 shape: [3],
-                                 dataType: .float32,
-                                 strides: [1])
+let shaped = MLShapedArray(scalars: data, shape: [3])
+let fromShaped = try MLMultiArray(shaped)
 ```
 
-See `references/coreml-swift-integration.md` for advanced MLMultiArray patterns
+See [references/coreml-swift-integration.md](references/coreml-swift-integration.md) for advanced MLMultiArray patterns
 including NLP tokenization and audio feature extraction.
 
 ## Image Preprocessing
@@ -270,7 +290,7 @@ func createPixelBuffer(from cgImage: CGImage, width: Int, height: Int) -> CVPixe
 ```
 
 For additional preprocessing patterns (normalization, center-cropping), see
-`references/coreml-swift-integration.md`.
+[references/coreml-swift-integration.md](references/coreml-swift-integration.md).
 
 ## Multi-Model Pipelines
 
@@ -344,7 +364,7 @@ guard let mainFunction = program.functions["main"] else { return }
 for operation in mainFunction.block.operations {
     let deviceUsage = computePlan.deviceUsage(for: operation)
     let estimatedCost = computePlan.estimatedCost(of: operation)
-    print("\(operation.operatorName): \(deviceUsage?.preferredComputeDevice ?? "unknown")")
+    print("\(operation.operatorName): \(String(describing: deviceUsage?.preferred))")
 }
 ```
 
@@ -360,24 +380,34 @@ Run outside the debugger for accurate results (Xcode: Product > Profile).
 
 ## Model Deployment
 
-### Bundle vs On-Demand Resources
+### Bundle vs Downloaded Assets
 
 | Strategy | Pros | Cons |
 |---|---|---|
 | Bundle in app | Instant availability, works offline | Increases app download size |
-| On-demand resources | Smaller initial download | Requires download before first use |
-| Background Assets (iOS 16+) | Downloads ahead of time | More complex setup |
+| Background Assets | Preferred for large or updateable model assets | Requires asset-pack setup |
+| On-demand resources | Smaller initial download for existing ODR apps | Legacy technology; prefer Background Assets for new work |
 | CloudKit / server | Maximum flexibility | Requires network, longer setup |
 
 ### Size Considerations
 
-- App Store limit: 4 GB for app bundle
-- Cellular download limit: 200 MB (can request exception)
-- Use ODR tags for models > 50 MB
+- For iOS/iPadOS 18+, App Store Connect lists a 4 GB thinned app bundle limit
+  and 8 GB thinned ODR asset-pack limit.
+- Prefer Background Assets for new large or updateable model assets; keep ODR
+  guidance for existing projects that already use it.
 - Pre-compile to `.mlmodelc` to skip on-device compilation
+- For downloaded `.mlmodel` or `.mlpackage` files, compile once with
+  `MLModel.compileModel(at:)`, move the resulting `.mlmodelc` out of Core ML's
+  temporary location, and cache it by model version.
+- Validate memory and performance on physical target devices, especially the
+  lowest-memory supported device. Check model load, first prediction, repeated
+  predictions, background/foreground transitions, and low-memory behavior.
+
+For Background Assets, make the asset pack locally available, resolve the model
+URL, then load the compiled model with `MLModel.load(contentsOf:configuration:)`.
 
 ```swift
-// On-demand resource loading
+// Existing On-Demand Resources project
 let request = NSBundleResourceRequest(tags: ["ml-model-v2"])
 try await request.beginAccessingResources()
 let modelURL = Bundle.main.url(forResource: "LargeModel", withExtension: "mlmodelc")!
@@ -389,15 +419,17 @@ let model = try await MLModel.load(contentsOf: modelURL, configuration: config)
 
 - **Unload on background:** Release model references when the app enters background
   to free GPU/ANE memory. Reload on foreground return.
-- **Use `.cpuOnly` for background tasks:** Background processing cannot use GPU or
-  ANE; setting `.cpuOnly` avoids silent fallback and resource contention.
+- **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.
 - **Share model instances:** Never create multiple `MLModel` instances from the same
   compiled model. Use an actor to provide shared access.
 - **Monitor memory pressure:** Large models (>100 MB) can trigger memory warnings.
   Register for `UIApplication.didReceiveMemoryWarningNotification` and release
   cached models when under pressure.
 
-See `references/coreml-swift-integration.md` for an actor-based model manager with
+See [references/coreml-swift-integration.md](references/coreml-swift-integration.md) for an actor-based model manager with
 lifecycle-aware loading and cache eviction.
 
 ## Common Mistakes
@@ -414,6 +446,13 @@ lifecycle-aware loading and cache eviction.
 **DO:** Use `.all` and let the system choose the optimal compute unit.
 **Why:** `.all` enables Neural Engine and GPU, which are faster and more energy-efficient.
 
+**DON'T:** Claim GPU or Neural Engine are categorically unavailable for all
+background-adjacent work.
+**DO:** Treat background execution as policy-, mode-, contention-, thermal-, and
+energy-dependent, and profile the actual workload on device.
+**Why:** Apps may be suspended, throttled, or limited by their background mode;
+`.cpuOnly` is a tradeoff, not a universal requirement.
+
 **DON'T:** Ignore `MLFeatureValue` type mismatches between input and model expectations.
 **DO:** Match types exactly -- use `MLFeatureValue(pixelBuffer:)` for images, not raw data.
 **Why:** Type mismatches cause cryptic runtime crashes or silent incorrect results.
@@ -445,14 +484,16 @@ lifecycle-aware loading and cache eviction.
 - [ ] Image inputs use Vision pipeline (`CoreMLRequest` iOS 18+ or `VNCoreMLRequest`) for correct preprocessing
 - [ ] `MLComputePlan` checked to verify compute device dispatch (iOS 17.4+)
 - [ ] Batch predictions used when processing multiple inputs
-- [ ] Model size appropriate for deployment strategy (bundle vs ODR)
+- [ ] Model size appropriate for deployment strategy (bundle, Background Assets, ODR)
 - [ ] Memory tested on target devices (especially older devices with less RAM)
 - [ ] Predictions run outside debugger for accurate performance measurement
 
 ## References
 
-- Patterns and code: `references/coreml-swift-integration.md`
+- Patterns and code: [references/coreml-swift-integration.md](references/coreml-swift-integration.md)
 - Model conversion and optimization (Python-side): covered in the `apple-on-device-ai` skill
 - Apple docs: [Core ML](https://sosumi.ai/documentation/coreml) |
   [MLModel](https://sosumi.ai/documentation/coreml/mlmodel) |
-  [MLComputePlan](https://sosumi.ai/documentation/coreml/mlcomputeplan-1w21n)
+  [MLTensor](https://sosumi.ai/documentation/coreml/mltensor) |
+  [MLComputePlan](https://sosumi.ai/documentation/coreml/mlcomputeplan-1w21n) |
+  [Background Assets](https://sosumi.ai/documentation/backgroundassets)

package/pipeline/skills/shared/external/coreml/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "coreml",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Review this Core ML prediction service for iOS 26: it loads a compiled model with MLModel(contentsOf:), calls `try await model.prediction(from:)`, uses `model.predictions(from: batchProvider)`, and says async prediction is available on iOS 17. Provide corrected Swift snippets and availability notes without turning this into model conversion guidance.",
+      "expected_output": "A concise review that keeps model loading asynchronous, corrects prediction and batch prediction API usage, and preserves the Swift integration boundary.",
+      "files": [],
+      "assertions": [
+        "States that stateless MLModel prediction APIs are synchronous and does not put `await` on stateless `model.prediction(...)` calls.",
+        "Uses `MLModel.load(contentsOf:configuration:)` for asynchronous model loading and notes it is available from iOS 15+.",
+        "Uses `predictions(fromBatch:)` for batch prediction when no explicit `MLPredictionOptions` are supplied.",
+        "Notes that `MLModel.compileModel(at:)` async runtime compilation is iOS 16+ when discussing runtime compilation.",
+        "Keeps the answer focused on Swift Core ML integration rather than Python-side conversion, quantization, or framework selection."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Implement snippets for a stateful audio Core ML model that uses MLState and MLTensor preprocessing on iOS 18+. Include the concurrency rules and materialization step. Avoid unsupported tensor APIs.",
+      "expected_output": "Swift snippets that use MLState correctly, serialize stateful predictions, and use source-grounded MLTensor materialization and operations.",
+      "files": [],
+      "assertions": [
+        "Creates state with `model.makeState()` and passes it to `model.prediction(from:using:)` without `await` on the prediction call.",
+        "States that predictions sharing the same `MLState` must be serialized and that state buffers should not be read or written while a prediction is in flight.",
+        "Does not claim `MLState` is non-Sendable.",
+        "Uses `await tensor.shapedArray(of:)` when materializing an `MLTensor`.",
+        "Avoids unsupported examples such as `MLTensor(multiArray)`, `tensor.std()`, and `tensor.standardDeviation()`."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Write a deployment note for a 600 MB Core ML model in an iOS app. Compare bundling, Background Assets, On-Demand Resources, and server delivery; include memory/background compute guidance and App Store size caveats.",
+      "expected_output": "A deployment note that prefers current asset-delivery guidance, avoids stale download-limit claims, and keeps background compute guidance conservative.",
+      "files": [],
+      "assertions": [
+        "Prefers Background Assets for new large or updateable model assets and frames On-Demand Resources as legacy or existing-project guidance.",
+        "Does not repeat a blanket 200 MB cellular download limit or a rule that models over 50 MB must use ODR.",
+        "Mentions checking current App Store Connect size limits or gives the iOS/iPadOS 18+ thinned app bundle and ODR asset-pack limits with appropriate caveats.",
+        "Recommends precompiled `.mlmodelc` assets and physical-device memory/performance validation.",
+        "Softens `.cpuOnly` background guidance to policy, contention, thermal, or energy constraints instead of claiming GPU or Neural Engine are categorically unavailable."
+      ]
+    }
+  ]
+}

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

@@ -1,14 +1,14 @@
 # Core ML Swift Integration Reference
 
 Complete implementation patterns for loading, configuring, and running Core ML
-models in Swift. All patterns target iOS 26+ with Swift 6.2, backward-compatible
+models in Swift. All patterns target iOS 26+ with Swift 6.3, backward-compatible
 to iOS 14 unless noted.
 
 ## Contents
 - Actor-Based Model Loading and Caching
 - Auto-Generated Class Usage
 - Manual MLFeatureProvider
-- Async Prediction Patterns
+- Prediction in Async Workflows
 - MLBatchProvider for Batch Inference
 - Stateful Predictions with MLState (iOS 18+)
 - Image Preprocessing
@@ -116,11 +116,11 @@ final class ClassifierViewModel {
 
             let model = try await modelManager.model(named: "ImageClassifier", configuration: config)
 
-            let pixelBuffer = try image.toPixelBuffer(width: 224, height: 224)
+            let pixelBuffer = try createPixelBuffer(from: image, width: 224, height: 224)
             let input = try MLDictionaryFeatureProvider(dictionary: [
                 "image": MLFeatureValue(pixelBuffer: pixelBuffer),
             ])
-            let output = try await model.prediction(from: input)
+            let output = try model.prediction(from: input)
 
             classLabel = output.featureValue(for: "classLabel")?.stringValue ?? "Unknown"
             confidence = output.featureValue(for: "classLabelProbs")?
@@ -135,7 +135,7 @@ final class ClassifierViewModel {
 
 ## Auto-Generated Class Usage
 
-When you add a `.mlpackage` or `.mlmodelc` to your Xcode project, Xcode
+When you add a `.mlmodel` or `.mlpackage` to your Xcode project, Xcode
 generates a Swift class with typed inputs and outputs.
 
 ```swift
@@ -206,9 +206,13 @@ let input = CustomImageInput(image: pixelBuffer, confidenceThreshold: 0.7)
 let output = try model.prediction(from: input)
 ```
 
-## Async Prediction Patterns
+## Prediction in Async Workflows
 
-### Single Prediction with Swift Concurrency (iOS 17+)
+`MLModel.prediction(...)` is synchronous. Use Swift concurrency to keep loading,
+preprocessing, and caller coordination off the main actor, then call prediction
+without `await`.
+
+### Single Prediction from an Actor
 
 ```swift
 actor PredictionService {
@@ -218,8 +222,8 @@ actor PredictionService {
         self.model = model
     }
 
-    func predict(input: MLFeatureProvider) async throws -> MLFeatureProvider {
-        try await model.prediction(from: input)
+    func predict(input: any MLFeatureProvider) async throws -> any MLFeatureProvider {
+        try model.prediction(from: input)
     }
 }
 ```
@@ -227,20 +231,24 @@ actor PredictionService {
 ### Streaming Predictions
 
 ```swift
-func classifyFrames(_ frames: AsyncStream<CVPixelBuffer>) async throws -> AsyncStream<String> {
+func classifyFrames(_ frames: AsyncStream<CVPixelBuffer>) async throws -> AsyncThrowingStream<String, Error> {
     let model = try await ModelManager().model(named: "Classifier")
 
-    return AsyncStream { continuation in
+    return AsyncThrowingStream { continuation in
         Task {
-            for await frame in frames {
-                let input = try MLDictionaryFeatureProvider(dictionary: [
-                    "image": MLFeatureValue(pixelBuffer: frame),
-                ])
-                let output = try await model.prediction(from: input)
-                let label = output.featureValue(for: "classLabel")?.stringValue ?? "unknown"
-                continuation.yield(label)
+            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)
             }
-            continuation.finish()
         }
     }
 }
@@ -258,7 +266,7 @@ func batchClassify(images: [CVPixelBuffer], model: MLModel) throws -> [(label: S
         ])
     })
 
-    let batchOutput = try model.predictions(from: batchInputs)
+    let batchOutput = try model.predictions(fromBatch: batchInputs)
 
     var results: [(String, Double)] = []
     for i in 0..<batchOutput.count {
@@ -272,6 +280,20 @@ func batchClassify(images: [CVPixelBuffer], model: MLModel) throws -> [(label: S
 }
 ```
 
+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)
+```
+
+Do not write `predictions(from:)` for the no-options batch path; the `from:`
+label belongs to the overload that also takes `options:`.
+
 ## Stateful Predictions with MLState (iOS 18+)
 
 `MLState` enables models that maintain internal state across predictions. This is
@@ -305,7 +327,7 @@ actor AudioClassifier {
             "audio_features": MLFeatureValue(multiArray: audioFeatures)
         ])
 
-        let output = try await model.prediction(from: input, using: state)
+        let output = try model.prediction(from: input, using: state)
         return output.featureValue(for: "label")?.stringValue ?? "unknown"
     }
 
@@ -322,8 +344,14 @@ enum ClassifierError: Error {
 
 ### Key Rules for MLState
 
-- **Not Sendable:** Use `MLState` from a single actor or task. Do not share
-  across concurrency domains.
+- **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
@@ -428,12 +456,12 @@ let mean = tensor1D.mean()
 let argmax = tensor1D.argmax()
 
 // Activation functions
-let softmaxed = tensor1D.softmax()
+let softmaxed = tensor1D.softmax(alongAxis: -1)
 
-// Interop with MLMultiArray
-let multiArray = try MLMultiArray([1.0, 2.0, 3.0])
-let fromMultiArray = MLTensor(multiArray)
-let shaped = tensor1D.shapedArray(of: Float.self) // MLShapedArray
+// Interop with MLShapedArray / MLMultiArray
+let shaped = await tensor1D.shapedArray(of: Float.self) // MLShapedArray<Float>
+let multiArray = try MLMultiArray(shaped)
+let shapedAgain = MLShapedArray<Float>(multiArray)
 
 // Concatenation
 let a = MLTensor([1.0, 2.0])
@@ -568,7 +596,7 @@ func analyzeSentiment(text: String) throws -> (label: String, confidence: Double
 }
 ```
 
-## MLComputePlan Detailed Usage (iOS 17+)
+## MLComputePlan Detailed Usage (iOS 17.4+)
 
 ```swift
 import CoreML
@@ -587,7 +615,7 @@ func profileModel(at url: URL) async throws {
     for operation in mainFunction.block.operations {
         let opName = operation.operatorName
         if let deviceUsage = computePlan.deviceUsage(for: operation) {
-            print("  \(opName): \(deviceUsage.preferredComputeDevice)")
+            print("  \(opName): \(deviceUsage.preferred)")
         }
         if let cost = computePlan.estimatedCost(of: operation) {
             print("    Estimated weight: \(cost.weight)")
@@ -665,7 +693,7 @@ struct MyApp: App {
 ```swift
 import CoreML
 
-func loadAndPredict(modelName: String, input: MLFeatureProvider) async -> MLFeatureProvider? {
+func loadAndPredict(modelName: String, input: any MLFeatureProvider) async -> (any MLFeatureProvider)? {
     let config = MLModelConfiguration()
     config.computeUnits = .all
 
@@ -675,7 +703,7 @@ func loadAndPredict(modelName: String, input: MLFeatureProvider) async -> MLFeat
             return nil
         }
         let model = try await MLModel.load(contentsOf: url, configuration: config)
-        return try await model.prediction(from: input)
+        return try model.prediction(from: input)
     } catch {
         print("Model error: \(error)")
         return nil
@@ -693,6 +721,11 @@ func loadAndPredict(modelName: String, input: MLFeatureProvider) async -> MLFeat
 | 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` |
 
+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.
+
 ## Testing Patterns
 
 ```swift
@@ -755,11 +788,23 @@ private func createTestPixelBuffer(width: Int, height: Int) throws -> CVPixelBuf
 
 1. **Unload on background.** Unload models when `scenePhase == .background`
    and reload on return to foreground. iOS reclaims memory aggressively.
-2. **Use `.cpuOnly` for background processing.** GPU and Neural Engine may not
-   be available in background execution contexts.
+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.
-4. **Share model instances.** Use an actor (like `ModelManager` above) to
+   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.
-5. **Release batch providers promptly.** Large `MLArrayBatchProvider` instances
+6. **Release batch providers promptly.** Large `MLArrayBatchProvider` instances
    hold references to all input data.