axiom-ios-ai

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

---

Content truncated.