Repository Public MIT
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