axiom-ai

---
name: axiom-ai
description: Use when implementing, testing, or evaluating ANY Apple Intelligence, on-device AI, or speech-to-text feature. Covers Foundation Models, @Generable, LanguageModelSession, Tool protocol, eval suites, model-as-judge scoring, SpeechTranscriber, CoreML.
license: MIT
---

# Apple Intelligence & AI

**You MUST use this skill for ANY Apple Intelligence or Foundation Models work.**

<!-- AXIOM_AUDITOR_INLINE_BEGIN — auto-maintained by scripts/build-inlined-auditors.ts; do not hand-edit -->
> **Not on Claude Code?** Where this router says "Launch `some-auditor` agent", read that auditor's file in this suite and follow it inline — the same procedure, needing only file search and read.
>
> Available here: `skills/foundation-models-auditor.md`.
>
> Agents that need Bash — builds, tests, simulators, crash symbolication — stay Claude Code-only; there is no inline equivalent for those.
<!-- AXIOM_AUDITOR_INLINE_END -->

## When to Use

Use this router when:
- Implementing Apple Intelligence features
- Using Foundation Models
- Working with LanguageModelSession
- Generating structured output with @Generable
- Debugging AI generation issues
- iOS 26 on-device AI

## AI Approach Triage

**First, determine which kind of AI the developer needs:**

| Developer Intent | Route To |
|-----------------|----------|
| On-device text generation (Apple Intelligence) | **Stay here** → Foundation Models skills |
| Custom ML model deployment (PyTorch, TensorFlow) — classic Core ML | **See skills/ios-ml.md** (hub) → conversion / compression / training files |
| Custom **LLM-scale / transformer** model on-device (27-cycle) | **See skills/core-ai.md** → Core AI conversion, runtime, specialization |
| Computer vision (image analysis, OCR, segmentation) | **/skill axiom-vision** → Vision framework |
| Cloud API integration (OpenAI, generic HTTP) | **/skill axiom-networking** → URLSession patterns |
| Cloud Claude integration (Anthropic SDK, Messages API, Claude Agent SDK) | **See `claude-api` skill** (external) → includes automated Opus 4.6 → 4.7 migration |
| Speech-to-text / transcription (SpeechAnalyzer, SpeechTranscriber, mic → transcript) | **See skills/ios-ml.md** → Speech-to-Text section (the ~2-analyzer cap, `OS27` input providers) |
| Turnkey Apple Intelligence UI — suggested actions for a messaging conversation (`OS27`) | **See skills/suggested-actions.md** → drop-in `SuggestedActionsView`, entitlement-gated |
| System AI features (Writing Tools, Genmoji) | No custom code needed — these are system-provided |

**Key boundary: Foundation Models vs ML (custom models)**
- Foundation Models = Apple's on-device LLM framework (LanguageModelSession, @Generable)
- ML = Custom model deployment (CoreML conversion, quantization, MLTensor, speech-to-text)
- If developer says "run my own model" → skills/ios-ml.md. If "use Apple Intelligence" → stay here.

## Training Path Boundaries

When developers say "I need to train / fine-tune / personalize a model," four distinct paths exist. They are often conflated; each has different output, lifecycle, and runtime compatibility.

