Skip to main content

qualia_core_db/nlp/coref/
mod.rs

1//! Bounded coreference: exact-string grouping plus an experimental pronoun sieve.
2//!
3//! NLP-001 is a resource/contract repair, not a coreference-quality claim.
4//! Exact surface grouping is not identity. The name-to-gender list is
5//! experimental and must not emit personal gender or identity facts.
6//! Substrate mention generation is still one-word-per-mention; NLP-500/NLP-501
7//! replace the detector and heuristic. Empty mention lists skip detection.
8
9mod error;
10mod limits;
11mod resolve;
12mod validate;
13
14pub use error::CorefError;
15pub use limits::{
16    fnv1a64, workspace_bytes_required, CancellationToken, CorefLimits, CorefWorkStats,
17    DEFAULT_MAX_ANTECEDENTS_PER_PRONOUN, DEFAULT_MAX_ANTECEDENT_CHECKS, DEFAULT_MAX_CHAINS,
18    DEFAULT_MAX_MENTIONS, DEFAULT_MAX_MENTION_TEXT_BYTES, DEFAULT_MAX_SOURCE_BYTES,
19    DEFAULT_MAX_WORKSPACE_BYTES, SENTINEL_BYTES,
20};
21pub use resolve::resolve_coreferences_into;
22pub use validate::{
23    aggregate_mention_text_bytes, mention_kind_from_label, offset_from_i64, offset_from_u64,
24    preflight_counts, validate_mention, validate_mentions,
25};
26
27use crate::nlp::span::DocSpan;
28
29/// Coarse mention kind, used by the pronoun sieve for agreement.
30#[derive(Debug, Clone, Copy, PartialEq, Eq)]
31#[repr(u8)]
32pub enum MentionKind {
33    Pronoun = 0,
34    Proper = 1,
35    Common = 2,
36}
37
38impl MentionKind {
39    /// Views `self` as `label`.
40    pub fn as_label(self) -> &'static str {
41        match self {
42            Self::Pronoun => "pronoun",
43            Self::Proper => "proper",
44            Self::Common => "common",
45        }
46    }
47}
48
49/// One coreference mention with byte-span provenance. Cold/host form.
50#[derive(Debug, Clone, PartialEq, Eq)]
51pub struct CorefMention {
52    pub span: DocSpan,
53    pub text: String,
54    pub kind: MentionKind,
55}
56
57/// A resolved coreference chain: all mentions judged co-referent.
58#[derive(Debug, Clone, PartialEq, Eq)]
59pub struct CorefChain {
60    pub id: u32,
61    pub mentions: Vec<CorefMention>,
62}
63
64/// Validated mention used on the hot path. Text is the source slice.
65#[derive(Debug, Clone, Copy, PartialEq, Eq)]
66#[repr(C)]
67pub struct ValidatedMention {
68    pub start: u32,
69    pub end: u32,
70    pub kind: MentionKind,
71}
72
73impl ValidatedMention {
74    /// Doc span of the mention.
75    pub fn span(self) -> DocSpan {
76        DocSpan::new(self.start, self.end)
77    }
78}
79
80/// Per-mention scratch record. Caller-owned; zero-initialized then filled.
81#[derive(Debug, Clone, Copy, Default)]
82#[repr(C)]
83pub struct MentionWork {
84    pub parent: u32,
85    pub hash: u64,
86    pub norm_off: u32,
87    pub norm_len: u32,
88    pub scratch: u32,
89}
90
91/// Caller-owned hot-path workspace.
92pub struct CorefScratch<'a> {
93    pub work: &'a mut [MentionWork],
94    pub order: &'a mut [u32],
95    pub gather: &'a mut [u32],
96    pub norm: &'a mut [u8],
97}
98
99impl CorefScratch<'_> {
100    /// `provided` size in bytes.
101    pub fn provided_bytes(&self) -> usize {
102        core::mem::size_of_val(self.work)
103            .saturating_add(core::mem::size_of_val(self.order))
104            .saturating_add(core::mem::size_of_val(self.gather))
105            .saturating_add(self.norm.len())
106    }
107}
108
109/// Chain header written into a caller buffer.
110#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
111#[repr(C)]
112pub struct CorefChainHead {
113    pub id: u32,
114    pub mention_start: u32,
115    pub mention_count: u32,
116}
117
118/// Cold adapter: validate, allocate scratch, resolve, materialize chains.
119///
120/// Errors are never converted into an empty success. Empty `mentions` is a
121/// documented no-detection mode and returns zero chains.
122pub fn resolve_coreferences(
123    source: &str,
124    mentions: &[CorefMention],
125) -> Result<Vec<CorefChain>, CorefError> {
126    resolve_coreferences_counted(
127        source,
128        mentions,
129        &CorefLimits::DEFAULT,
130        &CancellationToken::new(),
131    )
132    .map(|(chains, _)| chains)
133}
134
135/// Cold adapter that also returns work counters.
136pub fn resolve_coreferences_counted(
137    source: &str,
138    mentions: &[CorefMention],
139    limits: &CorefLimits,
140    cancel: &CancellationToken,
141) -> Result<(Vec<CorefChain>, CorefWorkStats), CorefError> {
142    let text_bytes = aggregate_mention_text_bytes(mentions, limits.max_mention_text_bytes)?;
143    preflight_counts(source, mentions.len(), text_bytes, limits)?;
144    if mentions.is_empty() {
145        return Ok((Vec::new(), CorefWorkStats::default()));
146    }
147    let mut validated = vec![
148        ValidatedMention {
149            start: 0,
150            end: 0,
151            kind: MentionKind::Common
152        };
153        mentions.len()
154    ];
155    validate_mentions(source, mentions, &mut validated)?;
156    let norm_cap = text_bytes;
157    let required = workspace_bytes_required(mentions.len(), norm_cap);
158    if required > limits.max_workspace_bytes {
159        return Err(CorefError::WorkspaceTooSmall {
160            required,
161            provided: limits.max_workspace_bytes,
162        });
163    }
164    let mut work = vec![MentionWork::default(); mentions.len()];
165    let mut order = vec![0u32; mentions.len()];
166    let mut gather = vec![0u32; mentions.len()];
167    let mut norm = vec![0u8; norm_cap];
168    let mut scratch = CorefScratch {
169        work: &mut work,
170        order: &mut order,
171        gather: &mut gather,
172        norm: &mut norm,
173    };
174    let mut heads =
175        vec![CorefChainHead::default(); core::cmp::min(mentions.len(), limits.max_chains)];
176    let mut ids = vec![0u32; mentions.len()];
177    let mut stats = CorefWorkStats::default();
178    let chain_count = resolve_coreferences_into(
179        source,
180        &validated,
181        limits,
182        &mut scratch,
183        &mut heads,
184        &mut ids,
185        cancel,
186        &mut stats,
187    )?;
188    let mut chains = Vec::with_capacity(chain_count);
189    for head in heads.iter().take(chain_count) {
190        let start = head.mention_start as usize;
191        let count = head.mention_count as usize;
192        let mut chain_mentions = Vec::with_capacity(count);
193        for &mention_index in ids[start..start + count].iter() {
194            chain_mentions.push(mentions[mention_index as usize].clone());
195        }
196        chains.push(CorefChain {
197            id: head.id,
198            mentions: chain_mentions,
199        });
200    }
201    Ok((chains, stats))
202}
203
204#[cfg(test)]
205mod tests;