Skip to main content

qualia_core_db/extensions/
resource_catalog.rs

1//! Resource Catalog — canonical types, Quin encoding, and CapabilityProfile binding.
2//!
3//! This module defines the authoritative Rust types for the YAML-backed resource
4//! catalog (`resources/*.yaml`). It is the single source of truth — the Flutter
5//! bridge and CLI both reference these types, not their own copies.
6//!
7//! # Quin encoding
8//!
9//! Each catalog entry can be encoded as a set of `NQuin`s for first-class
10//! graph membership. Predicate convention:
11//!
12//! | Predicate string         | Meaning                        |
13//! |--------------------------|--------------------------------|
14//! | `llm:hasFormat`          | Model file format (e.g. `gguf`)|
15//! | `llm:hasQuantization`    | Quantization level             |
16//! | `llm:hasSizeMb`          | File size (inline integer)     |
17//! | `llm:hasRamEstimateMb`   | Peak RAM needed (inline int)   |
18//! | `llm:hasSourceRepo`      | Source repo hash               |
19//! | `llm:hasLicense`         | License identifier hash        |
20//! | `ont:hasFormat`          | Ontology serialisation format  |
21//! | `ont:hasDomain`          | Domain tag hash                |
22//! | `prov:wasGeneratedBy`    | Provenance: download event     |
23//! | `prov:atPath`            | Local file path hash           |
24//! | `prov:atTimestamp`       | Unix timestamp (inline int)    |
25
26use crate::llm_agent::AgentBackend;
27use crate::profiles::CapabilityProfile;
28use crate::{q_hash, NQuin};
29use serde::{Deserialize, Serialize};
30
31// ─── Inline type tag for object field (resolver.rs convention) ───────────────
32const INLINE_TAG_INTEGER: u64 = 0x1u64 << 60;
33
34// ─── Catalog context hashes (compile-time) ───────────────────────────────────
35const CTX_LLM: u64 = q_hash("catalog:llm");
36const CTX_ONT: u64 = q_hash("catalog:ontology");
37const CTX_PROV: u64 = q_hash("catalog:provenance");
38
39// ─── Download info ────────────────────────────────────────────────────────────
40
41/// Where and how to fetch a resource.
42#[derive(Debug, Clone, Serialize, Deserialize)]
43pub struct DownloadInfo {
44    /// Source type: `"huggingface"`, `"direct"`, `"github"`.
45    #[serde(rename = "type")]
46    pub download_type: String,
47    /// HuggingFace repo slug (e.g. `"unsloth/Phi-3-mini-4k-instruct-GGUF"`).
48    pub repo: Option<String>,
49    /// Filename within the repo (e.g. `"Phi-3-mini-4k-instruct.Q4_K_M.gguf"`).
50    pub file: Option<String>,
51    /// Direct URL for `"direct"` or `"github"` sources.
52    pub url: Option<String>,
53    /// Path within a GitHub repo (used with `type: github`).
54    pub path: Option<String>,
55}
56
57impl DownloadInfo {
58    /// Resolve to a concrete download URL.
59    pub fn resolved_url(&self) -> Option<String> {
60        match self.download_type.as_str() {
61            "huggingface" => {
62                let repo = self.repo.as_deref()?;
63                let file = self.file.as_deref()?;
64                Some(format!(
65                    "https://huggingface.co/{}/resolve/main/{}",
66                    repo, file
67                ))
68            }
69            "github" => {
70                let repo = self.repo.as_deref()?;
71                let path = self.path.as_deref()?;
72                let path = path.trim_start_matches('/');
73                Some(format!(
74                    "https://raw.githubusercontent.com/{}/main/{}",
75                    repo, path
76                ))
77            }
78            _ => self.url.clone(),
79        }
80    }
81
82    /// Local filename to use when saving (falls back to last URL segment).
83    pub fn local_filename(&self) -> Option<String> {
84        if let Some(ref f) = self.file {
85            return Some(f.clone());
86        }
87        self.url
88            .as_ref()
89            .and_then(|u| u.split('/').last().map(|s| s.to_string()))
90    }
91}
92
93// ─── LLM resource ─────────────────────────────────────────────────────────────
94
95/// A downloadable LLM / model package (primarily GGUF).
96#[derive(Debug, Clone, Serialize, Deserialize)]
97pub struct LLMResource {
98    pub id: String,
99    pub name: String,
100    pub provider: Option<String>,
101    /// File format — always `"gguf"` for Qualia-compatible models.
102    pub format: String,
103    /// Quantization level (e.g. `"Q4_K_M"`, `"Q8_0"`).
104    pub quantization: Option<String>,
105    /// Compressed file size in MB.
106    pub size_mb: Option<u32>,
107    pub download: DownloadInfo,
108    pub license: Option<String>,
109    pub recommended_for: Option<Vec<String>>,
110    /// Peak RAM required (model + runtime overhead) in MB.
111    pub ram_estimate_mb: Option<u32>,
112    pub tags: Option<Vec<String>>,
113    pub last_verified: Option<String>,
114    pub notes: Option<String>,
115    /// `text` (default) or `multimodal` (requires `vision_projector`).
116    pub modality: Option<String>,
117    /// Vision / CLIP projector GGUF paired with the language model.
118    pub vision_projector: Option<DownloadInfo>,
119    /// Architecture family for multimodal routing: `llava`, `qwen2vl`, `smolvlm`, `gemma3`.
120    pub architecture: Option<String>,
121    /// Recommended decode context window in tokens.
122    pub context_window: Option<u32>,
123}
124
125impl LLMResource {
126    /// `true` when multimodal.
127    pub fn is_multimodal(&self) -> bool {
128        matches!(self.modality.as_deref(), Some("multimodal" | "vision"))
129            || self.vision_projector.is_some()
130    }
131
132    /// Context window in tokens after policy caps.
133    pub fn effective_context_window(&self) -> u32 {
134        self.context_window
135            .unwrap_or(if self.is_multimodal() { 8192 } else { 4096 })
136    }
137    /// Encode this catalog entry as a set of `NQuin`s.
138    ///
139    /// Returns Quins using the `catalog:llm` context graph.  Vec allocation is
140    /// intentional — this runs once at catalog load, not in a hot evaluator loop.
141    pub fn to_quins(&self) -> Vec<NQuin> {
142        let subject = q_hash(&format!("llm:{}", self.id));
143        let mut out = Vec::with_capacity(8);
144
145        // Format (always present)
146        out.push(Self::quin(
147            subject,
148            q_hash("llm:hasFormat"),
149            q_hash(&self.format),
150            CTX_LLM,
151        ));
152
153        // Quantization
154        if let Some(ref q) = self.quantization {
155            out.push(Self::quin(
156                subject,
157                q_hash("llm:hasQuantization"),
158                q_hash(q),
159                CTX_LLM,
160            ));
161        }
162
163        // File size (inline integer)
164        if let Some(sz) = self.size_mb {
165            out.push(Self::quin(
166                subject,
167                q_hash("llm:hasSizeMb"),
168                INLINE_TAG_INTEGER | sz as u64,
169                CTX_LLM,
170            ));
171        }
172
173        // Peak RAM (inline integer)
174        if let Some(ram) = self.ram_estimate_mb {
175            out.push(Self::quin(
176                subject,
177                q_hash("llm:hasRamEstimateMb"),
178                INLINE_TAG_INTEGER | ram as u64,
179                CTX_LLM,
180            ));
181        }
182
183        // Source repo
184        if let Some(ref repo) = self.download.repo {
185            out.push(Self::quin(
186                subject,
187                q_hash("llm:hasSourceRepo"),
188                q_hash(&format!("hf:{}", repo)),
189                CTX_LLM,
190            ));
191        }
192
193        // License
194        if let Some(ref lic) = self.license {
195            out.push(Self::quin(
196                subject,
197                q_hash("llm:hasLicense"),
198                q_hash(&format!("license:{}", lic)),
199                CTX_LLM,
200            ));
201        }
202
203        // Provider
204        if let Some(ref prov) = self.provider {
205            out.push(Self::quin(
206                subject,
207                q_hash("llm:hasProvider"),
208                q_hash(prov),
209                CTX_LLM,
210            ));
211        }
212
213        if self.is_multimodal() {
214            out.push(Self::quin(
215                subject,
216                q_hash("llm:hasModality"),
217                q_hash("multimodal"),
218                CTX_LLM,
219            ));
220        }
221
222        if let Some(ref arch) = self.architecture {
223            out.push(Self::quin(
224                subject,
225                q_hash("llm:hasArchitecture"),
226                q_hash(arch),
227                CTX_LLM,
228            ));
229        }
230
231        out
232    }
233
234    /// Generate a provenance `NQuin` recording a completed download event.
235    ///
236    /// Written to the WAL immediately after the file is saved to disk.
237    pub fn provenance_quin(&self, timestamp_unix: u64, local_path: &str) -> NQuin {
238        let subject = q_hash(&format!("download:{}", self.id));
239        let predicate = q_hash("prov:wasGeneratedBy");
240        let object = q_hash(local_path);
241        let context = CTX_PROV;
242        // Store lower 32 bits of Unix timestamp in metadata
243        let metadata = timestamp_unix & 0xFFFF_FFFF;
244        let parity = subject ^ predicate ^ object ^ context ^ metadata;
245        NQuin {
246            subject,
247            predicate,
248            object,
249            context,
250            metadata,
251            parity,
252        }
253    }
254
255    /// Generate a supplementary provenance Quin recording the source URL.
256    pub fn source_url_quin(&self) -> Option<NQuin> {
257        let url = self.download.resolved_url()?;
258        let subject = q_hash(&format!("download:{}", self.id));
259        let predicate = q_hash("prov:hadPrimarySource");
260        let object = q_hash(&url);
261        let parity = subject ^ predicate ^ object ^ CTX_PROV;
262        Some(NQuin {
263            subject,
264            predicate,
265            object,
266            context: CTX_PROV,
267            metadata: 0,
268            parity,
269        })
270    }
271
272    /// Build a `CapabilityProfile` for this model, bound to its local file path.
273    ///
274    /// The profile ID is deterministic: `q_hash("profile:{id}")`, so callers
275    /// can look it up without storing a separate reference.
276    pub fn to_capability_profile(&self, local_path: &str) -> CapabilityProfile {
277        self.to_capability_profile_with_projector(local_path, None)
278    }
279
280    /// `LLMResource::to_capability_profile_with_projector`.
281    pub fn to_capability_profile_with_projector(
282        &self,
283        local_path: &str,
284        vision_projector_path: Option<&str>,
285    ) -> CapabilityProfile {
286        let modality = if self.is_multimodal() {
287            "multimodal".to_string()
288        } else {
289            "text".to_string()
290        };
291        CapabilityProfile {
292            profile_id: q_hash(&format!("profile:{}", self.id)),
293            active_engines: vec![],
294            loaded_ontologies: vec![],
295            preferred_backend: AgentBackend::Local {
296                model_path: local_path.to_string(),
297                context_window: self.effective_context_window(),
298                quantization: self
299                    .quantization
300                    .clone()
301                    .unwrap_or_else(|| "Q4_K_M".to_string()),
302                vision_projector_path: vision_projector_path.map(|s| s.to_string()),
303                modality,
304                architecture: self.architecture.clone(),
305            },
306            permitted_intent_frames: vec![],
307        }
308    }
309
310    fn quin(subject: u64, predicate: u64, object: u64, context: u64) -> NQuin {
311        let parity = subject ^ predicate ^ object ^ context;
312        NQuin {
313            subject,
314            predicate,
315            object,
316            context,
317            metadata: 0,
318            parity,
319        }
320    }
321}
322
323// ─── Ontology resource ────────────────────────────────────────────────────────
324
325/// A downloadable ontology (OWL, SKOS, RDF/Turtle, etc.).
326#[derive(Debug, Clone, Serialize, Deserialize)]
327pub struct OntologyResource {
328    pub id: String,
329    pub name: String,
330    pub acronym: Option<String>,
331    pub source: Option<String>,
332    pub format: String,
333    /// YAML may use fractional estimates (e.g. `0.2` MB).
334    pub size_estimate_mb: Option<f64>,
335    pub download: DownloadInfo,
336    pub license: Option<String>,
337    pub domain: Option<String>,
338    pub tags: Option<Vec<String>>,
339    pub import_strategy: Option<String>,
340    pub last_verified: Option<String>,
341    pub notes: Option<String>,
342}
343
344impl OntologyResource {
345    /// Encode this ontology entry as `NQuin`s in the `catalog:ontology` context.
346    pub fn to_quins(&self) -> Vec<NQuin> {
347        let subject = q_hash(&format!("ont:{}", self.id));
348        let mut out = Vec::with_capacity(5);
349
350        out.push(Self::quin(
351            subject,
352            q_hash("ont:hasFormat"),
353            q_hash(&self.format),
354            CTX_ONT,
355        ));
356
357        if let Some(ref domain) = self.domain {
358            out.push(Self::quin(
359                subject,
360                q_hash("ont:hasDomain"),
361                q_hash(domain),
362                CTX_ONT,
363            ));
364        }
365
366        if let Some(sz) = self.size_estimate_mb {
367            let mb = sz.ceil().max(0.0) as u64;
368            out.push(Self::quin(
369                subject,
370                q_hash("ont:hasSizeMb"),
371                INLINE_TAG_INTEGER | mb,
372                CTX_ONT,
373            ));
374        }
375
376        if let Some(ref lic) = self.license {
377            out.push(Self::quin(
378                subject,
379                q_hash("ont:hasLicense"),
380                q_hash(&format!("license:{}", lic)),
381                CTX_ONT,
382            ));
383        }
384
385        if let Some(ref src) = self.source {
386            out.push(Self::quin(
387                subject,
388                q_hash("ont:hasSource"),
389                q_hash(src),
390                CTX_ONT,
391            ));
392        }
393
394        out
395    }
396
397    /// Provenance Quin for a completed ontology import.
398    pub fn provenance_quin(&self, timestamp_unix: u64, local_path: &str) -> NQuin {
399        let subject = q_hash(&format!("import:{}", self.id));
400        let predicate = q_hash("prov:wasGeneratedBy");
401        let object = q_hash(local_path);
402        let metadata = timestamp_unix & 0xFFFF_FFFF;
403        let parity = subject ^ predicate ^ object ^ CTX_PROV ^ metadata;
404        NQuin {
405            subject,
406            predicate,
407            object,
408            context: CTX_PROV,
409            metadata,
410            parity,
411        }
412    }
413
414    fn quin(subject: u64, predicate: u64, object: u64, context: u64) -> NQuin {
415        let parity = subject ^ predicate ^ object ^ context;
416        NQuin {
417            subject,
418            predicate,
419            object,
420            context,
421            metadata: 0,
422            parity,
423        }
424    }
425}
426
427// ─── SPARQL endpoint resource ─────────────────────────────────────────────────
428
429/// A public SPARQL endpoint.
430#[derive(Debug, Clone, Serialize, Deserialize)]
431pub struct SPARQLResource {
432    pub id: String,
433    pub name: String,
434    pub endpoint: String,
435    pub gui: Option<String>,
436    pub maintainer: Option<String>,
437    pub reliability: Option<String>,
438    pub domains: Option<Vec<String>>,
439    pub rate_limit: Option<String>,
440    pub federation_supported: Option<bool>,
441    pub example_queries: Option<Vec<ExampleQuery>>,
442    pub last_verified: Option<String>,
443    pub notes: Option<String>,
444}
445
446#[derive(Debug, Clone, Serialize, Deserialize)]
447pub struct ExampleQuery {
448    pub description: Option<String>,
449    pub query: Option<String>,
450}
451
452// ─── Resource catalog ─────────────────────────────────────────────────────────
453
454/// The complete in-memory resource catalog, loaded from `resources/*.yaml`.
455pub struct ResourceCatalog {
456    pub llms: Vec<LLMResource>,
457    pub ontologies: Vec<OntologyResource>,
458    pub sparql_endpoints: Vec<SPARQLResource>,
459}
460
461impl ResourceCatalog {
462    /// Creates an empty catalog.
463    pub fn empty() -> Self {
464        Self {
465            llms: vec![],
466            ontologies: vec![],
467            sparql_endpoints: vec![],
468        }
469    }
470
471    /// LLM resource by `id`.
472    pub fn find_llm(&self, id: &str) -> Option<&LLMResource> {
473        self.llms.iter().find(|r| r.id == id)
474    }
475
476    /// Ontology resource by `id`.
477    pub fn find_ontology(&self, id: &str) -> Option<&OntologyResource> {
478        self.ontologies.iter().find(|r| r.id == id)
479    }
480
481    /// SPARQL resource by `id`.
482    pub fn find_sparql(&self, id: &str) -> Option<&SPARQLResource> {
483        self.sparql_endpoints.iter().find(|r| r.id == id)
484    }
485
486    /// Serialize a summary for FRB / JSON consumers.
487    pub fn summary_json(&self) -> String {
488        #[derive(Serialize)]
489        struct Summary {
490            llm_count: usize,
491            ontology_count: usize,
492            sparql_count: usize,
493        }
494        serde_json::to_string(&Summary {
495            llm_count: self.llms.len(),
496            ontology_count: self.ontologies.len(),
497            sparql_count: self.sparql_endpoints.len(),
498        })
499        .unwrap_or_else(|_| "{}".to_string())
500    }
501}
502
503// ─── YAML loader (canonical — CLI, Flutter, client-core) ─────────────────────
504
505use std::path::{Path, PathBuf};
506
507/// Errors loading `resources/*.yaml`.
508#[derive(Debug, Clone, PartialEq, Eq)]
509pub enum CatalogError {
510    Io { path: PathBuf, message: String },
511    Parse { path: PathBuf, message: String },
512    Index { message: String },
513}
514
515impl std::fmt::Display for CatalogError {
516    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
517        match self {
518            CatalogError::Io { path, message } => {
519                write!(f, "cannot read {}: {}", path.display(), message)
520            }
521            CatalogError::Parse { path, message } => {
522                write!(f, "{}: {}", path.display(), message)
523            }
524            CatalogError::Index { message } => write!(f, "catalog.yaml: {}", message),
525        }
526    }
527}
528
529impl std::error::Error for CatalogError {}
530
531#[derive(Debug, Deserialize)]
532struct CatalogRoot {
533    catalog: CatalogMeta,
534}
535
536#[derive(Debug, Deserialize)]
537struct CatalogMeta {
538    sources: CatalogSources,
539}
540
541#[derive(Debug, Deserialize)]
542struct CatalogSources {
543    llms: String,
544    ontologies: String,
545    sparql_endpoints: String,
546}
547
548#[derive(Debug, Deserialize)]
549struct LlmsFile {
550    llms: Vec<LLMResource>,
551}
552
553#[derive(Debug, Deserialize)]
554struct OntologiesFile {
555    ontologies: Vec<OntologyResource>,
556}
557
558#[derive(Debug, Deserialize)]
559struct SparqlFile {
560    sparql_endpoints: Vec<SPARQLResource>,
561}
562
563fn read_yaml<T: serde::de::DeserializeOwned>(path: &Path) -> Result<T, CatalogError> {
564    let raw = std::fs::read_to_string(path).map_err(|e| CatalogError::Io {
565        path: path.to_path_buf(),
566        message: e.to_string(),
567    })?;
568    serde_yaml::from_str(&raw).map_err(|e| CatalogError::Parse {
569        path: path.to_path_buf(),
570        message: e.to_string(),
571    })
572}
573
574/// Resolve the resources directory for desktop / dev builds.
575///
576/// Order: `QUALIA_RESOURCES_DIR` → `{exe}/bundled/resources/` → dev tree `../../resources`.
577pub fn resolve_resources_dir() -> PathBuf {
578    if let Ok(extra) = std::env::var("QUALIA_RESOURCES_DIR") {
579        return PathBuf::from(extra);
580    }
581
582    if let Ok(exe) = std::env::current_exe() {
583        if let Some(root) = exe.parent() {
584            for rel in ["bundled/resources", "resources", "bundled"] {
585                let candidate = root.join(rel);
586                if candidate.join("catalog.yaml").is_file() {
587                    return candidate;
588                }
589            }
590        }
591    }
592
593    PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../resources")
594}
595
596/// Load the full catalog from `dir/catalog.yaml` and referenced child YAML files.
597pub fn load_from_dir(dir: &Path) -> Result<ResourceCatalog, CatalogError> {
598    let index_path = dir.join("catalog.yaml");
599    let index: CatalogRoot = read_yaml(&index_path)?;
600
601    let llms_path = dir.join(&index.catalog.sources.llms);
602    let ont_path = dir.join(&index.catalog.sources.ontologies);
603    let sparql_path = dir.join(&index.catalog.sources.sparql_endpoints);
604
605    let llms_file: LlmsFile = read_yaml(&llms_path)?;
606    let ont_file: OntologiesFile = read_yaml(&ont_path)?;
607    let sparql_file: SparqlFile = read_yaml(&sparql_path)?;
608
609    Ok(ResourceCatalog {
610        llms: llms_file.llms,
611        ontologies: ont_file.ontologies,
612        sparql_endpoints: sparql_file.sparql_endpoints,
613    })
614}
615
616/// Load from [`resolve_resources_dir()`].
617pub fn load_default() -> Result<ResourceCatalog, CatalogError> {
618    load_from_dir(&resolve_resources_dir())
619}
620
621#[cfg(test)]
622mod load_tests {
623    use super::*;
624
625    fn resources_fixture_dir() -> PathBuf {
626        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../resources")
627    }
628
629    #[test]
630    fn loads_all_entries_from_committed_yaml() {
631        let dir = resources_fixture_dir();
632        let cat = load_from_dir(&dir).expect("catalog should load");
633        assert!(
634            cat.llms.len() >= 10,
635            "expected >=10 LLMs, got {}",
636            cat.llms.len()
637        );
638        let multimodal = cat.llms.iter().filter(|m| m.is_multimodal()).count();
639        assert!(
640            multimodal >= 3,
641            "expected >=3 multimodal LLMs, got {multimodal}"
642        );
643        assert!(
644            cat.ontologies.len() >= 12,
645            "expected >=12 ontologies, got {}",
646            cat.ontologies.len()
647        );
648        assert!(
649            cat.sparql_endpoints.len() >= 3,
650            "expected >=3 SPARQL endpoints, got {}",
651            cat.sparql_endpoints.len()
652        );
653    }
654
655    #[test]
656    fn github_download_resolves_raw_url() {
657        let info = DownloadInfo {
658            download_type: "github".to_string(),
659            repo: Some("schemaorg/schemaorg".to_string()),
660            file: None,
661            url: None,
662            path: Some("data/releases/27.0/schemaorg-all-https.rdf".to_string()),
663        };
664        let url = info.resolved_url().expect("github url");
665        assert!(url.contains("raw.githubusercontent.com/schemaorg/schemaorg"));
666        assert!(url.contains("schemaorg-all-https.rdf"));
667    }
668
669    #[test]
670    fn find_llm_by_id() {
671        let cat = load_from_dir(&resources_fixture_dir()).unwrap();
672        assert!(cat.find_llm("phi-3-mini-4k-instruct-q4km").is_some());
673    }
674}