| Path | Trains | Output | Lifecycle | Routes to |
|------|--------|--------|-----------|-----------|
| **FM custom adapter** (26-cycle only — runtime obsoleted in 27.0) | Apple's frozen on-device 3B LLM (rank-32 LoRA) | `.fmadapter` package, ~160 MB | Build-time per OS version, delivered via Background Assets | `skills/foundation-models-adapters.md` (discipline) + `skills/foundation-models-adapters-ref.md` (toolkit + runtime) + `skills/foundation-models-adapters-diag.md` (failure modes); delivery via `axiom-integration (skills/background-assets.md)` |
| **Core ML `MLUpdateTask`** | Your NN-spec model's fully-connected and convolutional layers | Updated `.mlmodelc` saved to disk | Runtime, per-user (on-device personalization) | `skills/coreml-training.md` |
| **Create ML** | A new Core ML model from scratch / transfer learning | `.mlmodel` | Build-time, on Mac or iOS (per type) | `skills/coreml-training.md` |
| **MLX LM** (`mlx_lm.lora`) | Open-source LLMs on Apple silicon | `adapters/adapters.safetensors` — NOT loadable by Foundation Models | Build-time; not an iOS distribution path | External — outside Axiom scope; treat as adjacent research tool |
| **Server LLM fine-tune** | Cloud-hosted model (e.g., vendor fine-tunes) | Cloud artifact, accessed via API | Build-time; runs in cloud | `/skill axiom-networking` for the API integration; the fine-tune workflow is the vendor's domain |

**Critical distinctions**:
- MLX LM output (`.safetensors`) cannot be loaded into a `LanguageModelSession`. Different toolchain, different deployment target.
- `MLUpdateTask` is **NN-spec only** — does not support ML Program (`.mlpackage`) models from modern PyTorch / TensorFlow conversion. This is the main reason it's rarely used in new projects.
- FM custom adapters are pinned per-base-model version (per-OS). One adapter does NOT serve every device in your install base — see the Approach Triage section in `skills/foundation-models.md` for the deflection ladder.

For the full "which path applies to me?" disambiguation (decision tree, the three week-costing mistakes, per-path routing) → `skills/training-paths.md`.

## Cross-Domain Routing

**Foundation Models + concurrency** (session blocking main thread, UI freezes):
- Foundation Models sessions are async — blocking likely means missing `await` or running on @MainActor
- **Fix here first** using async session patterns in foundation-models skill
- If concurrency issue is broader than Foundation Models → **also invoke axiom-concurrency**

**Foundation Models + data** (@Generable decoding errors, structured output issues):
- @Generable output problems are Foundation Models-specific, NOT generic Codable issues
- **Stay here** → foundation-models-diag handles structured output debugging
- If developer also has general Codable/serialization questions → **also invoke axiom-data**

**Foundation Models + security** (prompt injection, securing agent tools, confirmation gating):
- Threat modeling and mitigations for agentic features (`.onToolCall` confirmation, `.historyTransform` spotlighting/redaction, lock-screen intent policy) → **axiom-security (skills/agentic-security.md)**
- Stay here for the API surface itself (DynamicProfile, tools, sessions)

**Speech-to-text + audio capture** (transcription that fights your audio session):
- `SpeechAnalyzer` / `SpeechTranscriber`, the ~2-analyzer cap, the `OS27` input providers → **stay here** (`skills/ios-ml.md`)
- **The trap**: `CaptureInputSequenceProvider.providerWithSession(...)` (`OS27`) reconfigures your app's default `AVAudioSession`. If the app also records or plays back, the capture/session half of the fix lives in **axiom-media** (`avfoundation-ref`, `camera-capture`) — use `provider(from:in:)` and add its `captureAudioDataOutput` to your own session.

## Routing Logic

### Custom Core ML Work (your own models, not Apple's LLM)

`skills/ios-ml.md` is the hub (deployment, runtime, speech-to-text). The lifecycle stages have dedicated files:

- **Convert** a trained PyTorch/TF/Keras model → `skills/coreml-conversion.md` (`coremltools.convert`, ML Program vs NN-spec, parity validation)
- **Compress** it → `skills/coreml-compression.md` (the PTQ-vs-QAT decision, palettization/quantization/pruning)
- **Train from scratch / personalize on-device** → `skills/coreml-training.md` (Create ML; `MLUpdateTask` and its NN-spec-only limitation)

### Core AI — the 27-cycle path for LLM-scale on-device models (`OS27`)

