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/ResponsesAPI.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// The Responses API wire format (`POST /v1/responses`, semantic SSE events), shared by OpenAI and xAI.92//93// Conversation state is always sent in full with `store: false`: nothing is retained server-side on the user's behalf.94// Reasoning items are not replayed between turns (the core message model has no place to keep their encrypted content);95// function calls are replayed without item ids, which both providers accept (verified live on 2026-11-21).9697/// What a given model accepts, as far as it is known before sending. Unknown fields are sent and removed on a 400.98struct ResponsesModelPlan: Sendable {99 /// nil: unknown, send and fall back. false: never send `temperature` / `top_p`.100 var acceptsSampling: Bool?101 /// nil: unknown. Empty: the model does not reason, never send `reasoning`.102 var reasoningEfforts: [String]?103 /// Put the system text in a leading `developer` message instead of top-level `instructions`.104 var systemAsDeveloperMessage = false105 /// Ask for reasoning summaries even when the user set no effort (models known to reason by default).106 var requestSummaryByDefault = false107}108109enum ResponsesEncoder {110 static func body(_ request: GenerationRequest, plan: ResponsesModelPlan) -> [String: JSONValue] {111 var body: [String: JSONValue] = ["model": .string(request.model.modelID), "stream": true, "store": false]112 var input: [JSONValue] = []113 if let system = request.system?.trimmingCharacters(in: .whitespacesAndNewlines), !system.isEmpty {114 if plan.systemAsDeveloperMessage { input.append(["role": "developer", "content": .string(system)]) } else { body["instructions"] = .string(system) }115 }116 for message in request.messages { input.append(contentsOf: items(message)) }117 body["input"] = .array(input)118 if !request.tools.isEmpty {119 body["tools"] = .array(request.tools.map { tool in120 ["type": "function", "name": .string(tool.name), "description": .string(tool.summary), "parameters": tool.parameters, "strict": false]121 })122 }123 let p = request.parameters124 if let max = p.maxOutputTokens { body["max_output_tokens"] = .number(Double(max)) }125 if plan.acceptsSampling != false {126 if let t = p.temperature { body["temperature"] = .number(t) }127 if let t = p.topP { body["top_p"] = .number(t) }128 }129 if let reasoning = reasoning(p.reasoning, plan: plan) { body["reasoning"] = reasoning }130 return body131 }132133 /// Maps the app's four levels onto what the model accepts. "Off" becomes the lowest effort the model has.134 static func reasoning(_ effort: ReasoningEffort?, plan: ResponsesModelPlan) -> JSONValue? {135 if let known = plan.reasoningEfforts, known.isEmpty { return nil }136 guard let effort else { return plan.requestSummaryByDefault ? ["summary": "auto"] : nil }137 let wanted: String138 switch effort {139 case .off: wanted = "none"140 case .low: wanted = "low"141 case .medium: wanted = "medium"142 case .high: wanted = "high"143 }144 var value = wanted145 if let known = plan.reasoningEfforts, !known.contains(wanted) {146 value = effort == .off ? (["none", "minimal", "low"].first(where: known.contains) ?? known.first ?? "low") : (known.contains("medium") ? "medium" : known.first ?? wanted)147 }148 return value == "none" ? ["effort": "none"] : ["effort": .string(value), "summary": "auto"]149 }150151 static func items(_ message: PromptMessage) -> [JSONValue] {152 switch message.role {153 case .user:154 var parts: [JSONValue] = message.images.map { ["type": "input_image", "image_url": .string(dataURL($0)), "detail": "auto"] }155 if !message.text.isEmpty || parts.isEmpty { parts.append(["type": "input_text", "text": .string(message.text)]) }156 return [["role": "user", "content": .array(parts)]]157 case .assistant:158 var out: [JSONValue] = []159 if !message.text.isEmpty { out.append(["role": "assistant", "content": .string(message.text)]) }160 for call in message.toolCalls {161 out.append(["type": "function_call", "call_id": .string(call.id), "name": .string(call.name), "arguments": .string(ToolArguments.wireText(call.arguments))])162 }163 return out164 case .tool:165 let text = message.toolIsError ? "Error: " + message.text : message.text166 return [["type": "function_call_output", "call_id": .string(message.toolCallID ?? ""), "output": .string(text)]]167 }168 }169170 /// Edits the body after a parameter rejection. Returns false when the failure is not one this layer can route around.171 static func adjust(_ failure: ProviderHTTP.Failure, _ body: inout [String: JSONValue]) -> Bool {172 var candidates: [UnsupportedParameter.Candidate] = []173 if body["temperature"] != nil { candidates.append(.init("temperature")) }174 if body["top_p"] != nil { candidates.append(.init("top_p", ["topP"])) }175 if body["reasoning"] != nil { candidates.append(.init("reasoning", ["reasoning_effort", "reasoningEffort", "reasoning.effort", "reasoning.summary", "summary"])) }176 if body["instructions"] != nil { candidates.append(.init("instructions")) }177 guard let hit = UnsupportedParameter.detect(failure, candidates: candidates) else { return false }178 switch hit {179 case "reasoning":180 // A model that reasons but has no "none" level: ask for its lowest real level instead of giving up on the setting.181 let message = (failure.body.message ?? "").lowercased()182 if body["reasoning"]?["effort"]?.stringValue == "none", message.contains("none") {183 body["reasoning"] = ["effort": "low", "summary": "auto"]184 } else if body["reasoning"]?["summary"] != nil, message.contains("summary"), let effort = body["reasoning"]?["effort"] {185 body["reasoning"] = ["effort": effort]186 } else {187 body.removeValue(forKey: "reasoning")188 }189 case "instructions":190 guard let text = body["instructions"], case .array(let input)? = body["input"] else { return false }191 body.removeValue(forKey: "instructions")192 body["input"] = .array([["role": "system", "content": text]] + input)193 default: body.removeValue(forKey: hit)194 }195 return true196 }197}198199/// Turns Responses API stream events into `StreamEvent`s. One instance per response.200struct ResponsesStreamDecoder {201 private struct Call { var id: String; var name: String; var arguments = ""; var completed = false }202203 let modelID: String204 /// Divisor that turns the provider's reported cost into US dollars (xAI reports `cost_in_usd_ticks`, 1e10 ticks per dollar).205 var costTicksPerUSD: Double?206 private(set) var started = false207 private(set) var finished = false208 private var calls: [String: Call] = [:] // by item id209 private var callOrder: [String] = []210 private var sawRefusal = false211 private var emittedCalls = false212213 init(modelID: String, costTicksPerUSD: Double? = nil) { self.modelID = modelID; self.costTicksPerUSD = costTicksPerUSD }214215 mutating func consume(_ event: SSEEvent) throws -> [StreamEvent] {216 let data = event.data.trimmingCharacters(in: .whitespaces)217 if data == "[DONE]" || data.isEmpty { return [] }218 guard let json = JSONValue.parse(data) else { throw AstraError.decoding("a stream event was not valid JSON") }219 let type = json["type"]?.stringValue ?? event.event ?? ""220 var out: [StreamEvent] = []221222 func start(_ response: JSONValue?) -> [StreamEvent] {223 guard !started else { return [] }224 return [.messageStarted(MessageStart(responseID: response?["id"]?.stringValue, reportedModel: response?["model"]?.stringValue))]225 }226227 switch type {228 case "response.created", "response.in_progress", "response.queued":229 out += start(json["response"]); started = true230231 case "response.output_text.delta":232 out += start(nil); started = true233 if let delta = json["delta"]?.stringValue, !delta.isEmpty { out.append(.textDelta(delta)) }234235 case "response.refusal.delta":236 out += start(nil); started = true237 sawRefusal = true238 if let delta = json["delta"]?.stringValue, !delta.isEmpty { out.append(.textDelta(delta)) }239240 case "response.reasoning_summary_part.added":241 // Separate consecutive summary parts; the summary is the only reasoning text ever surfaced.242 if let index = json["summary_index"]?.intValue, index > 0 { out.append(.reasoningSummaryDelta("\n\n")) }243244 case "response.reasoning_summary_text.delta":245 out += start(nil); started = true246 if let delta = json["delta"]?.stringValue, !delta.isEmpty { out.append(.reasoningSummaryDelta(delta)) }247248 case "response.output_item.added":249 out += start(nil); started = true250 if let item = json["item"], item["type"]?.stringValue == "function_call" { out += open(item) }251252 case "response.function_call_arguments.delta":253 guard let itemID = json["item_id"]?.stringValue, let delta = json["delta"]?.stringValue, var call = calls[itemID], !call.completed else { break }254 call.arguments += delta255 calls[itemID] = call256 if !delta.isEmpty { out.append(.toolCallDelta(id: call.id, argumentsFragment: delta)) }257258 case "response.output_item.done":259 if let item = json["item"], item["type"]?.stringValue == "function_call" {260 out += open(item)261 out += complete(itemID: item["id"]?.stringValue ?? item["call_id"]?.stringValue ?? "", finalArguments: item["arguments"]?.stringValue)262 }263264 case "response.completed", "response.incomplete":265 out += start(json["response"]); started = true266 out += completeAll()267 if let usage = usage(json["response"]?["usage"]) { out.append(.usage(usage)) }268 let reason: StopReason269 if type == "response.incomplete" {270 switch json["response"]?["incomplete_details"]?["reason"]?.stringValue {271 case "max_output_tokens": reason = .maxTokens272 case "content_filter": reason = .contentFilter273 default: reason = .unknown274 }275 } else {276 reason = emittedCalls ? .toolCalls : sawRefusal ? .contentFilter : .endOfTurn277 }278 out.append(.messageCompleted(reason))279 finished = true280281 case "response.failed":282 let error = json["response"]?["error"]283 throw Self.streamError(code: error?["code"]?.stringValue, message: error?["message"]?.stringValue, modelID: modelID)284285 case "error":286 let error = json["error"] ?? json287 throw Self.streamError(code: error["code"]?.stringValue ?? error["type"]?.stringValue, message: error["message"]?.stringValue ?? error.stringValue, modelID: modelID)288289 default:290 break // content parts, *.done echoes, hosted-tool progress, raw reasoning text: nothing to surface291 }292 return out293 }294295 private mutating func open(_ item: JSONValue) -> [StreamEvent] {296 let itemID = item["id"]?.stringValue ?? item["call_id"]?.stringValue ?? ""297 guard calls[itemID] == nil, let name = item["name"]?.stringValue else { return [] }298 let callID = item["call_id"]?.stringValue ?? itemID299 calls[itemID] = Call(id: callID, name: name)300 callOrder.append(itemID)301 emittedCalls = true302 return [.toolCallStarted(id: callID, name: name)]303 }304305 private mutating func complete(itemID: String, finalArguments: String?) -> [StreamEvent] {306 guard var call = calls[itemID], !call.completed else { return [] }307 var out: [StreamEvent] = []308 if let final = finalArguments, !final.isEmpty, final != call.arguments {309 // The provider sent the arguments whole (or the deltas were lost): surface the part not yet seen.310 if final.hasPrefix(call.arguments) {311 let rest = String(final.dropFirst(call.arguments.count))312 if !rest.isEmpty { out.append(.toolCallDelta(id: call.id, argumentsFragment: rest)) }313 }314 call.arguments = final315 }316 call.completed = true317 calls[itemID] = call318 out.append(.toolCallCompleted(ToolCall(id: call.id, name: call.name, arguments: ToolArguments.parse(call.arguments))))319 return out320 }321322 private mutating func completeAll() -> [StreamEvent] {323 var out: [StreamEvent] = []324 for itemID in callOrder { out += complete(itemID: itemID, finalArguments: nil) }325 return out326 }327328 /// `input_tokens` already counts cached tokens; `cached_tokens` and `cache_write_tokens` are subsets of it.329 func usage(_ json: JSONValue?) -> TokenUsage? {330 guard let json, json.objectValue != nil else { return nil }331 var cost: Double?332 if let divisor = costTicksPerUSD, let ticks = json["cost_in_usd_ticks"]?.doubleValue { cost = ticks / divisor }333 return TokenUsage(inputTokens: json["input_tokens"]?.intValue, outputTokens: json["output_tokens"]?.intValue,334 cachedInputTokens: json["input_tokens_details"]?["cached_tokens"]?.intValue,335 cacheWriteTokens: json["input_tokens_details"]?["cache_write_tokens"]?.intValue,336 reasoningTokens: json["output_tokens_details"]?["reasoning_tokens"]?.intValue, reportedCostUSD: cost)337 }338339 /// Errors that arrive inside a 200 stream carry a code, not a status: map the documented codes onto the HTTP classes.340 static func streamError(code: String?, message: String?, modelID: String) -> AstraError {341 let c = (code ?? "").lowercased()342 let status: Int343 if c.contains("rate_limit") || c.contains("slow_down") || c.contains("insufficient_quota") || c.contains("credit") || c.contains("spend_limit") || c.contains("usage_limit") {344 status = 429345 } else if c.contains("context_length") || c.contains("invalid") || c.contains("unsupported") || c.contains("content_policy") || c.contains("string_above_max_length") {346 status = 400347 } else if c.contains("overloaded") || c.contains("unavailable") {348 status = 503349 } else if c.contains("model_not_found") {350 status = 404351 } else if c.contains("authentication") || c.contains("api_key") {352 status = 401353 } else {354 status = 500355 }356 return mapHTTPError(status: status, code: code, message: message, retryAfter: nil, model: modelID)357 }358}359360/// Drives one Responses API generation: request (with parameter fallback), SSE decoding, terminal-event guarantee.361func runResponsesStream(http: ProviderHTTP, request: GenerationRequest, plan: ResponsesModelPlan, secrets: [String], costTicksPerUSD: Double? = nil,362 normalize: (ProviderHTTP.Failure) -> ProviderHTTP.Failure = { $0 },363 makeRequest: (JSONValue) throws -> URLRequest, continuation: EventContinuation) async throws {364 let body = ResponsesEncoder.body(request, plan: plan)365 let (_, lines) = try await http.openAdjusting(body: body, modelID: request.model.modelID, secrets: secrets, makeRequest: makeRequest,366 normalize: normalize, adjust: ResponsesEncoder.adjust)367 var parser = SSEParser()368 var decoder = ResponsesStreamDecoder(modelID: request.model.modelID, costTicksPerUSD: costTicksPerUSD)369 for try await line in lines {370 guard let event = parser.feed(line) else { continue }371 for out in try decoder.consume(event) { continuation.yield(out) }372 if decoder.finished { return }373 }374 if let event = parser.finish() { for out in try decoder.consume(event) { continuation.yield(out) } }375 try Task.checkCancellation()376 if !decoder.finished { throw AstraError.network("The connection closed before the answer was complete.") }377}378