Repository Public MIT
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