Skip to main content

qualia_core_db/query/
ontology_loader.rs

1#![cfg(not(target_arch = "wasm32"))]
2//! Startup ontology loader — parses bundled Turtle/N-Triples ontology files into NQuins
3//! and seeds the daemon graph at startup.
4//!
5//! Ontology files are resolved in priority order:
6//!   1. `$QUALIA_ONTOLOGY_PATH/` environment variable if set
7//!   2. `ontologies/` relative to the current working directory (dev / workspace layout)
8//!   3. Alongside the binary: `<exe-dir>/ontologies/`
9//!
10//! Any file that cannot be read or parsed emits a log warning and is skipped — the daemon
11//! starts successfully even if ontology files are absent.
12
13use crate::{q_hash, NQuin};
14
15// Canonical named graphs for each ontology.
16const RIGHTS_GRAPH: u64 = q_hash("urn:qualia:ontology:rights");
17const COGAI_GRAPH: u64 = q_hash("urn:qualia:ontology:cogai");
18const EPISTEMIC_GRAPH: u64 = q_hash("urn:qualia:ontology:epistemic");
19const UDHR_GRAPH: u64 = q_hash("urn:qualia:ontology:udhr");
20const CRC_GRAPH: u64 = q_hash("urn:qualia:ontology:crc");
21const PLATFORMS_GRAPH: u64 = q_hash("urn:qualia:ontology:platforms");
22const EMOJI_GRAPH: u64 = q_hash("urn:qualia:ontology:emoji");
23const CRC_ANNOTATED_GRAPH: u64 = q_hash("urn:qualia:ontology:crc_annotated");
24const CRPD_ANNOTATED_GRAPH: u64 = q_hash("urn:qualia:ontology:crpd_annotated");
25const ICCPR_ANNOTATED_GRAPH: u64 = q_hash("urn:qualia:ontology:iccpr_annotated");
26const ICESCR_ANNOTATED_GRAPH: u64 = q_hash("urn:qualia:ontology:icescr_annotated");
27const UDHR_ANNOTATED_GRAPH: u64 = q_hash("urn:qualia:ontology:udhr_annotated");
28const CAT_ANNOTATED_GRAPH: u64 = q_hash("urn:qualia:ontology:cat_annotated");
29const LAWYERS_PRINCIPLES_ANNOTATED_GRAPH: u64 =
30    q_hash("urn:qualia:ontology:lawyers_principles_annotated");
31const REMEDY_REPARATION_ANNOTATED_GRAPH: u64 =
32    q_hash("urn:qualia:ontology:remedy_reparation_annotated");
33const RIGHT_DEVELOPMENT_ANNOTATED_GRAPH: u64 =
34    q_hash("urn:qualia:ontology:right_development_annotated");
35const TORTURE_DECLARATION_ANNOTATED_GRAPH: u64 =
36    q_hash("urn:qualia:ontology:torture_declaration_annotated");
37const HR_DEFENDERS_ANNOTATED_GRAPH: u64 = q_hash("urn:qualia:ontology:hr_defenders_annotated");
38const PEOPLES_PEACE_ANNOTATED_GRAPH: u64 = q_hash("urn:qualia:ontology:peoples_peace_annotated");
39const MENTAL_ILLNESS_PRINCIPLES_ANNOTATED_GRAPH: u64 =
40    q_hash("urn:qualia:ontology:mental_illness_principles_annotated");
41const ISTANBUL_PROTOCOL_ANNOTATED_GRAPH: u64 =
42    q_hash("urn:qualia:ontology:istanbul_protocol_annotated");
43const PALERMO_PROTOCOL_ANNOTATED_GRAPH: u64 =
44    q_hash("urn:qualia:ontology:palermo_protocol_annotated");
45const COMMONWEALTH_CHARTER_ANNOTATED_GRAPH: u64 =
46    q_hash("urn:qualia:ontology:commonwealth_charter_annotated");
47const DNS_RECORD_TYPES_GRAPH: u64 = q_hash("urn:qualia:ontology:dns");
48const TERN_GRAPH: u64 = q_hash("urn:qualia:ontology:tern");
49const DWC_GRAPH: u64 = q_hash("urn:qualia:ontology:dwc");
50const AUNSL_GRAPH: u64 = q_hash("urn:qualia:ontology:aunsl");
51const MA_ONT_GRAPH: u64 = q_hash("urn:qualia:ontology:ma_ont");
52const SPARQL_MM_GRAPH: u64 = q_hash("urn:qualia:ontology:sparql_mm");
53const QUDT_GRAPH: u64 = q_hash("urn:qualia:ontology:qudt");
54
55/// Files to load at startup, as `(filename, named_graph_context)` pairs.
56const STARTUP_ONTOLOGIES: &[(&str, u64)] = &[
57    ("dns_record_types.ttl", DNS_RECORD_TYPES_GRAPH),
58    ("rights_ontology.ttl", RIGHTS_GRAPH),
59    ("cogai_shapes.ttl", COGAI_GRAPH),
60    ("epistemic_shapes.ttl", EPISTEMIC_GRAPH),
61    ("udhr.ttl", UDHR_GRAPH),
62    ("crc.ttl", CRC_GRAPH),
63    ("platforms.ttl", PLATFORMS_GRAPH),
64    ("emoji.n3", EMOJI_GRAPH),
65    ("udhr_annotated.ttl", UDHR_ANNOTATED_GRAPH),
66    ("crc_annotated.ttl", CRC_ANNOTATED_GRAPH),
67    ("crpd_annotated.ttl", CRPD_ANNOTATED_GRAPH),
68    ("iccpr_annotated.ttl", ICCPR_ANNOTATED_GRAPH),
69    ("icescr_annotated.ttl", ICESCR_ANNOTATED_GRAPH),
70    ("cat_annotated.ttl", CAT_ANNOTATED_GRAPH),
71    (
72        "lawyers_principles_annotated.ttl",
73        LAWYERS_PRINCIPLES_ANNOTATED_GRAPH,
74    ),
75    (
76        "remedy_reparation_annotated.ttl",
77        REMEDY_REPARATION_ANNOTATED_GRAPH,
78    ),
79    (
80        "right_development_annotated.ttl",
81        RIGHT_DEVELOPMENT_ANNOTATED_GRAPH,
82    ),
83    (
84        "torture_declaration_annotated.ttl",
85        TORTURE_DECLARATION_ANNOTATED_GRAPH,
86    ),
87    ("hr_defenders_annotated.ttl", HR_DEFENDERS_ANNOTATED_GRAPH),
88    ("peoples_peace_annotated.ttl", PEOPLES_PEACE_ANNOTATED_GRAPH),
89    (
90        "mental_illness_principles_annotated.ttl",
91        MENTAL_ILLNESS_PRINCIPLES_ANNOTATED_GRAPH,
92    ),
93    (
94        "istanbul_protocol_annotated.ttl",
95        ISTANBUL_PROTOCOL_ANNOTATED_GRAPH,
96    ),
97    (
98        "palermo_protocol_annotated.ttl",
99        PALERMO_PROTOCOL_ANNOTATED_GRAPH,
100    ),
101    (
102        "commonwealth_charter_annotated.ttl",
103        COMMONWEALTH_CHARTER_ANNOTATED_GRAPH,
104    ),
105    ("tern.ttl", TERN_GRAPH),
106    ("darwin-core.rdf", DWC_GRAPH),
107    ("aunsl.ttl", AUNSL_GRAPH),
108    ("ma-ont.ttl", MA_ONT_GRAPH),
109    ("sparql-mm.ttl", SPARQL_MM_GRAPH),
110    ("qudt-schema.ttl", QUDT_GRAPH),
111];
112
113/// Startup ontology catalog: `(filename, named_graph_context_hash)`.
114pub fn startup_ontology_catalog() -> &'static [(&'static str, u64)] {
115    STARTUP_ONTOLOGIES
116}
117
118/// Resolved ontologies directory, if present on disk.
119pub fn ontology_dir_path() -> Option<std::path::PathBuf> {
120    find_ontology_dir()
121}
122
123/// Discover the ontologies directory.
124fn find_ontology_dir() -> Option<std::path::PathBuf> {
125    // 1. Environment variable override.
126    if let Ok(p) = std::env::var("QUALIA_ONTOLOGY_PATH") {
127        let pb = std::path::PathBuf::from(p);
128        if pb.is_dir() {
129            return Some(pb);
130        }
131    }
132
133    // 2. `./ontologies/` (workspace root when running via `cargo run`).
134    let cwd = std::path::PathBuf::from("ontologies");
135    if cwd.is_dir() {
136        return Some(cwd);
137    }
138
139    // 3. Next to the binary.
140    if let Ok(exe) = std::env::current_exe() {
141        let sibling = exe.parent().map(|p| p.join("ontologies"));
142        if let Some(ref s) = sibling {
143            if s.is_dir() {
144                return Some(s.clone());
145            }
146        }
147    }
148
149    None
150}
151
152/// Parse a single Turtle file into NQuins, all placed in `graph_context`.
153///
154/// Each triple becomes:
155///   `NQuin { subject = q_hash(subject_iri), predicate = q_hash(pred_iri),
156///            object = q_hash(object_str), context = graph_context, ... }`
157pub fn parse_ttl_to_quins(path: &std::path::Path, graph_context: u64) -> Vec<NQuin> {
158    use std::fs::File;
159    use std::io::BufReader;
160
161    let file = match File::open(path) {
162        Ok(f) => f,
163        Err(e) => {
164            log::warn!("[ontology_loader] cannot open {:?}: {e}", path);
165            return Vec::new();
166        }
167    };
168
169    let reader = BufReader::new(file);
170    let mut parser = rio_turtle::TurtleParser::new(reader, None);
171    let mut quins = Vec::new();
172
173    let result = {
174        use rio_api::parser::TriplesParser;
175        parser.parse_all(
176            &mut |t: rio_api::model::Triple| -> Result<(), std::io::Error> {
177                let s = q_hash(&t.subject.to_string());
178                let p = q_hash(&t.predicate.to_string());
179                let o = q_hash(&t.object.to_string());
180                quins.push(NQuin {
181                    subject: s,
182                    predicate: p,
183                    object: o,
184                    context: graph_context,
185                    metadata: 0,
186                    parity: s ^ p ^ o ^ graph_context,
187                });
188                Ok(())
189            },
190        )
191    };
192
193    if let Err(e) = result {
194        log::warn!("[ontology_loader] parse error in {:?}: {e}", path);
195    }
196
197    log::info!(
198        "[ontology_loader] loaded {} quins from {:?}",
199        quins.len(),
200        path
201    );
202    quins
203}
204
205/// Load a unified `.q42` volume ontology file.
206pub fn load_q42_file(path: &std::path::Path) -> Vec<NQuin> {
207    let all_quins = match crate::q42_reader::read_q42_quins(path) {
208        Ok(quins) => quins,
209        Err(e) => {
210            log::warn!("[ontology_loader] cannot open q42 volume {:?}: {e}", path);
211            return Vec::new();
212        }
213    };
214    log::info!(
215        "[ontology_loader] loaded {} quins from unified volume {:?}",
216        all_quins.len(),
217        path
218    );
219    all_quins
220}
221
222/// Load all startup ontologies into the daemon graph.
223///
224/// Call this once, immediately after `daemon_graph::init_daemon_graph()`.
225pub fn load_startup_ontologies() {
226    let dir = match find_ontology_dir() {
227        Some(d) => d,
228        None => {
229            log::info!("[ontology_loader] no ontologies directory found — skipping");
230            return;
231        }
232    };
233
234    log::info!("[ontology_loader] loading ontologies from {:?}", dir);
235
236    let mut all_quins: Vec<NQuin> = Vec::new();
237    for (filename, context) in STARTUP_ONTOLOGIES {
238        let path = dir.join(filename);
239        if !path.exists() {
240            log::warn!("[ontology_loader] {:?} not found — skipping", path);
241            continue;
242        }
243        let quins = parse_ttl_to_quins(&path, *context);
244        all_quins.extend(quins);
245    }
246
247    // Load any binary .q42 files present in the ontologies directory
248    if let Ok(entries) = std::fs::read_dir(&dir) {
249        for entry in entries.filter_map(|e| e.ok()) {
250            let path = entry.path();
251            if path.extension().and_then(|s| s.to_str()) == Some("q42") {
252                let quins = load_q42_file(&path);
253                all_quins.extend(quins);
254            }
255        }
256    }
257
258    crate::daemon_graph::extend_with_ontology_quins(all_quins);
259    log::info!(
260        "[ontology_loader] daemon graph now has {} quins after ontology seed",
261        crate::daemon_graph::graph_quin_count(),
262    );
263}
264
265#[cfg(test)]
266mod tests {
267    use super::*;
268    use std::io::Write;
269
270    #[test]
271    fn parse_ttl_minimal() {
272        let ttl = b"@prefix ex: <http://example.org/> .\nex:Alice a ex:Person .\n";
273        let tmp = tempfile::NamedTempFile::new().expect("tmp");
274        tmp.as_file().write_all(ttl).unwrap();
275        let quins = parse_ttl_to_quins(tmp.path(), 0xCAFE);
276        assert!(!quins.is_empty());
277        assert!(quins.iter().all(|q| q.context == 0xCAFE));
278    }
279
280    #[test]
281    fn parse_ttl_missing_file_returns_empty() {
282        let quins = parse_ttl_to_quins(std::path::Path::new("/nonexistent/file.ttl"), 0);
283        assert!(quins.is_empty());
284    }
285}