Skip to main content

fetchium_core/search/
backend_selector.rs

1//! Adaptive Backend Selector (ABS) — smart per-query backend routing.
2//!
3//! Novel algorithm: Instead of querying all backends for every query, ABS
4//! dynamically selects the most promising backends based on:
5//!
6//! 1. **Query intent** — Academic queries prefer arXiv + Scholar; code queries
7//!    prefer GitHub + StackOverflow; news queries prefer HackerNews + Reddit.
8//! 2. **Historical success rates** — Backends that have returned good results
9//!    for similar queries in the past are preferred.
10//! 3. **Current health** — Backends with open circuit breakers are skipped.
11//!
12//! Uses a **UCB1 multi-armed bandit** to balance exploration (trying backends
13//! that haven't been used recently) vs exploitation (using backends known to work).
14
15use crate::rank::fusion::QueryIntent;
16use crate::types::BackendId;
17use dashmap::DashMap;
18use std::sync::atomic::{AtomicU64, Ordering};
19use std::sync::Arc;
20
21/// Configuration for the Adaptive Backend Selector.
22#[derive(Debug, Clone)]
23pub struct AbsConfig {
24    /// Minimum number of backends to always include.
25    pub min_backends: usize,
26    /// Maximum number of backends to select.
27    pub max_backends: usize,
28    /// UCB1 exploration parameter (higher = more exploration).
29    pub exploration_factor: f64,
30    /// Whether to always include at least one "reliable" backend.
31    pub always_include_reliable: bool,
32}
33
34impl Default for AbsConfig {
35    fn default() -> Self {
36        Self {
37            min_backends: 3,
38            max_backends: 8,
39            exploration_factor: 1.41, // sqrt(2), standard UCB1
40            always_include_reliable: true,
41        }
42    }
43}
44
45/// Per-backend performance statistics.
46#[derive(Debug)]
47struct BackendStats {
48    /// Total number of times this backend was selected.
49    selections: AtomicU64,
50    /// Total number of successful queries (returned >= 1 result).
51    successes: AtomicU64,
52    /// Total reward (sum of quality scores from results).
53    total_reward: AtomicU64, // stored as reward * 1000 to avoid floating point atomics
54}
55
56impl BackendStats {
57    fn new() -> Self {
58        Self {
59            selections: AtomicU64::new(0),
60            successes: AtomicU64::new(0),
61            total_reward: AtomicU64::new(0),
62        }
63    }
64
65    fn success_rate(&self) -> f64 {
66        let sel = self.selections.load(Ordering::Relaxed);
67        if sel == 0 {
68            return 0.5; // optimistic prior
69        }
70        self.successes.load(Ordering::Relaxed) as f64 / sel as f64
71    }
72
73    fn avg_reward(&self) -> f64 {
74        let sel = self.selections.load(Ordering::Relaxed);
75        if sel == 0 {
76            return 0.5; // optimistic prior
77        }
78        (self.total_reward.load(Ordering::Relaxed) as f64 / 1000.0) / sel as f64
79    }
80}
81
82/// Intent-to-backend affinity matrix.
83///
84/// Maps query intents to their preferred backends with affinity scores.
85fn intent_affinity(intent: &QueryIntent, backend: &BackendId) -> f64 {
86    // SearXNG is a META-SEARCH engine (aggregates Google, Bing, Brave, DDG, Wikipedia,
87    // StackOverflow, GitHub, ArXiv). It should ALWAYS be selected because it provides
88    // the broadest coverage of any single backend.
89    if *backend == BackendId::Searxng {
90        return 0.85; // High for all intents — it covers everything
91    }
92
93    // Premium backends also get consistently high scores — they provide
94    // pre-scored, AI-optimized results when API keys are available.
95    match backend {
96        BackendId::Tavily | BackendId::Serper | BackendId::Exa | BackendId::Firecrawl => {
97            return 0.80; // Premium backends always valuable
98        }
99        _ => {}
100    }
101
102    match intent {
103        QueryIntent::Academic | QueryIntent::Data => match backend {
104            BackendId::Arxiv => 0.95,
105            BackendId::GoogleScholar => 0.90,
106            BackendId::Wikipedia => 0.70,
107            BackendId::StackOverflow => 0.60,
108            BackendId::Github => 0.50,
109            _ => 0.30,
110        },
111        QueryIntent::Code => match backend {
112            BackendId::Github => 0.95,
113            BackendId::StackOverflow => 0.90,
114            BackendId::HackerNews => 0.50,
115            BackendId::Reddit => 0.40,
116            _ => 0.30,
117        },
118        QueryIntent::HowTo => match backend {
119            BackendId::StackOverflow => 0.95,
120            BackendId::Github => 0.80,
121            BackendId::DuckDuckGo => 0.80,
122            BackendId::Google => 0.75,
123            BackendId::Brave => 0.70,
124            BackendId::Bing => 0.65,
125            BackendId::Wikipedia => 0.15,
126            BackendId::Arxiv => 0.10,
127            BackendId::Reddit => 0.35,
128            _ => 0.40,
129        },
130        QueryIntent::CurrentEvents => match backend {
131            BackendId::HackerNews => 0.90,
132            BackendId::Reddit => 0.85,
133            BackendId::Google => 0.75,
134            BackendId::Bing => 0.65,
135            BackendId::DuckDuckGo => 0.60,
136            BackendId::Brave => 0.55,
137            BackendId::StackOverflow => 0.30,
138            BackendId::Github => 0.15,
139            BackendId::Wikipedia => 0.10, // Wikipedia almost never useful for temporal queries
140            BackendId::Arxiv => 0.10,     // ArXiv returns old papers, not news
141            _ => 0.30,
142        },
143        QueryIntent::Comparison => match backend {
144            BackendId::DuckDuckGo => 0.85,
145            BackendId::Google => 0.80,
146            BackendId::Brave => 0.75,
147            BackendId::Bing => 0.70,
148            BackendId::StackOverflow => 0.68,
149            BackendId::Wikipedia => 0.60,
150            BackendId::Reddit => 0.20,
151            BackendId::HackerNews => 0.20,
152            BackendId::Arxiv => 0.05,
153            _ => 0.40,
154        },
155        QueryIntent::Factual => match backend {
156            BackendId::Wikipedia => 0.95,
157            BackendId::DuckDuckGo => 0.70,
158            BackendId::Google => 0.65,
159            BackendId::Brave => 0.60,
160            BackendId::Github => 0.20,
161            _ => 0.40,
162        },
163        QueryIntent::Informational => match backend {
164            BackendId::Wikipedia => 0.95,
165            BackendId::DuckDuckGo => 0.80,
166            BackendId::Google => 0.75,
167            BackendId::Brave => 0.70,
168            BackendId::Bing => 0.65,
169            BackendId::StackOverflow => 0.55,
170            BackendId::Reddit => 0.45,
171            BackendId::HackerNews => 0.40,
172            BackendId::Arxiv => 0.35,
173            BackendId::Github => 0.10,
174            _ => 0.40,
175        },
176        QueryIntent::Verification => match backend {
177            BackendId::Wikipedia => 0.90,
178            BackendId::Arxiv => 0.85,
179            BackendId::GoogleScholar => 0.80,
180            BackendId::DuckDuckGo => 0.60,
181            _ => 0.35,
182        },
183        QueryIntent::Opinion => match backend {
184            BackendId::Reddit => 0.90,
185            BackendId::HackerNews => 0.85,
186            BackendId::StackOverflow => 0.80,
187            BackendId::DuckDuckGo => 0.70,
188            BackendId::Google => 0.65,
189            BackendId::Brave => 0.60,
190            BackendId::Wikipedia => 0.40,
191            BackendId::Arxiv => 0.15,
192            _ => 0.50,
193        },
194        QueryIntent::Casual => match backend {
195            BackendId::DuckDuckGo => 0.85,
196            BackendId::Google => 0.85,
197            BackendId::Brave => 0.80,
198            BackendId::Bing => 0.75,
199            BackendId::Reddit => 0.70,
200            BackendId::Wikipedia => 0.30,
201            BackendId::HackerNews => 0.20,
202            BackendId::StackOverflow => 0.10,
203            BackendId::Github => 0.05,
204            BackendId::Arxiv => 0.05,
205            BackendId::GoogleScholar => 0.05,
206            _ => 0.40,
207        },
208        _ => match backend {
209            BackendId::DuckDuckGo => 0.70,
210            BackendId::Google => 0.70,
211            BackendId::StackOverflow => 0.65,
212            BackendId::Bing => 0.60,
213            BackendId::Brave => 0.60,
214            BackendId::Wikipedia => 0.55,
215            _ => 0.50,
216        },
217    }
218}
219
220/// Hard precision guardrails: exclude backends that are consistently off-intent.
221///
222/// This runs before ranking so noisy sources are never selected for clearly
223/// mismatched intents (for example StackOverflow for medical or policy queries).
224fn intent_backend_allowed(intent: &QueryIntent, backend: &BackendId) -> bool {
225    match intent {
226        QueryIntent::CurrentEvents => !matches!(
227            backend,
228            BackendId::StackOverflow | BackendId::Github | BackendId::Arxiv
229        ),
230        QueryIntent::Factual | QueryIntent::Informational => {
231            // ArXiv returns papers for ANY search term — flooding non-academic queries
232            // with irrelevant results. Only allow ArXiv for Academic/Verification intents.
233            !matches!(
234                backend,
235                BackendId::StackOverflow | BackendId::Github | BackendId::Arxiv
236            )
237        }
238        QueryIntent::Verification => {
239            !matches!(backend, BackendId::StackOverflow | BackendId::Github)
240        }
241        QueryIntent::HowTo => !matches!(backend, BackendId::Arxiv | BackendId::GoogleScholar),
242        QueryIntent::Comparison => !matches!(
243            backend,
244            BackendId::Arxiv | BackendId::GoogleScholar | BackendId::Reddit | BackendId::HackerNews
245        ),
246        QueryIntent::Academic | QueryIntent::Data => !matches!(backend, BackendId::Reddit),
247        QueryIntent::Opinion => !matches!(backend, BackendId::Arxiv),
248        QueryIntent::Casual => {
249            // Casual queries should never hit specialist backends
250            !matches!(
251                backend,
252                BackendId::StackOverflow
253                    | BackendId::Github
254                    | BackendId::Arxiv
255                    | BackendId::GoogleScholar
256            )
257        }
258        _ => true,
259    }
260}
261
262/// Adaptive Backend Selector using UCB1 multi-armed bandit.
263#[derive(Clone)]
264pub struct AdaptiveBackendSelector {
265    stats: Arc<DashMap<String, BackendStats>>,
266    total_rounds: Arc<AtomicU64>,
267    config: AbsConfig,
268}
269
270/// Selection result with metadata.
271#[derive(Debug, Clone)]
272pub struct BackendSelection {
273    /// The selected backends, ordered by expected value.
274    pub backends: Vec<BackendId>,
275    /// UCB1 scores for each selected backend (parallel with `backends`).
276    pub scores: Vec<f64>,
277}
278
279impl AdaptiveBackendSelector {
280    /// Create a new selector.
281    pub fn new(config: AbsConfig) -> Self {
282        Self {
283            stats: Arc::new(DashMap::new()),
284            total_rounds: Arc::new(AtomicU64::new(0)),
285            config,
286        }
287    }
288
289    /// Select backends for a query based on intent and historical performance.
290    pub fn select(
291        &self,
292        intent: &QueryIntent,
293        available_backends: &[BackendId],
294        unhealthy_backends: &[BackendId],
295    ) -> BackendSelection {
296        let total = self.total_rounds.fetch_add(1, Ordering::Relaxed) + 1;
297
298        // Filter out unhealthy backends
299        let healthy: Vec<&BackendId> = available_backends
300            .iter()
301            .filter(|b| !unhealthy_backends.contains(b))
302            .filter(|b| intent_backend_allowed(intent, b))
303            .collect();
304
305        if healthy.is_empty() {
306            return BackendSelection {
307                backends: vec![],
308                scores: vec![],
309            };
310        }
311
312        // Score each backend with UCB1 + intent affinity
313        let mut scored: Vec<(BackendId, f64)> = healthy
314            .iter()
315            .map(|&backend| {
316                let key = backend.to_string();
317                let ucb1 = self.ucb1_score(&key, total);
318                let affinity = intent_affinity(intent, backend);
319                let combined = ucb1 * 0.4 + affinity * 0.6; // 60% intent, 40% history
320                (backend.clone(), combined)
321            })
322            .collect();
323
324        // Sort by combined score (descending)
325        scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
326
327        // Select top N backends (bounded by config)
328        let n = scored
329            .len()
330            .min(self.config.max_backends)
331            .max(self.config.min_backends.min(scored.len()));
332
333        let mut backends: Vec<BackendId> = scored[..n].iter().map(|(b, _)| b.clone()).collect();
334        let mut scores: Vec<f64> = scored[..n].iter().map(|(_, s)| *s).collect();
335
336        // Ensure at least one reliable backend is included — intent-aware selection.
337        // CurrentEvents → DuckDuckGo/HackerNews (not Wikipedia which returns static articles)
338        // Code → StackOverflow/DuckDuckGo
339        // Academic → Arxiv/Wikipedia
340        // Default → Wikipedia/DuckDuckGo
341        if self.config.always_include_reliable {
342            let reliable: &[BackendId] = match intent {
343                QueryIntent::CurrentEvents => &[BackendId::DuckDuckGo, BackendId::HackerNews],
344                QueryIntent::Code => &[BackendId::StackOverflow, BackendId::DuckDuckGo],
345                QueryIntent::HowTo => &[BackendId::StackOverflow, BackendId::DuckDuckGo],
346                QueryIntent::Academic | QueryIntent::Data => {
347                    &[BackendId::Arxiv, BackendId::Wikipedia]
348                }
349                _ => &[BackendId::Wikipedia, BackendId::DuckDuckGo],
350            };
351            let has_reliable = backends.iter().any(|b| reliable.contains(b));
352            if !has_reliable {
353                if let Some(reliable_b) = reliable
354                    .iter()
355                    .find(|b| healthy.contains(b) && !backends.contains(b))
356                {
357                    if backends.len() >= self.config.max_backends {
358                        backends.pop();
359                        scores.pop();
360                    }
361                    backends.push(reliable_b.clone());
362                    scores.push(0.5);
363                }
364            }
365        }
366
367        BackendSelection { backends, scores }
368    }
369
370    /// Report the outcome of using a backend.
371    pub fn report_outcome(&self, backend: &BackendId, result_count: usize, quality: f64) {
372        let key = backend.to_string();
373        let entry = self.stats.entry(key).or_insert_with(BackendStats::new);
374        entry.selections.fetch_add(1, Ordering::Relaxed);
375        if result_count > 0 {
376            entry.successes.fetch_add(1, Ordering::Relaxed);
377        }
378        let reward_int = (quality.clamp(0.0, 1.0) * 1000.0) as u64;
379        entry.total_reward.fetch_add(reward_int, Ordering::Relaxed);
380    }
381
382    /// Get performance summary for all backends.
383    pub fn summary(&self) -> Vec<(String, f64, u64)> {
384        self.stats
385            .iter()
386            .map(|entry| {
387                let key = entry.key().clone();
388                let rate = entry.value().success_rate();
389                let count = entry.value().selections.load(Ordering::Relaxed);
390                (key, rate, count)
391            })
392            .collect()
393    }
394
395    /// UCB1 score for a backend.
396    ///
397    /// UCB1 = avg_reward + C * sqrt(ln(total_rounds) / selections)
398    fn ucb1_score(&self, key: &str, total_rounds: u64) -> f64 {
399        match self.stats.get(key) {
400            Some(stats) => {
401                let selections = stats.selections.load(Ordering::Relaxed);
402                if selections == 0 {
403                    return 1.0; // moderate exploration bonus for unseen
404                }
405                let avg = stats.avg_reward();
406                let exploration = self.config.exploration_factor
407                    * ((total_rounds as f64).ln() / selections as f64).sqrt();
408                (avg + exploration).min(1.0)
409            }
410            None => 1.0, // unseen backend — moderate exploration bonus
411        }
412    }
413}
414
415impl Default for AdaptiveBackendSelector {
416    fn default() -> Self {
417        Self::new(AbsConfig::default())
418    }
419}
420
421#[cfg(test)]
422mod tests {
423    use super::*;
424
425    fn all_backends() -> Vec<BackendId> {
426        vec![
427            BackendId::DuckDuckGo,
428            BackendId::Google,
429            BackendId::Bing,
430            BackendId::Wikipedia,
431            BackendId::HackerNews,
432            BackendId::Arxiv,
433            BackendId::Github,
434            BackendId::Reddit,
435            BackendId::StackOverflow,
436            BackendId::Brave,
437        ]
438    }
439
440    #[test]
441    fn academic_query_prefers_arxiv() {
442        let abs = AdaptiveBackendSelector::default();
443        let selection = abs.select(&QueryIntent::Academic, &all_backends(), &[]);
444
445        // arXiv should be in the top 3 for academic queries
446        let top3: Vec<_> = selection.backends.iter().take(3).collect();
447        assert!(
448            top3.contains(&&BackendId::Arxiv),
449            "Academic query should include arXiv in top 3, got: {:?}",
450            top3
451        );
452    }
453
454    #[test]
455    fn code_query_prefers_github() {
456        let abs = AdaptiveBackendSelector::default();
457        let selection = abs.select(&QueryIntent::Code, &all_backends(), &[]);
458
459        let top3: Vec<_> = selection.backends.iter().take(3).collect();
460        assert!(
461            top3.contains(&&BackendId::Github),
462            "Code query should include GitHub in top 3, got: {:?}",
463            top3
464        );
465    }
466
467    #[test]
468    fn unhealthy_backends_excluded() {
469        let abs = AdaptiveBackendSelector::default();
470        let unhealthy = vec![BackendId::Google, BackendId::Bing];
471        let selection = abs.select(&QueryIntent::Factual, &all_backends(), &unhealthy);
472
473        assert!(!selection.backends.contains(&BackendId::Google));
474        assert!(!selection.backends.contains(&BackendId::Bing));
475    }
476
477    #[test]
478    fn respects_max_backends() {
479        let config = AbsConfig {
480            max_backends: 3,
481            min_backends: 1,
482            ..AbsConfig::default()
483        };
484        let abs = AdaptiveBackendSelector::new(config);
485        let selection = abs.select(&QueryIntent::Factual, &all_backends(), &[]);
486
487        assert!(selection.backends.len() <= 3);
488    }
489
490    #[test]
491    fn learning_improves_selection() {
492        let abs = AdaptiveBackendSelector::default();
493
494        // Report that Wikipedia consistently gives great results
495        for _ in 0..20 {
496            abs.report_outcome(&BackendId::Wikipedia, 10, 0.95);
497        }
498        // Report that Bing consistently fails
499        for _ in 0..20 {
500            abs.report_outcome(&BackendId::Bing, 0, 0.0);
501        }
502
503        let selection = abs.select(&QueryIntent::Factual, &all_backends(), &[]);
504        let wiki_pos = selection
505            .backends
506            .iter()
507            .position(|b| *b == BackendId::Wikipedia);
508        let bing_pos = selection
509            .backends
510            .iter()
511            .position(|b| *b == BackendId::Bing);
512
513        // Wikipedia should rank higher than Bing after learning
514        match (wiki_pos, bing_pos) {
515            (Some(w), Some(b)) => assert!(w < b, "Wikipedia should rank above Bing after learning"),
516            (Some(_), None) => {} // Bing might be excluded entirely — that's fine
517            _ => panic!("Wikipedia should be selected"),
518        }
519    }
520
521    #[test]
522    fn reliable_backend_always_included() {
523        let config = AbsConfig {
524            always_include_reliable: true,
525            max_backends: 3,
526            min_backends: 1,
527            ..AbsConfig::default()
528        };
529        let abs = AdaptiveBackendSelector::new(config);
530
531        // Factual intent: reliable fallback is Wikipedia/DuckDuckGo
532        let backends = vec![
533            BackendId::Arxiv,
534            BackendId::Github,
535            BackendId::HackerNews,
536            BackendId::Wikipedia, // reliable for Factual
537        ];
538
539        let selection = abs.select(&QueryIntent::Factual, &backends, &[]);
540        assert!(
541            selection.backends.contains(&BackendId::Wikipedia)
542                || selection.backends.contains(&BackendId::DuckDuckGo),
543            "Should include at least one reliable backend for Factual"
544        );
545
546        // Code intent: reliable fallback is StackOverflow/DuckDuckGo
547        let code_backends = vec![
548            BackendId::Arxiv,
549            BackendId::Github,
550            BackendId::HackerNews,
551            BackendId::StackOverflow, // reliable for Code
552        ];
553
554        let selection = abs.select(&QueryIntent::Code, &code_backends, &[]);
555        assert!(
556            selection.backends.contains(&BackendId::StackOverflow)
557                || selection.backends.contains(&BackendId::DuckDuckGo),
558            "Should include at least one reliable backend for Code"
559        );
560    }
561
562    #[test]
563    fn empty_available_returns_empty() {
564        let abs = AdaptiveBackendSelector::default();
565        let selection = abs.select(&QueryIntent::Factual, &[], &[]);
566        assert!(selection.backends.is_empty());
567    }
568
569    #[test]
570    fn factual_excludes_code_backends() {
571        let abs = AdaptiveBackendSelector::default();
572        let backends = vec![
573            BackendId::StackOverflow,
574            BackendId::Github,
575            BackendId::Wikipedia,
576            BackendId::DuckDuckGo,
577            BackendId::Searxng,
578        ];
579        let selection = abs.select(&QueryIntent::Factual, &backends, &[]);
580        assert!(!selection.backends.contains(&BackendId::StackOverflow));
581        assert!(!selection.backends.contains(&BackendId::Github));
582    }
583
584    #[test]
585    fn current_events_excludes_static_dev_sources() {
586        let abs = AdaptiveBackendSelector::default();
587        let backends = vec![
588            BackendId::StackOverflow,
589            BackendId::Github,
590            BackendId::Arxiv,
591            BackendId::HackerNews,
592            BackendId::Searxng,
593            BackendId::DuckDuckGo,
594        ];
595        let selection = abs.select(&QueryIntent::CurrentEvents, &backends, &[]);
596        assert!(!selection.backends.contains(&BackendId::StackOverflow));
597        assert!(!selection.backends.contains(&BackendId::Github));
598        assert!(!selection.backends.contains(&BackendId::Arxiv));
599    }
600}