Skip to main content

qualia_core_db/nlp/
capability.rs

1//! Honest maturity metadata for public `NLP.*` invoke IDs.
2//!
3//! Existing IDs are preserved, including `NLP.graphrag_query`. Algorithm class,
4//! maturity, version, and evidence are labels of what the engine actually runs
5//! today — not Stanford/Stanza/spaCy parity, FrameNet, OpenIE, or GraphRAG.
6
7use crate::ENGINE_VERSION;
8
9/// One public NLP invoke: what it is, what class of algorithm it uses, and
10/// what evaluation evidence currently exists.
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub struct NlpCapability {
13    pub id: &'static str,
14    /// `stable`, `partial`, `experimental`, or `fail-closed`.
15    pub maturity: &'static str,
16    /// Algorithm actually implemented. Must not name a system we do not ship.
17    pub algorithm_class: &'static str,
18    /// Engine semver (`ENGINE_VERSION`); not a linguistic model card.
19    pub version: &'static str,
20    /// What evaluation evidence currently exists (availability, not a score).
21    pub evidence: &'static str,
22}
23
24/// Public `NLP.*` descriptors. Order matches `ids.rs` bind groups, not quality.
25pub const NLP_CAPABILITIES: &[NlpCapability] = &[
26    NlpCapability {
27        id: "NLP.tokenize",
28        maturity: "experimental",
29        algorithm_class: "deterministic UTF-8 prototype tokenizer (byte spans; not Stanford/spaCy)",
30        version: ENGINE_VERSION,
31        evidence: "unit tests",
32    },
33    NlpCapability {
34        id: "NLP.split_sentences",
35        maturity: "experimental",
36        algorithm_class: "deterministic UTF-8 sentence-split prototype (not Stanford/spaCy)",
37        version: ENGINE_VERSION,
38        evidence: "unit tests",
39    },
40    NlpCapability {
41        id: "NLP.gazetteer_run",
42        maturity: "experimental",
43        algorithm_class: "compiled Aho-Corasick patterns over the default lexicon (not NER)",
44        version: ENGINE_VERSION,
45        evidence: "unit tests",
46    },
47    NlpCapability {
48        id: "NLP.gazetteer_build",
49        maturity: "experimental",
50        algorithm_class: "reports default compiled lexicon size (not NER; does not compile caller patterns)",
51        version: ENGINE_VERSION,
52        evidence: "unit tests",
53    },
54    NlpCapability {
55        id: "NLP.fst_lookup",
56        maturity: "experimental",
57        algorithm_class: "trie lookup over caller-supplied entries plus English suffix stripping (-s/-es/-ies/-ed/-ing); empty entries yield no results (not a language pack)",
58        version: ENGINE_VERSION,
59        evidence: "unit tests",
60    },
61    NlpCapability {
62        id: "NLP.coref_resolve",
63        maturity: "experimental",
64        algorithm_class: "bounded exact-string grouping plus experimental pronoun sieve; empty mentions skip detection (not multi-pass sieve quality)",
65        version: ENGINE_VERSION,
66        evidence: "unit tests",
67    },
68    NlpCapability {
69        id: "NLP.frame_extract",
70        maturity: "experimental",
71        algorithm_class: "small lexical-trigger rule demo (not FrameNet)",
72        version: ENGINE_VERSION,
73        evidence: "unit tests",
74    },
75    NlpCapability {
76        id: "NLP.relation_extract",
77        maturity: "experimental",
78        algorithm_class: "small pattern rule demo (is/has/located-in; not OpenIE)",
79        version: ENGINE_VERSION,
80        evidence: "unit tests",
81    },
82    NlpCapability {
83        id: "NLP.substrate_extract",
84        maturity: "experimental",
85        algorithm_class: "symbolic pipeline (tokenize → gazetteer → ISO/units → rules → exact-match coref); every word becomes a mention",
86        version: ENGINE_VERSION,
87        evidence: "unit tests",
88    },
89    NlpCapability {
90        id: "NLP.graphrag_query",
91        maturity: "experimental",
92        algorithm_class: "keyword-triple term overlap over caller-supplied triples (not GraphRAG, embeddings, or graph-neighborhood retrieval)",
93        version: ENGINE_VERSION,
94        evidence: "unit tests",
95    },
96];
97
98/// Look up honest metadata for a public `NLP.*` invoke id.
99pub fn lookup(id: &str) -> Option<&'static NlpCapability> {
100    NLP_CAPABILITIES.iter().find(|cap| cap.id == id)
101}
102
103#[cfg(test)]
104mod tests {
105    use super::*;
106
107    const PUBLIC_NLP_IDS: &[&str] = &[
108        "NLP.tokenize",
109        "NLP.split_sentences",
110        "NLP.gazetteer_run",
111        "NLP.gazetteer_build",
112        "NLP.fst_lookup",
113        "NLP.coref_resolve",
114        "NLP.frame_extract",
115        "NLP.relation_extract",
116        "NLP.substrate_extract",
117        "NLP.graphrag_query",
118    ];
119
120    #[test]
121    fn table_lookup_covers_each_public_nlp_id() {
122        assert_eq!(NLP_CAPABILITIES.len(), PUBLIC_NLP_IDS.len());
123        for id in PUBLIC_NLP_IDS {
124            let cap = lookup(id).unwrap_or_else(|| panic!("missing NLP capability for {id}"));
125            assert_eq!(cap.id, *id);
126            assert_eq!(cap.maturity, "experimental");
127            assert_eq!(cap.version, ENGINE_VERSION);
128            assert!(!cap.algorithm_class.is_empty());
129            assert_eq!(cap.evidence, "unit tests");
130        }
131        assert!(lookup("NLP.does_not_exist").is_none());
132        assert!(lookup("nlp.analyze").is_none());
133    }
134
135    #[test]
136    fn fst_algorithm_class_discloses_caller_supplied_entries() {
137        let cap = lookup("NLP.fst_lookup").expect("NLP.fst_lookup");
138        let class = cap.algorithm_class.to_ascii_lowercase();
139        assert!(
140            class.contains("caller-supplied"),
141            "algorithm_class must disclose caller-supplied entries, got {}",
142            cap.algorithm_class
143        );
144        assert!(
145            class.contains("empty"),
146            "algorithm_class must disclose empty-entries yield no results, got {}",
147            cap.algorithm_class
148        );
149    }
150
151    #[test]
152    fn graphrag_algorithm_class_contains_keyword() {
153        let cap = lookup("NLP.graphrag_query").expect("NLP.graphrag_query");
154        assert!(
155            cap.algorithm_class.to_ascii_lowercase().contains("keyword"),
156            "algorithm_class must contain keyword, got {}",
157            cap.algorithm_class
158        );
159        assert_eq!(cap.maturity, "experimental");
160        assert_eq!(cap.version, ENGINE_VERSION);
161    }
162
163    #[cfg(not(all(
164        target_arch = "wasm32",
165        feature = "wasm-ontology",
166        not(any(
167            feature = "wasm-logic",
168            feature = "wasm-scientific",
169            feature = "wasm-full"
170        ))
171    )))]
172    #[test]
173    fn every_bound_nlp_dot_id_is_in_the_table() {
174        for id in crate::poet_host::invoke::ids::ALL_BOUND
175            .iter()
176            .copied()
177            .filter(|id| id.starts_with("NLP."))
178        {
179            assert!(
180                lookup(id).is_some(),
181                "bound invoke {id} missing from NLP_CAPABILITIES"
182            );
183        }
184    }
185}