Skip to main content

qualia_core_db/research/
investigation.rs

1//! Investigation — evidence collection, hypotheses, timelines, links.
2
3use std::collections::BTreeMap;
4
5/// Reliability level for a piece of evidence.
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub enum EvidenceReliability {
8    Confirmed,
9    Probable,
10    Possible,
11    Doubtful,
12    Discredited,
13}
14
15impl EvidenceReliability {
16    /// Numeric reliability score in `[0,1]`.
17    pub fn as_f64(&self) -> f64 {
18        match self {
19            Self::Confirmed => 1.0,
20            Self::Probable => 0.75,
21            Self::Possible => 0.5,
22            Self::Doubtful => 0.25,
23            Self::Discredited => 0.0,
24        }
25    }
26}
27
28/// A piece of evidence in an investigation.
29#[derive(Debug, Clone)]
30pub struct Evidence {
31    pub id: String,
32    pub description: String,
33    pub source: String,
34    pub reliability: EvidenceReliability,
35    pub timestamp: Option<String>,
36    pub supports: Vec<String>,    // Hypothesis IDs this supports
37    pub contradicts: Vec<String>, // Hypothesis IDs this contradicts
38}
39
40impl Evidence {
41    /// Creates evidence with `id`, `description`, `source`.
42    pub fn new(id: &str, description: &str, source: &str) -> Self {
43        Self {
44            id: id.to_string(),
45            description: description.to_string(),
46            source: source.to_string(),
47            reliability: EvidenceReliability::Possible,
48            timestamp: None,
49            supports: Vec::new(),
50            contradicts: Vec::new(),
51        }
52    }
53
54    /// Sets this evidence's reliability rating.
55    pub fn set_reliability(&mut self, reliability: EvidenceReliability) {
56        self.reliability = reliability;
57    }
58}
59
60/// A hypothesis proposed during an investigation.
61#[derive(Debug, Clone)]
62pub struct Hypothesis {
63    pub id: String,
64    pub statement: String,
65    pub supporting_evidence: Vec<String>,
66    pub contradicting_evidence: Vec<String>,
67    pub confidence: f64,
68    pub status: HypothesisStatus,
69}
70
71#[derive(Debug, Clone, Copy, PartialEq, Eq)]
72pub enum HypothesisStatus {
73    Proposed,
74    UnderEvaluation,
75    Supported,
76    Refuted,
77    Inconclusive,
78}
79
80impl Hypothesis {
81    /// Creates a hypothesis with `id` and `statement`.
82    pub fn new(id: &str, statement: &str) -> Self {
83        Self {
84            id: id.to_string(),
85            statement: statement.to_string(),
86            supporting_evidence: Vec::new(),
87            contradicting_evidence: Vec::new(),
88            confidence: 0.0,
89            status: HypothesisStatus::Proposed,
90        }
91    }
92
93    /// Evaluate the hypothesis based on collected evidence.
94    pub fn evaluate(&mut self) {
95        let support_count = self.supporting_evidence.len();
96        let contra_count = self.contradicting_evidence.len();
97        let total = support_count + contra_count;
98        if total == 0 {
99            self.status = HypothesisStatus::Inconclusive;
100            return;
101        }
102        self.confidence = support_count as f64 / total as f64;
103        self.status = if self.confidence >= 2.0 / 3.0 {
104            HypothesisStatus::Supported
105        } else if self.confidence <= 1.0 / 3.0 {
106            HypothesisStatus::Refuted
107        } else {
108            HypothesisStatus::UnderEvaluation
109        };
110    }
111}
112
113/// A timeline entry for the investigation.
114#[derive(Debug, Clone)]
115pub struct TimelineEntry {
116    pub timestamp: String,
117    pub event: String,
118    pub evidence_id: Option<String>,
119}
120
121/// An investigation — evidence, hypotheses, timeline, and links.
122#[derive(Debug, Clone)]
123pub struct Investigation {
124    pub id: String,
125    pub evidence: BTreeMap<String, Evidence>,
126    pub hypotheses: BTreeMap<String, Hypothesis>,
127    pub timeline: Vec<TimelineEntry>,
128    pub links: Vec<(String, String, String)>, // (source, target, link_type)
129}
130
131impl Investigation {
132    /// Creates an empty investigation with `id`.
133    pub fn new(id: &str) -> Self {
134        Self {
135            id: id.to_string(),
136            evidence: BTreeMap::new(),
137            hypotheses: BTreeMap::new(),
138            timeline: Vec::new(),
139            links: Vec::new(),
140        }
141    }
142
143    /// Adds evidence to the investigation.
144    pub fn collect_evidence(&mut self, evidence: Evidence) {
145        self.evidence.insert(evidence.id.clone(), evidence);
146    }
147
148    /// Updates reliability of `evidence_id`; `false` when not found.
149    pub fn set_reliability(&mut self, evidence_id: &str, reliability: EvidenceReliability) -> bool {
150        if let Some(ev) = self.evidence.get_mut(evidence_id) {
151            ev.set_reliability(reliability);
152            true
153        } else {
154            false
155        }
156    }
157
158    /// Adds a hypothesis.
159    pub fn propose_hypothesis(&mut self, hypothesis: Hypothesis) {
160        self.hypotheses.insert(hypothesis.id.clone(), hypothesis);
161    }
162
163    /// Evaluate evidence for a hypothesis — links evidence and re-evaluates.
164    pub fn evaluate_evidence(&mut self, hypothesis_id: &str) -> bool {
165        let ev_ids: Vec<String> = self.evidence.keys().cloned().collect();
166        for ev_id in ev_ids {
167            let (supports, contradicts) = {
168                let ev = self.evidence.get(&ev_id).unwrap();
169                (ev.supports.clone(), ev.contradicts.clone())
170            };
171            if let Some(hyp) = self.hypotheses.get_mut(hypothesis_id) {
172                if supports.contains(&hyp.id.to_string())
173                    && !hyp.supporting_evidence.contains(&ev_id)
174                {
175                    hyp.supporting_evidence.push(ev_id.clone());
176                }
177                if contradicts.contains(&hyp.id.to_string())
178                    && !hyp.contradicting_evidence.contains(&ev_id)
179                {
180                    hyp.contradicting_evidence.push(ev_id);
181                }
182            }
183        }
184        if let Some(hyp) = self.hypotheses.get_mut(hypothesis_id) {
185            hyp.evaluate();
186            true
187        } else {
188            false
189        }
190    }
191
192    /// Adds a timeline event, optionally linked to `evidence_id`.
193    pub fn create_timeline(&mut self, timestamp: &str, event: &str, evidence_id: Option<&str>) {
194        self.timeline.push(TimelineEntry {
195            timestamp: timestamp.to_string(),
196            event: event.to_string(),
197            evidence_id: evidence_id.map(|s| s.to_string()),
198        });
199    }
200
201    /// Adds a typed link between two evidence/hypothesis ids.
202    pub fn add_link(&mut self, source: &str, target: &str, link_type: &str) {
203        self.links.push((
204            source.to_string(),
205            target.to_string(),
206            link_type.to_string(),
207        ));
208    }
209
210    /// Find a path between two entities through the link graph (BFS).
211    pub fn find_path(&self, start: &str, end: &str) -> Option<Vec<String>> {
212        if start == end {
213            return Some(vec![start.to_string()]);
214        }
215        let mut visited = std::collections::BTreeSet::new();
216        let mut queue: Vec<(String, Vec<String>)> =
217            vec![(start.to_string(), vec![start.to_string()])];
218        visited.insert(start.to_string());
219
220        while let Some((current, path)) = queue.pop() {
221            for (src, tgt, _) in &self.links {
222                if src == &current && !visited.contains(tgt) {
223                    let mut new_path = path.clone();
224                    new_path.push(tgt.clone());
225                    if tgt == end {
226                        return Some(new_path);
227                    }
228                    visited.insert(tgt.clone());
229                    queue.push((tgt.clone(), new_path));
230                }
231                if tgt == &current && !visited.contains(src) {
232                    let mut new_path = path.clone();
233                    new_path.push(src.clone());
234                    if src == end {
235                        return Some(new_path);
236                    }
237                    visited.insert(src.clone());
238                    queue.push((src.clone(), new_path));
239                }
240            }
241        }
242        None
243    }
244}
245
246#[cfg(test)]
247mod tests {
248    use super::*;
249
250    #[test]
251    fn investigation_basic() {
252        let inv = Investigation::new("inv1");
253        assert_eq!(inv.id, "inv1");
254        assert!(inv.evidence.is_empty());
255    }
256
257    #[test]
258    fn investigation_collect_evidence() {
259        let mut inv = Investigation::new("inv1");
260        inv.collect_evidence(Evidence::new("e1", "Document found", "source_a"));
261        assert!(inv.evidence.contains_key("e1"));
262    }
263
264    #[test]
265    fn investigation_propose_hypothesis() {
266        let mut inv = Investigation::new("inv1");
267        inv.propose_hypothesis(Hypothesis::new("h1", "X caused Y"));
268        assert!(inv.hypotheses.contains_key("h1"));
269    }
270
271    #[test]
272    fn hypothesis_evaluate_supported() {
273        let mut inv = Investigation::new("inv1");
274        let mut ev1 = Evidence::new("e1", "Evidence A", "src");
275        ev1.supports = vec!["h1".to_string()];
276        let mut ev2 = Evidence::new("e2", "Evidence B", "src");
277        ev2.supports = vec!["h1".to_string()];
278        let mut ev3 = Evidence::new("e3", "Evidence C", "src");
279        ev3.contradicts = vec!["h1".to_string()];
280        inv.collect_evidence(ev1);
281        inv.collect_evidence(ev2);
282        inv.collect_evidence(ev3);
283        inv.propose_hypothesis(Hypothesis::new("h1", "X caused Y"));
284        inv.evaluate_evidence("h1");
285        let hyp = inv.hypotheses.get("h1").unwrap();
286        assert_eq!(hyp.status, HypothesisStatus::Supported);
287    }
288
289    #[test]
290    fn hypothesis_evaluate_refuted() {
291        let mut inv = Investigation::new("inv1");
292        let mut ev1 = Evidence::new("e1", "Evidence A", "src");
293        ev1.contradicts = vec!["h1".to_string()];
294        let mut ev2 = Evidence::new("e2", "Evidence B", "src");
295        ev2.contradicts = vec!["h1".to_string()];
296        let mut ev3 = Evidence::new("e3", "Evidence C", "src");
297        ev3.supports = vec!["h1".to_string()];
298        inv.collect_evidence(ev1);
299        inv.collect_evidence(ev2);
300        inv.collect_evidence(ev3);
301        inv.propose_hypothesis(Hypothesis::new("h1", "X caused Y"));
302        inv.evaluate_evidence("h1");
303        let hyp = inv.hypotheses.get("h1").unwrap();
304        assert_eq!(hyp.status, HypothesisStatus::Refuted);
305    }
306
307    #[test]
308    fn investigation_timeline() {
309        let mut inv = Investigation::new("inv1");
310        inv.create_timeline("2024-01-01", "Event A", Some("e1"));
311        inv.create_timeline("2024-02-01", "Event B", None);
312        assert_eq!(inv.timeline.len(), 2);
313    }
314
315    #[test]
316    fn investigation_find_path() {
317        let mut inv = Investigation::new("inv1");
318        inv.add_link("a", "b", "causal");
319        inv.add_link("b", "c", "temporal");
320        inv.add_link("c", "d", "informational");
321        let path = inv.find_path("a", "d");
322        assert!(path.is_some());
323        assert_eq!(path.unwrap(), vec!["a", "b", "c", "d"]);
324    }
325
326    #[test]
327    fn investigation_find_path_none() {
328        let mut inv = Investigation::new("inv1");
329        inv.add_link("a", "b", "causal");
330        assert!(inv.find_path("a", "z").is_none());
331    }
332}