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/AnthropicProvider.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/// Anthropic through the Messages API (`POST /v1/messages`, `anthropic-version: 2026-10-21`).92///93/// Choices worth knowing:94/// - Sampling parameters are never sent: API version 2026-10-21 rejects `temperature`, `top_p` and `top_k` on every model.95/// - Thinking blocks are never replayed. Earlier turns are sent as text and `tool_use` blocks only, which the API accepts96/// inside a tool cycle as well (verified live on claude-haiku-5-5, claude-sonnet-5-5 and claude-haiku-4-5 on 2026-11-21).97/// Because no block is replayed, no signature can be invalidated by the app trimming or editing history.98/// - Thinking text reaches the app only as the summary the API returns (`display: "summarized"`), as `.reasoningSummaryDelta`.99/// - Server-side refusal fallbacks are not enabled: the model that answers is always the model that was requested.100public struct AnthropicProvider: ChatProvider {101 public let kind: ProviderKind = .anthropic102 public static let defaultBaseURL = URL(string: "https://api.anthropic.com/v1")!103 public static let apiVersion = "2026-10-21"104105 private let http: ProviderHTTP106 private let apiKey: KeyProvider107 private let baseURL: URL108109 public init(transport: any HTTPTransport, apiKey: @escaping KeyProvider, diagnostics: (any DiagnosticsSink)? = nil, baseURL: URL = AnthropicProvider.defaultBaseURL) {110 self.http = ProviderHTTP(kind: .anthropic, transport: transport, diagnostics: diagnostics)111 self.apiKey = apiKey112 self.baseURL = baseURL113 }114115 static func headers(_ key: String) -> [String: String] { ["x-api-key": key, "anthropic-version": apiVersion] }116117 // MARK: Models118119 public func listModels() async throws -> [ModelInfo] {120 let key = try resolveKey(apiKey, kind: kind, required: true) ?? ""121 var out: [ModelInfo] = []122 var after: String?123 let fetchedAt = Date()124 for _ in 0..<20 {125 var components = URLComponents(url: baseURL.appendingPathComponent("models"), resolvingAgainstBaseURL: false)!126 components.queryItems = [URLQueryItem(name: "limit", value: "1000")] + (after.map { [URLQueryItem(name: "after_id", value: $0)] } ?? [])127 let (json, _) = try await http.json(ProviderHTTP.request(components.url!, headers: Self.headers(key)), secrets: [key])128 guard let data = json["data"]?.arrayValue else { throw AstraError.decoding("the model list has no data array") }129 out += data.compactMap { Self.modelInfo($0, fetchedAt: fetchedAt) }130 guard json["has_more"]?.boolValue == true, let last = json["last_id"]?.stringValue, last != after else { break }131 after = last132 }133 return out134 }135136 static func modelInfo(_ entry: JSONValue, fetchedAt: Date) -> ModelInfo? {137 guard let id = entry["id"]?.stringValue else { return nil }138 let ref = ModelRef(provider: .anthropic, modelID: id)139 let created = entry["created_at"]?.stringValue.flatMap { ISO8601DateFormatter().date(from: $0) }140 let name = entry["display_name"]?.stringValue141 if var info = CuratedCatalog.info(for: ref) {142 // Limits the API reports today win over the curated copy.143 info.displayName = name ?? info.displayName144 info.contextLength = entry["max_input_tokens"]?.intValue ?? info.contextLength145 info.maxOutputTokens = entry["max_tokens"]?.intValue ?? info.maxOutputTokens146 info.createdAt = created147 return info148 }149 // Unknown to the curated table: claim only what the API itself reports.150 var capabilities: Set<Capability> = [.text]151 let reported = entry["capabilities"]152 if reported?["image_input"]?["supported"]?.boolValue == true { capabilities.insert(.vision) }153 if reported?["pdf_input"]?["supported"]?.boolValue == true { capabilities.insert(.documents) }154 if reported?["structured_outputs"]?["supported"]?.boolValue == true { capabilities.insert(.structuredOutput) }155 if reported?["thinking"]?["supported"]?.boolValue == true { capabilities.insert(.reasoning) }156 return ModelInfo(ref: ref, displayName: name ?? id, contextLength: entry["max_input_tokens"]?.intValue, maxOutputTokens: entry["max_tokens"]?.intValue,157 capabilities: capabilities, source: .providerAPI(fetchedAt: fetchedAt), vendor: "anthropic", createdAt: created)158 }159160 public func verify() async throws -> ConnectionStatus {161 let models = try await listModels()162 return ConnectionStatus(ok: true, detail: "Key accepted. \(models.count) models available.", modelCount: models.count)163 }164165 // MARK: Request166167 static func body(_ request: GenerationRequest) -> [String: JSONValue] {168 let modelID = request.model.modelID169 let entry = CuratedCatalog.anthropic(modelID)170 var body: [String: JSONValue] = ["model": .string(modelID), "stream": true, "messages": .array(messages(request.messages))]171172 if let system = request.system?.trimmingCharacters(in: .whitespacesAndNewlines), !system.isEmpty {173 var block: [String: JSONValue] = ["type": "text", "text": .string(system)]174 // Cache the stable prefix (tools, then system) when it is long enough for this model to store.175 let prefixTokens = TokenEstimator.estimate(system) + request.tools.reduce(0) { $0 + TokenEstimator.estimate($1.summary) + TokenEstimator.estimate($1.parameters.serialized()) }176 if prefixTokens >= (entry?.cacheMinimumTokens ?? 4096) { block["cache_control"] = ["type": "ephemeral"] }177 body["system"] = [.object(block)]178 }179 if !request.tools.isEmpty {180 body["tools"] = .array(request.tools.map { tool in181 ["name": .string(tool.name), "description": .string(tool.summary), "input_schema": tool.parameters, "eager_input_streaming": true]182 })183 }184 if !request.parameters.stop.isEmpty { body["stop_sequences"] = .array(request.parameters.stop.prefix(4).map(JSONValue.string)) }185186 var maxTokens = request.parameters.maxOutputTokens ?? min(entry?.maxOutputTokens ?? 4096, 16_000)187 let effort = request.parameters.reasoning188 switch entry?.thinking {189 case .adaptive(let off, let onByDefault, let summaryOptIn):190 var thinking: [String: JSONValue] = ["type": "adaptive"]191 if summaryOptIn { thinking["display"] = "summarized" }192 switch effort {193 case nil:194 if onByDefault { body["thinking"] = .object(thinking) }195 case .off?:196 switch off {197 case .disabled: body["thinking"] = ["type": "disabled"]198 case .betweenTools: body["thinking"] = ["type": "between_tools"]199 case .unavailable:200 body["thinking"] = .object(thinking)201 body["output_config"] = ["effort": "low"]202 }203 case let level?:204 body["thinking"] = .object(thinking)205 if entry?.effort == true { body["output_config"] = ["effort": .string(level.rawValue)] }206 }207 case .budget:208 if let effort, effort != .off {209 let budget = effort == .low ? 1024 : effort == .medium ? 4096 : 16_000210 body["thinking"] = ["type": "enabled", "budget_tokens": .number(Double(budget))]211 maxTokens += budget // the budget must stay below max_tokens and should not eat the answer212 }213 case nil:214 // A model this build does not know: ask for adaptive thinking only when the user asked for reasoning; removed on a 400.215 if let effort, effort != .off {216 body["thinking"] = ["type": "adaptive", "display": "summarized"]217 body["output_config"] = ["effort": .string(effort.rawValue)]218 }219 }220 body["max_tokens"] = .number(Double(maxTokens))221 return body222 }223224 /// Roles must alternate and tool results travel in a user turn: consecutive turns of the same wire role are merged,225 /// so several tool results (and a user message that follows them) become one user turn with the results first.226 static func messages(_ messages: [PromptMessage]) -> [JSONValue] {227 var turns: [(role: String, content: [JSONValue])] = []228 func append(_ role: String, _ blocks: [JSONValue]) {229 guard !blocks.isEmpty else { return }230 if let last = turns.last, last.role == role { turns[turns.count - 1].content += blocks } else { turns.append((role, blocks)) }231 }232 for message in messages {233 switch message.role {234 case .user:235 var blocks: [JSONValue] = message.images.map { image in236 ["type": "image", "source": ["type": "base64", "media_type": .string(image.mimeType), "data": .string(image.data.base64EncodedString())]]237 }238 if !message.text.isEmpty { blocks.append(["type": "text", "text": .string(message.text)]) }239 append("user", blocks)240 case .assistant:241 var blocks: [JSONValue] = []242 if !message.text.isEmpty { blocks.append(["type": "text", "text": .string(message.text)]) }243 for call in message.toolCalls {244 blocks.append(["type": "tool_use", "id": .string(call.id), "name": .string(call.name), "input": ToolArguments.wireObject(call.arguments)])245 }246 append("assistant", blocks)247 case .tool:248 var block: [String: JSONValue] = ["type": "tool_result", "tool_use_id": .string(message.toolCallID ?? ""), "content": .string(message.text)]249 if message.toolIsError { block["is_error"] = true }250 append("user", [.object(block)])251 }252 }253 return turns.map { ["role": .string($0.role), "content": .array($0.content)] }254 }255256 static func adjust(_ failure: ProviderHTTP.Failure, _ body: inout [String: JSONValue]) -> Bool {257 var candidates: [UnsupportedParameter.Candidate] = []258 if body["thinking"] != nil { candidates.append(.init("thinking", ["budget_tokens", "display"])) }259 if body["output_config"] != nil { candidates.append(.init("output_config", ["effort", "effort parameter"])) }260 if body["tools"]?[0]?["eager_input_streaming"] != nil { candidates.append(.init("eager_input_streaming")) }261 guard failure.status == 400, let hit = candidates.first(where: { c in262 let message = (failure.body.message ?? "").lowercased()263 return ([c.key] + c.aliases).contains { message.contains($0.lowercased()) }264 })?.key else { return false }265 switch hit {266 case "eager_input_streaming":267 guard case .array(let tools)? = body["tools"] else { return false }268 body["tools"] = .array(tools.map { tool in269 guard case .object(var o) = tool else { return tool }270 o.removeValue(forKey: "eager_input_streaming")271 return .object(o)272 })273 case "thinking":274 body.removeValue(forKey: "thinking")275 default:276 body.removeValue(forKey: "output_config")277 }278 return true279 }280281 // MARK: Stream282283 public func stream(_ request: GenerationRequest) -> AsyncThrowingStream<StreamEvent, Error> {284 let http = http, apiKey = apiKey, url = baseURL.appendingPathComponent("messages")285 let secretBox = SecretBox()286 return makeEventStream(secrets: { secretBox.values }) { continuation in287 let key = try resolveKey(apiKey, kind: .anthropic, required: true) ?? ""288 secretBox.add(key)289 let modelID = request.model.modelID290 var headers = Self.headers(key)291 headers["Accept"] = "text/event-stream"292 let (_, lines) = try await http.openAdjusting(body: Self.body(request), modelID: modelID, secrets: [key], makeRequest: { body in293 ProviderHTTP.request(url, method: "POST", headers: headers, body: body)294 }, adjust: Self.adjust)295 var parser = SSEParser()296 var decoder = AnthropicStreamDecoder(modelID: modelID)297 for try await line in lines {298 guard let event = parser.feed(line) else { continue }299 for out in try decoder.consume(event) { continuation.yield(out) }300 if decoder.finished { return }301 }302 if let event = parser.finish() { for out in try decoder.consume(event) { continuation.yield(out) } }303 try Task.checkCancellation()304 if !decoder.finished { throw AstraError.network("The connection closed before the answer was complete.") }305 }306 }307}308309/// Turns Messages API stream events into `StreamEvent`s. One instance per response.310struct AnthropicStreamDecoder {311 private enum Block { case text, thinking, tool(id: String, name: String, json: String), other }312313 let modelID: String314 private(set) var started = false315 private(set) var finished = false316 private var blocks: [Int: Block] = [:]317 private var stopReason: StopReason?318 private var usage = TokenUsage()319 private var thinkingBlocks = 0320321 init(modelID: String) { self.modelID = modelID }322323 mutating func consume(_ event: SSEEvent) throws -> [StreamEvent] {324 guard let json = JSONValue.parse(event.data) else { throw AstraError.decoding("a stream event was not valid JSON") }325 let type = json["type"]?.stringValue ?? event.event ?? ""326 var out: [StreamEvent] = []327 switch type {328 case "message_start":329 let message = json["message"]330 if !started {331 started = true332 out.append(.messageStarted(MessageStart(responseID: message?["id"]?.stringValue, reportedModel: message?["model"]?.stringValue)))333 }334 if let u = Self.usage(message?["usage"]) { usage = usage.merged(with: u); out.append(.usage(usage)) }335336 case "content_block_start":337 guard let index = json["index"]?.intValue else { break }338 let block = json["content_block"]339 switch block?["type"]?.stringValue {340 case "text":341 blocks[index] = .text342 if let text = block?["text"]?.stringValue, !text.isEmpty { out.append(.textDelta(text)) }343 case "thinking":344 blocks[index] = .thinking345 thinkingBlocks += 1346 if thinkingBlocks > 1 { out.append(.reasoningSummaryDelta("\n\n")) }347 if let text = block?["thinking"]?.stringValue, !text.isEmpty { out.append(.reasoningSummaryDelta(text)) }348 case "tool_use":349 let id = block?["id"]?.stringValue ?? "toolu_\(index)", name = block?["name"]?.stringValue ?? ""350 // Without eager streaming a non-empty `input` can arrive whole in the start event.351 var initial = ""352 if let input = block?["input"], case .object(let o) = input, !o.isEmpty { initial = input.serialized() }353 blocks[index] = .tool(id: id, name: name, json: initial)354 out.append(.toolCallStarted(id: id, name: name))355 if !initial.isEmpty { out.append(.toolCallDelta(id: id, argumentsFragment: initial)) }356 default:357 blocks[index] = .other // redacted_thinking, server tool blocks, fallback markers: nothing to show358 }359360 case "content_block_delta":361 guard let index = json["index"]?.intValue, let delta = json["delta"] else { break }362 switch delta["type"]?.stringValue {363 case "text_delta":364 if let text = delta["text"]?.stringValue, !text.isEmpty { out.append(.textDelta(text)) }365 case "thinking_delta":366 if let text = delta["thinking"]?.stringValue, !text.isEmpty { out.append(.reasoningSummaryDelta(text)) }367 case "input_json_delta":368 guard case .tool(let id, let name, var buffer)? = blocks[index], let fragment = delta["partial_json"]?.stringValue else { break }369 // A start event that carried a whole input is replaced by the streamed one.370 if buffer.hasPrefix("{"), buffer.hasSuffix("}"), !fragment.isEmpty, JSONValue.parse(buffer) != nil, fragment.hasPrefix("{") { buffer = "" }371 buffer += fragment372 blocks[index] = .tool(id: id, name: name, json: buffer)373 if !fragment.isEmpty { out.append(.toolCallDelta(id: id, argumentsFragment: fragment)) }374 default:375 break // signature_delta, citations_delta: integrity data, not content376 }377378 case "content_block_stop":379 guard let index = json["index"]?.intValue else { break }380 if case .tool(let id, let name, let buffer)? = blocks[index] {381 out.append(.toolCallCompleted(ToolCall(id: id, name: name, arguments: ToolArguments.parse(buffer))))382 }383 blocks[index] = nil384385 case "message_delta":386 if let reason = json["delta"]?["stop_reason"]?.stringValue { stopReason = Self.stopReason(reason) }387 if let u = Self.usage(json["usage"]) { usage = usage.merged(with: u); out.append(.usage(usage)) }388389 case "message_stop":390 // A tool call cut off by max_tokens never got its block stop: close it so the stream stays well formed.391 for (_, block) in blocks.sorted(by: { $0.key < $1.key }) {392 if case .tool(let id, let name, let buffer) = block { out.append(.toolCallCompleted(ToolCall(id: id, name: name, arguments: ToolArguments.parse(buffer)))) }393 }394 blocks.removeAll()395 out.append(.messageCompleted(stopReason ?? .unknown))396 finished = true397398 case "error":399 let error = json["error"]400 throw Self.streamError(type: error?["type"]?.stringValue, message: error?["message"]?.stringValue, modelID: modelID)401402 default:403 break // ping and event types added later404 }405 return out406 }407408 static func stopReason(_ raw: String) -> StopReason {409 switch raw {410 case "end_turn": .endOfTurn411 case "max_tokens", "model_context_window_exceeded": .maxTokens412 case "tool_use": .toolCalls413 case "stop_sequence": .stopSequence414 case "refusal": .contentFilter415 case "pause_turn": .endOfTurn416 default: .unknown417 }418 }419420 /// Anthropic reports `input_tokens` without the cached part. The app's `inputTokens` is the whole prompt:421 /// uncached + cache reads + cache writes, with the last two also reported on their own as subsets.422 static func usage(_ json: JSONValue?) -> TokenUsage? {423 guard let json, json.objectValue != nil else { return nil }424 let read = json["cache_read_input_tokens"]?.intValue425 let write = json["cache_creation_input_tokens"]?.intValue426 var total: Int?427 if let base = json["input_tokens"]?.intValue { total = base + (read ?? 0) + (write ?? 0) }428 return TokenUsage(inputTokens: total, outputTokens: json["output_tokens"]?.intValue, cachedInputTokens: total == nil ? nil : read,429 cacheWriteTokens: total == nil ? nil : write, reasoningTokens: json["output_tokens_details"]?["thinking_tokens"]?.intValue)430 }431432 static func streamError(type: String?, message: String?, modelID: String) -> AstraError {433 let status: Int434 switch type {435 case "overloaded_error": status = 529436 case "rate_limit_error": status = 429437 case "invalid_request_error": status = 400438 case "authentication_error": status = 401439 case "billing_error": status = 402440 case "permission_error": status = 403441 case "not_found_error": status = 404442 case "request_too_large": status = 413443 case "timeout_error": status = 408444 default: status = 500445 }446 return mapHTTPError(status: status, code: type, message: message, retryAfter: nil, model: modelID)447 }448}449