FloodFire CrisisRoom

FloodFire CrisisRoom is a multi-agent shipboard emergency command dashboard that ingests flooding, fire, smoke, and crew-report signals, verifies them, creates response tasks, and drafts crew/passenger advisories for bridge approval.

This is a hackathon MVP scaffold. It is mock-first, typed, and runnable without external API keys.

🏆 Redis Beyond Caching - Prize Track

Redis is the intelligent memory layer powering multi-agent crisis coordination:

• ✅ Vector Search: Semantic memory retrieval (RediSearch + embeddings)
• ✅ Real-Time Streams: Agent coordination via Redis Streams
• ✅ AI Memory: Persistent agent context across sessions
• ✅ Hybrid Search: Keyword + vector similarity fusion

Not a cache - Redis is the primary data store for agent memories, event sourcing, and semantic search.

📚 See: README_REDIS.md | REDIS_SHOWCASE.md | REDIS_ARCHITECTURE.md

Hackathon Prize-Track Strategy

• AI agents: clear agent boundaries for Commander, Flood Analyst, Fire Analyst, Verification, Response Planner, and Public Information.
• Real-time data: connector stubs and simulated shipboard sensors for bilge alarms, pump-room water rise, Engine Room thermal alarms, smoke reports, and crew field reports.
• Voice: Deepgram-ready voice report interface with manual fallback.
• Memory and coordination: Redis placeholder for incident memory, dedupe, and agent state.
• Redis beyond caching: Redis stores durable crisis memory, stream-based operational events, and agent context retrieval. If Redis Stack/RediSearch is available, the app reports vector-search readiness; otherwise it uses lexical retrieval over Redis memory hashes.
• Observability: Arize and Sentry placeholders for tracing, evaluation, and reliability.
• Human-centered safety: crew/passenger advisories are drafts only and require bridge/human approval.

Architecture

apps/web Next.js dashboard
  -> typed API client
  -> FastAPI REST + WebSocket
  -> route modules
  -> services: simulation, verification, agents, tasks, alert drafting
  -> in-memory store by default
  -> optional Redis and external connector stubs

Setup

cp .env.example .env

Put real secrets only in .env. The committed .env.example intentionally contains placeholders.

Minimum keys for the full demo:

• ASI_ONE_API_KEY — Fetch.ai ASI:One LLM
• AGENTVERSE_API_KEY — Agentverse mailbox for discoverable uAgents

Optional keys:

• ASI_ONE_MODEL: ASI:One model name, defaults to asi1-mini.
• ANTHROPIC_API_KEY: future Claude agent reasoning.
• REDIS_URL: local or hosted Redis connection string.
• REDIS_ACCOUNT_KEY, REDIS_API_KEY: hosted Redis account/API access if your Redis provider requires them.
• DEEPGRAM_API_KEY: voice transcription.
• BROWSERBASE_API_KEY: official-source browser checks.
• ARIZE_API_KEY + ARIZE_SPACE_ID: LLM tracing/evaluation (see Arize Observability below).
• SENTRY_DSN: frontend/backend error monitoring.
• NASA_FIRMS_MAP_KEY: real active fire detections.

Quick Start

Run these from the repo root (crisis-room/).

1. One-time install

npm install
cd api && python3 -m venv .venv && . .venv/bin/activate && pip install -e .

2. Start the app (terminal 1)

npm run dev

Starts:

• Frontend: http://localhost:3000/dashboard
• API: http://localhost:8000

Leave this terminal running.

3. Start Fetch.ai agents (terminal 2, optional)

Required for the Agentverse sponsor track. The dashboard works without this if ASI_ONE_API_KEY is set — ASI:One is called directly from FastAPI.

npm run dev:agents

Starts all four agents in a single uAgents Bureau (one process, served on :8100). They register on Agentverse (discoverable) and communicate with each other in-process (see Agent-to-agent communication):

Agent	Role
FloodFire Crisis Orchestrator	Coordinates the specialist swarm and synthesizes the bridge situation brief
Hazard Intelligence Agent	Assesses flood/fire/smoke indicators, localizes to compartments, ranks severity
Response Coordination Agent	Turns confirmed hazards into prioritized, sequenced response tasks
Public Advisory Agent	Drafts approval-gated crew/passenger advisories (never claims transmission)

On startup it sends one demo incident through the pipeline and prints the assembled brief, then stays running. Use --no-demo to skip the demo, or --once to exit after it. Each agent's address is printed at startup. Leave this terminal running.

4. Start Redis (terminal 3, optional)

Only if you want Redis crisis memory persistence:

redis-server

Or point REDIS_URL in .env at a hosted Redis instance — no local Redis process needed.

5. Agentverse connectivity

The Bureau batch-registers all four agents on Agentverse automatically at startup (Batch registration on Almanac API successful) — no manual connection step.

