Repository Public
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : ORIX DJ9// File : Packages/ORIXDJCore/Sources/ORIXDJEngine/Anthropic/AnthropicClient.swift10// Description : Minimal client for the Anthropic Messages API (raw HTTPS;11// there is no official Swift SDK): model listing, streamed12// messages, typed errors, bounded retries. The API key is13// only ever placed in the request header.14// Module : ORIXDJEngine15// Repository : https://git.spboucher.ai/orix-dj16// Created : 2026-11-2117// Last Modified : 2026-11-2118//19// =============================================================================20// AUTHOR & PROFESSIONAL AFFILIATION21// =============================================================================22//23// Author : Simon-Pierre Boucher24// Position : Professor of Finance25// Institution : Université du Québec en Outaouais (UQO)26// Department : Département des sciences administratives27// Organization : SP Boucher28//29// Website : https://spboucher.ai30// Git : https://git.spboucher.ai31//32// =============================================================================33// OFFICIAL CONTACT DIRECTORY34// =============================================================================35//36// General : info@spboucher.ai37// Professional : contact@spboucher.ai38// Direct : simon@spboucher.ai39// Research : research@spboucher.ai40// Development : dev@spboucher.ai41// Support : support@spboucher.ai42// Security/Admin : admin@spboucher.ai43// Notifications : notifications@spboucher.ai44//45// Preferred Contact: support@spboucher.ai46//47// =============================================================================48// COPYRIGHT & INTELLECTUAL PROPERTY49// =============================================================================50//51// Copyright (c) 202652// Simon-Pierre Boucher53//54// All rights reserved where applicable.55//56// This file is governed by the applicable project license,57// copyright notices, institutional agreements and relevant law.58//59// Unless expressly authorized by the applicable license or60// rights holder, copying, redistribution, sublicensing,61// publication and commercial exploitation are not permitted.62//63// Existing third-party rights and notices remain unaffected.64//65// =============================================================================66// CONFIDENTIALITY & SECURITY67// =============================================================================68//69// Classification : Public70// Distribution : Public repository; use is governed by the project license71// Security Contact : admin@spboucher.ai72//73// Access to this source does not independently grant permission74// to redistribute or disclose confidential materials.75//76// Do not embed credentials, private keys, access tokens,77// certificates or confidential personal information.78//79// =============================================================================80// LICENSE & MAINTENANCE81// =============================================================================82//83// License : None specified (no license file in this repository)84// Maintainer : Simon-Pierre Boucher85// Technical Contact: dev@spboucher.ai86//87// =============================================================================88// END OF SP BOUCHER SOURCE HEADER89// =============================================================================9091import Foundation92import Security9394public struct AnthropicModel: Sendable, Equatable, Identifiable, Codable {95 public var id: String96 public var displayName: String97 public var maxInputTokens: Int?98 public var maxOutputTokens: Int?99}100101public enum AnthropicError: Error, LocalizedError, Equatable {102 case noKey103 case unauthorized104 case billing105 case forbidden(String)106 case modelNotFound(String)107 case rateLimited(retryAfter: Double?)108 case overloaded109 case badRequest(String)110 case server(Int, String)111 case network(String)112 case refusal(category: String?)113 case truncated114 case invalidResponse115 case requestLimit(Int)116 case cancelled117118 public var errorDescription: String? {119 switch self {120 case .noKey: "No Anthropic API key is configured. Add one in Settings → AI → Anthropic."121 case .unauthorized: "Anthropic rejected the API key. Check it in Settings → AI → Anthropic."122 case .billing: "The Anthropic account has a billing problem."123 case let .forbidden(m): "This API key is not allowed to do that: \(m)"124 case let .modelNotFound(m): "The model \"\(m)\" is not available to this API key. Pick another one in Settings."125 case let .rateLimited(retry): "Anthropic is rate limiting this key." + (retry.map { " Try again in \(Int($0.rounded(.up))) s." } ?? "")126 case .overloaded: "The Anthropic API is overloaded right now. Try again in a moment."127 case let .badRequest(m): "Anthropic refused the request: \(m)"128 case let .server(code, m): "Anthropic returned an error (\(code)): \(m)"129 case let .network(m): "The network request failed: \(m)"130 case let .refusal(category): "Claude declined this request" + (category.map { " (\($0))." } ?? ".")131 case .truncated: "The answer was cut off because it reached the output limit. Raise the limit in Settings or ask for something shorter."132 case .invalidResponse: "The response from Anthropic could not be understood."133 case let .requestLimit(n): "The request limit set in Settings (\(n) per hour) has been reached."134 case .cancelled: "Cancelled."135 }136 }137138 public var isRetryable: Bool {139 switch self { case .overloaded, .network: true; case let .server(code, _): code >= 500; default: false }140 }141}142143/// Settings stored in the app's preferences. The API key is not part of them: it lives in the Keychain.144public struct AnthropicSettings: Codable, Sendable, Equatable {145 public static let defaultModel = "claude-opus-5-5"146 public var model = AnthropicSettings.defaultModel147 /// nil uses the model's own default effort.148 public var effort: String?149 public var maxOutputTokens = 16000150 public var maxRequestsPerHour = 60151 /// Show exactly what will be sent and ask before every request.152 public var confirmBeforeSending = true153 /// Let the API retry a declined request on its default fallback model.154 public var refusalFallback = true155 public init() {}156}157158public struct AnthropicMessage: Sendable, Equatable, Codable {159 public var role: String160 public var content: String161 public init(role: String, content: String) { self.role = role; self.content = content }162}163164public struct AnthropicRequest: Sendable, Equatable {165 public var system: String166 public var messages: [AnthropicMessage]167 public init(system: String, messages: [AnthropicMessage]) { self.system = system; self.messages = messages }168}169170public struct AnthropicResult: Sendable, Equatable {171 public var text: String172 public var model: String173 public var stopReason: String174 public var inputTokens: Int175 public var outputTokens: Int176 public var cacheReadTokens: Int177 public var cacheCreationTokens: Int178 public var requestID: String?179}180181public final class AnthropicClient: @unchecked Sendable {182 public static let apiVersion = "2026-10-21"183 static let fallbackBeta = "server-side-fallback-2026-07-01"184 /// Models that accept the server-side refusal fallback.185 static let fallbackModels: Set<String> = ["claude-fable-5-2", "claude-fable-5-1", "claude-opus-5-5", "claude-opus-5", "claude-sonnet-5-5"]186187 private let session: URLSession188 private let baseURL: URL189 private let lock = NSLock()190 private var requestTimes: [Date] = []191192 public init(session: URLSession? = nil, baseURL: URL = URL(string: "https://api.anthropic.com")!) {193 if let session { self.session = session } else {194 // No cookies, no cache, no credential storage: nothing about a request is kept on disk.195 let c = URLSessionConfiguration.ephemeral196 c.timeoutIntervalForRequest = 120; c.timeoutIntervalForResource = 900; c.waitsForConnectivity = false197 self.session = URLSession(configuration: c)198 }199 self.baseURL = baseURL200 }201202 private func request(_ path: String, key: String, query: [URLQueryItem] = []) -> URLRequest {203 var components = URLComponents(url: baseURL.appendingPathComponent(path), resolvingAgainstBaseURL: false)!204 if !query.isEmpty { components.queryItems = query }205 var r = URLRequest(url: components.url!)206 r.setValue(key, forHTTPHeaderField: "x-api-key")207 r.setValue(Self.apiVersion, forHTTPHeaderField: "anthropic-version")208 r.setValue("application/json", forHTTPHeaderField: "content-type")209 return r210 }211212 static func error(status: Int, body: Data, headers: [AnyHashable: Any], model: String) -> AnthropicError {213 struct Envelope: Decodable { struct E: Decodable { var type: String?; var message: String? }; var error: E? }214 let e = (try? JSONDecoder().decode(Envelope.self, from: body))?.error215 let message = e?.message ?? HTTPURLResponse.localizedString(forStatusCode: status)216 switch status {217 case 400, 413, 422: return .badRequest(message)218 case 401: return .unauthorized219 case 402: return .billing220 case 403: return .forbidden(message)221 case 404: return .modelNotFound(model)222 case 429:223 let retry = (headers["retry-after"] as? String ?? headers["Retry-After"] as? String).flatMap(Double.init)224 return .rateLimited(retryAfter: retry)225 case 529: return .overloaded226 default: return .server(status, message)227 }228 }229230 /// Lists the models this key can use. Also the way a key is validated.231 public func models(apiKey: String) async throws -> [AnthropicModel] {232 guard !apiKey.isEmpty else { throw AnthropicError.noKey }233 struct Page: Decodable {234 struct M: Decodable { var id: String; var display_name: String?; var max_input_tokens: Int?; var max_tokens: Int? }235 var data: [M]; var has_more: Bool?; var last_id: String?236 }237 var out: [AnthropicModel] = []238 var after: String?239 for _ in 0 ..< 10 {240 var query = [URLQueryItem(name: "limit", value: "100")]241 if let after { query.append(URLQueryItem(name: "after_id", value: after)) }242 let (data, response): (Data, URLResponse)243 do { (data, response) = try await session.data(for: request("v1/models", key: apiKey, query: query)) } catch { throw AnthropicError.network(error.localizedDescription) }244 guard let http = response as? HTTPURLResponse else { throw AnthropicError.invalidResponse }245 guard http.statusCode == 200 else { throw Self.error(status: http.statusCode, body: data, headers: http.allHeaderFields, model: "") }246 guard let page = try? JSONDecoder().decode(Page.self, from: data) else { throw AnthropicError.invalidResponse }247 out += page.data.map { AnthropicModel(id: $0.id, displayName: $0.display_name ?? $0.id, maxInputTokens: $0.max_input_tokens, maxOutputTokens: $0.max_tokens) }248 guard page.has_more == true, let last = page.last_id else { break }249 after = last250 }251 return out252 }253254 func body(_ r: AnthropicRequest, settings: AnthropicSettings, fallback: Bool) -> [String: Any] {255 var body: [String: Any] = [256 "model": settings.model,257 "max_tokens": settings.maxOutputTokens,258 "stream": true,259 // The language description is long and identical on every request: cache it.260 "system": [["type": "text", "text": r.system, "cache_control": ["type": "ephemeral"]]],261 "messages": r.messages.map { ["role": $0.role, "content": $0.content] },262 ]263 if let effort = settings.effort { body["output_config"] = ["effort": effort] }264 if fallback { body["fallbacks"] = "default" }265 return body266 }267268 private func checkBudget(_ settings: AnthropicSettings) throws {269 lock.lock(); defer { lock.unlock() }270 let cutoff = Date().addingTimeInterval(-3600)271 requestTimes.removeAll { $0 < cutoff }272 if requestTimes.count >= settings.maxRequestsPerHour { throw AnthropicError.requestLimit(settings.maxRequestsPerHour) }273 requestTimes.append(Date())274 }275276 public var requestsInLastHour: Int { lock.withLock { requestTimes.filter { $0 > Date().addingTimeInterval(-3600) }.count } }277278 /// Sends a request and streams the answer. `onText` receives text as it arrives (on an arbitrary thread).279 public func send(_ r: AnthropicRequest, settings: AnthropicSettings, apiKey: String, onText: (@Sendable (String) -> Void)? = nil) async throws -> AnthropicResult {280 guard !apiKey.isEmpty else { throw AnthropicError.noKey }281 try checkBudget(settings)282 var useFallback = settings.refusalFallback && Self.fallbackModels.contains(settings.model)283 var attempt = 0284 let streamed = StreamFlag()285 var forward: (@Sendable (String) -> Void)?286 if let onText {287 forward = { (text: String) in288 streamed.set()289 onText(text)290 }291 }292 let forwardText = forward293 while true {294 do { return try await once(r, settings: settings, apiKey: apiKey, fallback: useFallback, onText: forwardText) }295 catch let e as AnthropicError {296 // A key or deployment without the fallback beta rejects the parameter: retry once without it.297 if case let .badRequest(m) = e, useFallback, m.contains("fallback") || m.contains("anthropic-beta") { useFallback = false; continue }298 // Never retry once text has been shown: a second answer would be appended to the first.299 guard e.isRetryable, attempt < 2, !streamed.isSet else { throw e }300 attempt += 1301 try? await Task.sleep(nanoseconds: UInt64(pow(2, Double(attempt)) * 0.75e9))302 }303 }304 }305306 private func once(_ r: AnthropicRequest, settings: AnthropicSettings, apiKey: String, fallback: Bool, onText: (@Sendable (String) -> Void)?) async throws -> AnthropicResult {307 var req = request("v1/messages", key: apiKey)308 req.httpMethod = "POST"309 if fallback { req.setValue(Self.fallbackBeta, forHTTPHeaderField: "anthropic-beta") }310 req.httpBody = try JSONSerialization.data(withJSONObject: body(r, settings: settings, fallback: fallback))311 let bytes: URLSession.AsyncBytes; let response: URLResponse312 do { (bytes, response) = try await session.bytes(for: req) } catch is CancellationError { throw AnthropicError.cancelled } catch {313 if (error as? URLError)?.code == .cancelled { throw AnthropicError.cancelled }314 throw AnthropicError.network(error.localizedDescription)315 }316 guard let http = response as? HTTPURLResponse else { throw AnthropicError.invalidResponse }317 guard http.statusCode == 200 else {318 var data = Data()319 do { for try await b in bytes { data.append(b); if data.count > 65536 { break } } } catch {}320 throw Self.error(status: http.statusCode, body: data, headers: http.allHeaderFields, model: settings.model)321 }322 var result = AnthropicResult(text: "", model: settings.model, stopReason: "", inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0,323 requestID: http.value(forHTTPHeaderField: "request-id"))324 var refusalCategory: String?325 do {326 for try await line in bytes.lines {327 guard line.hasPrefix("data:") else { continue }328 let payload = line.dropFirst(5).trimmingCharacters(in: .whitespaces)329 guard let object = try? JSONSerialization.jsonObject(with: Data(payload.utf8)) as? [String: Any], let type = object["type"] as? String else { continue }330 switch type {331 case "message_start":332 if let message = object["message"] as? [String: Any] {333 if let m = message["model"] as? String { result.model = m }334 if let usage = message["usage"] as? [String: Any] {335 result.inputTokens = usage["input_tokens"] as? Int ?? 0336 result.cacheReadTokens = usage["cache_read_input_tokens"] as? Int ?? 0337 result.cacheCreationTokens = usage["cache_creation_input_tokens"] as? Int ?? 0338 }339 }340 case "content_block_delta":341 if let delta = object["delta"] as? [String: Any], delta["type"] as? String == "text_delta", let text = delta["text"] as? String {342 result.text += text343 onText?(text)344 }345 case "message_delta":346 if let delta = object["delta"] as? [String: Any] {347 if let stop = delta["stop_reason"] as? String { result.stopReason = stop }348 if let details = delta["stop_details"] as? [String: Any] { refusalCategory = details["category"] as? String }349 }350 if let usage = object["usage"] as? [String: Any], let o = usage["output_tokens"] as? Int { result.outputTokens = o }351 case "error":352 let e = object["error"] as? [String: Any]353 let kind = e?["type"] as? String ?? ""354 let message = e?["message"] as? String ?? "stream error"355 throw kind == "overloaded_error" ? AnthropicError.overloaded : AnthropicError.server(500, message)356 default: break357 }358 }359 } catch let e as AnthropicError { throw e } catch is CancellationError { throw AnthropicError.cancelled } catch {360 if (error as? URLError)?.code == .cancelled { throw AnthropicError.cancelled }361 throw AnthropicError.network(error.localizedDescription)362 }363 // Always look at the stop reason before trusting the text.364 if result.stopReason == "refusal" { throw AnthropicError.refusal(category: refusalCategory) }365 if result.stopReason == "max_tokens" { throw AnthropicError.truncated }366 guard !result.stopReason.isEmpty else { throw AnthropicError.invalidResponse }367 return result368 }369}370371private final class StreamFlag: @unchecked Sendable {372 private let lock = NSLock(); private var value = false373 func set() { lock.lock(); value = true; lock.unlock() }374 var isSet: Bool { lock.lock(); defer { lock.unlock() }; return value }375}376377/// Keychain storage for the user's Anthropic API key. The key never goes to preferences, logs or project files.378public enum APIKeyStore {379 public static let defaultService = "ai.spboucher.orix.dj.anthropic"380 private static let account = "api-key"381382 private static func query(_ service: String) -> [String: Any] {383 [kSecClass as String: kSecClassGenericPassword, kSecAttrService as String: service, kSecAttrAccount as String: account]384 }385386 @discardableResult public static func save(_ key: String, service: String = defaultService) -> Bool {387 let trimmed = key.trimmingCharacters(in: .whitespacesAndNewlines)388 SecItemDelete(query(service) as CFDictionary)389 guard !trimmed.isEmpty else { return true }390 var attributes = query(service)391 attributes[kSecValueData as String] = Data(trimmed.utf8)392 attributes[kSecAttrAccessible as String] = kSecAttrAccessibleWhenUnlockedThisDeviceOnly393 attributes[kSecAttrLabel as String] = "ORIX DJ – Anthropic API key"394 return SecItemAdd(attributes as CFDictionary, nil) == errSecSuccess395 }396397 public static func load(service: String = defaultService) -> String? {398 var q = query(service)399 q[kSecReturnData as String] = true; q[kSecMatchLimit as String] = kSecMatchLimitOne400 var item: CFTypeRef?401 guard SecItemCopyMatching(q as CFDictionary, &item) == errSecSuccess, let data = item as? Data else { return nil }402 return String(data: data, encoding: .utf8)403 }404405 @discardableResult public static func delete(service: String = defaultService) -> Bool {406 let status = SecItemDelete(query(service) as CFDictionary)407 return status == errSecSuccess || status == errSecItemNotFound408 }409410 /// "sk-ant-…abcd" for display: never the whole key.411 public static func masked(_ key: String) -> String {412 guard key.count > 12 else { return String(repeating: "•", count: key.count) }413 return key.prefix(7) + "…" + key.suffix(4)414 }415}416