SPB Git

Repository Public MIT

ResponsesAPI.swift 19.5 KB 378 lines swift

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

Theme