qualia_core_db/inference/
quant_graph_grounding.rs1use std::sync::{Mutex, OnceLock};
21
22use crate::{q_hash, NQuin};
23#[path = "grounding_scope.rs"]
24pub(crate) mod scoped;
25
26pub const P_CAPITAL_OF: &str = "https://ns.webizen.org/q42/capitalOf";
28pub const CTX_GROUNDING: &str = "https://ns.webizen.org/q42/grounding-fact";
30
31#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct GroundingResult {
34 pub text: String,
35 pub repaired: bool,
36 pub reason: Option<String>,
38 pub object_hash: Option<u64>,
40}
41
42#[derive(Debug, Clone)]
44pub struct GroundingFact {
45 pub quin: NQuin,
46 pub prompt_needles: Vec<String>,
48 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 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
112pub 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
152pub 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 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
198pub 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
213pub 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
221pub 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
242pub 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
253pub 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
271pub fn reset_fact_store_to_defaults() {
273 if let Ok(mut g) = fact_store().lock() {
274 *g = seed_defaults();
275 }
276}
277
278pub 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
291pub 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
341pub 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}