feat: geospatial risk primitives and HazardEvent schema with dedup key

Author: VenkateswarluNagineni

src/aegis/geo.py

@@ -0,0 +1,43 @@
+"""Geospatial primitives for hazard risk scoring.
+
+Great-circle distance + a distance-decay proximity risk score. Pure-numpy so the core
+risk math has no heavy geo dependencies (GeoPandas/H3 arrive in later phases for the
+polygon/indexing work).
+"""
+
+from __future__ import annotations
+
+import math
+
+EARTH_RADIUS_KM = 6371.0088
+
+
+def haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Great-circle distance between two (lat, lon) points in kilometres."""
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dphi = math.radians(lat2 - lat1)
+    dlmb = math.radians(lon2 - lon1)
+    a = math.sin(dphi / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dlmb / 2) ** 2
+    return 2 * EARTH_RADIUS_KM * math.asin(math.sqrt(a))
+
+
+def proximity_risk(distance_km: float, radius_km: float = 50.0) -> float:
+    """Distance-decay risk in [0, 1].
+
+    1.0 at the hazard, decaying exponentially with distance. ``radius_km`` is the
+    characteristic scale at which risk falls to ~37% (one e-folding). Negative distances
+    are treated as 0 (at the event).
+    """
+    if radius_km <= 0:
+        raise ValueError("radius_km must be positive")
+    d = max(distance_km, 0.0)
+    return math.exp(-d / radius_km)
+
+
+def asset_risk(
+    asset: tuple[float, float],
+    hazard: tuple[float, float],
+    radius_km: float = 50.0,
+) -> float:
+    """Convenience: proximity risk of a hazard to an asset, both as (lat, lon)."""
+    return proximity_risk(haversine_km(*asset, *hazard), radius_km=radius_km)

src/aegis/schema.py

@@ -0,0 +1,39 @@
+"""Canonical hazard-event schema.
+
+Every source (FIRMS fires, USGS quakes, NOAA alerts) is normalized into ``HazardEvent``
+so enrichment, scoring, and RAG stay source-agnostic. ``dedup_key`` is the basis for
+change-detection: two ingests producing the same key are the same real-world event.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class HazardType(StrEnum):
+    WILDFIRE = "wildfire"
+    EARTHQUAKE = "earthquake"
+    SEVERE_WEATHER = "severe_weather"
+    FLOOD = "flood"
+    OTHER = "other"
+
+
+class HazardEvent(BaseModel):
+    """A normalized hazard observation."""
+
+    source: str = Field(description="Originating feed, e.g. 'firms', 'usgs', 'noaa'")
+    source_id: str = Field(description="Stable id within the source feed")
+    hazard_type: HazardType
+    latitude: float = Field(ge=-90, le=90)
+    longitude: float = Field(ge=-180, le=180)
+    observed_at: datetime
+    magnitude: float | None = Field(default=None, description="Quake magnitude / fire FRP / etc.")
+    raw: dict = Field(default_factory=dict, description="Original source payload")
+
+    @property
+    def dedup_key(self) -> str:
+        """Stable identity for change-detection across re-ingests."""
+        return f"{self.source}:{self.source_id}"

tests/test_geo.py

@@ -0,0 +1,29 @@
+import math
+
+import pytest
+
+from aegis.geo import asset_risk, haversine_km, proximity_risk
+
+
+def test_haversine_known_distance():
+    # College Station, TX -> Austin, TX is ~135 km.
+    d = haversine_km(30.6280, -96.3344, 30.2672, -97.7431)
+    assert 120 < d < 150
+
+
+def test_proximity_risk_bounds_and_decay():
+    assert proximity_risk(0.0) == 1.0
+    assert math.isclose(proximity_risk(50.0, radius_km=50.0), math.exp(-1), rel_tol=1e-9)
+    assert proximity_risk(1000.0) < proximity_risk(10.0)
+
+
+def test_proximity_risk_rejects_bad_radius():
+    with pytest.raises(ValueError):
+        proximity_risk(10.0, radius_km=0)
+
+
+def test_asset_risk_higher_when_closer():
+    hazard = (30.0, -96.0)
+    near = asset_risk((30.1, -96.1), hazard)
+    far = asset_risk((35.0, -100.0), hazard)
+    assert near > far

tests/test_schema.py

@@ -0,0 +1,16 @@
+from datetime import datetime
+
+from aegis.schema import HazardEvent, HazardType
+
+
+def test_dedup_key_is_stable():
+    ev = HazardEvent(
+        source="usgs",
+        source_id="ak0231",
+        hazard_type=HazardType.EARTHQUAKE,
+        latitude=61.2,
+        longitude=-149.9,
+        observed_at=datetime(2026, 6, 8, 0, 0, 0),
+        magnitude=4.5,
+    )
+    assert ev.dedup_key == "usgs:ak0231"