Skip to main content

qualia_mcp/tools/
living_cosmic.rs

1//! MCP tools for 0.0.41 Living-World Biological/Anatomical Engines, Etalon-Vibe SDK
2//! Parity Dispatch, and Omniversal Cosmic Coordinate Systems (OCS v2.2.0).
3//!
4//! Follows `AGENTS.md` §0-B (<500 lines) and §0-A (zero-heap hot-path calls).
5
6use crate::types::{parse_tool_args, McpSystemError};
7use qualia_core_db::modalities::biological_ontology::{
8    find_pin_by_id, find_pins_by_scale, query_closest_anatomical_pin_zero_heap,
9    CANONICAL_ANATOMICAL_PINS,
10};
11use qualia_core_db::render::botanical_anatomy::{
12    root_flare_radius, GOLDEN_ANGLE_RAD, PIPE_EXPONENT_EUCALYPTUS,
13};
14use qualia_core_db::render::skeletal::fauna_rig::{FAUNA_MAX_JOINTS, FAUNA_PARENT_INDICES};
15use qualia_core_db::render::vertebrate_anatomy::{
16    evaluate_anatomical_layer_peel_zero_heap, ZoologicalAnatomicalLayer,
17};
18use serde_json::{json, Value};
19use vibe::cosmic::{
20    celestial::{body_profile_by_name, pulsar_dispersion_delay_s},
21    flrw::observe_redshift,
22    nested::compute_healpix_index,
23    usri::g_coord_realm_to_realm_class,
24    warp::{cochrane_units, warp_velocity, WarpScale},
25};
26use vibe::extension_registry::{ExtensionRegistry, BUILTIN_EXTENSION_ALIASES};
27
28/// `etalon_vibe_sdk` — Inspect the 11 Etalon-Vibe SDK providers, 37 extension descriptors, and 5-field `NQuin48` parity.
29pub fn etalon_vibe_sdk(raw_args: &[u8]) -> Result<String, McpSystemError> {
30    let v = parse_tool_args(raw_args)?;
31    let filter_alias = v.get("provider").and_then(Value::as_str);
32    let registry = ExtensionRegistry::with_builtin_providers();
33
34    let mut providers = Vec::new();
35    for &alias in BUILTIN_EXTENSION_ALIASES {
36        if let Some(target) = filter_alias {
37            if !alias.eq_ignore_ascii_case(target) {
38                continue;
39            }
40        }
41        let Some((_, provider, descriptor)) = registry.find_by_namespace_or_alias(alias) else {
42            return Err(McpSystemError::ExecutionFailed(format!(
43                "Provider '{alias}' missing from ExtensionRegistry"
44            )));
45        };
46        let quins = provider.static_ontology_nquins();
47        let parity_ok = quins.iter().all(|q| q.verify_parity());
48        let functions: Vec<Value> = descriptor
49            .sub_namespaces
50            .iter()
51            .flat_map(|ns| {
52                ns.functions.iter().map(move |f| {
53                    json!({
54                        "path": format!("{alias}.{}.{}", ns.name, f.name),
55                        "iri": f.canonical_iri.iri,
56                        "effects": f.effects.0,
57                        "output_elements": f.required_output_elems,
58                        "max_ticks": f.envelope.max_ticks,
59                        "max_output_bytes": f.envelope.max_output_bytes,
60                    })
61                })
62            })
63            .collect();
64        providers.push(json!({
65            "alias": alias,
66            "iri": descriptor.canonical_iri.iri,
67            "targets": descriptor.supported_targets.0,
68            "ontology_quins": quins.len(),
69            "five_field_parity_valid": parity_ok,
70            "functions": functions,
71        }));
72    }
73
74    Ok(json!({
75        "status": "ok",
76        "schema": "qualia.etalon-vibe-sdk/v1",
77        "provider_count": registry.active_count(),
78        "providers": providers,
79    })
80    .to_string())
81}
82
83/// `living_world_anatomy` — Query botanical/vertebrate anatomical pins, zero-heap ray-sphere Loupe picking,
84/// botanical root-flare allometry, and 3-layer vertebrate osteology/myology/integument peel.
85pub fn living_world_anatomy(raw_args: &[u8]) -> Result<String, McpSystemError> {
86    let v = parse_tool_args(raw_args)?;
87    let op = v.get("op").and_then(Value::as_str).unwrap_or("catalog");
88
89    match op {
90        "catalog" | "pins" => {
91            let scale = v.get("scale").and_then(Value::as_u64).unwrap_or(0) as u8;
92            let pins: Vec<Value> = if (1..=5).contains(&scale) {
93                find_pins_by_scale(scale)
94                    .map(|p| {
95                        json!({
96                            "pin_id": p.pin_id,
97                            "scale": p.scale,
98                            "curie": p.ontology_curie,
99                            "scientific_term": p.scientific_term,
100                            "anchor_xyz": p.anchor_local_xyz,
101                        })
102                    })
103                    .collect()
104            } else {
105                CANONICAL_ANATOMICAL_PINS
106                    .iter()
107                    .map(|p| {
108                        json!({
109                            "pin_id": p.pin_id,
110                            "scale": p.scale,
111                            "curie": p.ontology_curie,
112                            "scientific_term": p.scientific_term,
113                            "anchor_xyz": p.anchor_local_xyz,
114                        })
115                    })
116                    .collect()
117            };
118            Ok(json!({
119                "status": "ok",
120                "op": op,
121                "scale_filter": scale,
122                "pin_count": pins.len(),
123                "pins": pins,
124                "botanical_constants": {
125                    "golden_angle_rad": GOLDEN_ANGLE_RAD,
126                    "pipe_exponent_eucalyptus": PIPE_EXPONENT_EUCALYPTUS,
127                },
128                "vertebrate_rig": {
129                    "max_joints": FAUNA_MAX_JOINTS,
130                    "parent_indices": FAUNA_PARENT_INDICES,
131                }
132            })
133            .to_string())
134        }
135        "pin_by_id" => {
136            let id = v
137                .get("pin_id")
138                .and_then(Value::as_str)
139                .ok_or(McpSystemError::InvalidParameters)?;
140            let Some(pin) = find_pin_by_id(id) else {
141                return Err(McpSystemError::ExecutionFailed(format!(
142                    "Unknown pin_id: {id}"
143                )));
144            };
145            Ok(json!({
146                "status": "ok",
147                "pin_id": pin.pin_id,
148                "scale": pin.scale,
149                "curie": pin.ontology_curie,
150                "iri": pin.full_ontology_iri(),
151                "scientific_term": pin.scientific_term,
152                "anchor_xyz": pin.anchor_local_xyz,
153                "normal_xyz": pin.normal_xyz,
154                "biophysical_formula": pin.biophysical_formula,
155                "summary": pin.educational_summary,
156                "indigenous_custodial_context": pin.indigenous_custodial_context,
157            })
158            .to_string())
159        }
160        "ray_pick" => {
161            let scale = v.get("scale").and_then(Value::as_u64).unwrap_or(0) as u8;
162            let origin = parse_vec3(&v, "ray_origin", [0.0, 0.0, 5.0]);
163            let dir = parse_vec3(&v, "ray_dir", [0.0, 0.0, -1.0]);
164            let max_dist = v.get("max_dist").and_then(Value::as_f64).unwrap_or(10.0) as f32;
165            let hit = query_closest_anatomical_pin_zero_heap(scale, origin, dir, max_dist);
166            Ok(json!({
167                "status": "ok",
168                "op": "ray_pick",
169                "hit": hit.map(|p| json!({
170                    "pin_id": p.pin_id,
171                    "scale": p.scale,
172                    "curie": p.ontology_curie,
173                    "scientific_term": p.scientific_term,
174                    "anchor_xyz": p.anchor_local_xyz,
175                })),
176            })
177            .to_string())
178        }
179        "root_flare" => {
180            let base_r = v.get("base_radius").and_then(Value::as_f64).unwrap_or(0.45);
181            let depth_m = v.get("depth_m").and_then(Value::as_f64).unwrap_or(0.2);
182            let factor = v.get("flare_factor").and_then(Value::as_f64).unwrap_or(0.6);
183            let r = root_flare_radius(base_r, depth_m, factor);
184            Ok(json!({
185                "status": "ok",
186                "op": "root_flare",
187                "radius_m": r,
188            })
189            .to_string())
190        }
191        "layer_peel" => {
192            let ost = v.get("osteology_vis").and_then(Value::as_f64).unwrap_or(1.0) as f32;
193            let myo = v.get("myology_vis").and_then(Value::as_f64).unwrap_or(0.5) as f32;
194            let int = v.get("integument_vis").and_then(Value::as_f64).unwrap_or(0.15) as f32;
195            let explode = v.get("explode").and_then(Value::as_f64).unwrap_or(0.5) as f32;
196            let in_pos = [[0.0f32, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 2.0, 0.0]];
197            let in_nrm = [[0.0f32, 1.0, 0.0]; 3];
198            let tags = [
199                ZoologicalAnatomicalLayer::Osteology,
200                ZoologicalAnatomicalLayer::MyologyAndTendons,
201                ZoologicalAnatomicalLayer::ExternalIntegument,
202            ];
203            let mut out_pos = [[0.0f32; 3]; 3];
204            let mut out_alpha = [0.0f32; 3];
205            let n = evaluate_anatomical_layer_peel_zero_heap(
206                &in_pos, &in_nrm, &tags, ost, myo, int, explode, &mut out_pos, &mut out_alpha,
207            );
208            Ok(json!({
209                "status": "ok",
210                "op": "layer_peel",
211                "evaluated_vertices": n,
212                "displaced_positions": out_pos,
213                "layer_alphas": out_alpha,
214            })
215            .to_string())
216        }
217        other => Err(McpSystemError::ExecutionFailed(format!(
218            "Unsupported living_world_anatomy op: {other}"
219        ))),
220    }
221}
222
223fn parse_vec3(v: &Value, key: &str, default: [f32; 3]) -> [f32; 3] {
224    let Some(arr) = v.get(key).and_then(Value::as_array) else {
225        return default;
226    };
227    if arr.len() < 3 {
228        return default;
229    }
230    [
231        arr[0].as_f64().unwrap_or(default[0] as f64) as f32,
232        arr[1].as_f64().unwrap_or(default[1] as f64) as f32,
233        arr[2].as_f64().unwrap_or(default[2] as f64) as f32,
234    ]
235}
236
237/// `cosmic_coordinates` — Omniversal Coordinate System (OCS v2.2.0): celestial profiles,
238/// FLRW redshift cosmology, pulsar dispersion delay, warp velocity, HEALPix, and USRI realms.
239pub fn cosmic_coordinates(raw_args: &[u8]) -> Result<String, McpSystemError> {
240    let v = parse_tool_args(raw_args)?;
241    let op = v.get("op").and_then(Value::as_str).unwrap_or("celestial_profile");
242
243    let allowed: &[&str] = match op {
244        "celestial_profile" => &["op", "body"],
245        "redshift" => &["op", "z"],
246        "pulsar_dispersion" => &["op", "dm_pc_cm3", "freq_hz"],
247        "warp" => &["op", "warp_factor", "scale"],
248        "healpix" => &["op", "x", "y", "z", "nside"],
249        "usri_realm" => &["op", "realm"],
250        _ => &[],
251    };
252    if v.as_object().is_some_and(|map| map.keys().any(|key| !allowed.contains(&key.as_str()))) {
253        return Err(McpSystemError::ExecutionFailed(format!("Unknown argument for cosmic_coordinates({op}); HEALPix uses integer z, not total_z")));
254    }
255    for key in ["z", "dm_pc_cm3", "freq_hz", "warp_factor", "x", "y", "nside"] {
256        if v.get(key).is_some_and(|value| !value.is_number()) {
257            return Err(McpSystemError::InvalidParameters);
258        }
259    }
260    for key in ["body", "scale", "realm"] {
261        if v.get(key).is_some_and(|value| !value.is_string()) {
262            return Err(McpSystemError::InvalidParameters);
263        }
264    }
265    if v.get("scale").is_some_and(|scale| !matches!(scale.as_str(), Some("tos" | "tng"))) {
266        return Err(McpSystemError::InvalidParameters);
267    }
268
269    match op {
270        "celestial_profile" => {
271            let name = v.get("body").and_then(Value::as_str).unwrap_or("earth");
272            let Some(profile) = body_profile_by_name(name) else {
273                return Err(McpSystemError::ExecutionFailed(format!(
274                    "Unknown celestial body: {name}"
275                )));
276            };
277            Ok(json!({
278                "status": "ok",
279                "op": "celestial_profile",
280                "body": profile.name,
281                "usri": profile.usri,
282                "equatorial_radius_m": profile.equatorial_radius_m,
283                "rotation_period_s": profile.rotation_period_s,
284                "mass_kg": profile.mass_kg,
285                "surface_gravity_m_s2": profile.surface_gravity(),
286            })
287            .to_string())
288        }
289        "redshift" => {
290            let z = v.get("z").and_then(Value::as_f64).unwrap_or(1.0);
291            let obs = observe_redshift(z);
292            Ok(json!({
293                "status": "ok",
294                "op": "redshift",
295                "z": obs.z,
296                "comoving_distance_mpc": obs.comoving_distance_mpc,
297                "physical_distance_mpc": obs.physical_distance_mpc,
298                "recession_velocity_km_s": obs.recession_velocity_km_s,
299            })
300            .to_string())
301        }
302        "pulsar_dispersion" => {
303            let dm = v.get("dm_pc_cm3").and_then(Value::as_f64).unwrap_or(50.0);
304            let freq = v.get("freq_hz").and_then(Value::as_f64).unwrap_or(1.4e9);
305            let delay = pulsar_dispersion_delay_s(dm, freq)
306                .map_err(|e| McpSystemError::ExecutionFailed(e.to_string()))?;
307            Ok(json!({
308                "status": "ok",
309                "op": "pulsar_dispersion",
310                "dm_pc_cm3": dm,
311                "freq_hz": freq,
312                "delay_seconds": delay,
313            })
314            .to_string())
315        }
316        "warp" => {
317            let factor = v.get("warp_factor").and_then(Value::as_f64).unwrap_or(5.0);
318            let scale = match v.get("scale").and_then(Value::as_str).unwrap_or("tng") {
319                "tos" => WarpScale::Tos,
320                _ => WarpScale::Tng,
321            };
322            Ok(json!({
323                "status": "ok",
324                "op": "warp",
325                "warp_factor": factor,
326                "velocity_m_s": warp_velocity(factor, scale),
327                "cochrane_multiple_c": cochrane_units(factor, scale),
328            })
329            .to_string())
330        }
331        "healpix" => {
332            if v.get("nside").is_some_and(|value| value.as_u64().is_none()) {
333                return Err(McpSystemError::InvalidParameters);
334            }
335            for key in ["x", "y", "z"] {
336                if v.get(key).is_some_and(|value| value.as_i64().is_none()) {
337                    return Err(McpSystemError::InvalidParameters);
338                }
339            }
340            let x = v.get("x").and_then(Value::as_i64).unwrap_or(1);
341            let y = v.get("y").and_then(Value::as_i64).unwrap_or(2);
342            let z = v.get("z").and_then(Value::as_i64).unwrap_or(3);
343            let nside = v.get("nside").and_then(Value::as_u64).unwrap_or(64);
344            if nside == 0 || !nside.is_power_of_two() || nside > (1 << 29) {
345                return Err(McpSystemError::InvalidParameters);
346            }
347            let idx = compute_healpix_index([x, y, z], nside);
348            Ok(json!({
349                "status": "ok",
350                "op": "healpix",
351                "nside": nside,
352                "healpix_index": idx,
353            })
354            .to_string())
355        }
356        "usri_realm" => {
357            let realm = v.get("realm").and_then(Value::as_str).unwrap_or("g_coord_terrestrial");
358            let mapped = g_coord_realm_to_realm_class(realm).map(|r| format!("{r:?}"));
359            Ok(json!({
360                "status": "ok",
361                "op": "usri_realm",
362                "realm": realm,
363                "realm_class": mapped,
364            })
365            .to_string())
366        }
367        other => Err(McpSystemError::ExecutionFailed(format!(
368            "Unsupported cosmic_coordinates op: {other}"
369        ))),
370    }
371}
372
373#[cfg(test)]
374mod tests {
375    use super::*;
376
377    #[test]
378    fn healpix_contract_uses_integer_z_and_rejects_ignored_aliases() {
379        let valid: Value = serde_json::from_str(&cosmic_coordinates(br#"{"op":"healpix","x":1,"y":2,"z":900,"nside":64}"#).unwrap()).unwrap();
380        assert_eq!(valid["status"], "ok");
381        assert!(cosmic_coordinates(br#"{"op":"healpix","total_z":900}"#).is_err());
382        assert!(cosmic_coordinates(br#"{"op":"healpix","z":1.5}"#).is_err());
383        assert!(cosmic_coordinates(br#"{"op":"healpix","nside":0}"#).is_err());
384        assert!(cosmic_coordinates(br#"{"op":"healpix","nside":3}"#).is_err());
385        let schema: Value = serde_json::from_str(crate::registry::stable_mcp_tools().iter().find(|t| t.name == "cosmic_coordinates").unwrap().input_schema).unwrap();
386        assert!(schema["properties"].get("total_z").is_none());
387        assert_eq!(schema["allOf"][0]["then"]["properties"]["z"]["type"], "integer");
388    }
389
390    #[test]
391    fn test_etalon_vibe_sdk_mcp_tool() {
392        let out = etalon_vibe_sdk(b"{}").unwrap();
393        let v: Value = serde_json::from_str(&out).unwrap();
394        assert_eq!(v["status"], "ok");
395        assert_eq!(v["provider_count"], 11);
396    }
397
398    #[test]
399    fn test_living_world_anatomy_and_cosmic_mcp_tools() {
400        let out = living_world_anatomy(br#"{"op":"catalog","scale":4}"#).unwrap();
401        let v: Value = serde_json::from_str(&out).unwrap();
402        assert_eq!(v["status"], "ok");
403        assert!(v["pin_count"].as_u64().unwrap() > 0);
404
405        let peel = living_world_anatomy(br#"{"op":"layer_peel","explode":0.5}"#).unwrap();
406        let pv: Value = serde_json::from_str(&peel).unwrap();
407        assert_eq!(pv["evaluated_vertices"], 3);
408
409        let cos = cosmic_coordinates(br#"{"op":"redshift","z":2.0}"#).unwrap();
410        let cv: Value = serde_json::from_str(&cos).unwrap();
411        assert_eq!(cv["status"], "ok");
412        assert!(cv["comoving_distance_mpc"].as_f64().unwrap() > 0.0);
413    }
414}