lean_ctx/core/
intent_router.rs

1use serde::Serialize;
2
3use crate::core::budget_tracker::{BudgetLevel, BudgetSnapshot};
4use crate::core::context_ledger::PressureAction;
5use crate::core::intent_engine::{classify, route_intent, IntentDimension, ModelTier, TaskType};
6
7#[derive(Debug, Clone, Serialize)]
8pub struct IntentRouteV1 {
9    pub schema_version: u32,
10    pub created_at: String,
11    pub inputs: IntentRouteInputsV1,
12    pub decision: IntentRouteDecisionV1,
13}
14
15#[derive(Debug, Clone, Serialize)]
16pub struct IntentRouteInputsV1 {
17    pub query_md5: String,
18    pub query_redacted: String,
19    pub role: String,
20    pub profile: String,
21    pub task_type: TaskType,
22    pub confidence: f64,
23    pub dimension: IntentDimension,
24    pub budgets: BudgetSnapshot,
25    pub pressure: PressureSummaryV1,
26    pub policy_md5: String,
27}
28
29#[derive(Debug, Clone, Serialize)]
30pub struct PressureSummaryV1 {
31    pub utilization_pct: u8,
32    pub remaining_tokens: usize,
33    pub action: PressureActionV1,
34}
35
36#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
37#[serde(rename_all = "snake_case")]
38pub enum PressureActionV1 {
39    NoAction,
40    SuggestCompression,
41    ForceCompression,
42    EvictLeastRelevant,
43}
44
45impl PressureActionV1 {
46    fn from_action(a: PressureAction) -> Self {
47        match a {
48            PressureAction::NoAction => Self::NoAction,
49            PressureAction::SuggestCompression => Self::SuggestCompression,
50            PressureAction::ForceCompression => Self::ForceCompression,
51            PressureAction::EvictLeastRelevant => Self::EvictLeastRelevant,
52        }
53    }
54}
55
56#[derive(Debug, Clone, Serialize)]
57pub struct IntentRouteDecisionV1 {
58    pub recommended_model_tier: ModelTier,
59    pub effective_model_tier: ModelTier,
60    pub recommended_read_mode: String,
61    pub effective_read_mode: String,
62    pub degraded_by_budget: bool,
63    pub degraded_by_pressure: bool,
64    pub reason: String,
65}
66
67#[derive(Debug, Clone)]
68pub struct RouteInputs {
69    pub tokens_level: BudgetLevel,
70    pub cost_level: BudgetLevel,
71    pub pressure_action: PressureAction,
72    pub pressure_utilization: f64,
73    pub pressure_remaining_tokens: usize,
74}
75
76pub fn route_v1(query: &str) -> IntentRouteV1 {
77    let budgets = crate::core::budget_tracker::BudgetTracker::global().check();
78    let ledger = crate::core::context_ledger::ContextLedger::load();
79    let pressure = ledger.pressure();
80    let profile_name = crate::core::profiles::active_profile_name();
81    let profile = crate::core::profiles::active_profile();
82    let role_name = crate::core::roles::active_role_name();
83
84    let inputs = RouteInputs {
85        tokens_level: budgets.tokens.level.clone(),
86        cost_level: budgets.cost.level.clone(),
87        pressure_action: pressure.recommendation,
88        pressure_utilization: pressure.utilization,
89        pressure_remaining_tokens: pressure.remaining_tokens,
90    };
91
92    route_v1_with(
93        query,
94        &role_name,
95        &profile_name,
96        &profile.routing,
97        budgets,
98        &inputs,
99        None,
100    )
101}
102
103pub fn route_v1_with(
104    query: &str,
105    role_name: &str,
106    profile_name: &str,
107    routing: &crate::core::profiles::RoutingConfig,
108    budgets: BudgetSnapshot,
109    inputs: &RouteInputs,
110    created_at_override: Option<&str>,
111) -> IntentRouteV1 {
112    let created_at = created_at_override.map_or_else(
113        || chrono::Utc::now().to_rfc3339(),
114        std::string::ToString::to_string,
115    );
116
117    let classification = classify(query);
118    let base = route_intent(query, &classification);
119
120    let query_redacted = truncate(&crate::core::redaction::redact_text(query), 180);
121    let query_md5 = crate::core::hasher::hash_str(query);
122
123    let policy_md5 = crate::core::hasher::hash_str(&format!(
124        "max_model_tier={};degrade_under_pressure={}",
125        routing.max_model_tier_effective(),
126        routing.degrade_under_pressure_effective()
127    ));
128
129    let recommended_model_tier = base.model_tier;
130    let tokens_level = inputs.tokens_level.clone();
131    let cost_level = inputs.cost_level.clone();
132    let (effective_model_tier, degraded_by_budget) = apply_budget_caps(
133        recommended_model_tier,
134        tokens_level.clone(),
135        cost_level.clone(),
136        routing,
137    );
138
139    let recommended_read_mode =
140        read_mode_for_tier(recommended_model_tier, classification.task_type);
141    let (effective_read_mode, degraded_by_pressure) = if routing.degrade_under_pressure_effective()
142    {
143        apply_pressure_degrade(&recommended_read_mode, inputs.pressure_action)
144    } else {
145        (recommended_read_mode.clone(), false)
146    };
147
148    let reason = build_reason(&ReasonInputs {
149        task_type: classification.task_type,
150        dimension: base.dimension,
151        recommended_tier: recommended_model_tier,
152        effective_tier: effective_model_tier,
153        read_mode: effective_read_mode.clone(),
154        degraded_by_budget,
155        degraded_by_pressure,
156        tokens_level,
157        cost_level,
158        pressure: inputs.pressure_action,
159    });
160
161    IntentRouteV1 {
162        schema_version: crate::core::contracts::INTENT_ROUTE_V1_SCHEMA_VERSION,
163        created_at,
164        inputs: IntentRouteInputsV1 {
165            query_md5,
166            query_redacted,
167            role: role_name.to_string(),
168            profile: profile_name.to_string(),
169            task_type: classification.task_type,
170            confidence: classification.confidence,
171            dimension: base.dimension,
172            budgets,
173            pressure: PressureSummaryV1 {
174                utilization_pct: (inputs.pressure_utilization * 100.0).min(254.0) as u8,
175                remaining_tokens: inputs.pressure_remaining_tokens,
176                action: PressureActionV1::from_action(inputs.pressure_action),
177            },
178            policy_md5,
179        },
180        decision: IntentRouteDecisionV1 {
181            recommended_model_tier,
182            effective_model_tier,
183            recommended_read_mode,
184            effective_read_mode,
185            degraded_by_budget,
186            degraded_by_pressure,
187            reason,
188        },
189    }
190}
191
192fn apply_budget_caps(
193    tier: ModelTier,
194    tokens_level: BudgetLevel,
195    cost_level: BudgetLevel,
196    routing: &crate::core::profiles::RoutingConfig,
197) -> (ModelTier, bool) {
198    let mut out = tier;
199    let mut degraded = false;
200
201    // Hard cap from profile policy.
202    out = cap_to(out, parse_tier_cap(routing.max_model_tier_effective()));
203    if out != tier {
204        degraded = true;
205    }
206
207    // Budget-based caps (recommendation only; never blocks).
208    let max_budget = worst_budget_level(tokens_level, cost_level);
209    out = match max_budget {
210        BudgetLevel::Ok => out,
211        BudgetLevel::Warning => cap_to(out, ModelTier::Standard),
212        BudgetLevel::Exhausted => cap_to(out, ModelTier::Fast),
213    };
214    if out != tier {
215        degraded = true;
216    }
217
218    (out, degraded)
219}
220
221fn worst_budget_level(a: BudgetLevel, b: BudgetLevel) -> BudgetLevel {
222    match (a, b) {
223        (BudgetLevel::Exhausted, _) | (_, BudgetLevel::Exhausted) => BudgetLevel::Exhausted,
224        (BudgetLevel::Warning, _) | (_, BudgetLevel::Warning) => BudgetLevel::Warning,
225        _ => BudgetLevel::Ok,
226    }
227}
228
229fn parse_tier_cap(s: &str) -> ModelTier {
230    match s.trim().to_lowercase().as_str() {
231        "fast" => ModelTier::Fast,
232        "standard" => ModelTier::Standard,
233        _ => ModelTier::Premium,
234    }
235}
236
237fn cap_to(tier: ModelTier, cap: ModelTier) -> ModelTier {
238    match cap {
239        ModelTier::Fast => ModelTier::Fast,
240        ModelTier::Standard => match tier {
241            ModelTier::Premium => ModelTier::Standard,
242            _ => tier,
243        },
244        ModelTier::Premium => tier,
245    }
246}
247
248pub fn read_mode_for_tier(tier: ModelTier, task_type: TaskType) -> String {
249    match (tier, task_type) {
250        (ModelTier::Fast, _) => "signatures".to_string(),
251        (ModelTier::Standard, TaskType::Explore | TaskType::Review) => "map".to_string(),
252        (ModelTier::Standard, _) => "full".to_string(),
253        (ModelTier::Premium, _) => "auto".to_string(),
254    }
255}
256
257fn apply_pressure_degrade(mode: &str, pressure: PressureAction) -> (String, bool) {
258    if let Some(downgraded) = crate::core::auto_mode_resolver::pressure_downgrade(mode, &pressure) {
259        (downgraded, true)
260    } else {
261        (mode.to_string(), false)
262    }
263}
264
265struct ReasonInputs {
266    task_type: TaskType,
267    dimension: IntentDimension,
268    recommended_tier: ModelTier,
269    effective_tier: ModelTier,
270    read_mode: String,
271    degraded_by_budget: bool,
272    degraded_by_pressure: bool,
273    tokens_level: BudgetLevel,
274    cost_level: BudgetLevel,
275    pressure: PressureAction,
276}
277
278fn build_reason(i: &ReasonInputs) -> String {
279    format!(
280        "task={} dim={} tier={}→{} read={} budget={} pressure={:?} degrade(budget={},pressure={})",
281        i.task_type.as_str(),
282        i.dimension.as_str(),
283        i.recommended_tier.as_str(),
284        i.effective_tier.as_str(),
285        i.read_mode,
286        worst_budget_level(i.tokens_level.clone(), i.cost_level.clone()),
287        i.pressure,
288        i.degraded_by_budget,
289        i.degraded_by_pressure
290    )
291}
292
293fn truncate(s: &str, max: usize) -> String {
294    if s.chars().count() <= max {
295        return s.to_string();
296    }
297    s.chars().take(max).collect()
298}
299
300#[cfg(test)]
301mod tests {
302    use super::*;
303    use crate::core::budget_tracker::{BudgetLevel, CostStatus, DimensionStatus};
304
305    fn budget(level: BudgetLevel) -> BudgetSnapshot {
306        BudgetSnapshot {
307            role: "coder".to_string(),
308            tokens: DimensionStatus {
309                used: 1,
310                limit: 1,
311                percent: 100,
312                level: level.clone(),
313            },
314            shell: DimensionStatus {
315                used: 0,
316                limit: 0,
317                percent: 0,
318                level: BudgetLevel::Ok,
319            },
320            cost: CostStatus {
321                used_usd: 0.0,
322                limit_usd: 0.0,
323                percent: 0,
324                level,
325            },
326        }
327    }
328
329    #[test]
330    fn routing_is_deterministic_for_same_inputs() {
331        let r = crate::core::profiles::RoutingConfig::default();
332        let b = budget(BudgetLevel::Ok);
333        let inputs = RouteInputs {
334            tokens_level: BudgetLevel::Ok,
335            cost_level: BudgetLevel::Ok,
336            pressure_action: PressureAction::NoAction,
337            pressure_utilization: 0.1,
338            pressure_remaining_tokens: 1000,
339        };
340        let a = route_v1_with(
341            "fix bug in src/lib.rs",
342            "coder",
343            "bugfix",
344            &r,
345            b.clone(),
346            &inputs,
347            Some("2026-01-01T00:00:00Z"),
348        );
349        let b2 = route_v1_with(
350            "fix bug in src/lib.rs",
351            "coder",
352            "bugfix",
353            &r,
354            b,
355            &inputs,
356            Some("2026-01-01T00:00:00Z"),
357        );
358        assert_eq!(
359            serde_json::to_string(&a).unwrap(),
360            serde_json::to_string(&b2).unwrap()
361        );
362    }
363
364    #[test]
365    fn budget_caps_premium_to_fast_when_exhausted() {
366        let routing = crate::core::profiles::RoutingConfig {
367            max_model_tier: Some("premium".to_string()),
368            ..Default::default()
369        };
370        let b = budget(BudgetLevel::Exhausted);
371        let inputs = RouteInputs {
372            tokens_level: BudgetLevel::Exhausted,
373            cost_level: BudgetLevel::Ok,
374            pressure_action: PressureAction::NoAction,
375            pressure_utilization: 0.1,
376            pressure_remaining_tokens: 1000,
377        };
378        let r = route_v1_with(
379            "implement feature x",
380            "coder",
381            "exploration",
382            &routing,
383            b,
384            &inputs,
385            Some("2026-01-01T00:00:00Z"),
386        );
387        assert_eq!(r.decision.effective_model_tier, ModelTier::Fast);
388        assert!(r.decision.degraded_by_budget);
389    }
390
391    #[test]
392    fn pressure_forces_degraded_mode() {
393        let routing = crate::core::profiles::RoutingConfig::default();
394        let b = budget(BudgetLevel::Ok);
395        let inputs = RouteInputs {
396            tokens_level: BudgetLevel::Ok,
397            cost_level: BudgetLevel::Ok,
398            pressure_action: PressureAction::EvictLeastRelevant,
399            pressure_utilization: 0.95,
400            pressure_remaining_tokens: 100,
401        };
402        let r = route_v1_with(
403            "review the auth module",
404            "coder",
405            "review",
406            &routing,
407            b,
408            &inputs,
409            Some("2026-01-01T00:00:00Z"),
410        );
411        assert!(
412            r.decision.effective_read_mode == "signatures"
413                || r.decision.effective_read_mode == "reference",
414            "expected degraded mode, got: {}",
415            r.decision.effective_read_mode
416        );
417        assert!(r.decision.degraded_by_pressure);
418    }
419}
lean_ctx/core/intent_router.rs

lean_ctx/core/
intent_router.rs