To run the agents as separate processes instead (each on its own port, e.g. for individual Agentverse mailbox/proxy connection), use the single-agent runner — see Agent-to-agent communication. Standalone agents honor FETCH_CONNECTIVITY (proxy default, or mailbox/endpoint).

6. Verify

curl http://localhost:8000/
curl http://localhost:8000/api/fetch/status

Stop everything

for p in 3000 8000 8100; do lsof -ti:$p | xargs kill 2>/dev/null; done

Run scripts reference

Command	What it does
npm run dev	Frontend + API together (recommended)
npm run dev:web	Next.js only on :3000
npm run dev:api	FastAPI only on :8000
npm run dev:agents	All four Fetch.ai uAgents in one Bureau on :8100 — Agentverse-discoverable + real agent-to-agent communication

Run agents as separate processes instead of the Bureau (each binds its own port 8100–8103 and uses FETCH_CONNECTIVITY; note cross-process A2A needs Almanac/ledger network access):

cd api && . .venv/bin/activate && python3.13 fetch_agents/run_agent.py orchestrator  # :8100
cd api && . .venv/bin/activate && python3.13 fetch_agents/run_agent.py hazard        # :8101
cd api && . .venv/bin/activate && python3.13 fetch_agents/run_agent.py response      # :8102
cd api && . .venv/bin/activate && python3.13 fetch_agents/run_agent.py advisory      # :8103

Agent-to-agent communication

The four agents collaborate via Fetch.ai uAgents messaging. The orchestrator runs a pipeline: it dispatches the incident to the Hazard Intelligence Agent, threads that assessment into the Response Coordination Agent, threads both into the Public Advisory Agent, then synthesizes the bridge brief — each specialist builds on the previous one's output. Messaging uses ctx.send_and_receive with an internal SpecialistQuery / SpecialistReport model pair (api/fetch_agents/messages.py), kept separate from the public chat protocol used for Agentverse discovery.

npm run dev:agents runs the whole fleet in one Bureau, which routes messages between agents in-process and sends one demo incident through the pipeline on startup:

npm run dev:agents
# custom scenario / options:
cd api && . .venv/bin/activate && python fetch_agents/run_fleet.py "Bilge alarm on Deck 3; smoke in the Engine Room"
cd api && . .venv/bin/activate && python fetch_agents/run_fleet.py --once      # exit after the demo brief
cd api && . .venv/bin/activate && python fetch_agents/run_fleet.py --no-demo   # just run the discoverable fleet

You'll see the orchestrator dispatch to each specialist (with Received A2A query … building on it) and print the assembled brief.

Why a Bureau? Cross-process uAgent messaging resolves peer addresses via the Fetch.ai Almanac (ledger network access). When that network is unavailable, a Bureau routes messages in-process so the agents still collaborate with no external dependency, while still batch-registering on Agentverse for discoverability. To run agents as separate processes, use run_agent.py (above).

Run Frontend

npm run dev:web

Open http://localhost:3000/dashboard.

Run Backend

npm run dev:api

Backend health check: http://localhost:8000/.

Run Frontend and Backend Together

npm run dev

This installs frontend dependencies, creates/uses api/.venv, installs the FastAPI app, sources the root .env, starts the backend on http://localhost:8000, and starts the frontend on http://localhost:3000.

Redis is optional. With REDIS_URL=redis://localhost:6379, start a local Redis separately if you want persistence; otherwise the app falls back to memory.

Docker Compose

docker compose up --build

Start Simulation

curl -X POST http://localhost:8000/api/incidents -H 'Content-Type: application/json' -d '{}'
curl -X POST http://localhost:8000/api/incidents/<incident_id>/simulate/start
curl -X POST http://localhost:8000/api/incidents/<incident_id>/agents/run

Each simulation call advances one deterministic shipboard fire/flood event.

Fetch.ai and Redis Integration

Fetch.ai ASI:One and Redis are optional. The backend runs without either one.

Fetch.ai:

• Set ASI_ONE_API_KEY and AGENTVERSE_API_KEY in local .env.
• Agent messages, incident briefs, public alert drafts, and command parsing use ASI:One when available.
• See Quick Start above for startup and Agentverse mailbox steps.
• Check GET /api/fetch/status for agent addresses and ASI:One configuration.
• If ASI:One is missing or fails, deterministic fallback text is used.

Redis:

• Set REDIS_URL to redis://... or rediss://....
• The incident store writes IncidentState JSON to Redis under floodfire:incident:{incident_id}.
• The incident index is stored in floodfire:incidents.
• Crisis memory records are stored as Redis hashes under floodfire:memory:{memory_id}.
• Each incident has a memory set at floodfire:incident:{incident_id}:memory_ids.
• Each incident also writes operational events to a Redis Stream at floodfire:incident:{incident_id}:stream.
• Agents retrieve Redis memory before ASI:One generation and include recalled shipboard context in their prompts.
• The dashboard shows Redis memory status, memory count, stream support, vector-search readiness, and recalled records in the Redis Crisis Memory panel.
• If Redis is unavailable, the app continues with in-memory state.

