docs: architecture README, phased roadmap, phase 0 notes

Author: VenkateswarluNagineni

README.md

@@ -0,0 +1,63 @@
+# Aegis — Event-Driven Disaster Intelligence Pipeline
+
+[![CI](https://github.com/VenkateswarluNagineni/aegis-disaster-intel/actions/workflows/ci.yml/badge.svg)](https://github.com/VenkateswarluNagineni/aegis-disaster-intel/actions/workflows/ci.yml)
+[![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Ingests **live public hazard feeds** (wildfires, earthquakes, severe weather), enriches
+each event with an **agentic LLM workflow**, scores **geospatial risk**, and serves a
+**RAG query layer** so an analyst can ask "what's escalating near these assets right now?"
+
+Ingestion is **event-driven** — feeds fire updates that trigger processing — not naive
+polling, with **change-detection and dedup** so the same event isn't reprocessed or
+double-counted.
+
+> Why it exists: disaster response needs *fresh, deduplicated, enriched, location-aware*
+> signal. This pipeline mirrors that end to end on real open data.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph Sources
+      F[NASA FIRMS<br/>active fires]
+      Q[USGS<br/>earthquakes]
+      W[NOAA / NWS<br/>alerts]
+    end
+    F & Q & W --> ING[Event-driven ingestors<br/>change-detection + dedup]
+    ING --> N[Normalize to<br/>HazardEvent schema]
+    N --> EN[Agentic enrichment<br/>LangChain: geocode, classify,<br/>summarize, severity]
+    EN --> GEO[Geospatial risk scoring<br/>haversine / H3, asset proximity]
+    GEO --> ST[(Store: events +<br/>FAISS vector index)]
+    ST --> RAG[RAG query API<br/>'what's escalating near X?']
+    AF[Airflow] -. schedules backfills & sweeps .-> ING
+```
+
+## What makes it different
+
+- **Event-driven, not polling** — change-detection on feed state; only new/changed events flow.
+- **Agentic enrichment** — an LLM workflow geocodes, classifies hazard type, estimates
+  severity, and writes an analyst-ready summary, with validation guards.
+- **Geospatial-first** — proximity-to-asset risk scoring, not just a table of rows.
+- **RAG over live events** — natural-language situational queries with citations.
+
+## Tech stack
+
+`Python 3.11` · `LangChain` (agentic enrichment) · `FAISS` · `GeoPandas / H3` ·
+`Airflow` · real APIs: `NASA FIRMS`, `USGS`, `NOAA/NWS` · `Docker`
+
+## Status
+
+🚧 Built in public, in phases — see **[ROADMAP.md](ROADMAP.md)**. Each phase ships tested
+code + a design note in [`docs/`](docs/).
+
+## Quickstart
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT © Venkateswarlu Nagineni

ROADMAP.md

@@ -0,0 +1,44 @@
+# Aegis Roadmap
+
+Built in public, one phase at a time. Each phase ships tested code + a `docs/NOTES_<phase>.md`
+design note. The daily build routine picks up the next unchecked phase.
+
+> Convention: `[ ]` not started · `[~]` in progress · `[x]` done.
+
+## Foundations
+- [x] **Phase 0 — Scaffold.** Packaging, geospatial risk primitives (haversine,
+  distance-decay proximity, asset risk), canonical `HazardEvent` schema + dedup key,
+  tests, ruff, CI, Docker skeleton, roadmap.
+- [ ] **Phase 1 — USGS earthquake ingestor.** Pull the GeoJSON feed, normalize to
+  `HazardEvent`, tests against a recorded fixture.
+- [ ] **Phase 2 — NASA FIRMS wildfire ingestor.** Active-fire feed → `HazardEvent`
+  (handles FRP/confidence fields).
+- [ ] **Phase 3 — NOAA / NWS alerts ingestor.** Severe-weather alerts → `HazardEvent`.
+
+## Event-driven core
+- [ ] **Phase 4 — Change-detection + dedup store.** State by `dedup_key`; only new/changed
+  events advance (no reprocessing).
+- [ ] **Phase 5 — Event-driven trigger layer.** Feed-state hashing → emit only on change,
+  replacing naive polling.
+- [ ] **Phase 6 — Airflow orchestration.** Scheduled sweeps + backfill DAGs with retries.
+
+## Enrichment & scoring
+- [ ] **Phase 7 — Agentic enrichment workflow.** LangChain pipeline: reverse-geocode,
+  classify hazard subtype, estimate severity, write analyst summary — with output
+  validation/guards.
+- [ ] **Phase 8 — Geospatial risk scoring.** Asset registry + proximity risk; H3 cells
+  for spatial bucketing and aggregation.
+- [ ] **Phase 9 — Severity model.** Calibrated severity/escalation score combining
+  magnitude, trend, and proximity.
+
+## Retrieval & serving
+- [ ] **Phase 10 — Embedding + FAISS index.** Embed enriched events for semantic search.
+- [ ] **Phase 11 — RAG query API (FastAPI).** "What's escalating near <area>?" with
+  cited source events.
+- [ ] **Phase 12 — Situational dashboard.** Map view, escalation feed, asset risk table.
+
+## Hardening & polish
+- [ ] **Phase 13 — Backfill + replay tooling.** Reconstruct state from history.
+- [ ] **Phase 14 — Rate-limit & resilience.** Backoff, caching, partial-feed handling.
+- [ ] **Phase 15 — Dockerized demo + sample feeds.** One-command reproducible run.
+- [ ] **Phase 16 — Architecture deep-dive + demo GIF.** Recruiter-ready walkthrough.

docs/NOTES_phase0.md

@@ -0,0 +1,26 @@
+# Phase 0 — Scaffold (design notes)
+
+## What landed
+- `src/` package `aegis` with two real, tested pieces:
+  - `geo.py`: haversine great-circle distance + a **distance-decay proximity risk** score
+    (exponential, `radius_km` = one e-folding). Validated against the known College
+    Station→Austin distance (~135 km).
+  - `schema.py`: canonical `HazardEvent` with a **`dedup_key`** property — the foundation
+    of change-detection (phase 4).
+- ruff + pytest CI green from commit one.
+
+## Decisions & trade-offs
+- **`dedup_key` from day zero.** The whole "event-driven, not polling" thesis depends on
+  knowing when an event is the *same* event. Baking the dedup identity into the schema
+  forces every ingestor to declare it.
+- **Distance-decay over a hard radius.** A binary "within 50 km" flag throws away signal;
+  exponential decay gives a smooth, explainable risk that ranks assets sensibly.
+- **Pure-numpy/math core, geo libs later.** GeoPandas/H3/Shapely are heavy; the core risk
+  math doesn't need them, so CI stays fast and the math stays readable. They arrive in
+  phase 8 for polygon ops and spatial indexing.
+- **Agentic enrichment with guards (phase 7).** LLM enrichment is powerful but must be
+  validated — the plan treats schema-validated, guarded output as non-negotiable.
+
+## Next
+Phase 1: the USGS earthquake ingestor (cleanest public GeoJSON feed) → first real
+`HazardEvent` records flowing through the schema.