Skip to main content

fetchium_core/intelligence/
pie.rs

1//! Persistent Intelligence Engine (PIE) — PRD §31.
2//!
3//! Orchestrates 4 learning layers that persist across sessions:
4//! - PKG: Personal Knowledge Graph
5//! - STM: Source Trust Memory (Bayesian Beta distribution)
6//! - FPM: Failure Pattern Memory
7//! - QPM: Query Prediction Model
8//!
9//! Data stored in `~/.fetchium/intelligence/`.
10
11pub mod fpm;
12pub mod pkg;
13pub mod qpm;
14pub mod stm;
15
16use crate::error::FetchiumError;
17use crate::intelligence::intelligence_data_dir;
18
19/// Aggregate statistics across all 4 PIE layers.
20#[derive(Debug, Clone, serde::Serialize)]
21pub struct PieStats {
22    pub entities: u64,
23    pub relationships: u64,
24    pub tracked_domains: u64,
25    pub failure_patterns: u64,
26    pub query_history_size: u64,
27}
28
29/// The 4-layer Persistent Intelligence Engine.
30pub struct PersistentIntelligenceEngine {
31    pub pkg: pkg::PersonalKnowledgeGraph,
32    pub stm: stm::SourceTrustMemory,
33    pub fpm: fpm::FailurePatternMemory,
34    pub qpm: qpm::QueryPredictionModel,
35}
36
37impl PersistentIntelligenceEngine {
38    /// Open all 4 layers from the default intelligence data directory.
39    pub fn new() -> Result<Self, FetchiumError> {
40        let base = intelligence_data_dir();
41        std::fs::create_dir_all(&base).map_err(|e| {
42            FetchiumError::Io(std::io::Error::new(
43                e.kind(),
44                format!("Failed to create intelligence dir {}: {e}", base.display()),
45            ))
46        })?;
47        Ok(Self {
48            pkg: pkg::PersonalKnowledgeGraph::new(&base.join("knowledge_graph.db"))?,
49            stm: stm::SourceTrustMemory::new(&base.join("source_trust.db"))?,
50            fpm: fpm::FailurePatternMemory::new(&base.join("failure_patterns.db"))?,
51            qpm: qpm::QueryPredictionModel::new(&base.join("query_patterns.db"))?,
52        })
53    }
54
55    /// Observe a completed search: update STM for each result domain and log the query.
56    pub fn observe_search(
57        &self,
58        query: &str,
59        result_domains: &[&str],
60        topic: &str,
61    ) -> Result<(), FetchiumError> {
62        for domain in result_domains {
63            self.stm.update_trust(domain, true, 0.7)?;
64        }
65        self.qpm.record_query(query, topic, None)?;
66        Ok(())
67    }
68
69    /// Observe a fetch attempt and record in both STM and FPM.
70    #[allow(clippy::too_many_arguments)]
71    pub fn observe_fetch(
72        &self,
73        domain: &str,
74        url: &str,
75        layer: u8,
76        success: bool,
77        error: Option<&str>,
78        duration_ms: u64,
79        relevance: f64,
80    ) -> Result<(), FetchiumError> {
81        let _ = url; // stored implicitly via domain
82        self.stm.update_trust(domain, success, relevance)?;
83        self.fpm
84            .record_attempt(domain, layer, success, error, duration_ms)?;
85        Ok(())
86    }
87
88    /// Aggregate statistics across all 4 layers.
89    pub fn stats(&self) -> Result<PieStats, FetchiumError> {
90        Ok(PieStats {
91            entities: self.pkg.entity_count()?,
92            relationships: self.pkg.relationship_count()?,
93            tracked_domains: self.stm.domain_count()?,
94            failure_patterns: self.fpm.pattern_count()?,
95            query_history_size: self.qpm.query_count()?,
96        })
97    }
98
99    /// Reset all learned data across all layers.
100    pub fn reset_all(&self) -> Result<(), FetchiumError> {
101        self.pkg.reset()?;
102        self.stm.reset()?;
103        self.fpm.reset()?;
104        self.qpm.reset()?;
105        Ok(())
106    }
107
108    /// Export a human-readable JSON summary of all layers.
109    pub fn export_json(&self) -> Result<String, FetchiumError> {
110        let stats = self.stats()?;
111        let top_entities = self.pkg.top_entities(20)?;
112        let top_domains = self.stm.top_trusted(20)?;
113        let top_topics = self.qpm.top_topics(10)?;
114
115        let export = serde_json::json!({
116            "stats": stats,
117            "top_entities": top_entities,
118            "top_trusted_domains": top_domains,
119            "top_query_topics": top_topics,
120        });
121
122        Ok(serde_json::to_string_pretty(&export)?)
123    }
124}
125
126/// Extract a coarse topic from a query string (lowercased first non-trivial word cluster).
127pub fn extract_topic(query: &str) -> String {
128    let stop_words = [
129        "the", "a", "an", "is", "are", "was", "were", "what", "how", "why", "who", "when", "where",
130        "which", "of", "in", "to", "for",
131    ];
132    let words: Vec<&str> = query
133        .split_whitespace()
134        .filter(|w| {
135            let lw = w.to_lowercase();
136            !stop_words.contains(&lw.as_str()) && lw.len() >= 3
137        })
138        .take(3)
139        .collect();
140    if words.is_empty() {
141        query.to_lowercase().trim().to_string()
142    } else {
143        words.join(" ").to_lowercase()
144    }
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150
151    #[test]
152    fn extract_topic_removes_stop_words() {
153        let topic = extract_topic("What is the best Rust framework for web");
154        assert!(
155            topic.contains("best") || topic.contains("rust") || topic.contains("framework"),
156            "topic={topic}"
157        );
158    }
159}