Skip to main content

qualia_core_db/inference/
qualia_hybrid.rs

1//! Qualia-unique hybrid inference: graph + manifold + modes + deontic.
2//!
3//! Most engines only optimise GEMV. QualiaDB can also:
4//! 1. **Graph-grounded speculative draft** — encode fact-table repairs as draft
5//!    tokens and verify with the same batch path as prompt-lookup (bit-exact when
6//!    accepted; force-emit when `QUALIA_GRAPH_FORCE=1`).
7//! 2. **Graph route mask** — hash prompt tokens into the U1 `AttentionRouteMask`
8//!    so sparse attention can bias toward graph-linked KV provenance slots.
9//! 3. **10D query publish** — fold prompt word hashes into a `Tensor10D` query
10//!    anchor for the continuous U1→U0 context-inject path.
11//! 4. **Graph logit bias** — boost tokenizer ids for known answer strings mid-decode
12//!    (neuro-symbolic sampling, not post-hoc string replace only).
13//! 5. **Deontic obligation** — when a high-stakes fact matches the prompt, compile
14//!    an `OP_OBLIGATE` norm Quin so the Rights/Webizen layer can audit the duty
15//!    to ground (unique to Qualia’s logic stack).
16//!
17//! These are first-class companions to portable/cuda/quant-graph modes — not a
18//! second engine.
19
20use crate::compute_universe::{
21    publish_attention_route_mask, publish_query_tensor, AttentionRouteMask,
22};
23use crate::prompt_lookup::{Draft, MAX_DRAFT};
24use crate::q_hash;
25use crate::tensor::Tensor10D;
26use crate::NQuin;
27
28#[cfg(not(target_arch = "wasm32"))]
29use crate::gguf_bridge::execution_env;
30// Browser configuration does not require the optional GPU inference runtime.
31#[cfg(target_arch = "wasm32")]
32use std::env as execution_env;
33
34/// Logit boost applied to graph answer-token ids (nats; soft guidance).
35pub const GRAPH_LOGIT_BIAS: f32 = 2.5;
36
37/// Prepare hybrid hints before a decode turn (safe no-ops when inactive).
38/// Call **after** any default `publish_query_tensor` so route/query are not wiped.
39/// FastVerify skips mid-decode hybrid work (post-turn verify owns quality).
40///
41/// **Do not** enable route masks under `mode=cuda` alone. That used to OR in
42/// `prefer_tensor_core_gemm()`, which published random prompt-hash KV masks and
43/// destroyed attention (measured garbage decode 2026-07-24: repeated `Ċ` tokens).
44/// Hybrid routing is for quant-graph / explicit `QUALIA_HYBRID_ROUTE=1` only.
45pub fn prepare_hybrid_decode(prompt: &str) {
46    if matches!(
47        crate::inference_modes::active_inference_mode(),
48        crate::inference_modes::InferenceMode::FastVerify
49    ) {
50        return;
51    }
52    let hybrid_route = crate::inference_modes::quant_graph_grounding_enabled()
53        || matches!(
54            execution_env::var("QUALIA_HYBRID_ROUTE").ok().as_deref(),
55            Some("1") | Some("true")
56        );
57    if hybrid_route {
58        publish_graph_route_from_prompt(prompt);
59        publish_prompt_query_tensor(prompt);
60    }
61    if crate::inference_modes::quant_graph_grounding_enabled() {
62        let _ = publish_grounding_obligation(prompt);
63    }
64}
65
66/// Map prompt words → attention route bits (tensor/KV provenance indices).
67/// Novel: uses the same U1 mask path as 10D kNN routing, fed from language not GPU.
68/// When quant-graph matches a fact, also route bits from subject/object quin hashes
69/// so attention can prefer KV slots co-located with grounding provenance.
70pub fn publish_graph_route_from_prompt(prompt: &str) {
71    let mut mask = AttentionRouteMask::default();
72    for word in prompt.split(|c: char| !c.is_alphanumeric()) {
73        if word.len() < 3 {
74            continue;
75        }
76        let h = q_hash(&word.to_ascii_lowercase());
77        // 1024 KV slots covered by route mask mapping in attention_kv_mask_u32.
78        mask.set_index((h % 1024) as u32);
79        // Also set a few nearby slots for soft neighbourhood.
80        mask.set_index(((h.wrapping_add(1)) % 1024) as u32);
81    }
82    // Fact-quin routing: subject/object hashes → deterministic KV indices.
83    if crate::inference_modes::quant_graph_grounding_enabled() {
84        let g = crate::quant_graph_grounding::ground_generation(prompt, "");
85        if let Some(obj) = g.object_hash {
86            mask.set_index((obj % 1024) as u32);
87            mask.set_index(((obj >> 10) % 1024) as u32);
88            // Export quin into a one-slot scratch for future SPARQL/WAL consumers.
89            let mut buf = [NQuin {
90                subject: 0,
91                predicate: 0,
92                object: 0,
93                context: 0,
94                metadata: 0,
95                parity: 0,
96            }; 8];
97            let n = crate::quant_graph_grounding::export_fact_quins(&mut buf);
98            for q in buf.iter().take(n) {
99                mask.set_index((q.subject % 1024) as u32);
100                mask.set_index((q.object % 1024) as u32);
101            }
102        }
103    }
104    if mask.active_bits > 0 {
105        publish_attention_route_mask(mask);
106        log::debug!("qualia_hybrid|route_mask|bits={}", mask.active_bits);
107    }
108}
109
110/// Fold prompt into a 10D query for continuous graph–tensor inject.
111pub fn publish_prompt_query_tensor(prompt: &str) {
112    let mut t = Tensor10D {
113        q: 0.0,
114        v: 0.0,
115        w: 0.0,
116        x: 0.0,
117        y: 0.0,
118        z: 0.0,
119        t: 0.0,
120        alpha: 0.0,
121        mu: 0.0,
122        sigma: 0.0,
123    };
124    let mut subject = 0u64;
125    let mut i = 0usize;
126    for word in prompt.split_whitespace().take(32) {
127        let h = q_hash(word);
128        subject ^= h.rotate_left((i as u32) * 3);
129        let f = ((h & 0xFFFF) as f32) / 65535.0;
130        match i % 10 {
131            0 => t.q += f,
132            1 => t.v += f,
133            2 => t.w += f,
134            3 => t.x += f,
135            4 => t.y += f,
136            5 => t.z += f,
137            6 => t.t += f,
138            7 => t.alpha += f,
139            8 => t.mu += f,
140            _ => t.sigma += f,
141        }
142        i += 1;
143    }
144    if i > 0 {
145        let n = i as f32;
146        t.q /= n;
147        t.v /= n;
148        t.w /= n;
149        t.x /= n;
150        t.y /= n;
151        t.z /= n;
152        t.t /= n;
153        t.alpha /= n;
154        t.mu /= n;
155        t.sigma /= n;
156        publish_query_tensor(t, subject);
157    }
158}
159
160/// Draft tokens from the quant-graph fact table (repair text encoded by caller).
161///
162/// `encode` should be the model tokenizer (`encode` or chat-aware). Returns empty
163/// when no fact matches the prompt. Uses empty-answer probe: if needles match and
164/// the (empty) answer is not yet grounded, draft the repair string for verify.
165pub fn propose_fact_draft(prompt: &str, encode: &dyn Fn(&str) -> Vec<u32>) -> Draft {
166    if !crate::inference_modes::quant_graph_grounding_enabled() {
167        return Draft::empty();
168    }
169    // Empty answer never contains answer_ok → repaired=true iff needles match.
170    let g = crate::quant_graph_grounding::ground_generation(prompt, "");
171    // Accept either repaired text or a known reason with object (fact hit).
172    let repair = if g.repaired {
173        g.text.as_str()
174    } else if g.reason.is_some() && g.object_hash.is_some() {
175        // Prompt matches a fact but empty answer was treated as already-ok (shouldn't
176        // happen); still no draft — model is free.
177        return Draft::empty();
178    } else {
179        return Draft::empty();
180    };
181    let ids = encode(repair);
182    if ids.is_empty() {
183        return Draft::empty();
184    }
185    let mut d = Draft::empty();
186    let take = ids.len().min(MAX_DRAFT);
187    d.tokens[..take].copy_from_slice(&ids[..take]);
188    d.len = take;
189    log::info!("qualia_hybrid|fact_draft|reason={:?}|len={take}", g.reason);
190    d
191}
192
193/// Whether to force-emit graph repair without model verify (high-stakes capitals, etc.).
194#[inline]
195pub fn graph_force_enabled() -> bool {
196    matches!(
197        execution_env::var("QUALIA_GRAPH_FORCE").ok().as_deref(),
198        Some("1") | Some("true")
199    )
200}
201
202/// If quant-graph + force, return full repair token sequence for immediate emit.
203pub fn force_fact_tokens(prompt: &str, encode: &dyn Fn(&str) -> Vec<u32>) -> Option<Vec<u32>> {
204    if !crate::inference_modes::quant_graph_grounding_enabled() || !graph_force_enabled() {
205        return None;
206    }
207    let g = crate::quant_graph_grounding::ground_generation(prompt, "");
208    if !g.repaired {
209        return None;
210    }
211    let ids = encode(&g.text);
212    if ids.is_empty() {
213        None
214    } else {
215        log::info!("qualia_hybrid|fact_force|reason={:?}", g.reason);
216        Some(ids)
217    }
218}
219
220/// Soft-boost logits for graph answer strings (first matching token id per string).
221///
222/// `lookup` maps a short answer string → preferred token id (e.g. tokenizer encode
223/// of "Paris" / "paris"). Call after full logits are on host, before sample/argmax.
224/// Returns how many vocab entries were boosted.
225pub fn apply_graph_logit_bias(
226    prompt: &str,
227    logits: &mut [f32],
228    lookup: &dyn Fn(&str) -> Option<u32>,
229) -> usize {
230    if !crate::inference_modes::quant_graph_grounding_enabled() || logits.is_empty() {
231        return 0;
232    }
233    let g = crate::quant_graph_grounding::ground_generation(prompt, "");
234    if !g.repaired {
235        // Already grounded or no match — nothing to bias.
236        return 0;
237    }
238    // Prefer the repair text tokens and the reason's capital name.
239    let mut boosted = 0usize;
240    let candidates: [&str; 4] = [
241        g.reason.as_deref().unwrap_or(""),
242        "Paris",
243        "paris",
244        g.text.as_str(),
245    ];
246    // Extract last word of repair as primary answer (… is Paris.)
247    let last_word = g
248        .text
249        .split(|c: char| !c.is_alphanumeric())
250        .filter(|w| w.len() > 2)
251        .last()
252        .unwrap_or("");
253    for s in [last_word, candidates[1], candidates[2]] {
254        if s.is_empty() {
255            continue;
256        }
257        if let Some(tid) = lookup(s) {
258            let i = tid as usize;
259            if i < logits.len() {
260                logits[i] += GRAPH_LOGIT_BIAS;
261                boosted += 1;
262            }
263        }
264        // Case variants
265        let lower = s.to_ascii_lowercase();
266        if lower != s {
267            if let Some(tid) = lookup(&lower) {
268                let i = tid as usize;
269                if i < logits.len() {
270                    logits[i] += GRAPH_LOGIT_BIAS * 0.5;
271                    boosted += 1;
272                }
273            }
274        }
275    }
276    if boosted > 0 {
277        log::debug!("qualia_hybrid|logit_bias|n={boosted}|reason={:?}", g.reason);
278    }
279    boosted
280}
281
282/// Compile a deontic **obligation** Quin for a matched grounding fact (audit trail).
283///
284/// Uses real `compile_norm_quin` — party = process principal hash, property =
285/// capitalOf path, contract = grounding context. Returns None when no fact matches.
286pub fn publish_grounding_obligation(prompt: &str) -> Option<NQuin> {
287    if !crate::inference_modes::quant_graph_grounding_enabled() {
288        return None;
289    }
290    let g = crate::quant_graph_grounding::ground_generation(prompt, "");
291    if g.reason.is_none() && !g.repaired {
292        return None;
293    }
294    let object = g.object_hash.unwrap_or(0);
295    if object == 0 {
296        return None;
297    }
298    // Party: synthetic "decode principal"; property: capitalOf; action: object city.
299    let party = q_hash("q42:inference-principal");
300    let property = q_hash(crate::quant_graph_grounding::P_CAPITAL_OF);
301    let contract = q_hash(crate::quant_graph_grounding::CTX_GROUNDING);
302    // Portal-only WASM lacks `crate::modalities`; obligation Quins need native/full stack.
303    #[cfg(any(
304        not(target_arch = "wasm32"),
305        feature = "wasm-ontology",
306        feature = "wasm-logic",
307        feature = "wasm-scientific",
308        feature = "wasm-full"
309    ))]
310    {
311        let quin = crate::modalities::logic::deontic::compile_norm_quin(
312            party,
313            crate::modalities::logic::deontic::OP_OBLIGATE,
314            property,
315            object,
316            contract,
317            0, // no expiry
318            false,
319        );
320        log::info!(
321            "qualia_hybrid|deontic_obligate|reason={:?}|object={object:#x}",
322            g.reason
323        );
324        Some(quin)
325    }
326    #[cfg(all(
327        target_arch = "wasm32",
328        not(any(
329            feature = "wasm-ontology",
330            feature = "wasm-logic",
331            feature = "wasm-scientific",
332            feature = "wasm-full"
333        ))
334    ))]
335    {
336        let _ = (party, property, object, contract);
337        log::info!(
338            "qualia_hybrid|deontic_obligate_skipped|portal_wasm|reason={:?}|object={object:#x}",
339            g.reason
340        );
341        None
342    }
343}
344
345/// Prefer fact draft when quant-graph; else prompt-lookup n-gram draft.
346pub fn propose_best_draft(prompt: &str, ctx: &[u32], encode: &dyn Fn(&str) -> Vec<u32>) -> Draft {
347    let fact = propose_fact_draft(prompt, encode);
348    if fact.len > 0 {
349        return fact;
350    }
351    crate::prompt_lookup::propose(ctx, MAX_DRAFT)
352}
353
354#[cfg(test)]
355mod tests {
356    use super::*;
357    use crate::inference_modes::{set_inference_mode, InferenceMode};
358    use crate::quant_graph_grounding::reset_fact_store_to_defaults;
359    use std::sync::Mutex;
360
361    /// Serialise mode mutations — InferenceMode is process-global.
362    fn mode_lock() -> std::sync::MutexGuard<'static, ()> {
363        static LOCK: Mutex<()> = Mutex::new(());
364        LOCK.lock().unwrap_or_else(|e| e.into_inner())
365    }
366
367    #[test]
368    #[serial_test::serial]
369    fn fact_draft_on_capital_prompt() {
370        if std::env::var("QUALIA_INFERENCE_MODE").is_ok() {
371            return;
372        }
373        let _g = mode_lock();
374        reset_fact_store_to_defaults();
375        set_inference_mode(InferenceMode::QuantGraph);
376        // Sanity: empty answer must repair when needles match.
377        let g =
378            crate::quant_graph_grounding::ground_generation("What is the capital of France?", "");
379        assert!(
380            g.repaired,
381            "expected repair on empty answer; reason={:?} text={}",
382            g.reason, g.text
383        );
384        let encode = |s: &str| {
385            // Fake tokenizer: one id per byte
386            s.bytes().map(|b| b as u32).collect()
387        };
388        let d = propose_fact_draft("What is the capital of France?", &encode);
389        assert!(
390            d.len > 0,
391            "draft len 0; repaired={} text={}",
392            g.repaired,
393            g.text
394        );
395        set_inference_mode(InferenceMode::Portable);
396    }
397
398    #[test]
399    fn route_mask_sets_bits() {
400        publish_graph_route_from_prompt("capital of France Paris knowledge graph");
401        let m = crate::compute_universe::attention_route_mask();
402        assert!(m.active_bits > 0);
403    }
404
405    #[test]
406    #[serial_test::serial]
407    fn logit_bias_boosts_vocab_slot() {
408        if std::env::var("QUALIA_INFERENCE_MODE").is_ok() {
409            return;
410        }
411        let _g = mode_lock();
412        reset_fact_store_to_defaults();
413        set_inference_mode(InferenceMode::QuantGraph);
414        let mut logits = vec![0.0f32; 128];
415        // Map any answer string containing 'P'/'p' style to fixed ids.
416        let lookup = |s: &str| -> Option<u32> {
417            if s.eq_ignore_ascii_case("paris") {
418                Some(42)
419            } else {
420                None
421            }
422        };
423        let n = apply_graph_logit_bias("What is the capital of France?", &mut logits, &lookup);
424        assert!(n >= 1);
425        assert!(logits[42] >= GRAPH_LOGIT_BIAS);
426        set_inference_mode(InferenceMode::Portable);
427    }
428
429    #[test]
430    #[serial_test::serial]
431    fn deontic_obligation_on_match() {
432        if std::env::var("QUALIA_INFERENCE_MODE").is_ok() {
433            return;
434        }
435        let _g = mode_lock();
436        reset_fact_store_to_defaults();
437        set_inference_mode(InferenceMode::QuantGraph);
438        let q = publish_grounding_obligation("What is the capital of France?");
439        assert!(q.is_some());
440        let q = q.unwrap();
441        assert_eq!(
442            (q.predicate & 0xFF) as u8,
443            crate::modalities::logic::deontic::OP_OBLIGATE
444        );
445        set_inference_mode(InferenceMode::Portable);
446    }
447}