Repository Public
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : SP Term9// File : Packages/SPIntelligence/Sources/AIAssistant/AIClient.swift10// Module : AIAssistant11// Repository : https://git.spboucher.ai/sp-term12// Created : 2026-11-1713// Last Modified : 2026-11-1714//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 : None specified (no license file in this repository)80// Maintainer : Simon-Pierre Boucher81// Technical Contact: dev@spboucher.ai82//83// =============================================================================84// END OF SP BOUCHER SOURCE HEADER85// =============================================================================8687import Foundation8889/// Broad category of an error returned by a provider.90public enum AIAPIErrorKind: String, Sendable, Codable, Hashable {91 case invalidRequest, authentication, permission, notFound, rateLimited, overloaded, server, other92}9394/// An HTTP/API error returned by a provider. Messages are sanitised: they never contain the key.95public struct AIAPIError: Sendable, Equatable {96 /// HTTP status code.97 public let status: Int98 public let kind: AIAPIErrorKind99 /// Provider error type string (`rate_limit_error`, `invalid_api_key`, ...), when present.100 public let type: String?101 /// Provider message, redacted.102 public let message: String103 /// Provider request id (`request-id` / `x-request-id`), useful for support.104 public let requestID: String?105 /// Seconds to wait before retrying, from `retry-after`.106 public let retryAfter: TimeInterval?107 /// Whether retrying later may succeed (429, 5xx).108 public var isRetryable: Bool { kind == .rateLimited || kind == .overloaded || kind == .server }109}110111/// Errors thrown by ``AIClient`` and ``ContextPreview``. None of them carries a secret.112public enum AIClientError: Error, Sendable, Equatable {113 /// The provider base URL cannot produce a valid endpoint.114 case invalidEndpoint115 /// The ``NetworkPolicy`` refused the destination; nothing was sent.116 case policyViolation(NetworkPolicyError)117 /// The provider needs a key and none is stored; nothing was sent.118 case missingAPIKey(providerID: String)119 /// The secret store failed; nothing was sent.120 case secretStore(String)121 /// The transport failed (DNS, TLS, timeout, ...).122 case transport(String)123 /// The provider answered with an error status.124 case api(AIAPIError)125 /// The model declined to answer (Anthropic `stop_reason: "refusal"`).126 case refused(category: String?)127 /// The response could not be decoded.128 case decoding(String)129}130131/// Token accounting reported by the provider.132public struct AIUsage: Sendable, Equatable {133 public let inputTokens: Int?134 public let outputTokens: Int?135136 public init(inputTokens: Int?, outputTokens: Int?) {137 self.inputTokens = inputTokens138 self.outputTokens = outputTokens139 }140}141142/// A completed assistant answer.143public struct AIResponse: Sendable, Equatable {144 /// Concatenated text of the answer.145 public let text: String146 /// Model reported by the provider.147 public let model: String?148 /// Provider stop reason (`end_turn`, `max_tokens`, `stop`, `length`, ...).149 public let stopReason: String?150 public let usage: AIUsage151 /// Provider request id, when present.152 public let requestID: String?153154 /// `true` when the answer was cut by the output-token limit.155 public var isTruncated: Bool { stopReason == "max_tokens" || stopReason == "length" }156 /// Inert command proposals found in fenced code blocks of the answer.157 public func proposedCommands(workingDirectory: String? = nil, host: String? = nil, isMultiHost: Bool = false) -> [ProposedCommand] {158 extractCommands(fromMarkdown: text).map {159 ProposedCommand(text: $0, workingDirectory: workingDirectory, host: host, isMultiHost: isMultiHost)160 }161 }162}163164/// Sends approved previews to the configured provider.165///166/// Guarantees: a request can only be built from an ``ApprovedPreview``; the167/// ``NetworkPolicy`` is re-checked and the key looked up before any I/O; errors never contain the key.168public struct AIClient: Sendable {169 private let transport: any HTTPTransport170 private let secrets: any SecretStore171 private let policy: NetworkPolicy172173 /// - Parameters:174 /// - transport: network door; defaults to `URLSession`.175 /// - secrets: where provider keys are read (account = provider `id`).176 /// - policy: enforced on every request, in addition to the check made when the preview was built.177 public init(transport: any HTTPTransport = URLSessionTransport(), secrets: any SecretStore, policy: NetworkPolicy = NetworkPolicy()) {178 self.transport = transport179 self.secrets = secrets180 self.policy = policy181 }182183 /// Sends the approved request and returns the complete answer.184 /// - Throws: ``AIClientError``.185 public func send(_ approved: ApprovedPreview) async throws -> AIResponse {186 let (request, key) = try prepare(approved, stream: false)187 let response: HTTPResponse188 do {189 response = try await transport.send(request)190 } catch {191 throw AIClientError.transport(Self.sanitize(String(describing: error), key: key))192 }193 guard (200..<300).contains(response.statusCode) else {194 throw AIClientError.api(Self.apiError(status: response.statusCode, headers: response.headers, body: response.body, key: key))195 }196 return try ProviderWire.decodeResponse(response, kind: approved.preview.provider.kind)197 }198199 /// Sends the approved request with `stream: true` and yields text deltas as they arrive.200 /// The stream finishes normally at the end of the answer and throws ``AIClientError`` on failure.201 public func stream(_ approved: ApprovedPreview) -> AsyncThrowingStream<String, any Error> {202 AsyncThrowingStream { continuation in203 let task = Task {204 do {205 let (request, key) = try prepare(approved, stream: true)206 let response: HTTPStreamResponse207 do {208 response = try await transport.streamLines(request)209 } catch {210 throw AIClientError.transport(Self.sanitize(String(describing: error), key: key))211 }212 let kind = approved.preview.provider.kind213 do {214 guard (200..<300).contains(response.statusCode) else {215 var body = ""216 for try await line in response.lines { body += line + "\n" }217 throw AIClientError.api(Self.apiError(status: response.statusCode, headers: response.headers, body: Data(body.utf8), key: key))218 }219 for try await line in response.lines {220 switch try ProviderWire.parseStreamLine(line, kind: kind, sanitize: { Self.sanitize($0, key: key) }) {221 case .delta(let text): continuation.yield(text)222 case .done: continuation.finish(); return223 case .ignore: continue224 }225 }226 continuation.finish()227 } catch let error as AIClientError {228 throw error229 } catch {230 throw AIClientError.transport(Self.sanitize(String(describing: error), key: key))231 }232 } catch {233 continuation.finish(throwing: error)234 }235 }236 continuation.onTermination = { _ in task.cancel() }237 }238 }239240 // MARK: - Internals241242 private func prepare(_ approved: ApprovedPreview, stream: Bool) throws -> (HTTPRequest, SecretValue?) {243 let preview = approved.preview244 do {245 try policy.validate(preview.endpoint)246 } catch let error as NetworkPolicyError {247 throw AIClientError.policyViolation(error)248 }249 var key: SecretValue?250 do {251 key = try secrets.secret(for: preview.provider.id)252 } catch {253 throw AIClientError.secretStore(String(describing: error))254 }255 if let k = key, k.isEmpty { key = nil }256 if key == nil && preview.provider.kind.requiresAPIKey {257 throw AIClientError.missingAPIKey(providerID: preview.provider.id)258 }259 let body: Data260 do {261 body = try ProviderWire.body(for: preview, stream: stream)262 } catch {263 throw AIClientError.decoding("could not encode the request")264 }265 var headers = ["content-type": "application/json"]266 if stream { headers["accept"] = "text/event-stream" }267 switch preview.provider.kind {268 case .anthropic:269 headers["anthropic-version"] = "2023-06-01"270 if let key { headers["x-api-key"] = key.reveal() }271 case .openAI, .openAICompatible:272 if let key { headers["authorization"] = "Bearer " + key.reveal() }273 }274 return (HTTPRequest(url: preview.endpoint, method: "POST", headers: headers, body: body), key)275 }276277 static func sanitize(_ message: String, key: SecretValue?) -> String {278 var redactor = SecretRedactor()279 if let key { redactor = SecretRedactor(additionalSecrets: [key]) }280 let text = redactor.redact(message).text281 return text.count > 600 ? String(text.prefix(600)) + "..." : text282 }283284 static func apiError(status: Int, headers: [String: String], body: Data, key: SecretValue?) -> AIAPIError {285 let response = HTTPResponse(statusCode: status, headers: headers, body: body)286 let (type, rawMessage) = ProviderWire.decodeErrorBody(body)287 let kind: AIAPIErrorKind288 switch status {289 case 400, 413, 422: kind = .invalidRequest290 case 401: kind = .authentication291 case 403: kind = .permission292 case 404: kind = .notFound293 case 429: kind = .rateLimited294 case 529, 503: kind = .overloaded295 case 500...599: kind = .server296 default: kind = .other297 }298 let message = rawMessage ?? HTTPURLResponse.localizedString(forStatusCode: status)299 return AIAPIError(300 status: status, kind: kind, type: type, message: sanitize(message, key: key),301 requestID: response.header("request-id") ?? response.header("x-request-id"),302 retryAfter: response.header("retry-after").flatMap { TimeInterval($0.trimmingCharacters(in: .whitespaces)) }303 )304 }305}306307enum StreamEvent: Equatable {308 case delta(String)309 case done310 case ignore311}312313/// Request/response encoding for the two supported dialects.314enum ProviderWire {315 static func endpoint(for config: AIProviderConfig) -> URL? {316 guard var components = URLComponents(url: config.baseURL, resolvingAgainstBaseURL: false),317 let host = components.host, !host.isEmpty else { return nil }318 var path = components.path319 while path.hasSuffix("/") { path.removeLast() }320 if path.hasSuffix("/v1") { path.removeLast(3) }321 switch config.kind {322 case .anthropic: path += "/v1/messages"323 case .openAI, .openAICompatible: path += "/v1/chat/completions"324 }325 components.path = path326 components.query = nil327 components.fragment = nil328 components.user = nil329 components.password = nil330 return components.url331 }332333 private struct Message: Encodable {334 let role: String335 let content: String336 }337338 private struct AnthropicBody: Encodable {339 let model: String340 let max_tokens: Int341 let system: String342 let messages: [Message]343 let stream: Bool?344 }345346 private struct OpenAIBody: Encodable {347 let model: String348 let messages: [Message]349 let max_tokens: Int?350 let max_completion_tokens: Int?351 let stream: Bool?352 }353354 static func body(for preview: ContextPreview, stream: Bool) throws -> Data {355 let encoder = JSONEncoder()356 encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]357 let user = Message(role: "user", content: preview.payloadText)358 switch preview.provider.kind {359 case .anthropic:360 return try encoder.encode(AnthropicBody(361 model: preview.model, max_tokens: preview.maxOutputTokens, system: preview.systemPrompt,362 messages: [user], stream: stream ? true : nil))363 case .openAI:364 return try encoder.encode(OpenAIBody(365 model: preview.model, messages: [Message(role: "system", content: preview.systemPrompt), user],366 max_tokens: nil, max_completion_tokens: preview.maxOutputTokens, stream: stream ? true : nil))367 case .openAICompatible:368 return try encoder.encode(OpenAIBody(369 model: preview.model, messages: [Message(role: "system", content: preview.systemPrompt), user],370 max_tokens: preview.maxOutputTokens, max_completion_tokens: nil, stream: stream ? true : nil))371 }372 }373374 private struct AnthropicResponse: Decodable {375 struct Block: Decodable { let type: String; let text: String? }376 struct Usage: Decodable { let input_tokens: Int?; let output_tokens: Int? }377 struct StopDetails: Decodable { let category: String? }378 let content: [Block]379 let model: String?380 let stop_reason: String?381 let stop_details: StopDetails?382 let usage: Usage?383 }384385 private struct OpenAIResponse: Decodable {386 struct Choice: Decodable {387 struct Msg: Decodable { let content: String?; let refusal: String? }388 let message: Msg389 let finish_reason: String?390 }391 struct Usage: Decodable { let prompt_tokens: Int?; let completion_tokens: Int? }392 let choices: [Choice]393 let model: String?394 let usage: Usage?395 }396397 static func decodeResponse(_ response: HTTPResponse, kind: AIProviderKind) throws -> AIResponse {398 let requestID = response.header("request-id") ?? response.header("x-request-id")399 do {400 switch kind {401 case .anthropic:402 let decoded = try JSONDecoder().decode(AnthropicResponse.self, from: response.body)403 if decoded.stop_reason == "refusal" { throw AIClientError.refused(category: decoded.stop_details?.category) }404 let text = decoded.content.filter { $0.type == "text" }.compactMap(\.text).joined()405 return AIResponse(text: text, model: decoded.model, stopReason: decoded.stop_reason,406 usage: AIUsage(inputTokens: decoded.usage?.input_tokens, outputTokens: decoded.usage?.output_tokens),407 requestID: requestID)408 case .openAI, .openAICompatible:409 let decoded = try JSONDecoder().decode(OpenAIResponse.self, from: response.body)410 guard let choice = decoded.choices.first else { throw AIClientError.decoding("the response contains no choice") }411 if choice.message.content == nil, choice.message.refusal != nil { throw AIClientError.refused(category: nil) }412 return AIResponse(text: choice.message.content ?? "", model: decoded.model, stopReason: choice.finish_reason,413 usage: AIUsage(inputTokens: decoded.usage?.prompt_tokens, outputTokens: decoded.usage?.completion_tokens),414 requestID: requestID)415 }416 } catch let error as AIClientError {417 throw error418 } catch {419 throw AIClientError.decoding("the provider response is not in the expected format")420 }421 }422423 private struct ErrorEnvelope: Decodable {424 struct Detail: Decodable {425 let type: String?426 let code: String?427 let message: String?428429 init(from decoder: any Decoder) throws {430 if let single = try? decoder.singleValueContainer(), let text = try? single.decode(String.self) {431 type = nil; code = nil; message = text432 return433 }434 let container = try decoder.container(keyedBy: CodingKeys.self)435 type = try? container.decodeIfPresent(String.self, forKey: .type)436 code = try? container.decodeIfPresent(String.self, forKey: .code)437 message = try? container.decodeIfPresent(String.self, forKey: .message)438 }439 enum CodingKeys: String, CodingKey { case type, code, message }440 }441 let error: Detail442 }443444 static func decodeErrorBody(_ body: Data) -> (type: String?, message: String?) {445 guard let envelope = try? JSONDecoder().decode(ErrorEnvelope.self, from: body) else { return (nil, nil) }446 return (envelope.error.type ?? envelope.error.code, envelope.error.message)447 }448449 private struct AnthropicStreamEvent: Decodable {450 struct Delta: Decodable { let type: String?; let text: String?; let stop_reason: String? }451 let type: String452 let delta: Delta?453 }454455 private struct OpenAIStreamChunk: Decodable {456 struct Choice: Decodable {457 struct Delta: Decodable { let content: String? }458 let delta: Delta?459 }460 let choices: [Choice]?461 }462463 static func parseStreamLine(_ line: String, kind: AIProviderKind, sanitize: (String) -> String) throws -> StreamEvent {464 let trimmed = line.trimmingCharacters(in: .whitespaces)465 guard trimmed.hasPrefix("data:") else { return .ignore }466 let payload = trimmed.dropFirst(5).trimmingCharacters(in: .whitespaces)467 if payload == "[DONE]" { return .done }468 let data = Data(payload.utf8)469 if let envelope = try? JSONDecoder().decode(ErrorEnvelope.self, from: data) {470 let type = envelope.error.type ?? envelope.error.code471 let kindOfError: AIAPIErrorKind = type == "overloaded_error" ? .overloaded : type == "rate_limit_error" ? .rateLimited : .server472 throw AIClientError.api(AIAPIError(status: 200, kind: kindOfError, type: type,473 message: sanitize(envelope.error.message ?? "stream error"),474 requestID: nil, retryAfter: nil))475 }476 switch kind {477 case .anthropic:478 guard let event = try? JSONDecoder().decode(AnthropicStreamEvent.self, from: data) else { return .ignore }479 switch event.type {480 case "content_block_delta":481 if event.delta?.type == "text_delta", let text = event.delta?.text, !text.isEmpty { return .delta(text) }482 return .ignore483 case "message_delta":484 if event.delta?.stop_reason == "refusal" { throw AIClientError.refused(category: nil) }485 return .ignore486 case "message_stop":487 return .done488 default:489 return .ignore490 }491 case .openAI, .openAICompatible:492 guard let chunk = try? JSONDecoder().decode(OpenAIStreamChunk.self, from: data) else { return .ignore }493 if let text = chunk.choices?.first?.delta?.content, !text.isEmpty { return .delta(text) }494 return .ignore495 }496 }497}498