SPB Git

Repository Public

VQModels.swift 9.1 KB 187 lines swift

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

Theme