@swiftbrowser/native 0.18.3 → 0.21.0

package/swift/Sources/SwiftBrowserNative/Host/LanguageModelBridge.swift

@@ -0,0 +1,511 @@
+#if canImport(SwiftUI) && !canImport(FoundationBridge)
+import Foundation
+import SwiftBrowserProtocol
+#if canImport(FoundationModels)
+import FoundationModels
+#endif
+
+/// Foundation Models for a JavaScript app (`LanguageModelSession` in
+/// @swiftbrowser/react; docs/ops-protocol.md, "The on-device language
+/// model"): `languageModel` requests, answered by Apple Intelligence's
+/// on-device model where it can answer (iOS 26 and macOS 26), else by the
+/// app's `LanguageModels.fallback` (LanguageModelProvider.swift), else not at
+/// all. The commands are the page's (Web/src/languageModel.ts):
+///
+/// - `availability` → `{ status: "available" }` or `{ status: "unavailable",
+///   reason }`, the model that would answer, with `download: { size?,
+///   downloaded, progress?, failure? }` where it is a model the app fetches;
+///   and `models`, the choices (Apple Intelligence where it answers, then the
+///   fallback's), each `{ id, name, summary?, selected, download? }`;
+/// - `select` makes the choice `id` answer from the next session on
+///   (remembered across launches);
+/// - `download` starts fetching the app's model, `deleteDownload` removes it;
+/// - `open` makes the app's session `session` with its `instructions` and
+///   `tools` (`[{ name, description, parameters }]`, the arguments a JSON
+///   schema) on that model, `prewarm` loads it, `close` lets it go;
+/// - `toolCall` answers the session's next call of one of its tools, once
+///   the model makes one, as `{ call, name, arguments }` (`{ closed: true }`
+///   once the session is closed); the app runs it and answers with
+///   `toolResult` (`call`, and `output` or `error`), which the model reads;
+/// - `respond` → `{ content }`, the whole response;
+/// - `stream` starts a response as stream `stream`; each `next` answers
+///   `{ content, done }` once the response has grown or ended, the latest
+///   snapshot (a reader slower than the model skips what it missed);
+///   `cancel` stops it.
+///
+/// A failure rejects as a tagged message (`context: …`, `guardrail: …`),
+/// which the app reads back as its `GenerationError` case.
+@MainActor
+final class LanguageModelBridge {
+    /// A response under way, read by `next`.
+    @MainActor
+    private final class Stream {
+        var content = ""
+        var done = false
+        var error: Error?
+        /// Whether the app has had the content as it is now.
+        var delivered = true
+        var waiter: CheckedContinuation<Void, Never>?
+        var task: Task<Void, Never>?
+
+        func wake() {
+            waiter?.resume()
+            waiter = nil
+        }
+    }
+
+    private var sessions: [Int: any LanguageModelProviderSession] = [:]
+    /// Each session's tool calls, waiting for the app.
+    private var relays: [Int: ToolRelay] = [:]
+    private var streams: [Int: Stream] = [:]
+    /// Apple Intelligence's model, once asked for (iOS 26 and macOS 26).
+    private var system: (any LanguageModelProvider)?
+    /// The viewer's choice: `system`, `fallback`, or nil for the default
+    /// (Apple Intelligence where it answers, else the app's model).
+    private static let choiceKey = "SwiftBrowserNative.languageModelChoice"
+    static let systemChoice = "system"
+
+    func handle(_ params: JSONObject) async throws -> JSONValue {
+        switch params["action"]?.string {
+        case "availability":
+            let current = await choice()
+            var answer = Self.json(current.availability, download: current.provider?.downloadState)
+            let models = await modelsJSON(current)
+            if !models.isEmpty, case .object(var object) = answer {
+                object["models"] = .array(models)
+                answer = .object(object)
+            }
+            return answer
+        case "select":
+            guard let id = params["id"]?.string else { throw HostRequestFailure("languageModel: no id") }
+            if id == Self.systemChoice {
+                UserDefaults.standard.set(Self.systemChoice, forKey: Self.choiceKey)
+            } else {
+                UserDefaults.standard.set("fallback", forKey: Self.choiceKey)
+                LanguageModels.fallback?.select(id)
+            }
+            return .object([:])
+        case "download":
+            LanguageModels.fallback?.startDownload()
+            return .object([:])
+        case "deleteDownload":
+            try await LanguageModels.fallback?.deleteDownload()
+            return .object([:])
+        case "open":
+            let id = try Self.int(params, "session")
+            let current = await choice()
+            guard let provider = current.provider, current.availability == .available else {
+                throw LanguageModelError(.unavailable, "the on-device language model is not available")
+            }
+            let relay = ToolRelay()
+            let tools = (params["tools"]?.array ?? []).compactMap { tool -> LanguageModelTool? in
+                guard let object = tool.object, let name = object["name"]?.string else { return nil }
+                return LanguageModelTool(
+                    name: name,
+                    description: object["description"]?.string ?? "",
+                    parameters: object["parameters"] ?? .object(["type": .string("object"), "properties": .object([:])]),
+                    call: { arguments in try await relay.call(name: name, arguments: arguments) }
+                )
+            }
+            sessions[id] = try provider.makeSession(instructions: params["instructions"]?.string, tools: tools)
+            relays[id] = relay
+            return .object([:])
+        case "toolCall":
+            let id = try Self.int(params, "session")
+            guard let relay = relays[id] else { return .object(["closed": .bool(true)]) }
+            return await relay.next()
+        case "toolResult":
+            let id = try Self.int(params, "session")
+            relays[id]?.answer(try Self.int(params, "call"), output: params["output"]?.string, error: params["error"]?.string)
+            return .object([:])
+        case "prewarm":
+            try session(params).prewarm()
+            return .object([:])
+        case "respond":
+            let response = try session(params).streamResponse(to: params["prompt"]?.string ?? "", options: Self.options(params["options"]))
+            var content = ""
+            for try await snapshot in response {
+                content = snapshot
+            }
+            return .object(["content": .string(content)])
+        case "stream":
+            let response = try session(params).streamResponse(to: params["prompt"]?.string ?? "", options: Self.options(params["options"]))
+            stream(response, id: try Self.int(params, "stream"))
+            return .object([:])
+        case "next":
+            return try await next(Self.int(params, "stream"))
+        case "cancel":
+            if let stream = try streams[Self.int(params, "stream")], !stream.done {
+                stream.task?.cancel()
+                finish(stream)
+            }
+            return .object([:])
+        case "close":
+            let id = try Self.int(params, "session")
+            sessions.removeValue(forKey: id)?.close()
+            relays.removeValue(forKey: id)?.close()
+            return .object([:])
+        case let action:
+            throw HostRequestFailure("unsupported: languageModel action \(action ?? "none")")
+        }
+    }
+
+    /// Cancels every response and lets every session go (the app is going away).
+    func stop() {
+        for stream in streams.values {
+            stream.task?.cancel()
+            finish(stream)
+        }
+        streams = [:]
+        for session in sessions.values { session.close() }
+        sessions = [:]
+        for relay in relays.values { relay.close() }
+        relays = [:]
+    }
+
+    /// The model that answers now and its availability: Apple Intelligence's
+    /// where it can answer and the viewer has not chosen the app's model;
+    /// otherwise the app's fallback, unless the system model is only still
+    /// downloading and the viewer has not chosen; otherwise none, for the
+    /// system's reason.
+    private func choice() async -> Choice {
+        var reason = LanguageModelAvailability.Reason.deviceNotEligible
+        let chosen = UserDefaults.standard.string(forKey: Self.choiceKey)
+        var systemAnswers = false
+        #if canImport(FoundationModels)
+        if #available(iOS 26.0, macOS 26.0, *) {
+            let provider = system ?? FoundationModelsProvider()
+            system = provider
+            let availability = await provider.availability()
+            systemAnswers = availability == .available
+            if systemAnswers, chosen != "fallback" || LanguageModels.fallback == nil {
+                return Choice(provider: provider, availability: availability, systemAnswers: true, isFallback: false)
+            }
+            if case .unavailable(let systemReason) = availability { reason = systemReason }
+        }
+        #endif
+        if let fallback = LanguageModels.fallback, systemAnswers || reason != .modelNotReady || chosen == "fallback" {
+            return Choice(provider: fallback, availability: await fallback.availability(), systemAnswers: systemAnswers, isFallback: true)
+        }
+        return Choice(provider: nil, availability: .unavailable(reason), systemAnswers: systemAnswers, isFallback: false)
+    }
+
+    private struct Choice {
+        let provider: (any LanguageModelProvider)?
+        let availability: LanguageModelAvailability
+        /// Whether Apple Intelligence can answer, chosen or not.
+        let systemAnswers: Bool
+        let isFallback: Bool
+    }
+
+    /// The models the viewer can choose: Apple Intelligence where it answers,
+    /// then the fallback's; none when there is no choice to make.
+    private func modelsJSON(_ current: Choice) async -> [JSONValue] {
+        var models: [JSONValue] = []
+        if current.systemAnswers {
+            models.append(.object([
+                "id": .string(Self.systemChoice),
+                "name": .string("Apple Intelligence"),
+                "summary": .string("Built into this device"),
+                "selected": .bool(!current.isFallback),
+            ]))
+        }
+        if let fallback = LanguageModels.fallback {
+            let choices = fallback.choices
+            for choice in choices {
+                var object: JSONObject = [
+                    "id": .string(choice.id),
+                    "name": .string(choice.name),
+                    "selected": .bool(current.isFallback && choice.id == fallback.selectedChoice),
+                ]
+                if let summary = choice.summary { object["summary"] = .string(summary) }
+                if let download = choice.download { object["download"] = Self.json(download) }
+                models.append(.object(object))
+            }
+        }
+        return models.count > 1 ? models : []
+    }
+
+    private func session(_ params: JSONObject) throws -> any LanguageModelProviderSession {
+        let id = try Self.int(params, "session")
+        guard let session = sessions[id] else { throw HostRequestFailure("languageModel: no session \(id)") }
+        return session
+    }
+
+    private func stream(_ response: AsyncThrowingStream<String, Error>, id: Int) {
+        let stream = Stream()
+        streams[id] = stream
+        stream.task = Task { @MainActor [weak self] in
+            do {
+                for try await snapshot in response {
+                    if stream.done { break }
+                    stream.content = snapshot
+                    stream.delivered = false
+                    stream.wake()
+                }
+            } catch {
+                if !Task.isCancelled { stream.error = error }
+            }
+            self?.finish(stream)
+        }
+    }
+
+    private func finish(_ stream: Stream) {
+        guard !stream.done else { return }
+        stream.done = true
+        stream.delivered = false
+        stream.wake()
+    }
+
+    private func next(_ id: Int) async throws -> JSONValue {
+        guard let stream = streams[id] else { throw HostRequestFailure("languageModel: no stream \(id)") }
+        while stream.delivered {
+            await withCheckedContinuation { stream.waiter = $0 }
+        }
+        stream.delivered = true
+        if stream.done { streams[id] = nil }
+        if let error = stream.error { throw error }
+        return .object(["content": .string(stream.content), "done": .bool(stream.done)])
+    }
+
+    // MARK: Conversions
+
+    static func json(_ availability: LanguageModelAvailability, download: LanguageModelDownload? = nil) -> JSONValue {
+        var object: JSONObject
+        switch availability {
+        case .available:
+            object = ["status": .string("available")]
+        case .unavailable(let reason):
+            object = ["status": .string("unavailable"), "reason": .string(reason.rawValue)]
+        }
+        if let download { object["download"] = json(download) }
+        return .object(object)
+    }
+
+    static func json(_ download: LanguageModelDownload) -> JSONValue {
+        var state: JSONObject = ["downloaded": .bool(download.isDownloaded)]
+        if let size = download.size { state["size"] = .number(Double(size)) }
+        if let progress = download.progress { state["progress"] = .number(progress) }
+        if let failure = download.failure { state["failure"] = .string(failure) }
+        return .object(state)
+    }
+
+    static func options(_ value: JSONValue?) -> LanguageModelOptions {
+        let options = value?.object ?? [:]
+        return LanguageModelOptions(
+            temperature: options["temperature"]?.double,
+            maximumResponseTokens: options["maximumResponseTokens"]?.int,
+            greedy: options["sampling"]?.string == "greedy"
+        )
+    }
+
+    private static func int(_ params: JSONObject, _ key: String) throws -> Int {
+        guard let value = params[key]?.int else { throw HostRequestFailure("languageModel: no \(key)") }
+        return value
+    }
+}
+
+/// A session's tool calls on their way to the app and back: the model's
+/// call waits here until the app, asking with `toolCall`, has run it and
+/// answered with `toolResult`.
+@MainActor
+final class ToolRelay {
+    private struct Call {
+        let id: Int
+        let name: String
+        let arguments: JSONValue
+    }
+
+    private var waiting: [Call] = []
+    private var answers: [Int: CheckedContinuation<String, Error>] = [:]
+    /// The app's `toolCall` request, when it asked before the model called.
+    private var asker: CheckedContinuation<JSONValue, Never>?
+    private var nextID = 1
+    private var closed = false
+
+    /// Hands the call to the app and waits for what it answers.
+    func call(name: String, arguments: JSONValue) async throws -> String {
+        guard !closed else { throw LanguageModelError(.unavailable, "the session is closed") }
+        let id = nextID
+        nextID += 1
+        return try await withCheckedThrowingContinuation { continuation in
+            answers[id] = continuation
+            let call = Call(id: id, name: name, arguments: arguments)
+            if let asker {
+                self.asker = nil
+                asker.resume(returning: Self.json(call))
+            } else {
+                waiting.append(call)
+            }
+        }
+    }
+
+    /// The next call for the app to run, once the model makes one.
+    func next() async -> JSONValue {
+        if !waiting.isEmpty { return Self.json(waiting.removeFirst()) }
+        if closed { return .object(["closed": .bool(true)]) }
+        return await withCheckedContinuation { asker = $0 }
+    }
+
+    func answer(_ id: Int, output: String?, error: String?) {
+        guard let continuation = answers.removeValue(forKey: id) else { return }
+        if let error {
+            continuation.resume(throwing: LanguageModelError(.unavailable, "the tool failed: \(error)"))
+        } else {
+            continuation.resume(returning: output ?? "")
+        }
+    }
+
+    /// The session is gone: the app stops asking, and calls under way fail.
+    func close() {
+        closed = true
+        asker?.resume(returning: .object(["closed": .bool(true)]))
+        asker = nil
+        for continuation in answers.values { continuation.resume(throwing: LanguageModelError(.unavailable, "the session is closed")) }
+        answers = [:]
+        waiting = []
+    }
+
+    private static func json(_ call: Call) -> JSONValue {
+        .object(["call": .number(Double(call.id)), "name": .string(call.name), "arguments": call.arguments])
+    }
+}
+
+#if canImport(FoundationModels)
+/// Apple Intelligence's on-device model as a provider: FoundationModels'
+/// `SystemLanguageModel.default` and `LanguageModelSession`.
+@available(iOS 26.0, macOS 26.0, *)
+@MainActor
+final class FoundationModelsProvider: LanguageModelProvider {
+    func availability() async -> LanguageModelAvailability {
+        // Off the main thread: the first read can take a while (seconds in the Simulator).
+        Self.availability(await Task.detached { SystemLanguageModel.default.availability }.value)
+    }
+
+    func makeSession(instructions: String?, tools: [LanguageModelTool]) throws -> any LanguageModelProviderSession {
+        let bridged: [any Tool] = try tools.map { try BridgedTool($0) }
+        return Session(instructions.map { LanguageModelSession(tools: bridged, instructions: $0) } ?? LanguageModelSession(tools: bridged))
+    }
+
+    /// An app's tool as FoundationModels calls one: its arguments' schema made
+    /// at run time from the JSON schema, the arguments handed on as JSON.
+    struct BridgedTool: Tool {
+        let name: String
+        let description: String
+        let parameters: GenerationSchema
+        let run: @Sendable (JSONValue) async throws -> String
+
+        init(_ tool: LanguageModelTool) throws {
+            name = tool.name
+            description = tool.description
+            parameters = try GenerationSchema(root: Self.schema(tool.parameters, name: "\(tool.name)Arguments"), dependencies: [])
+            run = tool.call
+        }
+
+        func call(arguments: GeneratedContent) async throws -> String {
+            try await run((try? JSONValue.parse(arguments.jsonString)) ?? .object([:]))
+        }
+
+        /// A JSON schema as a generation schema: objects, strings (enums as
+        /// choices), numbers, integers, booleans and arrays.
+        static func schema(_ json: JSONValue, name: String) -> DynamicGenerationSchema {
+            let object = json.object ?? [:]
+            let description = object["description"]?.string
+            if let choices = object["enum"]?.array?.compactMap(\.string), !choices.isEmpty {
+                return DynamicGenerationSchema(name: name, description: description, anyOf: choices)
+            }
+            switch object["type"]?.string {
+            case "object":
+                let required = Set((object["required"]?.array ?? []).compactMap(\.string))
+                let properties = (object["properties"]?.object ?? [:]).sorted { $0.key < $1.key }.map { key, value in
+                    DynamicGenerationSchema.Property(
+                        name: key,
+                        description: value.object?["description"]?.string,
+                        schema: schema(value, name: "\(name)_\(key)"),
+                        isOptional: !required.contains(key)
+                    )
+                }
+                return DynamicGenerationSchema(name: name, description: description, properties: properties)
+            case "array":
+                return DynamicGenerationSchema(arrayOf: schema(object["items"] ?? .object([:]), name: "\(name)_item"))
+            case "integer":
+                return DynamicGenerationSchema(type: Int.self)
+            case "number":
+                return DynamicGenerationSchema(type: Double.self)
+            case "boolean":
+                return DynamicGenerationSchema(type: Bool.self)
+            default:
+                return DynamicGenerationSchema(type: String.self)
+            }
+        }
+    }
+
+    @MainActor
+    final class Session: LanguageModelProviderSession {
+        private let session: LanguageModelSession
+
+        init(_ session: LanguageModelSession) {
+            self.session = session
+        }
+
+        func prewarm() {
+            session.prewarm()
+        }
+
+        func streamResponse(to prompt: String, options: LanguageModelOptions) -> AsyncThrowingStream<String, Error> {
+            let session = session
+            return AsyncThrowingStream { continuation in
+                let task = Task { @MainActor in
+                    do {
+                        for try await snapshot in session.streamResponse(to: prompt, options: FoundationModelsProvider.options(options)) {
+                            continuation.yield(snapshot.content)
+                        }
+                        continuation.finish()
+                    } catch {
+                        continuation.finish(throwing: FoundationModelsProvider.tagged(error))
+                    }
+                }
+                continuation.onTermination = { _ in task.cancel() }
+            }
+        }
+
+        func close() {}
+    }
+
+    static func availability(_ availability: SystemLanguageModel.Availability) -> LanguageModelAvailability {
+        switch availability {
+        case .available:
+            return .available
+        case .unavailable(let reason):
+            switch reason {
+            case .deviceNotEligible: return .unavailable(.deviceNotEligible)
+            case .appleIntelligenceNotEnabled: return .unavailable(.appleIntelligenceNotEnabled)
+            case .modelNotReady: return .unavailable(.modelNotReady)
+            @unknown default: return .unavailable(.deviceNotEligible)
+            }
+        }
+    }
+
+    static func options(_ options: LanguageModelOptions) -> GenerationOptions {
+        GenerationOptions(sampling: options.greedy ? .greedy : nil, temperature: options.temperature, maximumResponseTokens: options.maximumResponseTokens)
+    }
+
+    /// A `GenerationError` as the error the app reads its case from.
+    static func tagged(_ error: Error) -> Error {
+        guard let error = error as? LanguageModelSession.GenerationError else { return error }
+        let kind: LanguageModelError.Kind
+        switch error {
+        case .exceededContextWindowSize: kind = .context
+        case .assetsUnavailable: kind = .unavailable
+        case .guardrailViolation: kind = .guardrail
+        case .unsupportedLanguageOrLocale: kind = .language
+        case .rateLimited: kind = .rateLimited
+        case .concurrentRequests: kind = .concurrent
+        case .refusal: kind = .refusal
+        default: return HostRequestFailure(error.localizedDescription)
+        }
+        return LanguageModelError(kind, error.localizedDescription)
+    }
+}
+#endif
+#endif