`skills/core-ai.md` covers Core AI, the on-device inference framework that powers Apple Intelligence and is now open to your apps. Route here (not `skills/ios-ml.md`) when the model is LLM-scale / a transformer, or when the developer needs custom Metal kernels, multi-function assets, ahead-of-time compilation, KV-cache states, or the specialization/caching deployment model. Covers the Python toolchain (`coreai-torch`/`coreai-opt`), the Swift runtime (`import CoreAI` → `AIModel`/`InferenceFunction`/`NDArray`), specialization discipline, and the Foundation Models bridge (`CoreAILanguageModel` from the open-source `coreai-models` package — not a system-framework type).

### Turnkey Apple Intelligence UI — Suggested Actions (`OS27`)

`skills/suggested-actions.md` covers the `SuggestedActions` framework: a drop-in SwiftUI `SuggestedActionsView` that renders Apple-Intelligence-generated suggested actions for a messaging conversation (iOS/macOS/macCatalyst/visionOS 27). This is a **system-provided** feature — you describe the message (`SuggestedActionsMessage`) and add the `com.apple.developer.suggested-actions` entitlement; there's no `LanguageModelSession`, prompt, or `@Generable`. Route here for messaging/chat/email apps that want inline system suggestions. If the developer wants to generate their *own* structured output, that's Foundation Models, not this. The entitlement/capability half also surfaces via **axiom-integration**, which cross-points back here.

### Foundation Models Work

**Implementation patterns** → `skills/foundation-models.md`
- LanguageModelSession basics
- @Generable structured output
- Tool protocol integration
- Streaming with PartiallyGenerated
- Dynamic schemas
- Private Cloud Compute model + multimodal image input (`OS27`)
- WWDC 2025 + 2026 code examples

**API reference** → `skills/foundation-models-ref.md`
- Complete API documentation
- All @Generable examples
- Tool protocol patterns
- Streaming generation patterns
- `OS27`: Private Cloud Compute, multimodal `Attachment` + `ImageReference` tool args, `LanguageModel` protocol + capabilities, reasoning + token usage, Dynamic Profiles (full modifier surface + `@SessionProperty`), Dynamic Instructions, custom model providers (`LanguageModelExecutor`), `LanguageModelError` migration, built-in system tools, improved Foundation Models Instrument

**Diagnostics** → `skills/foundation-models-diag.md`
- AI response blocked
- Generation slow
- Guardrail violations
- Context limits exceeded
- Model unavailable

**Guardrails & safety decisions** → `skills/foundation-models-guardrails.md`
- When to use `permissiveContentTransformations` vs `.default`
- False-positive triage (correct refusal vs over-restrictive)
- Custom safety eval / red-team methodology
- Adapter × guardrail interaction (safety erosion)

**Evaluation-driven development — the discipline (`OS27`)** → `skills/foundation-models-evaluations.md`
- "Is this AI feature actually good?" / "Did that prompt change help?" / about to ship on eyeballed outputs
- Dataset design (golden / edge / adversarial / known-failures, holdout sets, how many samples)
- Judge calibration — the four judge biases, Cohen's kappa > 0.6 before you trust a score
- Guardrails vs the optimization target; why passing metrics can be lying metrics
- Hill-climbing as a controlled experiment (one variable per round)

**Evaluation failures — the suite is lying to you (`OS27`)** → `skills/foundation-models-evaluations-diag.md`
- A metric reads exactly `-1`, or the pass rate went **up** after adding harder samples
- Suite green but no tool calls were ever evaluated; CI green but the model was never available
- SIGABRT after `loadJSON`; SIGTRAP "missing required entitlement" (PCC)
- Judge scores everything the same; Cohen's kappa negative; scores swing run to run
- Won't compile: `if/else` in an `evaluators` block, "unsupported recursion for type alias `Evaluators`"

