Repository Public MIT
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : ORIX Astra9// File : Packages/AstraProviders/Sources/GeminiProvider.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 Foundation9091/// Google Gemini through the native API (`POST /v1beta/models/{model}:streamGenerateContent?alt=sse`).92///93/// - The key travels in the `x-goog-api-key` header and is never part of a URL.94/// - Gemini 3 and later return a `thoughtSignature` on the first `functionCall` part of a turn and reject (HTTP 400) a95/// tool cycle that does not send it back. Signatures are kept in memory, keyed by tool-call id, and echoed verbatim.96/// When a signature is not available (the app was restarted mid-cycle, or the history comes from another model) the97/// documented placeholder `skip_thought_signature_validator` is sent instead; both paths were verified live on 2026-11-21.98/// - Gemini 2.5 and earlier return no call ids: ids are synthesised from the response id and the call's position.99/// - Thought summaries (`thought: true` parts) are surfaced as `.reasoningSummaryDelta` only when the API returns them.100public struct GeminiProvider: ChatProvider {101 public let kind: ProviderKind = .google102 public static let defaultBaseURL = URL(string: "https://generativelanguage.googleapis.com/v1beta")!103 static let signaturePlaceholder = "skip_thought_signature_validator"104 static let synthesizedIDPrefix = "gemini-call-"105106 private let http: ProviderHTTP107 private let apiKey: KeyProvider108 private let baseURL: URL109110 public init(transport: any HTTPTransport, apiKey: @escaping KeyProvider, diagnostics: (any DiagnosticsSink)? = nil, baseURL: URL = GeminiProvider.defaultBaseURL) {111 self.http = ProviderHTTP(kind: .google, transport: transport, diagnostics: diagnostics)112 self.apiKey = apiKey113 self.baseURL = baseURL114 }115116 static func headers(_ key: String) -> [String: String] { ["x-goog-api-key": key] }117118 /// Google answers an invalid key with HTTP 400 and reason `API_KEY_INVALID`.119 static func normalize(_ failure: ProviderHTTP.Failure) -> ProviderHTTP.Failure {120 var f = failure121 let code = f.body.code ?? "", message = (f.body.message ?? "").lowercased()122 if f.status == 400, code.contains("API_KEY_INVALID") || message.contains("api key not valid") || message.contains("api key expired") { f.status = 401 }123 // A 429 that says when to retry is a rate limit, whatever its wording says about plans and billing.124 if f.status == 429, f.retryAfter != nil, message.contains("billing") || message.contains("credit") { f.body.message = nil; f.body.code = "RESOURCE_EXHAUSTED" }125 return f126 }127128 // MARK: Models129130 public func listModels() async throws -> [ModelInfo] {131 let key = try resolveKey(apiKey, kind: kind, required: true) ?? ""132 var out: [ModelInfo] = []133 var pageToken: String?134 let fetchedAt = Date()135 for _ in 0..<20 {136 var components = URLComponents(url: baseURL.appendingPathComponent("models"), resolvingAgainstBaseURL: false)!137 components.queryItems = [URLQueryItem(name: "pageSize", value: "1000")] + (pageToken.map { [URLQueryItem(name: "pageToken", value: $0)] } ?? [])138 let (json, _) = try await http.json(ProviderHTTP.request(components.url!, headers: Self.headers(key)), secrets: [key], normalize: Self.normalize)139 guard let models = json["models"]?.arrayValue else { throw AstraError.decoding("the model list has no models array") }140 out += models.compactMap { Self.modelInfo($0, fetchedAt: fetchedAt) }141 guard let next = json["nextPageToken"]?.stringValue, !next.isEmpty else { break }142 pageToken = next143 }144 return out145 }146147 static func modelInfo(_ entry: JSONValue, fetchedAt: Date) -> ModelInfo? {148 guard let name = entry["name"]?.stringValue else { return nil }149 let id = name.hasPrefix("models/") ? String(name.dropFirst("models/".count)) : name150 let methods = entry["supportedGenerationMethods"]?.arrayValue?.compactMap(\.stringValue) ?? []151 guard methods.contains("generateContent"), isTextModel(id) else { return nil }152 let ref = ModelRef(provider: .google, modelID: id)153 var capabilities: Set<Capability> = [.text]154 if entry["thinking"]?.boolValue == true { capabilities.insert(.reasoning) }155 var pricing: Pricing?156 if let curated = CuratedCatalog.gemini(id) {157 capabilities.formUnion(curated.capabilities)158 pricing = CuratedCatalog.pricing(curated)159 }160 // Limits and the thinking flag come from the API; prices and the remaining capabilities, where present, from the curated table.161 return ModelInfo(ref: ref, displayName: entry["displayName"]?.stringValue ?? id, summary: entry["description"]?.stringValue.map { String($0.prefix(400)) },162 contextLength: entry["inputTokenLimit"]?.intValue, maxOutputTokens: entry["outputTokenLimit"]?.intValue, capabilities: capabilities,163 source: .providerAPI(fetchedAt: fetchedAt), pricing: pricing, supportedParameters: Set(methods), vendor: "google")164 }165166 /// `generateContent` is also offered by speech, image, music, video and agent models, which do not answer a chat turn with text.167 static func isTextModel(_ id: String) -> Bool {168 let lower = id.lowercased()169 let excluded = ["tts", "image", "banana", "lyria", "veo", "omni", "live", "transcribe", "embedding", "aqa", "computer-use", "deep-research", "antigravity", "robotics", "genie"]170 return !excluded.contains(where: { lower.contains($0) })171 }172173 public func verify() async throws -> ConnectionStatus {174 let models = try await listModels()175 return ConnectionStatus(ok: true, detail: "Key accepted. \(models.count) text models available.", modelCount: models.count)176 }177178 // MARK: Request179180 static func body(_ request: GenerationRequest, signatures: ThoughtSignatureStore = .shared) -> [String: JSONValue] {181 var body: [String: JSONValue] = ["contents": .array(contents(request.messages, signatures: signatures))]182 if let system = request.system?.trimmingCharacters(in: .whitespacesAndNewlines), !system.isEmpty {183 body["systemInstruction"] = ["parts": [["text": .string(system)]]]184 }185 if !request.tools.isEmpty {186 // `parametersJsonSchema` takes a full JSON Schema; the older `parameters` field rejects keywords such as additionalProperties.187 body["tools"] = [["functionDeclarations": .array(request.tools.map { tool in188 ["name": .string(tool.name), "description": .string(tool.summary), "parametersJsonSchema": tool.parameters]189 })]]190 }191 var config: [String: JSONValue] = [:]192 let p = request.parameters193 if let v = p.maxOutputTokens { config["maxOutputTokens"] = .number(Double(v)) }194 if let v = p.temperature { config["temperature"] = .number(v) }195 if let v = p.topP { config["topP"] = .number(v) }196 if let v = p.seed { config["seed"] = .number(Double(v)) }197 if !p.stop.isEmpty { config["stopSequences"] = .array(p.stop.prefix(5).map(JSONValue.string)) }198 if let thinking = thinkingConfig(p.reasoning, modelID: request.model.modelID) { config["thinkingConfig"] = thinking }199 if !config.isEmpty { body["generationConfig"] = .object(config) }200 return body201 }202203 /// Gemini 2.5 takes a token budget; Gemini 3 and later take a level. Anything the model refuses is removed on a 400.204 static func thinkingConfig(_ effort: ReasoningEffort?, modelID: String) -> JSONValue? {205 let id = modelID.lowercased()206 guard id.hasPrefix("gemini-") || id.hasPrefix("gemma-") else { return nil }207 guard let effort else { return ["includeThoughts": true] }208 if id.contains("gemini-2.5") || id.contains("gemini-2.0") {209 switch effort {210 case .off: return ["thinkingBudget": id.contains("pro") ? 128 : 0] // 2.5 Pro cannot turn thinking off211 case .low: return ["thinkingBudget": 1024, "includeThoughts": true]212 case .medium: return ["thinkingBudget": 8192, "includeThoughts": true]213 case .high: return ["thinkingBudget": 24576, "includeThoughts": true]214 }215 }216 switch effort {217 case .off: return ["thinkingLevel": "minimal"]218 case .low: return ["thinkingLevel": "low", "includeThoughts": true]219 case .medium: return ["thinkingLevel": "medium", "includeThoughts": true]220 case .high: return ["thinkingLevel": "high", "includeThoughts": true]221 }222 }223224 /// Roles are `user` and `model` and must alternate: consecutive turns of the same role are merged, so the results of225 /// parallel calls travel in one user turn, in call order.226 static func contents(_ messages: [PromptMessage], signatures: ThoughtSignatureStore) -> [JSONValue] {227 var turns: [(role: String, parts: [JSONValue])] = []228 func append(_ role: String, _ parts: [JSONValue]) {229 guard !parts.isEmpty else { return }230 if let last = turns.last, last.role == role { turns[turns.count - 1].parts += parts } else { turns.append((role, parts)) }231 }232 for message in messages {233 switch message.role {234 case .user:235 var parts: [JSONValue] = message.images.map { ["inlineData": ["mimeType": .string($0.mimeType), "data": .string($0.data.base64EncodedString())]] }236 if !message.text.isEmpty { parts.append(["text": .string(message.text)]) }237 append("user", parts)238 case .assistant:239 var parts: [JSONValue] = []240 if !message.text.isEmpty { parts.append(["text": .string(message.text)]) }241 for (position, call) in message.toolCalls.enumerated() {242 var functionCall: [String: JSONValue] = ["name": .string(call.name), "args": ToolArguments.wireObject(call.arguments)]243 if !call.id.hasPrefix(synthesizedIDPrefix) { functionCall["id"] = .string(call.id) }244 var part: [String: JSONValue] = ["functionCall": .object(functionCall)]245 if let signature = signatures.signature(for: call.id) {246 part["thoughtSignature"] = .string(signature)247 } else if position == 0 {248 part["thoughtSignature"] = .string(signaturePlaceholder)249 }250 parts.append(.object(part))251 }252 append("model", parts)253 case .tool:254 var response: [String: JSONValue] = ["name": .string(message.toolName ?? ""), "response": [message.toolIsError ? "error" : "result": .string(message.text)]]255 if let id = message.toolCallID, !id.isEmpty, !id.hasPrefix(synthesizedIDPrefix) { response["id"] = .string(id) }256 append("user", [["functionResponse": .object(response)]])257 }258 }259 return turns.map { ["role": .string($0.role), "parts": .array($0.parts)] }260 }261262 static func adjust(_ failure: ProviderHTTP.Failure, _ body: inout [String: JSONValue]) -> Bool {263 guard failure.status == 400, case .object(var config)? = body["generationConfig"] else { return false }264 let message = (failure.body.message ?? "").lowercased()265 func store() { if config.isEmpty { body.removeValue(forKey: "generationConfig") } else { body["generationConfig"] = .object(config) } }266 if config["thinkingConfig"] != nil, message.contains("thinking") || message.contains("thought") {267 if config["thinkingConfig"]?["thinkingLevel"]?.stringValue == "minimal", message.contains("minimal") {268 config["thinkingConfig"] = ["thinkingLevel": "low"] // the model has no near-off level269 } else {270 config.removeValue(forKey: "thinkingConfig")271 }272 store()273 return true274 }275 for (key, names) in [("seed", ["seed"]), ("topP", ["top_p", "topp"]), ("temperature", ["temperature"]), ("stopSequences", ["stop_sequences", "stopsequences"])] {276 if config[key] != nil, names.contains(where: message.contains), message.contains("not supported") || message.contains("unknown name") || message.contains("invalid") {277 config.removeValue(forKey: key)278 store()279 return true280 }281 }282 return false283 }284285 // MARK: Stream286287 public func stream(_ request: GenerationRequest) -> AsyncThrowingStream<StreamEvent, Error> {288 let http = http, apiKey = apiKey, baseURL = baseURL289 let secretBox = SecretBox()290 return makeEventStream(secrets: { secretBox.values }) { continuation in291 let key = try resolveKey(apiKey, kind: .google, required: true) ?? ""292 secretBox.add(key)293 let modelID = request.model.modelID294 guard modelID.range(of: #"^[A-Za-z0-9._\-]+$"#, options: .regularExpression) != nil,295 let url = URL(string: baseURL.absoluteString + "/models/\(modelID):streamGenerateContent?alt=sse") else {296 throw AstraError.modelNotFound(modelID)297 }298 var headers = Self.headers(key)299 headers["Accept"] = "text/event-stream"300 let (_, lines) = try await http.openAdjusting(body: Self.body(request), modelID: modelID, secrets: [key], makeRequest: { body in301 ProviderHTTP.request(url, method: "POST", headers: headers, body: body)302 }, normalize: Self.normalize, adjust: Self.adjust)303 var parser = SSEParser()304 var decoder = GeminiStreamDecoder(modelID: modelID)305 for try await line in lines {306 guard let event = parser.feed(line) else { continue }307 for out in try decoder.consume(event.data) { continuation.yield(out) }308 if decoder.finished { return }309 }310 if let event = parser.finish() { for out in try decoder.consume(event.data) { continuation.yield(out) } }311 try Task.checkCancellation()312 if !decoder.finished { throw AstraError.network("The connection closed before the answer was complete.") }313 }314 }315}316317/// Thought signatures of recent function calls, by tool-call id. In memory only: they are opaque, short-lived tokens.318final class ThoughtSignatureStore: @unchecked Sendable {319 static let shared = ThoughtSignatureStore()320 private let lock = NSLock()321 private var values: [String: String] = [:]322 private var order: [String] = []323 private let capacity: Int324325 init(capacity: Int = 512) { self.capacity = capacity }326327 func signature(for callID: String) -> String? { lock.withLock { values[callID] } }328329 func store(_ signature: String, for callID: String) {330 lock.withLock {331 if values[callID] == nil { order.append(callID) }332 values[callID] = signature333 while order.count > capacity { values.removeValue(forKey: order.removeFirst()) }334 }335 }336}337338/// Turns `GenerateContentResponse` chunks into `StreamEvent`s. One instance per response.339struct GeminiStreamDecoder {340 let modelID: String341 let signatures: ThoughtSignatureStore342 private(set) var started = false343 private(set) var finished = false344 private var responseID: String?345 private var callCount = 0346 private var usage: TokenUsage?347348 init(modelID: String, signatures: ThoughtSignatureStore = .shared) { self.modelID = modelID; self.signatures = signatures }349350 mutating func consume(_ data: String) throws -> [StreamEvent] {351 let trimmed = data.trimmingCharacters(in: .whitespaces)352 if trimmed.isEmpty || trimmed == "[DONE]" || finished { return [] }353 guard let json = JSONValue.parse(trimmed) else { throw AstraError.decoding("a stream chunk was not valid JSON") }354 if let error = json["error"], !error.isNull {355 let body = ProviderErrorBody.parse(json)356 let failure = GeminiProvider.normalize(ProviderHTTP.Failure(status: error["code"]?.intValue ?? 500, body: body, retryAfter: body.retryDelay))357 throw mapHTTPError(status: failure.status, code: failure.body.code, message: failure.body.message, retryAfter: failure.retryAfter, model: modelID)358 }359 var out: [StreamEvent] = []360 if !started {361 started = true362 responseID = json["responseId"]?.stringValue363 out.append(.messageStarted(MessageStart(responseID: responseID, reportedModel: json["modelVersion"]?.stringValue)))364 }365 if let u = Self.usage(json["usageMetadata"]) { usage = usage?.merged(with: u) ?? u }366367 // The prompt itself was refused: there is no candidate, only the reason.368 if let block = json["promptFeedback"]?["blockReason"]?.stringValue, !block.isEmpty, (json["candidates"]?.arrayValue ?? []).isEmpty {369 return out + end(.contentFilter)370 }371 guard let candidate = json["candidates"]?[0] else { return out }372 for part in candidate["content"]?["parts"]?.arrayValue ?? [] {373 if let call = part["functionCall"] {374 let name = call["name"]?.stringValue ?? ""375 let id = call["id"]?.stringValue ?? "\(GeminiProvider.synthesizedIDPrefix)\(responseID ?? "r")-\(callCount)"376 callCount += 1377 if let signature = part["thoughtSignature"]?.stringValue, !signature.isEmpty { signatures.store(signature, for: id) }378 let arguments = call["args"].flatMap { value -> JSONValue? in if case .object = value { return value }; return nil } ?? .object([:])379 out.append(.toolCallStarted(id: id, name: name))380 out.append(.toolCallDelta(id: id, argumentsFragment: arguments.serialized()))381 out.append(.toolCallCompleted(ToolCall(id: id, name: name, arguments: arguments)))382 } else if let text = part["text"]?.stringValue, !text.isEmpty {383 out.append(part["thought"]?.boolValue == true ? .reasoningSummaryDelta(text) : .textDelta(text))384 }385 }386 if let reason = candidate["finishReason"]?.stringValue, !reason.isEmpty {387 switch reason {388 case "MALFORMED_FUNCTION_CALL", "UNEXPECTED_TOOL_CALL", "TOO_MANY_TOOL_CALLS", "MISSING_THOUGHT_SIGNATURE":389 throw AstraError.protocolViolation("the model produced a tool call the provider could not use (\(reason.lowercased()))")390 default:391 out += end(Self.stopReason(reason, calledTools: callCount > 0))392 }393 }394 return out395 }396397 private mutating func end(_ reason: StopReason) -> [StreamEvent] {398 finished = true399 var out: [StreamEvent] = []400 if let usage { out.append(.usage(usage)) }401 out.append(.messageCompleted(reason))402 return out403 }404405 /// Gemini reports `STOP` for a turn that ends in function calls.406 static func stopReason(_ raw: String, calledTools: Bool) -> StopReason {407 switch raw {408 case "STOP": calledTools ? .toolCalls : .endOfTurn409 case "MAX_TOKENS": .maxTokens410 case "SAFETY", "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII", "LANGUAGE", "IMAGE_SAFETY", "IMAGE_PROHIBITED_CONTENT", "IMAGE_RECITATION": .contentFilter411 default: .unknown412 }413 }414415 /// `promptTokenCount` is the whole prompt, cached part included. Thinking is billed as output, so it is added to the416 /// visible `candidatesTokenCount` and also reported on its own as reasoning tokens.417 static func usage(_ json: JSONValue?) -> TokenUsage? {418 guard let json, json.objectValue != nil else { return nil }419 let thoughts = json["thoughtsTokenCount"]?.intValue420 let candidates = json["candidatesTokenCount"]?.intValue421 let output: Int? = candidates == nil && thoughts == nil ? nil : (candidates ?? 0) + (thoughts ?? 0)422 return TokenUsage(inputTokens: json["promptTokenCount"]?.intValue, outputTokens: output, cachedInputTokens: json["cachedContentTokenCount"]?.intValue, reasoningTokens: thoughts)423 }424}425