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.

Auditors are skills here. Where this router says "Launch some-auditor agent", invoke the matching Codex skill instead — same procedure, no Claude Code agent required.

Available: axiom-audit-foundation-models.

The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run.

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 → 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 policy. axiom-integration (skills/background-assets.md) covers the delivery half.

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)