Skip to main content

qualia_mcp/tools/
sim_fire_ecology.rs

1//! MCP tools for Fire Ecology, Dead Fuel Moisture, and Byram Fireline Intensity.
2//!
3//! Powered by `qualia-sim::fire_ecology`.
4//! Designed according to `AGENTS.md` ยง0-B (<500 lines).
5
6use crate::types::{parse_tool_args, McpSystemError};
7use qualia_sim::fire_ecology::{
8    evaluate_dead_fine_fuel_moisture, evaluate_fireline_intensity, FirelineRegime,
9    ForestFuelStratum, FuelMoistureState,
10};
11use serde_json::{json, Value};
12
13fn parse_forest_stratum(v: &Value) -> ForestFuelStratum {
14    let years = v.get("years_since_fire").and_then(Value::as_f64).unwrap_or(8.0) as f32;
15    ForestFuelStratum::mature_dry_sclerophyll(years)
16}
17
18/// `sim_evaluate_fuel_stratum` tool โ€” calculates multi-stratum Olson fuel accumulation across post-fire succession.
19pub fn evaluate_fuel_stratum_tool(args: &[u8]) -> Result<String, McpSystemError> {
20    let v = parse_tool_args(args)?;
21    let stratum = parse_forest_stratum(&v);
22
23    let payload = json!({
24        "surfaceLitterTonsHa": stratum.surface_litter_t_ha,
25        "nearSurfaceGrassTonsHa": stratum.near_surface_grass_t_ha,
26        "elevatedShrubTonsHa": stratum.elevated_shrub_t_ha,
27        "barkHazardScore": stratum.bark_hazard_score,
28        "canopyFoliageTonsHa": stratum.canopy_foliage_t_ha,
29        "totalFineFuelKgM2": stratum.total_fine_fuel_kg_m2(),
30    });
31    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
32}
33
34/// `sim_evaluate_dead_fuel_moisture` tool โ€” models dead fine fuel moisture (DFMC) from vapor pressure deficit and solar drying.
35pub fn evaluate_dead_fuel_moisture_tool(args: &[u8]) -> Result<String, McpSystemError> {
36    let v = parse_tool_args(args)?;
37    let temp = v.get("temp_c").and_then(Value::as_f64).unwrap_or(32.0) as f32;
38    let rh = v.get("relative_humidity_pct").and_then(Value::as_f64).unwrap_or(22.0) as f32 / 100.0;
39    let rad = v.get("solar_radiation_wm2").and_then(Value::as_f64).unwrap_or(850.0) as f32;
40    let kbdi = v.get("kbdi_drought_index").and_then(Value::as_f64).unwrap_or(120.0) as f32;
41
42    let dfmc = evaluate_dead_fine_fuel_moisture(temp, rh, rad, kbdi);
43
44    let payload = json!({
45        "deadFineFuelMoistureFraction": dfmc,
46        "deadFineFuelMoisturePct": dfmc * 100.0,
47        "isFlammable": dfmc < 0.16,
48        "extinguishmentState": dfmc >= 0.16,
49        "criticalCrownRisk": dfmc < 0.05,
50    });
51    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
52}
53
54/// `sim_evaluate_fire_behavior` tool โ€” calculates rate of spread, Byram's fireline intensity, crown fire initiation, and spotting.
55pub fn evaluate_fire_behavior_tool(args: &[u8]) -> Result<String, McpSystemError> {
56    let v = parse_tool_args(args)?;
57    let stratum = parse_forest_stratum(&v);
58    let dfmc = v.get("dead_fuel_moisture_pct").and_then(Value::as_f64).unwrap_or(6.5) as f32 / 100.0;
59    let kbdi = v.get("kbdi").and_then(Value::as_f64).unwrap_or(85.0) as f32;
60    let curing = v.get("curing_pct").and_then(Value::as_f64).unwrap_or(65.0) as f32;
61    let moisture = FuelMoistureState {
62        dead_fuel_moisture_fraction: dfmc,
63        kbdi_drought_index: kbdi,
64        grass_curing_percentage: curing,
65    };
66    let wind_speed_km_h = v.get("wind_speed_10m_km_h").and_then(Value::as_f64).unwrap_or(35.0) as f32;
67    let wind_m_s = wind_speed_km_h / 3.6;
68    let slope = v.get("slope_degrees").and_then(Value::as_f64).unwrap_or(5.0) as f32;
69
70    let behavior = evaluate_fireline_intensity(&stratum, &moisture, wind_m_s, slope);
71
72    let payload = json!({
73        "regime": format!("{:?}", behavior.regime),
74        "rateOfSpreadMPerS": behavior.forward_spread_rate_m_s,
75        "rateOfSpreadKmPerHour": behavior.forward_spread_rate_m_s * 3.6,
76        "firelineIntensityKwPerM": behavior.fireline_intensity_kw_m,
77        "fuelConsumedKgM2": behavior.fuel_consumed_kg_m2,
78        "flameLengthMeters": behavior.flame_length_m,
79        "barkSpottingDistanceKm": behavior.spotting_distance_km,
80        "isCatastrophicCrowning": matches!(behavior.regime, FirelineRegime::CatastrophicCrowningPyroCb),
81    });
82    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
83}
84
85pub use evaluate_fire_behavior_tool as sim_fire_ecology_eval;
86pub use evaluate_fuel_stratum_tool as sim_fuel_stratum_eval;
87pub use evaluate_dead_fuel_moisture_tool as sim_dead_fuel_moisture_eval;