Skip to main content

aios_agent/router/
mod.rs

1//! DecisionRouter - multi-tier decision routing.
2//!
3//! Routing priority:
4//! 1. Circuit breaker: too many consecutive backend errors -> FallbackNoOp.
5//! 2. Privacy sensitivity: notifications with verification/financial hints ->
6//!    RuleBased (blocks cloud routing while keeping sensitive data local).
7//!    App transitions carry no raw text and are excluded from the privacy score,
8//!    so they pass through this gate unchanged.
9//! 3. Local actionable signal: foreground transitions, file activity, actionable
10//!    notifications -> LocalEvaluator (so next-app prediction and other local
11//!    proactive actions are not blocked by the privacy gate).
12//! 4. Semantic complexity: low complexity -> RuleBased, medium/high -> CloudLlm
13//!    when configured, otherwise LocalEvaluator.
14use std::cell::RefCell;
15use std::collections::HashSet;
16#[cfg(test)]
17use std::sync::{Arc, Mutex};
18use std::time::{Duration, Instant};
19
20use aios_spec::{
21    ActionType, DecisionBackendResult, DecisionRoute, Intent, IntentBatch, IntentType, ModelInput,
22    SanitizedEventType, SemanticHint, StructuredContext,
23};
24
25use crate::backends::cloud_llm::CloudBackendState;
26use crate::backends::fallback::FallbackNoOpBackend;
27use crate::backends::local_evaluator::LocalEvaluatorBackend;
28use crate::backends::predictive::PredictiveLocalBackend;
29use crate::backends::rule_based::RuleBasedBackend;
30use crate::DecisionBackend;
31
32// ============================================================
33// RouterConfig
34// ============================================================
35
36#[derive(Debug, Clone)]
37pub struct RouterConfig {
38    /// Number of privacy-sensitive signals above which cloud routing is blocked.
39    pub privacy_score_threshold: usize,
40    /// Number of consecutive errors before the circuit breaker trips.
41    pub circuit_breaker_threshold: u32,
42    /// Time window (in seconds) over which consecutive errors are counted.
43    pub circuit_breaker_window_secs: u64,
44}
45
46impl Default for RouterConfig {
47    fn default() -> Self {
48        Self {
49            privacy_score_threshold: 3,
50            circuit_breaker_threshold: 5,
51            circuit_breaker_window_secs: 60,
52        }
53    }
54}
55
56// ============================================================
57// Circuit breaker state
58// ============================================================
59
60#[derive(Debug, Clone)]
61struct ErrorRecord {
62    timestamp: Instant,
63}
64
65#[derive(Debug, Clone, Default)]
66struct CircuitState {
67    errors: Vec<ErrorRecord>,
68}
69
70impl CircuitState {
71    fn record_error(&mut self) {
72        self.errors.push(ErrorRecord {
73            timestamp: Instant::now(),
74        });
75    }
76
77    fn record_success(&mut self) {
78        self.errors.clear();
79    }
80
81    fn count_recent_errors(&self, window_secs: u64) -> u32 {
82        let cutoff = Instant::now()
83            .checked_sub(Duration::from_secs(window_secs))
84            .unwrap_or(Instant::now());
85        self.errors.iter().filter(|e| e.timestamp >= cutoff).count() as u32
86    }
87}
88
89struct CompositeLocalEvaluatorBackend {
90    heuristic: LocalEvaluatorBackend,
91    predictive: PredictiveLocalBackend,
92}
93
94impl CompositeLocalEvaluatorBackend {
95    fn new(predictive: PredictiveLocalBackend) -> Self {
96        Self {
97            heuristic: LocalEvaluatorBackend,
98            predictive,
99        }
100    }
101
102    fn merge_results(
103        &self,
104        input: &ModelInput,
105        heuristic: DecisionBackendResult,
106        predictive: DecisionBackendResult,
107    ) -> DecisionBackendResult {
108        let mut heuristic_intents = heuristic.intent_batch.intents;
109        let mut predictive_intents = predictive.intent_batch.intents;
110        let heuristic_idle = take_idle_noop(&mut heuristic_intents);
111        let predictive_idle = take_idle_noop(&mut predictive_intents);
112
113        let mut intents = heuristic_intents;
114        intents.extend(predictive_intents);
115        if intents.is_empty() {
116            if let Some(intent) = heuristic_idle.or(predictive_idle) {
117                intents.push(intent);
118            }
119        }
120
121        let mut rationale_tags = heuristic.rationale_tags;
122        merge_tags(&mut rationale_tags, predictive.rationale_tags);
123        let error = merge_errors(heuristic.error, predictive.error);
124
125        DecisionBackendResult {
126            route: DecisionRoute::LocalEvaluator,
127            intent_batch: IntentBatch {
128                window_id: input.current_context.window_id.clone(),
129                intents,
130                generated_at_ms: input.current_context.window_end_ms,
131                model: "local-evaluator+predictive-local-v0.1".into(),
132            },
133            rationale_tags,
134            latency_us: heuristic.latency_us + predictive.latency_us,
135            error,
136        }
137    }
138}
139
140impl DecisionBackend for CompositeLocalEvaluatorBackend {
141    fn evaluate(&self, context: &StructuredContext) -> DecisionBackendResult {
142        let input = ModelInput::current_only(context.clone());
143        self.evaluate_model_input(&input)
144    }
145
146    fn evaluate_model_input(&self, input: &ModelInput) -> DecisionBackendResult {
147        let heuristic = self.heuristic.evaluate_model_input(input);
148        let predictive = self.predictive.evaluate_model_input(input);
149        self.merge_results(input, heuristic, predictive)
150    }
151}
152
153fn take_idle_noop(intents: &mut Vec<Intent>) -> Option<Intent> {
154    intents
155        .iter()
156        .position(is_idle_noop)
157        .map(|idx| intents.remove(idx))
158}
159
160fn is_idle_noop(intent: &Intent) -> bool {
161    matches!(intent.intent_type, IntentType::Idle)
162        && intent
163            .suggested_actions
164            .iter()
165            .all(|action| action.action_type == ActionType::NoOp)
166}
167
168fn merge_tags(target: &mut Vec<String>, source: Vec<String>) {
169    for tag in source {
170        if !target.contains(&tag) {
171            target.push(tag);
172        }
173    }
174}
175
176fn merge_errors(left: Option<String>, right: Option<String>) -> Option<String> {
177    match (left, right) {
178        (Some(left), Some(right)) => Some(format!("{left}; {right}")),
179        (Some(error), None) | (None, Some(error)) => Some(error),
180        (None, None) => None,
181    }
182}
183
184// ============================================================
185// Routing reason
186// ============================================================
187
188#[derive(Debug, Clone)]
189enum RoutingReason {
190    CircuitBreakerTripped { failure_count: u32 },
191    PrivacySensitive { score: usize },
192    LocalActionableSignal,
193    LowComplexity,
194    LocalPreferred { complexity: &'static str },
195    CloudPreferred { complexity: &'static str },
196}
197
198impl RoutingReason {
199    fn tag(&self) -> String {
200        match self {
201            RoutingReason::CircuitBreakerTripped { failure_count } => {
202                format!("routing:circuit_breaker_fallback(errors={failure_count})")
203            },
204            RoutingReason::PrivacySensitive { score } => {
205                format!("routing:privacy_sensitive(score={score})")
206            },
207            RoutingReason::LocalActionableSignal => "routing:local_actionable_signal".into(),
208            RoutingReason::LowComplexity => "routing:low_complexity".into(),
209            RoutingReason::LocalPreferred { complexity } => {
210                format!("routing:{complexity}_complexity(local_evaluator)")
211            },
212            RoutingReason::CloudPreferred { complexity } => {
213                format!("routing:{complexity}_complexity(cloud_llm)")
214            },
215        }
216    }
217}
218
219// ============================================================
220// DecisionRouter
221// ============================================================
222
223pub struct DecisionRouter {
224    config: RouterConfig,
225    rule_based: Box<dyn DecisionBackend + Send + Sync>,
226    local_evaluator: Box<dyn DecisionBackend + Send + Sync>,
227    fallback: Box<dyn DecisionBackend + Send + Sync>,
228    cloud_llm: Option<Box<dyn DecisionBackend + Send + Sync>>,
229    cloud_disabled: bool,
230    cloud_misconfigured: Option<String>,
231    circuit_state: RefCell<CircuitState>,
232    /// Optional runtime user id supplied by the environment. This is a stop-gap
233    /// until the daemon/collector plumbs a real `UserBehaviorProfile` through
234    /// `ModelInput`. When present it is attached to the default behavior profile
235    /// so personalized models (e.g. `PredictiveLocalBackend`) can key per-user
236    /// transition tables.
237    runtime_user_id: Option<String>,
238}
239
240impl DecisionRouter {
241    pub fn new(config: RouterConfig) -> Self {
242        let cloud_state = CloudBackendState::from_env();
243        if let CloudBackendState::Misconfigured(error) = &cloud_state {
244            tracing::warn!(
245                error = %error,
246                "cloud llm backend configuration ignored; DecisionRouter will stay local"
247            );
248        }
249
250        let (cloud_llm, cloud_disabled, cloud_misconfigured) = match cloud_state {
251            CloudBackendState::Ready(backend) => {
252                let backend: Box<dyn DecisionBackend + Send + Sync> = Box::new(backend);
253                (Some(backend), false, None)
254            },
255            CloudBackendState::Disabled => (None, true, None),
256            CloudBackendState::Misconfigured(error) => (None, false, Some(error)),
257        };
258
259        let local_evaluator: Box<dyn DecisionBackend + Send + Sync> = match std::env::var(
260            "DIPECS_NEXT_APP_MODEL_PATH",
261        ) {
262            Ok(path) if !path.trim().is_empty() => match PredictiveLocalBackend::from_path(&path) {
263                Ok(backend) => Box::new(CompositeLocalEvaluatorBackend::new(backend)),
264                Err(error) => {
265                    tracing::warn!(error = %error, "next-app model ignored; falling back to heuristic local evaluator");
266                    Box::new(LocalEvaluatorBackend)
267                },
268            },
269            _ => Box::new(LocalEvaluatorBackend),
270        };
271
272        let runtime_user_id = std::env::var("DIPECS_NEXT_APP_USER_ID")
273            .ok()
274            .filter(|s| !s.trim().is_empty());
275
276        Self {
277            config,
278            rule_based: Box::new(RuleBasedBackend),
279            local_evaluator,
280            fallback: Box::new(FallbackNoOpBackend),
281            cloud_llm,
282            cloud_disabled,
283            cloud_misconfigured,
284            circuit_state: RefCell::new(CircuitState::default()),
285            runtime_user_id,
286        }
287    }
288
289    #[cfg(test)]
290    fn with_backends(
291        config: RouterConfig,
292        rule_based: Box<dyn DecisionBackend + Send + Sync>,
293        local_evaluator: Box<dyn DecisionBackend + Send + Sync>,
294        cloud_llm: Option<Box<dyn DecisionBackend + Send + Sync>>,
295        fallback: Box<dyn DecisionBackend + Send + Sync>,
296    ) -> Self {
297        Self::with_backends_and_runtime_user_id(
298            config,
299            rule_based,
300            local_evaluator,
301            cloud_llm,
302            fallback,
303            None,
304        )
305    }
306
307    #[cfg(test)]
308    fn with_backends_and_runtime_user_id(
309        config: RouterConfig,
310        rule_based: Box<dyn DecisionBackend + Send + Sync>,
311        local_evaluator: Box<dyn DecisionBackend + Send + Sync>,
312        cloud_llm: Option<Box<dyn DecisionBackend + Send + Sync>>,
313        fallback: Box<dyn DecisionBackend + Send + Sync>,
314        runtime_user_id: Option<String>,
315    ) -> Self {
316        let cloud_disabled = cloud_llm.is_none();
317        Self {
318            config,
319            rule_based,
320            local_evaluator,
321            fallback,
322            cloud_llm,
323            cloud_disabled,
324            cloud_misconfigured: None,
325            circuit_state: RefCell::new(CircuitState::default()),
326            runtime_user_id,
327        }
328    }
329
330    /// Evaluate a StructuredContext through the routing pipeline.
331    ///
332    /// Uses interior mutability (`RefCell`) to track circuit breaker state
333    /// across calls without requiring `&mut self`.
334    pub fn evaluate(&self, context: &StructuredContext) -> DecisionBackendResult {
335        let input = ModelInput::current_only(context.clone());
336        self.evaluate_model_input(&input)
337    }
338
339    /// Evaluate with an explicit behavior profile. Callers that already have a
340    /// `UserBehaviorProfile` (e.g. the daemon after aggregating recent feedback)
341    /// should use this so personalized backends receive `user_id` and history.
342    pub fn evaluate_with_profile(
343        &self,
344        context: &StructuredContext,
345        profile: aios_spec::UserBehaviorProfile,
346    ) -> DecisionBackendResult {
347        let mut input = ModelInput::current_only(context.clone());
348        input.behavior_profile = profile;
349        self.evaluate_model_input(&input)
350    }
351
352    /// Evaluate a model input that includes the current window plus optional
353    /// behavior profile and recent feedback memory.
354    pub fn evaluate_model_input(&self, input: &ModelInput) -> DecisionBackendResult {
355        let owned_input;
356        let input = if input.behavior_profile.user_id.is_none() {
357            if let Some(user_id) = &self.runtime_user_id {
358                owned_input = {
359                    let mut input = input.clone();
360                    input.behavior_profile.user_id = Some(user_id.clone());
361                    input
362                };
363                &owned_input
364            } else {
365                input
366            }
367        } else {
368            input
369        };
370        let context = &input.current_context;
371        let (route, reason) = self.determine_route(context);
372        let reason_tag = reason.tag();
373
374        let (mut result, backend_failed) = match route {
375            DecisionRoute::RuleBased => {
376                let result = self.rule_based.evaluate_model_input(input);
377                let backend_failed = result.error.is_some();
378                (result, backend_failed)
379            },
380            DecisionRoute::LocalEvaluator => {
381                let result = self.local_evaluator.evaluate_model_input(input);
382                let backend_failed = result.error.is_some();
383                (result, backend_failed)
384            },
385            DecisionRoute::CloudLlm => match &self.cloud_llm {
386                Some(backend) => {
387                    let cloud_result = backend.evaluate_model_input(input);
388                    if let Some(error) = cloud_result.error.as_deref() {
389                        let mut fallback = self.rule_based.evaluate_model_input(input);
390                        fallback.error = Some(format!("cloud llm backend failed: {error}"));
391                        fallback
392                            .rationale_tags
393                            .push("backend:cloud_llm_error(rule_based_fallback)".to_string());
394                        (fallback, true)
395                    } else {
396                        (cloud_result, false)
397                    }
398                },
399                None => {
400                    let result = self.rule_based.evaluate_model_input(input);
401                    let backend_failed = result.error.is_some();
402                    (result, backend_failed)
403                },
404            },
405            DecisionRoute::FallbackNoOp => {
406                let result = self.fallback.evaluate_model_input(input);
407                // FallbackNoOp may preserve an audit error while successfully
408                // generating the safe NoOp used to probe recovery.
409                (result, false)
410            },
411            _ => {
412                let result = self.rule_based.evaluate_model_input(input);
413                let backend_failed = result.error.is_some();
414                (result, backend_failed)
415            },
416        };
417
418        // Inject routing reason tag
419        if !result.rationale_tags.iter().any(|tag| tag == &reason_tag) {
420            result.rationale_tags.push(reason_tag);
421        }
422
423        // Update circuit breaker state
424        let mut state = self.circuit_state.borrow_mut();
425        if backend_failed {
426            state.record_error();
427        } else {
428            state.record_success();
429        }
430
431        result
432    }
433
434    // --- Private routing logic ---
435
436    fn determine_route(&self, context: &StructuredContext) -> (DecisionRoute, RoutingReason) {
437        // Priority 1: Circuit breaker
438        let error_count = self
439            .circuit_state
440            .borrow()
441            .count_recent_errors(self.config.circuit_breaker_window_secs);
442        if error_count >= self.config.circuit_breaker_threshold {
443            return (
444                DecisionRoute::FallbackNoOp,
445                RoutingReason::CircuitBreakerTripped {
446                    failure_count: error_count,
447                },
448            );
449        }
450
451        // Priority 2: Privacy sensitivity.
452        //
453        // App transitions are deliberately *not* counted as privacy-sensitive
454        // (they carry no raw text), so this gate only fires for notifications
455        // with VerificationCode / FinancialContext hints.
456        let privacy_score = Self::compute_privacy_score(context);
457        if privacy_score > self.config.privacy_score_threshold {
458            return (
459                DecisionRoute::RuleBased,
460                RoutingReason::PrivacySensitive {
461                    score: privacy_score,
462                },
463            );
464        }
465
466        // Priority 3: Low-risk proactive local signals.
467        //
468        // LocalEvaluator owns prefetch, process prewarm, and work-scoped
469        // keepalive. These are exactly the low-risk signals the next-app
470        // predictor needs (foreground transitions, file activity, and
471        // non-sensitive actionable notifications). Since the privacy gate above
472        // no longer counts AppTransition, app-transition-heavy windows are not
473        // trapped in RuleBased, while truly sensitive notification windows
474        // still route conservatively.
475        if Self::has_local_actionable_signal(context) {
476            return (
477                DecisionRoute::LocalEvaluator,
478                RoutingReason::LocalActionableSignal,
479            );
480        }
481
482        // Priority 4: Semantic complexity
483        let unique_types = Self::count_unique_semantic_hint_types(context);
484        match unique_types {
485            0 | 1 => (DecisionRoute::RuleBased, RoutingReason::LowComplexity),
486            2 | 3 => self.cloud_route_or_fallback("medium"),
487            _ => self.cloud_route_or_fallback("high"),
488        }
489    }
490
491    fn cloud_route_or_fallback(&self, complexity: &'static str) -> (DecisionRoute, RoutingReason) {
492        if self.cloud_llm.is_some() {
493            return (
494                DecisionRoute::CloudLlm,
495                RoutingReason::CloudPreferred { complexity },
496            );
497        }
498        if self.cloud_disabled || self.cloud_misconfigured.is_some() {
499            return (
500                DecisionRoute::LocalEvaluator,
501                RoutingReason::LocalPreferred { complexity },
502            );
503        }
504        // No cloud backend available; stay local for safety.
505        (
506            DecisionRoute::LocalEvaluator,
507            RoutingReason::LocalPreferred { complexity },
508        )
509    }
510
511    /// Count privacy-sensitive signals. Only notification events carrying
512    /// `VerificationCode` or `FinancialContext` hints are counted; app
513    /// transitions carry no raw text and are excluded from this score, so they
514    /// pass through the privacy gate unchanged and are then handled by
515    /// `has_local_actionable_signal` below.
516    fn compute_privacy_score(context: &StructuredContext) -> usize {
517        context
518            .events
519            .iter()
520            .map(|event| match &event.event_type {
521                SanitizedEventType::Notification { semantic_hints, .. } => semantic_hints
522                    .iter()
523                    .filter(|h| {
524                        matches!(
525                            h,
526                            SemanticHint::VerificationCode | SemanticHint::FinancialContext
527                        )
528                    })
529                    .count(),
530                _ => 0,
531            })
532            .sum()
533    }
534
535    fn has_local_actionable_signal(context: &StructuredContext) -> bool {
536        context.events.iter().any(|event| match &event.event_type {
537            SanitizedEventType::FileActivity { .. } => true,
538            SanitizedEventType::Notification { semantic_hints, .. } => {
539                semantic_hints.iter().any(|hint| {
540                    matches!(
541                        hint,
542                        SemanticHint::FileMention
543                            | SemanticHint::ImageMention
544                            | SemanticHint::LinkAttachment
545                    )
546                })
547            },
548            SanitizedEventType::AppTransition {
549                transition: aios_spec::AppTransition::Foreground,
550                ..
551            } => true,
552            _ => false,
553        })
554    }
555
556    /// Count unique SemanticHint variants across all notification events.
557    fn count_unique_semantic_hint_types(context: &StructuredContext) -> usize {
558        let mut seen: HashSet<&SemanticHint> = HashSet::new();
559        for event in &context.events {
560            if let SanitizedEventType::Notification { semantic_hints, .. } = &event.event_type {
561                for hint in semantic_hints {
562                    seen.insert(hint);
563                }
564            }
565        }
566        seen.len()
567    }
568}
569
570impl Default for DecisionRouter {
571    fn default() -> Self {
572        Self::new(RouterConfig::default())
573    }
574}
575
576#[cfg(test)]
577mod tests;