Skip to main content

qualia_core_db/inference/inference_agent/
local_agent.rs

1// The concrete `LocalLlmAgent` struct, its constructors, LoRA adapter
2// management, sieve-lexicon wiring, and DID hashing. The Phase-8 decode path
3// lives in `decode.rs`; intent validation in `validation.rs`; the
4// `AgentRuntime` impl in `runtime.rs` — all separate impl blocks on this type.
5
6use crate::q_hash;
7
8use super::types::{default_local_modality, AgentBackend};
9
10// ─── LocalLlmAgent ───────────────────────────────────────────────────────────
11/// The concrete local inference agent. Uses a mock inference path for now;
12/// swap `infer_local_model` for an actual llama.cpp FFI call.
13pub struct LocalLlmAgent {
14    #[cfg(not(target_arch = "wasm32"))]
15    pub(super) native_request:
16        std::sync::Mutex<Option<super::native_request::NativeGovernedRequest>>,
17    pub agent_did: String,
18    pub backend: AgentBackend,
19    pub memory_used_bytes: std::sync::atomic::AtomicU64,
20    // NOTE: the four fields below were private in the monolith. They are now
21    // `pub(super)` widenings so the decode (`decode.rs`) and runtime
22    // (`runtime.rs`) impl blocks can read/write them across the new submodule
23    // boundary. Visibility stays crate-internal — the external API is unchanged.
24    /// Set by `validate_intent` when `output_mode` requires graph-structured emission.
25    pub(super) use_sieve_output: std::sync::atomic::AtomicBool,
26    /// Memory-mapped `.q42.lex` sidecar for dynamic sieve masks.
27    pub(super) sieve_lex_path: std::sync::Mutex<Option<String>>,
28    /// IRI hashes to resolve through the lexicon for Subject / Predicate / Object slots.
29    pub(super) sieve_spec: std::sync::Mutex<crate::neuro_symbolic_sieve::SieveLexSpec>,
30    /// Optional LoRA adapter manager for zero-copy context-driven neural adaptation.
31    /// When set, the prompt is classified into a domain (Medical / Legal / Chemical / …)
32    /// and the matching adapter's delta is applied to the embedding hidden state before
33    /// the autoregressive decode loop.
34    pub(super) lora_manager: std::sync::Mutex<Option<crate::lora::LoRAAdapterManager>>,
35}
36
37impl LocalLlmAgent {
38    /// Creates `LocalLlmAgent` with the given state.
39    pub fn new(agent_did: impl Into<String>, model_path: impl Into<String>) -> Self {
40        Self::with_local_backend(
41            agent_did,
42            AgentBackend::Local {
43                model_path: model_path.into(),
44                context_window: 4096,
45                quantization: "Q4_K_M".into(),
46                vision_projector_path: None,
47                modality: default_local_modality(),
48                architecture: None,
49            },
50        )
51    }
52
53    /// Construct an agent with a fully specified backend (e.g. catalog multimodal profile).
54    pub fn with_local_backend(agent_did: impl Into<String>, backend: AgentBackend) -> Self {
55        Self {
56            #[cfg(not(target_arch = "wasm32"))]
57            native_request: std::sync::Mutex::new(None),
58            agent_did: agent_did.into(),
59            backend,
60            memory_used_bytes: std::sync::atomic::AtomicU64::new(0),
61            use_sieve_output: std::sync::atomic::AtomicBool::new(false),
62            sieve_lex_path: std::sync::Mutex::new(None),
63            sieve_spec: std::sync::Mutex::new(
64                crate::neuro_symbolic_sieve::SieveLexSpec::graph_mutation_default(),
65            ),
66            lora_manager: std::sync::Mutex::new(None),
67        }
68    }
69
70    /// Bind one prepared normal-runtime request. Occupied bindings refuse rather
71    /// than replacing another caller's authority. Every infer entry consumes it.
72    #[cfg(not(target_arch = "wasm32"))]
73    pub fn bind_native_governed_request(
74        &self,
75        request: super::native_request::NativeGovernedRequest,
76    ) -> Result<(), super::governed::PolicyError> {
77        let mut slot = self
78            .native_request
79            .lock()
80            .map_err(|_| super::governed::PolicyError::Revoked)?;
81        if slot.is_some() {
82            return Err(super::governed::PolicyError::Capacity);
83        }
84        *slot = Some(request);
85        Ok(())
86    }
87
88    // ── LoRA adapter management ───────────────────────────────────────────────
89
90    /// Attach a LoRA adapter directory to this agent.
91    ///
92    /// Adapters are loaded lazily on the first prompt that triggers a domain
93    /// switch.  The directory must contain `*.lora` files named after
94    /// `ContextType::adapter_filename()` (e.g. `medical_v1.lora`).
95    pub fn attach_lora_adapters(&self, adapter_dir: impl Into<std::path::PathBuf>) {
96        let mgr = crate::lora::LoRAAdapterManager::new(adapter_dir);
97        *self.lora_manager.lock().unwrap_or_else(|e| e.into_inner()) = Some(mgr);
98    }
99
100    /// Attach a LoRA manager pre-configured with expected embedding dimensions.
101    ///
102    /// `n_in` should match the model's embedding dimension (e.g. 4096 for 7B models).
103    pub fn attach_lora_adapters_with_dims(
104        &self,
105        adapter_dir: impl Into<std::path::PathBuf>,
106        n_in: usize,
107        n_out: usize,
108    ) {
109        let mut mgr = crate::lora::LoRAAdapterManager::new(adapter_dir);
110        mgr.set_expected_dims(n_in, n_out);
111        *self.lora_manager.lock().unwrap_or_else(|e| e.into_inner()) = Some(mgr);
112    }
113
114    /// Remove the LoRA manager and revert to base-model-only inference.
115    pub fn detach_lora_adapters(&self) {
116        *self.lora_manager.lock().unwrap_or_else(|e| e.into_inner()) = None;
117    }
118
119    /// Detect context from `prompt` and pre-warm the LoRA adapter cache.
120    ///
121    /// Call this before a batch of related prompts to avoid cold-load latency
122    /// on the first inference.
123    pub fn warm_lora_for_prompt(&self, prompt: &str) {
124        let mut guard = self.lora_manager.lock().unwrap_or_else(|e| e.into_inner());
125        if let Some(mgr) = guard.as_mut() {
126            let (ctx, conf) = mgr.detector.analyze_text(prompt);
127            if conf >= mgr.detector.confidence_threshold {
128                let _ = mgr.switch_to(ctx);
129            }
130        }
131    }
132
133    /// Return the currently active LoRA context type, if any.
134    pub fn active_lora_context(&self) -> Option<crate::lora::ContextType> {
135        let guard = self.lora_manager.lock().unwrap_or_else(|e| e.into_inner());
136        guard
137            .as_ref()
138            .and_then(|m| m.active())
139            .map(|a| a.context_type)
140    }
141
142    /// Wire the `.q42.lex` sidecar used to populate FSM sieve masks at inference time.
143    pub fn configure_sieve_lex(&self, path: impl Into<String>) {
144        *self
145            .sieve_lex_path
146            .lock()
147            .unwrap_or_else(|e| e.into_inner()) = Some(path.into());
148    }
149
150    /// q-hash of the agent DID.
151    pub fn agent_did_hash(&self) -> u64 {
152        q_hash(&self.agent_did)
153    }
154}