Skip to main content

wellfare_core/anatomy/
bridge.rs

1//! S4 (bridge) — map a person's **WellFair records → anatomy factors** via the knowledge base.
2//!
3//! The host layer (client-core) normalizes each health record into a [`RecordRef`] (its id, journal
4//! kind, human label, and — for the temporal view — when it happened and a dose scaler). This module,
5//! pure and testable, resolves each ref to a [`FactorKnowledge`](super::knowledge::FactorKnowledge)
6//! entry by kind + slugified label and instantiates a [`Factor`] or [`FactorEvent`]. Records with no
7//! matching knowledge entry are **reported, not silently dropped** — an honest "we don't have a
8//! mapping for this yet" (expected until Timothy's corpus lands for meds / diet / herbs).
9//!
10//! The knowledge lookup is by candidate keys per kind (e.g. a `"diet"` record tries `food:…`,
11//! `whole-food:…`, `herb:…`, `tea:…`, `supplement:…`), so one diet log can resolve to a food, a herb,
12//! or a tea entry without the host having to know which.
13
14use serde::{Deserialize, Serialize};
15
16use super::factor::Factor;
17use super::knowledge::KnowledgeBase;
18use super::lens::{AnatomyView, Lens, build_view};
19use super::temporal::Timeline;
20
21/// A normalized reference to one health record — the minimum the bridge needs.
22#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
23pub struct RecordRef {
24    pub id: String,
25    /// Journal kind: `"condition"`, `"medication"`, `"diet"`, `"clinical_report"`, etc.
26    pub kind: String,
27    /// Human label / name / description carried by the record.
28    pub label: String,
29    /// Timeline position in minutes (for the temporal view); `None` = treat as standing/non-temporal.
30    #[serde(default, skip_serializing_if = "Option::is_none")]
31    pub at_minute: Option<i64>,
32    /// Dose scaler for the temporal event (percent; `None` = 100).
33    #[serde(default, skip_serializing_if = "Option::is_none")]
34    pub dose_scale_pct: Option<u32>,
35}
36
37impl RecordRef {
38    /// Creates a new instance.
39    pub fn new(id: impl Into<String>, kind: impl Into<String>, label: impl Into<String>) -> Self {
40        Self {
41            id: id.into(),
42            kind: kind.into(),
43            label: label.into(),
44            at_minute: None,
45            dose_scale_pct: None,
46        }
47    }
48
49    /// Element access.
50    pub fn at(mut self, at_minute: i64) -> Self {
51        self.at_minute = Some(at_minute);
52        self
53    }
54
55    ///  when dosed.
56    pub fn dosed(mut self, dose_scale_pct: u32) -> Self {
57        self.dose_scale_pct = Some(dose_scale_pct);
58        self
59    }
60}
61
62/// Candidate knowledge-key prefixes to try for a given journal kind, most specific first.
63fn key_prefixes(kind: &str) -> &'static [&'static str] {
64    match kind {
65        "condition" | "disputed_diagnosis" => &["cond"],
66        "medication" | "med_administration" => &["med"],
67        // A diet log could be any ingestible — try the food/botanical/supplement families.
68        "diet" | "food" | "nutrition" => &[
69            "food",
70            "whole-food",
71            "herb",
72            "tea",
73            "supplement",
74            "nutrient",
75        ],
76        "herb" => &["herb"],
77        "tea" => &["tea"],
78        "supplement" => &["supplement"],
79        "nutrient" => &["nutrient"],
80        _ => &[],
81    }
82}
83
84/// The knowledge key candidates for a record (kind-appropriate prefixes × slugified label).
85pub fn knowledge_key_candidates(kind: &str, label: &str) -> Vec<String> {
86    let slug = super::slugify(label);
87    if slug.is_empty() {
88        return Vec::new();
89    }
90    key_prefixes(kind)
91        .iter()
92        .map(|p| format!("{p}:{slug}"))
93        .collect()
94}
95
96/// The outcome of mapping records to factors: what resolved, and what didn't (honestly surfaced).
97#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
98pub struct BridgeResult {
99    pub factors: Vec<Factor>,
100    /// `(kind, label)` of records with no knowledge mapping — shown as "not mapped yet", not dropped.
101    pub unmapped: Vec<(String, String)>,
102}
103
104/// Map records to non-temporal [`Factor`]s via the knowledge base. Each factor keeps the record's id
105/// (so a view can trace back to the source record).
106pub fn records_to_factors(records: &[RecordRef], kb: &KnowledgeBase) -> BridgeResult {
107    let mut result = BridgeResult::default();
108    for r in records {
109        match resolve(kb, &r.kind, &r.label) {
110            Some(entry) => result.factors.push(entry.to_factor(r.id.clone())),
111            None => result.unmapped.push((r.kind.clone(), r.label.clone())),
112        }
113    }
114    result
115}
116
117/// Map records to a temporal [`Timeline`] via the knowledge base (uses each record's `at_minute` /
118/// `dose_scale_pct`, defaulting to 0 / 100). Unmapped records are returned alongside.
119pub fn records_to_timeline(
120    records: &[RecordRef],
121    kb: &KnowledgeBase,
122) -> (Timeline, Vec<(String, String)>) {
123    let mut tl = Timeline::new();
124    let mut unmapped = Vec::new();
125    for r in records {
126        match resolve(kb, &r.kind, &r.label) {
127            Some(entry) => {
128                let ev = entry.to_event(
129                    r.id.clone(),
130                    r.at_minute.unwrap_or(0),
131                    r.dose_scale_pct.unwrap_or(100),
132                );
133                tl = tl.with_event(ev);
134            }
135            None => unmapped.push((r.kind.clone(), r.label.clone())),
136        }
137    }
138    (tl, unmapped)
139}
140
141/// One-shot: records → factors → an [`AnatomyView`] for a lens. Returns the view plus the unmapped set.
142pub fn build_view_from_records(
143    records: &[RecordRef],
144    kb: &KnowledgeBase,
145    lens: Lens,
146    convergence_threshold: usize,
147) -> (AnatomyView, Vec<(String, String)>) {
148    let bridge = records_to_factors(records, kb);
149    let view = build_view(&bridge.factors, lens, convergence_threshold);
150    (view, bridge.unmapped)
151}
152
153fn resolve<'a>(
154    kb: &'a KnowledgeBase,
155    kind: &str,
156    label: &str,
157) -> Option<&'a super::knowledge::FactorKnowledge> {
158    knowledge_key_candidates(kind, label)
159        .into_iter()
160        .find_map(|k| kb.get(&k))
161}
162
163#[cfg(test)]
164mod tests {
165    use super::*;
166    use crate::anatomy::seed_knowledge_base;
167
168    #[test]
169    fn candidate_keys_are_kind_appropriate() {
170        assert_eq!(
171            knowledge_key_candidates("condition", "Type 2 Diabetes"),
172            vec!["cond:type-2-diabetes"]
173        );
174        assert_eq!(
175            knowledge_key_candidates("medication", "Warfarin"),
176            vec!["med:warfarin"]
177        );
178        // A diet log fans out across ingestible families.
179        let diet = knowledge_key_candidates("diet", "Chamomile");
180        assert!(diet.contains(&"tea:chamomile".to_string()));
181        assert!(diet.contains(&"food:chamomile".to_string()));
182        // An empty/punctuation-only label yields no candidates.
183        assert!(knowledge_key_candidates("diet", "  ").is_empty());
184    }
185
186    #[test]
187    fn records_resolve_against_the_seed_and_report_unmapped() {
188        let kb = seed_knowledge_base();
189        let records = vec![
190            RecordRef::new("rec:beer-1", "diet", "Beer"),
191            RecordRef::new("rec:mt-1", "diet", "Milk thistle"),
192            RecordRef::new("rec:unknown", "medication", "Some Med We Lack"),
193        ];
194        let res = records_to_factors(&records, &kb);
195        // Beer (food:beer) and milk thistle (herb:milk-thistle) resolve; the unknown med does not.
196        assert_eq!(res.factors.len(), 2);
197        assert!(res.factors.iter().any(|f| f.id == "rec:beer-1"));
198        assert!(res.factors.iter().any(|f| f.id == "rec:mt-1"));
199        assert_eq!(
200            res.unmapped,
201            vec![("medication".to_string(), "Some Med We Lack".to_string())]
202        );
203    }
204
205    #[test]
206    fn beer_label_resolves_via_slug_match() {
207        // The seed key is "food:beer" with label "Beer (alcohol)" → slug "beer-alcohol" would NOT match.
208        // The bridge slugs the *record* label, so the record must be "Beer" to hit "food:beer".
209        let kb = seed_knowledge_base();
210        let hit = records_to_factors(&[RecordRef::new("r", "diet", "Beer")], &kb);
211        assert_eq!(hit.factors.len(), 1, "record label 'Beer' → food:beer");
212        let miss = records_to_factors(&[RecordRef::new("r", "diet", "Beer (alcohol)")], &kb);
213        assert_eq!(
214            miss.factors.len(),
215            0,
216            "the fuller label slugs differently — honestly unmapped"
217        );
218        assert_eq!(miss.unmapped.len(), 1);
219    }
220
221    #[test]
222    fn temporal_bridge_builds_a_timeline_that_loads_systems() {
223        let kb = seed_knowledge_base();
224        let records = vec![
225            RecordRef::new("r:beer", "diet", "Beer").at(0).dosed(300),
226            RecordRef::new("r:water", "diet", "Water + electrolytes").at(120),
227        ];
228        let (tl, unmapped) = records_to_timeline(&records, &kb);
229        assert!(unmapped.is_empty());
230        let dig = tl
231            .burden_at(60)
232            .into_iter()
233            .find(|b| b.system_id == "digestive")
234            .unwrap();
235        assert!(dig.net_milli > 0);
236    }
237
238    #[test]
239    fn end_to_end_person_view_from_records() {
240        let kb = seed_knowledge_base();
241        let records = vec![RecordRef::new("r:beer", "diet", "Beer")];
242        let (view, unmapped) = build_view_from_records(&records, &kb, Lens::Person, 1);
243        assert!(unmapped.is_empty());
244        // Beer loads digestive + urinary; the person view lists them plainly.
245        assert!(view.systems.iter().any(|s| s.system_id == "digestive"));
246        assert!(view.boundary.contains("not medical advice"));
247    }
248}