SPB Git

Repository Public

AIClient.swift 22.0 KB 498 lines swift

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

Theme