Skip to main content

qualia_client_core/wellfair/
ccf_resolver.rs

1//! Discover the CCF/HRA reference-organ GLB assets from the Human Reference Atlas **SPARQL endpoint**
2//! (the scalable, canonical source — no repo clone, no Git-LFS pointers). The HRA Knowledge Graph
3//! registers each reference organ as linked data; the GLB lives as a `foaf:depiction` `xsd:anyURI`
4//! pointing at `cdn.humanatlas.io` (the real binary). The CDN path encodes organ, sex, and version, so
5//! the discovered filename (e.g. `3d-vh-m-liver.glb`) feeds straight into
6//! [`body_system_for_organ`](wellfare_core::anatomy::body_system_for_organ) and
7//! [`compile_body`](super::anatomy_body::compile_body).
8//!
9//! This module is **pure** (query construction + result parsing + model filtering) — no HTTP, so it is
10//! unit-tested against captured real endpoint JSON. The live GET + the per-organ binary fetch are a thin
11//! transport layer (qualia-client-core's async HTTP is a separate lane); this owns the semantics.
12
13use serde::{Deserialize, Serialize};
14use wellfare_core::anatomy::AnatomyModel;
15
16/// The HRA Linked Open Data SPARQL endpoint (verified live: returns `application/sparql-results+json`).
17pub const HRA_SPARQL_ENDPOINT: &str = "https://lod.humanatlas.io/sparql";
18
19/// A descriptive User-Agent. Some asset hosts (e.g. NIH 3D's WAF) reject requests with **no**
20/// User-Agent (reqwest sends none by default) with a 403 — an explicit one is required.
21const HTTP_USER_AGENT: &str = "QualiaDB-anatomy/1.0";
22
23/// The query that lists every reference-organ GLB URL registered in the HRA KG (across named graphs).
24/// Bound variable is `glb`. Deterministic ordering so the manifest is stable/attestable.
25pub fn ref_organ_glb_query() -> String {
26    "SELECT DISTINCT ?glb WHERE { \
27       GRAPH ?g { ?s <http://xmlns.com/foaf/0.1/depiction> ?glb } \
28       FILTER(STRENDS(LCASE(STR(?glb)), \".glb\") && CONTAINS(STR(?glb), \"/ref-organ/\")) \
29     } ORDER BY ?glb"
30        .to_string()
31}
32
33/// One discovered reference-organ asset: the GLB filename (the organ key used everywhere downstream),
34/// its canonical CDN URL, and which reference model it belongs to.
35#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
36pub struct RefOrgan {
37    /// The GLB filename, e.g. `3d-vh-m-liver.glb` — this is the `organ_key` for `body_system_for_organ`.
38    pub filename: String,
39    /// The canonical CDN URL of the binary GLB.
40    pub glb_url: String,
41    /// The reference model this organ belongs to (from the `-f-`/`-m-` sex marker in the filename).
42    pub model: AnatomyModel,
43}
44
45/// Parse the SPARQL-results JSON from [`ref_organ_glb_query`] into the reference-organ manifest.
46///
47/// The sex/model is read from the unambiguous `-f-`/`-m-` filename infix (provider varies — `vh`,
48/// `allen`, `sbu`, `nih` — but the sex marker does not). A GLB with no sex infix (rare; unsexed asset)
49/// is skipped rather than guessed. Malformed JSON yields an empty manifest.
50pub fn parse_ref_organs(sparql_json: &str) -> Vec<RefOrgan> {
51    let root: serde_json::Value = match serde_json::from_str(sparql_json) {
52        Ok(v) => v,
53        Err(_) => return Vec::new(),
54    };
55    let bindings = root
56        .get("results")
57        .and_then(|r| r.get("bindings"))
58        .and_then(|b| b.as_array());
59    let mut out = Vec::new();
60    if let Some(bindings) = bindings {
61        for b in bindings {
62            let Some(url) = b
63                .get("glb")
64                .and_then(|g| g.get("value"))
65                .and_then(|v| v.as_str())
66            else {
67                continue;
68            };
69            let filename = url.rsplit('/').next().unwrap_or(url).to_string();
70            let Some(model) = model_from_filename(&filename) else {
71                continue;
72            };
73            out.push(RefOrgan {
74                filename,
75                glb_url: url.to_string(),
76                model,
77            });
78        }
79    }
80    out
81}
82
83/// The reference model a CCF GLB filename belongs to, from its `-f-`/`-m-` sex infix.
84fn model_from_filename(filename: &str) -> Option<AnatomyModel> {
85    if filename.contains("-f-") {
86        Some(AnatomyModel::Female)
87    } else if filename.contains("-m-") {
88        Some(AnatomyModel::Male)
89    } else {
90        None
91    }
92}
93
94/// The organs of a single model, in discovery order.
95pub fn organs_for_model(organs: &[RefOrgan], model: AnatomyModel) -> Vec<RefOrgan> {
96    organs
97        .iter()
98        .filter(|o| o.model == model)
99        .cloned()
100        .collect()
101}
102
103/// A live CCF discovery / fetch error.
104#[cfg(not(target_arch = "wasm32"))]
105#[derive(Debug)]
106pub enum CcfError {
107    Http(reqwest::Error),
108}
109
110#[cfg(not(target_arch = "wasm32"))]
111impl std::fmt::Display for CcfError {
112    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
113        match self {
114            CcfError::Http(e) => write!(f, "CCF HTTP: {e}"),
115        }
116    }
117}
118
119#[cfg(not(target_arch = "wasm32"))]
120impl std::error::Error for CcfError {}
121
122#[cfg(not(target_arch = "wasm32"))]
123impl From<reqwest::Error> for CcfError {
124    fn from(e: reqwest::Error) -> Self {
125        CcfError::Http(e)
126    }
127}
128
129/// Discover the reference-organ manifest **live** from the HRA SPARQL endpoint (blocking network I/O —
130/// call off the async runtime, e.g. via `spawn_blocking`). The query/parse are pure and unit-tested;
131/// this only adds the transport. If the live endpoint returns an HTTP error (e.g. 502 Bad Gateway)
132/// or times out, it gracefully falls back to the embedded CCF reference-organ manifest.
133#[cfg(not(target_arch = "wasm32"))]
134pub fn discover_ref_organs(endpoint: &str) -> Result<Vec<RefOrgan>, CcfError> {
135    let client = reqwest::blocking::Client::builder()
136        .timeout(std::time::Duration::from_secs(12))
137        .build()
138        .unwrap_or_default();
139
140    let res = client
141        .post(endpoint)
142        .header(reqwest::header::USER_AGENT, HTTP_USER_AGENT)
143        .header(reqwest::header::CONTENT_TYPE, "application/sparql-query")
144        .header(reqwest::header::ACCEPT, "application/sparql-results+json")
145        .body(ref_organ_glb_query())
146        .send();
147
148    match res {
149        Ok(resp) if resp.status().is_success() => {
150            if let Ok(text) = resp.text() {
151                let organs = parse_ref_organs(&text);
152                if !organs.is_empty() {
153                    return Ok(organs);
154                }
155            }
156        }
157        Ok(resp) => {
158            eprintln!(
159                "Warning: HRA SPARQL endpoint '{endpoint}' returned status {}. Falling back to embedded CCF manifest.",
160                resp.status()
161            );
162            return Ok(fallback_ref_organs());
163        }
164        Err(e) => {
165            eprintln!(
166                "Warning: HRA SPARQL endpoint '{endpoint}' unreachable ({e}). Falling back to embedded CCF manifest."
167            );
168            return Ok(fallback_ref_organs());
169        }
170    }
171    Ok(fallback_ref_organs())
172}
173
174/// Embedded fallback list of canonical CCF/HRA reference organ GLBs on `cdn.humanatlas.io`.
175/// Used automatically when the live SPARQL endpoint is temporarily down (e.g. 502 Bad Gateway).
176pub fn fallback_ref_organs() -> Vec<RefOrgan> {
177    const FALLBACK_MANIFEST: &[(&str, &str, AnatomyModel)] = &[
178        // Male organs
179        ("3d-vh-m-brain.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/brain-male/v1.2/assets/3d-vh-m-brain.glb", AnatomyModel::Male),
180        ("3d-vh-m-heart.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/heart-male/v1.2/assets/3d-vh-m-heart.glb", AnatomyModel::Male),
181        ("3d-vh-m-lung-l.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/lung-male-left/v1.2/assets/3d-vh-m-lung-l.glb", AnatomyModel::Male),
182        ("3d-vh-m-lung-r.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/lung-male-right/v1.2/assets/3d-vh-m-lung-r.glb", AnatomyModel::Male),
183        ("3d-vh-m-liver.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/liver-male/v1.2/assets/3d-vh-m-liver.glb", AnatomyModel::Male),
184        ("3d-vh-m-kidney-l.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-male-left/v1.3/assets/3d-vh-m-kidney-l.glb", AnatomyModel::Male),
185        ("3d-vh-m-kidney-r.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-male-right/v1.3/assets/3d-vh-m-kidney-r.glb", AnatomyModel::Male),
186        ("3d-vh-m-spleen.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/spleen-male/v1.2/assets/3d-vh-m-spleen.glb", AnatomyModel::Male),
187        ("3d-vh-m-pancreas.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/pancreas-male/v1.2/assets/3d-vh-m-pancreas.glb", AnatomyModel::Male),
188        ("3d-vh-m-small-intestine.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/small-intestine-male/v1.2/assets/3d-vh-m-small-intestine.glb", AnatomyModel::Male),
189        ("3d-vh-m-large-intestine.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/large-intestine-male/v1.2/assets/3d-vh-m-large-intestine.glb", AnatomyModel::Male),
190        ("3d-vh-m-urinary-bladder.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/urinary-bladder-male/v1.2/assets/3d-vh-m-urinary-bladder.glb", AnatomyModel::Male),
191        ("3d-vh-m-prostate.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/prostate-male/v1.2/assets/3d-vh-m-prostate.glb", AnatomyModel::Male),
192        ("3d-vh-m-trachea.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/trachea-male/v1.2/assets/3d-vh-m-trachea.glb", AnatomyModel::Male),
193        ("3d-vh-m-larynx.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/larynx-male/v1.2/assets/3d-vh-m-larynx.glb", AnatomyModel::Male),
194        ("3d-vh-m-main-bronchus.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/main-bronchus-male/v1.2/assets/3d-vh-m-main-bronchus.glb", AnatomyModel::Male),
195        ("3d-vh-m-thymus.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/thymus-male/v1.2/assets/3d-vh-m-thymus.glb", AnatomyModel::Male),
196        ("3d-vh-m-eye-l.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/eye-male-left/v1.2/assets/3d-vh-m-eye-l.glb", AnatomyModel::Male),
197        ("3d-vh-m-eye-r.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/eye-male-right/v1.2/assets/3d-vh-m-eye-r.glb", AnatomyModel::Male),
198        ("3d-vh-m-pelvis.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/pelvis-male/v1.2/assets/3d-vh-m-pelvis.glb", AnatomyModel::Male),
199        ("3d-vh-m-skin.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/skin-male/v1.2/assets/3d-vh-m-skin.glb", AnatomyModel::Male),
200        ("3d-vh-m-blood-vasculature.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/blood-vasculature-male/v1.2/assets/3d-vh-m-blood-vasculature.glb", AnatomyModel::Male),
201
202        // Female organs
203        ("3d-vh-f-brain.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/brain-female/v1.2/assets/3d-vh-f-brain.glb", AnatomyModel::Female),
204        ("3d-vh-f-heart.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/heart-female/v1.2/assets/3d-vh-f-heart.glb", AnatomyModel::Female),
205        ("3d-vh-f-lung-l.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/lung-female-left/v1.2/assets/3d-vh-f-lung-l.glb", AnatomyModel::Female),
206        ("3d-vh-f-lung-r.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/lung-female-right/v1.2/assets/3d-vh-f-lung-r.glb", AnatomyModel::Female),
207        ("3d-vh-f-liver.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/liver-female/v1.2/assets/3d-vh-f-liver.glb", AnatomyModel::Female),
208        ("3d-vh-f-kidney-l.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb", AnatomyModel::Female),
209        ("3d-vh-f-kidney-r.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-right/v1.3/assets/3d-vh-f-kidney-r.glb", AnatomyModel::Female),
210        ("3d-vh-f-spleen.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/spleen-female/v1.2/assets/3d-vh-f-spleen.glb", AnatomyModel::Female),
211        ("3d-vh-f-pancreas.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/pancreas-female/v1.2/assets/3d-vh-f-pancreas.glb", AnatomyModel::Female),
212        ("3d-vh-f-small-intestine.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/small-intestine-female/v1.2/assets/3d-vh-f-small-intestine.glb", AnatomyModel::Female),
213        ("3d-vh-f-large-intestine.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/large-intestine-female/v1.2/assets/3d-vh-f-large-intestine.glb", AnatomyModel::Female),
214        ("3d-vh-f-urinary-bladder.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/urinary-bladder-female/v1.2/assets/3d-vh-f-urinary-bladder.glb", AnatomyModel::Female),
215        ("3d-vh-f-uterus.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/uterus-female/v1.2/assets/3d-vh-f-uterus.glb", AnatomyModel::Female),
216        ("3d-vh-f-ovary-l.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/ovary-female-left/v1.2/assets/3d-vh-f-ovary-l.glb", AnatomyModel::Female),
217        ("3d-vh-f-ovary-r.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/ovary-female-right/v1.2/assets/3d-vh-f-ovary-r.glb", AnatomyModel::Female),
218        ("3d-vh-f-fallopian-tube-l.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/fallopian-tube-female-left/v1.2/assets/3d-vh-f-fallopian-tube-l.glb", AnatomyModel::Female),
219        ("3d-vh-f-fallopian-tube-r.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/fallopian-tube-female-right/v1.2/assets/3d-vh-f-fallopian-tube-r.glb", AnatomyModel::Female),
220        ("3d-vh-f-vagina.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/vagina-female/v1.2/assets/3d-vh-f-vagina.glb", AnatomyModel::Female),
221        ("3d-vh-f-trachea.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/trachea-female/v1.2/assets/3d-vh-f-trachea.glb", AnatomyModel::Female),
222        ("3d-vh-f-larynx.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/larynx-female/v1.2/assets/3d-vh-f-larynx.glb", AnatomyModel::Female),
223        ("3d-vh-f-main-bronchus.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/main-bronchus-female/v1.2/assets/3d-vh-f-main-bronchus.glb", AnatomyModel::Female),
224        ("3d-vh-f-thymus.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/thymus-female/v1.2/assets/3d-vh-f-thymus.glb", AnatomyModel::Female),
225        ("3d-vh-f-eye-l.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/eye-female-left/v1.2/assets/3d-vh-f-eye-l.glb", AnatomyModel::Female),
226        ("3d-vh-f-eye-r.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/eye-female-right/v1.2/assets/3d-vh-f-eye-r.glb", AnatomyModel::Female),
227        ("3d-vh-f-pelvis.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/pelvis-female/v1.2/assets/3d-vh-f-pelvis.glb", AnatomyModel::Female),
228        ("3d-vh-f-skin.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/skin-female/v1.2/assets/3d-vh-f-skin.glb", AnatomyModel::Female),
229        ("3d-vh-f-blood-vasculature.glb", "https://cdn.humanatlas.io/digital-objects/ref-organ/blood-vasculature-female/v1.2/assets/3d-vh-f-blood-vasculature.glb", AnatomyModel::Female),
230    ];
231
232    FALLBACK_MANIFEST
233        .iter()
234        .map(|(filename, url, model)| RefOrgan {
235            filename: filename.to_string(),
236            glb_url: url.to_string(),
237            model: *model,
238        })
239        .collect()
240}
241
242/// Fetch one organ's GLB bytes from its CDN URL (blocking).
243#[cfg(not(target_arch = "wasm32"))]
244pub fn fetch_glb(glb_url: &str) -> Result<Vec<u8>, CcfError> {
245    let bytes = reqwest::blocking::Client::builder()
246        .timeout(std::time::Duration::from_secs(180))
247        .build()?
248        .get(glb_url)
249        .header(reqwest::header::USER_AGENT, HTTP_USER_AGENT)
250        .send()?
251        .error_for_status()?
252        .bytes()?;
253    Ok(bytes.to_vec())
254}
255
256#[cfg(test)]
257mod tests {
258    use super::*;
259
260    // A captured, real fragment of the HRA endpoint response (three bindings — a male organ, a
261    // lateralized female organ, and a female-only organ).
262    const SAMPLE_JSON: &str = r#"{
263      "head": { "vars": ["glb"] },
264      "results": { "bindings": [
265        { "glb": { "datatype": "http://www.w3.org/2001/XMLSchema#anyURI", "type": "literal",
266          "value": "https://cdn.humanatlas.io/digital-objects/ref-organ/liver-male/v1.2/assets/3d-vh-m-liver.glb" } },
267        { "glb": { "datatype": "http://www.w3.org/2001/XMLSchema#anyURI", "type": "literal",
268          "value": "https://cdn.humanatlas.io/digital-objects/ref-organ/kidney-female-left/v1.3/assets/3d-vh-f-kidney-l.glb" } },
269        { "glb": { "datatype": "http://www.w3.org/2001/XMLSchema#anyURI", "type": "literal",
270          "value": "https://cdn.humanatlas.io/digital-objects/ref-organ/uterus-female/v1.2/assets/3d-vh-f-uterus.glb" } }
271      ]}
272    }"#;
273
274    #[test]
275    fn query_is_stable_and_targets_ref_organ_depictions() {
276        let q = ref_organ_glb_query();
277        assert!(q.contains("foaf/0.1/depiction"));
278        assert!(q.contains("/ref-organ/"));
279        assert!(q.contains("ORDER BY ?glb"), "deterministic manifest");
280    }
281
282    #[test]
283    fn parses_real_endpoint_json_into_typed_manifest() {
284        let organs = parse_ref_organs(SAMPLE_JSON);
285        assert_eq!(organs.len(), 3);
286        // Filename is the downstream organ key; the CDN URL is the real binary.
287        assert_eq!(organs[0].filename, "3d-vh-m-liver.glb");
288        assert!(organs[0].glb_url.starts_with("https://cdn.humanatlas.io/"));
289        // Sex/model read from the -m-/-f- infix.
290        assert_eq!(organs[0].model, AnatomyModel::Male);
291        assert_eq!(organs[1].model, AnatomyModel::Female);
292        assert_eq!(organs[2].model, AnatomyModel::Female);
293    }
294
295    #[test]
296    fn model_filter_splits_the_body() {
297        let organs = parse_ref_organs(SAMPLE_JSON);
298        assert_eq!(organs_for_model(&organs, AnatomyModel::Male).len(), 1);
299        assert_eq!(organs_for_model(&organs, AnatomyModel::Female).len(), 2);
300    }
301
302    #[test]
303    fn discovered_filenames_resolve_to_body_systems() {
304        // The whole point: a SPARQL-discovered filename feeds straight into the organ→system map.
305        use wellfare_core::anatomy::body_system_for_organ;
306        let organs = parse_ref_organs(SAMPLE_JSON);
307        assert_eq!(
308            body_system_for_organ(&organs[0].filename),
309            Some("digestive")
310        ); // liver
311        assert_eq!(body_system_for_organ(&organs[1].filename), Some("urinary")); // kidney
312        assert_eq!(
313            body_system_for_organ(&organs[2].filename),
314            Some("reproductive")
315        ); // uterus
316    }
317
318    #[test]
319    fn malformed_json_and_unsexed_assets_are_handled() {
320        assert!(parse_ref_organs("not json").is_empty());
321        // An asset with no -f-/-m- infix is skipped, not guessed.
322        let no_sex = r#"{"results":{"bindings":[
323          {"glb":{"type":"literal","value":"https://cdn.humanatlas.io/digital-objects/ref-organ/x/v1/assets/3d-vh-mystery.glb"}}
324        ]}}"#;
325        assert!(parse_ref_organs(no_sex).is_empty());
326    }
327}