Skip to content

160-tool MCP server for real-time global intelligence from free public APIs: markets, liquidity, prediction markets, SEC filings, conflict, military, aircraft-cohort early warning, migration and border flows, cyber, climate, news and more. Dated observation history, 29 research prompts, cited briefs, geofences, SSE dashboard. MIT, no paid API keys.

AOI escalation: score the news and convergence components

Phoenix Agent (mac-studio)3144876b83fa
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6311734..a08f2cd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,47 @@
# Changelog
+## Unreleased
+
+### Added: AOI escalation news and convergence components
+- `intel_aoi_escalation` now scores the news and convergence components it
+ used to report as null (ROADMAP Phase 23).
+- News: the rise in the area's share of all GDELT coverage over the last 7
+ days against the 7 days before, for the reverse-geocoded settlement and
+ county (the query the AOI brief already uses, sent as `timelinevolraw`).
+ Expected articles = prior share x current GDELT volume; change_pct =
+ 100 x (current - expected) / max(expected, 20); component =
+ min(20, 0.2 x max(0, change_pct)). Shares rather than raw counts because
+ GDELT's own intake has multi-day outages (measured 2026-10-17 for
+ Pittsburgh: no data for 16 of 85 days), which raw counts would read as a
+ surge on recovery; a comparison where one week monitored under half the
+ other's volume is refused as a data gap. An area that cannot be
+ geocoded is not scored, rather than searched by the AOI's name.
+- Convergence: `analysis/convergence.py`, unmodified, over the
+ earthquakes, military flights, ACLED events and wildfires inside the
+ AOI's exact shape (circle, polygon or corridor, through the same
+ `filter_by_aoi` scoping as the brief). With an input missing, a
+ convergent cell is reported as a lower bound; no cell at all is null,
+ because quiet cannot be told from missing.
+- New response keys; existing keys keep their meaning. `computed_from`
+ names the components the score was computed from, and
+ `zero_filled_components` the ones among them that are a 0 only because
+ the military or ACLED fetch failed (`score_hotspot` takes no null for
+ those, unchanged); `news_signal` (query, both windows' counts and
+ shares, change), `news_scoping` and `convergence_signal` (cells, events
+ per domain, inputs used, failed or partial) carry the working. A failed
+ news or convergence input makes that component null in `components`,
+ listed in `unavailable_components` and explained in `data_gaps`, never
+ a 0.
+
+### Changed
+- The escalation also fetches earthquakes and wildfires (convergence
+ inputs) and one GDELT timeline, in parallel with ACLED and military
+ flights; their failures are named in `data_gaps`. The brief, the change
+ sweep and the escalation now share one AOI scoping helper.
+- `test_aoi.py` stubs every network-bound source by default: its older
+ escalation tests stub only ACLED and military flights and would
+ otherwise reach Nominatim, GDELT, USGS and FIRMS live.
+
## 0.11.0 - 2026-10-12
Cross-border migration (MCP tools, CLI, collector and a dashboard
diff --git a/README.md b/README.md
index 77f7474..026624e 100644
--- a/README.md
+++ b/README.md
@@ -571,7 +571,17 @@ instead of silently omitting it.
`intel_aoi_escalation` runs the same baseline/military/conflict/social-
unrest scoring engine that powers `intel_hotspot_escalation` for the 22
built-in hotspots, but scoped to your AOI's own radius instead of a fixed
-2-degree window.
+2-degree window. It also scores the two components the built-ins leave
+null. News is the rise in the area's share of all GDELT coverage over the
+last 7 days against the 7 before, for the reverse-geocoded place (the
+same query the brief uses), so a swing or outage in what GDELT ingests is
+not read as a news surge. Convergence runs the multi-domain convergence
+grid over the earthquakes, military flights, ACLED events and wildfires
+inside the AOI's exact shape. If either one's inputs fail, it comes back
+null with the reason in `data_gaps`, never as a 0, and `computed_from`
+names the components the score was computed from
+(`zero_filled_components` flags any that are a 0 only because the
+military or ACLED fetch failed).
AOIs persist in a dedicated table inside the same SQLite cache database
the server already uses (`~/.cache/world-intel-mcp/cache.db` by default,
diff --git a/ROADMAP.md b/ROADMAP.md
index 4f03400..1c802ab 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -564,7 +564,7 @@ Ordered by value; numbers are proposals, not commitments.
| Polygon AOIs | 3-64 vertex shapes, dateline-aware, exact membership across brief/changes/escalation; DB migrates in place | :white_check_mark: Shipped in 0.5.0 (`intel_aoi_define_polygon`) |
| Corridor AOIs | Waypoint route + width; distances measured to the route | :white_check_mark: Shipped in 0.5.0 (`intel_aoi_define_corridor`) |
| AOI groups / watchlists | `intel_aoi_digest` sweeps all (or named) AOIs in one call, advancing snapshots | :white_check_mark: Shipped in 0.8.0 |
-| Escalation news + convergence components | `intel_aoi_escalation` reports null for news/convergence; wire GDELT name-mention counts and the existing convergence grid | :yellow_circle: |
+| Escalation news + convergence components | `intel_aoi_escalation` reported null for news/convergence. News is now the rise in the geocoded place's share of all GDELT coverage, the last 7 days against the 7 before (`timelinevolraw` for the brief's settlement + county query), not name-mention counts: GDELT's own intake has multi-day outages (measured 2026-10-17 for Pittsburgh: no data for 16 of 85 days), which raw counts would read as a surge on recovery, so windows with uneven intake are refused as a data gap. Convergence runs `analysis/convergence.py` over the earthquakes, military flights, ACLED events and wildfires inside the AOI's exact shape. A failed news or convergence input makes that component null plus a `data_gaps` entry, never a 0; `computed_from` names the components behind the score | :white_check_mark: Shipped (Unreleased) |
| Geo-scoped news | AOI centre reverse-geocoded via OSM Nominatim (`sources/geocode.py`); GDELT searched for the settlement + county, e.g. `("Pittsburgh" OR "Allegheny County")`. Brief reports `news_scoping`; name-mention fallback is disclosed as a data gap. GDELT GEO 2.0 API was tried first and is 404 (both path variants, measured), so per-article coordinates are not available; the curated 105-city set could not do this either (nearest to Pittsburgh: Toronto, ~360 km) | :white_check_mark: Shipped in 0.10.0 |
| CLI parity | `intel aoi` group with all 9 subcommands, shared store semantics, live-smoked | :white_check_mark: Shipped in 0.8.0 |
| Dashboard AOI layer | `/api/aois` + a toggleable "AOI Geofences" Leaflet layer: circles, polygons, and corridors drawn from the store, tooltip/detail with what the last collector sweep counted inside each. Reads the stored snapshot, never gathers live (a never-swept AOI says so instead of showing zeros; a broken store is a 503, not an empty map). Verified in headless Chromium: 2 shapes rendered, 50 km circle at 50,000 m, no console errors | :white_check_mark: Shipped in 0.10.0 |
diff --git a/src/world_intel_mcp/analysis/aoi.py b/src/world_intel_mcp/analysis/aoi.py
index 5255f76..77e8624 100644
--- a/src/world_intel_mcp/analysis/aoi.py
+++ b/src/world_intel_mcp/analysis/aoi.py
@@ -37,10 +37,11 @@ import math
import os
import sqlite3
import time
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Any
+from .convergence import detect_convergence
from .escalation import score_hotspot
from .situation import _add_source, _cite, _has_valid_citation
@@ -1252,6 +1253,24 @@ async def _aoi_news_query(fetcher, aoi_row: dict) -> tuple[str, dict]:
}
+def _scope_to_aoi(
+ result: Any, list_key: str, aoi_row: dict, lat_key: str, lon_key: str
+) -> dict:
+ """One domain's fetch result scoped to the AOI: ``{"error": msg}``,
+ or ``{"items": [...]}`` filtered to the exact shape by
+ ``filter_by_aoi`` (plus ``partial_errors`` when the fetch reported
+ partial coverage). Shared by the brief/changes gather and the
+ escalation score, so every AOI tool agrees on what is inside the
+ fence."""
+ if isinstance(result, dict) and result.get("error"):
+ return {"error": str(result["error"])}
+ items = result.get(list_key, []) if isinstance(result, dict) else []
+ entry: dict[str, Any] = {"items": filter_by_aoi(items, aoi_row, lat_key, lon_key)}
+ if isinstance(result, dict) and result.get("partial_errors"):
+ entry["partial_errors"] = result["partial_errors"]
+ return entry
+
+
async def _gather_scoped_domains(fetcher, aoi_row: dict) -> dict[str, dict]:
"""Fetch all six dynamic domains in parallel and scope each to the
AOI. The single shared scoping path for ``fetch_aoi_brief`` and
@@ -1295,27 +1314,19 @@ async def _gather_scoped_domains(fetcher, aoi_row: dict) -> dict[str, dict]:
),
)
- scoped: dict[str, dict] = {}
-
- def _scope(
- result: Any, list_key: str, domain: str, lat_key: str, lon_key: str
- ) -> None:
- if isinstance(result, dict) and result.get("error"):
- scoped[domain] = {"error": str(result["error"])}
- return
- items = result.get(list_key, []) if isinstance(result, dict) else []
- entry: dict[str, Any] = {
- "items": filter_by_aoi(items, aoi_row, lat_key, lon_key)
- }
- if isinstance(result, dict) and result.get("partial_errors"):
- entry["partial_errors"] = result["partial_errors"]
- scoped[domain] = entry
-
- _scope(eq_result, "earthquakes", "earthquakes", "latitude", "longitude")
- _scope(mil_result, "aircraft", "military_flights", "latitude", "longitude")
- _scope(conflict_result, "events", "conflict_events", "latitude", "longitude")
- _scope(wildfire_result, "clusters", "wildfires", "lat", "lon")
- _scope(aviation_result, "sampled", "aviation", "lat", "lon")
+ scoped: dict[str, dict] = {
+ "earthquakes": _scope_to_aoi(
+ eq_result, "earthquakes", aoi_row, "latitude", "longitude"
+ ),
+ "military_flights": _scope_to_aoi(
+ mil_result, "aircraft", aoi_row, "latitude", "longitude"
+ ),
+ "conflict_events": _scope_to_aoi(
+ conflict_result, "events", aoi_row, "latitude", "longitude"
+ ),
+ "wildfires": _scope_to_aoi(wildfire_result, "clusters", aoi_row, "lat", "lon"),
+ "aviation": _scope_to_aoi(aviation_result, "sampled", aoi_row, "lat", "lon"),
+ }
if isinstance(news_result, dict) and news_result.get("error"):
scoped["news"] = {"error": str(news_result["error"]), "scoping": news_scoping}
@@ -1598,17 +1609,345 @@ async def fetch_aoi_brief(fetcher, store: AOIStore, name: Any) -> dict:
# ---------------------------------------------------------------------------
-# intel_aoi_escalation (optional, reuses analysis/escalation.py unmodified)
+# intel_aoi_escalation (reuses analysis/escalation.py and
+# analysis/convergence.py unmodified)
# ---------------------------------------------------------------------------
+# News component: how the area's share of world coverage moved, the
+# latest week against the week before. Seven days matches the ACLED
+# window this score already uses and puts every weekday in each window.
+NEWS_WINDOW_DAYS = 7
+
+# Floor on the expected article count in the percent change, so a
+# handful of stories about a quiet place cannot read as a surge (one
+# extra article against an expected 0.5 would otherwise be +200%).
+_NEWS_EXPECTED_FLOOR = 20.0
+
+# Each window must have monitored at least this fraction of the other
+# window's GDELT volume. GDELT's index has multi-day ingestion outages:
+# measured 2026-10-17 for ("Pittsburgh" OR "Allegheny County"), its
+# default daily timeline had no data at all for 16 of 85 days, and
+# Oct 6, 8 and 10 held 3.3%, 0.6% and 1.5% of a normal day's volume.
+# Raw counts across such a gap read the recovery as a news surge; even
+# shares get noisy when one window rests on a sliver of intake.
+_NEWS_MIN_INTAKE_RATIO = 0.5
+
+NEWS_METHOD = (
+ "GDELT DOC timelinevolraw for the geocoded place query (see "
+ "news_scoping). Current window: the 7 days ending with GDELT's current "
+ "time step, which may be partly filled; prior window: the 7 days before "
+ "it. Share = matching articles / all articles GDELT monitored in the "
+ "window. expected_articles = prior share x current monitored volume; "
+ "change_pct = 100 x (current articles - expected) / max(expected, 20); "
+ "news component = min(20, 0.2 x max(0, change_pct)), so a doubled share "
+ "scores the full 20 (once 20 or more articles were expected) and a flat "
+ "or falling one scores 0. Not scored when "
+ "either window monitored under half the other's volume (GDELT ingestion "
+ "gaps)."
+)
+
+# Convergence component: the geolocated domains whose in-fence events
+# feed analysis/convergence.py, with their coordinate keys. Aviation is
+# left out (a 1-in-10 sample of ordinary civil traffic is not a risk
+# signal) and news has no per-article coordinates.
+_CONVERGENCE_DOMAINS: dict[str, tuple[str, str]] = {
+ "earthquakes": ("latitude", "longitude"),
+ "military_flights": ("latitude", "longitude"),
+ "conflict_events": ("latitude", "longitude"),
+ "wildfires": ("lat", "lon"),
+}
+_CONVERGENCE_GRID_DEGREES = 1.0
+_CONVERGENCE_MIN_DOMAINS = 2
+_CONVERGENCE_MIN_EVENTS = 3
+
+CONVERGENCE_METHOD = (
+ "analysis/convergence.py detect_convergence over the events inside the "
+ "AOI's exact shape (filter_by_aoi) from earthquakes, military flights, "
+ "ACLED conflict events and wildfires: 1-degree grid, a cell converges "
+ "with events from at least 2 of those domains and at least 3 events, "
+ "cell score = domains x (1 + sqrt(events)). Input = the strongest cell; "
+ "convergence component = min(8, 2 x score), so any convergent cell "
+ "(smallest possible score 5.46) earns the full 8. A cell's lat/lon is "
+ "its grid-cell centre, which can lie outside a small AOI."
+)
+
+
+def _parse_gdelt_step(raw: Any) -> datetime | None:
+ try:
+ return datetime.strptime(str(raw), "%Y%m%dT%H%M%SZ").replace(
+ tzinfo=timezone.utc
+ )
+ except ValueError:
+ return None
+
+
+def _is_count(value: Any) -> bool:
+ return (
+ isinstance(value, (int, float)) and not isinstance(value, bool) and value >= 0
+ )
+
+
+def _iso(dt: datetime) -> str:
+ return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def news_coverage_trend(timeline: Any, now: datetime | None = None) -> dict:
+ """Escalation signal from a GDELT ``timelinevolraw`` timeline: the
+ area's share of all GDELT-monitored coverage in the latest
+ ``NEWS_WINDOW_DAYS`` days against the same span just before (the
+ formula is ``NEWS_METHOD``).
+
+ Shares, not raw counts, because GDELT's intake swings by weekday and
+ has whole-day outages; a share is unaffected by how much GDELT
+ happened to ingest, and a partly filled latest step simply weighs
+ less. Steps GDELT has no data for count in neither window, and the
+ comparison is refused when the two windows' intake is too uneven
+ (``_NEWS_MIN_INTAKE_RATIO``).
+
+ Returns the comparison (window bounds, articles, monitored volume,
+ shares, ``expected_articles``, ``change_pct`` and ``score_input``,
+ the non-negative value the escalation score takes) or a dict with
+ ``error`` naming why the timeline cannot support one. Pure: no I/O;
+ ``now`` is injectable.
+ """
+ now = now or datetime.now(timezone.utc)
+ data = None
+ if isinstance(timeline, list):
+ for series in timeline:
+ if isinstance(series, dict) and isinstance(series.get("data"), list):
+ if series["data"]:
+ data = series["data"]
+ break
+ if not data:
+ return {
+ "error": (
+ "GDELT returned no coverage timeline for the query (nothing "
+ "matched in its search window, or an empty upstream answer; "
+ "the two cannot be told apart)"
+ )
+ }
+
+ steps: dict[datetime, tuple[float, float]] = {}
+ for point in data:
+ when = _parse_gdelt_step(point.get("date")) if isinstance(point, dict) else None
+ value = point.get("value") if isinstance(point, dict) else None
+ norm = point.get("norm") if isinstance(point, dict) else None
+ if when is None or not _is_count(value) or not _is_count(norm):
+ return {"error": f"GDELT timeline point is malformed: {point!r}"[:240]}
+ steps[when] = (float(value), float(norm))
+
+ times = sorted(steps)
+ if len(times) < 2:
+ return {
+ "error": (
+ "GDELT timeline holds a single time step; comparing two "
+ "windows needs the step size"
+ )
+ }
+ step = min(b - a for a, b in zip(times, times[1:]))
+ step_s = step.total_seconds()
+ if step_s > 86400 or 86400 % step_s:
+ return {
+ "error": (
+ f"GDELT timeline step of {step_s:.0f} s does not divide a day; "
+ "day windows cannot be formed"
+ )
+ }
+
+ # Anchor both windows to the step containing `now` on the series' own
+ # grid, so a feed that stopped updating leaves its silent days inside
+ # the current window instead of sliding the comparison into the past
+ # (and steps after `now`, when replaying history, fall outside both).
+ last = times[-1]
+ current_step = last + step * math.floor((now - last) / step)
+ window = timedelta(days=NEWS_WINDOW_DAYS)
+ end = current_step + step
+ cur_start = end - window
+ pri_start = cur_start - window
+ per_window = int(window / step)
+
+ def _window(start: datetime, stop: datetime) -> dict:
+ present = [steps[t] for t in times if start <= t < stop]
+ return {
+ "start": _iso(start),
+ "end": _iso(stop),
+ "articles": int(sum(v for v, _ in present)),
+ "monitored_articles": int(sum(n for _, n in present)),
+ "steps_with_data": len(present),
+ "steps": per_window,
+ }
+
+ cur = _window(cur_start, end)
+ pri = _window(pri_start, cur_start)
+ out: dict[str, Any] = {
+ "window_days": NEWS_WINDOW_DAYS,
+ "step_seconds": int(step_s),
+ "latest_step": _iso(last),
+ "current_window": cur,
+ "prior_window": pri,
+ "method": NEWS_METHOD,
+ }
+
+ cur_norm, pri_norm = cur["monitored_articles"], pri["monitored_articles"]
+ low, high = min(cur_norm, pri_norm), max(cur_norm, pri_norm)
+ if low <= 0 or low < _NEWS_MIN_INTAKE_RATIO * high:
+ out["error"] = (
+ f"GDELT intake too uneven to compare: it monitored {pri_norm:,} "
+ f"articles in the prior {NEWS_WINDOW_DAYS} days ({pri['steps_with_data']} "
+ f"of {per_window} steps with data) and {cur_norm:,} in the latest "
+ f"{NEWS_WINDOW_DAYS} ({cur['steps_with_data']} of {per_window}), so a "
+ "comparison would measure GDELT's ingestion gaps, not the news"
+ )
+ return out
+
+ prior_share = pri["articles"] / pri_norm
+ expected = prior_share * cur_norm
+ change_pct = (
+ 100.0 * (cur["articles"] - expected) / max(expected, _NEWS_EXPECTED_FLOOR)
+ )
+ pri["share_per_10k"] = round(prior_share * 1e4, 2)
+ cur["share_per_10k"] = round(cur["articles"] / cur_norm * 1e4, 2)
+ out["expected_articles"] = round(expected, 1)
+ out["change_pct"] = round(change_pct, 1)
+ out["score_input"] = round(max(0.0, change_pct), 1)
+
+ missing = 2 * per_window - cur["steps_with_data"] - pri["steps_with_data"]
+ if missing > 0:
+ out["note"] = (
+ f"GDELT has no data for {missing} of the {2 * per_window} time steps "
+ "compared; each window's share covers the steps it has."
+ )
+ return out
+
+
+def aoi_convergence(scoped: dict[str, dict]) -> dict:
+ """Multi-domain convergence inside an AOI: ``detect_convergence``
+ (``analysis/convergence.py``, unmodified) over the in-fence events of
+ the four geolocated domains in ``_CONVERGENCE_DOMAINS``. ``scoped``
+ maps each domain to its ``_scope_to_aoi`` result, so the events are
+ already filtered to the AOI's exact shape (circle, polygon or
+ corridor).
+
+ ``score`` is the strongest convergent cell's score, the escalation
+ input. It is a measured 0.0 only when every input domain answered in
+ full. With a domain failed or partial, a positive score is reported
+ with ``lower_bound`` true (with uniform weights a cell scores
+ domains x (1 + sqrt(events)), so the missing events could only raise
+ it), and no convergent cell yields ``score`` None plus ``error``,
+ because quiet cannot be told from missing.
+ """
+ events: list[dict] = []
+ events_by_domain: dict[str, int] = {}
+ used: list[str] = []
+ failed: list[str] = []
+ partial: list[str] = []
+ for domain, (lat_key, lon_key) in _CONVERGENCE_DOMAINS.items():
+ result = scoped.get(domain) or {}
+ if result.get("error") or "items" not in result:
+ failed.append(domain)
+ continue
+ used.append(domain)
+ if result.get("partial_errors"):
+ partial.append(domain)
+ events_by_domain[domain] = len(result["items"])
+ events.extend(
+ {"lat": item.get(lat_key), "lon": item.get(lon_key), "type": domain}
+ for item in result["items"]
+ )
+
+ cells = detect_convergence(
+ events,
+ resolution=_CONVERGENCE_GRID_DEGREES,
+ min_types=_CONVERGENCE_MIN_DOMAINS,
+ min_total=_CONVERGENCE_MIN_EVENTS,
+ )
+ incomplete = failed + partial
+ out: dict[str, Any] = {
+ "score": None,
+ "lower_bound": False,
+ "convergent_cells": len(cells),
+ "cells": cells[:5],
+ "events_by_domain": events_by_domain,
+ "inputs_used": used,
+ "inputs_failed": failed,
+ "inputs_partial": partial,
+ "method": CONVERGENCE_METHOD,
+ }
+ if not used:
+ out["error"] = "no convergence input domain answered"
+ elif incomplete and not cells:
+ out["error"] = (
+ f"no convergent cell among {', '.join(used)}, but "
+ f"{', '.join(incomplete)} answered only partly or not at all, so "
+ "quiet cannot be told from missing"
+ )
+ else:
+ out["score"] = cells[0]["convergence_score"] if cells else 0.0
+ out["lower_bound"] = bool(incomplete)
+ return out
+
+
+async def _aoi_news_timeline(fetcher, aoi_row: dict) -> tuple[dict, dict]:
+ """The escalation's news input: GDELT's per-step article counts
+ (``timelinevolraw``) for the place the AOI sits in, searched with the
+ same geocoded query the brief uses (``_aoi_news_query``). Returns
+ ``(result, scoping)``; ``scoping["query"]`` is the query actually
+ sent, or None when none was.
+
+ When the area cannot be placed, the only query left is the AOI's own
+ name (the brief's fallback), which counts mentions of a label rather
+ than coverage of the area; it is not sent, ``scoping["basis"]`` is
+ ``"unavailable"`` and ``result`` is an error instead."""
+ from ..sources import news
+
+ try:
+ query, scoping = await _aoi_news_query(fetcher, aoi_row)
+ except Exception as exc:
+ logger.warning("AOI escalation: news query failed: %s", exc)
+ return {"error": f"the news query could not be built: {exc}"}, {
+ "basis": "unavailable",
+ "query": None,
+ "reason": str(exc),
+ }
+ if scoping.get("basis") != "geocoded":
+ reason = scoping.get("reason") or "no named place"
+ return {
+ "error": (
+ f"not scored: the area could not be placed ({reason}), and "
+ "counting mentions of the AOI's own name would not measure "
+ "coverage of the area"
+ )
+ }, {"basis": "unavailable", "query": None, "reason": reason}
+ result = await _safe_fetch(
+ news.fetch_gdelt_search(fetcher, query=query, mode="timelinevolraw"),
+ "news_timeline",
+ )
+ return result, scoping
+
async def fetch_aoi_escalation(fetcher, store: AOIStore, name: Any) -> dict:
"""Run the existing hotspot escalation scoring (``score_hotspot`` in
``analysis/escalation.py``, unmodified) on a user-defined AOI instead
- of only the 22 built-in intel hotspots. Gathers military and conflict
- signals scoped to the AOI's own radius (via haversine), rather than
- the fixed 2-degree window ``fetch_hotspot_escalation`` uses for the
- built-ins."""
+ of only the 22 built-in intel hotspots.
+
+ Military and conflict signals are scoped to the AOI's exact shape,
+ rather than the fixed 2-degree window ``fetch_hotspot_escalation``
+ uses for the built-ins. The news component is the rise in the
+ area's share of GDELT coverage, this week against last, for the
+ geocoded place (``news_coverage_trend``). The convergence component
+ is ``analysis/convergence.py`` run over the in-fence earthquakes,
+ military flights, conflict events and wildfires (``aoi_convergence``).
+
+ When the news or convergence inputs fail, that component is
+ ``None`` in ``components``, listed in ``unavailable_components`` and
+ explained in ``data_gaps``, never a 0; ``computed_from`` names the
+ components the score was renormalized over. A military or ACLED
+ failure is named in ``data_gaps`` but still enters the score as 0,
+ because ``score_hotspot`` takes no null for those components;
+ ``zero_filled_components`` lists which of ``computed_from`` that
+ happened to, so a reader can tell those zeros from measured quiet.
+ ``news_signal`` and ``convergence_signal`` carry the working for
+ both new components."""
if not isinstance(name, str) or not name.strip():
return {"error": "name must be a non-empty string."}
@@ -1619,28 +1958,45 @@ async def fetch_aoi_escalation(fetcher, store: AOIStore, name: Any) -> dict:
}
from ..sources import conflict as conflict_mod
+ from ..sources import seismology
lat, lon, radius_km = aoi["lat"], aoi["lon"], aoi["radius_km"]
aoi_name = aoi["name"]
bboxes = bboxes_from_radius_km(lat, lon, radius_km)
+ wildfire_regions = _overlapping_wildfire_regions(lat, lon, radius_km)
- acled_result, mil_result = await asyncio.gather(
+ (
+ acled_result,
+ mil_result,
+ eq_result,
+ wildfire_result,
+ (news_result, news_scoping),
+ ) = await asyncio.gather(
_safe_fetch(conflict_mod.fetch_acled_events(fetcher, days=7), "acled_events"),
_fetch_military_merged(fetcher, bboxes),
+ _safe_fetch(seismology.fetch_earthquakes(fetcher, hours=72), "earthquakes"),
+ _safe_fetch(_fetch_wildfires_for_aoi(fetcher, wildfire_regions), "wildfires"),
+ _aoi_news_timeline(fetcher, aoi),
)
+ scoped = {
+ "earthquakes": _scope_to_aoi(
+ eq_result, "earthquakes", aoi, "latitude", "longitude"
+ ),
+ "military_flights": _scope_to_aoi(
+ mil_result, "aircraft", aoi, "latitude", "longitude"
+ ),
+ "conflict_events": _scope_to_aoi(
+ acled_result, "events", aoi, "latitude", "longitude"
+ ),
+ "wildfires": _scope_to_aoi(wildfire_result, "clusters", aoi, "lat", "lon"),
+ }
data_gaps: list[str] = []
conflict_count = fatalities = protests = 0
- if isinstance(acled_result, dict) and acled_result.get("error"):
- data_gaps.append(f"Conflict events: {acled_result['error']}")
+ if scoped["conflict_events"].get("error"):
+ data_gaps.append(f"Conflict events: {scoped['conflict_events']['error']}")
else:
- events = filter_by_aoi(
- acled_result.get("events", []) if isinstance(acled_result, dict) else [],
- aoi,
- "latitude",
- "longitude",
- )
- for ev in events:
+ for ev in scoped["conflict_events"]["items"]:
if "protest" in (ev.get("event_type") or "").lower():
protests += 1
else:
@@ -1648,20 +2004,41 @@ async def fetch_aoi_escalation(fetcher, store: AOIStore, name: Any) -> dict:
fatalities += ev.get("fatalities") or 0
military_count = 0
- if isinstance(mil_result, dict) and mil_result.get("error"):
- data_gaps.append(f"Military flights: {mil_result['error']}")
+ if scoped["military_flights"].get("error"):
+ data_gaps.append(f"Military flights: {scoped['military_flights']['error']}")
else:
- for partial in (
- mil_result.get("partial_errors", []) if isinstance(mil_result, dict) else []
- ):
+ for partial in scoped["military_flights"].get("partial_errors", []):
data_gaps.append(f"Military flights: partial coverage: {partial}")
- aircraft = filter_by_aoi(
- mil_result.get("aircraft", []) if isinstance(mil_result, dict) else [],
- aoi,
- "latitude",
- "longitude",
+ military_count = len(scoped["military_flights"]["items"])
+
+ for domain, label in (("earthquakes", "Earthquakes"), ("wildfires", "Wildfires")):
+ if scoped[domain].get("error"):
+ data_gaps.append(f"{label}: {scoped[domain]['error']}")
+
+ convergence = aoi_convergence(scoped)
+ if convergence.get("error"):
+ data_gaps.append(f"Convergence: not scored; {convergence['error']}.")
+ elif convergence["lower_bound"]:
+ incomplete = convergence["inputs_failed"] + convergence["inputs_partial"]
+ data_gaps.append(
+ f"Convergence: computed without full {', '.join(incomplete)} data; "
+ f"{convergence['score']} is a lower bound (the missing events could "
+ "only raise it)."
)
- military_count = len(aircraft)
+
+ if news_result.get("error"):
+ trend: dict[str, Any] = {"error": str(news_result["error"])}
+ else:
+ trend = news_coverage_trend(news_result.get("timeline"))
+ news_signal = {
+ "query": news_scoping.get("query"),
+ "basis": news_scoping.get("basis"),
+ **trend,
+ }
+ if news_signal.get("error"):
+ data_gaps.append(f"News: {news_signal['error']}.")
+ elif news_signal.get("note"):
+ data_gaps.append(f"News: {news_signal['note']}")
hotspot_config = {
"lat": lat,
@@ -1671,10 +2048,10 @@ async def fetch_aoi_escalation(fetcher, store: AOIStore, name: Any) -> dict:
}
scored = score_hotspot(
hotspot_config,
- news_mentions=None,
+ news_mentions=None if news_signal.get("error") else news_signal["score_input"],
military_count=military_count,
conflict_events=conflict_count,
- convergence_score=None,
+ convergence_score=convergence["score"],
fatalities=fatalities,
protests=protests,
)
@@ -1687,11 +2064,25 @@ async def fetch_aoi_escalation(fetcher, store: AOIStore, name: Any) -> dict:
"radius_km": radius_km,
"kind": aoi.get("kind", "circle"),
},
- "unavailable_components": ["news", "convergence"],
+ "unavailable_components": scored["unavailable_components"],
"data_gaps": data_gaps,
"source": "aoi-escalation",
"timestamp": _utc_now_iso(),
**scored,
+ "computed_from": [
+ comp for comp, points in scored["components"].items() if points is not None
+ ],
+ "zero_filled_components": (
+ (["military"] if scoped["military_flights"].get("error") else [])
+ + (
+ ["conflict", "social_unrest"]
+ if scoped["conflict_events"].get("error")
+ else []
+ )
+ ),
+ "news_scoping": news_scoping,
+ "news_signal": news_signal,
+ "convergence_signal": convergence,
}
diff --git a/src/world_intel_mcp/tests/test_aoi.py b/src/world_intel_mcp/tests/test_aoi.py
index eaf9b4f..016083d 100644
--- a/src/world_intel_mcp/tests/test_aoi.py
+++ b/src/world_intel_mcp/tests/test_aoi.py
@@ -42,6 +42,33 @@ _NEAR_LAT, _NEAR_LON = 40.50, -80.00
_FAR_LAT, _FAR_LON = 42.33, -83.05
+async def _unstubbed_domain(*args, **kwargs) -> dict:
+ return {"error": "domain not stubbed by this test"}
+
+
[email protected](autouse=True)
+def _no_live_domains(monkeypatch: pytest.MonkeyPatch) -> None:
+ """No test in this module reaches a live API: every network-bound
+ source function the AOI tools compose defaults to an outage. A test
+ that wants data for a domain stubs it (``_patch_all_domains`` or its
+ own ``monkeypatch.setattr``), which overrides this default.
+
+ Added with the escalation news and convergence components (Phase 23):
+ ``fetch_aoi_escalation`` now also reverse-geocodes and queries GDELT,
+ USGS and FIRMS, which the escalation tests written before it (they
+ stub only ACLED and military) would otherwise send live."""
+ for module, attr in (
+ (geocode, "fetch_place_context"),
+ (seismology, "fetch_earthquakes"),
+ (military, "fetch_military_flights"),
+ (conflict, "fetch_acled_events"),
+ (wildfire, "fetch_wildfires"),
+ (aviation, "fetch_domestic_flights"),
+ (news, "fetch_gdelt_search"),
+ ):
+ monkeypatch.setattr(module, attr, _unstubbed_domain)
+
+
@pytest.fixture
def store(tmp_path: Path) -> AOIStore:
s = AOIStore(tmp_path / "test_aoi_cache.db")
diff --git a/src/world_intel_mcp/tests/test_aoi_escalation.py b/src/world_intel_mcp/tests/test_aoi_escalation.py
new file mode 100644
index 0000000..8214c2f
--- /dev/null
+++ b/src/world_intel_mcp/tests/test_aoi_escalation.py
@@ -0,0 +1,1223 @@
+"""Tests for the news and convergence components of intel_aoi_escalation
+(ROADMAP Phase 23, "Escalation news + convergence components").
+
+Before this change ``fetch_aoi_escalation`` reported both components as
+null unconditionally. These tests pin real values:
+
+* news: the rise in the area's share of GDELT coverage, this week
+ against last, for the reverse-geocoded place
+ (``aoi.news_coverage_trend``);
+* convergence: ``analysis/convergence.py`` over the in-fence events of
+ four geolocated domains, scoped to the AOI's exact shape
+ (``aoi.aoi_convergence``).
+
+Each expected number is worked by hand in a comment next to its
+assertion. No test reaches a live API: the autouse fixture turns every
+network-bound source the escalation composes into an outage, and a test
+that wants data stubs that domain or mocks its HTTP edge with respx. The
+two respx tests replay responses captured live on 2026-10-17.
+"""
+
+import functools
+import random
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import httpx
+import pytest
+import respx
+
+from world_intel_mcp.analysis import aoi
+from world_intel_mcp.analysis.aoi import AOIStore
+from world_intel_mcp.sources import (
+ aviation,
+ conflict,
+ geocode,
+ military,
+ news,
+ seismology,
+ wildfire,
+)
+
+# The real HTTP-backed functions, kept before any test patches them, for
+# the respx tests that exercise them end to end.
+_REAL_FETCH_PLACE_CONTEXT = geocode.fetch_place_context
+_REAL_FETCH_GDELT_SEARCH = news.fetch_gdelt_search
+
+
+async def _outage(*args, **kwargs) -> dict:
+ return {"error": "domain not stubbed by this test"}
+
+
[email protected](autouse=True)
+def _hermetic_domains(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Every source the escalation composes defaults to an outage, so a
+ forgotten stub shows up as a data gap instead of a live request."""
+ for module, attr in (
+ (geocode, "fetch_place_context"),
+ (seismology, "fetch_earthquakes"),
+ (military, "fetch_military_flights"),
+ (conflict, "fetch_acled_events"),
+ (wildfire, "fetch_wildfires"),
+ (aviation, "fetch_domestic_flights"),
+ (news, "fetch_gdelt_search"),
+ ):
+ monkeypatch.setattr(module, attr, _outage)
+
+
+def store(tmp_path: Path) -> AOIStore:
+ s = AOIStore(tmp_path / "test_aoi_escalation.db")
+ yield s
+ s.close()
+
+
+# Pittsburgh, the README worked example: a 50 km circle.
+_PGH_LAT, _PGH_LON, _PGH_RADIUS_KM = 40.4406, -79.9959, 50.0
+_PGH_QUERY = '("Pittsburgh" OR "Allegheny County")'
+# ~7 km from the centre (inside); Detroit area, ~330 km (outside).
+_NEAR = (40.50, -80.00)
+_FAR = (42.33, -83.05)
+
+# A square around Pittsburgh, and a point inside its bounding circle but
+# outside the square (same geometry as test_aoi.py's polygon tests).
+_PGH_SQUARE = [[39.5, -81.0], [39.5, -79.0], [41.3, -79.0], [41.3, -81.0]]
+_IN_SQUARE = (40.4, -80.0)
+_IN_CIRCLE_NOT_SQUARE = (40.4, -78.7)
+
+# A 20 km wide corridor along latitude 40 from -81 to -79. Its bounding
+# circle (centroid 40.0, -80.0; radius ~95 km) contains the off-route
+# point, ~67 km from the route and so outside the 10 km half-width.
+_ROUTE = [[40.0, -81.0], [40.0, -79.0]]
+_ON_ROUTE = (40.0, -80.0)
+_OFF_ROUTE = (40.6, -80.0)
+
+_SIX = ["baseline", "news", "military", "conflict", "social_unrest", "convergence"]
+
+_PLACE = {
+ "place": "Pittsburgh",
+ "county": "Allegheny County",
+ "state": "Pennsylvania",
+ "country_code": "us",
+ "display_name": "Pittsburgh, Allegheny County, Pennsylvania, United States",
+ "terms": ["Pittsburgh", "Allegheny County"],
+ "source": "nominatim-reverse",
+}
+
+# geocode.fetch_place_context's answer for a point with no named place.
+_UNNAMED = "No named place at 40.4406, -79.9959 (open water or unnamed area)."
+
+# GDELT's documented degraded answer from sources/news.py.
+_GDELT_DOWN = "GDELT fetch failed (rate limited, API error, or malformed response)"
+
+# Test clock: windows are the 7 days ending with the step containing it.
+_NOW = datetime(2026, 10, 17, 16, 30, tzinfo=timezone.utc)
+_PRIOR_START = datetime(2026, 10, 4, tzinfo=timezone.utc) # prior: Oct 4-10
+
+
+# ---------------------------------------------------------------------------
+# Builders
+# ---------------------------------------------------------------------------
+
+
+def _steps(start: datetime, step: timedelta, counts: list[tuple[int, int]]) -> list:
+ """GDELT ``timelinevolraw`` points: (matching articles, all monitored
+ articles) per step from ``start``."""
+ return [
+ {
+ "date": (start + step * i).strftime("%Y%m%dT%H%M%SZ"),
+ "value": value,
+ "norm": norm,
+ }
+ for i, (value, norm) in enumerate(counts)
+ ]
+
+
+def _timeline(points: list[dict]) -> list[dict]:
+ return [{"series": "Article Count", "data": points}]
+
+
+def _two_weeks(prior: list[tuple[int, int]], current: list[tuple[int, int]]) -> list:
+ """Daily timeline: ``prior`` for Oct 4-10, ``current`` for Oct 11-17."""
+ return _timeline(_steps(_PRIOR_START, timedelta(days=1), prior + current))
+
+
+_FLAT_WEEKS = _two_weeks([(10, 1000)] * 7, [(10, 1000)] * 7) # change 0.0
+_RISING_WEEKS = _two_weeks([(10, 1000)] * 7, [(15, 1000)] * 7) # change +50.0
+
+
+def _quake(point: tuple[float, float]) -> dict:
+ return {"latitude": point[0], "longitude": point[1], "magnitude": 4.6}
+
+
+def _aircraft(point: tuple[float, float], icao: str) -> dict:
+ return {"latitude": point[0], "longitude": point[1], "icao24": icao}
+
+
+def _battle(point: tuple[float, float], fatalities: int = 0) -> dict:
+ return {
+ "event_type": "Battles",
+ "latitude": point[0],
+ "longitude": point[1],
+ "fatalities": fatalities,
+ }
+
+
+def _protest(point: tuple[float, float]) -> dict:
+ return {
+ "event_type": "Protests",
+ "latitude": point[0],
+ "longitude": point[1],
+ "fatalities": 0,
+ }
+
+
+def _fire(point: tuple[float, float]) -> dict:
+ return {"lat": point[0], "lon": point[1], "fire_count": 3, "max_frp": 10.0}
+
+
+def _install(
+ monkeypatch: pytest.MonkeyPatch,
+ *,
+ quakes: list | str | None = None,
+ aircraft: list | str | None = None,
+ acled: list | str | None = None,
+ fires: list | str | None = None,
+ place: dict | None = _PLACE,
+ timeline: list | None = None,
+ gdelt: dict | Exception | None = None,
+ now: datetime = _NOW,
+) -> dict:
+ """Stub the escalation's sources. A list is that domain's events, a
+ str its fetch error, None leaves the autouse outage. GDELT answers
+ ``timeline`` unless ``gdelt`` overrides it with a result dict or an
+ exception to raise. The news trend's clock is pinned to ``now``.
+ Returns the recorded geocode and GDELT calls."""
+ calls: dict[str, list] = {"geocode": [], "gdelt": []}
+
+ def _answer(value, key):
+ return {"error": value} if isinstance(value, str) else {key: value}
+
+ if quakes is not None:
+
+ async def _quakes(fetcher, **kwargs):
+ return _answer(quakes, "earthquakes")
+
+ monkeypatch.setattr(seismology, "fetch_earthquakes", _quakes)
+ if aircraft is not None:
+
+ async def _military(fetcher, bbox=None):
+ return _answer(aircraft, "aircraft")
+
+ monkeypatch.setattr(military, "fetch_military_flights", _military)
+ if acled is not None:
+
+ async def _acled(fetcher, **kwargs):
+ return _answer(acled, "events")
+
+ monkeypatch.setattr(conflict, "fetch_acled_events", _acled)
+ if fires is not None:
+
+ async def _fires(fetcher, region=None):
+ if isinstance(fires, str):
+ return {"error": fires}
+ return {"fires_by_region": {region: {"top_clusters": fires}}}
+
+ monkeypatch.setattr(wildfire, "fetch_wildfires", _fires)
+ if place is not None:
+
+ async def _place(fetcher, lat, lon):
+ calls["geocode"].append((lat, lon))
+ return place
+
+ monkeypatch.setattr(geocode, "fetch_place_context", _place)
+
+ async def _gdelt(fetcher, **kwargs):
+ calls["gdelt"].append(kwargs)
+ if isinstance(gdelt, Exception):
+ raise gdelt
+ if gdelt is not None:
+ return gdelt
+ return {"timeline": timeline or [], "source": "gdelt"}
+
+ monkeypatch.setattr(news, "fetch_gdelt_search", _gdelt)
+ monkeypatch.setattr(
+ aoi, "news_coverage_trend", functools.partial(aoi.news_coverage_trend, now=now)
+ )
+ return calls
+
+
+def _near_and_far() -> dict:
+ """One event per domain near Pittsburgh and one in Detroit. Inside
+ the fence: 1 quake, 1 aircraft, 1 protest, 1 fire, all in grid cell
+ (40, -80). Outside: the same four domains in cell (42, -84), which
+ would form a second convergent cell if scoping leaked."""
+ return {
+ "quakes": [_quake(_NEAR), _quake(_FAR)],
+ "aircraft": [_aircraft(_NEAR, "a1"), _aircraft(_FAR, "a2")],
+ "acled": [_protest(_NEAR), _battle(_FAR, fatalities=2)],
+ "fires": [_fire(_NEAR), _fire(_FAR)],
+ }
+
+
+def _all_at(point: tuple[float, float]) -> dict:
+ """One quake, one aircraft, one protest and one fire at ``point``."""
+ return {
+ "quakes": [_quake(point)],
+ "aircraft": [_aircraft(point, "a1")],
+ "acled": [_protest(point)],
+ "fires": [_fire(point)],
+ }
+
+
+# ---------------------------------------------------------------------------
+# news_coverage_trend: the news component's input
+# ---------------------------------------------------------------------------
+
+
+def test_news_trend_scores_the_rise_in_coverage_share() -> None:
+ trend = aoi.news_coverage_trend(_RISING_WEEKS, now=_NOW)
+
+ assert "error" not in trend
+ assert trend["window_days"] == 7
+ assert trend["step_seconds"] == 86400
+ assert trend["latest_step"] == "2026-10-17T00:00:00Z"
+ # _NOW (Oct 17 16:30) is inside the Oct 17 step, so the current
+ # window is Oct 11-17 and the prior one Oct 4-10.
+ assert trend["current_window"] == {
+ "start": "2026-10-11T00:00:00Z",
+ "end": "2026-10-18T00:00:00Z",
+ "articles": 105, # 7 x 15
+ "monitored_articles": 7000, # 7 x 1000
+ "steps_with_data": 7,
+ "steps": 7,
+ "share_per_10k": 150.0, # 105 / 7000 x 10^4
+ }
+ assert trend["prior_window"] == {
+ "start": "2026-10-04T00:00:00Z",
+ "end": "2026-10-11T00:00:00Z",
+ "articles": 70,
+ "monitored_articles": 7000,
+ "steps_with_data": 7,
+ "steps": 7,
+ "share_per_10k": 100.0, # 70 / 7000 x 10^4
+ }
+ # expected = prior share 70/7000 x current volume 7000 = 70;
+ # change = 100 x (105 - 70) / 70 = +50%.
+ assert trend["expected_articles"] == 70.0
+ assert trend["change_pct"] == 50.0
+ assert trend["score_input"] == 50.0
+ assert "note" not in trend
+ assert "max(expected, 20)" in trend["method"]
+
+
+def test_news_trend_measures_share_not_raw_volume() -> None:
+ """Raw matches rise 80% (70 -> 126) only because GDELT monitored 80%
+ more articles (7000 -> 12600): the share is flat, so no rise."""
+ trend = aoi.news_coverage_trend(
+ _two_weeks([(10, 1000)] * 7, [(18, 1800)] * 7), now=_NOW
+ )
+ assert trend["current_window"]["articles"] == 126
+ assert trend["current_window"]["monitored_articles"] == 12600
+ # expected = 70/7000 x 12600 = 126; change = 0.
+ assert trend["expected_articles"] == 126.0
+ assert trend["change_pct"] == 0.0
+ assert trend["score_input"] == 0.0
+ assert trend["prior_window"]["share_per_10k"] == 100.0
+ assert trend["current_window"]["share_per_10k"] == 100.0
+
+
+def test_news_trend_fall_scores_zero_not_negative() -> None:
+ trend = aoi.news_coverage_trend(
+ _two_weeks([(20, 1000)] * 7, [(10, 1000)] * 7), now=_NOW
+ )
+ # expected = 140/7000 x 7000 = 140; change = 100 x (70 - 140) / 140.
+ assert trend["expected_articles"] == 140.0
+ assert trend["change_pct"] == -50.0
+ assert trend["score_input"] == 0.0
+
+
+def test_news_trend_floor_keeps_a_few_stories_from_reading_as_a_surge() -> None:
+ """Nothing last week and 5 stories this week: the percent change is
+ taken against the 20-article floor, not against an expected 0."""
+ trend = aoi.news_coverage_trend(
+ _two_weeks([(0, 1000)] * 7, [(5, 1000)] + [(0, 1000)] * 6), now=_NOW
+ )
+ assert trend["expected_articles"] == 0.0
+ # 100 x (5 - 0) / max(0, 20) = 25.
+ assert trend["change_pct"] == 25.0
+ assert trend["score_input"] == 25.0
+
+
+def test_news_trend_partly_filled_latest_day_weighs_by_its_intake() -> None:
+ """The current day is half ingested (5 of a normal 10 matches, 500 of
+ 1000 monitored). Raw counts would read 70 -> 65 as a fall; the share
+ is unchanged."""
+ trend = aoi.news_coverage_trend(
+ _two_weeks([(10, 1000)] * 7, [(10, 1000)] * 6 + [(5, 500)]), now=_NOW
+ )
+ assert trend["current_window"]["articles"] == 65
+ assert trend["current_window"]["monitored_articles"] == 6500
+ # expected = 70/7000 x 6500 = 65.
+ assert trend["expected_articles"] == 65.0
+ assert trend["change_pct"] == 0.0
+
+
+def test_news_trend_names_missing_steps_when_intake_still_balances() -> None:
+ points = _steps(_PRIOR_START, timedelta(days=1), [(10, 1000)] * 14)
+ del points[3] # GDELT has nothing for Oct 7
+ trend = aoi.news_coverage_trend(_timeline(points), now=_NOW)
+
+ assert trend["prior_window"]["steps_with_data"] == 6
+ assert trend["prior_window"]["monitored_articles"] == 6000
+ # 6000 >= 0.5 x 7000, so comparable: expected = 60/6000 x 7000 = 70.
+ assert trend["expected_articles"] == 70.0
+ assert trend["change_pct"] == 0.0
+ assert trend["note"] == (
+ "GDELT has no data for 1 of the 14 time steps compared; each "
+ "window's share covers the steps it has."
+ )
+
+
+def test_news_trend_refuses_a_stale_feed() -> None:
+ """A series that stopped on Oct 9 is compared over the week that
+ actually ends now (no data), not slid back to its last two weeks."""
+ start = datetime(2026, 9, 26, tzinfo=timezone.utc)
+ trend = aoi.news_coverage_trend(
+ _timeline(_steps(start, timedelta(days=1), [(10, 1000)] * 14)), now=_NOW
+ )
+ assert trend["latest_step"] == "2026-10-09T00:00:00Z"
+ assert trend["current_window"]["start"] == "2026-10-11T00:00:00Z"
+ assert trend["current_window"]["steps_with_data"] == 0
+ assert trend["error"] == (
+ "GDELT intake too uneven to compare: it monitored 6,000 articles in "
+ "the prior 7 days (6 of 7 steps with data) and 0 in the latest 7 "
+ "(0 of 7), so a comparison would measure GDELT's ingestion gaps, not "
+ "the news"
+ )
+ assert "score_input" not in trend
+ assert "change_pct" not in trend
+
+
+def test_news_trend_hourly_steps() -> None:
+ """Short GDELT timespans come back hourly: windows are 168 steps."""
+ start = datetime(2026, 10, 3, 17, tzinfo=timezone.utc)
+ counts = [(1, 100)] * 168 + [(2, 100)] * 168 # ends Oct 17 16:00
+ trend = aoi.news_coverage_trend(
+ _timeline(_steps(start, timedelta(hours=1), counts)), now=_NOW
+ )
+ assert trend["step_seconds"] == 3600
+ assert trend["latest_step"] == "2026-10-17T16:00:00Z"
+ assert trend["current_window"]["start"] == "2026-10-10T17:00:00Z"
+ assert trend["current_window"]["end"] == "2026-10-17T17:00:00Z"
+ assert trend["current_window"]["steps"] == 168
+ assert trend["current_window"]["steps_with_data"] == 168
+ # expected = 168/16800 x 16800 = 168; change = 100 x (336 - 168) / 168.
+ assert trend["expected_articles"] == 168.0
+ assert trend["change_pct"] == 100.0
+ assert trend["score_input"] == 100.0
+
+
+ "timeline, starts_with",
+ [
+ (None, "GDELT returned no coverage timeline"),
+ ([], "GDELT returned no coverage timeline"),
+ ([{"series": "Article Count", "data": []}], "GDELT returned no coverage"),
+ (
+ _timeline([{"date": "20261017T000000Z", "value": "12", "norm": 900}]),
+ "GDELT timeline point is malformed",
+ ),
+ (
+ _timeline([{"date": "20261017T000000Z", "value": 3, "norm": -1}]),
+ "GDELT timeline point is malformed",
+ ),
+ (
+ _timeline([{"date": "2026-10-17", "value": 3, "norm": 900}]),
+ "GDELT timeline point is malformed",
+ ),
+ (
+ _timeline([{"date": "20261017T000000Z", "value": 3, "norm": 900}]),
+ "GDELT timeline holds a single time step",
+ ),
+ (
+ _timeline(
+ _steps(_PRIOR_START, timedelta(hours=7), [(1, 100)] * 60)
+ ),
+ "GDELT timeline step of 25200 s does not divide a day",
+ ),
+ (
+ _timeline(_steps(_PRIOR_START, timedelta(days=2), [(1, 100)] * 9)),
+ "GDELT timeline step of 172800 s does not divide a day",
+ ),
+ ],
+)
+def test_news_trend_unusable_timeline_is_an_error_not_a_zero(
+ timeline, starts_with
+) -> None:
+ trend = aoi.news_coverage_trend(timeline, now=_NOW)
+ assert trend["error"].startswith(starts_with)
+ assert "score_input" not in trend
+
+
+# ---------------------------------------------------------------------------
+# aoi_convergence: the convergence component's input
+# ---------------------------------------------------------------------------
+
+
+def _scoped(**domains) -> dict:
+ """``aoi_convergence`` input: each domain's items, or {"error"} for
+ a str. Domains not given answered with no events."""
+ out = {}
+ for domain in ("earthquakes", "military_flights", "conflict_events", "wildfires"):
+ value = domains.get(domain, [])
+ out[domain] = {"error": value} if isinstance(value, str) else {"items": value}
+ return out
+
+
+def test_convergence_quiet_area_with_every_input_answered_is_a_measured_zero() -> (
+ None
+):
+ result = aoi.aoi_convergence(_scoped(earthquakes=[_quake(_NEAR)]))
+
+ assert result["score"] == 0.0
+ assert result["lower_bound"] is False
+ assert result["convergent_cells"] == 0
+ assert result["cells"] == []
+ assert result["events_by_domain"] == {
+ "earthquakes": 1,
+ "military_flights": 0,
+ "conflict_events": 0,
+ "wildfires": 0,
+ }
+ assert result["inputs_used"] == [
+ "earthquakes",
+ "military_flights",
+ "conflict_events",
+ "wildfires",
+ ]
+ assert result["inputs_failed"] == []
+ assert "error" not in result
+
+
+def test_convergence_cell_score_is_domains_times_one_plus_sqrt_events() -> None:
+ result = aoi.aoi_convergence(
+ _scoped(
+ earthquakes=[_quake(_NEAR)],
+ military_flights=[_aircraft(_NEAR, "a1")],
+ conflict_events=[_battle(_NEAR), _protest(_NEAR)],
+ wildfires=[_fire(_NEAR)],
+ )
+ )
+ # 5 events from 4 domains in cell (40, -80): 4 x (1 + sqrt 5) = 12.944.
+ assert result["score"] == 12.94
+ assert result["lower_bound"] is False
+ assert result["cells"] == [
+ {
+ "lat": 40.5,
+ "lon": -79.5,
+ "event_count": 5,
+ "signal_types": [
+ "conflict_events",
+ "earthquakes",
+ "military_flights",
+ "wildfires",
+ ],
+ "type_count": 4,
+ "total_weight": 5.0,
+ "convergence_score": 12.94,
+ }
+ ]
+
+
+def test_convergence_with_a_failed_input_is_a_lower_bound() -> None:
+ result = aoi.aoi_convergence(
+ _scoped(
+ military_flights=[_aircraft(_NEAR, "a1")],
+ conflict_events=[_battle(_NEAR), _battle(_NEAR)],
+ wildfires="FIRMS unavailable",
+ )
+ )
+ # 3 events from 2 domains: 2 x (1 + sqrt 3) = 5.464.
+ assert result["score"] == 5.46
+ assert result["lower_bound"] is True
+ assert result["inputs_failed"] == ["wildfires"]
+ assert result["inputs_used"] == [
+ "earthquakes",
+ "military_flights",
+ "conflict_events",
+ ]
+ assert "error" not in result
+
+
+def test_convergence_with_a_failed_input_and_no_cell_is_null_not_zero() -> None:
+ result = aoi.aoi_convergence(
+ _scoped(conflict_events=[_battle(_NEAR)], wildfires="FIRMS unavailable")
+ )
+ assert result["score"] is None
+ assert result["error"] == (
+ "no convergent cell among earthquakes, military_flights, "
+ "conflict_events, but wildfires answered only partly or not at all, "
+ "so quiet cannot be told from missing"
+ )
+
+
+def test_convergence_partial_input_counts_as_incomplete() -> None:
+ scoped = _scoped(conflict_events=[_battle(_NEAR)])
+ scoped["military_flights"] = {
+ "items": [_aircraft(_NEAR, "a1")],
+ "partial_errors": ["box 2: adsb.lol timed out"],
+ }
+ quiet = aoi.aoi_convergence(scoped)
+ assert quiet["score"] is None
+ assert quiet["inputs_partial"] == ["military_flights"]
+ assert "military_flights answered only partly or not at all" in quiet["error"]
+
+ scoped["conflict_events"]["items"].append(_battle(_NEAR))
+ busy = aoi.aoi_convergence(scoped)
+ # 2 battles + 1 aircraft: 2 x (1 + sqrt 3) = 5.464, a lower bound.
+ assert busy["score"] == 5.46
+ assert busy["lower_bound"] is True
+
+
+def test_convergence_with_no_input_answered_is_an_error() -> None:
+ result = aoi.aoi_convergence(
+ _scoped(
+ earthquakes="USGS down",
+ military_flights="adsb.lol down",
+ conflict_events="ACLED down",
+ wildfires="FIRMS down",
+ )
+ )
+ assert result["score"] is None
+ assert result["error"] == "no convergence input domain answered"
+ assert result["inputs_used"] == []
+
+
+def test_convergence_without_a_domain_never_exceeds_the_full_score() -> None:
+ """The lower-bound claim on the real code path: over seeded random
+ event sets spread across four grid cells, dropping any one domain
+ never raises the strongest cell, and a score computed without it is
+ flagged as a lower bound."""
+ rng = random.Random(20261017)
+ makers = {
+ "earthquakes": lambda p: _quake(p),
+ "military_flights": lambda p: _aircraft(p, "x"),
+ "conflict_events": lambda p: _battle(p),
+ "wildfires": lambda p: _fire(p),
+ }
+ checked = 0
+ for _ in range(300):
+ full = _scoped(
+ **{
+ domain: [
+ make((rng.uniform(40.0, 41.99), rng.uniform(-81.0, -79.01)))
+ for _ in range(rng.randint(0, 4))
+ ]
+ for domain, make in makers.items()
+ }
+ )
+ full_score = aoi.aoi_convergence(full)["score"]
+ assert full_score is not None
+ for missing in makers:
+ partial = aoi.aoi_convergence({**full, missing: {"error": "down"}})
+ if partial["score"] is None:
+ assert partial["error"]
+ continue
+ checked += 1
+ assert partial["lower_bound"] is True
+ assert partial["score"] <= full_score
+ assert checked >= 200 # the property was exercised, not vacuous
+
+
+# ---------------------------------------------------------------------------
+# fetch_aoi_escalation end to end (sources stubbed)
+# ---------------------------------------------------------------------------
+
+
+async def test_escalation_scores_news_and_convergence(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ calls = _install(monkeypatch, timeline=_RISING_WEEKS, **_near_and_far())
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ # news: share +50% -> min(20, 0.2 x 50) = 10.0
+ # military: 1 aircraft in the fence -> 1.0
+ # conflict: the only in-fence ACLED event is a protest -> 0.0
+ # social_unrest: 1 protest x 0.4 -> 0.4
+ # convergence: 4 domains x (1 + sqrt 4) = 12.0 -> min(8, 2 x 12) = 8.0
+ assert result["components"] == {
+ "baseline": 0.0,
+ "news": 10.0,
+ "military": 1.0,
+ "conflict": 0.0,
+ "social_unrest": 0.4,
+ "convergence": 8.0,
+ }
+ # 19.4 of 100 possible points.
+ assert result["score"] == 19.4
+ assert result["level"] == "watch"
+ assert result["trend_signal"] == "active"
+ assert result["computed_from"] == _SIX
+ assert result["zero_filled_components"] == []
+ assert result["unavailable_components"] == []
+ assert result["data_gaps"] == []
+ assert result["source"] == "aoi-escalation"
+ assert result["aoi"]["kind"] == "circle"
+
+ # The geo-scoped query, as a coverage timeline, sent once.
+ assert calls["geocode"] == [(_PGH_LAT, _PGH_LON)]
+ assert calls["gdelt"] == [{"query": _PGH_QUERY, "mode": "timelinevolraw"}]
+ assert result["news_scoping"]["basis"] == "geocoded"
+ assert result["news_scoping"]["place"] == "Pittsburgh"
+ assert result["news_signal"]["query"] == _PGH_QUERY
+ assert result["news_signal"]["change_pct"] == 50.0
+ assert result["news_signal"]["expected_articles"] == 70.0
+
+ convergence = result["convergence_signal"]
+ assert convergence["score"] == 12.0
+ assert convergence["lower_bound"] is False
+ # Only the Pittsburgh cell: the Detroit events are outside the fence.
+ assert convergence["convergent_cells"] == 1
+ assert convergence["cells"][0]["lat"] == 40.5
+ assert convergence["cells"][0]["lon"] == -79.5
+ assert convergence["events_by_domain"] == {
+ "earthquakes": 1,
+ "military_flights": 1,
+ "conflict_events": 1,
+ "wildfires": 1,
+ }
+
+
+def _quiet_but_convergent() -> dict:
+ """2 quakes and 1 fire in one cell, no aircraft or ACLED events:
+ convergence 2 x (1 + sqrt 3) = 5.46 -> component 8.0, every other
+ measured component 0.0, so the score is easy to read."""
+ return {
+ "quakes": [_quake(_NEAR), _quake(_NEAR)],
+ "aircraft": [],
+ "acled": [],
+ "fires": [_fire(_NEAR)],
+ }
+
+
+ "gdelt, gap",
+ [
+ (
+ {"error": _GDELT_DOWN, "degraded": True, "timeline": [], "count": 0},
+ f"News: {_GDELT_DOWN}.",
+ ),
+ (httpx.ConnectError("connection refused"), "News: connection refused."),
+ ],
+)
+async def test_escalation_failed_news_query_is_a_gap_not_a_zero(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch, gdelt, gap
+) -> None:
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ _install(monkeypatch, gdelt=gdelt, **_quiet_but_convergent())
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ assert result["components"]["news"] is None
+ assert result["unavailable_components"] == ["news"]
+ assert result["computed_from"] == [c for c in _SIX if c != "news"]
+ assert result["data_gaps"] == [gap]
+ # Renormalized over the 80 points measured: 8.0 / 80 x 100 = 10.0.
+ assert result["score"] == 10.0
+ assert result["news_signal"]["query"] == _PGH_QUERY
+ assert "score_input" not in result["news_signal"]
+
+
+ "failing, error, zero_filled, gap",
+ [
+ (
+ "acled",
+ "ACLED down",
+ ["conflict", "social_unrest"],
+ "Conflict events: ACLED down",
+ ),
+ (
+ "aircraft",
+ "adsb.lol and OpenSky both unavailable",
+ ["military"],
+ "Military flights: adsb.lol and OpenSky both unavailable",
+ ),
+ ],
+)
+async def test_escalation_names_components_zero_filled_for_want_of_data(
+ fetcher,
+ store: AOIStore,
+ monkeypatch: pytest.MonkeyPatch,
+ failing,
+ error,
+ zero_filled,
+ gap,
+) -> None:
+ """score_hotspot takes no null for military, conflict or social
+ unrest, so a failed military or ACLED fetch still enters the score
+ as 0. The response names those zeros instead of letting them pass
+ as measured quiet."""
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ inputs = _quiet_but_convergent()
+ inputs[failing] = error
+ _install(monkeypatch, timeline=_FLAT_WEEKS, **inputs)
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ assert result["zero_filled_components"] == zero_filled
+ assert all(result["components"][c] == 0.0 for c in zero_filled)
+ assert set(zero_filled) <= set(result["computed_from"])
+ assert gap in result["data_gaps"]
+
+
+async def test_escalation_flat_news_week_is_a_measured_zero(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """Same inputs with GDELT answering a flat share: news is a real 0.0
+ and counts, so the score is 8.0 of 100 instead of 10.0 of 80."""
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ _install(monkeypatch, timeline=_FLAT_WEEKS, **_quiet_but_convergent())
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ assert result["components"]["news"] == 0.0
+ assert result["components"]["convergence"] == 8.0
+ assert result["computed_from"] == _SIX
+ assert result["score"] == 8.0
+ assert result["data_gaps"] == []
+
+
+ "place, reason",
+ [
+ (
+ {"error": "Reverse geocoding unavailable: Nominatim down", "place": None},
+ "Reverse geocoding failed: Reverse geocoding unavailable: Nominatim down",
+ ),
+ (
+ {"place": None, "terms": [], "note": _UNNAMED},
+ _UNNAMED,
+ ),
+ ],
+)
+async def test_escalation_unplaced_area_sends_no_name_mention_query(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch, place, reason
+) -> None:
+ """Without a geocoded place the brief falls back to the AOI's name;
+ the escalation does not, because mentions of a label are not
+ coverage of the area."""
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ calls = _install(
+ monkeypatch, place=place, timeline=_RISING_WEEKS, **_quiet_but_convergent()
+ )
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ assert calls["gdelt"] == []
+ assert result["components"]["news"] is None
+ assert result["news_scoping"] == {
+ "basis": "unavailable",
+ "query": None,
+ "reason": reason,
+ }
+ assert result["news_signal"]["query"] is None
+ assert result["data_gaps"] == [
+ f"News: not scored: the area could not be placed ({reason}), and "
+ "counting mentions of the AOI's own name would not measure coverage "
+ "of the area."
+ ]
+
+
+async def test_escalation_geocoder_exception_is_a_gap_not_a_crash(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ calls = _install(monkeypatch, timeline=_RISING_WEEKS, **_quiet_but_convergent())
+
+ async def _raises(fetcher, lat, lon):
+ raise RuntimeError("geocoder exploded")
+
+ monkeypatch.setattr(geocode, "fetch_place_context", _raises)
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ assert calls["gdelt"] == []
+ assert result["components"]["news"] is None
+ assert result["news_scoping"] == {
+ "basis": "unavailable",
+ "query": None,
+ "reason": "geocoder exploded",
+ }
+ assert result["data_gaps"] == [
+ "News: the news query could not be built: geocoder exploded."
+ ]
+ # Convergence 8.0 of the 80 points measured: 8.0 / 80 x 100 = 10.0.
+ assert result["score"] == 10.0
+
+
+async def test_escalation_names_gdelt_steps_with_no_data(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """News is still scored when the intake balances, and the missing
+ GDELT step is named as a gap."""
+ points = _steps(_PRIOR_START, timedelta(days=1), [(10, 1000)] * 14)
+ del points[3] # GDELT has nothing for Oct 7
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ _install(monkeypatch, timeline=_timeline(points), **_quiet_but_convergent())
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ # Share flat (60/6000 vs 70/7000): news 0.0, measured; 8.0 of 100.
+ assert result["components"]["news"] == 0.0
+ assert result["computed_from"] == _SIX
+ assert result["score"] == 8.0
+ assert result["data_gaps"] == [
+ "News: GDELT has no data for 1 of the 14 time steps compared; each "
+ "window's share covers the steps it has."
+ ]
+
+
+ "point, convergence, military",
+ [
+ (_IN_CIRCLE_NOT_SQUARE, 0.0, 0.0), # in the bounding circle only
+ (_IN_SQUARE, 8.0, 1.0), # positive control
+ ],
+)
+async def test_escalation_convergence_is_scoped_to_the_polygon(
+ fetcher,
+ store: AOIStore,
+ monkeypatch: pytest.MonkeyPatch,
+ point,
+ convergence,
+ military,
+) -> None:
+ aoi.define_polygon_aoi(store, "PGH Square", _PGH_SQUARE)
+ _install(monkeypatch, timeline=_FLAT_WEEKS, **_all_at(point))
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "PGH Square")
+
+ assert result["aoi"]["kind"] == "polygon"
+ assert result["components"]["convergence"] == convergence
+ assert result["components"]["military"] == military
+ # Every input answered, so an empty fence is a measured 0.0.
+ assert result["computed_from"] == _SIX
+ expected_events = 1 if convergence else 0
+ assert result["convergence_signal"]["events_by_domain"] == {
+ "earthquakes": expected_events,
+ "military_flights": expected_events,
+ "conflict_events": expected_events,
+ "wildfires": expected_events,
+ }
+
+
+ "point, convergence",
+ [
+ (_OFF_ROUTE, 0.0), # in the bounding circle, 67 km off the route
+ (_ON_ROUTE, 8.0), # positive control
+ ],
+)
+async def test_escalation_convergence_is_scoped_to_the_corridor(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch, point, convergence
+) -> None:
+ aoi.define_corridor_aoi(store, "Route 40", _ROUTE, width_km=20.0)
+ _install(monkeypatch, timeline=_FLAT_WEEKS, **_all_at(point))
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Route 40")
+
+ assert result["aoi"]["kind"] == "corridor"
+ assert result["components"]["convergence"] == convergence
+ assert result["convergence_signal"]["convergent_cells"] == (1 if convergence else 0)
+
+
+async def test_escalation_convergence_without_wildfires_is_a_lower_bound(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ _install(
+ monkeypatch,
+ timeline=_FLAT_WEEKS,
+ quakes=[],
+ aircraft=[_aircraft(_NEAR, "a1")],
+ acled=[_battle(_NEAR), _battle(_NEAR)],
+ fires="NASA_FIRMS_API_KEY not set",
+ )
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ # 2 battles + 1 aircraft: 2 x (1 + sqrt 3) = 5.46 -> min(8, 10.9) = 8.0.
+ assert result["convergence_signal"]["score"] == 5.46
+ assert result["convergence_signal"]["lower_bound"] is True
+ assert result["components"]["convergence"] == 8.0
+ # military 1.0 + conflict 2 x 0.5 = 1.0 + convergence 8.0 = 10.0 of 100.
+ assert result["score"] == 10.0
+ assert result["data_gaps"] == [
+ "Wildfires: NASA_FIRMS_API_KEY not set",
+ "Convergence: computed without full wildfires data; 5.46 is a lower "
+ "bound (the missing events could only raise it).",
+ ]
+
+
+async def test_escalation_convergence_without_wildfires_and_no_cell_is_null(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ _install(
+ monkeypatch,
+ timeline=_FLAT_WEEKS,
+ quakes=[],
+ aircraft=[],
+ acled=[_battle(_NEAR)],
+ fires="NASA_FIRMS_API_KEY not set",
+ )
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ assert result["components"]["convergence"] is None
+ assert result["unavailable_components"] == ["convergence"]
+ assert result["computed_from"] == [c for c in _SIX if c != "convergence"]
+ assert result["data_gaps"] == [
+ "Wildfires: NASA_FIRMS_API_KEY not set",
+ "Convergence: not scored; no convergent cell among earthquakes, "
+ "military_flights, conflict_events, but wildfires answered only partly "
+ "or not at all, so quiet cannot be told from missing.",
+ ]
+ # conflict 1 x 0.5 = 0.5 of the 92 points measured:
+ # 0.5 / 92 x 100 = 0.54, which rounds to 0.5.
+ assert result["score"] == 0.5
+
+
+# ---------------------------------------------------------------------------
+# Real geocode + GDELT paths, replaying responses captured live
+# ---------------------------------------------------------------------------
+
+# Captured live 2026-10-17T16:57:53Z: GET
+# https://api.gdeltproject.org/api/v2/doc/doc with the parameters
+# fetch_gdelt_search sends for this AOI (query ("Pittsburgh" OR
+# "Allegheny County"), mode timelinevolraw, maxrecords 50, format json,
+# no timespan). GDELT answered daily steps from 2026-07-25 to 2026-10-17
+# (every step at T000000Z, shortened to its day here). 16 of those 85 days
+# are absent and Oct 6, 8 and 10 hold a sliver of a normal day's volume:
+# an ingestion outage, not quiet news.
+_LIVE_PGH_DAYS = [
+ ("20260725", 122, 92281),
+ ("20260726", 97, 98797),
+ ("20260727", 302, 137794),
+ ("20260728", 402, 193271),
+ ("20260729", 210, 162086),
+ ("20260730", 176, 168455),
+ ("20260731", 233, 149894),
+ ("20260801", 129, 110262),
+ ("20260802", 154, 103171),
+ ("20260803", 288, 147538),
+ ("20260804", 343, 157631),
+ ("20260805", 310, 175970),
+ ("20260806", 364, 159186),
+ ("20260807", 247, 117971),
+ ("20260808", 199, 114555),
+ ("20260809", 178, 103098),
+ ("20260810", 168, 115167),
+ ("20260811", 255, 131138),
+ ("20260812", 297, 140458),
+ ("20260813", 308, 179907),
+ ("20260814", 333, 194350),
+ ("20260815", 185, 108259),
+ ("20260816", 189, 103863),
+ ("20260817", 232, 116203),
+ ("20260818", 390, 169174),
+ ("20260819", 344, 157610),
+ ("20260820", 207, 171970),
+ ("20260821", 573, 160721),
+ ("20260822", 216, 98241),
+ ("20260823", 100, 88414),
+ ("20260824", 237, 117661),
+ ("20260825", 315, 132186),
+ ("20260826", 279, 179831),
+ ("20260827", 333, 172877),
+ ("20260828", 298, 125894),
+ ("20260829", 164, 91911),
+ ("20260830", 130, 79465),
+ ("20260831", 248, 107519),
+ ("20260901", 158, 116481),
+ ("20260902", 174, 105316),
+ ("20260903", 239, 120602),
+ ("20260904", 276, 156481),
+ ("20260905", 151, 102774),
+ ("20260906", 156, 98645),
+ ("20260907", 338, 118079),
+ ("20260908", 124, 77318),
+ ("20260909", 272, 158938),
+ ("20260910", 443, 155062),
+ ("20260911", 512, 154253),
+ ("20260912", 184, 120863),
+ ("20260913", 52, 29203),
+ ("20260920", 172, 105485),
+ ("20260921", 171, 108510),
+ ("20260922", 437, 105779),
+ ("20260923", 309, 149817),
+ ("20260924", 441, 155942),
+ ("20260925", 226, 58811),
+ ("20260927", 207, 77392),
+ ("20260928", 201, 121105),
+ ("20260929", 164, 134919),
+ ("20260930", 233, 111356),
+ ("20261001", 491, 174731),
+ ("20261002", 115, 61712),
+ ("20261006", 1, 3958),
+ ("20261008", 0, 678),
+ ("20261010", 5, 1836),
+ ("20261015", 92, 95273),
+ ("20261016", 163, 150288),
+ ("20261017", 96, 77358),
+]
+_LIVE_CAPTURED_AT = datetime(2026, 10, 17, 16, 57, 53, tzinfo=timezone.utc)
+_LIVE_GDELT_BODY = {
+ "query_details": {"title": _PGH_QUERY, "date_resolution": "day"},
+ "timeline": [
+ {
+ "series": "Article Count",
+ "data": [
+ {"date": f"{day}T000000Z", "value": value, "norm": norm}
+ for day, value, norm in _LIVE_PGH_DAYS
+ ],
+ }
+ ],
+}
+
+# Captured live 2026-10-17T17:06:04Z: the Nominatim reverse lookup
+# geocode.fetch_place_context makes for this AOI's centre (lat 40.44060,
+# lon -79.99590, format jsonv2, zoom 10, addressdetails 1). Trimmed to
+# the fields fetch_place_context reads plus the OSM identity of the match.
+_LIVE_PGH_REVERSE = {
+ "licence": "Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
+ "osm_type": "relation",
+ "osm_id": 188553,
+ "lat": "40.4406968",
+ "lon": "-80.0025666",
+ "category": "boundary",
+ "type": "administrative",
+ "addresstype": "city",
+ "name": "Pittsburgh",
+ "display_name": "Pittsburgh, Allegheny County, Pennsylvania, United States",
+ "address": {
+ "city": "Pittsburgh",
+ "county": "Allegheny County",
+ "state": "Pennsylvania",
+ "ISO3166-2-lvl4": "US-PA",
+ "country": "United States",
+ "country_code": "us",
+ },
+}
+
+
+def _live_edges(monkeypatch: pytest.MonkeyPatch, now: datetime) -> tuple:
+ """Real geocode and GDELT functions behind respx routes serving the
+ captures; the four event domains stubbed with 5 in-fence events from
+ 4 domains in one cell (1 quake, 2 aircraft, 1 protest, 1 fire)."""
+ _install(
+ monkeypatch,
+ now=now,
+ quakes=[_quake(_NEAR)],
+ aircraft=[_aircraft(_NEAR, "a1"), _aircraft(_NEAR, "a2")],
+ acled=[_protest(_NEAR)],
+ fires=[_fire(_NEAR)],
+ )
+ monkeypatch.setattr(geocode, "fetch_place_context", _REAL_FETCH_PLACE_CONTEXT)
+ monkeypatch.setattr(news, "fetch_gdelt_search", _REAL_FETCH_GDELT_SEARCH)
+ nominatim = respx.get(
+ url__regex=r"^https://nominatim\.openstreetmap\.org/reverse"
+ ).mock(return_value=httpx.Response(200, json=_LIVE_PGH_REVERSE))
+ gdelt = respx.get(
+ url__regex=r"^https://api\.gdeltproject\.org/api/v2/doc/doc"
+ ).mock(return_value=httpx.Response(200, json=_LIVE_GDELT_BODY))
+ return nominatim, gdelt
+
+
+async def test_live_capture_outage_week_is_refused_not_read_as_a_surge(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """At capture time GDELT's prior week held 6 matching articles out of
+ 6,472 monitored (3 days with data) and the current week 351 of
+ 322,919. Raw counts would read a 58x surge; the escalation refuses the
+ comparison and leaves news out of the score."""
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ nominatim, gdelt = _live_edges(monkeypatch, _LIVE_CAPTURED_AT)
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ reverse = nominatim.calls.last.request.url.params
+ assert (reverse["lat"], reverse["lon"]) == ("40.44060", "-79.99590")
+ sent = gdelt.calls.last.request.url.params
+ assert sent["query"] == _PGH_QUERY
+ assert sent["mode"] == "timelinevolraw"
+ assert gdelt.call_count == 1
+
+ signal = result["news_signal"]
+ assert signal["current_window"]["articles"] == 351 # 92 + 163 + 96
+ assert signal["current_window"]["monitored_articles"] == 322919
+ assert signal["current_window"]["steps_with_data"] == 3 # Oct 15-17
+ assert signal["prior_window"]["articles"] == 6 # 1 + 0 + 5
+ assert signal["prior_window"]["monitored_articles"] == 6472
+ assert signal["prior_window"]["steps_with_data"] == 3 # Oct 6, 8, 10
+ assert result["components"]["news"] is None
+ assert result["data_gaps"] == [
+ "News: GDELT intake too uneven to compare: it monitored 6,472 "
+ "articles in the prior 7 days (3 of 7 steps with data) and 322,919 in "
+ "the latest 7 (3 of 7), so a comparison would measure GDELT's "
+ "ingestion gaps, not the news."
+ ]
+ # military 2.0 + unrest 0.4 + convergence 8.0 = 10.4 of the 80 points
+ # measured: 10.4 / 80 x 100 = 13.0.
+ assert result["score"] == 13.0
+ assert result["computed_from"] == [c for c in _SIX if c != "news"]
+
+
+async def test_live_capture_full_weeks_score_the_share_change(
+ fetcher, store: AOIStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The same capture read as of 2026-09-12 12:00 UTC, when both weeks
+ are complete. Current Sep 6-12: 2,029 matches of 883,158 monitored;
+ prior Aug 30-Sep 5: 1,376 of 788,638. expected = 1376/788638 x 883158
+ = 1540.92; change = 100 x (2029 - 1540.92) / 1540.92 = +31.67%."""
+ aoi.define_aoi(store, "Pittsburgh", _PGH_LAT, _PGH_LON, _PGH_RADIUS_KM)
+ _live_edges(monkeypatch, datetime(2026, 9, 12, 12, tzinfo=timezone.utc))
+
+ result = await aoi.fetch_aoi_escalation(fetcher, store, "Pittsburgh")
+
+ signal = result["news_signal"]
+ assert signal["current_window"]["start"] == "2026-09-06T00:00:00Z"
+ assert signal["current_window"]["articles"] == 2029
+ assert signal["current_window"]["monitored_articles"] == 883158
+ assert signal["prior_window"]["start"] == "2026-08-30T00:00:00Z"
+ assert signal["prior_window"]["articles"] == 1376
+ assert signal["prior_window"]["monitored_articles"] == 788638
+ assert signal["expected_articles"] == 1540.9
+ assert signal["change_pct"] == 31.7
+ assert signal["prior_window"]["share_per_10k"] == 17.45
+ assert signal["current_window"]["share_per_10k"] == 22.97
+ # news = min(20, 0.2 x 31.7) = 6.34 -> 6.3
+ assert result["components"]["news"] == 6.3
+ # military 2.0 + unrest 0.4 + news 6.34 + convergence 8.0 = 16.74 of 100.
+ assert result["score"] == 16.7
+ assert result["computed_from"] == _SIX
+ assert result["data_gaps"] == []
diff --git a/src/world_intel_mcp/tools/aoi.py b/src/world_intel_mcp/tools/aoi.py
index 7cb4f38..ddd55d8 100644
--- a/src/world_intel_mcp/tools/aoi.py
+++ b/src/world_intel_mcp/tools/aoi.py
@@ -77,7 +77,7 @@ TOOLS: list[Tool] = [
),
Tool(
name="intel_aoi_escalation",
- description="Run the hotspot escalation scoring (baseline, military, conflict, social-unrest components; 0-100) on a user-defined AOI instead of only the 22 built-in intel hotspots. News-mention and geo-convergence components are not wired up and report null, same as intel_hotspot_escalation. Required: name (must already be defined via intel_aoi_define).",
+ description="Run the hotspot escalation scoring (baseline, news, military, conflict, social-unrest and convergence components; 0-100) on a user-defined AOI instead of only the 22 built-in intel hotspots. News: the rise in the area's share of GDELT coverage, the last 7 days against the 7 before, for the reverse-geocoded place (news_signal shows the counts). Convergence: multi-domain convergence of the earthquakes, military flights, ACLED events and wildfires inside the AOI's exact shape (circle, polygon or corridor; convergence_signal shows the cells). If the news or convergence inputs fail, that component is null and explained in data_gaps, never a 0; computed_from lists the components the score was computed from, and zero_filled_components any of those that are a 0 only because the military or ACLED fetch failed. Required: name (must already be defined via intel_aoi_define).",
inputSchema={
"type": "object",
"properties": {