Skip to main content

fetchium_core/rank/
evidence.rs

1//! Evidence Graph Builder (EGB) — builds citation/corroboration graphs between results.
2//!
3//! Detects when multiple sources agree on the same facts, strengthening confidence.
4//! Uses term-overlap and URL cross-references to build an evidence network.
5//! Results with high corroboration scores are more trustworthy.
6
7use crate::types::ResultItem;
8use std::collections::{HashMap, HashSet};
9
10/// Configuration for the evidence graph builder.
11#[derive(Debug, Clone)]
12pub struct EvidenceConfig {
13    /// Minimum Jaccard similarity to consider two results corroborating.
14    pub corroboration_threshold: f64,
15    /// Bonus multiplier applied to well-corroborated results.
16    pub corroboration_boost: f64,
17    /// Maximum number of edges per node (prevents dense graphs).
18    pub max_edges_per_node: usize,
19}
20
21impl Default for EvidenceConfig {
22    fn default() -> Self {
23        Self {
24            corroboration_threshold: 0.15,
25            corroboration_boost: 1.2,
26            max_edges_per_node: 5,
27        }
28    }
29}
30
31/// An edge in the evidence graph representing agreement between two results.
32#[derive(Debug, Clone)]
33pub struct EvidenceEdge {
34    /// Index of the source result.
35    pub from: usize,
36    /// Index of the target result.
37    pub to: usize,
38    /// Strength of the corroboration (Jaccard similarity).
39    pub strength: f64,
40    /// Terms shared between the two results.
41    pub shared_terms: Vec<String>,
42}
43
44/// A node in the evidence graph with its corroboration score.
45#[derive(Debug, Clone)]
46pub struct EvidenceNode {
47    /// Index into the original results.
48    pub result_index: usize,
49    /// How many other results corroborate this one.
50    pub corroboration_count: usize,
51    /// Aggregate corroboration strength (sum of edge weights).
52    pub corroboration_strength: f64,
53    /// The result is from a unique source (no corroboration).
54    pub is_unique_claim: bool,
55}
56
57/// The complete evidence graph.
58#[derive(Debug, Clone)]
59pub struct EvidenceGraph {
60    pub nodes: Vec<EvidenceNode>,
61    pub edges: Vec<EvidenceEdge>,
62    /// Average corroboration across all results.
63    pub mean_corroboration: f64,
64    /// Fraction of results with at least one corroboration.
65    pub coverage: f64,
66}
67
68/// Build an evidence graph from search results.
69///
70/// Computes pairwise similarity between all results and builds a graph
71/// where edges represent agreement/corroboration.
72pub fn build_evidence_graph(results: &[ResultItem], config: &EvidenceConfig) -> EvidenceGraph {
73    if results.is_empty() {
74        return EvidenceGraph {
75            nodes: vec![],
76            edges: vec![],
77            mean_corroboration: 0.0,
78            coverage: 0.0,
79        };
80    }
81
82    let n = results.len();
83
84    // Extract term sets for all results
85    let term_sets: Vec<HashSet<String>> = results.iter().map(extract_terms).collect();
86
87    // Extract domains to avoid self-corroboration from same source
88    let domains: Vec<String> = results.iter().map(|r| extract_domain(&r.url)).collect();
89
90    // Build edges
91    let mut edges = Vec::new();
92    let mut edge_counts: HashMap<usize, usize> = HashMap::new();
93
94    for i in 0..n {
95        for j in (i + 1)..n {
96            // Skip same-domain results (not independent corroboration)
97            if !domains[i].is_empty() && domains[i] == domains[j] {
98                continue;
99            }
100
101            // Check edge limits
102            let i_count = edge_counts.get(&i).copied().unwrap_or(0);
103            let j_count = edge_counts.get(&j).copied().unwrap_or(0);
104            if i_count >= config.max_edges_per_node || j_count >= config.max_edges_per_node {
105                continue;
106            }
107
108            let similarity = jaccard(&term_sets[i], &term_sets[j]);
109            if similarity >= config.corroboration_threshold {
110                let shared: Vec<String> =
111                    term_sets[i].intersection(&term_sets[j]).cloned().collect();
112
113                edges.push(EvidenceEdge {
114                    from: i,
115                    to: j,
116                    strength: similarity,
117                    shared_terms: shared,
118                });
119
120                *edge_counts.entry(i).or_insert(0) += 1;
121                *edge_counts.entry(j).or_insert(0) += 1;
122            }
123        }
124    }
125
126    // Build nodes
127    let mut node_strengths: Vec<f64> = vec![0.0; n];
128    let mut node_counts: Vec<usize> = vec![0; n];
129
130    for edge in &edges {
131        node_strengths[edge.from] += edge.strength;
132        node_strengths[edge.to] += edge.strength;
133        node_counts[edge.from] += 1;
134        node_counts[edge.to] += 1;
135    }
136
137    let nodes: Vec<EvidenceNode> = (0..n)
138        .map(|i| EvidenceNode {
139            result_index: i,
140            corroboration_count: node_counts[i],
141            corroboration_strength: node_strengths[i],
142            is_unique_claim: node_counts[i] == 0,
143        })
144        .collect();
145
146    // Compute graph-level metrics
147    let total_strength: f64 = node_strengths.iter().sum();
148    let mean_corroboration = if n > 0 {
149        total_strength / n as f64
150    } else {
151        0.0
152    };
153    let corroborated_count = node_counts.iter().filter(|&&c| c > 0).count();
154    let coverage = if n > 0 {
155        corroborated_count as f64 / n as f64
156    } else {
157        0.0
158    };
159
160    EvidenceGraph {
161        nodes,
162        edges,
163        mean_corroboration,
164        coverage,
165    }
166}
167
168/// Apply corroboration boosts to result scores.
169///
170/// Results confirmed by multiple independent sources get their score boosted.
171pub fn apply_evidence_boost(
172    results: &mut [ResultItem],
173    graph: &EvidenceGraph,
174    config: &EvidenceConfig,
175) {
176    for node in &graph.nodes {
177        if node.corroboration_count > 0 && node.result_index < results.len() {
178            let boost = 1.0
179                + (config.corroboration_boost - 1.0) * (node.corroboration_count as f64).min(3.0)
180                    / 3.0;
181            let result = &mut results[node.result_index];
182            let current = result.score.unwrap_or(0.5);
183            result.score = Some((current * boost).min(1.0));
184        }
185    }
186}
187
188// ─── Internal helpers ──────────────────────────────────────
189
190fn extract_terms(item: &ResultItem) -> HashSet<String> {
191    let text = format!("{} {}", item.title, item.snippet).to_lowercase();
192    text.split(|c: char| !c.is_alphanumeric())
193        .filter(|t| t.len() >= 3 && !is_stop_word(t))
194        .map(|t| t.to_string())
195        .collect()
196}
197
198fn extract_domain(url: &str) -> String {
199    url::Url::parse(url)
200        .ok()
201        .and_then(|u| u.host_str().map(|h| h.to_string()))
202        .unwrap_or_default()
203}
204
205fn jaccard(a: &HashSet<String>, b: &HashSet<String>) -> f64 {
206    if a.is_empty() && b.is_empty() {
207        return 0.0;
208    }
209    let intersection = a.intersection(b).count();
210    let union = a.union(b).count();
211    if union == 0 {
212        return 0.0;
213    }
214    intersection as f64 / union as f64
215}
216
217fn is_stop_word(word: &str) -> bool {
218    const STOP: &[&str] = &[
219        "the", "and", "for", "are", "but", "not", "you", "all", "can", "was", "one", "our", "out",
220        "has", "had", "how", "its", "may", "new", "now", "see", "way", "who", "did", "get", "let",
221        "say", "she", "too", "use", "this", "that", "with", "have", "from", "they", "been", "some",
222        "when", "what", "your", "each", "make", "like", "just", "than", "them", "very", "will",
223        "more", "also",
224    ];
225    STOP.contains(&word)
226}
227
228#[cfg(test)]
229mod tests {
230    use super::*;
231    use crate::types::BackendId;
232
233    fn make_item(title: &str, snippet: &str, url: &str) -> ResultItem {
234        ResultItem {
235            title: title.into(),
236            url: url.into(),
237            snippet: snippet.into(),
238            rank: 0,
239            backend: BackendId::DuckDuckGo,
240            score: Some(0.5),
241            published_date: None,
242        }
243    }
244
245    #[test]
246    fn empty_results_empty_graph() {
247        let graph = build_evidence_graph(&[], &EvidenceConfig::default());
248        assert!(graph.nodes.is_empty());
249        assert!(graph.edges.is_empty());
250        assert_eq!(graph.mean_corroboration, 0.0);
251    }
252
253    #[test]
254    fn single_result_no_edges() {
255        let items = vec![make_item(
256            "Rust",
257            "A systems language",
258            "https://rust-lang.org",
259        )];
260        let graph = build_evidence_graph(&items, &EvidenceConfig::default());
261        assert_eq!(graph.nodes.len(), 1);
262        assert!(graph.edges.is_empty());
263        assert!(graph.nodes[0].is_unique_claim);
264    }
265
266    #[test]
267    fn corroborating_results_create_edge() {
268        let items = vec![
269            make_item(
270                "Rust Memory Safety",
271                "Rust guarantees memory safety through ownership and borrowing",
272                "https://a.com/rust",
273            ),
274            make_item(
275                "Rust Safety Features",
276                "Rust ownership system ensures memory safety without garbage collection",
277                "https://b.com/rust",
278            ),
279        ];
280        let graph = build_evidence_graph(&items, &EvidenceConfig::default());
281        assert!(
282            !graph.edges.is_empty(),
283            "corroborating results should create edges"
284        );
285        assert!(graph.coverage > 0.0);
286    }
287
288    #[test]
289    fn unrelated_results_no_edges() {
290        let items = vec![
291            make_item(
292                "Rust Programming",
293                "Systems language with ownership",
294                "https://a.com",
295            ),
296            make_item(
297                "Cooking Recipe",
298                "How to bake chocolate cake flour sugar",
299                "https://b.com",
300            ),
301        ];
302        let graph = build_evidence_graph(&items, &EvidenceConfig::default());
303        assert!(
304            graph.edges.is_empty(),
305            "unrelated results should have no edges"
306        );
307    }
308
309    #[test]
310    fn same_domain_not_corroboration() {
311        let items = vec![
312            make_item(
313                "Rust Article 1",
314                "Rust ownership memory safety borrow",
315                "https://example.com/a",
316            ),
317            make_item(
318                "Rust Article 2",
319                "Rust ownership memory safety lifetimes",
320                "https://example.com/b",
321            ),
322        ];
323        let graph = build_evidence_graph(&items, &EvidenceConfig::default());
324        assert!(
325            graph.edges.is_empty(),
326            "same-domain results should not corroborate"
327        );
328    }
329
330    #[test]
331    fn evidence_boost_increases_scores() {
332        let mut items = vec![
333            make_item(
334                "Rust Safety",
335                "Rust memory safety ownership borrow",
336                "https://a.com",
337            ),
338            make_item(
339                "Rust Ownership",
340                "Rust memory safety borrow checker system",
341                "https://b.com",
342            ),
343        ];
344        let config = EvidenceConfig::default();
345        let graph = build_evidence_graph(&items, &config);
346
347        let scores_before: Vec<f64> = items.iter().map(|r| r.score.unwrap_or(0.0)).collect();
348        apply_evidence_boost(&mut items, &graph, &config);
349        let scores_after: Vec<f64> = items.iter().map(|r| r.score.unwrap_or(0.0)).collect();
350
351        if !graph.edges.is_empty() {
352            assert!(
353                scores_after[0] >= scores_before[0],
354                "corroborated result should be boosted"
355            );
356        }
357    }
358
359    #[test]
360    fn max_edges_respected() {
361        let config = EvidenceConfig {
362            max_edges_per_node: 2,
363            corroboration_threshold: 0.1,
364            ..EvidenceConfig::default()
365        };
366
367        // Create 5 similar results from different domains
368        let items: Vec<ResultItem> = (0..5)
369            .map(|i| {
370                make_item(
371                    "Rust memory safety ownership borrow checker",
372                    "The Rust programming language guarantees memory safety",
373                    &format!("https://site{i}.com/article"),
374                )
375            })
376            .collect();
377
378        let graph = build_evidence_graph(&items, &config);
379
380        // No node should have more than max_edges edges
381        for node in &graph.nodes {
382            assert!(
383                node.corroboration_count <= config.max_edges_per_node,
384                "node {} has {} edges, max is {}",
385                node.result_index,
386                node.corroboration_count,
387                config.max_edges_per_node,
388            );
389        }
390    }
391
392    #[test]
393    fn coverage_metric_correct() {
394        let items = vec![
395            make_item(
396                "Rust Safety",
397                "Rust ownership borrow memory safe",
398                "https://a.com",
399            ),
400            make_item(
401                "Rust Borrow",
402                "Rust ownership borrow memory checker",
403                "https://b.com",
404            ),
405            make_item(
406                "Cooking Tips",
407                "How to bake cookies flour sugar eggs",
408                "https://c.com",
409            ),
410        ];
411        let graph = build_evidence_graph(&items, &EvidenceConfig::default());
412
413        // Cooking result should be unique, Rust results may corroborate
414        assert!(graph.coverage <= 1.0);
415        assert!(graph.coverage >= 0.0);
416    }
417}