MIRAGE

MIRAGE turns early warnings into early action. AI agents coordinate shelters, resources and logistics, while human approvals and community alerts enable faster, explainable disaster response.

Comment

MIRAGE — Project Story

Inspiration

Disaster response usually breaks down in a very specific way: not because the warning never arrives, but because nobody can turn the warning into a decision fast enough. A cyclone forecast reaches a control room, and then human coordinators are left doing, by hand, the same allocation problem over and over — which shelters get which resources, which villages evacuate first, who signs off. Under pressure, that process is slow, inconsistent, and hard to audit after the fact.

MIRAGE started as a final-year research question: can a multi-agent system make these allocation decisions in a way that is not just fast, but provably fair and reproducible? That's a research problem. What turned it into something we wanted to keep building was realizing that the same architecture — Digital Twins feeding a blackboard, agents proposing allocations, a deterministic conflict resolver arbitrating between them, and a governance layer requiring human approval — maps almost exactly onto the "early warning → early action" gap that agencies like IGAD are trying to close in East Africa. The hackathon gave us a reason to take a research system and push it toward something a real operations team could actually stand behind.

What it does

MIRAGE simulates a disaster (currently cyclone landfall) using five coordinated Digital Twins — Cyclone, Population, Shelter, Resource, and Infrastructure — each modeling one part of the ground truth. Four specialized agents (Risk, Shelter, Logistics, Resource) read this shared state and propose allocations. Because independent agents will disagree, a deterministic conflict resolver arbitrates between them using one of four strategies — WEIGHTED, FCFS, EQUAL, or PRO_RATA — so the same inputs always produce the same output, which matters enormously when the output decides who gets a shelter bed.

Every allocation then passes through a governance workflow: an L1/L2/L3 approval state machine that keeps a human in the loop rather than letting the AI act unilaterally. On top of this, we added a community layer for the hackathon — a broadcast/alert mechanism so that once a decision is approved, the information doesn't stay inside a dashboard, it reaches the people it's about.

How we built it

The backend is Python/FastAPI, structured around a blackboard architecture: Digital Twins write state, agents read and reason over it, and the conflict resolver and governance engine sit downstream as separate, independently testable modules. This separation was deliberate — it let us validate the allocation logic against 5 baseline strategies across 45 evaluation runs (3 scenarios × 3 seeds each) before we ever touched the frontend, which meant three hypotheses about stock-out reduction, decision latency, and allocation fairness could be tested statistically rather than argued about anecdotally.

The frontend is a Next.js dashboard that visualizes the simulation live — the same blackboard state that drives the agents also drives the UI, so what you see on screen is not a mock, it's the actual system running. For the hackathon we extended this with a lightweight GIS layer (shelters, resources, and hazard zones plotted geographically) and the community alert panel, both built to plug into the existing state model rather than bolt on a separate system.

What we learned

The biggest lesson was about the cost of determinism. It's easy to build a multi-agent system that "seems to work" — much harder to build one where you can prove, run after run, that WEIGHTED allocation actually outperforms FCFS on fairness, not just that it looked reasonable once. Committing to deterministic conflict resolution early made evaluation possible, but it also meant every agent had to be written without hidden randomness, which is a stricter discipline than it sounds.

We also learned, more practically, how much a system's framing matters independent of its engineering. MIRAGE's underlying architecture didn't change much between "research project" and "hackathon submission" — what changed was foregrounding the community-facing loop and making the early-warning-to-action pipeline visible end-to-end, rather than burying it under evaluation tables. A good system that isn't legible to the people judging or funding it doesn't get to help anyone.

Challenges we ran into

Reconciling research rigor with hackathon pace was the central tension. The evaluation engine, governance state machine, and Digital Twins were built and validated over months; the hackathon window was days. We made a deliberate choice not to touch or dilute the validated core, and instead spent the limited time extending it outward — community alerts, geospatial visualization, regional scenario data — so the parts we added were additive, not replacements for work we'd already proven out.

The other real challenge was making determinism visible without making the demo boring. A system that behaves exactly the same way every run is a strength for evaluation and a risk for a live demo — there's no room for a lucky moment. We had to make sure the interesting part of the story (four agents disagreeing, a deterministic tie-break resolving it, a human approving it, a community receiving it) came through clearly on screen, not just in the metrics underneath it.

Built With

Share this project:

Updates