Skip to main content

qualia_core_db/nlp/
frame.rs

1//! Frame semantics — basic frame element identification.
2//!
3//! A small built-in frame lexicon (BUY, TRANSFER) is matched against lexical
4//! triggers (e.g. "bought", "gave"). When a trigger fires, the surrounding
5//! clause is scanned for role fillers using shallow syntactic cues
6//! (prepositions "from"/"to", subject/object position). All extracted
7//! elements carry exact byte-span provenance.
8//!
9//! Deterministic, WASM-compatible, no LLM.
10
11use super::span::DocSpan;
12use super::tokenize::{tokenize, TokenKind};
13
14/// One frame element: a role label and the text filling it, with provenance.
15#[derive(Debug, Clone, PartialEq, Eq)]
16pub struct FrameElement {
17    pub role: String,
18    pub text: String,
19    pub span: DocSpan,
20}
21
22/// One instantiated frame (a trigger + its filled elements).
23#[derive(Debug, Clone, PartialEq, Eq)]
24pub struct FrameInstance {
25    pub frame_type: String,
26    pub elements: Vec<FrameElement>,
27}
28
29/// A lexical trigger for a frame.
30struct Trigger {
31    /// Lowercased surface that fires the frame.
32    surface: &'static str,
33    frame_type: &'static str,
34    /// Roles filled by the clause, in canonical order.
35    roles: &'static [&'static str],
36}
37
38const BUY_TRIGGER: Trigger = Trigger {
39    surface: "bought",
40    frame_type: "BUY",
41    roles: &["buyer", "goods", "seller"],
42};
43
44const TRANSFER_TRIGGER: Trigger = Trigger {
45    surface: "gave",
46    frame_type: "TRANSFER",
47    roles: &["donor", "recipient", "theme"],
48};
49
50const TRIGGERS: &[&Trigger] = &[&BUY_TRIGGER, &TRANSFER_TRIGGER];
51
52/// Extract frame instances from `text`.
53pub fn extract_frames(text: &str) -> Vec<FrameInstance> {
54    let tokens = tokenize(text);
55    let mut out = Vec::new();
56    for (i, tok) in tokens.iter().enumerate() {
57        if tok.kind != TokenKind::Word {
58            continue;
59        }
60        let lower = tok.text.to_ascii_lowercase();
61        let trig = TRIGGERS.iter().find(|t| t.surface == lower.as_str());
62        let Some(trig) = trig else { continue };
63        let elements = match trig.frame_type {
64            "BUY" => extract_buy(text, &tokens, i),
65            "TRANSFER" => extract_transfer(text, &tokens, i),
66            _ => Vec::new(),
67        };
68        let elements = elements
69            .into_iter()
70            .filter(|e| trig.roles.contains(&e.role.as_str()))
71            .collect();
72        out.push(FrameInstance {
73            frame_type: trig.frame_type.to_string(),
74            elements,
75        });
76    }
77    out
78}
79
80/// BUY frame: buyer = subject before "bought", goods = object after,
81/// seller = noun after "from".
82fn extract_buy(
83    text: &str,
84    tokens: &[crate::nlp::tokenize::Token<'_>],
85    trig: usize,
86) -> Vec<FrameElement> {
87    let mut els = Vec::new();
88    // buyer: nearest preceding word token.
89    if let Some(buyer) = last_word_before(tokens, trig) {
90        els.push(make_element("buyer", text, buyer));
91    }
92    // goods: first word token after the trigger (skip leading determiner "a"/"the").
93    if let Some(goods) = first_word_after(tokens, trig) {
94        els.push(make_element("goods", text, goods));
95    }
96    // seller: word token after "from".
97    if let Some(from_pos) = find_word(tokens, "from", trig + 1) {
98        if let Some(seller) = first_word_after(tokens, from_pos) {
99            els.push(make_element("seller", text, seller));
100        }
101    }
102    els
103}
104
105/// TRANSFER frame: donor = subject before "gave", recipient = noun after "to",
106/// theme = noun between "gave" and "to".
107fn extract_transfer(
108    text: &str,
109    tokens: &[crate::nlp::tokenize::Token<'_>],
110    trig: usize,
111) -> Vec<FrameElement> {
112    let mut els = Vec::new();
113    if let Some(donor) = last_word_before(tokens, trig) {
114        els.push(make_element("donor", text, donor));
115    }
116    // theme: first word after trigger (until "to").
117    let to_pos = find_word(tokens, "to", trig + 1);
118    if let Some(theme) = first_word_after(tokens, trig) {
119        els.push(make_element("theme", text, theme));
120    }
121    if let Some(tp) = to_pos {
122        if let Some(recipient) = first_word_after(tokens, tp) {
123            els.push(make_element("recipient", text, recipient));
124        }
125    }
126    els
127}
128
129fn make_element(role: &str, _text: &str, tok: &crate::nlp::tokenize::Token<'_>) -> FrameElement {
130    FrameElement {
131        role: role.to_string(),
132        text: tok.text.to_string(),
133        span: tok.span,
134    }
135}
136
137fn last_word_before<'a>(
138    tokens: &'a [crate::nlp::tokenize::Token<'a>],
139    idx: usize,
140) -> Option<&'a crate::nlp::tokenize::Token<'a>> {
141    (0..idx).rev().find_map(|i| {
142        let t = &tokens[i];
143        (t.kind == TokenKind::Word && !is_det(t.text)).then_some(t)
144    })
145}
146
147fn first_word_after<'a>(
148    tokens: &'a [crate::nlp::tokenize::Token<'a>],
149    idx: usize,
150) -> Option<&'a crate::nlp::tokenize::Token<'a>> {
151    (idx + 1..tokens.len()).find_map(|i| {
152        let t = &tokens[i];
153        (t.kind == TokenKind::Word && !is_det(t.text)).then_some(t)
154    })
155}
156
157fn find_word(
158    tokens: &[crate::nlp::tokenize::Token<'_>],
159    surface: &str,
160    from: usize,
161) -> Option<usize> {
162    (from..tokens.len()).find(|&i| {
163        tokens[i].kind == TokenKind::Word && tokens[i].text.eq_ignore_ascii_case(surface)
164    })
165}
166
167fn is_det(text: &str) -> bool {
168    matches!(text.to_ascii_lowercase().as_str(), "a" | "an" | "the")
169}
170
171#[cfg(test)]
172mod tests {
173    use super::*;
174
175    #[test]
176    fn buy_frame_full() {
177        let src = "John bought a book from Mary";
178        let frames = extract_frames(src);
179        assert_eq!(frames.len(), 1);
180        assert_eq!(frames[0].frame_type, "BUY");
181        let roles: Vec<_> = frames[0].elements.iter().map(|e| e.role.as_str()).collect();
182        assert!(roles.contains(&"buyer"));
183        assert!(roles.contains(&"goods"));
184        assert!(roles.contains(&"seller"));
185        let buyer = frames[0]
186            .elements
187            .iter()
188            .find(|e| e.role == "buyer")
189            .unwrap();
190        assert_eq!(buyer.text, "John");
191        assert_eq!(&src[buyer.span.as_range()], "John");
192        let goods = frames[0]
193            .elements
194            .iter()
195            .find(|e| e.role == "goods")
196            .unwrap();
197        assert_eq!(goods.text, "book");
198        let seller = frames[0]
199            .elements
200            .iter()
201            .find(|e| e.role == "seller")
202            .unwrap();
203        assert_eq!(seller.text, "Mary");
204    }
205
206    #[test]
207    fn transfer_frame() {
208        let src = "Mary gave John a book";
209        let frames = extract_frames(src);
210        assert_eq!(frames.len(), 1);
211        assert_eq!(frames[0].frame_type, "TRANSFER");
212        let donor = frames[0]
213            .elements
214            .iter()
215            .find(|e| e.role == "donor")
216            .unwrap();
217        assert_eq!(donor.text, "Mary");
218    }
219
220    #[test]
221    fn transfer_frame_with_to() {
222        let src = "Mary gave a book to John";
223        let frames = extract_frames(src);
224        assert_eq!(frames.len(), 1);
225        let recipient = frames[0]
226            .elements
227            .iter()
228            .find(|e| e.role == "recipient")
229            .unwrap();
230        assert_eq!(recipient.text, "John");
231    }
232
233    #[test]
234    fn no_frame_for_unrelated_text() {
235        let frames = extract_frames("The sky is blue today.");
236        assert!(frames.is_empty());
237    }
238
239    #[test]
240    fn span_provenance_exact() {
241        let src = "John bought a book from Mary";
242        let frames = extract_frames(src);
243        let seller = frames[0]
244            .elements
245            .iter()
246            .find(|e| e.role == "seller")
247            .unwrap();
248        assert_eq!(&src[seller.span.as_range()], "Mary");
249    }
250}