Redis prize-track demo path:

1. Start Redis locally or point REDIS_URL at a hosted Redis instance.
2. Run npm run dev.
3. Open /dashboard.
4. Click Run Scenario Step several times.
5. Click Analyze Incident.
6. In Redis Crisis Memory, click Reindex, then Recall.
7. Explain that Redis is being used for shipboard agent memory, context retrieval, stream event history, and optional vector-search capability detection, not just caching.

Secrets:

• Do not commit .env.
• Do not paste real keys into source files.
• .env.example contains placeholders only.

Arize Observability

Arize AX gives the agent fleet LLM tracing plus an automated evaluator that scores agent output against the CrisisRoom safety policy.

Setup

1. In Arize, copy your Space ID and an API Key (Space Settings → API Keys).

2. Put them in .env:

   ARIZE_API_KEY=...
   ARIZE_SPACE_ID=...
   ARIZE_PROJECT_NAME=floodfire-crisisroom   # optional, this is the default
   

3. Start the API (npm run dev:api) and exercise the agents (create an incident, run agents, draft an alert). Every ASI:One call is auto-instrumented via OpenInference and streamed to Arize as a trace, wrapped in a per-agent span (e.g. Flood Analyst Agent, Incident Brief, Alert Draft) carrying input.value, output.value, and agent/task metadata.

Confirm wiring at any time:

curl http://localhost:8000/api/observability/status   # -> { "arize": { "enabled": true, ... } }

Evaluator

api/scripts/arize_eval.py is an LLM-as-judge that closes the loop. At trace time each generation's span_id + I/O is buffered to api/.arize_eval_queue.jsonl; the evaluator scores each one on two criteria and logs the results back onto the exact Arize spans (visible as feedback on the trace):

• safety_policy — flags any output that claims a public alert was sent, recommends automatic dispatch, or omits uncertainty on unverified reports.
• groundedness — checks the output is supported by the incident context.

cd api && . .venv/bin/activate
python scripts/arize_eval.py --dry-run   # score locally, print results
python scripts/arize_eval.py             # score and upload evals to Arize
python scripts/arize_eval.py --limit 50  # only the 50 most recent spans

This evaluator surfaced and let us tighten prompts that occasionally implied alerts had already been transmitted — the safety_policy fail rate is how we measure that improvement in Arize.

API Endpoints

• GET /: health check
• POST /api/incidents: create simulated incident
• GET /api/incidents: list incidents
• GET /api/incidents/{incident_id}: full incident state
• POST /api/incidents/{incident_id}/simulate/start: advance simulation
• POST /api/incidents/{incident_id}/reports: add field report
• GET /api/incidents/{incident_id}/reports: list reports
• POST /api/incidents/{incident_id}/agents/run: run scaffold agents
• GET /api/incidents/{incident_id}/agents/messages: list agent messages
• GET /api/incidents/{incident_id}/tasks: list tasks
• PATCH /api/tasks/{task_id}: update task status
• POST /api/incidents/{incident_id}/briefing: generate situation report
• POST /api/incidents/{incident_id}/public-alert-draft: generate public alert draft
• POST /api/voice/transcribe: Deepgram placeholder transcription
• GET /api/incidents/{incident_id}/memory/capabilities: Redis memory and vector-search status
• GET /api/incidents/{incident_id}/memory/search?q=...: retrieve relevant Redis crisis memories
• POST /api/incidents/{incident_id}/memory/reindex: rebuild Redis memory from current incident state
• GET /api/fetch/status: Fetch.ai ASI:One and uAgent registry status
• GET /ws/incidents/{incident_id}: WebSocket incident updates

Sponsor Integration Checklist

Core:

• Anthropic for agent reasoning and incident briefs
• Redis for incident memory, vector search, semantic deduplication, and agent state
• Deepgram for voice field reports and spoken briefings
• Band for multi-agent shared rooms
• Fetch.ai for discoverable emergency agents
• Browserbase for web-using official-source checks
• Arize for LLM tracing and output evaluation
• Sentry for frontend/backend error monitoring

Known Limitations

• Map is a Leaflet/Mapbox-style placeholder, not a real tile map.
• External data connectors return mock or empty data until credentials and API clients are added.
• Agent outputs use ASI:One when configured; otherwise deterministic fallbacks are used.
• Redis is optional; the default store is in-memory and resets on restart.
• Public alerts cannot be sent from this app.

Next Steps

1. Expand Fetch.ai uAgent orchestration and Agentverse discoverability.
2. Add Redis-backed persistence in api/app/services/redis_store.py.
3. Replace HazardMap.tsx with Leaflet or Mapbox.
4. Wire Deepgram audio upload in api/app/connectors/deepgram_client.py and VoiceReportPanel.tsx.
5. Add production auth, audit logging, and human approval workflow before any real deployment.