Overview
ColdMesh serves three LightGBM models trained for organ transplant logistics. Clients post JSON feature payloads and receive either quantile minutes (q10_min, q50_min, q90_min) or a diversion success_probability. The live Zi Humana console composes dwell + travel against ischaemic remaining time to surface best / median / worst cold-chain margins.
- Dwell-time — 22-feature quantile regressor for recipient facility handover
- Travel-time — 12-feature quantile regressor for corridor transit
- Locker diversion — binary success classifier for alternate handoff
Authentication
Requests accept an x-api-key header. The public demo console uses a research prototype key suitable for evaluation traffic. Production deployments should rotate keys via environment configuration (COLDMESH_DEMO_API_KEY / upstream backend policy).
x-api-key: <your-api-key> Content-Type: application/json Accept: application/json
Same-origin proxy
Browser clients should call the Zi Humana proxy at /api/coldmesh/*. The route forwards to the StochVRP-Mesh backend and injects the demo key when none is supplied.
GET /api/coldmesh/health POST /api/coldmesh/predict/dwell_advanced POST /api/coldmesh/predict/travel_time POST /api/coldmesh/predict/locker_advanced
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /health | Model readiness / service heartbeat |
POST | /predict/dwell_advanced | Facility handover dwell quantiles (min) |
POST | /predict/travel_time | Travel-time quantiles (min) |
POST | /predict/locker_advanced | Locker diversion success probability |
POST /predict/dwell_advanced
Predicts recipient-facility handover time under protocol, security, preservation, traffic, weather, and temporal context. Cyclic encodings for hour / day / month are derived client-side in the console.
Representative fields
{
"building_type": 2,
"organ_type": 1,
"security_level": 1,
"staff_shift": 0,
"handover_protocol": 1,
"preservation_method": 0,
"elevator_available": 1,
"floor_number": 4,
"distance_to_opc_km": 15,
"urban_density": 4000,
"traffic_congestion": 5,
"weather_severity": 4,
"ischaemic_remaining_min": 600,
"hour_sin": 0.5,
"hour_cos": 0.866
}Response
{
"q10_min": 18.2,
"q50_min": 27.5,
"q90_min": 41.0,
"interval_width_min": 22.8,
"interpretation": "moderate handover risk"
}POST /predict/travel_time
Estimates corridor transit under density, distance, road type, weather, traffic, holiday, and peak-hour flags. Used with dwell to build the cold-chain countdown against ischaemic remaining time.
{
"origin_density": 3000,
"destination_density": 5000,
"distance_km": 80,
"road_type": 0,
"weather": 3,
"traffic": 4,
"public_holiday": 0,
"peak_hour": 1
}POST /predict/locker_advanced
Returns success_probability for diverting to a locker / alternate handoff when route slack and occupancy collide. Validated at ROC-AUC 0.849 against a 52% base success rate.
{
"success_probability": 0.73
}Cold-chain risk synthesis
The console composes travel + dwell quantiles versus ischaemic_remaining_min to report:
- Best case — q10 travel + q10 dwell margin
- Median — q50 + q50
- Worst case — q90 + q90 (breach if negative margin)
This synthesis is the operational bridge between the predictive layer and classical VRPTW / QAOA pathfinding described in the StochVRP-Mesh research report.
Validation metrics
| Model | Primary metric | Value |
|---|---|---|
| Dwell quantile | 80% PI coverage | 0.747 |
| Travel quantile | 80% PI coverage | 0.771 |
| Locker diversion | ROC-AUC | 0.849 |