**Evaluations framework API (`OS27`)** → `skills/foundation-models-evaluations-ref.md`
- Building a regression suite for an AI feature (`Evaluation`, `Metric`, `Evaluator`, run via Swift Testing `.evaluates`)
- Datasets (`ModelSample`/`ArrayLoader`) + synthesizing more (`makeSamples`/`SampleGenerator`)
- Model-as-judge for open-ended output (`ModelJudgeEvaluator`, `ScoringScale`, `.pairwise`)
- Agentic tool-call/trajectory evaluation (`ToolCallEvaluator`, `TrajectoryExpectation`)
- Inspecting results — which samples failed and why (`detailed`, `ResultColumn`), and the error surface

**Custom adapter training (after Approach Triage rungs 1-4)** → `skills/foundation-models-adapters.md`
- Decision discipline (when adapter training is justified vs. rungs 1-4)
- Maintenance contract (per-OS retrain burden, four-axis eval)
- Per-OS variant strategy and runtime fallback
- Dataset construction discipline
- HIG disclosure for adapter-enhanced features

**Adapter toolkit & runtime API** → `skills/foundation-models-adapters-ref.md`
- Python toolkit setup (3.11, 32 GB Apple silicon Mac or Linux GPU)
- Dataset JSONL schema (chat-turn + tool-calling extension)
- `examples.train_adapter`, `examples.train_draft_model`, `examples.generate`, `export.export_fmadapter`
- `SystemLanguageModel.Adapter` runtime API and `AssetError` cases
- Per-base-model-version compatibility matrix
- `com.apple.developer.foundation-model-adapter` entitlement

**Adapter-specific diagnostics** → `skills/foundation-models-adapters-diag.md`
- `compatibleAdapterNotFound`, `invalidAdapterName`, `invalidAsset`
- Tool calls don't fire from adapter
- Adapter consumes context window with trivial prompts
- Accuracy drops after OS update (FB18924722)
- `coremltools.libmilstoragepython` missing on export

**Automated scanning** → Launch `foundation-models-auditor` agent or `/axiom:audit foundation-models`

Detects anti-patterns AND architectural gaps:
- Missing availability checks, main-thread `respond()`, manual JSON parsing, missing specific error catches (guardrail / context size), session created per-tap, no streaming for long output, missing `@Guide` constraints, nested non-`@Generable` types, no fallback UI
- Prompt-injection risk from direct user-text interpolation, `@Generable` enums without `@frozen` (future-case crash), missing Cancel UX, missing transcript trimming, stale availability cache after Settings toggle, partial-output validation gaps, Tool errors indistinguishable from session errors, no retry on transient errors
- **Quality (`OS27`)**: an AI feature shipping with **no evaluation suite** at all; a model judge used **without calibration**; an evaluation that runs but **asserts nothing**
- **Migration (`OS27`)**: deprecated `GenerationError` on a 27 target; a rename-only migration that **drops** `assetsUnavailable` / `concurrentRequests` / `decodingFailure` (they left the enum); error UI reading `recoverySuggestion`, which `LanguageModelError` **no longer implements** and which now silently renders nil

Scores: PRODUCTION-READY / NEEDS HARDENING / FRAGILE

## Decision Tree

