Skip to main content

qualia_cli/
llm_lifecycle.rs

1//! CLI harness for native GGUF lifecycle: discover → mmap → infer → evict.
2//!
3//! Uses the in-process stack (`gguf_bridge` / `wgpu` / Phase 8 bifurcated compute),
4//! not Ollama or external daemons. Models are memory-mapped via `memmap2`; the UI
5//! RAM ceiling is tracked separately from the 42 MB SlgArena Sentinel budget.
6
7use std::path::{Path, PathBuf};
8use std::sync::mpsc::sync_channel;
9use std::sync::{Arc, Mutex, OnceLock};
10use std::thread;
11use std::time::Duration;
12
13use qualia_client_core::model_lifecycle::{
14    self, lifecycle_label, wait_for_eviction_scrub, ActiveModelRecord, VaultGgufEntry,
15};
16use qualia_client_core::system_telemetry::SystemTelemetryEvent;
17use qualia_core_db::llm_agent::{AgentBackend, AgentIntent, AgentRuntime, LocalLlmAgent};
18use qualia_core_db::modalities::logic::n3_compiler::N3OutputMode;
19use qualia_core_db::orchestrator::OrchestrationResult;
20use qualia_core_db::q_hash;
21
22static CLI_SESSION: OnceLock<Mutex<Option<CliSession>>> = OnceLock::new();
23
24struct CliSession {
25    record: ActiveModelRecord,
26    agent: LocalLlmAgent,
27    authority: Option<Arc<qualia_core_db::llm_agent::native_request::NativeProductSession>>,
28}
29
30fn session_lock() -> &'static Mutex<Option<CliSession>> {
31    CLI_SESSION.get_or_init(|| Mutex::new(None))
32}
33
34fn store_session(record: ActiveModelRecord, agent: LocalLlmAgent) {
35    *session_lock().lock().expect("cli session lock") = Some(CliSession { record, agent, authority: None });
36}
37
38/// Explicit injection by an authenticated embedding after model load. CLI
39/// prompts, environment variables and model paths are never authority evidence.
40pub fn bind_session_authority(
41    authority: Arc<qualia_core_db::llm_agent::native_request::NativeProductSession>,
42) -> Result<(), String> {
43    authority.bind().map_err(|e| e.to_string())?;
44    let mut slot = session_lock().lock().map_err(|e| e.to_string())?;
45    let session = slot.as_mut().ok_or("Load a model before binding CLI inference authority")?;
46    session.authority = Some(authority);
47    Ok(())
48}
49
50fn with_session<F, T>(f: F) -> Result<T, String>
51where
52    F: FnOnce(&CliSession) -> Result<T, String>,
53{
54    let guard = session_lock().lock().map_err(|e| e.to_string())?;
55    let session = guard.as_ref().ok_or_else(|| {
56        "No model loaded — run `qualia-cli llm load --vault-path <DIR> <MODEL>` first".to_string()
57    })?;
58    f(session)
59}
60
61fn clear_session() {
62    if let Ok(mut guard) = session_lock().lock() {
63        *guard = None;
64    }
65}
66
67/// Attach structured logging and optional 100 ms telemetry samples to stdout.
68pub fn init_log_stream(enable_telemetry: bool) {
69    let _ = env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info"))
70        .format(|buf, record| {
71            use std::io::Write;
72            let target = record.target();
73            if target.contains("qualia") || record.args().to_string().contains("LLM_LOAD") {
74                writeln!(buf, "[{}] {} — {}", record.level(), target, record.args())
75            } else {
76                writeln!(buf, "[{}] {}", record.level(), record.args())
77            }
78        })
79        .try_init();
80
81    if !enable_telemetry {
82        return;
83    }
84
85    let (tx, rx) = sync_channel::<SystemTelemetryEvent>(64);
86    qualia_client_core::system_telemetry::subscribe_system_telemetry(tx);
87    thread::Builder::new()
88        .name("qualia-cli-telemetry".into())
89        .spawn(move || {
90            for event in rx {
91                eprintln!(
92                    "[TELEMETRY] RAM {}/{} MB | VRAM {}/{} MB | LLM {} MB | KV {} MB | lifecycle={} | {}",
93                    event.ram_used_mb,
94                    event.ram_total_mb,
95                    event.vram_used_mb,
96                    event.vram_total_mb,
97                    event.llm_memory_mb,
98                    event.kv_cache_mb,
99                    event.lifecycle,
100                    event.status,
101                );
102            }
103        })
104        .ok();
105}
106
107/// CLI: .
108pub fn run_list(vault_path: &Path) -> Result<(), String> {
109    let entries = model_lifecycle::scan_vault_gguf(vault_path).map_err(|e| e.to_string())?;
110    if entries.is_empty() {
111        println!("No `.p64` / `.gguf` files under {}", vault_path.display());
112        return Ok(());
113    }
114    println!(
115        "{:<32} {:>6} {:>12}  {:>18}  {}",
116        "NAME", "KIND", "SIZE (MiB)", "PROFILE_ID", "PATH"
117    );
118    println!("{}", "-".repeat(100));
119    for VaultGgufEntry {
120        name,
121        path,
122        profile_id,
123        size_bytes,
124        container,
125    } in entries
126    {
127        let mib = size_bytes as f64 / (1024.0 * 1024.0);
128        println!(
129            "{:<32} {:>6} {:>12.1}  0x{profile_id:016x}  {path}",
130            name, container, mib,
131        );
132    }
133    Ok(())
134}
135
136/// CLI: .
137pub fn run_duplicate_audit(vault_path: &Path) -> Result<(), String> {
138    let groups = model_lifecycle::audit_vault_duplicates(vault_path).map_err(|e| e.to_string())?;
139    if groups.is_empty() {
140        println!(
141            "No byte-identical GGUF duplicates under {}",
142            vault_path.display()
143        );
144        return Ok(());
145    }
146
147    let mut reclaimable = 0u64;
148    for group in &groups {
149        reclaimable = reclaimable.saturating_add(group.reclaimable_bytes());
150        println!(
151            "\nSHA-256 {}  ({:.1} MiB each)",
152            group.sha256,
153            group.size_bytes as f64 / (1024.0 * 1024.0)
154        );
155        println!("  keep: {}", group.canonical_path);
156        for path in &group.duplicate_paths {
157            println!("  duplicate: {path}");
158        }
159    }
160    println!(
161        "\nRead-only audit: {} exact duplicate group(s), {:.1} MiB reclaimable.",
162        groups.len(),
163        reclaimable as f64 / (1024.0 * 1024.0)
164    );
165    println!("No files were copied, moved, or deleted.");
166    Ok(())
167}
168
169/// CLI: .
170pub fn run_load(vault_path: &Path, model_ref: &str) -> Result<(), String> {
171    let gguf =
172        model_lifecycle::resolve_vault_model(vault_path, model_ref).map_err(|e| e.to_string())?;
173
174    println!("Loading {} …", gguf.display());
175    qualia_client_core::system_telemetry::start_activation_telemetry("CLI load");
176
177    let record = tokio::task::block_in_place(|| {
178        tokio::runtime::Handle::current().block_on(model_lifecycle::activate_vault_gguf(&gguf))
179    })
180    .map_err(|e| {
181        qualia_client_core::system_telemetry::stop_activation_telemetry();
182        e.to_string()
183    })?;
184
185    qualia_client_core::system_telemetry::stop_activation_telemetry();
186    qualia_client_core::system_telemetry::publish_idle_telemetry();
187
188    let agent = LocalLlmAgent::with_local_backend(
189        format!("did:qualia:cli-vault:{}", record.profile_id),
190        AgentBackend::Local {
191            model_path: record.gguf_path.clone(),
192            context_window: record.context_window,
193            quantization: record.quantization.clone(),
194            vision_projector_path: record.mmproj_path.clone(),
195            modality: record.modality.clone(),
196            architecture: record.architecture.clone(),
197        },
198    );
199
200    store_session(record.clone(), agent);
201
202    let orch = model_lifecycle::task_orchestrator();
203    println!("Model ready.");
204    println!("  model_id   : {}", record.model_id);
205    println!("  profile_id : 0x{:016x}", record.profile_id);
206    println!("  path       : {}", record.gguf_path);
207    println!("  lifecycle  : {}", record.lifecycle_state);
208    println!(
209        "  resident   : {} bytes mapped (+ KV cache tracked separately)",
210        orch.resident_memory_bytes()
211    );
212    println!("  backend    : native GGUF → wgpu (DirectML when available)");
213    Ok(())
214}
215
216/// CLI: .
217pub fn run_status() -> Result<(), String> {
218    let orch = model_lifecycle::task_orchestrator();
219    let lifecycle = model_lifecycle::get_model_lifecycle_state();
220    let resident_id = orch.resident_model_id();
221    let llm_mb = model_lifecycle::get_llm_memory_bytes() / (1024 * 1024);
222    let kv_mb = model_lifecycle::get_kv_cache_used_mb();
223
224    println!("Lifecycle state : {}", lifecycle_label(lifecycle));
225    println!(
226        "Resident id     : {:?}",
227        resident_id.map(|id| format!("0x{id:016x}"))
228    );
229    println!("Resident bytes  : {}", orch.resident_memory_bytes());
230    println!("LLM memory      : {} MiB", llm_mb);
231    println!("KV cache        : {} MiB", kv_mb);
232    println!(
233        "Thermal         : {}",
234        model_lifecycle::get_thermal_state_label()
235    );
236    println!(
237        "Scrubbing       : {}",
238        orch.scrubbing_lock
239            .load(std::sync::atomic::Ordering::Acquire)
240    );
241
242    if let Ok(guard) = session_lock().lock() {
243        if let Some(session) = guard.as_ref() {
244            println!(
245                "CLI session     : {} ({})",
246                session.record.model_id, session.record.gguf_path
247            );
248        } else {
249            println!("CLI session     : none");
250        }
251    }
252    Ok(())
253}
254
255/// CLI: .
256pub fn run_eval(prompt: &str, orchestrated: bool, stream: bool) -> Result<(), String> {
257    with_session(|session| {
258        let authority = session.authority.as_ref().ok_or(
259            "CLI inference requires a native host session: configure signed admission, log in with the selected identifier, install an evidence policy, then bind_session_authority after model load"
260        )?;
261        session.agent.bind_native_governed_request(authority.bind().map_err(|e| e.to_string())?)
262            .map_err(|e| e.to_string())?;
263        if orchestrated {
264            let intent = cli_read_intent();
265            let orch = model_lifecycle::task_orchestrator();
266            let started = std::time::Instant::now();
267            match orch.orchestrate_inference(
268                &session.agent,
269                prompt,
270                "ctx:qualia-cli-eval",
271                intent,
272                None,
273            ) {
274                OrchestrationResult::Committed { text, .. } => {
275                    println!(
276                        "\n--- output ({} ms) ---\n{text}\n",
277                        started.elapsed().as_millis()
278                    );
279                }
280                OrchestrationResult::Blocked {
281                    rule_violated,
282                    reason,
283                } => {
284                    return Err(format!(
285                        "Webizen blocked inference: {reason} (rule 0x{rule_violated:016x})"
286                    ));
287                }
288                OrchestrationResult::Failed(msg) => return Err(format!("Inference failed: {msg}")),
289            }
290        } else if stream {
291            let (text, _prov, tokens, _quin) = session.agent.infer_local_model_streaming(
292                prompt,
293                "ctx:qualia-cli-eval",
294                Some(|delta: String| {
295                    print!("{delta}");
296                    let _ = std::io::Write::flush(&mut std::io::stdout());
297                }),
298            );
299            println!("\n--- tokens generated: {tokens} ---");
300            if !text.is_empty() {
301                println!("(final length {} chars)", text.len());
302            }
303        } else {
304            let output = session
305                .agent
306                .infer(prompt, "ctx:qualia-cli-eval")
307                .map_err(|e| format!("{e:?}"))?;
308            println!(
309                "\n--- output ({} ms, {} tokens) ---\n{}\n",
310                output.inference_duration_ms, output.tokens_generated, output.text
311            );
312        }
313        Ok(())
314    })
315}
316
317/// CLI: .
318pub fn run_evict(model_id_ref: &str) -> Result<(), String> {
319    let profile_id = parse_model_id_ref(model_id_ref)?;
320    println!("Evicting model 0x{profile_id:016x} …");
321    model_lifecycle::unload_active_model(Some(profile_id));
322    if !wait_for_eviction_scrub(Duration::from_secs(10)) {
323        eprintln!("Warning: scrub did not finish within 10 s");
324    }
325    clear_session();
326    qualia_client_core::system_telemetry::publish_idle_telemetry();
327    println!("Eviction complete. Lifecycle → Discovered.");
328    run_status()
329}
330
331fn parse_model_id_ref(raw: &str) -> Result<u64, String> {
332    let trimmed = raw.trim();
333    if let Some(hex) = trimmed
334        .strip_prefix("0x")
335        .or_else(|| trimmed.strip_prefix("0X"))
336    {
337        u64::from_str_radix(hex, 16).map_err(|e| format!("Invalid hex profile id: {e}"))
338    } else if let Ok(id) = trimmed.parse::<u64>() {
339        Ok(id)
340    } else if let Ok(guard) = session_lock().lock() {
341        if let Some(session) = guard.as_ref() {
342            if session.record.model_id == trimmed {
343                return Ok(session.record.profile_id);
344            }
345        }
346        drop(guard);
347        Err(format!(
348            "Unknown model id `{trimmed}` — use 0x{{16 hex}} profile id or loaded model stem"
349        ))
350    } else {
351        Err("Session lock poisoned".to_string())
352    }
353}
354
355fn cli_read_intent() -> AgentIntent {
356    AgentIntent {
357        intent_predicate: q_hash("llm:ReadGraph"),
358        requested_graph_scope: vec![q_hash("ctx:qualia-cli-eval")],
359        context_namespaces: vec![],
360        requires_network: false,
361        ilp_offer_micro_cents: 0,
362        principal_did_hash: q_hash("did:qualia:cli-operator"),
363        mcp_intent_frame_hash: q_hash("purpose:CliEval"),
364        output_mode: N3OutputMode::FreeText,
365        clearance_ceiling: 0,
366        max_sentinel_depth: 32,
367        active_profile: None,
368    }
369}
370
371/// Default vault path when none is supplied (Windows-friendly).
372pub fn default_vault_path() -> PathBuf {
373    if let Ok(dir) = std::env::var("QUALIA_LLM_VAULT").or_else(|_| std::env::var("QUALIA_MODEL_PATHS")) {
374        let trimmed = dir.trim();
375        if !trimmed.is_empty() {
376            return PathBuf::from(trimmed);
377        }
378    }
379    for candidate in ["C:/LLM_files", "C:/LLM_Models", "C:/llmmodels"] {
380        let canonical = PathBuf::from(candidate);
381        if canonical.is_dir() {
382            return canonical;
383        }
384    }
385    let canonical = PathBuf::from("C:/LLM_files");
386    if canonical.is_dir() {
387        return canonical;
388    }
389    PathBuf::from("C:/llmmodels")
390}