Skip to main content

qualia_core_db/nlp/contracts/
views.rs

1//! Copy view records. Surfaces are [`DocSpan`] slices of the original source.
2//!
3//! v1 is in-process Rust (interned `&'static str`, native `usize`). It is not a
4//! C FFI layout. Cross-language ABI notes belong to NLP-900.
5
6use super::error::NlpContractError;
7use crate::nlp::span::DocSpan;
8use crate::nlp::tokenize::TokenKind;
9
10/// Token with no containing sentence.
11pub const SENTENCE_ID_NONE: u32 = u32::MAX;
12/// Token with no overlapping normalized value.
13pub const NORM_INDEX_NONE: u32 = u32::MAX;
14
15/// Token borrowed from the original source. In-process Rust; not a C ABI.
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub struct TokenView {
18    pub span: DocSpan,
19    pub kind: TokenKind,
20    pub sentence_id: u32,
21    pub norm_index: u32,
22}
23
24impl TokenView {
25    pub const EMPTY: Self = Self {
26        span: DocSpan {
27            start_utf8: 0,
28            end_utf8: 0,
29        },
30        kind: TokenKind::Other,
31        sentence_id: SENTENCE_ID_NONE,
32        norm_index: NORM_INDEX_NONE,
33    };
34
35    /// Source text slice for this token span; error when out of range.
36    pub fn text(self, source: &str) -> Result<&str, NlpContractError> {
37        slice_source(self.span, source)
38    }
39}
40
41/// Sentence borrowed from the original source. In-process Rust; not a C ABI.
42#[derive(Debug, Clone, Copy, PartialEq, Eq)]
43pub struct SentenceView {
44    pub span: DocSpan,
45}
46
47impl SentenceView {
48    pub const EMPTY: Self = Self {
49        span: DocSpan {
50            start_utf8: 0,
51            end_utf8: 0,
52        },
53    };
54
55    /// Source text slice for this sentence.
56    pub fn text(self, source: &str) -> Result<&str, NlpContractError> {
57        slice_source(self.span, source)
58    }
59}
60
61/// Gazetteer hit; IRI and surface are interned lexicon pointers (fat pointers).
62#[derive(Debug, Clone, Copy, PartialEq, Eq)]
63pub struct HitView {
64    pub span: DocSpan,
65    pub iri: &'static str,
66    pub surface: &'static str,
67}
68
69impl HitView {
70    pub const EMPTY: Self = Self {
71        span: DocSpan {
72            start_utf8: 0,
73            end_utf8: 0,
74        },
75        iri: "",
76        surface: "",
77    };
78
79    /// Source text slice for this hit.
80    pub fn text(self, source: &str) -> Result<&str, NlpContractError> {
81        slice_source(self.span, source)
82    }
83}
84
85/// Date / number view. Values are fixed-width; units are interned.
86#[derive(Debug, Clone, Copy, PartialEq)]
87pub enum NormView {
88    DateIso {
89        span: DocSpan,
90        yyyy_mm_dd: [u8; 10],
91    },
92    Number {
93        span: DocSpan,
94        value: f64,
95        unit: Option<&'static str>,
96    },
97}
98
99impl NormView {
100    pub const EMPTY: Self = Self::DateIso {
101        span: DocSpan {
102            start_utf8: 0,
103            end_utf8: 0,
104        },
105        yyyy_mm_dd: [0; 10],
106    };
107
108    /// Document span of this normalization.
109    pub fn span(self) -> DocSpan {
110        match self {
111            Self::DateIso { span, .. } | Self::Number { span, .. } => span,
112        }
113    }
114
115    /// Source text slice for this normalization.
116    pub fn text(self, source: &str) -> Result<&str, NlpContractError> {
117        slice_source(self.span(), source)
118    }
119}
120
121/// Span plan without owned `String` surfaces. Interned `&'static str` is not C ABI.
122#[derive(Debug, Clone, Copy, PartialEq, Eq)]
123pub struct PlanView {
124    pub span: DocSpan,
125    pub content_hash: u64,
126    pub source_hash: u64,
127    pub term_iri: &'static str,
128    pub kind: &'static str,
129}
130
131impl PlanView {
132    pub const EMPTY: Self = Self {
133        span: DocSpan {
134            start_utf8: 0,
135            end_utf8: 0,
136        },
137        content_hash: 0,
138        source_hash: 0,
139        term_iri: "",
140        kind: "",
141    };
142
143    /// Source text slice for this plan.
144    pub fn text(self, source: &str) -> Result<&str, NlpContractError> {
145        slice_source(self.span, source)
146    }
147}
148
149/// Caller-owned output slices. Overflow is a typed error; counts are not
150/// written as a successful summary when any channel is short.
151pub struct DocumentViewBuffers<'a> {
152    pub tokens: &'a mut [TokenView],
153    pub sentences: &'a mut [SentenceView],
154    pub hits: &'a mut [HitView],
155    pub norms: &'a mut [NormView],
156    pub plans: &'a mut [PlanView],
157}
158
159/// Filled counts for a successful buffered analysis.
160///
161/// `usize` counts are native-width (32-bit on wasm32). v1 is not a C layout.
162#[derive(Debug, Clone, Copy, PartialEq, Eq)]
163pub struct DocumentSummary {
164    pub contract_version: u16,
165    pub source_hash: u64,
166    pub token_count: usize,
167    pub sentence_count: usize,
168    pub hit_count: usize,
169    pub norm_count: usize,
170    pub plan_count: usize,
171    pub state: super::error::AnalysisState,
172}
173
174/// Half-open UTF-8 byte span against `source`, or [`NlpContractError::SpanInvalid`].
175pub fn slice_source(span: DocSpan, source: &str) -> Result<&str, NlpContractError> {
176    span.slice(source).ok_or(NlpContractError::SpanInvalid {
177        start: span.start_utf8,
178        end: span.end_utf8,
179    })
180}