1. Custom ML model / CoreML? → **skills/ios-ml.md** hub → convert (`coreml-conversion.md`), compress (`coreml-compression.md`), or train/personalize (`coreml-training.md`). LLM-scale / transformer / 27-cycle custom model? → **skills/core-ai.md** (Core AI)
2. Computer vision / image analysis / OCR? → **/skill axiom-vision**
3. Cloud AI API integration? → **/skill axiom-networking**
4. Implementing Foundation Models / @Generable / Tool protocol? → foundation-models
5. Need API reference / code examples? → foundation-models-ref
6. Debugging AI issues (blocked, slow, guardrails)? → foundation-models-diag
7. Foundation Models + UI freezing? → foundation-models (async patterns) + also invoke axiom-concurrency if needed
8. Considering training a custom adapter? → **foundation-models** Approach Triage (rungs 1-4) FIRST; only after documented rung-1-4 failures → foundation-models-adapters
9. Implementing adapter loading, training pipeline, or runtime selection? → foundation-models-adapters + foundation-models-adapters-ref + axiom-integration (skills/background-assets.md) for delivery
10. Debugging adapter-specific failures (compatibleAdapterNotFound, tool calls don't fire from adapter, accuracy regression after OS update)? → foundation-models-adapters-diag
11. Want automated Foundation Models code scan? → foundation-models-auditor (Agent — detects 14 anti-patterns AND completeness gaps including prompt injection, frozen-enum discipline, transcript trimming, Cancel UX, missing/uncalibrated eval suites; scores PRODUCTION-READY / NEEDS HARDENING / FRAGILE)
12. Measuring whether an AI feature improved/regressed, designing an eval dataset, calibrating a model judge, or about to ship on eyeballed outputs? → **foundation-models-evaluations** (discipline) + **foundation-models-evaluations-ref** (API) — `OS27` Evaluations framework
13. Adding Apple's built-in suggested actions to a messaging/chat/email app (`SuggestedActionsView`, suggested-actions entitlement)? → **skills/suggested-actions.md** (`OS27` — turnkey, system-provided; NOT Foundation Models)

## Anti-Rationalization

| Thought | Reality |
|---------|---------|
| "Foundation Models is just LanguageModelSession" | Foundation Models has @Generable, Tool protocol, streaming, and guardrails. foundation-models covers all. |
| "I'll figure out the AI patterns as I go" | AI APIs have specific error handling and fallback requirements. foundation-models prevents runtime failures. |
| "I've used LLMs before, this is similar" | Apple's on-device models have unique constraints (guardrails, context limits). foundation-models is Apple-specific. |
| "I know the Anthropic SDK already" | Opus 4.7 removed `temperature`, `top_p`, `top_k`, and prefill from the Messages API. Code that worked on 4.6 returns HTTP 400 at runtime. Read `claude-api` (external) before changing model IDs. |
| "We need to train a custom adapter to fix the model's outputs" | Most "we need an adapter" requests resolve via rungs 1-4 of the Approach Triage (prompt engineering, `@Generable`/`@Guide`, tool calling, built-in content-tagging adapter). foundation-models has the ladder; foundation-models-adapters is only justified after each rung's failure is documented. |
| "We trained one adapter, ship it for all our users" | Each `.fmadapter` pins to one base-model version; one adapter does not cover a multi-OS install base. foundation-models-adapters covers per-OS variant strategy and `compatibleAdapterIdentifiers(name:)` runtime selection. |
| "Skip locale-specific eval, our users are mostly English-speaking" | Apple's 2025 tech report groups eval as English-US / English-outside-US / PFIGSCJK. English-only eval against a multi-locale app ships invisible non-English regressions. foundation-models-adapters covers the four-axis eval requirement. |
| "The output looked good on the prompts I tried — ship it" | Five good results say nothing about the five hundred that fail, and the model changes under you on every OS update with no code change on your side. foundation-models-evaluations turns the prompts you already tried by hand into a gate. |
| "Our model judge agrees with me, I spot-checked it" | Your data skews toward decent output, so a judge that always scores high looks aligned on a spot-check and drifts hardest at scale. Apple's own sample judge starts at Cohen's kappa −0.037. foundation-models-evaluations has the calibration protocol. |
| "Just bundle the .fmadapter file in the app" | Apple's docs explicitly prohibit this. Adapters ship via Background Assets `onDemand` policy. axiom-integration (skills/background-assets.md) covers the delivery half. |
| "We'll add a custom adapter for our iOS 27 app" | The custom-adapter runtime (`SystemLanguageModel.Adapter`) is obsoleted in 27.0 and does not compile on a 27 deployment target — no replacement in the 27 SDK. foundation-models-adapters covers the pivot: rungs 1-4 or a custom provider (`LanguageModelExecutor`). |

## External Resources

**Cloud Claude integration (`claude-api` skill, ships outside Axiom).** Opus 4.7 removed `temperature`, `top_p`, `top_k`, and prefill from the Messages API — code that built successfully on 4.6 returns HTTP 400 at runtime, not compile time. The `claude-api` skill automates the migration (model ID swap, sampling-param removal, prefill replacement) and enforces prompt caching from day one. Skipping it costs an afternoon of production debugging when the first 400s arrive.

Apple's on-device Foundation Models and Anthropic's cloud Claude are unrelated stacks; use both in parallel when an app needs both, and treat `claude-api` as mandatory reading before any Claude model-ID change ships.

## Critical Patterns

**foundation-models**:
- LanguageModelSession setup
- @Generable for structured output
- Tool protocol for function calling
- Streaming generation
- Dynamic schema evolution

**foundation-models-diag**:
- Blocked response handling
- Performance optimization
- Guardrail violations
- Context management

## Example Invocations

User: "How do I use Apple Intelligence to generate structured data?"
→ Read: `skills/foundation-models.md`

User: "My AI generation is being blocked"
→ Read: `skills/foundation-models-diag.md`

User: "Show me @Generable examples"
→ Read: `skills/foundation-models-ref.md`

User: "Implement streaming AI generation"
→ Read: `skills/foundation-models.md`

User: "I want to add AI to my app"
→ First ask: Apple Intelligence (Foundation Models) or custom ML model? Route accordingly.

User: "My Foundation Models session is blocking the UI"
→ Read: `skills/foundation-models.md` (async patterns) + also invoke `axiom-concurrency` if needed

User: "Review my Foundation Models code for issues"
→ Invoke: `foundation-models-auditor` agent

User: "I want to run my PyTorch model on device"
→ Read: `skills/ios-ml.md` (classic Core ML conversion, not Foundation Models)

User: "I want to run my own LLM / SAM segmentation model on device" / "convert a PyTorch transformer with Core AI" / "my Core AI model stalls on first launch"
→ Read: `skills/core-ai.md` (Core AI conversion, runtime, specialization & caching)

User: "How do I train a custom adapter for our app's summarization?"
→ Read: `skills/foundation-models.md` (Approach Triage rungs 1-4 FIRST), then `skills/foundation-models-adapters.md` only if rung-1-4 failures are documented

User: "Our adapter loaded fine on iOS 26.0 but throws compatibleAdapterNotFound on 26.1"
→ Read: `skills/foundation-models-adapters-diag.md` (Pattern 1)

User: "What's the toolkit setup for adapter training?"
→ Read: `skills/foundation-models-adapters-ref.md` (Toolkit Setup)

User: "How do we ship a custom adapter to users?"
→ Read: `skills/foundation-models-adapters.md` (runtime lifecycle) + `axiom-integration (skills/background-assets.md)` (delivery)

User: "How do I measure if my prompt change made the tagging feature better?" / "Write an eval suite for my AI feature" / "The output looks good, can we ship?"
→ Read: `skills/foundation-models-evaluations.md` (the discipline — dataset design, guardrails vs optimization target, hill-climbing) + `skills/foundation-models-evaluations-ref.md` (the API — Metrics, `.evaluates`, model-as-judge, tool-call eval)

User: "My model judge is giving weird scores" / "How do I know I can trust the judge?"
→ Read: `skills/foundation-models-evaluations.md` (Judge Discipline — the four biases, Cohen's kappa > 0.6 calibration protocol, debugging from rationales)

User: "My eval metric returns -1" / "Our pass rate went up when we added harder test cases" / "The eval suite passes but I don't think it measured anything"
→ Read: `skills/foundation-models-evaluations-diag.md` (the framework fails silently — a green suite is not evidence a run happened)

User: "Add Apple's suggested actions to my messaging app" / "Show smart/on-device suggested replies for a message thread" / "What's the com.apple.developer.suggested-actions entitlement for?"
→ Read: `skills/suggested-actions.md` (turnkey `SuggestedActionsView`, system-provided — not Foundation Models)