1use crate::llm_agent::AgentBackend;
27use crate::profiles::CapabilityProfile;
28use crate::{q_hash, NQuin};
29use serde::{Deserialize, Serialize};
30
31const INLINE_TAG_INTEGER: u64 = 0x1u64 << 60;
33
34const 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#[derive(Debug, Clone, Serialize, Deserialize)]
43pub struct DownloadInfo {
44 #[serde(rename = "type")]
46 pub download_type: String,
47 pub repo: Option<String>,
49 pub file: Option<String>,
51 pub url: Option<String>,
53 pub path: Option<String>,
55}
56
57impl DownloadInfo {
58 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 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#[derive(Debug, Clone, Serialize, Deserialize)]
97pub struct LLMResource {
98 pub id: String,
99 pub name: String,
100 pub provider: Option<String>,
101 pub format: String,
103 pub quantization: Option<String>,
105 pub size_mb: Option<u32>,
107 pub download: DownloadInfo,
108 pub license: Option<String>,
109 pub recommended_for: Option<Vec<String>>,
110 pub ram_estimate_mb: Option<u32>,
112 pub tags: Option<Vec<String>>,
113 pub last_verified: Option<String>,
114 pub notes: Option<String>,
115 pub modality: Option<String>,
117 pub vision_projector: Option<DownloadInfo>,
119 pub architecture: Option<String>,
121 pub context_window: Option<u32>,
123}
124
125impl LLMResource {
126 pub fn is_multimodal(&self) -> bool {
128 matches!(self.modality.as_deref(), Some("multimodal" | "vision"))
129 || self.vision_projector.is_some()
130 }
131
132 pub fn effective_context_window(&self) -> u32 {
134 self.context_window
135 .unwrap_or(if self.is_multimodal() { 8192 } else { 4096 })
136 }
137 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 out.push(Self::quin(
147 subject,
148 q_hash("llm:hasFormat"),
149 q_hash(&self.format),
150 CTX_LLM,
151 ));
152
153 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 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 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 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 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 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 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 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 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 pub fn to_capability_profile(&self, local_path: &str) -> CapabilityProfile {
277 self.to_capability_profile_with_projector(local_path, None)
278 }
279
280 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#[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 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 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 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#[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
452pub struct ResourceCatalog {
456 pub llms: Vec<LLMResource>,
457 pub ontologies: Vec<OntologyResource>,
458 pub sparql_endpoints: Vec<SPARQLResource>,
459}
460
461impl ResourceCatalog {
462 pub fn empty() -> Self {
464 Self {
465 llms: vec![],
466 ontologies: vec![],
467 sparql_endpoints: vec![],
468 }
469 }
470
471 pub fn find_llm(&self, id: &str) -> Option<&LLMResource> {
473 self.llms.iter().find(|r| r.id == id)
474 }
475
476 pub fn find_ontology(&self, id: &str) -> Option<&OntologyResource> {
478 self.ontologies.iter().find(|r| r.id == id)
479 }
480
481 pub fn find_sparql(&self, id: &str) -> Option<&SPARQLResource> {
483 self.sparql_endpoints.iter().find(|r| r.id == id)
484 }
485
486 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
503use std::path::{Path, PathBuf};
506
507#[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
574pub 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
596pub 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
616pub 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}