Skip to main content

fetchium_core/rank/
fusion.rs

1//! HyperFusion 8-signal score normalization and fusion (PRD §8.1).
2//!
3//! Pipeline:
4//! 1. Compute raw scores for all 8 signals per result
5//! 2. Min-max normalize each signal across the result set to [0, 1]
6//! 3. Apply intent-weighted linear combination
7//! 4. Sort results by fusion score descending
8
9use crate::rank::signals::{
10    authority_score, bm25_score, consensus_score, depth_score, diversity_score, evidence_score,
11    semantic_score, temporal_score, ScoringContext,
12};
13use crate::types::ResultItem;
14use std::collections::HashMap;
15
16/// Query intent category for weight selection.
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
18pub enum QueryIntent {
19    #[default]
20    Factual,
21    /// Definitional / explanatory queries ("what is X", "explain Y", "how does Z work").
22    ///
23    /// Prioritizes BM25 text relevance and Wikipedia/educational sources over
24    /// GitHub repositories, which are almost never useful for definitions.
25    Informational,
26    HowTo,
27    Comparison,
28    Verification,
29    CurrentEvents,
30    DeepAnalysis,
31    Code,
32    Academic,
33    Opinion,
34    Data,
35    /// Everyday casual queries: "best pizza near me", "coffee stains shirt",
36    /// "cheap flights to paris", "signs of burnout". These should skip all
37    /// specialist backends (ArXiv, Scholar, GitHub, StackOverflow) and rely
38    /// on general web search + Reddit for real-world answers.
39    Casual,
40}
41
42/// Weights for the 8 HyperFusion signals, tuned per query intent.
43#[derive(Debug, Clone)]
44pub struct IntentWeights {
45    pub bm25: f64,
46    pub semantic: f64,
47    pub temporal: f64,
48    pub authority: f64,
49    pub evidence: f64,
50    pub diversity: f64,
51    pub depth: f64,
52    pub consensus: f64,
53}
54
55impl IntentWeights {
56    /// Return default weights for a given intent.
57    pub fn for_intent(intent: QueryIntent) -> Self {
58        match intent {
59            QueryIntent::Factual => Self {
60                bm25: 0.30,
61                semantic: 0.15,
62                temporal: 0.05,
63                authority: 0.10,
64                evidence: 0.15,
65                diversity: 0.05,
66                depth: 0.05,
67                consensus: 0.15,
68            },
69            QueryIntent::Informational => Self {
70                bm25: 0.40,
71                semantic: 0.20,
72                temporal: 0.05,
73                authority: 0.03,
74                evidence: 0.10,
75                diversity: 0.07,
76                depth: 0.10,
77                consensus: 0.05,
78            },
79            QueryIntent::CurrentEvents => Self {
80                bm25: 0.15,
81                semantic: 0.10,
82                temporal: 0.30,
83                authority: 0.10,
84                evidence: 0.10,
85                diversity: 0.05,
86                depth: 0.05,
87                consensus: 0.15,
88            },
89            QueryIntent::Academic => Self {
90                bm25: 0.15,
91                semantic: 0.20,
92                temporal: 0.05,
93                authority: 0.25,
94                evidence: 0.15,
95                diversity: 0.05,
96                depth: 0.10,
97                consensus: 0.05,
98            },
99            QueryIntent::DeepAnalysis => Self {
100                bm25: 0.10,
101                semantic: 0.15,
102                temporal: 0.05,
103                authority: 0.10,
104                evidence: 0.10,
105                diversity: 0.10,
106                depth: 0.30,
107                consensus: 0.10,
108            },
109            QueryIntent::Code => Self {
110                bm25: 0.35,
111                semantic: 0.15,
112                temporal: 0.05,
113                authority: 0.05,
114                evidence: 0.05,
115                diversity: 0.10,
116                depth: 0.15,
117                consensus: 0.10,
118            },
119            QueryIntent::HowTo => Self {
120                bm25: 0.35,
121                semantic: 0.15,
122                temporal: 0.05,
123                authority: 0.05,
124                evidence: 0.10,
125                diversity: 0.10,
126                depth: 0.15,
127                consensus: 0.05,
128            },
129            QueryIntent::Comparison => Self {
130                bm25: 0.15,
131                semantic: 0.20,
132                temporal: 0.05,
133                authority: 0.15,
134                evidence: 0.15,
135                diversity: 0.15,
136                depth: 0.10,
137                consensus: 0.05,
138            },
139            QueryIntent::Opinion => Self {
140                bm25: 0.20,
141                semantic: 0.10,
142                temporal: 0.05,
143                authority: 0.10,
144                evidence: 0.10,
145                diversity: 0.15,
146                depth: 0.10,
147                consensus: 0.20,
148            },
149            QueryIntent::Casual => Self {
150                bm25: 0.35,
151                semantic: 0.15,
152                temporal: 0.05,
153                authority: 0.05,
154                evidence: 0.05,
155                diversity: 0.15,
156                depth: 0.05,
157                consensus: 0.15,
158            },
159            // Balanced fallback for Verification, Data, and any new variants
160            _ => Self {
161                bm25: 0.15,
162                semantic: 0.15,
163                temporal: 0.10,
164                authority: 0.15,
165                evidence: 0.10,
166                diversity: 0.10,
167                depth: 0.10,
168                consensus: 0.15,
169            },
170        }
171    }
172
173    /// Apply per-signal weight overrides from config.
174    pub fn with_overrides(mut self, overrides: &HashMap<String, f64>) -> Self {
175        for (signal, &val) in overrides {
176            let val = val.clamp(0.0, 1.0);
177            match signal.as_str() {
178                "bm25" => self.bm25 = val,
179                "semantic" => self.semantic = val,
180                "temporal" => self.temporal = val,
181                "authority" => self.authority = val,
182                "evidence" => self.evidence = val,
183                "diversity" => self.diversity = val,
184                "depth" => self.depth = val,
185                "consensus" => self.consensus = val,
186                _ => {}
187            }
188        }
189        self
190    }
191
192    /// Sum of all weights (should be ~1.0 for calibrated weights).
193    pub fn sum(&self) -> f64 {
194        self.bm25
195            + self.semantic
196            + self.temporal
197            + self.authority
198            + self.evidence
199            + self.diversity
200            + self.depth
201            + self.consensus
202    }
203
204    /// Normalize weights so they sum to 1.0.
205    pub fn normalize(mut self) -> Self {
206        let s = self.sum();
207        if s > 0.0 {
208            self.bm25 /= s;
209            self.semantic /= s;
210            self.temporal /= s;
211            self.authority /= s;
212            self.evidence /= s;
213            self.diversity /= s;
214            self.depth /= s;
215            self.consensus /= s;
216        }
217        self
218    }
219}
220
221/// Raw 8-signal scores for a single result (before normalization).
222#[derive(Debug, Clone, Default)]
223struct RawScores {
224    bm25: f64,
225    semantic: f64,
226    temporal: f64,
227    authority: f64,
228    evidence: f64,
229    diversity: f64,
230    depth: f64,
231    consensus: f64,
232}
233
234/// Adjust raw authority score based on query intent to fix over-ranking biases.
235///
236/// GitHub.com has domain authority 0.90 (same tier as Wikipedia), which is correct
237/// for code queries but causes irrelevant repositories to rank above educational pages
238/// for informational/factual queries.
239///
240/// Wikipedia has high authority which is correct for factual/informational queries
241/// but causes generic articles to dominate temporal/current-events queries where
242/// news sources should rank higher.
243fn adjust_authority_for_intent(url: &str, base: f64, intent: QueryIntent) -> f64 {
244    // GitHub bias: repos only relevant for code queries
245    if url.contains("github.com/") {
246        return match intent {
247            QueryIntent::Code => base,               // repos are the right result
248            QueryIntent::Academic => base * 0.6,     // some papers reference repos
249            QueryIntent::DeepAnalysis => base * 0.7, // deep dives sometimes cite repos
250            QueryIntent::Casual => base * 0.2,       // repos never useful for casual queries
251            _ => base * 0.45,                        // informational/factual: heavily downweight
252        };
253    }
254
255    // Wikipedia bias: great for definitions, poor for "breakthroughs 2025" type queries
256    if url.contains("wikipedia.org") {
257        // Extra penalty for "List of..." and biography pages that are usually off-topic
258        let path_lower = url.to_lowercase();
259        let is_list_or_bio = path_lower.contains("list_of_")
260            || path_lower.contains("(academic)")
261            || path_lower.contains("(politician)")
262            || path_lower.contains("(footballer)")
263            || path_lower.contains("(singer)")
264            || path_lower.contains("(actor)");
265        let list_penalty = if is_list_or_bio { 0.5 } else { 1.0 };
266
267        return match intent {
268            QueryIntent::CurrentEvents => base * 0.35 * list_penalty,
269            QueryIntent::Casual => base * 0.50 * list_penalty, // Wikipedia generic articles drown casual results
270            QueryIntent::Factual | QueryIntent::Informational | QueryIntent::Verification => {
271                base * list_penalty
272            }
273            _ => base * 0.75 * list_penalty,
274        };
275    }
276
277    // Reddit/forum bias: great for opinions, but comparison/technical queries need
278    // structured articles over discussion threads.
279    if url.contains("reddit.com") || url.contains("news.ycombinator.com") {
280        return match intent {
281            QueryIntent::Opinion => base, // discussions add perspective for opinion queries
282            QueryIntent::Casual => base * 0.55, // prefer authoritative consumer sites over Reddit threads
283            QueryIntent::Comparison => base * 0.85, // community discussions valuable for comparisons
284            QueryIntent::Code | QueryIntent::HowTo => base * 0.60, // prefer docs/tutorials
285            QueryIntent::Academic => base * 0.40,   // not a good source
286            _ => base * 0.70,
287        };
288    }
289
290    // YouTube/video results: deprioritize for comparison/technical where text is better
291    if url.contains("youtube.com") || url.contains("youtu.be") {
292        return match intent {
293            QueryIntent::HowTo => base * 0.80, // tutorials on YouTube can be good
294            QueryIntent::Opinion => base * 0.85,
295            QueryIntent::Comparison => base * 0.50, // articles much better than videos
296            QueryIntent::Code => base * 0.45,       // text tutorials > video
297            QueryIntent::Academic => base * 0.35,
298            QueryIntent::Casual => base * 0.90,
299            _ => base * 0.65,
300        };
301    }
302
303    // ArXiv bias: excellent for academic/verification, often off-topic for
304    // opinion/comparison "best X" queries where community benchmarks matter more.
305    if url.contains("arxiv.org/") {
306        return match intent {
307            QueryIntent::Academic | QueryIntent::Verification | QueryIntent::Data => base,
308            QueryIntent::Opinion | QueryIntent::Comparison => base * 0.45,
309            QueryIntent::Casual => base * 0.15, // ArXiv never relevant for casual queries
310            _ => base * 0.75,
311        };
312    }
313
314    base
315}
316
317/// Apply HyperFusion ranking to a mutable slice of results.
318///
319/// Mutates `results` in-place: populates `score` field and re-sorts by fusion score.
320///
321/// # Arguments
322/// * `results` - The result set to rank
323/// * `query` - The user's query string
324/// * `intent` - Detected query intent for weight selection
325/// * `freshness_need` - How much recency matters (0=none, 1=high)
326/// * `weight_overrides` - Optional per-signal overrides from config
327pub fn hyperfusion_rank(
328    results: &mut [ResultItem],
329    query: &str,
330    intent: QueryIntent,
331    freshness_need: f64,
332    weight_overrides: &HashMap<String, f64>,
333) {
334    if results.is_empty() {
335        return;
336    }
337
338    let weights = IntentWeights::for_intent(intent)
339        .with_overrides(weight_overrides)
340        .normalize();
341
342    // Build scoring context (immutable view of all results)
343    let mut ctx = ScoringContext::new(query, results);
344
345    // Phase 1: compute raw scores
346    let mut raw: Vec<RawScores> = results
347        .iter()
348        .map(|r| {
349            let base_authority = authority_score(r);
350            RawScores {
351                bm25: bm25_score(r, &ctx),
352                semantic: semantic_score(r, &ctx),
353                temporal: temporal_score(r, freshness_need),
354                // Apply intent-based adjustment: downweight GitHub repos for non-code queries
355                authority: adjust_authority_for_intent(&r.url, base_authority, intent),
356                evidence: evidence_score(r),
357                // diversity and consensus are computed below with mutable ctx
358                diversity: 0.0,
359                depth: depth_score(r),
360                consensus: consensus_score(r, &ctx),
361            }
362        })
363        .collect();
364
365    // Diversity requires sequential access (tracks seen domains)
366    for (i, result) in results.iter().enumerate() {
367        raw[i].diversity = diversity_score(result, &mut ctx);
368    }
369
370    // Phase 2: min-max normalize each signal across result set
371    let normalized = min_max_normalize(raw);
372
373    // Phase 3: weighted fusion
374    let fusion_scores: Vec<f64> = normalized
375        .iter()
376        .map(|s| {
377            s.bm25 * weights.bm25
378                + s.semantic * weights.semantic
379                + s.temporal * weights.temporal
380                + s.authority * weights.authority
381                + s.evidence * weights.evidence
382                + s.diversity * weights.diversity
383                + s.depth * weights.depth
384                + s.consensus * weights.consensus
385        })
386        .collect();
387
388    // Apply power-law spread to widen the score distribution.
389    // Raw fusion scores cluster in [0.3, 0.7] due to min-max normalization.
390    // Spread them across [0.0, 1.0] for more discriminating ranking.
391    let fmin = fusion_scores.iter().cloned().fold(f64::INFINITY, f64::min);
392    let fmax = fusion_scores
393        .iter()
394        .cloned()
395        .fold(f64::NEG_INFINITY, f64::max);
396    let frange = fmax - fmin;
397    let spread_scores: Vec<f64> = if frange > 1e-9 {
398        fusion_scores
399            .iter()
400            .map(|&s| {
401                let normalized = (s - fmin) / frange; // [0, 1]
402                                                      // Apply power curve: pow(x, 0.6) spreads the top end
403                normalized.powf(0.6)
404            })
405            .collect()
406    } else {
407        fusion_scores.iter().map(|_| 0.5).collect()
408    };
409
410    // Apply spread fusion scores to result items
411    for (i, result) in results.iter_mut().enumerate() {
412        result.score = Some(spread_scores[i]);
413    }
414
415    // Phase 4: sort by fusion score descending, rank ties broken by original rank
416    results.sort_by(|a, b| {
417        let sa = a.score.unwrap_or(0.0);
418        let sb = b.score.unwrap_or(0.0);
419        sb.partial_cmp(&sa)
420            .unwrap_or(std::cmp::Ordering::Equal)
421            .then_with(|| a.rank.cmp(&b.rank))
422    });
423
424    // Re-assign ranks
425    for (i, r) in results.iter_mut().enumerate() {
426        r.rank = (i + 1) as u32;
427    }
428}
429
430/// Min-max normalize each signal across all results.
431///
432/// If all values are equal (range ≈ 0), returns 0.5 for all.
433fn min_max_normalize(scores: Vec<RawScores>) -> Vec<RawScores> {
434    const EPSILON: f64 = 1e-9;
435
436    macro_rules! normalize_field {
437        ($scores:expr, $field:ident) => {{
438            let min = $scores
439                .iter()
440                .map(|s| s.$field)
441                .fold(f64::INFINITY, f64::min);
442            let max = $scores
443                .iter()
444                .map(|s| s.$field)
445                .fold(f64::NEG_INFINITY, f64::max);
446            let range = max - min;
447            if range < EPSILON {
448                for s in $scores.iter_mut() {
449                    s.$field = 0.5;
450                }
451            } else {
452                for s in $scores.iter_mut() {
453                    s.$field = (s.$field - min) / range;
454                }
455            }
456        }};
457    }
458
459    let mut scores = scores;
460    normalize_field!(scores, bm25);
461    normalize_field!(scores, semantic);
462    normalize_field!(scores, temporal);
463    normalize_field!(scores, authority);
464    normalize_field!(scores, evidence);
465    normalize_field!(scores, diversity);
466    normalize_field!(scores, depth);
467    normalize_field!(scores, consensus);
468    scores
469}
470
471/// Simple heuristic to detect query intent from the query string.
472///
473/// Used when the caller doesn't specify intent explicitly.
474pub fn detect_intent(query: &str) -> QueryIntent {
475    let q = query.to_lowercase();
476    let is_language_learning = (q.contains("learn")
477        || q.contains("learning")
478        || q.contains("apprendre")
479        || q.contains("aprender")
480        || q.contains("lernen")
481        || q.contains("study"))
482        && (q.contains("french")
483            || q.contains("français")
484            || q.contains("francais")
485            || q.contains("spanish")
486            || q.contains("español")
487            || q.contains("espanol")
488            || q.contains("german")
489            || q.contains("deutsch")
490            || q.contains("italian")
491            || q.contains("italiano"));
492    let has_health_signal = q.contains("diabetes")
493        || q.contains("hypertension")
494        || q.contains("blood pressure")
495        || q.contains("medication")
496        || q.contains("treatment")
497        || q.contains("therapy")
498        || q.contains("disease")
499        || q.contains("symptom")
500        || q.contains("diagnosis")
501        || q.contains("vaccine")
502        || q.contains("insulin")
503        || q.contains("sleep apnea");
504    let has_guideline_signal = q.contains("guideline")
505        || q.contains("guidelines")
506        || q.contains("recommendation")
507        || q.contains("recommendations")
508        || q.contains("standards of care")
509        || q.contains("clinical practice");
510    let has_recent_year = q.contains("2025") || q.contains("2026");
511    let has_news_signal = q.contains("today")
512        || q.contains("latest")
513        || q.contains("news")
514        || q.contains("recent")
515        || q.contains("this year")
516        || q.contains("this month")
517        || q.contains("this week")
518        || q.contains("breaking")
519        || q.contains("update")
520        || q.contains("announcement")
521        || q.contains("released")
522        || q.contains("launched")
523        || q.contains("new in ");
524    let is_technical_eval = q.contains("benchmark")
525        || q.contains("performance")
526        || q.contains("vs ")
527        || q.contains(" vs")
528        || q.contains("compare")
529        || q.contains("runtime")
530        || q.contains("framework")
531        || q.contains("latency")
532        || q.contains("throughput");
533    let is_preference_query = q.contains("best ")
534        || q.starts_with("best ")
535        || q.contains("top ")
536        || q.contains("recommended")
537        || q.contains("which is better")
538        || q.contains("should i use")
539        || q.contains("worth it")
540        || q.contains("pros and cons");
541    let has_technical_signal = q.contains("protocol")
542        || q.contains("architecture")
543        || q.contains("docker")
544        || q.contains("compose")
545        || q.contains("container")
546        || q.contains("containers")
547        || q.contains("kubernetes")
548        || q.contains("networking")
549        || q.contains("hostname")
550        || q.contains("dns")
551        || q.contains("service name")
552        || q.contains("http")
553        || q.contains("api")
554        || q.contains("theorem")
555        || q.contains("equation")
556        || q.contains("compiler")
557        || q.contains("kernel")
558        || q.contains("database")
559        || q.contains("encryption")
560        || q.contains("neural")
561        || q.contains("quantum")
562        || q.contains("molecular")
563        || q.contains("genome")
564        || q.contains("proof")
565        || q.contains("axiom")
566        || q.contains("cryptograph");
567    let has_debug_signal = q.contains("error")
568        || q.contains("fix")
569        || q.contains("troubleshooting")
570        || q.contains("troubleshoot")
571        || q.contains("out of memory")
572        || q.contains("heap")
573        || q.contains("segmentation fault")
574        || q.contains("exception")
575        || q.contains("cors")
576        || q.contains("access-control-allow-origin")
577        || q.contains("ssl certificate")
578        || q.contains("oom killed");
579
580    // Code intent: explicit code/repo signals
581    // Note: "tutorial" and "example" with programming languages → HowTo (not Code)
582    // because users want articles/docs, not GitHub repos
583    let is_programming_lang = q.contains("python")
584        || q.contains("rust")
585        || q.contains("javascript")
586        || q.contains("typescript")
587        || q.contains("node.js")
588        || q.contains("nodejs")
589        || q.contains("java ")
590        || q.contains("golang")
591        || q.contains("go ")
592        || q.contains("ruby")
593        || q.contains("swift")
594        || q.contains("kotlin")
595        || q.contains("c++")
596        || q.contains("c#");
597    let has_tutorial_signal = q.contains("tutorial")
598        || q.contains("guide")
599        || q.contains("how to")
600        || q.contains("example");
601    if q.contains("code")
602        || q.contains("github")
603        || q.contains("function")
604        || q.contains("crate")
605        || q.contains("snippet")
606        || q.contains("implement")
607        || q.contains("algorithm")
608        || (is_programming_lang
609            && !has_tutorial_signal
610            && (q.contains("library") || q.contains("package") || q.contains("crate")))
611    {
612        return QueryIntent::Code;
613    }
614
615    if is_language_learning {
616        return QueryIntent::HowTo;
617    }
618
619    if has_debug_signal {
620        if is_programming_lang
621            || q.contains("node.js")
622            || q.contains("nodejs")
623            || q.contains("react")
624            || q.contains("typescript")
625        {
626            return QueryIntent::Code;
627        }
628        return QueryIntent::HowTo;
629    }
630
631    // Clinical guideline queries use "latest" language but behave like
632    // authoritative reference lookups, not news searches.
633    if has_health_signal && has_guideline_signal {
634        return QueryIntent::Verification;
635    }
636
637    // CurrentEvents: temporal signals — checked early so "breakthroughs 2025" doesn't
638    // fall through to Factual. Year patterns, recency keywords, and news signals.
639    if has_news_signal
640        || (has_recent_year && !is_technical_eval && !is_preference_query)
641        || (q.contains("breakthrough") && !is_technical_eval)
642    {
643        return QueryIntent::CurrentEvents;
644    }
645
646    // HowTo: procedural instructions
647    if q.contains("how to")
648        || q.contains("tutorial")
649        || q.contains("guide")
650        || q.contains("setup")
651        || q.contains("install")
652        || q.contains("configure")
653        || ((q.contains("docker")
654            || q.contains("compose")
655            || q.contains("container")
656            || q.contains("kubernetes")
657            || q.contains("networking")
658            || q.contains("hostname")
659            || q.contains("dns"))
660            && !q.contains(" vs ")
661            && !q.contains("compare")
662            && !q.contains("comparison"))
663    {
664        return QueryIntent::HowTo;
665    }
666
667    // Informational: definitional / explanatory — detected BEFORE generic Factual fallback
668    if q.starts_with("what is")
669        || q.starts_with("what are")
670        || q.starts_with("what does")
671        || q.starts_with("who is")
672        || q.starts_with("who was")
673        || q.starts_with("where is")
674        || q.starts_with("when was")
675        || q.starts_with("when did")
676        || q.contains("how does")
677        || q.contains("how do ")
678        || q.contains("define ")
679        || q.contains("definition of")
680        || q.contains("definition:")
681        || q.contains("explain ")
682        || q.contains("meaning of")
683        || q.contains(" is a ")
684        || q.contains(" is an ")
685    {
686        return QueryIntent::Informational;
687    }
688
689    // Casual consumer queries: "best pizza in new york", "cheap flights to paris",
690    // "best coffee shop near me". These look like Opinion ("best X") but are everyday
691    // consumer searches that should prefer review sites, travel sites, etc. over Reddit.
692    let is_consumer_query = q.contains("pizza")
693        || q.contains("restaurant")
694        || q.contains("hotel")
695        || q.contains("flight")
696        || q.contains("coffee")
697        || q.contains("recipe")
698        || q.contains("movie")
699        || q.contains("near me")
700        || q.contains("in new ")
701        || q.contains("in los ")
702        || q.contains("in san ")
703        || q.contains("in chicago")
704        || q.contains("in london")
705        || q.contains("in paris")
706        || q.contains("in tokyo")
707        || q.contains("shop")
708        || q.contains("store")
709        || q.contains("gym")
710        || q.contains("barber")
711        || q.contains("salon")
712        || q.contains("dentist")
713        || q.contains("plumber");
714    if is_preference_query && is_consumer_query && !is_programming_lang && !has_technical_signal {
715        return QueryIntent::Casual;
716    }
717
718    // Opinion: "best X", "top X", "recommended", "should I use"
719    if is_preference_query {
720        return QueryIntent::Opinion;
721    }
722
723    if q.contains("vs ")
724        || q.contains(" vs")
725        || q.contains("compare")
726        || q.contains("comparison")
727        || q.contains("difference")
728    {
729        return QueryIntent::Comparison;
730    }
731    if q.contains("arxiv") || q.contains("paper") || q.contains("research") || q.contains("study") {
732        return QueryIntent::Academic;
733    }
734    // DeepAnalysis: explicit analytical intent (but NOT "deep dive" which is just emphasis)
735    if q.contains("analysis") || q.contains("comprehensive") {
736        return QueryIntent::DeepAnalysis;
737    }
738    // "deep dive" is a common phrase meaning "thorough article", not DeepAnalysis.
739    // Route to HowTo for "X deep dive" patterns, which performs better than DeepAnalysis
740    // for technical explainers like "kubernetes pod networking deep dive".
741    if q.contains("deep dive") || q.contains("deep-dive") {
742        return QueryIntent::HowTo;
743    }
744    if q.contains("deep") && !q.contains("deep learning") {
745        return QueryIntent::DeepAnalysis;
746    }
747
748    // Casual: everyday queries that don't match any specialist intent.
749    // Short queries (≤6 words) without technical/academic signals are likely casual.
750    // Examples: "best pizza near me", "coffee stains shirt", "signs of burnout"
751    let word_count = q.split_whitespace().count();
752    if word_count <= 6 && !has_technical_signal {
753        return QueryIntent::Casual;
754    }
755
756    QueryIntent::Factual
757}
758
759#[cfg(test)]
760mod tests {
761    use super::*;
762    use crate::types::BackendId;
763
764    fn make_result(title: &str, url: &str, snippet: &str) -> ResultItem {
765        ResultItem {
766            title: title.into(),
767            url: url.into(),
768            snippet: snippet.into(),
769            rank: 1,
770            backend: BackendId::DuckDuckGo,
771            score: None,
772            published_date: None,
773        }
774    }
775
776    #[test]
777    fn weights_sum_to_one_after_normalize() {
778        for intent in [
779            QueryIntent::Factual,
780            QueryIntent::Informational,
781            QueryIntent::CurrentEvents,
782            QueryIntent::Academic,
783            QueryIntent::Code,
784            QueryIntent::DeepAnalysis,
785        ] {
786            let w = IntentWeights::for_intent(intent).normalize();
787            let sum = w.sum();
788            assert!((sum - 1.0).abs() < 1e-6, "intent={intent:?} sum={sum}");
789        }
790    }
791
792    #[test]
793    fn hyperfusion_ranks_relevant_higher() {
794        let mut results = vec![
795            make_result("Random Blog", "https://random-blog.xyz/post", "Some unrelated content about gardening"),
796            make_result("Rust Lang", "https://rust-lang.org", "Rust is a systems programming language focused on safety, performance, and concurrency."),
797            make_result("Python Docs", "https://python.org", "Python is a dynamic scripting language"),
798        ];
799        // Set ranks
800        for (i, r) in results.iter_mut().enumerate() {
801            r.rank = (i + 1) as u32;
802        }
803
804        hyperfusion_rank(
805            &mut results,
806            "Rust programming language",
807            QueryIntent::Factual,
808            0.5,
809            &HashMap::new(),
810        );
811
812        // Rust result should be ranked first
813        assert_eq!(
814            results[0].url, "https://rust-lang.org",
815            "Rust should rank first"
816        );
817        assert!(results[0].score.unwrap() > results[2].score.unwrap_or(0.0));
818    }
819
820    #[test]
821    fn hyperfusion_empty_input() {
822        let mut results = vec![];
823        hyperfusion_rank(
824            &mut results,
825            "test",
826            QueryIntent::Factual,
827            0.5,
828            &HashMap::new(),
829        );
830        assert!(results.is_empty());
831    }
832
833    #[test]
834    fn all_identical_scores_use_half() {
835        let scores = vec![
836            RawScores {
837                bm25: 0.5,
838                semantic: 0.5,
839                temporal: 0.5,
840                authority: 0.5,
841                evidence: 0.5,
842                diversity: 0.5,
843                depth: 0.5,
844                consensus: 0.5,
845            },
846            RawScores {
847                bm25: 0.5,
848                semantic: 0.5,
849                temporal: 0.5,
850                authority: 0.5,
851                evidence: 0.5,
852                diversity: 0.5,
853                depth: 0.5,
854                consensus: 0.5,
855            },
856        ];
857        let normalized = min_max_normalize(scores);
858        assert!((normalized[0].bm25 - 0.5).abs() < 1e-9);
859    }
860
861    #[test]
862    fn min_max_normalize_correct() {
863        let scores = vec![
864            RawScores {
865                bm25: 0.0,
866                semantic: 0.0,
867                temporal: 0.0,
868                authority: 0.0,
869                evidence: 0.0,
870                diversity: 0.0,
871                depth: 0.0,
872                consensus: 0.0,
873            },
874            RawScores {
875                bm25: 1.0,
876                semantic: 1.0,
877                temporal: 1.0,
878                authority: 1.0,
879                evidence: 1.0,
880                diversity: 1.0,
881                depth: 1.0,
882                consensus: 1.0,
883            },
884        ];
885        let normalized = min_max_normalize(scores);
886        assert!((normalized[0].bm25 - 0.0).abs() < 1e-9);
887        assert!((normalized[1].bm25 - 1.0).abs() < 1e-9);
888    }
889
890    #[test]
891    fn detect_intent_works() {
892        assert_eq!(detect_intent("how to install Rust"), QueryIntent::HowTo);
893        assert_eq!(
894            detect_intent("docker compose networking between containers"),
895            QueryIntent::HowTo
896        );
897        assert_eq!(
898            detect_intent("Rust vs Go performance"),
899            QueryIntent::Comparison
900        );
901        assert_eq!(
902            detect_intent("blood pressure medication side effects comparison"),
903            QueryIntent::Comparison
904        );
905        assert_eq!(
906            detect_intent("arxiv paper transformer attention"),
907            QueryIntent::Academic
908        );
909        assert_eq!(detect_intent("github rust async code"), QueryIntent::Code);
910        assert_eq!(
911            detect_intent("Rust latest news 2026"),
912            QueryIntent::CurrentEvents
913        );
914    }
915
916    #[test]
917    fn detect_intent_temporal_keywords() {
918        assert_eq!(
919            detect_intent("quantum computing breakthroughs 2025"),
920            QueryIntent::CurrentEvents
921        );
922        assert_eq!(
923            detect_intent("recent advances in AI"),
924            QueryIntent::CurrentEvents
925        );
926        assert_eq!(
927            detect_intent("breaking news AI regulation"),
928            QueryIntent::CurrentEvents
929        );
930        assert_eq!(
931            detect_intent("new in rust this year"),
932            QueryIntent::CurrentEvents
933        );
934        assert_eq!(
935            detect_intent("GPT-5 announcement"),
936            QueryIntent::CurrentEvents
937        );
938    }
939
940    #[test]
941    fn detect_intent_technical_year_query_not_forced_to_current_events() {
942        let intent =
943            detect_intent("best rust async runtime for high-throughput web api in 2025 benchmark");
944        assert_ne!(intent, QueryIntent::CurrentEvents);
945    }
946
947    #[test]
948    fn detect_intent_health_guidelines_prefer_verification_over_current_events() {
949        assert_eq!(
950            detect_intent("type 2 diabetes management latest guidelines"),
951            QueryIntent::Verification
952        );
953    }
954
955    #[test]
956    fn detect_intent_language_learning_prefers_howto() {
957        assert_eq!(
958            detect_intent("comment apprendre le français rapidement"),
959            QueryIntent::HowTo
960        );
961    }
962
963    #[test]
964    fn detect_intent_cors_fix_prefers_howto() {
965        assert_eq!(
966            detect_intent("CORS error Access-Control-Allow-Origin fix"),
967            QueryIntent::HowTo
968        );
969    }
970
971    #[test]
972    fn detect_intent_node_heap_prefers_code() {
973        assert_eq!(
974            detect_intent("JavaScript heap out of memory Node.js fix"),
975            QueryIntent::Code
976        );
977    }
978
979    #[test]
980    fn detect_intent_consumer_best_year_query_prefers_opinion() {
981        let intent = detect_intent("best noise cancelling headphones for office calls 2026");
982        assert_eq!(intent, QueryIntent::Opinion);
983    }
984
985    #[test]
986    fn wikipedia_authority_capped_for_temporal() {
987        let wiki_result = make_result(
988            "Quantum computing",
989            "https://en.wikipedia.org/wiki/Quantum_computing",
990            "Quantum computing is the exploitation of collective properties...",
991        );
992        let base_auth = 0.9_f64;
993        let events_auth =
994            adjust_authority_for_intent(&wiki_result.url, base_auth, QueryIntent::CurrentEvents);
995        let factual_auth =
996            adjust_authority_for_intent(&wiki_result.url, base_auth, QueryIntent::Factual);
997        assert!(
998            events_auth < 0.4,
999            "Wikipedia authority for CurrentEvents should be < 0.4, got {events_auth}"
1000        );
1001        assert!(
1002            (factual_auth - base_auth).abs() < 1e-9,
1003            "Wikipedia authority for Factual should be unchanged"
1004        );
1005    }
1006
1007    #[test]
1008    fn detect_intent_informational() {
1009        assert_eq!(
1010            detect_intent("what is artificial intelligence"),
1011            QueryIntent::Informational
1012        );
1013        assert_eq!(detect_intent("what is ai"), QueryIntent::Informational);
1014        assert_eq!(
1015            detect_intent("what are neural networks"),
1016            QueryIntent::Informational
1017        );
1018        assert_eq!(
1019            detect_intent("who is Alan Turing"),
1020            QueryIntent::Informational
1021        );
1022        assert_eq!(
1023            detect_intent("explain machine learning"),
1024            QueryIntent::Informational
1025        );
1026        assert_eq!(
1027            detect_intent("define deep learning"),
1028            QueryIntent::Informational
1029        );
1030        assert_eq!(
1031            detect_intent("how does TCP work"),
1032            QueryIntent::Informational
1033        );
1034        assert_eq!(
1035            detect_intent("meaning of recursion"),
1036            QueryIntent::Informational
1037        );
1038    }
1039
1040    #[test]
1041    fn informational_authority_lower_than_code_for_github() {
1042        let github_result = make_result(
1043            "hand_detection",
1044            "https://github.com/user/hand_detection",
1045            "A popular ML repository for hand detection",
1046        );
1047        let weights_info = IntentWeights::for_intent(QueryIntent::Informational);
1048        let weights_code = IntentWeights::for_intent(QueryIntent::Code);
1049        // Informational gives much less weight to authority than Code
1050        assert!(
1051            weights_info.authority < weights_code.authority,
1052            "Informational authority weight ({}) should be < Code ({})",
1053            weights_info.authority,
1054            weights_code.authority
1055        );
1056        // GitHub authority should be downscaled for Informational
1057        let base_auth = 0.9_f64; // GitHub domain tier
1058        let info_auth =
1059            adjust_authority_for_intent(&github_result.url, base_auth, QueryIntent::Informational);
1060        let code_auth =
1061            adjust_authority_for_intent(&github_result.url, base_auth, QueryIntent::Code);
1062        assert!(
1063            info_auth < code_auth,
1064            "GitHub info_auth ({info_auth}) should be < code_auth ({code_auth})"
1065        );
1066        assert!(
1067            info_auth < 0.5,
1068            "GitHub authority for informational queries should be < 0.5, got {info_auth}"
1069        );
1070    }
1071
1072    #[test]
1073    fn weight_overrides_applied() {
1074        let weights = IntentWeights::for_intent(QueryIntent::Factual)
1075            .with_overrides(&[("temporal".to_string(), 0.9f64)].into_iter().collect());
1076        assert!((weights.temporal - 0.9).abs() < 1e-9);
1077    }
1078
1079    #[test]
1080    fn hyperfusion_populates_scores() {
1081        let mut results = vec![
1082            make_result("A", "https://a.com", "content A about systems programming"),
1083            make_result("B", "https://b.com", "content B about databases"),
1084        ];
1085        results[0].rank = 1;
1086        results[1].rank = 2;
1087        hyperfusion_rank(
1088            &mut results,
1089            "systems",
1090            QueryIntent::Factual,
1091            0.5,
1092            &HashMap::new(),
1093        );
1094        assert!(results[0].score.is_some());
1095        assert!(results[1].score.is_some());
1096    }
1097}