Skip to main content

qualia_semantic_library/ingest/
cml.rs

1//! Stage 4 — CML layer: emit a small RDF/Turtle annotation over the document
2//! that QualiaDB can ingest. This is the semantic layer *on top of* the HTML:
3//! the document as a node, its sections, and heuristically-detected formal
4//! method candidates (Definition / Theorem / Lemma / Algorithm / Proposition),
5//! each carrying provenance back to the source.
6//!
7//! Vocabulary matches the existing acquisition pipeline (`cml:AcquiredMethod`,
8//! `cml:Proposed`) so containers feed the same QualiaDB ingest path. Methods are
9//! emitted as `cml:Proposed` — human attestation is still required before they
10//! are treated as authoritative (the corpus is not the arbiter).
11
12use super::chunk::Chunk;
13use crate::container::HmcManifest;
14
15const CML: &str = "https://webizen.org/cml#";
16const DCT: &str = "http://purl.org/dc/terms/";
17const PROV: &str = "http://www.w3.org/ns/prov#";
18
19/// Keywords that begin a formal-method statement worth surfacing as a candidate.
20const METHOD_CUES: &[&str] = &[
21    "Definition",
22    "Theorem",
23    "Lemma",
24    "Proposition",
25    "Corollary",
26    "Algorithm",
27    "Procedure",
28    "Axiom",
29    "Proof",
30];
31
32/// Build a Turtle document for one source container.
33pub fn build_cml(manifest: &HmcManifest, chunks: &[Chunk]) -> String {
34    let doc_iri = format!("urn:qualia:doc:{}", manifest.doc_id);
35    let mut out = String::new();
36    out.push_str(&format!("@prefix cml: <{CML}> .\n"));
37    out.push_str(&format!("@prefix dct: <{DCT}> .\n"));
38    out.push_str(&format!("@prefix prov: <{PROV}> .\n\n"));
39
40    out.push_str(&format!("<{doc_iri}> a cml:SourceDocument ;\n"));
41    out.push_str(&format!(
42        "    dct:title {} ;\n",
43        ttl_str(&manifest.source.title)
44    ));
45    out.push_str(&format!("    cml:blake3 {} ;\n", ttl_str(&manifest.doc_id)));
46    if manifest.source.page_count > 0 {
47        out.push_str(&format!(
48            "    cml:pageCount {} ;\n",
49            manifest.source.page_count
50        ));
51    }
52    out.push_str(&format!(
53        "    cml:sourceFile {} .\n\n",
54        ttl_str(&manifest.source.filename)
55    ));
56
57    let mut n = 0u32;
58    for c in chunks {
59        if let Some((cue, statement)) = detect_method(&c.text) {
60            let m_iri = format!("{doc_iri}#method-{n}");
61            n += 1;
62            out.push_str(&format!("<{m_iri}> a cml:AcquiredMethod, cml:Proposed ;\n"));
63            out.push_str(&format!("    cml:cue {} ;\n", ttl_str(cue)));
64            out.push_str(&format!(
65                "    dct:description {} ;\n",
66                ttl_str(&truncate(statement, 600))
67            ));
68            if !c.heading_path.is_empty() {
69                out.push_str(&format!(
70                    "    cml:headingPath {} ;\n",
71                    ttl_str(&c.heading_path.join(" / "))
72                ));
73            }
74            out.push_str(&format!("    prov:wasDerivedFrom <{doc_iri}> ;\n"));
75            out.push_str(&format!("    cml:chunkIndex {} .\n\n", c.idx));
76        }
77    }
78    out
79}
80
81/// If a chunk opens with a method cue, return (cue, statement).
82fn detect_method(text: &str) -> Option<(&'static str, &str)> {
83    let head = text.trim_start();
84    for cue in METHOD_CUES {
85        // Compare on bytes so a leading multi-byte char can't split mid-codepoint.
86        // A positive ASCII prefix match guarantees `cue.len()` is a char boundary.
87        if head.len() >= cue.len()
88            && head.as_bytes()[..cue.len()].eq_ignore_ascii_case(cue.as_bytes())
89        {
90            // require the cue to be a standalone token (followed by space/punct)
91            let next = head[cue.len()..].chars().next().unwrap_or(' ');
92            if !next.is_alphanumeric() {
93                return Some((cue, head));
94            }
95        }
96    }
97    None
98}
99
100fn truncate(s: &str, max: usize) -> String {
101    if s.len() <= max {
102        return s.to_string();
103    }
104    let mut i = max;
105    while i > 0 && !s.is_char_boundary(i) {
106        i -= 1;
107    }
108    format!("{}…", &s[..i])
109}
110
111/// Turtle-escape a string literal.
112fn ttl_str(s: &str) -> String {
113    let escaped = s
114        .replace('\\', "\\\\")
115        .replace('"', "\\\"")
116        .replace('\n', "\\n")
117        .replace('\r', "\\r")
118        .replace('\t', "\\t");
119    format!("\"{escaped}\"")
120}