Thin @objc Swift wrapper exposing Apple's FoundationModels framework to Objective-C and Kotlin/Native (cinterop) consumers.

FoundationModels (Apple's on-device LLM, iOS 26+) is Swift-only — it ships no Objective-C headers. Kotlin/Native cinterop can only consume Objective-C / C interfaces, so it cannot call the framework directly. This package is a minimal @objc surface that translates the Swift-only API (async/await, Instructions, GenerationOptions, streaming AsyncSequence) into completion-handler-based @objc methods that any non-Swift consumer can bind to.

It is consumed by ondevice-llm (a Kotlin Multiplatform on-device LLM library) via Kotlin's swiftPMDependencies, but it has no dependency on Kotlin or ondevice-llm — it is a standalone SwiftPM package.

.package(url: "https://github.com/uny/foundation-models-objc.git", from: "1.0.0")

From Kotlin Multiplatform (build.gradle.kts):

kotlin {
    swiftPMDependencies {
        iosMinimumDeploymentTarget.set("26.0")
        swiftPackage(
            url = url("https://github.com/uny/foundation-models-objc.git"),
            version = exact("1.0.0"),
            products = listOf(product("FoundationModelsObjC")),
        )
    }
}

Types mirror the Swift-only originals with an AFM (Apple Foundation Models) prefix, so the @objc surface reads like the standard API.

Mirror of GenerationOptions, passed to the respond(to:options:) / streamResponse(to:options:) overloads. Sentinel defaults mean "use the model default" the same way the primitive overloads do.

respond / streamResponse deliver failures as NSError in the AFMLanguageModelSession.errorDomain domain. The code is an AFMGenerationErrorCode (e.g. exceededContextWindowSize, guardrailViolation, rateLimited, cancelled) mapped from LanguageModelSession.GenerationError, so non-Swift consumers can branch on the cause. The original framework error is preserved under NSUnderlyingErrorKey.

Generation runs on a Task the session owns, so it can be cancelled from another thread; access to that task is guarded by an OSAllocatedUnfairLock for cross-thread safety.

A session holds one in-flight generation at a time: starting a new respond/streamResponse cancels any previous one, which then completes with an error whose code is AFMGenerationErrorCode.cancelled (the underlying CancellationError is preserved under NSUnderlyingErrorKey). A completion handler may therefore still fire after cancel()/close() (delivering that cancelled error), so callers should be prepared to ignore a completion on an already-cancelled call.

The Swift-only @Generable macro can't cross the @objc boundary, so structured (guided) generation is driven by a JSON Schema string and returns the model's output as a JSON string (GeneratedContent.jsonString):

respond(to: "Extract the contact", jsonSchema: schema, includeSchemaInPrompt: true, options: opts) { json, error in ... }

The supported JSON Schema subset (built by AFMSchemaBuilder): object (properties, required), array (items, minItems/maxItems), string (with optional enum), integer, number, boolean, and description (honored on objects, enums, and every object property regardless of its type; the framework's primitive and array schemas can't carry one, so a description placed directly on a bare scalar or array node — e.g. the root or an array's items — is dropped). Nested schemas are inlined (no $ref). A malformed schema fails with an NSError in AFMSchemaErrorDomain, distinct from generation failures.

Give the model tools it can call mid-generation. Implement AFMToolHandler (one call(argumentsJSON:completion:) method), describe each tool with an AFMTool (name, description, and a JSON Schema for its arguments), and start the session with init(tools:instructions:):

The bridge maps each tool's arguments to a JSON string and the handler's return value to the model, so no @Generable argument type is needed.

transcriptJSON() returns the full conversation history (instructions, prompts, responses, tool calls/outputs) as JSON, and init(transcriptJSON:) restores a session from it — so a multi-turn conversation can be persisted and resumed. The transcript already carries its own Instructions, so the restoring initializer takes no separate instructions argument.

Apache License 2.0. See LICENSE.