Skip to main content

fetchium_core/intelligence/pie/
pkg.rs

1//! Personal Knowledge Graph (PKG) — stores entities and relationships across sessions.
2//!
3//! Schema:
4//! - `entities(id, name, type, source_url, frequency, first_seen, last_seen)`
5//! - `relationships(entity_a, entity_b, relation, weight, first_seen, last_seen)`
6
7use rusqlite::Connection;
8use std::sync::Mutex;
9
10use crate::error::FetchiumError;
11use crate::intelligence::enable_wal;
12
13/// A node in the personal knowledge graph.
14#[derive(Debug, Clone, serde::Serialize)]
15pub struct Entity {
16    pub id: u64,
17    pub name: String,
18    pub entity_type: String,
19    pub frequency: u64,
20    pub first_seen: String,
21    pub last_seen: String,
22}
23
24/// A directed edge in the personal knowledge graph.
25#[derive(Debug, Clone, serde::Serialize)]
26pub struct Relationship {
27    pub entity_a: String,
28    pub entity_b: String,
29    pub relation: String,
30    pub weight: f64,
31}
32
33pub struct PersonalKnowledgeGraph {
34    conn: Mutex<Connection>,
35}
36
37impl PersonalKnowledgeGraph {
38    pub fn new(db_path: &std::path::Path) -> Result<Self, FetchiumError> {
39        let conn = Connection::open(db_path)?;
40        enable_wal(&conn)?;
41        conn.execute_batch(
42            "CREATE TABLE IF NOT EXISTS entities (
43                id          INTEGER PRIMARY KEY AUTOINCREMENT,
44                name        TEXT    NOT NULL UNIQUE,
45                type        TEXT    NOT NULL DEFAULT 'concept',
46                source_url  TEXT,
47                frequency   INTEGER NOT NULL DEFAULT 1,
48                first_seen  TEXT    NOT NULL DEFAULT (datetime('now')),
49                last_seen   TEXT    NOT NULL DEFAULT (datetime('now'))
50            );
51            CREATE TABLE IF NOT EXISTS relationships (
52                entity_a   TEXT NOT NULL,
53                entity_b   TEXT NOT NULL,
54                relation   TEXT NOT NULL,
55                weight     REAL NOT NULL DEFAULT 1.0,
56                first_seen TEXT NOT NULL DEFAULT (datetime('now')),
57                last_seen  TEXT NOT NULL DEFAULT (datetime('now')),
58                PRIMARY KEY (entity_a, entity_b, relation)
59            );",
60        )?;
61        Ok(Self {
62            conn: Mutex::new(conn),
63        })
64    }
65
66    /// Add or increment an entity. Returns entity ID.
67    pub fn add_entity(
68        &self,
69        name: &str,
70        entity_type: &str,
71        source_url: &str,
72    ) -> Result<u64, FetchiumError> {
73        let conn = self.conn.lock().unwrap();
74        conn.execute(
75            "INSERT INTO entities (name, type, source_url)
76             VALUES (?1, ?2, ?3)
77             ON CONFLICT(name) DO UPDATE SET
78                frequency  = frequency + 1,
79                last_seen  = datetime('now')",
80            rusqlite::params![name, entity_type, source_url],
81        )?;
82        let id: i64 = conn.query_row("SELECT id FROM entities WHERE name = ?1", [name], |row| {
83            row.get(0)
84        })?;
85        Ok(id as u64)
86    }
87
88    /// Add or update a weighted relationship between two entities.
89    pub fn add_relationship(
90        &self,
91        entity_a: &str,
92        entity_b: &str,
93        relation: &str,
94        weight: f64,
95    ) -> Result<(), FetchiumError> {
96        let conn = self.conn.lock().unwrap();
97        conn.execute(
98            "INSERT INTO relationships (entity_a, entity_b, relation, weight)
99             VALUES (?1, ?2, ?3, ?4)
100             ON CONFLICT(entity_a, entity_b, relation) DO UPDATE SET
101                weight    = (weight + ?4) / 2.0,
102                last_seen = datetime('now')",
103            rusqlite::params![entity_a, entity_b, relation, weight],
104        )?;
105        Ok(())
106    }
107
108    /// Find entities related to `entity`, sorted by weight descending.
109    pub fn related_entities(
110        &self,
111        entity: &str,
112        limit: usize,
113    ) -> Result<Vec<(String, String, f64)>, FetchiumError> {
114        let conn = self.conn.lock().unwrap();
115        let mut stmt = conn.prepare(
116            "SELECT entity_b, relation, weight FROM relationships WHERE entity_a = ?1
117             UNION
118             SELECT entity_a, relation, weight FROM relationships WHERE entity_b = ?1
119             ORDER BY weight DESC
120             LIMIT ?2",
121        )?;
122        let results = stmt
123            .query_map(rusqlite::params![entity, limit as i64], |row| {
124                Ok((
125                    row.get::<_, String>(0)?,
126                    row.get::<_, String>(1)?,
127                    row.get::<_, f64>(2)?,
128                ))
129            })?
130            .filter_map(|r| r.ok())
131            .collect();
132        Ok(results)
133    }
134
135    /// Top entities by frequency.
136    pub fn top_entities(&self, limit: usize) -> Result<Vec<Entity>, FetchiumError> {
137        let conn = self.conn.lock().unwrap();
138        let mut stmt = conn.prepare(
139            "SELECT id, name, type, frequency, first_seen, last_seen
140             FROM entities
141             ORDER BY frequency DESC
142             LIMIT ?1",
143        )?;
144        let results = stmt
145            .query_map([limit as i64], |row| {
146                Ok(Entity {
147                    id: row.get::<_, i64>(0)? as u64,
148                    name: row.get(1)?,
149                    entity_type: row.get(2)?,
150                    frequency: row.get::<_, i64>(3)? as u64,
151                    first_seen: row.get(4)?,
152                    last_seen: row.get(5)?,
153                })
154            })?
155            .filter_map(|r| r.ok())
156            .collect();
157        Ok(results)
158    }
159
160    /// Total entity count.
161    pub fn entity_count(&self) -> Result<u64, FetchiumError> {
162        let conn = self.conn.lock().unwrap();
163        let n: i64 = conn.query_row("SELECT COUNT(*) FROM entities", [], |row| row.get(0))?;
164        Ok(n as u64)
165    }
166
167    /// Total relationship count.
168    pub fn relationship_count(&self) -> Result<u64, FetchiumError> {
169        let conn = self.conn.lock().unwrap();
170        let n: i64 = conn.query_row("SELECT COUNT(*) FROM relationships", [], |row| row.get(0))?;
171        Ok(n as u64)
172    }
173
174    /// Reset all knowledge graph data.
175    pub fn reset(&self) -> Result<(), FetchiumError> {
176        let conn = self.conn.lock().unwrap();
177        conn.execute_batch(
178            "DELETE FROM entities;
179             DELETE FROM relationships;
180             VACUUM;",
181        )?;
182        Ok(())
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189    use tempfile::NamedTempFile;
190
191    #[test]
192    fn entity_frequency_increments_on_repeat() {
193        let tmp = NamedTempFile::new().unwrap();
194        let pkg = PersonalKnowledgeGraph::new(tmp.path()).unwrap();
195        pkg.add_entity("Rust", "language", "https://rust-lang.org")
196            .unwrap();
197        pkg.add_entity("Rust", "language", "https://doc.rust-lang.org")
198            .unwrap();
199        let entities = pkg.top_entities(5).unwrap();
200        assert_eq!(entities[0].name, "Rust");
201        assert_eq!(entities[0].frequency, 2);
202    }
203
204    #[test]
205    fn relationships_are_bidirectional_queryable() {
206        let tmp = NamedTempFile::new().unwrap();
207        let pkg = PersonalKnowledgeGraph::new(tmp.path()).unwrap();
208        pkg.add_relationship("Rust", "WebAssembly", "compiles_to", 0.8)
209            .unwrap();
210        let related = pkg.related_entities("WebAssembly", 10).unwrap();
211        assert!(related.iter().any(|(e, _, _)| e == "Rust"));
212    }
213}