qualia_core_db/nlp/coref/
mod.rs1mod 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#[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 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#[derive(Debug, Clone, PartialEq, Eq)]
51pub struct CorefMention {
52 pub span: DocSpan,
53 pub text: String,
54 pub kind: MentionKind,
55}
56
57#[derive(Debug, Clone, PartialEq, Eq)]
59pub struct CorefChain {
60 pub id: u32,
61 pub mentions: Vec<CorefMention>,
62}
63
64#[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 pub fn span(self) -> DocSpan {
76 DocSpan::new(self.start, self.end)
77 }
78}
79
80#[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
91pub 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 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#[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
118pub 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
135pub 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;