SPB Git

Repository Public MIT

GeminiProvider.swift 23.2 KB 425 lines swift

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
Files main
Menu

Theme