SPB Git

Repository Public MIT

ProviderSupport.swift 18.9 KB 380 lines swift

1// =============================================================================2//                  SP BOUCHER | SOFTWARE & RESEARCH3//             ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project          : ORIX Astra9// File             : Packages/AstraProviders/Sources/ProviderSupport.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/// Looks up the API key at request time, so a key added or rotated in Settings is used by the next request.92/// Returns nil (or an empty string) when no key is stored.93public typealias KeyProvider = @Sendable () throws -> String?9495// MARK: - Secrets9697enum Secrets {98    /// Removes the literal secrets and anything shaped like a credential from text bound for an error, a log or the screen.99    static func scrub(_ text: String, secrets: [String]) -> String {100        var out = text101        for secret in secrets where secret.count >= 4 { out = out.replacingOccurrences(of: secret, with: "•••") }102        return Redactor.redact(out)103    }104105    static func scrub(_ text: String?, secrets: [String]) -> String? { text.map { scrub($0, secrets: secrets) } }106107    /// Applies `scrub` to every user-visible string an error carries.108    static func scrub(_ error: AstraError, secrets: [String]) -> AstraError {109        func s(_ t: String) -> String { scrub(t, secrets: secrets) }110        func o(_ t: String?) -> String? { t.map(s) }111        switch error {112        case .unauthorized(let m): return .unauthorized(o(m))113        case .forbidden(let m): return .forbidden(o(m))114        case .rateLimited(let after, let m): return .rateLimited(retryAfter: after, message: o(m))115        case .quotaExceeded(let m): return .quotaExceeded(o(m))116        case .modelNotFound(let m): return .modelNotFound(s(m))117        case .contextTooLong(let m): return .contextTooLong(o(m))118        case .contentFiltered(let m): return .contentFiltered(o(m))119        case .invalidRequest(let m): return .invalidRequest(s(m))120        case .overloaded(let m): return .overloaded(o(m))121        case .server(let status, let m): return .server(status: status, message: o(m))122        case .network(let m): return .network(s(m))123        case .insecureEndpoint(let m): return .insecureEndpoint(s(m))124        case .decoding(let m): return .decoding(s(m))125        case .protocolViolation(let m): return .protocolViolation(s(m))126        case .unsupported(let m): return .unsupported(s(m))127        case .local(let m): return .local(s(m))128        case .missingCredential, .timeout, .cancelled: return error129        }130    }131}132133/// Holds the secrets a running request resolved, so an error raised anywhere in that request can be scrubbed of them.134final class SecretBox: @unchecked Sendable {135    private let lock = NSLock()136    private var stored: [String] = []137    func add(_ secret: String?) { if let secret, !secret.isEmpty { lock.withLock { stored.append(secret) } } }138    var values: [String] { lock.withLock { stored } }139}140141// MARK: - Error bodies142143/// The error a provider put in a response body, whatever its dialect:144/// OpenAI `{"error":{"message","type","code","param"}}`, Anthropic `{"type":"error","error":{"type","message"}}`,145/// OpenRouter `{"error":{"code":402,"message","metadata":{...}}}`, and the looser shapes of compatible servers.146struct ProviderErrorBody: Sendable, Equatable {147    var code: String?148    var message: String?149    var param: String?150    /// Retry delay carried in the body (Google `RetryInfo`), in seconds.151    var retryDelay: TimeInterval?152153    static func parse(_ data: Data) -> ProviderErrorBody {154        guard let json = JSONValue.parse(data) else {155            // Not JSON (an HTML gateway page, a plain-text proxy error): never surface the raw body.156            return ProviderErrorBody()157        }158        return parse(json)159    }160161    static func parse(_ json: JSONValue) -> ProviderErrorBody {162        var out = ProviderErrorBody()163        let error = json["error"] ?? json164        if let text = error.stringValue {165            // xAI: {"code": "invalid-argument", "error": "<message>"}166            out.message = text167            out.code = json["code"]?.stringValue ?? json["code"]?.intValue.map(String.init)168            return out169        }170        var codes: [String] = []171        for key in ["code", "type", "status"] {172            if let s = error[key]?.stringValue, !s.isEmpty { codes.append(s) } else if let n = error[key]?.intValue { codes.append(String(n)) }173        }174        if let metadata = error["metadata"] {175            for key in ["error_type", "provider_code"] { if let s = metadata[key]?.stringValue, !s.isEmpty { codes.append(s) } }176            if let reasons = metadata["reasons"]?.arrayValue, !reasons.isEmpty { codes.append("moderation") }177        }178        // Google: {"error": {"code": 400, "status": "INVALID_ARGUMENT", "details": [{"reason": "API_KEY_INVALID"}, {"retryDelay": "17s"}]}}179        for detail in error["details"]?.arrayValue ?? [] {180            if let reason = detail["reason"]?.stringValue, !reason.isEmpty { codes.append(reason) }181            if let delay = detail["retryDelay"]?.stringValue, delay.hasSuffix("s"), let seconds = Double(delay.dropLast()) { out.retryDelay = seconds }182        }183        out.code = codes.isEmpty ? nil : codes.joined(separator: " ")184        out.message = error["message"]?.stringValue ?? json["message"]?.stringValue ?? json["detail"]?.stringValue185        out.param = error["param"]?.stringValue186        return out187    }188}189190/// Recognises "this model does not take that parameter" rejections so a request can be retried without it.191enum UnsupportedParameter {192    /// One removable request field and the other spellings a server may use for it in an error message.193    struct Candidate: Sendable {194        var key: String195        var aliases: [String] = []196        init(_ key: String, _ aliases: [String] = []) { self.key = key; self.aliases = aliases }197    }198199    /// Returns the key of the candidate the rejection names, or nil when the failure is about something else.200    static func detect(_ failure: ProviderHTTP.Failure, candidates: [Candidate]) -> String? {201        guard failure.status == 400 || failure.status == 422 else { return nil }202        let body = failure.body203        let message = (body.message ?? "").lowercased()204        let code = (body.code ?? "").lowercased()205        let complains = code.contains("unsupported_parameter") || code.contains("unsupported_value") || code.contains("unknown_parameter")206            || message.contains("unsupported parameter") || message.contains("unsupported value") || message.contains("not supported")207            || message.contains("does not support") || message.contains("unknown parameter") || message.contains("unrecognized")208            || message.contains("extra inputs are not permitted") || message.contains("extra fields not permitted")209            || message.contains("unexpected keyword") || message.contains("is not allowed") || message.contains("unknown name")210            || message.contains("invalid value at") || message.contains("only supported") || message.contains("not permitted")211        guard complains else { return nil }212        if let param = body.param?.lowercased() {213            for c in candidates {214                for name in [c.key] + c.aliases where param == name.lowercased() || param.hasPrefix(name.lowercased() + ".") { return c.key }215            }216        }217        // Longest names first so "max_completion_tokens" is not mistaken for "max_tokens".218        let names = candidates.flatMap { c in ([c.key] + c.aliases).map { (name: $0.lowercased(), key: c.key) } }.sorted { $0.name.count > $1.name.count }219        for entry in names {220            let pattern = #"(^|[^a-z0-9_])"# + NSRegularExpression.escapedPattern(for: entry.name) + #"([^a-z0-9_]|$)"#221            if message.range(of: pattern, options: .regularExpression) != nil { return entry.key }222        }223        return nil224    }225}226227// MARK: - HTTP228229/// Shared request plumbing: JSON calls, streaming calls, typed errors, diagnostics. Holds no secret.230struct ProviderHTTP: Sendable {231    let kind: ProviderKind232    let transport: any HTTPTransport233    let diagnostics: (any DiagnosticsSink)?234235    struct Failure: Error {236        var status: Int237        var body: ProviderErrorBody238        var retryAfter: TimeInterval?239        func mapped(model: String?, secrets: [String]) -> AstraError {240            let message = Secrets.scrub(body.message, secrets: secrets)241            return Secrets.scrub(mapHTTPError(status: status, code: body.code, message: message, retryAfter: retryAfter, model: model), secrets: secrets)242        }243    }244245    static func requestID(_ response: HTTPURLResponse) -> String? {246        for name in ["request-id", "x-request-id", "x-generation-id"] { if let v = response.header(name), !v.isEmpty { return v } }247        return nil248    }249250    static func request(_ url: URL, method: String = "GET", headers: [String: String], body: JSONValue? = nil, timeout: TimeInterval? = nil) -> URLRequest {251        var r = URLRequest(url: url)252        r.httpMethod = method253        r.cachePolicy = .reloadIgnoringLocalAndRemoteCacheData254        if let timeout { r.timeoutInterval = timeout }255        for (name, value) in headers { r.setValue(value, forHTTPHeaderField: name) }256        if let body {257            r.httpBody = body.data258            r.setValue("application/json", forHTTPHeaderField: "Content-Type")259        }260        return r261    }262263    /// Sends a non-streaming request and decodes a JSON body; a non-2xx status becomes a typed error.264    func json(_ request: URLRequest, model: String? = nil, secrets: [String], normalize: (Failure) -> Failure = { $0 }) async throws -> (JSONValue, HTTPURLResponse) {265        let data: Data, response: HTTPURLResponse266        do { (data, response) = try await transport.send(request) } catch { throw Secrets.scrub(AstraError.wrap(error), secrets: secrets) }267        guard (200..<300).contains(response.statusCode) else {268            let parsed = ProviderErrorBody.parse(data)269            throw normalize(Failure(status: response.statusCode, body: parsed, retryAfter: response.retryAfter ?? parsed.retryDelay)).mapped(model: model, secrets: secrets)270        }271        guard let json = JSONValue.parse(data) else { throw AstraError.decoding("the provider did not answer with JSON") }272        return (json, response)273    }274275    /// Opens a streaming request. A non-2xx status throws `Failure` (unmapped, so callers can inspect it for a parameter fallback).276    func open(_ request: URLRequest, modelID: String, retryCount: Int, secrets: [String]) async throws -> (HTTPURLResponse, AsyncThrowingStream<String, Error>) {277        let started = Date()278        let response: HTTPURLResponse, lines: AsyncThrowingStream<String, Error>279        do { (response, lines) = try await transport.stream(request) } catch { throw Secrets.scrub(AstraError.wrap(error), secrets: secrets) }280        await diagnostics?.httpResponse(provider: kind, modelID: modelID, status: response.statusCode, requestID: Self.requestID(response),281                                        timeToHeaders: Date().timeIntervalSince(started), retryCount: retryCount)282        guard (200..<300).contains(response.statusCode) else {283            let body = await collectBody(lines)284            let parsed = ProviderErrorBody.parse(body)285            throw Failure(status: response.statusCode, body: parsed, retryAfter: response.retryAfter ?? parsed.retryDelay)286        }287        return (response, lines)288    }289}290291extension ProviderHTTP {292    /// Opens a streaming request, giving `adjust` the chance to edit the body and retry when the provider rejects a parameter.293    /// At most `maxAdjustments` retries; each one is reported to diagnostics with its retry count.294    func openAdjusting(body initial: [String: JSONValue], modelID: String, secrets: [String], maxAdjustments: Int = 3,295                       makeRequest: (JSONValue) throws -> URLRequest,296                       normalize: (Failure) -> Failure = { $0 },297                       adjust: (Failure, inout [String: JSONValue]) -> Bool) async throws -> (HTTPURLResponse, AsyncThrowingStream<String, Error>) {298        var body = initial299        var attempt = 0300        while true {301            do {302                return try await open(try makeRequest(.object(body)), modelID: modelID, retryCount: attempt, secrets: secrets)303            } catch let failure as Failure {304                let failure = normalize(failure)305                if attempt < maxAdjustments, adjust(failure, &body) { attempt += 1; continue }306                throw failure.mapped(model: modelID, secrets: secrets)307            }308        }309    }310}311312// MARK: - Streams313314typealias EventContinuation = AsyncThrowingStream<StreamEvent, Error>.Continuation315316/// Runs `body` in a task tied to the stream: when the consumer stops iterating or is cancelled, the task is cancelled,317/// which ends the iteration over the transport's line stream and so cancels the HTTP request itself.318func makeEventStream(secrets: @escaping @Sendable () -> [String],319                     _ body: @escaping @Sendable (EventContinuation) async throws -> Void) -> AsyncThrowingStream<StreamEvent, Error> {320    AsyncThrowingStream(bufferingPolicy: .unbounded) { continuation in321        let task = Task {322            do {323                try await body(continuation)324                if Task.isCancelled { continuation.finish(throwing: AstraError.cancelled) } else { continuation.finish() }325            } catch {326                if Task.isCancelled { continuation.finish(throwing: AstraError.cancelled); return }327                continuation.finish(throwing: Secrets.scrub(AstraError.wrap(error), secrets: secrets()))328            }329        }330        continuation.onTermination = { _ in task.cancel() }331    }332}333334/// Reads a key through its provider closure. A missing or blank key is `missingCredential` for providers that require one.335func resolveKey(_ provider: KeyProvider, kind: ProviderKind, required: Bool) throws -> String? {336    let raw: String?337    do { raw = try provider() } catch let e as AstraError { throw e } catch { throw AstraError.missingCredential(kind) }338    let key = raw?.trimmingCharacters(in: .whitespacesAndNewlines)339    if let key, !key.isEmpty { return key }340    if required { throw AstraError.missingCredential(kind) }341    return nil342}343344// MARK: - Tool calls345346enum ToolArguments {347    /// Parses accumulated argument text. Empty text is an empty object; anything that is not a JSON object is kept verbatim348    /// under `_raw` so the caller can show or repair it instead of losing it.349    static func parse(_ text: String) -> JSONValue {350        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)351        if trimmed.isEmpty { return .object([:]) }352        if let value = JSONValue.parse(trimmed), case .object = value { return value }353        return .object(["_raw": .string(text)])354    }355356    /// Serialises arguments for the wire. A call whose arguments never parsed is replayed with its original text.357    static func wireText(_ arguments: JSONValue) -> String {358        if case .object(let o) = arguments, o.count == 1, let raw = o["_raw"]?.stringValue { return raw }359        if case .object = arguments { return arguments.serialized() }360        return "{}"361    }362363    static func wireObject(_ arguments: JSONValue) -> JSONValue {364        if case .object = arguments { return arguments }365        return .object([:])366    }367}368369func dataURL(_ image: ImageInput) -> String { "data:\(image.mimeType);base64,\(image.data.base64EncodedString())" }370371extension Date {372    /// ISO calendar day in UTC, the format `Pricing.asOf` and `MetadataSource.documentation(asOf:)` use.373    var isoDay: String {374        var calendar = Calendar(identifier: .gregorian)375        calendar.timeZone = TimeZone(identifier: "UTC") ?? .gmt376        let c = calendar.dateComponents([.year, .month, .day], from: self)377        return String(format: "%04d-%02d-%02d", c.year ?? 0, c.month ?? 0, c.day ?? 0)378    }379}380
Files main
Menu

Theme