Jishnu-Vijayan-03/disaster-response

DisasterResponseEnv

Emergency Operations Center Triage Agent — OpenEnv Environment

Live Space: https://jishnu-vijayan-03-disaster-response.hf.space Dashboard: https://jishnu-vijayan-03-disaster-response.hf.space/dashboard API Docs: https://jishnu-vijayan-03-disaster-response.hf.space/docs

An RL training and evaluation environment that simulates real-world disaster response coordination. The agent plays the role of an Emergency Operations Center (EOC) triage coordinator who must allocate finite rescue resources across multiple disaster zones, filtering genuine distress signals from noise and adversarial misinformation.

Motivation

During the 2023 Türkiye–Syria earthquake, EOC operators received 300,000+ distress messages in 48 hours. Post-event analysis estimated that faster, more optimal triage decisions in the first 12 hours could have saved 8,000+ additional lives. Current automated triage tools are stateless classifiers — they ignore resource constraints, temporal urgency, and the strategic reserve problem. DisasterResponseEnv models the full stateful, resource-constrained, multi-zone sequential decision problem that real coordinators face.

Environment Description

The agent receives one alert per step from a queue of distress signals generated by disaster zones. Each zone has a continuous stress level [0, 1] that:

• —Grows 12% per step when the zone is not actively helped
• —Drops by up to 0.30 when a rescue team is dispatched to it
• —Generates more alerts (and more severe ones) as stress increases

The agent must triage alerts using observable signals only — source channel, severity score, and message text — without knowing whether each alert is genuine. Spoofed alerts (Task 3) have artificially inflated severity to drain resources before major events.

Resources are finite and lock for multiple steps after deployment, forcing long-horizon planning rather than greedy response.

Action Space

time_decay = exp(−0.07 × stepssincealert_arrived) — models survivor probability decay.

Observation Space

{
  "current_alert": {
    "alert_id": "a3f9b2c1",
    "zone_id": "zone_a",
    "zone_name": "Riverside District",
    "source": "sensor",
    "severity": 0.872,
    "message": "Structural sensor exceeds critical threshold — collapse imminent.",
    "arrival_step": 3,
    "deliberation_count": 0
  },
  "zones": [{"zone_id": "zone_a", "name": "Riverside District", "stress": 0.712, "pending_alerts": 2}],
  "resources": {
    "rescue_teams_available": 2,
    "rescue_teams_locked": [{"returns_at_step": 12}],
    "medical_units_available": 3,
    "medical_units_locked": [],
    "broadcast_credits": 2
  },
  "step": 5,
  "max_steps": 25,
  "task_name": "task1_flood_easy",
  "cumulative_reward": 1.42,
  "done": false,
  "reward": 0.85
}

is_real and is_spoofed are hidden from the agent — they are internal fields used only for reward calculation and grading.

Three Tasks

Task 1 — Single Zone Flood Triage (Easy)

One zone, abundant resources, short lock times. Learn the fundamental binary signal: real vs. noise.

Task 2 — Multi-Zone Flash Flood (Medium)

Three zones compete for limited resources. Spatial prioritisation: a zone at 0.70 stress growing for 10 steps is categorically different from one that just spiked. Evacuation credits become strategically valuable.

Task 3 — Cascading Compound Disaster (Hard)

Five zones, 8-step resource locks, zone cascade mechanics (zone_a → zone_d, zone_b → zone_e), and adversarial spoofed alerts designed to drain resources before the second wave. Only an agent with genuine multi-step lookahead performs well.

API Endpoints

Web Interfaces

OpenEnv Gradio UI — /web

Mounted automatically when ENABLE_WEB_INTERFACE=true (set in Dockerfile). Provides the standard OpenEnv step-and-observe interface.

🔗 https://jishnu-vijayan-03-disaster-response.hf.space/web

Custom EOC Dashboard — /dashboard

A purpose-built interactive dashboard for the disaster triage environment:

• —Auto Run with 3 selectable policies (Heuristic / Aggressive / Cautious) and adjustable step speed
• —Live zone stress bars, resource counters, alert severity visualisation
• —Step-by-step reward log with color-coded outcomes
• —Score banner on episode completion

🔗 https://jishnu-vijayan-03-disaster-response.hf.space/dashboard

Setup & Usage

Local Development

# Install dependencies
pip install -r requirements.txt
# or
uv sync

# Start server
uvicorn server.app:app --host 0.0.0.0 --port 7860

# Validate OpenEnv compliance
openenv validate

# Run inference against local server
export HF_TOKEN=your_token
export ENV_BASE_URL=http://localhost:7860
python inference.py

Docker

docker build -t disaster-response .
docker run -p 7860:7860 disaster-response

Run Inference Against Live Space

export API_BASE_URL=https://router.huggingface.co/v1
export HF_TOKEN=your_token
export MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
export ENV_BASE_URL=https://jishnu-vijayan-03-disaster-response.hf.space

python inference.py

Baseline Scores (Oracle-Normalised)

Oracle scores are stable across seeds (verified: task1=15.09, task2=14.81, task3=3.92 average raw reward).

Judge Quick Reference

Live Space URL: https://jishnu-vijayan-03-disaster-response.hf.space

1. Liveness Check

curl https://jishnu-vijayan-03-disaster-response.hf.space/health
# → {"status": "healthy"}

2. List Tasks + Action Schema

curl https://jishnu-vijayan-03-disaster-response.hf.space/tasks

3. Run a Complete Episode (Task 1)

# Reset
curl -X POST https://jishnu-vijayan-03-disaster-response.hf.space/reset \
  -H "Content-Type: application/json" \
  -d '{"task_name": "task1_flood_easy", "seed": 42}'

# Step (use alert_id from reset response)
curl -X POST https://jishnu-vijayan-03-disaster-response.hf.space/step \
  -H "Content-Type: application/json" \
  -d '{"action": {"action_type": "dispatch_rescue", "alert_id": "<id>"}}'

# Repeat /step until done=true, then:
curl https://jishnu-vijayan-03-disaster-response.hf.space/grader

4. Check Oracle Baseline

curl -X POST https://jishnu-vijayan-03-disaster-response.hf.space/baseline \
  -H "Content-Type: application/json" \
  -d '{"seed": 42, "num_seeds": 3}'

5. Run Inference Script

export HF_TOKEN=<your_token>
export ENV_BASE_URL=https://jishnu-vijayan-03-disaster-response.hf.space
export API_BASE_URL=https://router.huggingface.co/v1
export MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct

# Run all 3 tasks
python inference.py

# Run specific task
DISASTER_TASK=task1_flood_easy python inference.py

6. Interactive Testing

Open the dashboard in a browser for visual episode playback:

https://jishnu-vijayan-03-disaster-response.hf.space/dashboard

7. OpenEnv Validation

cd /path/to/repo
openenv validate
# → [OK] disaster-response: Ready for multi-mode deployment

Grader Score Interpretation

Project Structure

disaster-response/
├── models.py                  # Pydantic types: Action, Observation, State
├── inference.py               # LLM baseline script (OpenAI client)
├── openenv.yaml               # OpenEnv spec declaration
├── Dockerfile                 # Container (root-level, ENABLE_WEB_INTERFACE=true)
├── requirements.txt
├── pyproject.toml
├── uv.lock
└── server/
    ├── app.py                 # FastAPI app + all endpoints + web UI
    ├── config.py              # TASK_CONFIGS + DEFAULT_TASK
    ├── messages.py            # Alert message templates
    ├── oracle.py              # oracle_decide() + _oracle_create_alert()
    └── environment.py         # DisasterResponseEnvironment class

Made with ❤️ for the Meta Hackathon.