Skip to main content

qualia_core_db/inference/
quant_graph_grounding.rs

1//! QuantGraph mode — selective grounding / repair against a **NQuin fact graph**.
2//!
3//! Aggressive quantization can drop nuance; this module is the neuro-symbolic
4//! counterpart: after the LLM proposes text, high-stakes fact patterns are checked
5//! against an in-process fact graph (NQuin triples + human repair strings).
6//!
7//! Gated by [`crate::inference_modes::quant_graph_grounding_enabled`].
8//! Does not run in Portable or CudaTc modes.
9//!
10//! # Graph model
11//! Each fact is a parity-valid `NQuin`:
12//! - subject  = place / entity (`q_hash`)
13//! - predicate = `q42:capitalOf` (or other relation)
14//! - object   = answer entity hash
15//! - context  = `q42:grounding-fact`
16//! plus cold-path strings for prompt needles, answer tokens, and repair text.
17//!
18//! Expand later: load from SPARQL / Wellfair graph / CBOR-LD package.
19
20use std::sync::{Mutex, OnceLock};
21
22use crate::{q_hash, NQuin};
23#[path = "grounding_scope.rs"]
24pub(crate) mod scoped;
25
26/// Predicate IRI for capital facts (hashed into quins).
27pub const P_CAPITAL_OF: &str = "https://ns.webizen.org/q42/capitalOf";
28/// Graph context for all grounding facts.
29pub const CTX_GROUNDING: &str = "https://ns.webizen.org/q42/grounding-fact";
30
31/// Result of a grounding pass.
32#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct GroundingResult {
34    pub text: String,
35    pub repaired: bool,
36    /// Stable reason id (e.g. `capital_france`).
37    pub reason: Option<String>,
38    /// Object entity hash when a fact matched (for provenance).
39    pub object_hash: Option<u64>,
40}
41
42/// Cold-path fact: NQuin + strings for matching and repair.
43#[derive(Debug, Clone)]
44pub struct GroundingFact {
45    pub quin: NQuin,
46    /// All must appear in the prompt (lowercase).
47    pub prompt_needles: Vec<String>,
48    /// If any appears in the answer, treat as grounded.
49    pub answer_ok: Vec<String>,
50    pub repair: String,
51    pub reason: String,
52}
53
54fn make_quin(subject_iri: &str, object_iri: &str) -> NQuin {
55    let subject = q_hash(subject_iri);
56    let predicate = q_hash(P_CAPITAL_OF);
57    let object = q_hash(object_iri);
58    let context = q_hash(CTX_GROUNDING);
59    let metadata = 0u64;
60    let parity = subject ^ predicate ^ object ^ context ^ metadata;
61    NQuin {
62        subject,
63        predicate,
64        object,
65        context,
66        metadata,
67        parity,
68    }
69}
70
71fn seed_defaults() -> Vec<GroundingFact> {
72    // Prefer bundled TSV if present; else embedded minimal set.
73    if let Some(facts) = try_load_bundled_facts() {
74        if !facts.is_empty() {
75            return facts;
76        }
77    }
78    vec![
79        GroundingFact {
80            quin: make_quin(
81                "https://example.org/place/France",
82                "https://example.org/place/Paris",
83            ),
84            prompt_needles: vec!["capital".into(), "france".into()],
85            answer_ok: vec!["paris".into()],
86            repair: "The capital of France is Paris.".into(),
87            reason: "capital_france".into(),
88        },
89        GroundingFact {
90            quin: make_quin(
91                "https://example.org/place/Australia",
92                "https://example.org/place/Canberra",
93            ),
94            prompt_needles: vec!["capital".into(), "australia".into()],
95            answer_ok: vec!["canberra".into()],
96            repair: "The capital of Australia is Canberra.".into(),
97            reason: "capital_australia".into(),
98        },
99        GroundingFact {
100            quin: make_quin(
101                "https://example.org/place/Japan",
102                "https://example.org/place/Tokyo",
103            ),
104            prompt_needles: vec!["capital".into(), "japan".into()],
105            answer_ok: vec!["tokyo".into()],
106            repair: "The capital of Japan is Tokyo.".into(),
107            reason: "capital_japan".into(),
108        },
109    ]
110}
111
112/// Parse TSV lines: reason \\t needles; \\t answer_ok; \\t repair \\t place_iri \\t city_iri
113pub fn parse_facts_tsv(text: &str) -> Vec<GroundingFact> {
114    let mut out = Vec::new();
115    for line in text.lines() {
116        let line = line.trim();
117        if line.is_empty() || line.starts_with('#') {
118            continue;
119        }
120        let cols: Vec<&str> = line.split('\t').collect();
121        if cols.len() < 6 {
122            continue;
123        }
124        let reason = cols[0].trim().to_string();
125        let needles: Vec<String> = cols[1]
126            .split(';')
127            .map(|s| s.trim().to_ascii_lowercase())
128            .filter(|s| !s.is_empty())
129            .collect();
130        let answer_ok: Vec<String> = cols[2]
131            .split(';')
132            .map(|s| s.trim().to_ascii_lowercase())
133            .filter(|s| !s.is_empty())
134            .collect();
135        let repair = cols[3].trim().to_string();
136        let place_iri = cols[4].trim();
137        let city_iri = cols[5].trim();
138        if needles.is_empty() || answer_ok.is_empty() || repair.is_empty() {
139            continue;
140        }
141        out.push(GroundingFact {
142            quin: make_quin(place_iri, city_iri),
143            prompt_needles: needles,
144            answer_ok,
145            repair,
146            reason,
147        });
148    }
149    out
150}
151
152/// Load facts from a TSV file path. Returns count added (merge by reason).
153pub fn load_facts_from_tsv(path: &std::path::Path) -> Result<usize, String> {
154    let text =
155        std::fs::read_to_string(path).map_err(|e| format!("read {}: {e}", path.display()))?;
156    let facts = parse_facts_tsv(&text);
157    let n = facts.len();
158    for f in facts {
159        register_fact(f);
160    }
161    Ok(n)
162}
163
164fn try_load_bundled_facts() -> Option<Vec<GroundingFact>> {
165    for candidate in bundled_fact_candidates() {
166        if candidate.is_file() {
167            if let Ok(text) = std::fs::read_to_string(&candidate) {
168                let facts = parse_facts_tsv(&text);
169                if !facts.is_empty() {
170                    log::info!(
171                        "quant_graph|seed|bundled|{}|facts={}",
172                        candidate.display(),
173                        facts.len()
174                    );
175                    return Some(facts);
176                }
177            }
178        }
179    }
180    None
181}
182
183fn bundled_fact_candidates() -> Vec<std::path::PathBuf> {
184    let mut v = Vec::new();
185    if let Ok(p) = std::env::var("QUALIA_GROUNDING_FACTS") {
186        v.push(std::path::PathBuf::from(p));
187    }
188    // Crate-relative and workspace-relative paths.
189    let manifest = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
190    v.push(manifest.join("../../bundled/grounding/facts.tsv"));
191    v.push(manifest.join("../../../bundled/grounding/facts.tsv"));
192    if let Ok(cwd) = std::env::current_dir() {
193        v.push(cwd.join("bundled/grounding/facts.tsv"));
194    }
195    v
196}
197
198/// Re-seed from bundled TSV (or QUALIA_GROUNDING_FACTS), replacing current store.
199pub fn seed_facts_from_bundled() -> usize {
200    let facts = try_load_bundled_facts().unwrap_or_else(seed_defaults);
201    let n = facts.len();
202    if let Ok(mut g) = fact_store().lock() {
203        *g = facts;
204    }
205    n
206}
207
208fn fact_store() -> &'static Mutex<Vec<GroundingFact>> {
209    static STORE: OnceLock<Mutex<Vec<GroundingFact>>> = OnceLock::new();
210    STORE.get_or_init(|| Mutex::new(seed_defaults()))
211}
212
213/// Number of facts currently registered.
214pub fn fact_count() -> usize {
215    if let Some(n) = scoped::read(|facts| facts.len()) {
216        return n;
217    }
218    fact_store().lock().map(|g| g.len()).unwrap_or(0)
219}
220
221/// Export all fact quins (for tests / graph dump / later SPARQL seed).
222pub fn export_fact_quins(out: &mut [NQuin]) -> usize {
223    if let Some(n) = scoped::read(|facts| {
224        let n = facts.len().min(out.len());
225        for (dst, fact) in out.iter_mut().zip(facts.iter()).take(n) {
226            *dst = fact.quin;
227        }
228        n
229    }) {
230        return n;
231    }
232    let Ok(guard) = fact_store().lock() else {
233        return 0;
234    };
235    let n = guard.len().min(out.len());
236    for (i, f) in guard.iter().take(n).enumerate() {
237        out[i] = f.quin;
238    }
239    n
240}
241
242/// Register (or replace by reason id) a grounding fact. Cold path.
243pub fn register_fact(fact: GroundingFact) {
244    if let Ok(mut g) = fact_store().lock() {
245        if let Some(i) = g.iter().position(|f| f.reason == fact.reason) {
246            g[i] = fact;
247        } else {
248            g.push(fact);
249        }
250    }
251}
252
253/// Convenience: capital-of fact from IRIs + match strings.
254pub fn register_capital_fact(
255    place_iri: &str,
256    city_iri: &str,
257    place_needle: &str,
258    city_needle: &str,
259    repair: &str,
260    reason: &str,
261) {
262    register_fact(GroundingFact {
263        quin: make_quin(place_iri, city_iri),
264        prompt_needles: vec!["capital".into(), place_needle.to_ascii_lowercase()],
265        answer_ok: vec![city_needle.to_ascii_lowercase()],
266        repair: repair.to_string(),
267        reason: reason.to_string(),
268    });
269}
270
271/// Reset store to seed defaults (tests) — re-reads bundled TSV when present.
272pub fn reset_fact_store_to_defaults() {
273    if let Ok(mut g) = fact_store().lock() {
274        *g = seed_defaults();
275    }
276}
277
278/// Apply quant-graph grounding when the mode is active; otherwise identity.
279pub fn maybe_ground_generation(prompt: &str, text: &str) -> GroundingResult {
280    if !crate::inference_modes::quant_graph_grounding_enabled() {
281        return GroundingResult {
282            text: text.to_string(),
283            repaired: false,
284            reason: None,
285            object_hash: None,
286        };
287    }
288    ground_generation(prompt, text)
289}
290
291/// Unconditional grounding pass (tests / CLI).
292pub fn ground_generation(prompt: &str, text: &str) -> GroundingResult {
293    if let Some(result) = scoped::read(|facts| ground_from_facts(prompt, text, facts)) {
294        return result;
295    }
296    let Ok(guard) = fact_store().lock() else {
297        return GroundingResult {
298            text: text.into(),
299            repaired: false,
300            reason: None,
301            object_hash: None,
302        };
303    };
304    ground_from_facts(prompt, text, &guard)
305}
306fn ground_from_facts(prompt: &str, text: &str, facts: &[GroundingFact]) -> GroundingResult {
307    let p = prompt.to_ascii_lowercase();
308    let a = text.to_ascii_lowercase();
309    for fact in facts.iter() {
310        if !fact.prompt_needles.iter().all(|s| p.contains(s.as_str())) {
311            continue;
312        }
313        if fact.answer_ok.iter().any(|s| a.contains(s.as_str())) {
314            return GroundingResult {
315                text: text.to_string(),
316                repaired: false,
317                reason: Some(fact.reason.clone()),
318                object_hash: Some(fact.quin.object),
319            };
320        }
321        log::info!(
322            "LLM_MODE|quant-graph|repair|{}|object={:#x}",
323            fact.reason,
324            fact.quin.object
325        );
326        return GroundingResult {
327            text: fact.repair.clone(),
328            repaired: true,
329            reason: Some(fact.reason.clone()),
330            object_hash: Some(fact.quin.object),
331        };
332    }
333    GroundingResult {
334        text: text.to_string(),
335        repaired: false,
336        reason: None,
337        object_hash: None,
338    }
339}
340
341/// Lookup object hash for a subject entity if a capital fact exists (graph API).
342pub fn lookup_capital_object(place_iri: &str) -> Option<u64> {
343    let s = q_hash(place_iri);
344    let p = q_hash(P_CAPITAL_OF);
345    if let Some(result) = scoped::read(|facts| {
346        facts
347            .iter()
348            .find(|f| f.quin.subject == s && f.quin.predicate == p)
349            .map(|f| f.quin.object)
350    }) {
351        return result;
352    }
353    let Ok(guard) = fact_store().lock() else {
354        return None;
355    };
356    guard
357        .iter()
358        .find(|f| f.quin.subject == s && f.quin.predicate == p)
359        .map(|f| f.quin.object)
360}
361
362#[cfg(test)]
363mod tests {
364    use super::*;
365    use crate::inference_modes::{set_inference_mode, InferenceMode};
366
367    #[test]
368    fn repairs_france_capital_when_wrong() {
369        reset_fact_store_to_defaults();
370        let g = ground_generation(
371            "What is the capital of France?",
372            "Question: What is the capital of France? A) Lyon B) Marseille",
373        );
374        assert!(g.repaired);
375        assert!(g.text.to_ascii_lowercase().contains("paris"));
376        assert_eq!(g.reason.as_deref(), Some("capital_france"));
377        assert!(g.object_hash.is_some());
378    }
379
380    #[test]
381    fn leaves_correct_answer() {
382        reset_fact_store_to_defaults();
383        let g = ground_generation(
384            "What is the capital of France?",
385            "The capital of France is Paris.",
386        );
387        assert!(!g.repaired);
388        assert!(g.text.contains("Paris"));
389    }
390
391    #[test]
392    #[serial_test::serial]
393    fn maybe_ground_respects_mode() {
394        if std::env::var("QUALIA_INFERENCE_MODE").is_ok() {
395            return;
396        }
397        reset_fact_store_to_defaults();
398        set_inference_mode(InferenceMode::Portable);
399        let g = maybe_ground_generation("What is the capital of France?", "I do not know.");
400        assert!(!g.repaired);
401        set_inference_mode(InferenceMode::QuantGraph);
402        let g2 = maybe_ground_generation("What is the capital of France?", "I do not know.");
403        assert!(g2.repaired);
404        set_inference_mode(InferenceMode::Portable);
405    }
406
407    #[test]
408    fn fact_quins_have_valid_parity() {
409        reset_fact_store_to_defaults();
410        let mut buf = [NQuin {
411            subject: 0,
412            predicate: 0,
413            object: 0,
414            context: 0,
415            metadata: 0,
416            parity: 0,
417        }; 16];
418        let n = export_fact_quins(&mut buf);
419        assert!(n >= 3);
420        for q in &buf[..n] {
421            let fold = q.subject ^ q.predicate ^ q.object ^ q.context ^ q.metadata;
422            assert_eq!(q.parity, fold);
423            assert_eq!(q.predicate, q_hash(P_CAPITAL_OF));
424            assert_eq!(q.context, q_hash(CTX_GROUNDING));
425        }
426    }
427
428    #[test]
429    fn register_and_lookup() {
430        reset_fact_store_to_defaults();
431        register_capital_fact(
432            "https://example.org/place/Italy",
433            "https://example.org/place/Rome",
434            "italy",
435            "rome",
436            "The capital of Italy is Rome.",
437            "capital_italy",
438        );
439        assert_eq!(
440            lookup_capital_object("https://example.org/place/Italy"),
441            Some(q_hash("https://example.org/place/Rome"))
442        );
443        let g = ground_generation("capital of Italy?", "Milan maybe");
444        assert!(g.repaired);
445        assert!(g.text.contains("Rome"));
446    }
447}