SPB Git

Repository Public MIT

Providers.swift 18.7 KB 373 lines swift

1// =============================================================================2//                  SP BOUCHER | SOFTWARE & RESEARCH3//             ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project          : ORIX Astra9// File             : Packages/AstraLocal/Sources/Providers.swift10// Module           : Packages11// Repository       : https://git.spboucher.ai/orix-astra12// Created          : 2026-11-2113// Last Modified    : 2026-11-2114//15// =============================================================================16// AUTHOR & PROFESSIONAL AFFILIATION17// =============================================================================18//19// Author           : Simon-Pierre Boucher20// Position         : Professor of Finance21// Institution      : Université du Québec en Outaouais (UQO)22// Department       : Département des sciences administratives23// Organization     : SP Boucher24//25// Website          : https://spboucher.ai26// Git              : https://git.spboucher.ai27//28// =============================================================================29// OFFICIAL CONTACT DIRECTORY30// =============================================================================31//32// General          : info@spboucher.ai33// Professional     : contact@spboucher.ai34// Direct           : simon@spboucher.ai35// Research         : research@spboucher.ai36// Development      : dev@spboucher.ai37// Support          : support@spboucher.ai38// Security/Admin   : admin@spboucher.ai39// Notifications    : notifications@spboucher.ai40//41// Preferred Contact: support@spboucher.ai42//43// =============================================================================44// COPYRIGHT & INTELLECTUAL PROPERTY45// =============================================================================46//47// Copyright (c) 202648// Simon-Pierre Boucher49//50// All rights reserved where applicable.51//52// This file is governed by the applicable project license,53// copyright notices, institutional agreements and relevant law.54//55// Unless expressly authorized by the applicable license or56// rights holder, copying, redistribution, sublicensing,57// publication and commercial exploitation are not permitted.58//59// Existing third-party rights and notices remain unaffected.60//61// =============================================================================62// CONFIDENTIALITY & SECURITY63// =============================================================================64//65// Classification   : Public66// Distribution     : Public repository; use is governed by the project license67// Security Contact : admin@spboucher.ai68//69// Access to this source does not independently grant permission70// to redistribute or disclose confidential materials.71//72// Do not embed credentials, private keys, access tokens,73// certificates or confidential personal information.74//75// =============================================================================76// LICENSE & MAINTENANCE77// =============================================================================78//79// License          : Proprietary, all rights reserved (see license file)80// License File     : LICENSE81// Maintainer       : Simon-Pierre Boucher82// Technical Contact: dev@spboucher.ai83//84// =============================================================================85// END OF SP BOUCHER SOURCE HEADER86// =============================================================================8788import AstraCore89import Foundation90#if canImport(FoundationModels)91import FoundationModels92#endif9394// MARK: - MLX9596/// On-device models run with MLX. Lists what is installed in the `ModelStore`; generation goes through the `LocalEngine`.97///98/// Stream contract: `.messageStarted`, then `.textDelta` / `.reasoningSummaryDelta` (the model's own thinking block) / tool call events,99/// then `.usage` with token counts measured by the runtime and exactly one `.messageCompleted`. A cancelled generation ends by100/// throwing `AstraError.cancelled` instead of completing.101public struct MLXProvider: ChatProvider {102    public let kind: ProviderKind = .mlx103    public let engine: LocalEngine104    public var store: ModelStore { engine.store }105106    public init(engine: LocalEngine) { self.engine = engine }107108    public func listModels() async throws -> [ModelInfo] {109        let loaded = await engine.snapshot().loaded110        return store.installed().map { model in111            var info = model.card.modelInfo(source: .runtime)112            if let live = loaded.first(where: { $0.modelID == model.id }) {113                info.capabilities.formUnion(live.capabilities)114                if let n = live.contextLength { info.contextLength = n }115            }116            return info117        }118    }119120    public func verify() async throws -> ConnectionStatus {121        if let reason = MLXAvailability.unavailableReason { return ConnectionStatus(ok: false, detail: reason, modelCount: 0) }122        let count = store.installed().count123        return ConnectionStatus(ok: true, detail: count == 0 ? "MLX is available. No model is downloaded yet." : "MLX is available. \(count) model\(count == 1 ? "" : "s") on this device.",124                                modelCount: count)125    }126127    public func stream(_ request: GenerationRequest) -> AsyncThrowingStream<StreamEvent, Error> {128        guard request.model.provider == .mlx else {129            return AsyncThrowingStream { $0.finish(throwing: AstraError.invalidRequest("This request is not for an on-device MLX model.")) }130        }131        if let reason = MLXAvailability.unavailableReason { return AsyncThrowingStream { $0.finish(throwing: AstraError.unsupported(reason)) } }132        return engine.generate(request)133    }134}135136// MARK: - Apple Foundation Models137138/// Why the system model can or cannot be used right now.139public enum AppleFoundationAvailability: Sendable, Hashable {140    case available141    case deviceNotEligible142    case appleIntelligenceOff143    case modelNotReady144    case osTooOld145    case notInThisBuild146    case unknown147148    public var isAvailable: Bool { self == .available }149150    /// Sentence for the UI; nil when available.151    public var reason: String? {152        switch self {153        case .available: nil154        case .deviceNotEligible: "This device does not support Apple Intelligence."155        case .appleIntelligenceOff: "Apple Intelligence is turned off. Turn it on in Settings › Apple Intelligence & Siri."156        case .modelNotReady: "The Apple Intelligence model is not ready yet. The system is still downloading or preparing it."157        case .osTooOld: "The Apple system model needs iOS 26 or macOS 26, or later."158        case .notInThisBuild: "The Apple system model is not available on this platform."159        case .unknown: "The Apple system model is unavailable for a reason the system did not specify."160        }161    }162163    public static func current() -> AppleFoundationAvailability {164        #if canImport(FoundationModels)165        if #available(iOS 26.0, macOS 26.0, *) {166            switch SystemLanguageModel.default.availability {167            case .available: return .available168            case .unavailable(.deviceNotEligible): return .deviceNotEligible169            case .unavailable(.appleIntelligenceNotEnabled): return .appleIntelligenceOff170            case .unavailable(.modelNotReady): return .modelNotReady171            case .unavailable: return .unknown172            }173        }174        return .osTooOld175        #else176        return .notInThisBuild177        #endif178    }179}180181/// Why a generation by the system model failed, independent of the framework's own error types.182enum AppleGenerationFailure: Sendable, Hashable, CaseIterable {183    case contextWindowExceeded, assetsUnavailable, guardrailViolation, refusal, unsupportedGuide, unsupportedLanguage, decodingFailure184    case rateLimited, concurrentRequests, unsupportedCapability, unsupportedTranscriptContent, timeout, cancelled, unknown185186    static var isSimulator: Bool {187        #if targetEnvironment(simulator)188        true189        #else190        false191        #endif192    }193194    /// The error shown to the person. Plain sentences only: no system-localized string, no type name, no error code.195    func astraError(simulator: Bool = AppleGenerationFailure.isSimulator) -> AstraError {196        switch self {197        case .contextWindowExceeded: .contextTooLong("This conversation no longer fits in Apple Intelligence's context window. Start a new chat or shorten it.")198        case .guardrailViolation: .contentFiltered("Apple Intelligence did not answer because the request or the answer was blocked by its safety rules.")199        case .refusal: .contentFiltered("Apple Intelligence declined to answer this request.")200        case .assetsUnavailable: .local("The Apple Intelligence model is not ready on this device. The system is still downloading or preparing it; try again later.")201        case .unsupportedLanguage: .local("Apple Intelligence does not support the language of this conversation.")202        case .unsupportedGuide: .local("Apple Intelligence cannot produce the structured format this request asks for.")203        case .decodingFailure: .local("Apple Intelligence produced an answer that could not be read. Try again.")204        case .rateLimited: .local("The system is limiting requests to Apple Intelligence right now. Try again in a moment.")205        case .concurrentRequests: .local("Apple Intelligence is already answering another request. Wait for it to finish.")206        case .unsupportedCapability: .local("Apple Intelligence on this device does not support something this request needs.")207        case .unsupportedTranscriptContent: .local("This conversation contains content Apple Intelligence cannot read.")208        case .timeout: .local("Apple Intelligence took too long to answer. Try again.")209        case .cancelled: .cancelled210        case .unknown:211            .local("Apple Intelligence could not answer this request." + (simulator212                ? " The system model reports itself as available in the iOS Simulator, but generation may not work there; try on a physical device." : ""))213        }214    }215}216217/// The system language model (Apple Intelligence). Nothing to download: it is either present on the device or not.218///219/// Multi-turn conversations are replayed through a real `Transcript` (instructions, prompts, responses). Tool calls and images are not220/// supported by this adapter. Token counts are reported only on OS 27 and later, where the framework provides them; before that, none.221public struct AppleFoundationProvider: ChatProvider {222    public let kind: ProviderKind = .appleFoundation223    public static let modelID = "apple.system-language-model"224    public static let modelRef = ModelRef(provider: .appleFoundation, modelID: modelID)225    let availabilityProbe: @Sendable () -> AppleFoundationAvailability226227    public init(availability: @escaping @Sendable () -> AppleFoundationAvailability = { .current() }) { availabilityProbe = availability }228229    public var availability: AppleFoundationAvailability { availabilityProbe() }230231    /// The single system model, only while it can be used. It cannot be downloaded or removed by the app.232    public func listModels() async throws -> [ModelInfo] {233        guard availability.isAvailable else { return [] }234        return [ModelInfo(ref: Self.modelRef, displayName: "Apple Intelligence",235                          summary: "The system model, provided and updated by the operating system.", contextLength: Self.contextSize(),236                          capabilities: [.text], source: .runtime, vendor: "Apple")]237    }238239    public func verify() async throws -> ConnectionStatus {240        let a = availability241        return ConnectionStatus(ok: a.isAvailable, detail: a.reason ?? "The Apple system model is ready on this device.", modelCount: a.isAvailable ? 1 : 0)242    }243244    static func contextSize() -> Int? {245        #if canImport(FoundationModels)246        if #available(iOS 26.0, macOS 26.0, *) { return SystemLanguageModel.default.contextSize }247        #endif248        return nil249    }250251    public func stream(_ request: GenerationRequest) -> AsyncThrowingStream<StreamEvent, Error> {252        if let reason = availability.reason { return AsyncThrowingStream { $0.finish(throwing: AstraError.unsupported(reason)) } }253        if !request.tools.isEmpty || request.messages.contains(where: { $0.role == .tool || !$0.toolCalls.isEmpty }) {254            return AsyncThrowingStream { $0.finish(throwing: AstraError.unsupported("Tool calling is not available with the Apple system model in this app.")) }255        }256        if request.messages.contains(where: { !$0.images.isEmpty }) {257            return AsyncThrowingStream { $0.finish(throwing: AstraError.unsupported("The Apple system model does not read images in this app.")) }258        }259        guard let last = request.messages.last, last.role == .user else {260            return AsyncThrowingStream { $0.finish(throwing: AstraError.invalidRequest("The conversation must end with a user message.")) }261        }262        #if canImport(FoundationModels)263        if #available(iOS 26.0, macOS 26.0, *) {264            return AsyncThrowingStream { continuation in265                let task = Task { await Self.run(request, prompt: last.text, continuation) }266                continuation.onTermination = { _ in task.cancel() }267            }268        }269        #endif270        return AsyncThrowingStream { $0.finish(throwing: AstraError.unsupported(AppleFoundationAvailability.osTooOld.reason ?? "")) }271    }272273    #if canImport(FoundationModels)274    @available(iOS 26.0, macOS 26.0, *)275    static func transcript(system: String?, history: [PromptMessage]) -> Transcript {276        var entries: [Transcript.Entry] = []277        if let system, !system.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {278            entries.append(.instructions(Transcript.Instructions(segments: [.text(Transcript.TextSegment(content: system))], toolDefinitions: [])))279        }280        for message in history {281            let segment = Transcript.Segment.text(Transcript.TextSegment(content: message.text))282            switch message.role {283            case .user: entries.append(.prompt(Transcript.Prompt(segments: [segment])))284            case .assistant: entries.append(.response(Transcript.Response(assetIDs: [], segments: [segment])))285            case .tool: break286            }287        }288        return Transcript(entries: entries)289    }290291    @available(iOS 26.0, macOS 26.0, *)292    static func run(_ request: GenerationRequest, prompt: String, _ continuation: AsyncThrowingStream<StreamEvent, Error>.Continuation) async {293        let session = LanguageModelSession(transcript: transcript(system: request.system, history: Array(request.messages.dropLast())))294        let options = GenerationOptions(temperature: request.parameters.temperature, maximumResponseTokens: request.parameters.maxOutputTokens)295        continuation.yield(.messageStarted(MessageStart(reportedModel: modelID, servedBy: "Apple Intelligence")))296        var emitted = ""297        var usage: TokenUsage?298        do {299            for try await snapshot in session.streamResponse(to: prompt, options: options) {300                if Task.isCancelled { break }301                if #available(iOS 27.0, macOS 27.0, *) {302                    let u = snapshot.usage303                    if u.input.totalTokenCount > 0 || u.output.totalTokenCount > 0 {304                        usage = TokenUsage(inputTokens: u.input.totalTokenCount, outputTokens: u.output.totalTokenCount,305                                           cachedInputTokens: u.input.cachedTokenCount > 0 ? u.input.cachedTokenCount : nil,306                                           reasoningTokens: u.output.reasoningTokenCount > 0 ? u.output.reasoningTokenCount : nil)307                    }308                }309                let full = snapshot.content310                guard full.count > emitted.count, full.hasPrefix(emitted) else { continue }311                continuation.yield(.textDelta(String(full.dropFirst(emitted.count))))312                emitted = full313            }314        } catch {315            continuation.finish(throwing: Task.isCancelled ? AstraError.cancelled : map(error)); return316        }317        if Task.isCancelled { continuation.finish(throwing: AstraError.cancelled); return }318        // Token counts only when the framework reported them; nothing is estimated here.319        if let usage { continuation.yield(.usage(usage)) }320        continuation.yield(.messageCompleted(.endOfTurn))321        continuation.finish()322    }323324    /// Names the framework's error without keeping it, so the wording below can be tested without the framework running.325    @available(iOS 26.0, macOS 26.0, *)326    static func classify(_ error: Error) -> AppleGenerationFailure {327        if error is CancellationError { return .cancelled }328        if let e = error as? LanguageModelSession.GenerationError {329            switch e {330            case .exceededContextWindowSize: return .contextWindowExceeded331            case .assetsUnavailable: return .assetsUnavailable332            case .guardrailViolation: return .guardrailViolation333            case .unsupportedGuide: return .unsupportedGuide334            case .unsupportedLanguageOrLocale: return .unsupportedLanguage335            case .decodingFailure: return .decodingFailure336            case .rateLimited: return .rateLimited337            case .concurrentRequests: return .concurrentRequests338            case .refusal: return .refusal339            @unknown default: return .unknown340            }341        }342        if #available(iOS 27.0, macOS 27.0, *) {343            if let e = error as? LanguageModelError {344                switch e {345                case .contextSizeExceeded: return .contextWindowExceeded346                case .rateLimited: return .rateLimited347                case .guardrailViolation: return .guardrailViolation348                case .refusal: return .refusal349                case .unsupportedCapability: return .unsupportedCapability350                case .unsupportedTranscriptContent: return .unsupportedTranscriptContent351                case .unsupportedGenerationGuide: return .unsupportedGuide352                case .unsupportedLanguageOrLocale: return .unsupportedLanguage353                case .timeout: return .timeout354                @unknown default: return .unknown355                }356            }357            if let e = error as? LanguageModelSession.Error {358                switch e {359                case .concurrentRequests: return .concurrentRequests360                case .transcriptMutationWhileResponding: return .concurrentRequests361                @unknown default: return .unknown362                }363            }364            if error is SystemLanguageModel.Error { return .assetsUnavailable }365        }366        return .unknown367    }368369    @available(iOS 26.0, macOS 26.0, *)370    static func map(_ error: Error) -> AstraError { classify(error).astraError() }371    #endif372}373
Files main
Menu

Theme