Skip to main content

qualia_core_db/nlp/
relation.rs

1//! Relation extraction — RDF-Star triple extraction via shallow patterns.
2//!
3//! Pattern-based, deterministic. Recognised patterns:
4//!   - "X is Y"        → (X, rdf:type, Y)
5//!   - "X has Y"       → (X, has, Y)
6//!   - "X located in Y"→ (X, locatedIn, Y)
7//!
8//! Subjects/objects are noun-phrase windows around the trigger; spans are
9//! exact byte offsets into the source. WASM-compatible, no LLM.
10
11use super::span::DocSpan;
12use super::tokenize::{tokenize, TokenKind};
13
14/// One extracted relation with subject/object provenance and a confidence.
15#[derive(Debug, Clone, PartialEq)]
16pub struct ExtractedRelation {
17    pub subject: String,
18    pub predicate: String,
19    pub object: String,
20    pub subject_span: DocSpan,
21    pub object_span: DocSpan,
22    pub confidence: f64,
23}
24
25/// Extract relations from `text`.
26pub fn extract_relations(text: &str) -> Vec<ExtractedRelation> {
27    let tokens = tokenize(text);
28    let mut out = Vec::new();
29    let mut i = 0;
30    while i < tokens.len() {
31        let tok = &tokens[i];
32        if tok.kind != TokenKind::Word {
33            i += 1;
34            continue;
35        }
36        let lower = tok.text.to_ascii_lowercase();
37        match lower.as_str() {
38            "is" => {
39                if let Some(rel) = relation_is_a(text, &tokens, i) {
40                    out.push(rel);
41                }
42                i += 1;
43            }
44            "has" => {
45                if let Some(rel) = relation_has(text, &tokens, i) {
46                    out.push(rel);
47                }
48                i += 1;
49            }
50            "located" => {
51                // Expect "located in".
52                if i + 1 < tokens.len()
53                    && tokens[i + 1].kind == TokenKind::Word
54                    && tokens[i + 1].text.eq_ignore_ascii_case("in")
55                {
56                    if let Some(rel) = relation_located_in(text, &tokens, i) {
57                        out.push(rel);
58                    }
59                    i += 2;
60                } else {
61                    i += 1;
62                }
63            }
64            _ => {
65                i += 1;
66            }
67        }
68    }
69    out
70}
71
72/// "X is Y" → (X, rdf:type, Y). X = noun window before "is", Y = noun window after.
73fn relation_is_a(
74    text: &str,
75    tokens: &[crate::nlp::tokenize::Token<'_>],
76    trig: usize,
77) -> Option<ExtractedRelation> {
78    let subj = noun_window_before(tokens, trig)?;
79    let obj = noun_window_after(tokens, trig + 1)?;
80    Some(ExtractedRelation {
81        subject: span_text(text, subj),
82        predicate: "rdf:type".to_string(),
83        object: span_text(text, obj),
84        subject_span: subj,
85        object_span: obj,
86        confidence: 0.9,
87    })
88}
89
90/// "X has Y" → (X, has, Y).
91fn relation_has(
92    text: &str,
93    tokens: &[crate::nlp::tokenize::Token<'_>],
94    trig: usize,
95) -> Option<ExtractedRelation> {
96    let subj = noun_window_before(tokens, trig)?;
97    let obj = noun_window_after(tokens, trig + 1)?;
98    Some(ExtractedRelation {
99        subject: span_text(text, subj),
100        predicate: "has".to_string(),
101        object: span_text(text, obj),
102        subject_span: subj,
103        object_span: obj,
104        confidence: 0.85,
105    })
106}
107
108/// "X located in Y" → (X, locatedIn, Y). Trigger occupies two tokens.
109fn relation_located_in(
110    text: &str,
111    tokens: &[crate::nlp::tokenize::Token<'_>],
112    trig: usize,
113) -> Option<ExtractedRelation> {
114    let subj = noun_window_before(tokens, trig)?;
115    let obj = noun_window_after(tokens, trig + 2)?;
116    Some(ExtractedRelation {
117        subject: span_text(text, subj),
118        predicate: "locatedIn".to_string(),
119        object: span_text(text, obj),
120        subject_span: subj,
121        object_span: obj,
122        confidence: 0.8,
123    })
124}
125
126/// Collect a contiguous noun window (word tokens, skipping leading
127/// determiners) ending just before `trig`. Returns the combined span.
128fn noun_window_before(tokens: &[crate::nlp::tokenize::Token<'_>], trig: usize) -> Option<DocSpan> {
129    let mut start: Option<usize> = None;
130    let mut end: Option<usize> = None;
131    for j in (0..trig).rev() {
132        let t = &tokens[j];
133        if t.kind == TokenKind::Word {
134            if is_det(t.text) {
135                continue;
136            }
137            start = Some(j);
138            if end.is_none() {
139                end = Some(j);
140            }
141        } else if end.is_some() {
142            break;
143        }
144    }
145    let (s, e) = (start?, end?);
146    Some(DocSpan::new(
147        tokens[s].span.start_utf8,
148        tokens[e].span.end_utf8,
149    ))
150}
151
152/// Collect a contiguous noun window starting just after `from`.
153fn noun_window_after(tokens: &[crate::nlp::tokenize::Token<'_>], from: usize) -> Option<DocSpan> {
154    let mut start: Option<usize> = None;
155    let mut end: Option<usize> = None;
156    let mut j = from;
157    while j < tokens.len() {
158        let t = &tokens[j];
159        if t.kind == TokenKind::Word {
160            if is_det(t.text) && start.is_none() {
161                j += 1;
162                continue;
163            }
164            if start.is_none() {
165                start = Some(j);
166            }
167            end = Some(j);
168            j += 1;
169        } else if start.is_some() {
170            break;
171        } else {
172            j += 1;
173        }
174    }
175    let (s, e) = (start?, end?);
176    Some(DocSpan::new(
177        tokens[s].span.start_utf8,
178        tokens[e].span.end_utf8,
179    ))
180}
181
182fn span_text(text: &str, span: DocSpan) -> String {
183    span.slice(text).unwrap_or("").to_string()
184}
185
186fn is_det(text: &str) -> bool {
187    matches!(text.to_ascii_lowercase().as_str(), "a" | "an" | "the")
188}
189
190#[cfg(test)]
191mod tests {
192    use super::*;
193
194    #[test]
195    fn is_a_relation() {
196        let src = "Socrates is a philosopher";
197        let rels = extract_relations(src);
198        assert_eq!(rels.len(), 1);
199        assert_eq!(rels[0].subject, "Socrates");
200        assert_eq!(rels[0].predicate, "rdf:type");
201        assert_eq!(rels[0].object, "philosopher");
202        assert_eq!(&src[rels[0].subject_span.as_range()], "Socrates");
203        assert_eq!(&src[rels[0].object_span.as_range()], "philosopher");
204    }
205
206    #[test]
207    fn has_relation() {
208        let src = "A cat has a tail";
209        let rels = extract_relations(src);
210        assert_eq!(rels.len(), 1);
211        assert_eq!(rels[0].subject, "cat");
212        assert_eq!(rels[0].predicate, "has");
213        assert_eq!(rels[0].object, "tail");
214    }
215
216    #[test]
217    fn located_in_relation() {
218        let src = "Paris located in France";
219        let rels = extract_relations(src);
220        assert_eq!(rels.len(), 1);
221        assert_eq!(rels[0].subject, "Paris");
222        assert_eq!(rels[0].predicate, "locatedIn");
223        assert_eq!(rels[0].object, "France");
224    }
225
226    #[test]
227    fn no_relation_for_plain_text() {
228        let rels = extract_relations("The quick brown fox jumps.");
229        assert!(rels.is_empty());
230    }
231
232    #[test]
233    fn multiple_relations() {
234        let src = "Socrates is a philosopher. A cat has a tail.";
235        let rels = extract_relations(src);
236        assert_eq!(rels.len(), 2);
237    }
238}