1use std::path::{Path, PathBuf};
4use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
5use std::sync::{Arc, OnceLock};
6
7use qualia_core_db::{
8 gguf_sharder::GGufSharder,
9 llm_agent::{AgentBackend, LocalLlmAgent},
10 orchestrator::{ModelLifecycle, NullThermalGovernor, TaskOrchestrator},
11 q_hash,
12 resource_catalog::{LLMResource, ResourceCatalog},
13 wal::WriteAheadLog,
14};
15use serde::{Deserialize, Serialize};
16use sha2::{Digest, Sha256};
17
18#[derive(Debug)]
19pub enum ModelError {
20 NotFound(String),
21 NoDownloadUrl(String),
22 Download(String),
23 Shard(String),
24 Wal(String),
25 Activate(String),
26 Io(std::io::Error),
27 Json(serde_json::Error),
28}
29
30impl std::fmt::Display for ModelError {
31 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
32 match self {
33 ModelError::NotFound(id) => write!(f, "LLM not found in catalog: {id}"),
34 ModelError::NoDownloadUrl(id) => write!(f, "No download URL for: {id}"),
35 ModelError::Download(e) => write!(f, "Download failed: {e}"),
36 ModelError::Shard(e) => write!(f, "GGUF shard map failed: {e}"),
37 ModelError::Wal(e) => write!(f, "WAL write failed: {e}"),
38 ModelError::Activate(e) => write!(f, "Model activation failed: {e}"),
39 ModelError::Io(e) => write!(f, "IO error: {e}"),
40 ModelError::Json(e) => write!(f, "JSON error: {e}"),
41 }
42 }
43}
44
45impl From<std::io::Error> for ModelError {
46 fn from(e: std::io::Error) -> Self {
47 ModelError::Io(e)
48 }
49}
50
51impl From<serde_json::Error> for ModelError {
52 fn from(e: serde_json::Error) -> Self {
53 ModelError::Json(e)
54 }
55}
56
57#[derive(Debug, Clone, Serialize, Deserialize)]
58pub struct ActiveModelRecord {
59 pub model_id: String,
60 pub gguf_path: String,
61 pub profile_id: u64,
62 pub quantization: String,
63 pub lifecycle_state: String,
64 #[serde(default)]
65 pub modality: String,
66 #[serde(default)]
67 pub architecture: Option<String>,
68 #[serde(default)]
69 pub mmproj_path: Option<String>,
70 #[serde(default)]
71 pub context_window: u32,
72}
73
74#[derive(Debug, Clone, Serialize)]
75pub struct ModelInstallResult {
76 pub model_id: String,
77 pub gguf_path: String,
78 pub profile_id: u64,
79 pub pointer_quin_count: usize,
80 pub vision_pointer_quin_count: usize,
81 pub lifecycle_state: String,
82 pub wal_path: String,
83 pub modality: String,
84 pub mmproj_path: Option<String>,
85}
86
87#[derive(Debug, Clone, Serialize)]
88pub struct ModelStatus {
89 pub active: Option<ActiveModelRecord>,
90 pub lifecycle_state: String,
91 pub profile_id: Option<u64>,
92}
93
94#[derive(Debug, Clone, Serialize, Deserialize)]
95pub struct InstallManifest {
96 pub model_id: String,
97 pub gguf_path: String,
98 pub profile_id: u64,
99 pub quantization: String,
100 pub pointer_quin_count: usize,
101 pub vision_pointer_quin_count: usize,
102 pub installed_at: u64,
103 pub wal_path: String,
104 pub modality: String,
105 pub architecture: Option<String>,
106 pub mmproj_path: Option<String>,
107 pub context_window: u32,
108}
109
110fn orchestrator() -> Arc<TaskOrchestrator> {
111 task_orchestrator()
112}
113
114pub fn task_orchestrator() -> Arc<TaskOrchestrator> {
116 static ORCH: OnceLock<Arc<TaskOrchestrator>> = OnceLock::new();
117 ORCH.get_or_init(|| Arc::new(TaskOrchestrator::new(Box::new(NullThermalGovernor))))
118 .clone()
119}
120
121pub const MEMORY_FLOOR_MB: u32 = 512;
123
124static LLM_MEMORY_BYTES: AtomicU64 = AtomicU64::new(0);
125static KV_CACHE_USED_MB: AtomicU32 = AtomicU32::new(0);
126static LAST_DECODE_TOK_S_MILLI: AtomicU32 = AtomicU32::new(0);
128static LAST_DECODE_TOK_S_AT_SECS: AtomicU64 = AtomicU64::new(0);
130
131pub fn record_llm_memory_bytes(bytes: u64) {
133 LLM_MEMORY_BYTES.store(bytes, Ordering::Relaxed);
134}
135
136pub fn record_llm_memory_sample(bytes: u64) {
138 if bytes == 0 {
139 return;
140 }
141 let mut current = LLM_MEMORY_BYTES.load(Ordering::Relaxed);
142 while bytes > current {
143 match LLM_MEMORY_BYTES.compare_exchange(
144 current,
145 bytes,
146 Ordering::Relaxed,
147 Ordering::Relaxed,
148 ) {
149 Ok(_) => return,
150 Err(observed) => current = observed,
151 }
152 }
153}
154
155pub fn get_llm_memory_bytes() -> u64 {
157 LLM_MEMORY_BYTES.load(Ordering::Relaxed)
158}
159
160pub fn record_kv_cache_used_mb(megabytes: u32) {
162 KV_CACHE_USED_MB.store(megabytes, Ordering::Relaxed);
163}
164
165pub fn get_kv_cache_used_mb() -> u32 {
167 KV_CACHE_USED_MB.load(Ordering::Relaxed)
168}
169
170pub fn record_last_decode_tok_s(tokens: u32, duration_ms: u64) {
174 if tokens == 0 || duration_ms == 0 {
175 return;
176 }
177 let tok_s = (tokens as f64) / (duration_ms as f64 / 1000.0);
178 if !tok_s.is_finite() || tok_s <= 0.0 {
179 return;
180 }
181 let milli = (tok_s * 1000.0).round().clamp(0.0, u32::MAX as f64) as u32;
182 LAST_DECODE_TOK_S_MILLI.store(milli, Ordering::Relaxed);
183 let now = std::time::SystemTime::now()
184 .duration_since(std::time::UNIX_EPOCH)
185 .map(|d| d.as_secs())
186 .unwrap_or(0);
187 LAST_DECODE_TOK_S_AT_SECS.store(now, Ordering::Relaxed);
188}
189
190pub fn get_last_decode_tok_s() -> Option<f64> {
192 let milli = LAST_DECODE_TOK_S_MILLI.load(Ordering::Relaxed);
193 if milli == 0 {
194 None
195 } else {
196 Some(milli as f64 / 1000.0)
197 }
198}
199
200pub fn get_last_decode_tok_s_at_unix() -> u64 {
202 LAST_DECODE_TOK_S_AT_SECS.load(Ordering::Relaxed)
203}
204
205pub fn get_thermal_state_label() -> &'static str {
207 orchestrator().thermal_state_label()
208}
209
210pub fn models_dir(storage_root: &Path) -> PathBuf {
212 storage_root.join("Models")
213}
214
215pub fn lifecycle_label(state: ModelLifecycle) -> &'static str {
217 match state {
218 ModelLifecycle::Discovered => "Discovered",
219 ModelLifecycle::MappedToDisk => "MappedToDisk",
220 ModelLifecycle::StreamingVRAM => "StreamingVRAM",
221 ModelLifecycle::Active => "Active",
222 ModelLifecycle::Scrubbing => "Scrubbing",
223 }
224}
225
226fn probe_and_activate_model(
227 agent: &LocalLlmAgent,
228 profile_id: u64,
229 model_label: &str,
230 gguf_path: &str,
231) -> Result<(), ModelError> {
232 let orch = orchestrator();
233 if let Some(resident) = orch.resident_model_id() {
234 if resident != profile_id {
235 log::info!(
236 "LLM_LOAD|unload-start|0.01|Evicting resident model 0x{resident:016x} before loading {}",
237 model_label
238 );
239 orch.evict_model(resident);
240 let wait_started = std::time::Instant::now();
241 while orch.scrubbing_lock.load(Ordering::Acquire) {
242 if wait_started.elapsed() > std::time::Duration::from_secs(5) {
243 log::error!("LLM_LOAD|failed|1.00|Timed out waiting for prior model eviction");
244 return Err(ModelError::Activate(
245 "Timed out waiting for prior model eviction".to_string(),
246 ));
247 }
248 std::thread::sleep(std::time::Duration::from_millis(5));
249 }
250 record_llm_memory_bytes(0);
251 record_kv_cache_used_mb(0);
252 log::info!("LLM_LOAD|unload-done|0.03|Previous resident model scrubbed from memory");
253 }
254 }
255 let mut sys = sysinfo::System::new_all();
256 sys.refresh_memory();
257 let ram_total_gib = sys.total_memory() as f64 / 1024.0 / 1024.0 / 1024.0;
258 let ram_used_gib = sys.used_memory() as f64 / 1024.0 / 1024.0 / 1024.0;
259 let ram_free_gib = (ram_total_gib - ram_used_gib).max(0.0);
260 {
261 let mut state = orch.current_model_state.lock().unwrap();
262 *state = ModelLifecycle::MappedToDisk;
263 *state = ModelLifecycle::StreamingVRAM;
264 }
265 log::info!("LLM_LOAD|prepare|0.02|Preparing model {}", model_label);
266 log::info!(
267 "LLM_LOAD|ram-check|0.04|System RAM {:.1}/{:.1} GiB used; {:.1} GiB available",
268 ram_used_gib,
269 ram_total_gib,
270 ram_free_gib
271 );
272 match qualia_core_db::resident_model::mount_resident_gguf(
273 profile_id,
274 gguf_path,
275 orch.mlock_enabled
276 .load(std::sync::atomic::Ordering::Relaxed),
277 ) {
278 Ok(report) => {
279 let kv_cache_mb = (report.kv_cache_bytes / (1024 * 1024)).min(u32::MAX as u64) as u32;
280 record_llm_memory_bytes(report.mapped_bytes);
281 record_kv_cache_used_mb(kv_cache_mb);
282 if let Err(err) = orch.load_model(agent, profile_id) {
283 log::error!("LLM_LOAD|failed|1.00|Activation failed: {}", err);
284 return Err(ModelError::Activate(err.to_string()));
285 }
286 orch.register_resident_model(profile_id, report.mapped_bytes + report.kv_cache_bytes);
287 log::info!(
288 "LLM_LOAD|placement|0.96|Model mapped in system RAM ({:.2} GiB) and KV cache reserved in VRAM/system memory ({} MiB)",
289 report.mapped_bytes as f64 / (1024.0 * 1024.0 * 1024.0),
290 kv_cache_mb
291 );
292 log::info!(
293 "LLM_LOAD|active|1.00|Model ready (mapped {:.2} GiB, kv {} MiB, backend {})",
294 report.mapped_bytes as f64 / (1024.0 * 1024.0 * 1024.0),
295 kv_cache_mb,
296 if report.directml_enabled {
297 "DirectML+wgpu"
298 } else {
299 "wgpu"
300 }
301 );
302 }
303 Err(err) => {
304 record_llm_memory_bytes(0);
305 record_kv_cache_used_mb(0);
306 let mut state = orch.current_model_state.lock().unwrap();
307 *state = ModelLifecycle::MappedToDisk;
308 log::error!("LLM_LOAD|failed|1.00|Activation failed: {}", err);
309 return Err(ModelError::Activate(err));
310 }
311 }
312 Ok(())
313}
314
315pub fn unload_active_model(profile_id: Option<u64>) {
317 let orch = orchestrator();
318 let resident = profile_id.or_else(|| orch.resident_model_id());
319 if let Some(model_id) = resident {
320 log::info!("LLM_LOAD|unload-start|0.00|Unloading resident model 0x{model_id:016x}");
321 orch.evict_model(model_id);
322 let wait_started = std::time::Instant::now();
323 while orch.scrubbing_lock.load(Ordering::Acquire) {
324 if wait_started.elapsed() > std::time::Duration::from_secs(5) {
325 log::warn!("LLM_LOAD|failed|1.00|Timed out waiting for model scrub");
326 break;
327 }
328 std::thread::sleep(std::time::Duration::from_millis(5));
329 }
330 log::info!("LLM_LOAD|unload-done|1.00|Model memory scrub complete");
331 }
332 record_llm_memory_bytes(0);
333 record_kv_cache_used_mb(0);
334}
335
336fn unix_now() -> u64 {
337 std::time::SystemTime::now()
338 .duration_since(std::time::UNIX_EPOCH)
339 .unwrap_or_default()
340 .as_secs()
341}
342
343fn llm_filename(model: &LLMResource) -> String {
344 model
345 .download
346 .local_filename()
347 .unwrap_or_else(|| format!("{}.gguf", model.id))
348}
349
350fn install_manifest_path(models_dir: &Path, model_id: &str) -> PathBuf {
351 models_dir.join(format!("{model_id}.install.json"))
352}
353
354fn projector_filename(model: &LLMResource) -> Option<String> {
355 model.vision_projector.as_ref().and_then(|d| {
356 d.local_filename().or_else(|| {
357 d.resolved_url()
358 .and_then(|u| u.rsplit('/').next().map(|s| s.to_string()))
359 })
360 })
361}
362
363fn write_install_manifest(
364 models_dir: &Path,
365 model: &LLMResource,
366 gguf_path: &Path,
367 mmproj_path: Option<&Path>,
368 profile_id: u64,
369 pointer_quin_count: usize,
370 vision_pointer_quin_count: usize,
371 wal_path: &Path,
372) -> Result<(), ModelError> {
373 let modality = if model.is_multimodal() {
374 "multimodal".to_string()
375 } else {
376 "text".to_string()
377 };
378 let manifest = InstallManifest {
379 model_id: model.id.clone(),
380 gguf_path: gguf_path.to_string_lossy().into_owned(),
381 profile_id,
382 quantization: model
383 .quantization
384 .clone()
385 .unwrap_or_else(|| "Q4_K_M".to_string()),
386 pointer_quin_count,
387 vision_pointer_quin_count,
388 installed_at: unix_now(),
389 wal_path: wal_path.to_string_lossy().into_owned(),
390 modality: modality.clone(),
391 architecture: model.architecture.clone(),
392 mmproj_path: mmproj_path.map(|p| p.to_string_lossy().into_owned()),
393 context_window: model.effective_context_window(),
394 };
395 let json = serde_json::to_string_pretty(&manifest)?;
396 std::fs::write(install_manifest_path(models_dir, &model.id), json)?;
397 Ok(())
398}
399
400pub fn finalize_llm_install(
402 model: &LLMResource,
403 gguf_path: &Path,
404 mmproj_path: Option<&Path>,
405 storage_root: &Path,
406) -> Result<ModelInstallResult, ModelError> {
407 let models = models_dir(storage_root);
408 std::fs::create_dir_all(&models)?;
409
410 if !gguf_path.is_file() {
411 return Err(ModelError::Io(std::io::Error::new(
412 std::io::ErrorKind::NotFound,
413 format!("GGUF not found: {}", gguf_path.display()),
414 )));
415 }
416
417 if model.is_multimodal() && mmproj_path.is_none() {
418 return Err(ModelError::Shard(
419 "Multimodal model requires vision projector (mmproj) GGUF".to_string(),
420 ));
421 }
422
423 let path_str = gguf_path.to_string_lossy().into_owned();
424 let sharder = GGufSharder::new(path_str.clone());
425 let mut pointer_quins = sharder.generate_bidx_pointer_map();
426 let mut vision_pointer_quin_count = 0usize;
427
428 if let Some(mmproj) = mmproj_path {
429 if !mmproj.is_file() {
430 return Err(ModelError::Io(std::io::Error::new(
431 std::io::ErrorKind::NotFound,
432 format!("mmproj not found: {}", mmproj.display()),
433 )));
434 }
435 let mmproj_str = mmproj.to_string_lossy().into_owned();
436 let vision_sharder = GGufSharder::new(mmproj_str);
437 let vision_quins = vision_sharder.generate_bidx_pointer_map();
438 vision_pointer_quin_count = vision_quins.len();
439 pointer_quins.extend(vision_quins);
440 }
441
442 let wal_path = models.join("models.wal");
443 let mut wal = WriteAheadLog::open(&wal_path)
444 .map_err(|e| ModelError::Wal(format!("Cannot open {}: {}", wal_path.display(), e)))?;
445
446 let timestamp = unix_now();
447 let prov = model.provenance_quin(timestamp, &path_str);
448 wal.append_mutation(&prov)
449 .map_err(|e| ModelError::Wal(e.to_string()))?;
450
451 if let Some(src_quin) = model.source_url_quin() {
452 wal.append_mutation(&src_quin)
453 .map_err(|e| ModelError::Wal(e.to_string()))?;
454 }
455
456 for q in &pointer_quins {
457 wal.append_mutation(q)
458 .map_err(|e| ModelError::Wal(e.to_string()))?;
459 }
460
461 for q in &model.to_quins() {
462 wal.append_mutation(q)
463 .map_err(|e| ModelError::Wal(e.to_string()))?;
464 }
465
466 let mmproj_str = mmproj_path.map(|p| p.to_string_lossy().into_owned());
467 let profile = model.to_capability_profile_with_projector(&path_str, mmproj_str.as_deref());
468 write_install_manifest(
469 &models,
470 model,
471 gguf_path,
472 mmproj_path,
473 profile.profile_id,
474 pointer_quins
475 .len()
476 .saturating_sub(vision_pointer_quin_count),
477 vision_pointer_quin_count,
478 &wal_path,
479 )?;
480
481 {
482 let orch = orchestrator();
483 let mut state = orch.current_model_state.lock().unwrap();
484 *state = ModelLifecycle::MappedToDisk;
485 }
486
487 let modality = if model.is_multimodal() {
488 "multimodal".to_string()
489 } else {
490 "text".to_string()
491 };
492
493 Ok(ModelInstallResult {
494 model_id: model.id.clone(),
495 gguf_path: path_str,
496 profile_id: profile.profile_id,
497 pointer_quin_count: pointer_quins
498 .len()
499 .saturating_sub(vision_pointer_quin_count),
500 vision_pointer_quin_count,
501 lifecycle_state: lifecycle_label(ModelLifecycle::MappedToDisk).to_string(),
502 wal_path: wal_path.to_string_lossy().into_owned(),
503 modality,
504 mmproj_path: mmproj_str,
505 })
506}
507
508pub async fn install_catalog_llm(
510 catalog: &ResourceCatalog,
511 id: &str,
512 storage_root: &Path,
513) -> Result<ModelInstallResult, ModelError> {
514 let model = catalog
515 .find_llm(id)
516 .ok_or_else(|| ModelError::NotFound(id.to_string()))?;
517
518 let url = model
519 .download
520 .resolved_url()
521 .ok_or_else(|| ModelError::NoDownloadUrl(id.to_string()))?;
522
523 let models = models_dir(storage_root);
524 std::fs::create_dir_all(&models)?;
525
526 let filename = llm_filename(model);
527 let local_path = models.join(&filename);
528
529 crate::resource_import::stream_download(&url, &local_path)
530 .await
531 .map_err(ModelError::Download)?;
532
533 let mmproj_path = if let (Some(ref vp), Some(vp_url)) = (
534 model.vision_projector.as_ref(),
535 model
536 .vision_projector
537 .as_ref()
538 .and_then(|d| d.resolved_url()),
539 ) {
540 let vp_name = projector_filename(model).unwrap_or_else(|| "mmproj.gguf".to_string());
541 let vp_path = models.join(&vp_name);
542 crate::resource_import::stream_download(&vp_url, &vp_path)
543 .await
544 .map_err(ModelError::Download)?;
545 let _ = vp;
546 Some(vp_path)
547 } else {
548 None
549 };
550
551 finalize_llm_install(model, &local_path, mmproj_path.as_deref(), storage_root)
552}
553
554pub fn load_install_manifest(storage_root: &Path, model_id: &str) -> Option<InstallManifest> {
556 let path = install_manifest_path(&models_dir(storage_root), model_id);
557 let text = std::fs::read_to_string(path).ok()?;
558 serde_json::from_str(&text).ok()
559}
560
561fn sanitize_local_model_id(stem: &str) -> String {
562 let cleaned: String = stem
563 .chars()
564 .map(|c| {
565 if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
566 c
567 } else {
568 '_'
569 }
570 })
571 .collect();
572 if cleaned.is_empty() {
573 "local-model".to_string()
574 } else {
575 cleaned
576 }
577}
578
579#[derive(Debug, Clone, Serialize)]
583pub struct VaultGgufEntry {
584 pub name: String,
585 pub path: String,
586 pub profile_id: u64,
587 pub size_bytes: u64,
588 pub container: String,
590}
591
592#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
597pub struct VaultDuplicateGroup {
598 pub sha256: String,
599 pub size_bytes: u64,
600 pub canonical_path: String,
601 pub duplicate_paths: Vec<String>,
602}
603
604impl VaultDuplicateGroup {
605 pub fn reclaimable_bytes(&self) -> u64 {
607 self.size_bytes
608 .saturating_mul(self.duplicate_paths.len() as u64)
609 }
610}
611
612pub fn scan_vault_gguf(vault_dir: &Path) -> Result<Vec<VaultGgufEntry>, std::io::Error> {
618 if !vault_dir.is_dir() {
619 return Err(std::io::Error::new(
620 std::io::ErrorKind::NotFound,
621 format!("Vault directory not found: {}", vault_dir.display()),
622 ));
623 }
624 let mut raw = Vec::new();
625 collect_vault_models(vault_dir, &mut raw)?;
626 let p64_stems: std::collections::HashSet<String> = raw
628 .iter()
629 .filter(|e| e.container == "p64")
630 .map(|e| vault_stem_key(&e.path))
631 .collect();
632 let mut out: Vec<VaultGgufEntry> = raw
633 .into_iter()
634 .filter(|e| e.container == "p64" || !p64_stems.contains(&vault_stem_key(&e.path)))
635 .collect();
636 out.sort_by(|a, b| a.name.cmp(&b.name));
637 Ok(out)
638}
639
640fn vault_stem_key(path: &str) -> String {
642 Path::new(path)
643 .file_stem()
644 .and_then(|s| s.to_str())
645 .unwrap_or("")
646 .to_string()
647}
648
649pub fn audit_vault_duplicates(
655 vault_dir: &Path,
656) -> Result<Vec<VaultDuplicateGroup>, std::io::Error> {
657 use std::collections::BTreeMap;
658 use std::io::Read;
659
660 let entries = scan_vault_gguf(vault_dir)?;
661 let mut by_size: BTreeMap<u64, Vec<&VaultGgufEntry>> = BTreeMap::new();
662 for entry in &entries {
663 by_size.entry(entry.size_bytes).or_default().push(entry);
664 }
665
666 let mut groups = Vec::new();
667 for (size_bytes, candidates) in by_size {
668 if candidates.len() < 2 {
669 continue;
670 }
671 let mut by_digest: BTreeMap<String, Vec<String>> = BTreeMap::new();
672 for candidate in candidates {
673 let mut file = std::fs::File::open(&candidate.path)?;
674 let mut hasher = Sha256::new();
675 let mut buffer = [0u8; 64 * 1024];
678 loop {
679 let read = file.read(&mut buffer)?;
680 if read == 0 {
681 break;
682 }
683 hasher.update(&buffer[..read]);
684 }
685 let digest = hasher.finalize();
686 let mut digest_hex = String::with_capacity(digest.len() * 2);
687 for byte in digest {
688 use std::fmt::Write;
689 let _ = write!(digest_hex, "{byte:02x}");
690 }
691 by_digest
692 .entry(digest_hex)
693 .or_default()
694 .push(candidate.path.clone());
695 }
696
697 for (sha256, mut paths) in by_digest {
698 if paths.len() < 2 {
699 continue;
700 }
701 paths.sort_by(|a, b| {
702 let a_depth = Path::new(a).components().count();
703 let b_depth = Path::new(b).components().count();
704 a_depth.cmp(&b_depth).then_with(|| a.cmp(b))
705 });
706 let canonical_path = paths.remove(0);
707 groups.push(VaultDuplicateGroup {
708 sha256,
709 size_bytes,
710 canonical_path,
711 duplicate_paths: paths,
712 });
713 }
714 }
715 groups.sort_by(|a, b| a.canonical_path.cmp(&b.canonical_path));
716 Ok(groups)
717}
718
719fn collect_vault_models(dir: &Path, out: &mut Vec<VaultGgufEntry>) -> Result<(), std::io::Error> {
720 for entry in std::fs::read_dir(dir)? {
721 let entry = entry?;
722 let path = entry.path();
723 if path.is_dir() {
724 collect_vault_models(&path, out)?;
725 continue;
726 }
727 let ext = path
728 .extension()
729 .and_then(|e| e.to_str())
730 .unwrap_or("")
731 .to_ascii_lowercase();
732 let container = match ext.as_str() {
733 "p64" => "p64",
734 "gguf" => "gguf",
735 _ => continue,
736 };
737 let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("model");
738 let model_id = sanitize_local_model_id(stem);
739 let size_bytes = entry.metadata()?.len();
740 out.push(VaultGgufEntry {
741 name: path
742 .file_name()
743 .map(|n| n.to_string_lossy().into_owned())
744 .unwrap_or_else(|| model_id.clone()),
745 path: path.to_string_lossy().into_owned(),
746 profile_id: q_hash(&format!("profile:local:{model_id}")),
747 size_bytes,
748 container: container.into(),
749 });
750 }
751 Ok(())
752}
753
754pub fn resolve_vault_model(vault_dir: &Path, model_ref: &str) -> Result<PathBuf, ModelError> {
758 let direct = PathBuf::from(model_ref);
759 if direct.is_file() {
760 if let Some(p64) = prefer_p64_sibling(&direct) {
762 return Ok(p64);
763 }
764 return Ok(direct);
765 }
766 let in_vault = vault_dir.join(model_ref);
767 if in_vault.is_file() {
768 if let Some(p64) = prefer_p64_sibling(&in_vault) {
769 return Ok(p64);
770 }
771 return Ok(in_vault);
772 }
773 if !model_ref.ends_with(".p64") && !model_ref.ends_with(".gguf") {
775 let with_p64 = vault_dir.join(format!("{model_ref}.p64"));
776 if with_p64.is_file() {
777 return Ok(with_p64);
778 }
779 let with_gguf = vault_dir.join(format!("{model_ref}.gguf"));
780 if with_gguf.is_file() {
781 if let Some(p64) = prefer_p64_sibling(&with_gguf) {
782 return Ok(p64);
783 }
784 return Ok(with_gguf);
785 }
786 }
787 for entry in scan_vault_gguf(vault_dir).map_err(ModelError::Io)? {
788 let stem = PathBuf::from(&entry.path)
789 .file_stem()
790 .and_then(|s| s.to_str())
791 .unwrap_or("")
792 .to_string();
793 if entry.name == model_ref
794 || stem == model_ref
795 || format!("0x{:016x}", entry.profile_id) == model_ref.to_lowercase()
796 {
797 return Ok(PathBuf::from(entry.path));
798 }
799 }
800 Err(ModelError::NotFound(format!(
801 "No p64/GGUF matching `{model_ref}` under {}",
802 vault_dir.display()
803 )))
804}
805
806fn prefer_p64_sibling(path: &Path) -> Option<PathBuf> {
808 let is_gguf = path
809 .extension()
810 .and_then(|e| e.to_str())
811 .map(|e| e.eq_ignore_ascii_case("gguf"))
812 .unwrap_or(false);
813 if !is_gguf {
814 return None;
815 }
816 let p64 = path.with_extension("p64");
817 if p64.is_file() {
818 Some(p64)
819 } else {
820 None
821 }
822}
823
824pub async fn activate_vault_gguf(gguf_path: &Path) -> Result<ActiveModelRecord, ModelError> {
826 let path = prefer_p64_sibling(gguf_path).unwrap_or_else(|| gguf_path.to_path_buf());
827 if !path.is_file() {
828 return Err(ModelError::Io(std::io::Error::new(
829 std::io::ErrorKind::NotFound,
830 format!("Model not found: {}", path.display()),
831 )));
832 }
833 let stem = path
834 .file_stem()
835 .and_then(|s| s.to_str())
836 .unwrap_or("local-model");
837 let model_id = sanitize_local_model_id(stem);
838 let path_str = path.to_string_lossy().into_owned();
839 let profile_id = q_hash(&format!("profile:local:{model_id}"));
840 let quant = if path
841 .extension()
842 .and_then(|e| e.to_str())
843 .map(|e| e.eq_ignore_ascii_case("p64"))
844 .unwrap_or(false)
845 {
846 "p64"
847 } else {
848 "vault"
849 };
850
851 let agent = LocalLlmAgent::with_local_backend(
852 format!("did:qualia:cli-vault:{profile_id}"),
853 AgentBackend::Local {
854 model_path: path_str.clone(),
855 context_window: 4096,
856 quantization: quant.to_string(),
857 vision_projector_path: None,
858 modality: "text".to_string(),
859 architecture: None,
860 },
861 );
862 probe_and_activate_model(&agent, profile_id, &model_id, &path_str)?;
863
864 let lifecycle = *orchestrator().current_model_state.lock().unwrap();
865 Ok(ActiveModelRecord {
866 model_id,
867 gguf_path: path_str,
868 profile_id,
869 quantization: quant.to_string(),
870 lifecycle_state: lifecycle_label(lifecycle).to_string(),
871 modality: "text".to_string(),
872 architecture: None,
873 mmproj_path: None,
874 context_window: 4096,
875 })
876}
877
878pub fn wait_for_eviction_scrub(timeout: std::time::Duration) -> bool {
880 let orch = orchestrator();
881 let started = std::time::Instant::now();
882 while orch.scrubbing_lock.load(Ordering::Acquire) {
883 if started.elapsed() > timeout {
884 return false;
885 }
886 std::thread::sleep(std::time::Duration::from_millis(5));
887 }
888 true
889}
890
891pub fn finalize_local_gguf(
896 gguf_path: &Path,
897 storage_root: &Path,
898) -> Result<ActiveModelRecord, ModelError> {
899 if !gguf_path.is_file() {
900 return Err(ModelError::Io(std::io::Error::new(
901 std::io::ErrorKind::NotFound,
902 format!("GGUF not found: {}", gguf_path.display()),
903 )));
904 }
905
906 let models = models_dir(storage_root);
907 std::fs::create_dir_all(&models)?;
908
909 let stem = gguf_path
910 .file_stem()
911 .and_then(|s| s.to_str())
912 .unwrap_or("local-model");
913 let model_id = sanitize_local_model_id(stem);
914 let path_str = gguf_path.to_string_lossy().into_owned();
915 let profile_id = q_hash(&format!("profile:local:{model_id}"));
916
917 let sharder = GGufSharder::new(path_str.clone());
918 let pointer_quins = sharder.generate_bidx_pointer_map();
919 let pointer_quin_count = pointer_quins.len();
920
921 let wal_path = models.join("models.wal");
922 let mut wal = WriteAheadLog::open(&wal_path)
923 .map_err(|e| ModelError::Wal(format!("Cannot open {}: {}", wal_path.display(), e)))?;
924
925 let subject = q_hash(&format!("local-gguf:{model_id}"));
926 let predicate = q_hash("prov:wasDerivedFrom");
927 let object = q_hash(&path_str);
928 let context = q_hash("ctx:local-gguf");
929 let prov = qualia_core_db::NQuin {
930 subject,
931 predicate,
932 object,
933 context,
934 metadata: unix_now(),
935 parity: subject ^ predicate ^ object ^ context,
936 };
937 wal.append_mutation(&prov)
938 .map_err(|e| ModelError::Wal(e.to_string()))?;
939
940 for quin in pointer_quins {
941 wal.append_mutation(&quin)
942 .map_err(|e| ModelError::Wal(e.to_string()))?;
943 }
944
945 let manifest = InstallManifest {
946 model_id: model_id.clone(),
947 gguf_path: path_str.clone(),
948 profile_id,
949 quantization: "local".to_string(),
950 pointer_quin_count,
951 vision_pointer_quin_count: 0,
952 installed_at: unix_now(),
953 wal_path: wal_path.to_string_lossy().into_owned(),
954 modality: "text".to_string(),
955 architecture: None,
956 mmproj_path: None,
957 context_window: 4096,
958 };
959 let json = serde_json::to_string_pretty(&manifest)?;
960 std::fs::write(install_manifest_path(&models, &model_id), json)?;
961
962 let agent = LocalLlmAgent::with_local_backend(
963 format!("did:qualia:local-gguf:{profile_id}"),
964 AgentBackend::Local {
965 model_path: path_str.clone(),
966 context_window: 4096,
967 quantization: "local".to_string(),
968 vision_projector_path: None,
969 modality: "text".to_string(),
970 architecture: None,
971 },
972 );
973 probe_and_activate_model(&agent, profile_id, &model_id, &path_str)?;
974
975 let lifecycle = *orchestrator().current_model_state.lock().unwrap();
976 Ok(ActiveModelRecord {
977 model_id,
978 gguf_path: path_str,
979 profile_id,
980 quantization: "local".to_string(),
981 lifecycle_state: lifecycle_label(lifecycle).to_string(),
982 modality: "text".to_string(),
983 architecture: None,
984 mmproj_path: None,
985 context_window: 4096,
986 })
987}
988
989pub fn activate_model_for_id(
991 model_id: &str,
992 storage_root: &Path,
993) -> Result<ActiveModelRecord, ModelError> {
994 let manifest = load_install_manifest(storage_root, model_id).ok_or_else(|| {
995 ModelError::Activate(format!(
996 "No install manifest for `{model_id}` — download the model in LLM Hub first"
997 ))
998 })?;
999
1000 if !Path::new(&manifest.gguf_path).is_file() {
1001 return Err(ModelError::Activate(format!(
1002 "GGUF missing at {}",
1003 manifest.gguf_path
1004 )));
1005 }
1006
1007 if manifest.modality == "multimodal" {
1008 let mmproj = manifest.mmproj_path.as_deref().ok_or_else(|| {
1009 ModelError::Activate("Multimodal manifest missing mmproj_path".to_string())
1010 })?;
1011 if !Path::new(mmproj).is_file() {
1012 return Err(ModelError::Activate(format!(
1013 "Vision projector missing at {mmproj}"
1014 )));
1015 }
1016 }
1017
1018 let agent = LocalLlmAgent::with_local_backend(
1019 format!("did:qualia:profile:{}", manifest.profile_id),
1020 AgentBackend::Local {
1021 model_path: manifest.gguf_path.clone(),
1022 context_window: manifest.context_window,
1023 quantization: manifest.quantization.clone(),
1024 vision_projector_path: manifest.mmproj_path.clone(),
1025 modality: manifest.modality.clone(),
1026 architecture: manifest.architecture.clone(),
1027 },
1028 );
1029 probe_and_activate_model(
1030 &agent,
1031 manifest.profile_id,
1032 &manifest.model_id,
1033 &manifest.gguf_path,
1034 )?;
1035
1036 let lifecycle = *orchestrator().current_model_state.lock().unwrap();
1037 let record = ActiveModelRecord {
1038 model_id: manifest.model_id,
1039 gguf_path: manifest.gguf_path,
1040 profile_id: manifest.profile_id,
1041 quantization: manifest.quantization,
1042 lifecycle_state: lifecycle_label(lifecycle).to_string(),
1043 modality: manifest.modality,
1044 architecture: manifest.architecture,
1045 mmproj_path: manifest.mmproj_path,
1046 context_window: manifest.context_window,
1047 };
1048
1049 Ok(record)
1050}
1051
1052pub fn activate_model(
1054 profile_id: u64,
1055 storage_root: &Path,
1056) -> Result<ActiveModelRecord, ModelError> {
1057 let models = models_dir(storage_root);
1058 let entries = std::fs::read_dir(&models).map_err(ModelError::Io)?;
1059 for entry in entries.filter_map(Result::ok) {
1060 let path = entry.path();
1061 if path.extension().and_then(|e| e.to_str()) != Some("json") {
1062 continue;
1063 }
1064 if !path
1065 .file_name()
1066 .map(|n| n.to_string_lossy().contains(".install.json"))
1067 .unwrap_or(false)
1068 {
1069 continue;
1070 }
1071 if let Ok(text) = std::fs::read_to_string(&path) {
1072 if let Ok(manifest) = serde_json::from_str::<InstallManifest>(&text) {
1073 if manifest.profile_id == profile_id {
1074 return activate_model_for_id(&manifest.model_id, storage_root);
1075 }
1076 }
1077 }
1078 }
1079 Err(ModelError::Activate(format!(
1080 "No installed model with profile_id 0x{profile_id:016x}"
1081 )))
1082}
1083
1084pub fn get_model_lifecycle_state() -> ModelLifecycle {
1086 *orchestrator().current_model_state.lock().unwrap()
1087}
1088
1089pub fn get_model_status(active: Option<ActiveModelRecord>) -> ModelStatus {
1091 let lifecycle = get_model_lifecycle_state();
1092 ModelStatus {
1093 profile_id: active.as_ref().map(|r| r.profile_id),
1094 active,
1095 lifecycle_state: lifecycle_label(lifecycle).to_string(),
1096 }
1097}
1098
1099#[cfg(test)]
1100mod tests {
1101 use super::*;
1102
1103 #[test]
1104 fn duplicate_audit_groups_only_identical_gguf_files() {
1105 let root = std::env::temp_dir().join(format!(
1106 "qualia-gguf-audit-{}-{}",
1107 std::process::id(),
1108 unix_now()
1109 ));
1110 let nested = root.join("nested");
1111 std::fs::create_dir_all(&nested).unwrap();
1112 std::fs::write(root.join("keeper.gguf"), b"same model bytes").unwrap();
1113 std::fs::write(nested.join("copy.gguf"), b"same model bytes").unwrap();
1114 std::fs::write(root.join("same-size-not-copy.gguf"), b"other model byte").unwrap();
1115
1116 let groups = audit_vault_duplicates(&root).unwrap();
1117 assert_eq!(groups.len(), 1);
1118 assert_eq!(groups[0].size_bytes, 16);
1119 assert!(groups[0].canonical_path.ends_with("keeper.gguf"));
1120 assert_eq!(groups[0].duplicate_paths.len(), 1);
1121 assert!(groups[0].duplicate_paths[0].ends_with("copy.gguf"));
1122 assert_eq!(groups[0].reclaimable_bytes(), 16);
1123
1124 std::fs::remove_dir_all(root).unwrap();
1125 }
1126
1127 #[test]
1128 fn vault_scan_prefers_p64_over_gguf_same_stem() {
1129 let root = std::env::temp_dir().join(format!(
1130 "qualia-vault-p64-{}-{}",
1131 std::process::id(),
1132 unix_now()
1133 ));
1134 std::fs::create_dir_all(&root).unwrap();
1135 std::fs::write(root.join("smollm.gguf"), b"gguf-bytes").unwrap();
1136 std::fs::write(root.join("smollm.p64"), b"p64\0bytes").unwrap();
1137 std::fs::write(root.join("other.gguf"), b"only-gguf").unwrap();
1138
1139 let entries = scan_vault_gguf(&root).unwrap();
1140 let names: Vec<_> = entries.iter().map(|e| e.name.as_str()).collect();
1141 assert!(
1142 names.iter().any(|n| *n == "smollm.p64"),
1143 "p64 should be listed: {names:?}"
1144 );
1145 assert!(
1146 !names.iter().any(|n| *n == "smollm.gguf"),
1147 "gguf should be hidden when p64 exists: {names:?}"
1148 );
1149 assert!(names.iter().any(|n| *n == "other.gguf"));
1150
1151 let resolved = resolve_vault_model(&root, "smollm").unwrap();
1152 assert!(
1153 resolved.extension().and_then(|e| e.to_str()) == Some("p64"),
1154 "resolve stem should pick p64: {}",
1155 resolved.display()
1156 );
1157 let via_gguf = resolve_vault_model(&root, "smollm.gguf").unwrap();
1158 assert!(
1159 via_gguf.extension().and_then(|e| e.to_str()) == Some("p64"),
1160 "resolve gguf name should still prefer sibling p64: {}",
1161 via_gguf.display()
1162 );
1163
1164 std::fs::remove_dir_all(root).unwrap();
1165 }
1166}