peterfriese/jev-foundation-models: self-hosted tool for developers and homelabbers

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

Evaluate strongly typed @Generable structs and enums against application state in 40–150ms with zero hallucinations, calibrated probabilities, and full Apple Intelligence API compatibility.

[!WARNING] Security Advisory: Never Embed API Keys in Mobile Apps TypeSafe AI API keys (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.

Safe Deployment Patterns:

• Backend / Server / CLI: Use this library directly in server-side Swift services, macOS backend daemons, developer tools, or CLI applications where environment variables are kept server-side.
• Mobile Applications: Route mobile requests through your own authenticated backend gateway or proxy service that securely manages the TypeSafe API key.

💡 Why Decision Models in Apple Foundation Models?

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.

Jev (by TypeSafe AI) is a System One decision model. Rather than generating prose word-by-word, Jev evaluates typed questions directly against state in a single feed-forward pass:

🚀 Quick Start

1. Add Package Dependency

Add jev-foundation-models to your Package.swift or via Xcode (File > Add Package Dependencies...):

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

2. Define Your Decision Type

import FoundationModels

@Generable
struct CustomerTriage {
    @Guide(description: "Is this inquiry urgent or time-sensitive?")
    var isUrgent: Bool

    @Guide(description: "Which team should handle this request?")
    var department: Department

    @Guide(description: "Customer frustration score", .range(0...2))
    var frustration: Int
}

@Generable
enum Department {
    case billing
    case technical
    case account
}

3. Evaluate with LanguageModelSession

import FoundationModels
import JevFoundationModels

// 1. Create the model
let jev = JevLanguageModel(apiKey: ProcessInfo.processInfo.environment["TYPESAFE_API_KEY"]!)

// 2. Initialize native Apple FoundationModels session
let session = LanguageModelSession(model: jev)

// 3. Evaluate state
let ticket = "My account was double charged this morning! Please fix this ASAP."
let response = try await session.respond(to: ticket, generating: CustomerTriage.self)

// 4. Access typed results
let triage = response.content
print("Urgent: \(triage.isUrgent)")             // true
print("Route: \(triage.department)")           // .billing
print("Frustration: \(triage.frustration)")    // 2

// 5. Access calibrated probabilities & confidence from metadata
if let probabilities = response.metadata["probabilities"] {
    print("Probabilities: \(probabilities)")
}

🏗️ Architecture

jev-foundation-models conforms directly to Apple's public provider protocols:

┌────────────────────────────────────────────────────────────────────────┐
│                        LanguageModelSession                            │
│  session.respond(to: "...", generating: CustomerTriage.self)           │
└───────────────────────────────────┬─────────────��──────────────────────┘
                                    │ passes Request (Transcript + Schema)
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                             JevExecutor                                │
│  • SchemaTranslator: maps @Generable schema to Jev questions (noul/choice)
│  • JevClient: POST https://api.typesafe.ai/v1/systemone (40-150ms)     │
│  • ResponseSynthesizer: converts Jev answers into canonical JSON       │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ yields via Channel
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│              LanguageModelExecutorGenerationChannel                    │
│  • .text(synthesizedJSON) -> decoded directly into CustomerTriage      │
│  • .updateMetadata(probabilities, confidence)                          │
└────────────────────────────────────────────────────────────────────────┘

For more in-depth documentation, see:

• Architecture Guide
• Type Mapping Guide
• Tech Notes

🧪 Testing

This package includes a full offline mock transport for deterministic testing without hitting live APIs:

swift test

📱 Sample Applications

1. Duplicate Article Detection (duplicate-article-demo)

Demonstrates a two-layer deduplication system for read-it-later and knowledge-management apps:

• Layer 1 (Deterministic): Catches identical URLs and matching title/byline pairs instantly at 0ms and zero token cost.
• Layer 2 (Jev System One via Foundation Models): Catches rewritten wire stories and syndicated news (different URL, different headline, different byline) using calibrated probabilities and an escape hatch ("Save anyway").

# Run the 3-scenario deduplication walkthrough
swift run duplicate-article-demo

2. Ticket Triage (ticket-triage-demo)

Demonstrates multi-field @Generable evaluation with Bool, enum, and @Guide(.range(...)) score:

# Run with default sample ticket
swift run ticket-triage-demo

# Or evaluate custom text
swift run ticket-triage-demo "Our server deployment failed with error 500."

📄 License

This project is licensed under the Apache License, Version 2.0. See LICENSE for details.