Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Sources/VQuantKit/Models/VQModels.swift3// Description: Model registry, routing preview, usage and cost (CONTRACT §2.1–2.3).4import Foundation56/// `GET /api/v2/models`7public struct VQModelCatalog: Sendable, Equatable, VQJSONDecodable {8 /// Id of the default model.9 public var defaultModel: String10 /// The "Auto" entry (`id: "auto"`): the server routes the request.11 public var auto: VQAutoModel12 public var providers: [VQModelProvider]1314 public init(json j: VQJSON) {15 defaultModel = j.str("default")16 auto = j.model("auto") ?? VQAutoModel(json: ["id": "auto", "label": "Auto"])17 providers = j.models("providers")18 }19 public var allModels: [VQModelInfo] { providers.flatMap(\.models) }20 /// Models a person can pick: available and tool-capable.21 public var selectableModels: [VQModelInfo] { allModels.filter(\.selectable) }22 public func model(_ id: String) -> VQModelInfo? { allModels.first { $0.id == id } }23 public func provider(_ id: String) -> VQModelProvider? { providers.first { $0.id == id } }24}2526public struct VQAutoModel: Sendable, Equatable, VQJSONDecodable {27 public var id: String28 public var label: String29 public init(json j: VQJSON) { id = j.str("id", "auto"); label = j.str("label", "Auto") }30}3132public struct VQModelProvider: Sendable, Equatable, Identifiable, VQJSONDecodable {33 /// `anthropic` | `openai` | `google` | `openrouter` | `local` (or a provider added later).34 public var id: String35 public var name: String36 /// A key (or base URL) is present on the server. No secret ever reaches a client.37 public var configured: Bool38 public var ok: Bool39 public var checkedAt: Date?40 public var error: String?41 /// Server path of the logo (`/brand/providers/<id>.svg`); VQuantUI draws the five known marks itself.42 public var logo: String?43 public var models: [VQModelInfo]44 public init(json j: VQJSON) {45 id = j.str("id"); name = j.str("name", id); configured = j.flag("configured"); ok = j.flag("ok")46 checkedAt = j.num("checkedAt").flatMap { $0 > 0 ? Date(timeIntervalSince1970: $0 / 1000) : nil }47 error = j.optStr("error"); logo = j.optStr("logo"); models = j.models("models")48 }49}5051public struct VQModelInfo: Sendable, Equatable, Identifiable, VQJSONDecodable {52 public enum Tier: String, Sendable, Hashable, CaseIterable { case frontier, balanced, fast }53 public enum Source: String, Sendable, Hashable, CaseIterable { case api, curated }54 /// Native id for Anthropic/OpenAI/Google, `openrouter:<vendor/model>`, `local:<model>`.55 public var id: String56 public var label: String57 public var provider: String58 public var tier: VQOpen<Tier>?59 /// nil when neither the repository nor the provider states it (never filled in from memory).60 public var contextWindow: Int?61 public var maxOutput: Int?62 public var pricing: Pricing?63 public var capabilities: Capabilities64 public var available: Bool65 public var source: VQOpen<Source>?66 /// Available and tool-capable: `POST /api/chat` falls back to the default model for anything else.67 public var selectable: Bool6869 public struct Pricing: Sendable, Equatable, VQJSONDecodable {70 /// USD per million tokens.71 public var inputPerMTok: Double?72 public var outputPerMTok: Double?73 public init(json j: VQJSON) { inputPerMTok = j.num("inputPerMTok"); outputPerMTok = j.num("outputPerMTok") }74 }75 public struct Capabilities: Sendable, Equatable, VQJSONDecodable {76 public var tools: Bool, vision: Bool, reasoning: Bool, streaming: Bool77 public init(json j: VQJSON) { tools = j.flag("tools"); vision = j.flag("vision"); reasoning = j.flag("reasoning"); streaming = j.flag("streaming") }78 }79 public init(json j: VQJSON) {80 id = j.str("id"); label = j.str("label", id); provider = j.str("provider"); tier = j.optOpen("tier")81 contextWindow = j.int("contextWindow"); maxOutput = j.int("maxOutput"); pricing = j.model("pricing")82 capabilities = Capabilities(json: j["capabilities"] ?? .null); available = j.flag("available")83 source = j.optOpen("source"); selectable = j.flag("selectable")84 }85}8687/// The router's decision: the `model_routed` stream event and `GET /api/v2/models/route` (same shape).88public struct VQRouteDecision: Sendable, Equatable, VQJSONDecodable {89 public var requested: String90 public var model: String91 public var provider: String92 /// One sentence explaining the choice.93 public var reason: String94 /// `quality` | `balanced` | `economy`95 public var strategy: String96 public var candidates: [Candidate]97 public struct Candidate: Sendable, Equatable, VQJSONDecodable {98 public var model: String99 public var score: Double?100 public var why: String101 public init(json j: VQJSON) { model = j.str("model"); score = j.num("score"); why = j.str("why") }102 }103 public init(json j: VQJSON) {104 requested = j.str("requested", "auto"); model = j.str("model"); provider = j.str("provider"); reason = j.str("reason")105 strategy = j.str("strategy"); candidates = j.models("candidates")106 }107}108109/// Token and cost counters. `costUsd` is nil as soon as one call has no known price (never guessed);110/// `knownCostUsd` is the sum of the calls that have one.111public struct VQUsageCounters: Sendable, Equatable, VQJSONDecodable {112 public var calls: Int?113 public var inputTokens: Int114 public var outputTokens: Int115 public var costUsd: Double?116 public var knownCostUsd: Double?117 public var unpricedCalls: Int?118 public init(json j: VQJSON) {119 calls = j.int("calls"); inputTokens = j.int("inputTokens") ?? 0; outputTokens = j.int("outputTokens") ?? 0120 costUsd = j.num("costUsd"); knownCostUsd = j.num("knownCostUsd"); unpricedCalls = j.int("unpricedCalls")121 }122}123124public struct VQUsageByModel: Sendable, Equatable, VQJSONDecodable {125 public enum Role: String, Sendable, Hashable, CaseIterable { case lead, worker, auditor, reviewer, router }126 public var model: String127 public var provider: String128 public var role: VQOpen<Role>?129 public var counters: VQUsageCounters130 public init(json j: VQJSON) { model = j.str("model"); provider = j.str("provider"); role = j.optOpen("role"); counters = VQUsageCounters(json: j) }131 /// `utility` = the small auxiliary calls of a generation (follow-up suggestions, the history summariser). It is132 /// not a case of `Role` (the enumeration is frozen for source compatibility): it decodes as `.unknown("utility")`.133 public var isUtility: Bool { role?.rawValue == "utility" }134}135136/// The `usage` object of a generation: on the `done` event, in the trace, on stored messages, on reviews.137public struct VQUsage: Sendable, Equatable, VQJSONDecodable {138 public var counters: VQUsageCounters139 public var byModel: [VQUsageByModel]140 public init(json j: VQJSON) { counters = VQUsageCounters(json: j); byModel = j.models("byModel") }141 public var inputTokens: Int { counters.inputTokens }142 public var outputTokens: Int { counters.outputTokens }143 public var costUsd: Double? { counters.costUsd }144}145146/// `GET /api/v2/usage?days=30`147public struct VQUsageReport: Sendable, Equatable, VQJSONDecodable {148 public var days: Int149 public var since: Date?150 public var totals: VQUsageCounters151 public var byDay: [Day]152 public var byModel: [VQUsageByModel]153 public struct Day: Sendable, Equatable, Identifiable, VQJSONDecodable {154 /// UTC, `YYYY-MM-DD`155 public var date: String156 public var counters: VQUsageCounters157 public var id: String { date }158 public init(json j: VQJSON) { date = j.str("date"); counters = VQUsageCounters(json: j) }159 }160 public init(json j: VQJSON) {161 days = j.int("days") ?? 0; since = j.date("since"); totals = VQUsageCounters(json: j["totals"] ?? .null)162 byDay = j.models("byDay"); byModel = j.models("byModel")163 }164}165166public struct VQModelsClient: Sendable {167 public let client: VQClient168 public init(client: VQClient) { self.client = client }169170 public func catalog() async throws -> VQModelCatalog { try await client.decode(.get("/api/v2/models")) }171172 /// Previews the router's decision without running anything.173 public func route(mode: String? = nil, vision: Bool? = nil, query: String? = nil) async throws -> VQRouteDecision {174 let q = VQQueryItem.optional("mode", mode) + VQQueryItem.optional("vision", vision.map { $0 ? "true" : "false" }) + VQQueryItem.optional("q", query)175 return try await client.decode(.get("/api/v2/models/route", q))176 }177178 public func usage(days: Int = 30) async throws -> VQUsageReport {179 try await client.decode(.get("/api/v2/usage", [VQQueryItem("days", String(days))]))180 }181182 /// The trace of a generation; with `sessionId` the latest generation of that conversation (whatever `id` is).183 public func trace(generation id: String = "latest", sessionId: String? = nil) async throws -> VQGenerationTrace {184 try await client.decode(.get("/api/v2/generations/\(VQRequest.segment(id))/trace", VQQueryItem.optional("sessionId", sessionId)))185 }186}187