Skip to content
Back to search

system-one-foundation-models

A lightweight, native Swift 6 bridge integrating TypeSafe AI's Jev System One decision model into Apple's Foundation Models framework.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/peterfriese/system-one-foundation-models with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/peterfriese/system-one-foundation-models'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/peterfriese--system-one-foundation-models/badge.svg)](/listings/peterfriese--system-one-foundation-models)

HTML

<a href="/listings/peterfriese--system-one-foundation-models"><img src="/api/listings/peterfriese--system-one-foundation-models/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Add Package Dependency & Configure Traits

Add `SystemOneFoundationModels` to your `Package.swift` or via Xcode (**File > Add Package Dependencies...**):

dependencies: [
    .package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0")
]

Swift 6.1 Package Traits

Using Swift 6.1 Package Traits ([SE-0402](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0402-package-traits.md)), you can enable precisely the backend capabilities you need, eliminating unnecessary dependencies, cloud secrets, or neural model binaries:

// Default (TypeSafe Jev hosted cloud API):
.package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0")

// On-Device only (Core ML + Apple Neural Engine, zero network/cloud code):
.package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0", traits: ["OnDevice"])

// Remote only (Jev cloud, self-hosted laya-serve HTTP, and Clef; no Core ML binaries):
.package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0", traits: ["Remote"])

// All backends (Core ML, Laya HTTP, Jev cloud, and Cloudflare Clef):
.package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0", traits: ["All"])

| Trait | Type | Description | | :--- | :--- | :--- | | `Jev` *(default)* | Model Boundary | Enables TypeSafe Jev hosted cloud API client (`JevFoundationModels`) | | `Laya` | Model Boundary | Enables on-device Laya decision models via Core ML and Apple Neural Engine (`LayaOnDevice`) | | `LayaServe` | Model Boundary | Enables HTTP transport for self-hosted `laya-serve` instances (`LayaFoundationModels`) | | `Clef` | Model Boundary | Enables Cloudflare Clef and Clef-Flash hosted and local multimodal decision models (`ClefFoundationModels`) | | `OpenAI` | Model Boundary | Enables OpenAI Decisions API (`gpt-6-luna`) remote hosted client (`OpenAIFoundationModels`) | | `OnDevice` | Persona Shorthand | Enables on-device capabilities (activates `["Laya"]`) | | `Remote` | Persona Shorthand | Enables remote hosted and self-hosted decision model clients (activates `["Jev", "LayaServe", "Clef", "OpenAI"]`) | | `All` | Persona Shorthand | Enables all System One model backends and transports (activates `["Jev", "Laya", "LayaServe", "Clef", "OpenAI"]`) |

Which Target Should I Import?

The package is split into focused, modular targets so you only link the code and dependencies your project needs:

| Target / Library | Primary Capability | Network Required | API Key Required | Dependencies | | :--- | :--- | :---: | :---: | :--- | | `LayaOnDevice` | 100% offline inference via Core ML on Apple Neural Engine & GPU | ❌ No | ❌ No | `SystemOneCore` | | `LayaFoundationModels` | Connect to local (`localhost:8000`) or self-hosted `laya-serve` instances | ✅ Yes (Local/LAN) | ❌ No (Optional token) | `SystemOneCore` | | `ClefFoundationModels` | Multimodal decisions (Clef 27B & Clef-Flash 9B) via Cloudflare Workers AI or local runner | ✅ Yes (Workers AI or Local) | Optional (`CLOUDFLARE_API_TOKEN` for cloud) | `SystemOneCore` | | `OpenAIFoundationModels` | Non-autoregressive decisions via OpenAI Decisions API (`gpt-6-luna`) | ✅ Yes (Cloud HTTPS) | ✅ Yes (`OPENAI_API_KEY`) | `SystemOneCore` | | `JevFoundationModels` | Connect to TypeSafe AI cloud API with exponential retries | ✅ Yes (Cloud HTTPS) | ✅ Yes (`TYPESAFE_API_KEY`) | `SystemOneCore` | | `SystemOneCore` | Core abstractions, `@Generable` schema translation, `RoutingPolicy`, offline mocks | ❌ No | ❌ No | None | | `SystemOneFoundationModels` | Umbrella module bundling Core ML, Laya HTTP, Clef, OpenAI, and Jev Cloud backends | Varies by backend | Varies by backend | All above |

2. Choose Your Execution Backend

Option A: On-Device Core ML (Zero Network, Air-Gapped Privacy)

