Skip to main content

qualia_core_db/lora/
context_detector.rs

1//! Context detection for LoRA adapter selection.
2//!
3//! Classifies a natural-language prompt (and optionally the NQuin
4//! metadata vector) into one of the six `ContextType` domains using
5//! weighted keyword scoring and bigram analysis.
6
7use std::collections::HashMap;
8
9// ─── ContextType ─────────────────────────────────────────────────────────────
10
11/// Domain classification used to select the correct LoRA adapter.
12///
13/// The 4-bit encoding in `NQuin.metadata` bits 63–60 must stay stable;
14/// do not reorder these variants.
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
16#[repr(u8)]
17pub enum ContextType {
18    General = 0x0,
19    Medical = 0x1,
20    Legal = 0x2,
21    Chemical = 0x3,
22    Biological = 0x4,
23    Technical = 0x5,
24}
25
26impl ContextType {
27    /// Decode from the 4-bit metadata field (bits 63–60).
28    pub fn from_metadata_bits(bits: u8) -> Self {
29        match bits & 0xF {
30            0x1 => ContextType::Medical,
31            0x2 => ContextType::Legal,
32            0x3 => ContextType::Chemical,
33            0x4 => ContextType::Biological,
34            0x5 => ContextType::Technical,
35            _ => ContextType::General,
36        }
37    }
38
39    /// Metadata bit encoding for the context type.
40    pub fn to_metadata_bits(self) -> u8 {
41        self as u8
42    }
43
44    /// Adapter filename for the context.
45    pub fn adapter_filename(self) -> &'static str {
46        match self {
47            ContextType::General => "general_v1.lora",
48            ContextType::Medical => "medical_v1.lora",
49            ContextType::Legal => "legal_v1.lora",
50            ContextType::Chemical => "chemical_v1.lora",
51            ContextType::Biological => "biological_v1.lora",
52            ContextType::Technical => "technical_v1.lora",
53        }
54    }
55
56    /// All context types.
57    pub fn all() -> &'static [ContextType] {
58        &[
59            ContextType::General,
60            ContextType::Medical,
61            ContextType::Legal,
62            ContextType::Chemical,
63            ContextType::Biological,
64            ContextType::Technical,
65        ]
66    }
67}
68
69impl std::fmt::Display for ContextType {
70    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
71        match self {
72            ContextType::General => write!(f, "general"),
73            ContextType::Medical => write!(f, "medical"),
74            ContextType::Legal => write!(f, "legal"),
75            ContextType::Chemical => write!(f, "chemical"),
76            ContextType::Biological => write!(f, "biological"),
77            ContextType::Technical => write!(f, "technical"),
78        }
79    }
80}
81
82// ─── NGramAnalyzer ────────────────────────────────────────────────────────────
83
84struct NGramAnalyzer {
85    bigram_weights: HashMap<(&'static str, &'static str), (ContextType, f32)>,
86}
87
88impl NGramAnalyzer {
89    fn new() -> Self {
90        let mut bigram_weights = HashMap::new();
91        // Medical bigrams
92        for pair in [
93            ("patient", "diagnosis"),
94            ("medical", "record"),
95            ("clinical", "trial"),
96            ("emergency", "room"),
97            ("blood", "pressure"),
98            ("heart", "rate"),
99            ("drug", "dosage"),
100            ("surgical", "procedure"),
101        ] {
102            bigram_weights.insert(pair, (ContextType::Medical, 0.85));
103        }
104        // Legal bigrams
105        for pair in [
106            ("legal", "contract"),
107            ("court", "order"),
108            ("intellectual", "property"),
109            ("due", "diligence"),
110            ("breach", "contract"),
111            ("statute", "limitations"),
112            ("case", "law"),
113            ("legal", "counsel"),
114        ] {
115            bigram_weights.insert(pair, (ContextType::Legal, 0.85));
116        }
117        // Chemical bigrams
118        for pair in [
119            ("chemical", "reaction"),
120            ("organic", "compound"),
121            ("synthesis", "reaction"),
122            ("chemical", "bond"),
123            ("molecular", "weight"),
124            ("oxidation", "reduction"),
125            ("acid", "base"),
126            ("reaction", "mechanism"),
127        ] {
128            bigram_weights.insert(pair, (ContextType::Chemical, 0.85));
129        }
130        // Biological bigrams
131        for pair in [
132            ("gene", "expression"),
133            ("cell", "division"),
134            ("protein", "synthesis"),
135            ("natural", "selection"),
136            ("dna", "replication"),
137            ("immune", "system"),
138            ("metabolic", "pathway"),
139            ("stem", "cell"),
140        ] {
141            bigram_weights.insert(pair, (ContextType::Biological, 0.85));
142        }
143        // Technical bigrams
144        for pair in [
145            ("machine", "learning"),
146            ("neural", "network"),
147            ("api", "endpoint"),
148            ("data", "structure"),
149            ("time", "complexity"),
150            ("memory", "management"),
151            ("software", "architecture"),
152            ("distributed", "system"),
153        ] {
154            bigram_weights.insert(pair, (ContextType::Technical, 0.85));
155        }
156        Self { bigram_weights }
157    }
158
159    fn score(&self, tokens: &[&str]) -> HashMap<ContextType, f32> {
160        let mut scores: HashMap<ContextType, f32> = HashMap::new();
161        for window in tokens.windows(2) {
162            if let [a, b] = window {
163                if let Some(&(ctx, w)) = self.bigram_weights.get(&(*a, *b)) {
164                    *scores.entry(ctx).or_insert(0.0) += w;
165                }
166            }
167        }
168        scores
169    }
170}
171
172// ─── ContextDetector ─────────────────────────────────────────────────────────
173
174/// Classifies text into one of the `ContextType` domains.
175///
176/// Uses a two-phase approach:
177/// 1. Unigram keyword scoring (fast, O(n) where n = token count).
178/// 2. Bigram analysis for disambiguation of overlapping domains.
179///
180/// The resulting confidence is normalised to [0, 1]; a score below
181/// `confidence_threshold` falls back to `ContextType::General`.
182pub struct ContextDetector {
183    /// Per-domain keyword → weight table.
184    keyword_weights: HashMap<&'static str, Vec<(ContextType, f32)>>,
185    ngrams: NGramAnalyzer,
186    /// Minimum normalised confidence before the detector commits to a domain.
187    pub confidence_threshold: f32,
188}
189
190impl ContextDetector {
191    /// Creates `ContextDetector` with the given state.
192    pub fn new() -> Self {
193        let mut kw: HashMap<&'static str, Vec<(ContextType, f32)>> = HashMap::new();
194
195        macro_rules! add {
196            ($word:expr, $( ($ctx:expr, $w:expr) ),+) => {
197                kw.entry($word).or_default().extend([$( ($ctx, $w) ),+]);
198            };
199        }
200
201        // ── Medical ──
202        for w in [
203            "diagnosis",
204            "symptom",
205            "treatment",
206            "medication",
207            "patient",
208            "clinical",
209            "prescription",
210            "therapy",
211            "disease",
212            "anatomy",
213            "physiology",
214            "pharmacology",
215            "surgery",
216            "emergency",
217            "vaccine",
218            "oncology",
219            "radiology",
220            "pathology",
221            "neurology",
222            "cardiology",
223            "prognosis",
224            "aetiology",
225            "comorbidity",
226            "triage",
227            "dosage",
228        ] {
229            add!(
230                w,
231                (ContextType::Medical, 0.9),
232                (ContextType::Biological, 0.4)
233            );
234        }
235
236        // ── Legal ──
237        for w in [
238            "contract",
239            "agreement",
240            "liability",
241            "legal",
242            "court",
243            "law",
244            "jurisdiction",
245            "statute",
246            "regulation",
247            "compliance",
248            "litigation",
249            "plaintiff",
250            "defendant",
251            "attorney",
252            "verdict",
253            "evidence",
254            "indemnity",
255            "arbitration",
256            "injunction",
257            "tort",
258            "precedent",
259            "affidavit",
260            "deposition",
261            "fiduciary",
262            "subpoena",
263        ] {
264            add!(w, (ContextType::Legal, 0.9));
265        }
266
267        // ── Chemical ──
268        for w in [
269            "molecule",
270            "compound",
271            "reaction",
272            "chemical",
273            "synthesis",
274            "bond",
275            "catalyst",
276            "reagent",
277            "solvent",
278            "stoichiometry",
279            "organic",
280            "inorganic",
281            "polymer",
282            "spectroscopy",
283            "titration",
284            "oxidation",
285            "reduction",
286            "isomer",
287            "alkyl",
288            "hydroxyl",
289            "carbonyl",
290            "ester",
291            "molar",
292            "entropy",
293            "enthalpy",
294        ] {
295            add!(
296                w,
297                (ContextType::Chemical, 0.9),
298                (ContextType::Technical, 0.2)
299            );
300        }
301
302        // ── Biological ──
303        for w in [
304            "cell",
305            "gene",
306            "protein",
307            "dna",
308            "rna",
309            "organism",
310            "species",
311            "evolution",
312            "ecosystem",
313            "metabolism",
314            "genetics",
315            "biology",
316            "immunology",
317            "mitosis",
318            "meiosis",
319            "chromosome",
320            "allele",
321            "phenotype",
322            "genotype",
323            "ribosome",
324            "enzyme",
325            "chlorophyll",
326            "photosynthesis",
327            "fermentation",
328            "microbiome",
329        ] {
330            add!(
331                w,
332                (ContextType::Biological, 0.9),
333                (ContextType::Chemical, 0.3)
334            );
335        }
336
337        // ── Technical ──
338        for w in [
339            "algorithm",
340            "software",
341            "hardware",
342            "programming",
343            "code",
344            "system",
345            "database",
346            "network",
347            "protocol",
348            "interface",
349            "api",
350            "encryption",
351            "authentication",
352            "optimization",
353            "latency",
354            "throughput",
355            "compiler",
356            "runtime",
357            "kernel",
358            "concurrency",
359            "async",
360            "cache",
361            "shader",
362            "tensor",
363            "gradient",
364        ] {
365            add!(w, (ContextType::Technical, 0.9));
366        }
367
368        Self {
369            keyword_weights: kw,
370            ngrams: NGramAnalyzer::new(),
371            confidence_threshold: 0.55,
372        }
373    }
374
375    /// Classify `text` and return `(domain, confidence)`.
376    ///
377    /// Confidence of 0.0 means no relevant keywords found.
378    pub fn analyze_text(&self, text: &str) -> (ContextType, f32) {
379        let tokens: Vec<&str> = text
380            .split(|c: char| !c.is_alphanumeric())
381            .filter(|s| !s.is_empty())
382            .map(|s| {
383                // &'static trick: we only look up keys that are &'static str.
384                // For matching, we lowercase into a stack buffer via a scratch approach.
385                // Here we accept the pointer-equality limitation and use a raw compare.
386                s
387            })
388            .collect();
389
390        // Lowercase comparison via a small scratch allocation (adapter init path, not hot).
391        let lowered: Vec<String> = tokens.iter().map(|t| t.to_lowercase()).collect();
392        let lower_refs: Vec<&str> = lowered.iter().map(|s| s.as_str()).collect();
393
394        let mut scores: HashMap<ContextType, f32> = HashMap::new();
395
396        // Unigram pass
397        for tok in &lower_refs {
398            if let Some(weights) = self.keyword_weights.get(tok) {
399                for &(ctx, w) in weights {
400                    *scores.entry(ctx).or_insert(0.0) += w;
401                }
402            }
403        }
404
405        // Bigram pass (half weight)
406        for (ctx, w) in self.ngrams.score(&lower_refs) {
407            *scores.entry(ctx).or_insert(0.0) += w * 0.5;
408        }
409
410        if scores.is_empty() {
411            return (ContextType::General, 0.0);
412        }
413
414        let best = scores
415            .iter()
416            .max_by(|(_, a), (_, b)| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal))
417            .map(|(&ctx, &s)| (ctx, s))
418            .unwrap();
419
420        let total: f32 = scores.values().sum();
421        let confidence = if total > 0.0 { best.1 / total } else { 0.0 };
422
423        if confidence < self.confidence_threshold {
424            (ContextType::General, confidence)
425        } else {
426            (best.0, confidence)
427        }
428    }
429
430    /// Combine text-derived and metadata-derived contexts.
431    ///
432    /// The higher-confidence signal wins; ties go to metadata.
433    pub fn combine(
434        &self,
435        text_result: (ContextType, f32),
436        meta_result: (ContextType, f32),
437    ) -> (ContextType, f32) {
438        if text_result.1 > meta_result.1 {
439            text_result
440        } else {
441            meta_result
442        }
443    }
444}
445
446impl Default for ContextDetector {
447    fn default() -> Self {
448        Self::new()
449    }
450}
451
452// ─── Tests ───────────────────────────────────────────────────────────────────
453
454#[cfg(test)]
455mod tests {
456    use super::*;
457
458    #[test]
459    fn test_medical_detection() {
460        let det = ContextDetector::new();
461        let (ctx, conf) = det.analyze_text("The patient requires medication for the diagnosis");
462        assert_eq!(
463            ctx,
464            ContextType::Medical,
465            "expected Medical, got {:?} (conf={conf:.2})",
466            ctx
467        );
468        assert!(conf > 0.5);
469    }
470
471    #[test]
472    fn test_legal_detection() {
473        let det = ContextDetector::new();
474        let (ctx, conf) = det.analyze_text("The plaintiff filed a contract litigation case");
475        assert_eq!(
476            ctx,
477            ContextType::Legal,
478            "expected Legal, got {:?} (conf={conf:.2})",
479            ctx
480        );
481        assert!(conf > 0.5);
482    }
483
484    #[test]
485    fn test_chemical_detection() {
486        let det = ContextDetector::new();
487        let (ctx, conf) =
488            det.analyze_text("Organic synthesis of the catalyst compound via reaction");
489        assert_eq!(
490            ctx,
491            ContextType::Chemical,
492            "expected Chemical, got {:?} (conf={conf:.2})",
493            ctx
494        );
495        assert!(conf > 0.4);
496    }
497
498    #[test]
499    fn test_biological_detection() {
500        let det = ContextDetector::new();
501        let (ctx, conf) =
502            det.analyze_text("Gene expression in the cell affects protein synthesis via RNA");
503        assert_eq!(
504            ctx,
505            ContextType::Biological,
506            "expected Biological, got {:?} (conf={conf:.2})",
507            ctx
508        );
509        assert!(conf > 0.4);
510    }
511
512    #[test]
513    fn test_technical_detection() {
514        let det = ContextDetector::new();
515        let (ctx, conf) =
516            det.analyze_text("Optimizing the algorithm latency in the distributed system");
517        assert_eq!(
518            ctx,
519            ContextType::Technical,
520            "expected Technical, got {:?} (conf={conf:.2})",
521            ctx
522        );
523        assert!(conf > 0.5);
524    }
525
526    #[test]
527    fn test_general_fallback() {
528        let det = ContextDetector::new();
529        let (ctx, _conf) = det.analyze_text("Hello world");
530        assert_eq!(ctx, ContextType::General);
531    }
532
533    #[test]
534    fn test_roundtrip_metadata_bits() {
535        for &ct in ContextType::all() {
536            let bits = ct.to_metadata_bits();
537            let decoded = ContextType::from_metadata_bits(bits);
538            assert_eq!(decoded, ct, "roundtrip failed for {:?}", ct);
539        }
540    }
541}