1use 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#[derive(Debug, Clone)]
37pub struct RouterConfig {
38 pub privacy_score_threshold: usize,
40 pub circuit_breaker_threshold: u32,
42 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#[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#[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
219pub 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 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 pub fn evaluate(&self, context: &StructuredContext) -> DecisionBackendResult {
335 let input = ModelInput::current_only(context.clone());
336 self.evaluate_model_input(&input)
337 }
338
339 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 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 (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 if !result.rationale_tags.iter().any(|tag| tag == &reason_tag) {
420 result.rationale_tags.push(reason_tag);
421 }
422
423 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 fn determine_route(&self, context: &StructuredContext) -> (DecisionRoute, RoutingReason) {
437 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 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 if Self::has_local_actionable_signal(context) {
476 return (
477 DecisionRoute::LocalEvaluator,
478 RoutingReason::LocalActionableSignal,
479 );
480 }
481
482 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 (
506 DecisionRoute::LocalEvaluator,
507 RoutingReason::LocalPreferred { complexity },
508 )
509 }
510
511 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 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;