Skip to main content

qualia_core_db/nlp/
emit.rs

1//! Span-annotation plans. Host seals Quins via `text_span::annotation_quin`.
2
3use super::gazetteer::Hit;
4use super::hash::hash60;
5use super::normalize::Normalized;
6use super::span::DocSpan;
7
8#[derive(Debug, Clone, PartialEq)]
9pub struct AnnotationPlan {
10    pub term_iri: String,
11    pub start_utf8: u32,
12    pub end_utf8: u32,
13    pub content_hash: u64,
14    pub source_hash: u64,
15    pub surface: String,
16    pub kind: &'static str,
17}
18
19/// Emits annotation plans from raw hits.
20pub fn emit_from_hits(source: &str, hits: &[Hit]) -> Vec<AnnotationPlan> {
21    let source_hash = hash60(source.as_bytes());
22    hits.iter()
23        .filter_map(|h| {
24            let slice = h.span.slice(source)?;
25            Some(AnnotationPlan {
26                term_iri: h.iri.to_string(),
27                start_utf8: h.span.start_utf8,
28                end_utf8: h.span.end_utf8,
29                content_hash: hash60(slice.as_bytes()),
30                source_hash,
31                surface: slice.to_string(),
32                kind: "gazetteer",
33            })
34        })
35        .collect()
36}
37
38/// Emits annotation plans from normalized spans.
39pub fn emit_from_normalized(source: &str, norms: &[Normalized]) -> Vec<AnnotationPlan> {
40    let source_hash = hash60(source.as_bytes());
41    norms
42        .iter()
43        .filter_map(|n| {
44            let (span, iri, kind) = match n {
45                Normalized::DateIso { span, .. } => {
46                    (*span, "https://qualiadb.org/datatype/isoDate", "date")
47                }
48                Normalized::Number { span, unit, .. } => (
49                    *span,
50                    if unit.is_some() {
51                        "https://qualiadb.org/datatype/quantity"
52                    } else {
53                        "https://qualiadb.org/datatype/number"
54                    },
55                    "number",
56                ),
57            };
58            let slice = span.slice(source)?;
59            Some(AnnotationPlan {
60                term_iri: iri.to_string(),
61                start_utf8: span.start_utf8,
62                end_utf8: span.end_utf8,
63                content_hash: hash60(slice.as_bytes()),
64                source_hash,
65                surface: slice.to_string(),
66                kind,
67            })
68        })
69        .collect()
70}
71
72/// Doc span of an `AnnotationPlan`.
73pub fn span_of_plan(plan: &AnnotationPlan) -> DocSpan {
74    DocSpan::new(plan.start_utf8, plan.end_utf8)
75}
76
77#[cfg(test)]
78mod tests {
79    use super::*;
80    use crate::nlp::gazetteer::Gazetteer;
81    use crate::nlp::link::filter_known;
82    use crate::nlp::normalize::normalize_dates_and_numbers;
83
84    #[test]
85    fn plans_cover_lived_snippet() {
86        let src = "North Spring is the reference catchment. Timothy Charles Holborn recorded 12.5 mm of rain on 2026-08-15.";
87        let hits = filter_known(Gazetteer::default().find(src));
88        let mut plans = emit_from_hits(src, &hits);
89        plans.extend(emit_from_normalized(src, &normalize_dates_and_numbers(src)));
90        assert!(plans.iter().any(|p| p.term_iri.ends_with("NorthSpring")));
91        assert!(plans
92            .iter()
93            .any(|p| p.term_iri.contains("timothy_charles_holborn")));
94        assert!(plans.iter().any(|p| p.kind == "date"));
95        assert!(plans.iter().any(|p| p.kind == "number"));
96    }
97}