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/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