Skip to main content

fetchium_core/proactive/
prefetch.rs

1//! Predictive prefetching — pre-cache likely follow-up queries (PRD §33).
2
3use crate::error::FetchiumResult;
4use serde::{Deserialize, Serialize};
5use std::collections::VecDeque;
6
7/// A prefetch request with associated priority.
8#[derive(Debug, Clone, Serialize, Deserialize)]
9pub struct PrefetchEntry {
10    pub query: String,
11    /// Priority in [0.0, 1.0]; higher = fetch sooner.
12    pub priority: f64,
13    pub requested_at: String,
14}
15
16/// In-memory priority queue for prefetch requests.
17#[derive(Default)]
18pub struct PrefetchQueue {
19    queue: VecDeque<PrefetchEntry>,
20}
21
22impl PrefetchQueue {
23    pub fn new() -> Self {
24        Self::default()
25    }
26
27    /// Enqueue a query for prefetching.
28    pub fn enqueue(&mut self, query: &str, priority: f64) {
29        let entry = PrefetchEntry {
30            query: query.to_string(),
31            priority: priority.clamp(0.0, 1.0),
32            requested_at: chrono::Utc::now().to_rfc3339(),
33        };
34        // Insert in priority order (highest first)
35        let pos = self
36            .queue
37            .iter()
38            .position(|e| e.priority < entry.priority)
39            .unwrap_or(self.queue.len());
40        self.queue.insert(pos, entry);
41    }
42
43    /// Dequeue the highest-priority prefetch request.
44    pub fn dequeue(&mut self) -> Option<PrefetchEntry> {
45        self.queue.pop_front()
46    }
47
48    pub fn len(&self) -> usize {
49        self.queue.len()
50    }
51
52    pub fn is_empty(&self) -> bool {
53        self.queue.is_empty()
54    }
55}
56
57/// Generate prefetch candidates from a completed search result.
58///
59/// Heuristically generates likely follow-up queries:
60/// - Adds "tutorial" and "examples" variants for informational queries.
61/// - Adds "vs <top_result>" for comparison queries.
62pub fn generate_candidates(
63    query: &str,
64    result_titles: &[String],
65) -> FetchiumResult<Vec<(String, f64)>> {
66    let mut candidates: Vec<(String, f64)> = Vec::new();
67    let q = query.trim().to_ascii_lowercase();
68
69    // Tutorial follow-up for informational queries
70    if !q.contains("tutorial") && !q.contains("example") {
71        candidates.push((format!("{query} tutorial"), 0.6));
72        candidates.push((format!("{query} examples"), 0.5));
73    }
74
75    // "Latest news" follow-up
76    if !q.contains("news") && !q.contains("latest") {
77        candidates.push((format!("{query} latest news"), 0.7));
78    }
79
80    // Top result title as a follow-up query
81    if let Some(title) = result_titles.first() {
82        let short: String = title
83            .split_whitespace()
84            .take(5)
85            .collect::<Vec<_>>()
86            .join(" ");
87        if !short.is_empty() && short.len() > 5 {
88            candidates.push((short, 0.4));
89        }
90    }
91
92    Ok(candidates)
93}
94
95#[cfg(test)]
96mod tests {
97    use super::*;
98
99    #[test]
100    fn test_queue_priority_ordering() {
101        let mut q = PrefetchQueue::new();
102        q.enqueue("low", 0.2);
103        q.enqueue("high", 0.9);
104        q.enqueue("mid", 0.5);
105        let first = q.dequeue().unwrap();
106        assert_eq!(first.query, "high");
107    }
108
109    #[test]
110    fn test_generate_candidates() {
111        let titles = vec!["Rust async book".to_string()];
112        let cands = generate_candidates("Rust async", &titles).unwrap();
113        assert!(!cands.is_empty());
114    }
115}