Skip to main content

fetchium_core/token/
budget.rs

1//! Adaptive Token Budget (ATB) — dynamic token allocation based on query complexity.
2//!
3//! Simple factual queries get small token budgets (200-500 tokens).
4//! Complex deep-analysis queries get large budgets (5000+ tokens).
5//! This prevents wasting tokens on easy queries while ensuring thorough
6//! coverage for hard ones.
7
8use crate::rank::fusion::QueryIntent;
9
10/// Token budget configuration.
11#[derive(Debug, Clone)]
12pub struct BudgetConfig {
13    /// Minimum token budget for any query.
14    pub min_budget: u32,
15    /// Maximum token budget for any query.
16    pub max_budget: u32,
17    /// Number of results that affect budget (more results = more tokens).
18    pub tokens_per_result: u32,
19    /// Base overhead per query (formatting, metadata, etc.).
20    pub base_overhead: u32,
21}
22
23impl Default for BudgetConfig {
24    fn default() -> Self {
25        Self {
26            min_budget: 200,
27            max_budget: 10_000,
28            tokens_per_result: 150,
29            base_overhead: 100,
30        }
31    }
32}
33
34/// A computed token budget with allocation breakdown.
35#[derive(Debug, Clone)]
36pub struct AdaptiveBudget {
37    /// Total allocated tokens.
38    pub total: u32,
39    /// Tokens allocated for result content.
40    pub content_tokens: u32,
41    /// Tokens reserved for metadata/formatting.
42    pub overhead_tokens: u32,
43    /// Recommended max tokens per result.
44    pub per_result_limit: u32,
45    /// Budget tier for logging.
46    pub tier: BudgetTier,
47}
48
49/// Budget tier categories.
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51pub enum BudgetTier {
52    /// Minimal: quick factual answers (200-500 tokens).
53    Minimal,
54    /// Standard: typical searches (500-2000 tokens).
55    Standard,
56    /// Extended: complex queries (2000-5000 tokens).
57    Extended,
58    /// Deep: research/analysis queries (5000-10000 tokens).
59    Deep,
60}
61
62/// Compute the token budget for a query based on intent and result count.
63pub fn compute_budget(
64    intent: QueryIntent,
65    result_count: usize,
66    complexity_score: f64,
67    config: &BudgetConfig,
68) -> AdaptiveBudget {
69    // Base budget from intent
70    let intent_base = intent_base_budget(intent);
71
72    // Scale by complexity (0.0 → 0.5x, 0.5 → 1.0x, 1.0 → 2.0x)
73    let complexity_multiplier = 0.5 + complexity_score * 1.5;
74
75    // Result-based budget
76    let result_budget = result_count as u32 * config.tokens_per_result;
77
78    // Combined
79    let raw_total =
80        (intent_base as f64 * complexity_multiplier) as u32 + result_budget + config.base_overhead;
81
82    let total = raw_total.clamp(config.min_budget, config.max_budget);
83    let overhead = config.base_overhead.min(total);
84    let content_tokens = total - overhead;
85
86    let per_result_limit = if result_count > 0 {
87        content_tokens / result_count as u32
88    } else {
89        content_tokens
90    };
91
92    let tier = if total <= 500 {
93        BudgetTier::Minimal
94    } else if total <= 2000 {
95        BudgetTier::Standard
96    } else if total <= 5000 {
97        BudgetTier::Extended
98    } else {
99        BudgetTier::Deep
100    };
101
102    AdaptiveBudget {
103        total,
104        content_tokens,
105        overhead_tokens: overhead,
106        per_result_limit,
107        tier,
108    }
109}
110
111/// Get the PDS (Progressive Detail Streaming) tier token limits.
112pub fn pds_tier_limit(tier_name: &str) -> u32 {
113    match tier_name {
114        "key_facts" => 200,
115        "summary" => 1000,
116        "detailed" => 5000,
117        "complete" => 10_000,
118        _ => 1000,
119    }
120}
121
122/// Suggest the PDS tier based on available token budget.
123pub fn suggest_pds_tier(budget: &AdaptiveBudget) -> &'static str {
124    match budget.tier {
125        BudgetTier::Minimal => "key_facts",
126        BudgetTier::Standard => "summary",
127        BudgetTier::Extended => "detailed",
128        BudgetTier::Deep => "complete",
129    }
130}
131
132// ─── Internal ─────────────────────────────────────────────
133
134fn intent_base_budget(intent: QueryIntent) -> u32 {
135    match intent {
136        QueryIntent::Factual => 300,
137        QueryIntent::HowTo => 800,
138        QueryIntent::Comparison => 1500,
139        QueryIntent::Verification => 600,
140        QueryIntent::CurrentEvents => 700,
141        QueryIntent::DeepAnalysis => 3000,
142        QueryIntent::Code => 1200,
143        QueryIntent::Academic => 2000,
144        QueryIntent::Opinion => 800,
145        QueryIntent::Data => 1000,
146        QueryIntent::Informational => 500, // concise definitions
147        QueryIntent::Casual => 400,        // quick answers for everyday queries
148    }
149}
150
151#[cfg(test)]
152mod tests {
153    use super::*;
154
155    #[test]
156    fn factual_query_small_budget() {
157        let config = BudgetConfig::default();
158        let budget = compute_budget(QueryIntent::Factual, 1, 0.1, &config);
159        assert!(
160            budget.total <= 1000,
161            "factual should be small, got {}",
162            budget.total
163        );
164        assert!(matches!(
165            budget.tier,
166            BudgetTier::Minimal | BudgetTier::Standard
167        ));
168    }
169
170    #[test]
171    fn deep_analysis_large_budget() {
172        let config = BudgetConfig::default();
173        let budget = compute_budget(QueryIntent::DeepAnalysis, 10, 0.9, &config);
174        assert!(
175            budget.total >= 2000,
176            "deep analysis should be large, got {}",
177            budget.total
178        );
179        assert!(matches!(
180            budget.tier,
181            BudgetTier::Extended | BudgetTier::Deep
182        ));
183    }
184
185    #[test]
186    fn budget_respects_min_max() {
187        let config = BudgetConfig {
188            min_budget: 100,
189            max_budget: 500,
190            ..BudgetConfig::default()
191        };
192        let budget = compute_budget(QueryIntent::DeepAnalysis, 100, 1.0, &config);
193        assert!(budget.total <= 500);
194        assert!(budget.total >= 100);
195    }
196
197    #[test]
198    fn zero_results_uses_full_content_budget() {
199        let config = BudgetConfig::default();
200        let budget = compute_budget(QueryIntent::Factual, 0, 0.5, &config);
201        assert_eq!(budget.per_result_limit, budget.content_tokens);
202    }
203
204    #[test]
205    fn complexity_scales_budget() {
206        let config = BudgetConfig::default();
207        let low = compute_budget(QueryIntent::HowTo, 5, 0.1, &config);
208        let high = compute_budget(QueryIntent::HowTo, 5, 0.9, &config);
209        assert!(
210            high.total > low.total,
211            "higher complexity should mean bigger budget"
212        );
213    }
214
215    #[test]
216    fn per_result_limit_divides_evenly() {
217        let config = BudgetConfig::default();
218        let budget = compute_budget(QueryIntent::Code, 5, 0.5, &config);
219        assert!(budget.per_result_limit > 0);
220        assert!(budget.per_result_limit <= budget.content_tokens);
221    }
222
223    #[test]
224    fn pds_tier_suggestions() {
225        let minimal = AdaptiveBudget {
226            total: 300,
227            content_tokens: 200,
228            overhead_tokens: 100,
229            per_result_limit: 200,
230            tier: BudgetTier::Minimal,
231        };
232        assert_eq!(suggest_pds_tier(&minimal), "key_facts");
233
234        let deep = AdaptiveBudget {
235            total: 8000,
236            content_tokens: 7900,
237            overhead_tokens: 100,
238            per_result_limit: 790,
239            tier: BudgetTier::Deep,
240        };
241        assert_eq!(suggest_pds_tier(&deep), "complete");
242    }
243
244    #[test]
245    fn pds_tier_limits() {
246        assert_eq!(pds_tier_limit("key_facts"), 200);
247        assert_eq!(pds_tier_limit("summary"), 1000);
248        assert_eq!(pds_tier_limit("detailed"), 5000);
249        assert_eq!(pds_tier_limit("complete"), 10_000);
250        assert_eq!(pds_tier_limit("unknown"), 1000);
251    }
252
253    #[test]
254    fn overhead_never_exceeds_total() {
255        let config = BudgetConfig {
256            base_overhead: 5000,
257            min_budget: 200,
258            max_budget: 300,
259            ..BudgetConfig::default()
260        };
261        let budget = compute_budget(QueryIntent::Factual, 0, 0.0, &config);
262        assert!(budget.overhead_tokens <= budget.total);
263    }
264}