Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: SPChat/Core/Models/ArenaModels.swift3// Description: Arena (multi-model comparison): typed SSE events, the pure accumulator that turns them into columns, stored comparisons, judge, and the endpoints.4import Foundation56// MARK: - Events78/// What the server knows about a model before its answer arrives: an estimate of the input side only.9public struct ArenaEstimate: Sendable, Hashable {10 public var inputTokens: Int?11 public var inputCostUsd: Double?12 /// The server's own wording of how the estimate was made — shown verbatim.13 public var basis: String?1415 public init(inputTokens: Int? = nil, inputCostUsd: Double? = nil, basis: String? = nil) { self.inputTokens = inputTokens; self.inputCostUsd = inputCostUsd; self.basis = basis }16 init?(_ j: JSONValue?) {17 guard let j, j.objectValue != nil else { return nil }18 inputTokens = j["inputTokens"]?.intValue; inputCostUsd = j["inputCostUsd"]?.doubleValue; basis = j["basis"]?.stringValue19 }20}2122/// One model announced by the `start` event.23public struct ArenaModelInfo: Sendable, Hashable, Identifiable {24 public var id: String25 public var provider: String?26 public var route: String?27 public var creator: String?28 public var logo: String?29 public var displayName: String?30 public var estimate: ArenaEstimate?3132 init?(_ j: JSONValue) {33 guard let id = j["id"]?.stringValue, !id.isEmpty else { return nil }34 self.id = id; provider = j["provider"]?.stringValue; route = j["route"]?.stringValue; creator = j["creator"]?.stringValue35 logo = j["logo"]?.stringValue; displayName = j["displayName"]?.stringValue; estimate = ArenaEstimate(j["estimate"])36 }37}3839/// The measured result of one model: the `model_done` payload, and a row of a stored comparison's `results`.40public struct ArenaResult: Sendable, Hashable {41 public var modelId: String42 public var provider: String?43 public var route: String?44 public var creator: String?45 public var logo: String?46 public var displayName: String?47 /// Who actually served the request (« OpenRouter · Google »), when the route reports it.48 public var servedBy: String?49 public var text: String50 public var reasoning: String51 public var inputTokens: Int?52 public var outputTokens: Int?53 public var cachedTokens: Int?54 public var reasoningTokens: Int?55 public var costUsd: Double?56 /// true = the provider reported the billed amount; false = tokens × list price; nil = the row predates the field.57 public var exactCost: Bool?58 public var latencyMs: Int?59 public var ttftMs: Int?60 public var error: String?6162 public init?(_ j: JSONValue) {63 guard let id = j["modelId"]?.stringValue, !id.isEmpty else { return nil }64 modelId = id; provider = j["provider"]?.stringValue; route = j["route"]?.stringValue; creator = j["creator"]?.stringValue65 logo = j["logo"]?.stringValue; displayName = j["displayName"]?.stringValue; servedBy = j["servedBy"]?.stringValue66 text = j["text"]?.stringValue ?? ""; reasoning = j["reasoning"]?.stringValue ?? ""67 let u = j["usage"]68 inputTokens = u?["input"]?.intValue; outputTokens = u?["output"]?.intValue; cachedTokens = u?["cached"]?.intValue; reasoningTokens = u?["reasoning"]?.intValue69 costUsd = j["costUsd"]?.doubleValue; exactCost = j["exactCost"]?.boolValue70 latencyMs = j["latencyMs"]?.intValue; ttftMs = j["ttftMs"]?.intValue71 if let e = j["error"]?.stringValue, !e.isEmpty { error = e }72 }73}7475/// Events of a `POST /api/compare` run. Unknown event names and malformed payloads never fail: they become `.unknown`.76public enum ArenaEvent: Sendable, Equatable {77 case start(id: String?, models: [ArenaModelInfo])78 case text(model: String, delta: String)79 case reasoning(model: String, delta: String)80 case modelError(model: String, message: String)81 case modelDone(ArenaResult)82 case done(id: String?)83 /// Run-level failure (`error` event).84 case failure(message: String)85 case unknown(String)8687 public init(_ e: SSEEvent) { self.init(event: e.event, data: JSONValue.parse(Data(e.data.utf8)) ?? .null) }8889 public init(event: String, data d: JSONValue) {90 switch event {91 case "start": self = .start(id: d["id"]?.stringValue, models: (d["models"]?.arrayValue ?? []).compactMap(ArenaModelInfo.init))92 case "text":93 if let m = d["model"]?.stringValue, let delta = d["delta"]?.stringValue { self = .text(model: m, delta: delta) } else { self = .unknown(event) }94 case "reasoning":95 if let m = d["model"]?.stringValue, let delta = d["delta"]?.stringValue { self = .reasoning(model: m, delta: delta) } else { self = .unknown(event) }96 case "model_error":97 if let m = d["model"]?.stringValue { self = .modelError(model: m, message: d["message"]?.stringValue ?? "Erreur") } else { self = .unknown(event) }98 case "model_done":99 if let r = ArenaResult(d) { self = .modelDone(r) } else { self = .unknown(event) }100 case "done": self = .done(id: d["id"]?.stringValue)101 case "error": self = .failure(message: d["message"]?.stringValue ?? d["error"]?.stringValue ?? "Erreur")102 default: self = .unknown(event)103 }104 }105}106107// MARK: - Accumulator108109/// One column of the Arena: a model, its live stream, then its measured figures.110public struct ArenaColumn: Sendable, Hashable, Identifiable {111 public var modelId: String112 public var provider: String?113 public var route: String?114 public var logo: String?115 public var displayName: String?116 public var servedBy: String?117 public var estimate: ArenaEstimate?118 public var text = ""119 public var reasoning = ""120 public var inputTokens: Int?121 public var outputTokens: Int?122 public var reasoningTokens: Int?123 public var costUsd: Double?124 public var exactCost: Bool?125 public var latencyMs: Int?126 public var ttftMs: Int?127 public var error: String?128 public var done = false129 public var id: String { modelId }130131 public init(modelId: String, provider: String? = nil) { self.modelId = modelId; self.provider = provider }132 public init(result r: ArenaResult) { self.init(modelId: r.modelId); apply(r) }133134 public var hasAnswer: Bool { done && error == nil && !text.isEmpty }135 /// « facturé » only when the provider reported the billed amount for this very request.136 public var isBilledCost: Bool { exactCost == true }137138 mutating func apply(_ m: ArenaModelInfo) {139 provider = m.provider ?? provider; route = m.route ?? route; logo = m.logo ?? logo; displayName = m.displayName ?? displayName; estimate = m.estimate ?? estimate140 }141 mutating func apply(_ r: ArenaResult) {142 provider = r.provider ?? provider; route = r.route ?? route; logo = r.logo ?? logo; displayName = r.displayName ?? displayName; servedBy = r.servedBy ?? servedBy143 // the final text is authoritative, but a result without text never erases what was streamed144 if !r.text.isEmpty { text = r.text }145 if !r.reasoning.isEmpty { reasoning = r.reasoning }146 inputTokens = r.inputTokens; outputTokens = r.outputTokens; reasoningTokens = r.reasoningTokens147 costUsd = r.costUsd; exactCost = r.exactCost; latencyMs = r.latencyMs; ttftMs = r.ttftMs148 if let e = r.error { error = e }149 done = true150 }151}152153/// Folds the events of a run into columns. Pure: no clock, no I/O — the same events always give the same columns.154/// Columns keep the order the models were requested in; an event for a model that was not announced adds a column155/// rather than being dropped.156public struct ArenaAccumulator: Sendable, Equatable {157 public private(set) var columns: [ArenaColumn]158 public private(set) var comparisonId: String?159 /// The server sent `done`: the comparison is stored and can be preferred, judged, adopted, exported.160 public private(set) var finished = false161 public private(set) var failure: String?162163 public init(modelIds: [String] = [], provider: (String) -> String? = { _ in nil }) {164 var seen = Set<String>()165 columns = modelIds.filter { seen.insert($0).inserted }.map { ArenaColumn(modelId: $0, provider: provider($0)) }166 }167168 private mutating func index(_ modelId: String) -> Int {169 if let i = columns.firstIndex(where: { $0.modelId == modelId }) { return i }170 columns.append(ArenaColumn(modelId: modelId)); return columns.count - 1171 }172173 /// Returns true when the event changed what is displayed.174 @discardableResult public mutating func apply(_ event: ArenaEvent) -> Bool {175 switch event {176 case .start(let id, let models):177 if let id { comparisonId = id }178 for m in models { let i = index(m.id); columns[i].apply(m) }179 return true180 case .text(let model, let delta):181 guard !delta.isEmpty else { return false }182 let i = index(model); guard !columns[i].done else { return false }183 columns[i].text += delta; return true184 case .reasoning(let model, let delta):185 guard !delta.isEmpty else { return false }186 let i = index(model); guard !columns[i].done else { return false }187 columns[i].reasoning += delta; return true188 case .modelError(let model, let message):189 let i = index(model); columns[i].error = message; return true190 case .modelDone(let result):191 let i = index(result.modelId); columns[i].apply(result); return true192 case .done(let id):193 if let id { comparisonId = id }194 finished = true; return true195 case .failure(let message): failure = message; return true196 case .unknown: return false197 }198 }199200 /// The stream is over (ended, stopped or lost): nothing more will arrive, every column stops waiting.201 public mutating func close() { for i in columns.indices { columns[i].done = true } }202203 public var comparableAnswers: Int { columns.filter(\.hasAnswer).count }204}205206// MARK: - Stored comparisons207208public struct ArenaJudge: Sendable, Hashable {209 public var judgeModel: String210 public var text: String211 /// Anonymous letter → model id, in letter order.212 public var mapping: [Label]213 public var costUsd: Double?214 public var disclaimer: String215 public struct Label: Sendable, Hashable { public var label: String; public var modelId: String }216217 public init?(_ j: JSONValue?) {218 guard let j, let text = j["text"]?.stringValue else { return nil }219 self.text = text220 judgeModel = j["judgeModel"]?.stringValue ?? j["modelId"]?.stringValue ?? "?"221 mapping = (j["mapping"]?.objectValue ?? [:]).compactMap { k, v in v.stringValue.map { Label(label: k, modelId: $0) } }.sorted { $0.label < $1.label }222 costUsd = j["costUsd"]?.doubleValue223 disclaimer = j["disclaimer"]?.stringValue ?? "Évaluation générée par un modèle : une opinion, pas une vérité objective."224 }225 public func label(for modelId: String) -> String? { mapping.first { $0.modelId == modelId }?.label }226}227228/// A row of the history (`GET /api/compare`).229public struct ArenaHistoryItem: Sendable, Hashable, Identifiable {230 public var id: String231 public var prompt: String232 public var modelIds: [String]233 public var preferredModel: String?234 public var createdAt: Date?235 public var cost: Double?236237 public init?(_ j: JSONValue) {238 guard let id = j["id"]?.stringValue, !id.isEmpty else { return nil }239 self.id = id; prompt = j["prompt"]?.stringValue ?? ""240 modelIds = j["model_ids"]?.arrayValue?.compactMap(\.stringValue) ?? []241 preferredModel = j["preferred_model"]?.stringValue242 createdAt = j["created_at"]?.stringValue.flatMap(ServerDate.parse)243 cost = j["cost"]?.doubleValue244 }245}246247/// A stored comparison (`GET /api/compare?id=`).248public struct ArenaComparison: Sendable, Hashable, Identifiable {249 public var id: String250 public var prompt: String251 public var modelIds: [String]252 public var columns: [ArenaColumn]253 public var judge: ArenaJudge?254 public var preferredModel: String?255 public var conversationId: String?256 public var createdAt: Date?257258 public init?(_ j: JSONValue?) {259 guard let j, let id = j["id"]?.stringValue, !id.isEmpty else { return nil }260 self.id = id; prompt = j["prompt"]?.stringValue ?? ""261 modelIds = j["model_ids"]?.arrayValue?.compactMap(\.stringValue) ?? []262 columns = (j["results"]?.arrayValue ?? []).compactMap(ArenaResult.init).map(ArenaColumn.init(result:))263 judge = ArenaJudge(j["judge"]); preferredModel = j["preferred_model"]?.stringValue264 conversationId = j["conversation_id"]?.stringValue265 createdAt = j["created_at"]?.stringValue.flatMap(ServerDate.parse)266 }267}268269public enum ArenaExportFormat: String, Sendable, CaseIterable { case markdown = "md", json }270271// MARK: - Endpoints272273public extension APIClient {274 /// `POST /api/compare` — the same prompt to 2–6 models of any route; the answer is a detached SSE run.275 func openArena(prompt: String, modelIds: [String], effort: String? = nil, projectId: String? = nil) async throws -> StreamOpening {276 var payload: [String: JSONValue] = ["prompt": .string(prompt), "modelIds": .array(modelIds.map(JSONValue.string))]277 if let effort { payload["settings"] = ["effort": .string(effort)] }278 if let projectId { payload["projectId"] = .string(projectId) }279 return try await openStream(.post, "/api/compare", body: Data(JSONValue.object(payload).jsonString().utf8))280 }281 func arenaHistory() async throws -> [ArenaHistoryItem] {282 (try await json(.get, "/api/compare")["comparisons"]?.arrayValue ?? []).compactMap(ArenaHistoryItem.init)283 }284 /// nil when the server has no such comparison (yet).285 func arenaComparison(_ id: String) async throws -> ArenaComparison? { ArenaComparison(try await json(.get, "/api/compare", query: ["id": id])["comparison"]) }286 func preferArenaAnswer(comparisonId: String, modelId: String) async throws {287 _ = try await json(.patch, "/api/compare", body: ["id": .string(comparisonId), "preferredModel": .string(modelId)])288 }289 /// A real, billed model call: the judge reads the answers anonymously.290 func judgeArena(comparisonId: String, judgeModel: String) async throws -> ArenaJudge? {291 ArenaJudge(try await json(.post, "/api/compare/judge", body: ["id": .string(comparisonId), "judgeModel": .string(judgeModel)], timeout: 300)["judge"])292 }293 /// `POST /api/conversations/{id}/adopt` — brings an Arena answer into a conversation (no model is called again).294 /// Returns the id of the adopted message.295 @discardableResult func adoptArenaAnswer(conversationId: String, comparisonId: String, modelId: String) async throws -> String? {296 try await json(.post, "/api/conversations/\(conversationId)/adopt", body: ["comparisonId": .string(comparisonId), "modelId": .string(modelId)])["messageId"]?.stringValue297 }298 /// `GET /api/compare/export?id=&format=md|json` — the document written by the server.299 func exportArena(comparisonId: String, format: ArenaExportFormat) async throws -> DownloadedFile {300 try await download("/api/compare/export", query: ["id": comparisonId, "format": format.rawValue])301 }302}303