import FoundationModels
import LayaOnDevice

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 472 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # System One for Apple Foundation Models 🧠⚡️
  2. [![Swift 6](https://img.shields.io/badge/Swift-6.0-orange.svg?style=flat&logo=swift)](https://developer.apple.com/swift/)
  3. [![Xcode 27](https://img.shields.io/badge/Xcode-27.0+-blue.svg?style=flat&logo=xcode)](https://developer.apple.com/xcode/)
  4. [![iOS 27.0+](https://img.shields.io/badge/iOS-27.0+-black.svg?style=flat&logo=apple)](https://developer.apple.com/ios/)
  5. [![macOS 27.0+](https://img.shields.io/badge/macOS-27.0+-black.svg?style=flat&logo=apple)](https://developer.apple.com/macos/)
  6. [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fpeterfriese%2Fsystem-one-foundation-models%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/peterfriese/system-one-foundation-models)
  7. [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fpeterfriese%2Fsystem-one-foundation-models%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/peterfriese/system-one-foundation-models)
  8. [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  9. A lightweight, native Swift 6 bridge integrating **System One decision models** into Apple's **Foundation Models** framework (`LanguageModel`, `LanguageModelExecutor`, `@Generable`).
  10. Evaluate strongly typed `@Generable` structs and enums against application state in **15–150ms** with zero hallucinations, calibrated probabilities, and full Apple Intelligence API compatibility across:
  11. - **On-Device Core ML (`LayaOnDevice`)**: Run Laya's 322M (multilingual mmBERT) and 421M (English/typed-decisions ModernBERT) parameter models locally on the Apple Neural Engine and GPU with zero network calls.
  12. - **Self-Hosted HTTP (`LayaFoundationModels`)**: Connect to `laya-serve` (PR #31 merged into `NandhaKishorM/laya`) speaking the Jev-compatible `POST /v1/systemone` protocol with presets for `localhost:8000`, `localhost:8770`, and hosted `api.impossibl.com`.
  13. - **Cloudflare Clef (`ClefFoundationModels`)**: Run open-weight multimodal decision models—**Clef (27B)** and **Clef-Flash (9B)**—running via Cloudflare Workers AI edge, Cloudflare AI Gateway, or local runner (`Tools/ClefLocalRunner`), judging camera frames and image attachments alongside text in a single feed-forward pass.
  14. - **OpenAI Decisions (`OpenAIFoundationModels`)**: Non-autoregressive decision computing via OpenAI's Decisions API (`POST https://api.openai.com/v1/decisions`) powered by **`gpt-6-luna`** with ~150ms latency, zero output token billing ($0.10/1M input, $0.00 output), and enterprise multi-tenant header isolation (`OpenAI-Organization`, `OpenAI-Project`).
  15. - **Google Gemini Decisions (`GeminiFoundationModels`)**: High-density multimodal decision evaluation via Google's Gemini Decisions API (`POST https://generativelanguage.googleapis.com/v1beta/decisions`) powered by **`gemini-decision-1`** with up to 256K-token context, up to 1,000 concurrent questions per pass, ~150ms–250ms latency, and zero output token billing ($0.10/1M input, $0.00 output).
  16. - **TypeSafe AI Cloud (`JevFoundationModels`)**: Full backwards-compatible support for hosted TypeSafe Jev endpoints with automated HTTP retries (`RetryPolicy`), cooperative cancellation, and confidence routing (`RoutingPolicy`).
  17. > [!WARNING]
  18. > **Security Advisory: Never Embed API Keys in Mobile Apps**
  19. > Cloud API keys (`GEMINI_API_KEY`, `OPENAI_API_KEY`, `CLOUDFLARE_API_TOKEN`, `TYPESAFE_API_KEY`) must **never** be hardcoded or bundled inside client-side iOS, iPadOS, watchOS, or visionOS application binaries. Anyone can inspect or decompile mobile apps to extract embedded secrets.
  20. >
  21. > **Safe Deployment Patterns:**
  22. > - **On-Device Core ML (`LayaOnDevice`)**: Run models locally on hardware with 100% offline privacy and zero secrets required.
  23. > - **Backend / Server / CLI**: Use `GeminiLanguageModel`, `OpenAILanguageModel`, `ClefLanguageModel`, `LayaLanguageModel`, or `JevLanguageModel` directly in server-side Swift services or CLI tools where environment variables remain server-side.
  24. > - **Mobile Applications with Cloud APIs**: Route mobile requests through your own authenticated reverse proxy protected by Apple App Attest and Firebase App Check using universal `ProxyCredential` (`.appCheck`, `.header`, `.bearer`, `.custom`, or inline `authorize:` closures) and `SystemOneProxyBackend` (see [Mobile Security Guide](docs/mobile-security.md), [ADR-2026-11-12-01](docs/architecture/ADR-2026-11-12-01-universal-proxy-credentials.md), and [Tech Note 0010](tech-notes/0010-proxy-transport-and-dynamic-attestation.md)).
  25. ---
  26. ## 💡 Why Decision Models in Apple Foundation Models?
  27. Traditional Large Language Models (LLMs) are generative text engines: coercing them into producing deterministic structured decisions requires constrained token sampling or prompt-and-parse pipelines.
  28. **System One decision models** evaluate typed questions directly against state in a single feed-forward pass:
  29. | Apple Foundation Models (`@Generable`) | System One Decision Primitive | Behavior |
  30. | :--- | :--- | :--- |
  31. | `Bool` | **`noul`** | Binary judgment with calibrated probability of truth |
  32. | `enum` / String | **`choice`** | Categorical selection across discrete options |
  33. | `@Guide(description: "...")` | **`instructions`** | Semantic criteria evaluated against state |
  34. | `@Guide(.range(...))` | **`score`** | Bounded ordinal rubric scoring |
  35. | `Response.metadata` | **`confidence` & `probabilities`** | Direct access to model uncertainty |
  36. ### Multimodal Visual Decisions
  37. With **Cloudflare Clef (`ClefFoundationModels`)**, System One decision modeling extends natively into visual workflows:
  38. - **Single-Pass Evaluation**: Evaluates camera frames or image attachments (`Attachment(cgImage)`) alongside textual state in a single feed-forward pass—without generative captioning bottlenecks, hallucinations, or multi-stage prompt engineering.
  39. - **Native Apple Foundation Models Vision**: Fully complies with `LanguageModelCapabilities([.guidedGeneration, .vision])`, accepting standard `Prompt` attachments and returning strongly typed `@Generable` outcomes.
  40. - **Calibrated Visual Uncertainty**: Obtains discrete decision outputs (pass/fail, defect categories, priority tiers) alongside continuous probability distributions and confidence scores directly from visual features.
  41. ---
  42. ## 🚀 Quick Start
  43. ### 1. Add Package Dependency & Configure Traits
  44. Add `SystemOneFoundationModels` to your `Package.swift` or via Xcode (**File > Add Package Dependencies...**):
  45. ```swift
  46. dependencies: [
  47. .package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0")
  48. ]
  49. ```
  50. #### Swift 6.1 Package Traits
  51. Using Swift 6.1 Package Traits ([SE-0402](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0402-package-traits.md)), you can enable precisely the backend capabilities you need, eliminating unnecessary dependencies, cloud secrets, or neural model binaries:
  52. ```swift
  53. // Default (TypeSafe Jev hosted cloud API):
  54. .package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0")
  55. // On-Device only (Core ML + Apple Neural Engine, zero network/cloud code):
  56. .package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0", traits: ["OnDevice"])
  57. // Remote only (Jev cloud, self-hosted laya-serve HTTP, Clef, OpenAI, and Gemini; no Core ML binaries):
  58. .package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0", traits: ["Remote"])
  59. // All backends (Core ML, Laya HTTP, Jev cloud, Cloudflare Clef, OpenAI, and Google Gemini):
  60. .package(url: "https://github.com/peterfriese/system-one-foundation-models.git", from: "0.3.0", traits: ["All"])
  61. ```
  62. | Trait | Type | Description |
  63. | :--- | :--- | :--- |
  64. | `Jev` *(default)* | Model Boundary | Enables TypeSafe Jev hosted cloud API client (`JevFoundationModels`) |
  65. | `Laya` | Model Boundary | Enables on-device Laya decision models via Core ML and Apple Neural Engine (`LayaOnDevice`) |
  66. | `LayaServe` | Model Boundary | Enables HTTP transport for self-hosted `laya-serve` instances (`LayaFoundationModels`) |
  67. | `Clef` | Model Boundary | Enables Cloudflare Clef and Clef-Flash hosted and local multimodal decision models (`ClefFoundationModels`) |
  68. | `OpenAI` | Model Boundary | Enables OpenAI Decisions API (`gpt-6-luna`) remote hosted client (`OpenAIFoundationModels`) |
  69. | `Gemini` | Model Boundary | Enables Google Gemini Decisions API (`gemini-decision-1`) remote hosted client (`GeminiFoundationModels`) |
  70. | `OnDevice` | Persona Shorthand | Enables on-device capabilities (activates `["Laya"]`) |
  71. | `Remote` | Persona Shorthand | Enables remote hosted and self-hosted decision model clients (activates `["Jev", "LayaServe", "Clef", "OpenAI", "Gemini"]`) |
  72. | `All` | Persona Shorthand | Enables all System One model backends and transports (activates `["Jev", "Laya", "LayaServe", "Clef", "OpenAI", "Gemini"]`) |
  73. ### Which Target Should I Import?
  74. The package is split into focused, modular targets so you only link the code and dependencies your project needs:
  75. | Target / Library | Primary Capability | Network Required | API Key Required | Dependencies |
  76. | :--- | :--- | :---: | :---: | :--- |
  77. | `LayaOnDevice` | 100% offline inference via Core ML on Apple Neural Engine & GPU | ❌ No | ❌ No | `SystemOneCore` |
  78. | `LayaFoundationModels` | Connect to local (`localhost:8000`) or self-hosted `laya-serve` instances | ✅ Yes (Local/LAN) | ❌ No (Optional token) | `SystemOneCore` |
  79. | `ClefFoundationModels` | Multimodal decisions (Clef 27B & Clef-Flash 9B) via Cloudflare Workers AI or local runner | ✅ Yes (Workers AI or Local) | Optional (`CLOUDFLARE_API_TOKEN` for cloud) | `SystemOneCore` |
  80. | `OpenAIFoundationModels` | Non-autoregressive decisions via OpenAI Decisions API (`gpt-6-luna`) | ✅ Yes (Cloud HTTPS) | ✅ Yes (`OPENAI_API_KEY`) | `SystemOneCore` |
  81. | `GeminiFoundationModels` | Non-autoregressive multimodal decisions via Google Gemini Decisions API (`gemini-decision-1`) | ✅ Yes (Cloud HTTPS) | ✅ Yes (`GEMINI_API_KEY` or `GOOGLE_API_KEY`) | `SystemOneCore` |
  82. | `JevFoundationModels` | Connect to TypeSafe AI cloud API with exponential retries | ✅ Yes (Cloud HTTPS) | ✅ Yes (`TYPESAFE_API_KEY`) | `SystemOneCore` |
  83. | `SystemOneCore` | Core abstractions, `@Generable` schema translation, `RoutingPolicy`, offline mocks | ❌ No | ❌ No | None |
  84. | `SystemOneFoundationModels` | Umbrella module bundling Core ML, Laya HTTP, Clef, OpenAI, Gemini, and Jev Cloud backends | Varies by backend | Varies by backend | All above |
  85. ### 2. Choose Your Execution Backend
  86. #### Option A: On-Device Core ML (Zero Network, Air-Gapped Privacy)
  87. ```swift
  88. import FoundationModels
  89. import LayaOnDevice
  90. // 1. Initialize on-device engine with compiled Core ML model
  91. let engine = try LayaCoreMLEngine(
  92. modelURL: Bundle.main.url(forResource: "LayaModernBERT", withExtension: "mlmodelc")!,
  93. tokenizer: ModernBERTTokenizer.defaultTokenizer()
  94. )
  95. // 2. Initialize native Apple Foundation Models session
  96. let session = LanguageModelSession(model: LayaOnDeviceLanguageModel(engine: engine))
  97. ```
  98. #### Option B: Self-Hosted or Remote Laya HTTP (`laya-serve`)
  99. ```swift
  100. import FoundationModels
  101. import LayaFoundationModels
  102. // 1. Connect to local laya-serve (localhost:8000 or localhost:8770) or hosted endpoint
  103. let model = LayaLanguageModel(endpoint: .localDefault) // or .local(port: 8770) or .hosted
  104. // 2. Initialize native Apple Foundation Models session
  105. let session = LanguageModelSession(model: model)
  106. ```
  107. #### Option C: TypeSafe AI Jev Cloud with Resilience (Server / CLI)
  108. ```swift
  109. import FoundationModels
  110. import JevFoundationModels
  111. // 1. Connect to TypeSafe AI API with automated retry resilience
  112. let retryPolicy = RetryPolicy(maxAttempts: 3, initialDelay: .milliseconds(250), jitter: 0.15)
  113. let jev = JevLanguageModel(apiKey: ProcessInfo.processInfo.environment["TYPESAFE_API_KEY"]!, retryPolicy: retryPolicy)
  114. // 2. Initialize native Apple Foundation Models session
  115. let session = LanguageModelSession(model: jev)
  116. ```
  117. #### Option D: Cloudflare Clef & Clef-Flash Multimodal (`ClefFoundationModels`)
  118. ```swift
  119. import FoundationModels
  120. import ClefFoundationModels
  121. // 1. Connect to Cloudflare Workers AI edge (or .gateway / .local)
  122. let clef = ClefLanguageModel(
  123. endpoint: .workersAI(
  124. accountID: ProcessInfo.processInfo.environment["CLOUDFLARE_ACCOUNT_ID"]!,
  125. model: .clefFlash // or .clef (27B)
  126. ),
  127. apiToken: ProcessInfo.processInfo.environment["CLOUDFLARE_API_TOKEN"]
  128. )
  129. // 2. Initialize native Apple Foundation Models session
  130. let session = LanguageModelSession(model: clef)
  131. // 3. Evaluate multimodal decision with visual Attachment
  132. let prompt = Prompt {
  133. "Inspect the item presented in this camera frame for physical condition, category, and safety compliance."
  134. Attachment(cgImage)
  135. }
  136. let response = try await session.respond(to: prompt, generating: VisualInspectionDecision.self)
  137. ```
  138. #### Option E: OpenAI Decisions API (`gpt-6-luna`)
  139. ```swift
  140. import FoundationModels
  141. import OpenAIFoundationModels
  142. // 1. Connect to OpenAI Decisions API with optional enterprise headers
  143. let openai = OpenAILanguageModel(
  144. apiKey: ProcessInfo.processInfo.environment["OPENAI_API_KEY"]!,
  145. organization: ProcessInfo.processInfo.environment["OPENAI_ORGANIZATION"],
  146. project: ProcessInfo.processInfo.environment["OPENAI_PROJECT"]
  147. )
  148. // 2. Initialize native Apple Foundation Models session
  149. let session = LanguageModelSession(model: openai)
  150. ```
  151. #### Option F: Google Gemini Decisions API (`gemini-decision-1`)
  152. ```swift
  153. import FoundationModels
  154. import GeminiFoundationModels
  155. // 1. Connect to Google Gemini Decisions API (resolves GEMINI_API_KEY or GOOGLE_API_KEY)
  156. let gemini = GeminiLanguageModel(
  157. apiKey: ProcessInfo.processInfo.environment["GEMINI_API_KEY"]
  158. )
  159. // 2. Initialize native Apple Foundation Models session
  160. let session = LanguageModelSession(model: gemini)
  161. ```
  162. #### Option G: Mobile Security & Zero-Secret App Check Gateways (`ProxyCredential` & `SystemOneProxyBackend`)
  163. Every hosted System One model (`GeminiLanguageModel`, `OpenAILanguageModel`, `ClefLanguageModel`, `LayaLanguageModel`, `JevLanguageModel`, and vendor-agnostic `SystemOneLanguageModel`) supports dynamic, per-attempt credential injection (`.appCheck`, `.header`, `.bearer`, `.custom`, or inline `authorize:` trailing closures) with zero third-party SDK dependencies in `SystemOneFoundationModels`:
  164. ```swift
  165. import FoundationModels
  166. import GeminiFoundationModels // or OpenAIFoundationModels / ClefFoundationModels / LayaFoundationModels / JevFoundationModels
  167. import FirebaseAppCheck // or Apple App Attest / OAuth 2.0
  168. // 1. Reusable zero-dependency App Check credential (resolved on every attempt inside the retry loop)
  169. let appCheck = ProxyCredential.appCheck {
  170. try await AppCheck.appCheck().token(forcingRefresh: false).token
  171. }
  172. // Pattern A: Provider-specific passthrough proxy (works identically across Gemini, OpenAI, Clef, Laya, and Jev)
  173. let gemini = GeminiLanguageModel(
  174. proxyEndpoint: URL(string: "https://us-central1-myproject.cloudfunctions.net/geminiDecisions")!,
  175. credential: appCheck
  176. )
  177. // Pattern B: Vendor-agnostic gateway (server routes between Gemini, OpenAI, Clef, Jev, or Laya)
  178. let gatewayModel = SystemOneLanguageModel(
  179. proxyEndpoint: URL(string: "https://us-central1-myproject.cloudfunctions.net/systemone")!,
  180. credential: appCheck,
  181. modelID: "gemini-decision-1"
  182. )
  183. // Or use the inline trailing-closure `authorize:` syntax for multi-header gateways (App Check + User JWT):
  184. let customAuthModel = OpenAILanguageModel(
  185. proxyEndpoint: URL(string: "https://api.mycompany.com/v1/decisions")!
  186. ) { request in
  187. let attestToken = try await AppCheck.appCheck().token(forcingRefresh: false).token
  188. request.setValue(attestToken, forHTTPHeaderField: "X-Firebase-AppCheck")
  189. request.setValue("Bearer \(try await AuthManager.shared.validAccessToken())", forHTTPHeaderField: "Authorization")
  190. }
  191. // 2. Initialize native Apple Foundation Models session
  192. let session = LanguageModelSession(model: gemini)
  193. ```
  194. ### 3. Define Your Decision Type & Evaluate
  195. ```swift
  196. import FoundationModels
  197. @Generable
  198. struct CustomerTriage: Sendable {
  199. @Guide(description: "Is this inquiry urgent or time-sensitive?")
  200. var isUrgent: Bool
  201. @Guide(description: "Which team should handle this request?")
  202. var department: Department
  203. @Guide(description: "Customer frustration score", .range(0...2))
  204. var frustration: Int
  205. }
  206. @Generable
  207. enum Department: String, Sendable {
  208. case billing
  209. case technical
  210. case account
  211. }
  212. // Evaluate state
  213. let ticket = "My account was double charged this morning! Please fix this ASAP."
  214. let response = try await session.respond(to: ticket, generating: CustomerTriage.self)
  215. // Access typed results
  216. let triage = response.content
  217. print("Urgent: \(triage.isUrgent)") // true
  218. print("Route: \(triage.department)") // .billing
  219. print("Frustration: \(triage.frustration)") // 2
  220. // Confidence routing with RoutingPolicy
  221. let policy = RoutingPolicy(escalateBelow: 0.60, autoAtOrAbove: 0.85)
  222. switch response.decision(for: "department", policy: policy) {
  223. case .auto: print("Auto-routed to \(triage.department)")
  224. case .confirm: print("Suggesting \(triage.department) for confirmation")
  225. case .escalate: print("Escalated to human supervisor")
  226. }
  227. let judgement = response.judgement(for: "isUrgent", policy: policy)
  228. if judgement.decision == .auto && judgement.answer == true {
  229. print("Urgency: Decisive True -> Page on-call engineering P0")
  230. }
  231. // Canonical calibrated probability inspection
  232. if let urgencyProb = response.probability(for: "isUrgent") {
  233. print("Urgency probability: \(urgencyProb)")
  234. }
  235. if let typedProb = response.typedProbability(for: "isUrgent") {
  236. print("Decisiveness: \(typedProb.decisiveness)")
  237. }
  238. ```
  239. ### 4. Direct Ergonomic Decision Shortcuts (No `@Generable` Boilerplate)
  240. For ad-hoc questions where declaring a composite `@Generable` struct is unnecessary ceremony, `LanguageModelSession` provides direct, calibrated evaluation shortcuts:
  241. #### Binary Probability (`session.probability`)
  242. Evaluate the calibrated truth probability (0.0 to 1.0) of any statement against state:
  243. ```swift
  244. // Direct statement evaluation
  245. let isUrgent = try await session.probability(
  246. of: "Is this inquiry urgent or time-sensitive?",
  247. state: ticket
  248. )
  249. print("Urgency probability: \(isUrgent)") // e.g. 0.94
  250. // Optional criteria steering
  251. let isSpam = try await session.probability(
  252. of: "Is this message phishing or malicious?",
  253. state: emailBody,
  254. criteria: (
  255. whenTrue: "requests wire transfers, credentials, or urgent gift cards",
  256. whenFalse: "routine correspondence from an existing vendor"
  257. )
  258. )
  259. ```
  260. #### Strongly-Typed Categorical Choice (`session.choice` with `Choosable`)
  261. Evaluate discrete categorization across cases of any Swift enum conforming to `Choosable`:
  262. ```swift
  263. enum TicketPriority: String, Choosable {
  264. case critical = "CRITICAL"
  265. case high = "HIGH"
  266. case normal = "NORMAL"
  267. case low = "LOW"
  268. var optionDescription: String? {
  269. switch self {
  270. case .critical: "Complete service outage affecting all users"
  271. case .high: "Core workflow degraded"
  272. case .normal: "Standard request or minor bug"
  273. case .low: "Cosmetic issue or feature request"
  274. }
  275. }
  276. }
  277. let choice = try await session.choice(
  278. "Select the triage priority",
  279. from: TicketPriority.self,
  280. state: ticket
  281. )
  282. print("Winning case: \(choice.value)") // .critical
  283. print("Model confidence: \(choice.confidence)") // 0.92
  284. print("Distribution: \(choice.distribution)") // [.critical: 0.92, .high: 0.07, ...]
  285. print("P(critical): \(choice.probability(of: .critical))")
  286. ```
  287. #### Dynamic String Options (`session.choice`)
  288. Categorize state among dynamic runtime string options:
  289. ```swift
  290. let routing = try await session.choice(
  291. "Which team should handle this request?",
  292. options: ["billing", "technical", "account"],
  293. state: ticket
  294. )
  295. print("Chosen route: \(routing.value)") // "billing"
  296. print("Confidence: \(routing.confidence)") // 0.95
  297. ```
  298. #### Ordinal Rubric Scoring (`session.score`)
  299. Rate state across ordered rubric levels to obtain both the discrete winner and the probability-weighted continuous mean score:
  300. ```swift
  301. let frustration = try await session.score(
  302. "Rate customer frustration level based on sentiment and phrasing",
  303. levels: ["Calm", "Mildly Annoyed", "Frustrated", "Extremely Irate"],
  304. state: ticket
  305. )
  306. print("Continuous mean: \(frustration.value)") // 2.75 (0...3 scale)
  307. print("Most likely level: \(frustration.mostLikelyLevel)") // "Extremely Irate"
  308. print("Level index: \(frustration.mostLikelyIndex)") // 3
  309. print("Probabilities: \(frustration.probabilities)") // [0.01, 0.04, 0.15, 0.80]
  310. ```
  311. ---
  312. ## 📱 Flagship Reference App: MailTriageApp
  313. Explore [`Examples/MailTriageApp`](Examples/MailTriageApp/README.md), a complete native macOS and iOS reference application showcasing production-grade System One decision models in a modern Apple Mail interface:
  314. - **Intelligent Email Triage**: Automatically categorizes incoming messages, assigns color-coded urgency priority tokens (`P0 Critical`, `P1 High`, `P2 Normal`, `P3 Low`), extracts suggested follow-up actions (Reply, Forward, Compose), and drives batch triage flows.
  315. - **8 Selectable Backends**: Hot-swap backends on the fly in Settings:
  316. 1. **Laya Core ML**: 100% offline inference on the Apple Neural Engine and GPU.
  317. 2. **Laya Local**: Local `laya-serve` instance running on `http://127.0.0.1:8000`.
  318. 3. **Laya Remote**: Hosted Laya instance on `https://api.impossibl.com`.
  319. 4. **Cloudflare Clef**: Serverless Workers AI edge or local runner with multimodal email attachment triage.
  320. 5. **OpenAI Decisions**: OpenAI Decisions API (`gpt-6-luna`) with ~150ms latency and $0.00 output token billing.
  321. 6. **Google Gemini Decisions**: Google Gemini Decisions API (`gemini-decision-1`) with multimodal attachment triage, ~150ms latency, and $0.00 output token billing.
  322. 7. **Jev Cloud**: TypeSafe AI hosted service on `https://api.typesafe.ai`.
  323. 8. **Generative Baseline / Offline Mock**: On-device generative baseline or instant deterministic mock evaluation.
  324. - **Pure Native Architecture**: Built with Swift 6 Complete Strict Concurrency, SwiftUI `@Observable`, FactoryKit dependency injection, Liquid Glass design, and multi-window split views.
  325. - **Catalog of Demos**: Browse [`Examples/README.md`](Examples/README.md) for the full list of runnable CLI tools and sample projects.
  326. ---
  327. ## 🏗️ Architecture
  328. `SystemOneFoundationModels` conforms directly to Apple's public provider protocols (`LanguageModel`, `LanguageModelExecutor`):
  329. ```
  330. ┌────────────────────────────────────────────────────────────────────────┐
  331. │ LanguageModelSession │
  332. │ session.respond(to: "...", generating: CustomerTriage.self) │
  333. └───────────────────────────────────┬────────────────────────────────────┘
  334. │ passes Request (Transcript + Schema)
  335. ▼
  336. ┌────────────────────────────────────────────────────────────────────────┐
  337. │ SystemOneExecutor │
  338. │ • SchemaTranslator: maps @Generable schema to System One questions │
  339. │ • SystemOneBackend (Pluggable Execution Engine): │
  340. │ ├── LayaOnDeviceBackend: Core ML on Apple Neural Engine / GPU │
  341. │ ├── LayaHTTPBackend: POST http://localhost:8000/v1/systemone │
  342. │ ├── ClefHTTPBackend: Cloudflare Workers AI / Gateway / Local │
  343. │ ├── OpenAIDecisionsHTTPBackend: POST https://api.openai.com/... │
  344. │ ├── GeminiDecisionsHTTPBackend: POST https://generativelanguage... │
  345. │ ├── SystemOneProxyBackend: Canonical Vendor-Agnostic Proxy Gateway │
  346. │ └── JevBackend: POST https://api.typesafe.ai/v1/systemone │
  347. │ • ResponseSynthesizer: converts answers into canonical JSON / enums │
  348. └───────────────────────────────────┬────────────────────────────────────┘
  349. │ yields via Channel
  350. ▼
  351. ┌────────────────────────────────────────────────────────────────────────┐
  352. │ LanguageModelExecutorGenerationChannel │
  353. │ • .appendText(synthesizedJSON) -> decoded into CustomerTriage │
  354. │ • .updateMetadata(probabilities, confidence, scores, duration) │
  355. │ • .updateUsage(inputTokens, outputTokens) │
  356. └────────────────────────────────────────────────────────────────────────┘
  357. ```
  358. For more in-depth documentation, see:
  359. * [Getting Started Guide](docs/getting-started.md)
  360. * [Reference Demos & Examples Directory](Examples/README.md)
  361. * [Flagship Reference App (MailTriageApp)](Examples/MailTriageApp/README.md)
  362. * [Architecture Decision Records (ADRs)](docs/architecture/)
  363. * [ADR: Mail Triage System One Engine](docs/architecture/ADR-2026-09-25-mail-triage-system-one-engine.md)
  364. * [ADR: Cloudflare Clef Foundation Models Integration](docs/architecture/ADR-2026-10-03-01-clef-foundation-models-integration.md)
  365. * [ADR: OpenAI Decisions API Integration](docs/architecture/ADR-2026-10-08-01-openai-decisions-models-integration.md)
  366. * [ADR: Google Gemini Decisions API Integration](docs/architecture/ADR-2026-11-11-01-gemini-decisions-models-integration.md)
  367. * [ADR: Universal Proxy Credentials & Hardware-Attested Gateways](docs/architecture/ADR-2026-11-12-01-universal-proxy-credentials.md)
  368. * [Product Requirements Documents (PRDs)](docs/prd/)
  369. * [PRD: Mail Triage Engine](docs/prd/PRD-2026-09-25-mail-triage-system-one-engine.md)
  370. * [PRD: Clef Multimodal Decision Models](docs/prd/PRD-2026-10-03-clef-decision-models.md)
  371. * [PRD: OpenAI Decisions Models (`gpt-6-luna`)](docs/prd/PRD-2026-10-08-openai-decisions-models.md)
  372. * [PRD: Google Gemini Decisions Models (`gemini-decision-1`)](docs/prd/PRD-2026-11-11-gemini-decisions-models.md)
  373. * [PRD: Universal Proxy Credentials & Hardware-Attested Gateways](docs/prd/PRD-2026-11-12-universal-proxy-credentials.md)
  374. * [Repository Audit Sweep & Remediation Report](docs/plans/AUDIT-SWEEP-2026-10-09.md)
  375. * [CLI & Server Deployment Guide](docs/laya-cli-guide.md)
  376. * [Mobile Deployment & Core ML Guide](docs/laya-mobile-guide.md)
  377. * [Confidence Routing Guide](docs/confidence-routing.md)
  378. * [Resilience & Retries Guide](docs/resilience-and-retries.md)
  379. * [Mobile Security Guide (ProxyTransport & App Check)](docs/mobile-security.md)
  380. * [Type Mapping Guide](docs/mapping-guide.md)
  381. * [Tech Notes Index](tech-notes/README.md)
  382. * [Contributing Guide](CONTRIBUTING.md)
  383. ---
  384. ## 📄 License
  385. This project is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.