SPB Git

Repository Public MIT

Budget.swift 14.2 KB 287 lines swift

1// =============================================================================2//                  SP BOUCHER | SOFTWARE & RESEARCH3//             ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project          : ORIX Astra9// File             : Packages/AstraCore/Sources/Budget.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 Foundation8990/// Token estimation used when no tokenizer is available. Always labelled as an estimate in the UI.91public enum TokenEstimator {92    /// Conservative heuristic: about 3.6 UTF-8 bytes per token for Latin text, 1.6 characters for CJK. Overestimates slightly on purpose.93    public static func estimate(_ text: String) -> Int {94        guard !text.isEmpty else { return 0 }95        var cjk = 0, other = 096        for scalar in text.unicodeScalars {97            switch scalar.value {98            case 0x3040...0x30FF, 0x3400...0x4DBF, 0x4E00...0x9FFF, 0xAC00...0xD7AF, 0xF900...0xFAFF: cjk += 199            default: other += scalar.utf8.count100            }101        }102        return Int((Double(other) / 3.6).rounded(.up)) + Int((Double(cjk) / 1.6).rounded(.up))103    }104105    /// Per-image allowance; providers bill images differently, so this is a deliberately generous flat figure.106    public static let imageAllowance = 1_200107108    public static func estimate(_ message: PromptMessage) -> Int {109        var n = 4 + estimate(message.text) + message.images.count * imageAllowance110        for call in message.toolCalls { n += 8 + estimate(call.name) + estimate(call.arguments.serialized()) }111        return n112    }113}114115public enum TruncationStrategy: String, Sendable, Codable, CaseIterable, Identifiable {116    /// Drop the oldest turns until the conversation fits.117    case dropOldest118    /// Keep the first exchange (which usually sets the task) and the most recent turns; drop the middle.119    case keepFirstAndRecent120    /// Never drop anything: fail before sending when the conversation does not fit.121    case strict122    public var id: String { rawValue }123    public var title: String {124        switch self {125        case .dropOldest: "Drop oldest turns"126        case .keepFirstAndRecent: "Keep first exchange and recent turns"127        case .strict: "Never truncate"128        }129    }130}131132public struct ContextBudget: Sendable, Hashable, Codable {133    /// Total window in tokens (model limit, or the user's lower cap).134    public var window: Int135    /// Tokens reserved for the answer.136    public var reservedForOutput: Int137    public var strategy: TruncationStrategy138    public init(window: Int, reservedForOutput: Int, strategy: TruncationStrategy = .dropOldest) {139        self.window = max(256, window); self.reservedForOutput = max(0, reservedForOutput); self.strategy = strategy140    }141    public var inputBudget: Int { max(64, window - reservedForOutput) }142143    public struct Plan: Sendable, Hashable {144        public var messages: [PromptMessage]145        public var droppedCount: Int146        public var estimatedInputTokens: Int147        public var inputBudget: Int148        public var systemTokens: Int149        public var fits: Bool150        public var fraction: Double { inputBudget > 0 ? min(1, Double(estimatedInputTokens) / Double(inputBudget)) : 1 }151    }152153    /// Fits `messages` in the budget. Turns are dropped in whole units so a tool result never loses the call it answers,154    /// and the final user turn is never dropped.155    public func plan(system: String?, messages: [PromptMessage], toolsOverhead: Int = 0, count: (PromptMessage) -> Int = TokenEstimator.estimate) -> Plan {156        let systemTokens = (system.map(TokenEstimator.estimate) ?? 0) + toolsOverhead157        let units = Self.units(messages)158        let costs = units.map { $0.reduce(0) { $0 + count($1) } }159        let total = systemTokens + costs.reduce(0, +)160        if total <= inputBudget || units.count <= 1 || strategy == .strict {161            return Plan(messages: messages, droppedCount: 0, estimatedInputTokens: total, inputBudget: inputBudget, systemTokens: systemTokens, fits: total <= inputBudget)162        }163        var keep = Array(repeating: true, count: units.count)164        var running = total165        // candidates in drop order; the last unit (the turn being answered) is never a candidate166        let candidates: [Int] = switch strategy {167        case .keepFirstAndRecent: Array(Self.firstExchangeEnd(units)..<(units.count - 1))168        default: Array(0..<(units.count - 1))169        }170        for i in candidates where running > inputBudget { keep[i] = false; running -= costs[i] }171        if running > inputBudget, strategy == .keepFirstAndRecent {172            for i in 0..<(units.count - 1) where keep[i] && running > inputBudget { keep[i] = false; running -= costs[i] }173        }174        var kept: [PromptMessage] = []; var dropped = 0175        for (i, unit) in units.enumerated() { if keep[i] { kept += unit } else { dropped += unit.count } }176        // a conversation must not start with an assistant or tool turn after truncation177        while let first = kept.first, first.role != .user, kept.count > 1 { running -= count(first); kept.removeFirst(); dropped += 1 }178        return Plan(messages: kept, droppedCount: dropped, estimatedInputTokens: running, inputBudget: inputBudget, systemTokens: systemTokens, fits: running <= inputBudget)179    }180181    /// Groups an assistant turn that called tools with the tool results that answer it.182    static func units(_ messages: [PromptMessage]) -> [[PromptMessage]] {183        var out: [[PromptMessage]] = []184        for m in messages {185            if m.role == .tool, let last = out.last, last.first?.role == .assistant, !(last.first?.toolCalls.isEmpty ?? true) { out[out.count - 1].append(m) }186            else { out.append([m]) }187        }188        return out189    }190191    static func firstExchangeEnd(_ units: [[PromptMessage]]) -> Int {192        var i = 0193        if i < units.count, units[i].first?.role == .user { i += 1 }194        while i < units.count, units[i].first?.role != .user { i += 1 }195        return min(i, max(0, units.count - 1))196    }197}198199// MARK: - Cost200201/// A cost figure with its basis. `amountUSD` is nil when either usage or pricing is unavailable; it is never guessed.202public struct CostEstimate: Sendable, Hashable, Codable {203    public enum Basis: String, Sendable, Codable {204        case reportedByProvider, estimatedFromUsage, estimatedFromText, onDevice, unavailable205    }206    public var amountUSD: Double?207    public var basis: Basis208    public var pricingAsOf: String?209    public init(amountUSD: Double?, basis: Basis, pricingAsOf: String? = nil) { self.amountUSD = amountUSD; self.basis = basis; self.pricingAsOf = pricingAsOf }210    public static let unavailable = CostEstimate(amountUSD: nil, basis: .unavailable)211    public static let onDevice = CostEstimate(amountUSD: 0, basis: .onDevice)212213    public var label: String {214        switch basis {215        case .onDevice: return "On device"216        case .unavailable: return "Cost unavailable"217        default:218            guard let amountUSD else { return "Cost unavailable" }219            let prefix = basis == .reportedByProvider ? "" : "≈ "220            return prefix + Self.format(amountUSD)221        }222    }223224    public static func format(_ usd: Double) -> String {225        if usd == 0 { return "$0" }226        if usd < 0.0001 { return "< $0.0001" }227        if usd < 0.01 { return String(format: "$%.4f", usd) }228        if usd < 1 { return String(format: "$%.3f", usd) }229        return String(format: "$%.2f", usd)230    }231}232233public enum UsageAccounting {234    /// Cost of a finished generation: the provider's own figure when it reports one, otherwise usage × published price.235    public static func cost(usage: TokenUsage?, pricing: Pricing?, provider: ProviderKind) -> CostEstimate {236        if provider.isLocal { return .onDevice }237        if let reported = usage?.reportedCostUSD { return CostEstimate(amountUSD: reported, basis: .reportedByProvider) }238        guard let usage, let pricing, usage.inputTokens != nil || usage.outputTokens != nil else { return .unavailable }239        let cached = usage.cachedInputTokens ?? 0240        let written = usage.cacheWriteTokens ?? 0241        // Providers differ on whether cached tokens are included in input_tokens; adapters normalise so that242        // `inputTokens` is the total prompt and cached / written counts are subsets of it.243        let fresh = max(0, (usage.inputTokens ?? 0) - cached - written)244        var usd = Double(fresh) * pricing.inputPerMTok245        usd += Double(cached) * (pricing.cachedInputPerMTok ?? pricing.inputPerMTok)246        usd += Double(written) * (pricing.cacheWritePerMTok ?? pricing.inputPerMTok)247        usd += Double(usage.outputTokens ?? 0) * pricing.outputPerMTok248        return CostEstimate(amountUSD: usd / 1_000_000, basis: .estimatedFromUsage, pricingAsOf: pricing.asOf)249    }250251    /// Upper-bound estimate before sending (Arena guard): estimated prompt tokens plus the full output cap.252    public static func preflight(inputTokens: Int, maxOutputTokens: Int, pricing: Pricing?, provider: ProviderKind) -> CostEstimate {253        if provider.isLocal { return .onDevice }254        guard let pricing else { return .unavailable }255        let usd = (Double(inputTokens) * pricing.inputPerMTok + Double(maxOutputTokens) * pricing.outputPerMTok) / 1_000_000256        return CostEstimate(amountUSD: usd, basis: .estimatedFromText, pricingAsOf: pricing.asOf)257    }258}259260/// Drops or adjusts parameters a model does not accept, and reports what was changed so the UI can say so.261public enum ParameterNegotiator {262    public struct Result: Sendable, Hashable {263        public var parameters: GenerationParameters264        public var tools: [ToolDefinition]265        public var notes: [String]266    }267268    public static func negotiate(_ parameters: GenerationParameters, tools: [ToolDefinition], images: Bool, for model: ModelInfo) -> Result {269        var p = parameters; var t = tools; var notes: [String] = []270        if let supported = model.supportedParameters {271            if p.temperature != nil, !supported.contains("temperature") { p.temperature = nil; notes.append("Temperature is not accepted by this model.") }272            if p.topP != nil, !supported.contains("top_p") { p.topP = nil; notes.append("Top-p is not accepted by this model.") }273            if p.seed != nil, !supported.contains("seed") { p.seed = nil; notes.append("Seed is not accepted by this model.") }274            if !p.stop.isEmpty, !supported.contains("stop") { p.stop = []; notes.append("Stop sequences are not accepted by this model.") }275        }276        if let effort = p.reasoning, effort != .off, !model.capabilities.contains(.reasoning) {277            p.reasoning = nil; notes.append("This model has no reasoning control.")278        }279        if !t.isEmpty, !model.capabilities.contains(.tools) { t = []; notes.append("This model does not support tools.") }280        if images, !model.capabilities.contains(.vision) { notes.append("This model cannot read images; they were left out.") }281        if let cap = model.maxOutputTokens, let requested = p.maxOutputTokens, requested > cap {282            p.maxOutputTokens = cap; notes.append("Output limit lowered to the model's maximum (\(cap)).")283        }284        return Result(parameters: p, tools: t, notes: notes)285    }286}287
Files main
Menu

Theme