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.
Python ai-toolsai-watchanthropicclaudecybersecuritydashboardgeofencinggeopoliticalgeospatialintelligencemarketsmcpmigrationmilitarymodel-context-protocolnuclearosintreal-timespace-weatherthreat-intelligence
"""Country intelligence, risk scoring, signal convergence, and analysis sources.
Provides higher-level analytical functions that combine data from multiple
APIs (ACLED, World Bank, USGS, Ollama, Cloudflare, OpenSky, NASA) into
country briefs, risk scores, instability indices, geographic signal
convergence, focal point detection, signal summaries, temporal anomalies,
hotspot escalation, military surge, vessel tracking, and cascade analysis.
"""
import asyncio
import logging
import math
import os
import re
from datetime import datetime, timezone, timedelta
import httpx
from ..fetcher import Fetcher
from .conflict import acled_query, acled_failure_message, acled_failure_reason
from ..analysis.focal_points import detect_focal_points
from ..analysis.signals import aggregate_country_signals
from ..analysis.temporal import TemporalBaseline
from ..analysis.instability import (
compute_cii,
score_unrest,
score_conflict_v2,
score_security,
score_information,
)
from ..analysis.escalation import score_all_hotspots
from ..analysis.surge import detect_surges, SENSITIVE_REGIONS
from ..analysis.cascade import simulate_cascade
from ..config.countries import (
TIER1_COUNTRIES,
INTEL_HOTSPOTS,
STRATEGIC_WATERWAYS,
get_event_multiplier,
match_country_by_name,
)
logger = logging.getLogger("world-intel-mcp.sources.intelligence")
# Shared temporal baseline instance
_temporal = TemporalBaseline()
# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------
_WB_BASE = "https://api.worldbank.org/v2/country"
_USGS_ENDPOINT = "https://earthquake.usgs.gov/fdsnws/event/1/query"
_BASELINES = {
"Syria": 5000,
"Yemen": 3000,
"Ukraine": 8000,
"Myanmar": 4000,
"Somalia": 2500,
"Nigeria": 3500,
"DR Congo": 3000,
"Afghanistan": 2000,
"Iraq": 1500,
"Mali": 2000,
"Burkina Faso": 2500,
"Ethiopia": 2000,
"Sudan": 3000,
"South Sudan": 1500,
"Cameroon": 1000,
"Mozambique": 800,
"Pakistan": 1200,
"India": 1000,
"Colombia": 1500,
"Mexico": 4000,
}
_FOCUS_COUNTRIES = [
"SYR",
"UKR",
"YEM",
"MMR",
"SDN",
"ETH",
"NGA",
"COD",
"AFG",
"IRQ",
]
_HOTSPOTS = {
"middle_east": (33.0, 44.0),
"east_africa": (5.0, 38.0),
"south_asia": (30.0, 70.0),
"eastern_europe": (48.0, 35.0),
"sahel": (15.0, 2.0),
}
# ISO-3166 alpha-3 to country name for ACLED queries and display.
_ISO3_TO_NAME = {
"SYR": "Syria",
"UKR": "Ukraine",
"YEM": "Yemen",
"MMR": "Myanmar",
"SDN": "Sudan",
"ETH": "Ethiopia",
"NGA": "Nigeria",
"COD": "DR Congo",
"AFG": "Afghanistan",
"IRQ": "Iraq",
}
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _risk_level(score: float) -> str:
if score > 150:
return "critical"
if score > 100:
return "elevated"
if score > 50:
return "moderate"
return "low"
# ---------------------------------------------------------------------------
# Function 1: Country Intelligence Brief
# ---------------------------------------------------------------------------
async def fetch_country_brief(
fetcher: Fetcher,
country_code: str = "US",
) -> dict:
"""Generate a country intelligence brief using local LLM and public data.
Gathers economic indicators from World Bank and conflict data from ACLED
in parallel, then optionally enriches with an Ollama-generated analytical
brief. Falls back to a data-only summary when Ollama is unavailable.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
country_code: ISO 3166-1 alpha-2 country code (e.g. ``US``, ``UA``).
Returns:
Dict with brief text, supporting data, LLM availability flag,
source, and timestamp.
"""
now = datetime.now(timezone.utc)
# --- Gather background data in parallel --------------------------------
async def _fetch_gdp() -> list:
url = f"{_WB_BASE}/{country_code}/indicator/NY.GDP.MKTP.CD"
params = {
"format": "json",
"per_page": 5,
"date": "2020:2025",
}
data = await fetcher.get_json(
url,
source="world-bank",
cache_key=f"intel:wb:gdp:{country_code}",
cache_ttl=86400,
params=params,
)
if data is None:
return []
values = []
try:
if isinstance(data, list) and len(data) >= 2 and isinstance(data[1], list):
for rec in data[1]:
year = rec.get("date")
value = rec.get("value")
if year is not None and value is not None:
try:
values.append({"year": year, "value": float(value)})
except (ValueError, TypeError):
pass
except (KeyError, TypeError, IndexError) as exc:
logger.warning(
"Failed to parse World Bank GDP for %s: %s", country_code, exc
)
return values
async def _fetch_inflation() -> list:
url = f"{_WB_BASE}/{country_code}/indicator/FP.CPI.TOTL.ZG"
params = {
"format": "json",
"per_page": 5,
"date": "2020:2025",
}
data = await fetcher.get_json(
url,
source="world-bank",
cache_key=f"intel:wb:inflation:{country_code}",
cache_ttl=86400,
params=params,
)
if data is None:
return []
values = []
try:
if isinstance(data, list) and len(data) >= 2 and isinstance(data[1], list):
for rec in data[1]:
year = rec.get("date")
value = rec.get("value")
if year is not None and value is not None:
try:
values.append({"year": year, "value": float(value)})
except (ValueError, TypeError):
pass
except (KeyError, TypeError, IndexError) as exc:
logger.warning(
"Failed to parse World Bank inflation for %s: %s", country_code, exc
)
return values
async def _fetch_acled_count() -> tuple[int, str | None]:
start_date = (now - timedelta(days=30)).strftime("%Y-%m-%d")
end_date = now.strftime("%Y-%m-%d")
data = await acled_query(
fetcher,
params={
"limit": 0,
"event_date": f"{start_date}|{end_date}",
"event_date_where": "BETWEEN",
"country": country_code,
},
cache_key=f"intel:acled:count:{country_code}",
cache_ttl=900,
)
if data is None:
# 0 here is ambiguous between "queried, genuinely zero events"
# and "the fetch failed" — surface the reason via data_gaps
# below instead of letting the caller assume peace.
return 0, await acled_failure_reason(data)
# ACLED returns a count field when limit=0
try:
return int(data.get("count", len(data.get("data", [])))), None
except (ValueError, TypeError):
return len(data.get("data", [])), None
gdp_values, inflation_values, (event_count, acled_gap) = await asyncio.gather(
_fetch_gdp(),
_fetch_inflation(),
_fetch_acled_count(),
)
# --- Attempt Ollama-generated brief ------------------------------------
llm_available = False
brief_text = "LLM brief unavailable. Data summary below."
prompt = (
f"Provide a concise 3-paragraph intelligence brief for {country_code}. "
"Cover: (1) current political stability and governance, "
"(2) economic outlook and risks, "
"(3) security concerns and regional dynamics. "
"Be factual and analytical."
)
ollama_url = os.environ.get("OLLAMA_API_URL", "http://localhost:11434")
model = os.environ.get("OLLAMA_MODEL", "llama3.2:latest")
try:
async with httpx.AsyncClient(timeout=30.0, proxy=None) as client:
resp = await client.post(
f"{ollama_url}/api/generate",
json={
"model": model,
"prompt": prompt,
"stream": False,
},
)
resp.raise_for_status()
resp_data = resp.json()
generated = resp_data.get("response", "")
if generated and generated.strip():
brief_text = generated.strip()
llm_available = True
except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPStatusError) as exc:
logger.info("Ollama unavailable for country brief (%s): %s", country_code, exc)
except Exception as exc:
logger.warning("Unexpected error calling Ollama: %s", exc)
return {
"country_code": country_code,
"brief": brief_text,
"data": {
"gdp": gdp_values,
"inflation": inflation_values,
"recent_events": event_count,
},
"llm_available": llm_available,
"data_gaps": [acled_gap] if acled_gap else [],
"source": "country-intelligence",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# ---------------------------------------------------------------------------
# Function 2: Country Risk Scores
# ---------------------------------------------------------------------------
async def fetch_risk_scores(
fetcher: Fetcher,
limit: int = 20,
) -> dict:
"""Compute country risk scores from ACLED conflict data and baselines.
Fetches recent global conflict events, counts per country, and computes
a risk score as ``(events_30d / monthly_baseline) * 100``. Higher
scores indicate conflict above historical norms.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
limit: Maximum number of countries to return (sorted by risk).
Returns:
Dict with ranked country list, count, source, and timestamp.
"""
now = datetime.now(timezone.utc)
start_date = (now - timedelta(days=30)).strftime("%Y-%m-%d")
end_date = now.strftime("%Y-%m-%d")
data = await acled_query(
fetcher,
params={
"limit": 500,
"event_date": f"{start_date}|{end_date}",
"event_date_where": "BETWEEN",
},
cache_key="intel:risk:global:30d",
cache_ttl=1800,
)
if data is None:
reason = await acled_failure_reason(data)
if reason == "acled_unconfigured":
return {
"error": "ACLED credentials not configured (ACLED_EMAIL + ACLED_PASSWORD)",
"note": "Free academic access at acleddata.com",
"source": "risk-analysis",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# Credentials are set; sign-in or the live fetch failed. Previously this
# branch was unreachable in practice for a configured deployment
# under outage — it fell through to the same "not configured"
# message, misdiagnosing a transient failure as a config error.
return {
"error": acled_failure_message(reason),
"degraded": True,
"source": "risk-analysis",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# Count events per country
country_counts: dict[str, int] = {}
for event in data.get("data", []):
country_name = event.get("country")
if country_name:
country_counts[country_name] = country_counts.get(country_name, 0) + 1
# Compute risk scores
countries: list[dict] = []
for country_name, events_30d in country_counts.items():
baseline_annual = _BASELINES.get(country_name, 500)
monthly_baseline = baseline_annual / 12.0
risk_score = (
(events_30d / monthly_baseline) * 100 if monthly_baseline > 0 else 0.0
)
countries.append(
{
"country": country_name,
"events_30d": events_30d,
"monthly_baseline": round(monthly_baseline, 1),
"risk_score": round(risk_score, 1),
"risk_level": _risk_level(risk_score),
}
)
# Sort by risk_score descending, take top N
countries.sort(key=lambda c: c["risk_score"], reverse=True)
countries = countries[:limit]
return {
"countries": countries,
"count": len(countries),
"source": "risk-analysis",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# ---------------------------------------------------------------------------
# Function 3: Country Instability Index
# ---------------------------------------------------------------------------
async def fetch_instability_index(
fetcher: Fetcher,
country_code: str | None = None,
) -> dict:
"""Compute a Country Instability Index (CII) from multiple signals.
Combines conflict intensity, economic stress, humanitarian crisis data,
internet disruption indicators, and military activity into a 0-100
composite score. Higher values indicate greater instability.
When *country_code* is ``None``, returns a simplified index for 10
focus countries using ACLED data as the primary signal.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
country_code: Optional ISO 3166-1 alpha-3 code (e.g. ``UKR``).
Returns:
Dict with instability index, component scores, risk level, source,
and timestamp.
"""
now = datetime.now(timezone.utc)
if country_code is not None:
code = country_code.strip().upper()
names = _instability_country_names()
if code not in names:
# A code the index cannot name would be sent upstream as-is and
# score from inputs that never matched the place.
return {
"error": (
f"Unknown or unsupported country code {country_code!r}: the "
"instability index takes one of the ISO alpha-3 codes it can "
"name, listed in accepted_codes"
),
"accepted_codes": sorted(names),
"source": "instability-index-v2",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
return await _instability_single(fetcher, code, now)
return await _instability_multi(fetcher, now)
# ACLED spells this one differently from the sanctions-list form the
# dossier's name table uses.
_ACLED_NAME_OVERRIDES = {"KOR": "South Korea"}
def _instability_country_names() -> dict[str, str]:
"""ISO alpha-3 code -> English name for every country the single-country
index can query: its own table, the tier-1 countries and the dossier's
table."""
from ..analysis.dossier import _EXTRA_COUNTRY_NAMES
names = dict(_EXTRA_COUNTRY_NAMES)
names.update({code: cfg["name"] for code, cfg in TIER1_COUNTRIES.items() if cfg.get("name")})
names.update(_ISO3_TO_NAME)
names.update(_ACLED_NAME_OVERRIDES)
return names
async def _instability_single(
fetcher: Fetcher,
country_code: str,
now: datetime,
) -> dict:
"""Compute CII v2 instability index for a single country.
Uses 4 weighted domains: unrest, conflict, security, information.
Applies country-specific event multiplier and UCDP/displacement boosts.
Every input that could not be obtained is named in ``data_gaps``, and a
component with no measured input is null rather than 0. The total then
treats it as 0, so it is a lower bound (``index_is_lower_bound``); with
no component measured the index is null and the risk level "unknown".
"""
country_name = _instability_country_names()[country_code]
event_multiplier = get_event_multiplier(country_code)
start_date = (now - timedelta(days=30)).strftime("%Y-%m-%d")
end_date = now.strftime("%Y-%m-%d")
# --- Parallel data gathering -------------------------------------------
async def _fetch_acled() -> tuple[list[dict], str | None]:
"""Fetch ACLED events for this country."""
data = await acled_query(
fetcher,
params={
"limit": 500,
"event_date": f"{start_date}|{end_date}",
"event_date_where": "BETWEEN",
"country": country_name,
},
cache_key=f"intel:cii2:acled:{country_code}",
cache_ttl=1800,
)
if data is None:
return [], await acled_failure_reason(data)
events = data.get("data", []) if isinstance(data, dict) else []
return events, None
async def _fetch_outages() -> tuple[int, str | None]:
"""Count internet outages mentioning this country."""
from . import infrastructure
result = await infrastructure.fetch_internet_outages(fetcher)
if result.get("error"):
return 0, f"internet outages: {result['error']}"
count = 0
for outage in result.get("outages", []):
countries_list = outage.get("countries", [])
if isinstance(countries_list, list):
for c in countries_list:
if isinstance(c, str) and country_code.lower() in c.lower():
count += 1
return count, None
async def _fetch_military() -> tuple[int, str | None]:
"""Count military aircraft near this country."""
_COUNTRY_BBOX = {
"SYR": "32,35,37,42",
"UKR": "44,22,52,40",
"YEM": "12,42,19,55",
"MMR": "10,92,28,101",
"SDN": "8,21,23,39",
"ETH": "3,33,15,48",
"NGA": "4,3,14,15",
"COD": "-13,12,5,31",
"AFG": "29,60,38,75",
"IRQ": "29,39,37,49",
"IRN": "25,44,40,63",
"ISR": "29,34,33,36",
"PSE": "31,34,32,35",
"LBN": "33,35,34,37",
"TWN": "21,119,26,122",
"PRK": "37,124,43,131",
}
bbox = _COUNTRY_BBOX.get(country_code)
if bbox is None:
return 0, (
f"military aircraft: no bounding box for {country_code} (the index "
f"has {len(_COUNTRY_BBOX)}), not measured"
)
from . import military as mil_mod
result = await mil_mod.fetch_military_flights(fetcher, bbox=bbox)
if result.get("error"):
return 0, f"military aircraft: {result['error']}"
return result.get("count", 0), None
async def _fetch_news_velocity() -> tuple[int, str | None]:
"""Estimate news velocity from GDELT."""
from . import news
result = await news.fetch_gdelt_search(
fetcher,
query=country_name,
mode="artlist",
limit=100,
)
if result.get("error"):
return 0, f"news velocity (GDELT): {result['error']}"
return result.get("count", 0), None
(
(acled_events, acled_gap),
(outage_count, outage_gap),
(mil_count, mil_gap),
(news_vel, news_gap),
) = await asyncio.gather(
_fetch_acled(),
_fetch_outages(),
_fetch_military(),
_fetch_news_velocity(),
)
# Classify ACLED events into protests/riots vs armed conflict
protest_count = 0
riot_count = 0
conflict_count = 0
total_fatalities = 0
for ev in acled_events:
event_type = (ev.get("event_type") or "").lower()
fat = 0
try:
fat = int(ev.get("fatalities", 0))
except (ValueError, TypeError):
pass
total_fatalities += fat
if "protest" in event_type:
protest_count += 1
elif "riot" in event_type:
riot_count += 1
else:
conflict_count += 1
# Score each domain (0-25)
unrest_val = score_unrest(protest_count, riot_count)
conflict_val = score_conflict_v2(conflict_count, total_fatalities)
security_val = score_security(mil_count, outage_count)
info_val = score_information(news_vel)
# UCDP floor: active wars get a minimum score
ucdp_floor = None
country_cfg = TIER1_COUNTRIES.get(country_code)
if country_cfg and country_cfg.get("baseline_risk", 0) >= 80:
ucdp_floor = 70.0
elif country_cfg and country_cfg.get("baseline_risk", 0) >= 60:
ucdp_floor = 50.0
# Displacement boost
displacement_boost = 0.0
# (Would require UNHCR fetch; simplified: use baseline_risk as proxy)
if country_cfg and country_cfg.get("baseline_risk", 0) >= 70:
displacement_boost = 3.0
cii = compute_cii(
unrest=unrest_val,
conflict=conflict_val,
security=security_val,
information=info_val,
event_multiplier=event_multiplier,
ucdp_floor=ucdp_floor,
displacement_boost=displacement_boost,
)
# A component with no measured input is unknown, not 0.
unmeasured = []
if acled_gap:
unmeasured += ["unrest", "conflict"]
if mil_gap and outage_gap:
unmeasured.append("security")
if news_gap:
unmeasured.append("information")
for name in unmeasured:
cii["components"][name] = None
if unmeasured or mil_gap or outage_gap:
cii["index_is_lower_bound"] = True
if len(unmeasured) == len(cii["components"]):
cii["instability_index"] = None
cii["risk_level"] = "unknown"
if ucdp_floor is not None:
cii["ucdp_floor_basis"] = (
"static baseline_risk from the country table, not current UCDP data"
)
data_gaps = [g for g in (acled_gap, mil_gap, outage_gap, news_gap) if g]
return {
"country_code": country_code,
"country_name": country_name,
**cii,
"raw_data": {
"acled_events": len(acled_events),
"protests": protest_count,
"riots": riot_count,
"conflict_events": conflict_count,
"fatalities": total_fatalities,
"military_aircraft": mil_count,
"internet_outages": outage_count,
"news_articles": news_vel,
},
"data_gaps": data_gaps,
"source": "instability-index-v2",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
async def _instability_multi(fetcher: Fetcher, now: datetime) -> dict:
"""Compute CII v2 instability index for focus countries using ACLED."""
start_date = (now - timedelta(days=30)).strftime("%Y-%m-%d")
end_date = now.strftime("%Y-%m-%d")
# Fetch global events and bucket by country
data = await acled_query(
fetcher,
params={
"limit": 500,
"event_date": f"{start_date}|{end_date}",
"event_date_where": "BETWEEN",
},
cache_key="intel:cii2:multi:global:30d",
cache_ttl=1800,
)
if data is None:
reason = await acled_failure_reason(data)
if reason == "acled_unconfigured":
return {
"error": "ACLED credentials not configured (ACLED_EMAIL + ACLED_PASSWORD)",
"source": "instability-index-v2",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
return {
"error": acled_failure_message(reason),
"degraded": True,
"source": "instability-index-v2",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# Classify events by country and type
country_data: dict[str, dict] = {}
if data is not None:
events_list = data.get("data", []) if isinstance(data, dict) else []
for event in events_list:
country_name = event.get("country")
if not country_name:
continue
if country_name not in country_data:
country_data[country_name] = {
"protests": 0,
"riots": 0,
"conflict": 0,
"fatalities": 0,
"total": 0,
}
cd = country_data[country_name]
cd["total"] += 1
event_type = (event.get("event_type") or "").lower()
fat = 0
try:
fat = int(event.get("fatalities", 0))
except (ValueError, TypeError):
pass
cd["fatalities"] += fat
if "protest" in event_type:
cd["protests"] += 1
elif "riot" in event_type:
cd["riots"] += 1
else:
cd["conflict"] += 1
# Compute CII v2 for each focus country
results: list[dict] = []
for code in _FOCUS_COUNTRIES:
name = _ISO3_TO_NAME.get(code, code)
cd = country_data.get(
name,
{
"protests": 0,
"riots": 0,
"conflict": 0,
"fatalities": 0,
"total": 0,
},
)
multiplier = get_event_multiplier(code)
unrest_val = score_unrest(cd["protests"], cd["riots"])
conflict_val = score_conflict_v2(cd["conflict"], cd["fatalities"])
# Security and information not available in multi-country mode
security_val = 0.0
info_val = 0.0
# UCDP floor from countries config
country_cfg = TIER1_COUNTRIES.get(code)
ucdp_floor = None
if country_cfg and country_cfg.get("baseline_risk", 0) >= 80:
ucdp_floor = 70.0
elif country_cfg and country_cfg.get("baseline_risk", 0) >= 60:
ucdp_floor = 50.0
cii = compute_cii(
unrest=unrest_val,
conflict=conflict_val,
security=security_val,
information=info_val,
event_multiplier=multiplier,
ucdp_floor=ucdp_floor,
)
results.append(
{
"country_code": code,
"country_name": name,
**cii,
"events_30d": cd["total"],
}
)
results.sort(key=lambda r: r["instability_index"], reverse=True)
return {
"countries": results,
"count": len(results),
"note": "Multi-country CII v2 using ACLED unrest + conflict. "
"Use country_code for full 4-domain analysis.",
"source": "instability-index-v2",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# ---------------------------------------------------------------------------
# Function 4: Signal Convergence
# ---------------------------------------------------------------------------
async def fetch_signal_convergence(
fetcher: Fetcher,
lat: float | None = None,
lon: float | None = None,
radius_deg: float = 5.0,
) -> dict:
"""Detect geographic convergence of signals in hotspot regions.
Checks for overlapping seismic activity and other observable signals
within a radius of known or specified hotspot coordinates. Higher
convergence scores indicate multiple signal types in close proximity,
which may warrant deeper investigation.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
lat: Latitude of center point. If ``None``, scans 5 global
hotspot regions.
lon: Longitude of center point.
radius_deg: Radius in degrees for bounding box queries.
Returns:
Dict with hotspot list, convergence scores, source, and timestamp.
"""
now = datetime.now(timezone.utc)
if lat is not None and lon is not None:
regions = {"custom": (lat, lon)}
else:
regions = dict(_HOTSPOTS)
async def _assess_hotspot(name: str, center: tuple[float, float]) -> dict:
center_lat, center_lon = center
# Earthquake count within bounding box
min_lat = center_lat - radius_deg
max_lat = center_lat + radius_deg
min_lon = center_lon - radius_deg
max_lon = center_lon + radius_deg
starttime = (now - timedelta(days=30)).strftime("%Y-%m-%dT%H:%M:%S")
quake_data = await fetcher.get_json(
_USGS_ENDPOINT,
source="usgs",
cache_key=f"intel:convergence:usgs:{name}:{radius_deg}",
cache_ttl=600,
params={
"format": "geojson",
"minmagnitude": 2.5,
"starttime": starttime,
"minlatitude": min_lat,
"maxlatitude": max_lat,
"minlongitude": min_lon,
"maxlongitude": max_lon,
"limit": 100,
},
)
earthquake_count = 0
if quake_data is not None:
earthquake_count = len(quake_data.get("features", []))
# Convergence score heuristic (0-10)
# Each signal type present adds to the score.
score = 0.0
# Earthquakes: 0-5 points based on count
if earthquake_count > 0:
score += min(5.0, (earthquake_count / 20.0) * 5.0)
# Hotspot presence bonus (known conflict zones get a baseline)
if name in _HOTSPOTS:
score += 2.0
score = min(10.0, round(score, 1))
return {
"name": name,
"lat": center_lat,
"lon": center_lon,
"signals": {
"earthquakes": earthquake_count,
},
"convergence_score": score,
}
tasks = [_assess_hotspot(name, center) for name, center in regions.items()]
results = await asyncio.gather(*tasks)
# Sort by convergence score descending
hotspots = sorted(results, key=lambda h: h["convergence_score"], reverse=True)
return {
"hotspots": hotspots,
"source": "signal-convergence",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# ---------------------------------------------------------------------------
# Function 5: Focal Point Detection
# ---------------------------------------------------------------------------
async def fetch_focal_points(fetcher: Fetcher) -> dict:
"""Gather multi-source events and detect focal points.
Fetches news headlines, military flights, internet outages, and ACLED
protests in parallel, normalizes them into events, and runs focal point
detection to find entities where multiple signals converge.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
Returns:
Dict with focal_points list, count, source, and timestamp.
"""
now = datetime.now(timezone.utc)
# Import source modules for parallel data gathering
from . import news, military, infrastructure
async def _fetch_news_events() -> list[dict]:
result = await news.fetch_news_feed(fetcher, limit=100)
events = []
for item in result.get("items", []):
title = item.get("title", "")
# Extract entity: try to match country names from title
matched_iso = match_country_by_name(title)
if matched_iso:
country_cfg = TIER1_COUNTRIES.get(matched_iso)
entity = country_cfg["name"] if country_cfg else matched_iso
events.append(
{
"entity": entity,
"type": "news",
"timestamp": item.get("published")
or now.strftime("%Y-%m-%dT%H:%M:%SZ"),
"country": entity,
"weight": 1.0,
}
)
return events
async def _fetch_military_events() -> list[dict]:
result = await military.fetch_theater_posture(fetcher)
events = []
for theater_name, theater_data in result.get("theaters", {}).items():
count = theater_data.get("count", 0)
if count > 0:
for country in theater_data.get("countries", []):
events.append(
{
"entity": country,
"type": "military",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
"country": country,
"weight": min(3.0, count / 10.0),
}
)
return events
async def _fetch_outage_events() -> list[dict]:
result = await infrastructure.fetch_internet_outages(fetcher)
events = []
for outage in result.get("outages", []):
countries_list = outage.get("countries", [])
if isinstance(countries_list, list):
for c in countries_list:
if c:
events.append(
{
"entity": c,
"type": "infrastructure",
"timestamp": outage.get("start")
or now.strftime("%Y-%m-%dT%H:%M:%SZ"),
"country": c,
"weight": 2.0 if outage.get("is_ongoing") else 1.0,
}
)
return events
async def _fetch_protest_events() -> tuple[list[dict], str | None]:
start_date = (now - timedelta(days=7)).strftime("%Y-%m-%d")
end_date = now.strftime("%Y-%m-%d")
data = await acled_query(
fetcher,
params={
"limit": 200,
"event_date": f"{start_date}|{end_date}",
"event_date_where": "BETWEEN",
"event_type": "Protests",
},
cache_key="intel:focal:acled:protests:7d",
cache_ttl=1800,
)
events = []
if data is not None:
acled_list = data.get("data", []) if isinstance(data, dict) else []
for ev in acled_list:
country = ev.get("country")
if country:
events.append(
{
"entity": country,
"type": "protest",
"timestamp": ev.get("event_date")
or now.strftime("%Y-%m-%dT%H:%M:%SZ"),
"country": country,
"weight": 1.0,
}
)
return events, None
return events, await acled_failure_reason(data)
(
news_events,
mil_events,
outage_events,
(protest_events, acled_gap),
) = await asyncio.gather(
_fetch_news_events(),
_fetch_military_events(),
_fetch_outage_events(),
_fetch_protest_events(),
)
all_events = news_events + mil_events + outage_events + protest_events
focal_points = detect_focal_points(all_events)
return {
"focal_points": focal_points,
"count": len(focal_points),
"total_events_analyzed": len(all_events),
"data_gaps": [acled_gap] if acled_gap else [],
"source": "focal-point-analysis",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# ---------------------------------------------------------------------------
# Function 6: Signal Summary
# ---------------------------------------------------------------------------
async def fetch_signal_summary(
fetcher: Fetcher,
country: str | None = None,
) -> dict:
"""Run signal aggregator v2 across all domains.
Fetches ACLED conflict, USGS earthquakes, NASA FIRMS wildfires,
Cloudflare outages, military flights, and UNHCR displacement in parallel,
then aggregates signals by country with convergence scoring.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
country: Optional country name to filter results.
Returns:
Dict with countries list, count, source, and timestamp.
"""
now = datetime.now(timezone.utc)
from . import conflict, infrastructure, military, displacement
async def _fetch_conflict() -> tuple[list[dict], str | None]:
result = await conflict.fetch_acled_events(fetcher, days=7, limit=200)
return result.get("events", []), result.get("reason")
async def _fetch_earthquakes() -> list[dict]:
from . import seismology
result = await seismology.fetch_earthquakes(
fetcher, min_magnitude=4.5, hours=168, limit=100
)
return result.get("earthquakes", [])
async def _fetch_outages() -> list[dict]:
result = await infrastructure.fetch_internet_outages(fetcher)
return result.get("outages", [])
async def _fetch_military() -> list[dict]:
result = await military.fetch_theater_posture(fetcher)
aircraft = []
for theater_data in result.get("theaters", {}).values():
# Theater posture returns summary, not individual aircraft
for c in theater_data.get("countries", []):
aircraft.append(
{
"origin_country": c,
"count": theater_data.get("count", 0),
}
)
return aircraft
async def _fetch_protests() -> tuple[list[dict], str | None]:
start_date = (now - timedelta(days=7)).strftime("%Y-%m-%d")
end_date = now.strftime("%Y-%m-%d")
data = await acled_query(
fetcher,
params={
"limit": 200,
"event_date": f"{start_date}|{end_date}",
"event_date_where": "BETWEEN",
"event_type": "Protests",
},
cache_key="intel:signals:acled:protests:7d",
cache_ttl=1800,
)
if data is None:
return [], await acled_failure_reason(data)
acled_list = data.get("data", []) if isinstance(data, dict) else []
return [
{"country": ev.get("country"), "event_type": ev.get("event_type")}
for ev in acled_list
if ev.get("country")
], None
async def _fetch_displacement() -> list[dict]:
result = await displacement.fetch_displacement_summary(fetcher)
return result.get("by_origin", [])
(
(conflict_events, conflict_gap),
earthquake_data,
outage_data,
military_data,
(protest_data, protest_gap),
displacement_data,
) = await asyncio.gather(
_fetch_conflict(),
_fetch_earthquakes(),
_fetch_outages(),
_fetch_military(),
_fetch_protests(),
_fetch_displacement(),
)
aggregated = aggregate_country_signals(
conflict_events=conflict_events,
displacement_data=displacement_data,
earthquake_data=earthquake_data,
outage_data=outage_data,
military_data=military_data,
protest_data=protest_data,
)
# Filter to specific country if requested
if country:
filtered = {}
lower_country = country.lower()
for c_name, c_data in aggregated.items():
if lower_country in c_name.lower():
filtered[c_name] = c_data
aggregated = filtered
# Convert to list format
countries_list = [{"country": name, **data} for name, data in aggregated.items()]
data_gaps = sorted({g for g in (conflict_gap, protest_gap) if g})
return {
"countries": countries_list[:50],
"count": len(countries_list),
"data_gaps": data_gaps,
"source": "signal-aggregation-v2",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# ---------------------------------------------------------------------------
# Function 7: Temporal Anomaly Detection
# ---------------------------------------------------------------------------
async def fetch_temporal_anomalies(fetcher: Fetcher) -> dict:
"""Record observations and check for temporal anomalies.
Fetches current counts of military flights (by theater), ACLED events
(by country), and fires (by region), records each as a temporal
observation, and reports any that deviate significantly from baselines.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
Returns:
Dict with anomalies list, observations_recorded count, source,
and timestamp.
"""
now = datetime.now(timezone.utc)
from . import military
anomalies: list[dict] = []
observations_recorded = 0
# Military flights by theater
posture = await military.fetch_theater_posture(fetcher)
for theater_name, theater_data in posture.get("theaters", {}).items():
count = theater_data.get("count", 0)
result = _temporal.record_and_check("military_flights", theater_name, count)
observations_recorded += 1
if result is not None:
anomalies.append(result)
# ACLED events by country (top focus countries)
start_date = (now - timedelta(days=7)).strftime("%Y-%m-%d")
end_date = now.strftime("%Y-%m-%d")
data = await acled_query(
fetcher,
params={
"limit": 500,
"event_date": f"{start_date}|{end_date}",
"event_date_where": "BETWEEN",
},
cache_key="intel:temporal:acled:global:7d",
cache_ttl=1800,
)
acled_gap = None
if data is not None:
country_counts: dict[str, int] = {}
events_list = data.get("data", []) if isinstance(data, dict) else []
for event in events_list:
c = event.get("country")
if c:
country_counts[c] = country_counts.get(c, 0) + 1
for c_name, c_count in country_counts.items():
result = _temporal.record_and_check("acled_events", c_name, c_count)
observations_recorded += 1
if result is not None:
anomalies.append(result)
else:
# No ACLED observations were recorded this cycle — silently
# skipping (the prior behavior) makes a live outage indistinguishable
# from "nothing happened," which understates the anomaly count.
acled_gap = await acled_failure_reason(data)
# Sort anomalies by z_score descending
anomalies.sort(key=lambda a: a.get("z_score", 0), reverse=True)
return {
"anomalies": anomalies,
"anomaly_count": len(anomalies),
"observations_recorded": observations_recorded,
"data_gaps": [acled_gap] if acled_gap else [],
"source": "temporal-anomaly-detection",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# ---------------------------------------------------------------------------
# Function 8: Social Unrest Events (Protests + Riots)
# ---------------------------------------------------------------------------
def _haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
"""Great-circle distance between two points in km."""
R = 6371.0
dlat = math.radians(lat2 - lat1)
dlon = math.radians(lon2 - lon1)
a = (
math.sin(dlat / 2) ** 2
+ math.cos(math.radians(lat1))
* math.cos(math.radians(lat2))
* math.sin(dlon / 2) ** 2
)
return R * 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))
async def fetch_unrest_events(
fetcher: Fetcher,
country: str | None = None,
days: int = 7,
limit: int = 100,
) -> dict:
"""Fetch social unrest events (protests + riots) from ACLED.
Filters by event_type in (Protests, Riots).
Applies Haversine deduplication: merges events within 50 km on the
same day to remove redundant reports.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
country: Optional country name filter.
days: Lookback period in days.
limit: Maximum results from ACLED.
Returns:
Dict with events list, count, dedup stats, source, and timestamp.
"""
now = datetime.now(timezone.utc)
start_date = (now - timedelta(days=days)).strftime("%Y-%m-%d")
end_date = now.strftime("%Y-%m-%d")
params: dict = {
"limit": limit,
"event_date": f"{start_date}|{end_date}",
"event_date_where": "BETWEEN",
"event_type": "Protests:Riots",
"event_type_where": "IN",
}
if country:
params["country"] = country
cache_label = country or "global"
data = await acled_query(
fetcher,
params=params,
cache_key=f"intel:unrest:{cache_label}:{days}:{limit}",
cache_ttl=900,
)
if data is None:
reason = await acled_failure_reason(data)
if reason == "acled_unconfigured":
return {
"error": "ACLED credentials not configured (ACLED_EMAIL + ACLED_PASSWORD)",
"source": "acled-unrest",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
return {
"error": acled_failure_message(reason),
"degraded": True,
"source": "acled-unrest",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
raw_events = data.get("data", []) if isinstance(data, dict) else []
# Parse events
parsed: list[dict] = []
for ev in raw_events:
lat_raw = ev.get("latitude")
lon_raw = ev.get("longitude")
lat = None
lon = None
try:
lat = float(lat_raw) if lat_raw is not None else None
lon = float(lon_raw) if lon_raw is not None else None
except (ValueError, TypeError):
pass
fat = 0
try:
fat = int(ev.get("fatalities", 0))
except (ValueError, TypeError):
pass
parsed.append(
{
"event_date": ev.get("event_date"),
"event_type": ev.get("event_type"),
"sub_event_type": ev.get("sub_event_type"),
"country": ev.get("country"),
"admin1": ev.get("admin1"),
"location": ev.get("location"),
"latitude": lat,
"longitude": lon,
"fatalities": fat,
"actor1": ev.get("actor1"),
"notes": ev.get("notes"),
}
)
# Haversine deduplication: merge events within 50km on same day
DEDUP_RADIUS_KM = 50.0
deduped: list[dict] = []
original_count = len(parsed)
for event in parsed:
lat = event.get("latitude")
lon = event.get("longitude")
edate = event.get("event_date")
is_dup = False
if lat is not None and lon is not None:
for existing in deduped:
if existing.get("event_date") != edate:
continue
ex_lat = existing.get("latitude")
ex_lon = existing.get("longitude")
if ex_lat is None or ex_lon is None:
continue
dist = _haversine_km(lat, lon, ex_lat, ex_lon)
if dist < DEDUP_RADIUS_KM:
# Merge: keep higher fatality count
if event["fatalities"] > existing["fatalities"]:
existing["fatalities"] = event["fatalities"]
is_dup = True
break
if not is_dup:
deduped.append(event)
return {
"events": deduped,
"count": len(deduped),
"deduplicated": original_count - len(deduped),
"query": {"country": country, "days": days},
"source": "acled-unrest",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# ---------------------------------------------------------------------------
# Function 9: Hotspot Escalation Scoring
# ---------------------------------------------------------------------------
async def fetch_hotspot_escalation(fetcher: Fetcher) -> dict:
"""Score all 22 intel hotspots using multi-source signals.
For each hotspot:
- Fetch GDELT mentions (news velocity near lat/lon)
- Count military aircraft near hotspot (+/- 2 deg)
- Count ACLED events near hotspot (+/- 2 deg, last 7 days)
Runs analysis.escalation.score_all_hotspots().
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
Returns:
Dict with scored hotspots, count, source, and timestamp.
"""
now = datetime.now(timezone.utc)
from . import military as mil_mod
# Fetch global data once, then distribute to hotspots
async def _fetch_global_acled() -> tuple[list[dict], str | None]:
start_date = (now - timedelta(days=7)).strftime("%Y-%m-%d")
end_date = now.strftime("%Y-%m-%d")
data = await acled_query(
fetcher,
params={
"limit": 500,
"event_date": f"{start_date}|{end_date}",
"event_date_where": "BETWEEN",
},
cache_key="intel:escalation:acled:global:7d",
cache_ttl=1800,
)
if data is None:
return [], await acled_failure_reason(data)
events = data.get("data", []) if isinstance(data, dict) else []
return events, None
async def _fetch_global_military() -> list[dict]:
# Use theater posture for global coverage
result = await mil_mod.fetch_theater_posture(fetcher)
aircraft = []
for theater_data in result.get("theaters", {}).values():
for ac in theater_data.get("countries", []):
# Create pseudo-aircraft entries at theater bbox center
bbox = theater_data.get("bbox", "")
parts = bbox.split(",")
if len(parts) == 4:
try:
lat = (float(parts[0]) + float(parts[2])) / 2
lon = (float(parts[1]) + float(parts[3])) / 2
for _ in range(
theater_data.get("count", 0)
// max(1, len(theater_data.get("countries", [1])))
):
aircraft.append(
{"lat": lat, "lon": lon, "origin_country": ac}
)
except (ValueError, TypeError):
pass
return aircraft
(acled_events, acled_gap), military_data = await asyncio.gather(
_fetch_global_acled(),
_fetch_global_military(),
)
# Build signal dict for each hotspot
RADIUS_DEG = 2.0
hotspot_signals: dict[str, dict] = {}
for hs_name, hs_config in INTEL_HOTSPOTS.items():
hs_lat = hs_config["lat"]
hs_lon = hs_config["lon"]
# Count ACLED events near hotspot
conflict_count = 0
protest_count = 0
fatality_count = 0
for ev in acled_events:
try:
ev_lat = float(ev.get("latitude", 0))
ev_lon = float(ev.get("longitude", 0))
except (ValueError, TypeError):
continue
if (
abs(ev_lat - hs_lat) <= RADIUS_DEG
and abs(ev_lon - hs_lon) <= RADIUS_DEG
):
event_type = (ev.get("event_type") or "").lower()
if "protest" in event_type:
protest_count += 1
else:
conflict_count += 1
try:
fatality_count += int(ev.get("fatalities", 0))
except (ValueError, TypeError):
pass
# Count military aircraft near hotspot
mil_count = 0
for ac in military_data:
ac_lat = ac.get("lat", 0)
ac_lon = ac.get("lon", 0)
if (
abs(ac_lat - hs_lat) <= RADIUS_DEG
and abs(ac_lon - hs_lon) <= RADIUS_DEG
):
mil_count += 1
hotspot_signals[hs_name] = {
# news_mentions/convergence_score are left unset (None via
# score_hotspot's default) rather than 0 — no per-hotspot
# GDELT query or geo-convergence signal is wired up yet, and a
# hardcoded 0 is indistinguishable from "measured, genuinely
# quiet." score_all_hotspots renormalizes around the gap.
"military_count": mil_count,
"conflict_events": conflict_count,
"fatalities": fatality_count,
"protests": protest_count,
}
scored = score_all_hotspots(INTEL_HOTSPOTS, hotspot_signals)
return {
"hotspots": scored,
"count": len(scored),
"unavailable_components": ["news", "convergence"],
"data_gaps": [acled_gap] if acled_gap else [],
"source": "hotspot-escalation",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
# ---------------------------------------------------------------------------
# Function 10: Military Surge Detection
# ---------------------------------------------------------------------------
async def fetch_military_surge(fetcher: Fetcher) -> dict:
"""Detect military surge anomalies across sensitive regions.
1. Fetch theater posture (existing)
2. Build temporal baselines for each region
3. Run analysis.surge.detect_surges()
A theater that no military flight source answered for (posture's
unavailable_theaters) has unknown traffic, not zero: its regions go
unchecked and nothing is recorded in their baselines. With the posture
itself unavailable the response is an error.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
Returns:
Dict with surges list, regions checked, data_gaps, source, and
timestamp; unchecked_regions and degraded when some theaters had no
source; error / degraded / reason when the posture is unavailable.
"""
now = datetime.now(timezone.utc)
from . import military as mil_mod
from ..analysis.surge import _THEATER_REGION_MAP
posture = await mil_mod.fetch_theater_posture(fetcher)
if posture.get("error"):
# An outage used to record a zero in every region's baseline and
# report no surges, the reading of an empty sky.
return {
"surges": [],
"surge_count": 0,
"regions_checked": 0,
"data_gaps": [
f"theater posture unavailable ({posture['error']}): no region was "
"checked and nothing was recorded in the surge baselines"
],
"error": f"Theater posture unavailable: {posture['error']}",
"degraded": True,
"reason": posture.get("reason") or "theater_posture_unavailable",
"source": "military-surge-detection",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
theater_data = posture.get("theaters", {})
unavailable_theaters = set(posture.get("unavailable_theaters") or [])
# Build temporal baselines for each region
temporal_baselines: dict[str, dict] = {}
unchecked: list[str] = []
for region_name in SENSITIVE_REGIONS:
theaters = [
name for name, regions in _THEATER_REGION_MAP.items() if region_name in regions
]
if unavailable_theaters.intersection(theaters):
unchecked.append(region_name)
continue
# Record total aircraft count in the region's matching theaters
total = sum(theater_data.get(name, {}).get("count", 0) for name in theaters)
result = _temporal.record_and_check("surge_aircraft", region_name, total)
if result is not None:
temporal_baselines[region_name] = {
"z_score": result["z_score"],
"multiplier": result.get("multiplier"),
}
surges = detect_surges(theater_data, temporal_baselines)
response = {
"surges": surges,
"surge_count": len(surges),
"regions_checked": len(SENSITIVE_REGIONS) - len(unchecked),
"data_gaps": [],
"source": "military-surge-detection",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
if unchecked:
response["unchecked_regions"] = unchecked
response["degraded"] = True
response["data_gaps"].append(
"no military flight source answered for "
f"{', '.join(sorted(unavailable_theaters))}, so {', '.join(unchecked)} "
"went unchecked and nothing was recorded in their baselines"
)
return response
# ---------------------------------------------------------------------------
# Function 11: Vessel Snapshot at Strategic Waterways
# ---------------------------------------------------------------------------
_NAVAL_KEYWORDS = re.compile(
r"\b(naval|warship|destroyer|frigate|carrier|submarine|fleet|military\s+vessel|"
r"exercise|mine|ordnance|firing|weapons)\b",
re.IGNORECASE,
)
# A warning concerns a waterway when a position stated in its text lies
# within this distance of the waterway's reference point in
# STRATEGIC_WATERWAYS. 300 km is a chosen radius, not a measured boundary:
# it spans each canal end to end and a strait's approaches, but one point
# models the long GIUK Gap and Strait of Malacca only near that point.
_WATERWAY_PROXIMITY_KM = 300.0
# A warning that states no readable position is credited to no waterway,
# whatever its area code. Crediting one by NAVAREA (IV and XII both contain
# the Panama Canal) gave Panama warnings from Hawaii, California and
# Virginia: all 5 such credits in the 2026-10-17 capture were wrong, and
# none of the 200 among the 3,480 warnings of 2024 named Panama. Requiring
# the name would not fix it: 4:2024-468 names "PANAMA CITY", in Florida.
_VESSEL_MATCHING_RULE = (
"A warning is credited to a waterway only when a position stated in its "
"text (read in full, before the 500-character cut) lies within "
"proximity_km of the waterway's reference point. A warning that states "
"no readable position is credited to no waterway: its area code names "
"at least a whole NAVAREA (area_codes), far wider than proximity_km. "
"Naval ones are listed in unplaced_naval_warnings with the reason. "
"status counts the naval-keyword warnings credited to the waterway; it "
"reads stale when the feed's newest warning is older than "
"stale_after_days and unknown when the feed is unavailable or how "
"current it is cannot be checked (feed_stale null: no usable issue "
"date, or no active warnings at all). "
"total_nearby counts credited warnings of any topic."
)
async def fetch_vessel_snapshot(fetcher: Fetcher) -> dict:
"""Naval activity snapshot at strategic waterways using NGA warnings.
Uses NGA MSI (maritime.fetch_nav_warnings) filtered for naval/vessel
keywords. Each warning is credited only to the STRATEGIC_WATERWAYS
within _WATERWAY_PROXIMITY_KM of a position it states; one that states
no readable position is credited nowhere and, if naval, listed in
unplaced_naval_warnings. The response states the rule (matching_rule).
Before 2026-10-17 every warning counted at all nine waterways, so three
naval warnings anywhere on Earth marked Panama and Hormuz critical alike.
Scores each waterway: clear/advisory/elevated/critical; stale when the
feed's newest warning is past its staleness threshold (the counts then
describe the feed's last update, status_as_of, not today); unknown when
the feed itself is unavailable or its currency cannot be checked
(feed_stale None: no usable issue date, or an empty feed).
Note: Real-time AIS requires paid API. This uses NGA MSI as a
free proxy for naval activity indicators.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
Returns:
Dict with waterways list (each with total_nearby, the warnings of
any topic credited to it, and status_as_of), the matching rule,
naval warnings no rule could place, the feed's newest issue date,
feed_stale, data_gaps, source, and timestamp.
"""
now = datetime.now(timezone.utc)
from . import maritime
nav_data = await maritime.fetch_nav_warnings(fetcher)
all_warnings = nav_data.get("warnings", []) or []
feed_error = nav_data.get("error")
feed_stale = nav_data.get("feed_stale") is True
# Only feed_stale False says the feed is current. None (no usable issue
# date, or no active warnings) used to score as current: three undated
# warnings near Hormuz read "critical".
currency_unknown = not feed_error and nav_data.get("feed_stale") is None
credited: dict[str, dict] = {
ww["name"]: {"naval": [], "nearby": 0} for ww in STRATEGIC_WATERWAYS
}
unplaced_naval: list[dict] = []
naval_total = 0
truncated = 0
for warning in all_warnings:
text = warning.get("text") or ""
is_naval = bool(_NAVAL_KEYWORDS.search(text))
naval_total += is_naval
if isinstance(warning.get("positions"), list):
# fetch_nav_warnings read these from the full text, before the
# 500-character cut that used to hide later positions.
positions = [(p[0], p[1]) for p in warning["positions"]]
states_position = bool(positions) or bool(warning.get("mentions_position"))
else:
positions = maritime.extract_positions(text)
states_position = maritime.mentions_position(text)
if len(text) > maritime._MAX_TEXT_LENGTH and text.endswith("..."):
truncated += 1
matches: list[tuple[str, float]] = []
if positions:
for ww in STRATEGIC_WATERWAYS:
distance = min(
_haversine_km(ww["lat"], ww["lon"], lat, lon)
for lat, lon in positions
)
if distance <= _WATERWAY_PROXIMITY_KM:
matches.append((ww["name"], round(distance, 1)))
elif is_naval:
area = maritime.NGA_AREA_CODES.get(str(warning.get("navarea") or "").upper())
if states_position:
# Its only stated positions are malformed or not points.
reason = "position_unreadable"
elif area is None:
reason = "unknown_area_code"
elif area["single_navarea"]:
# One NAVAREA (XII) is still an ocean wide.
reason = "navarea_too_broad"
else:
reason = "multi_navarea_series"
unplaced_naval.append(
{
"id": warning.get("id"),
"navarea": warning.get("navarea"),
"series": area["series"] if area else None,
"issue_date": warning.get("issue_date"),
"reason": reason,
"text_snippet": text[:200],
}
)
for name, distance in matches:
entry = credited[name]
entry["nearby"] += 1
if is_naval:
entry["naval"].append(
{
"id": warning.get("id"),
"text_snippet": text[:200],
"navarea": warning.get("navarea"),
"issue_date": warning.get("issue_date"),
"match": "proximity",
"distance_km": distance,
}
)
waterways: list[dict] = []
for ww in STRATEGIC_WATERWAYS:
entry = credited[ww["name"]]
# Nearest stated positions first.
naval_warnings = sorted(entry["naval"], key=lambda d: d["distance_km"])
naval_count = len(naval_warnings)
if feed_error or currency_unknown:
status = "unknown"
elif feed_stale:
# A frozen feed's warnings describe its last update, not today:
# three 2024 warnings near Hormuz used to read "critical".
status = "stale"
elif naval_count >= 3:
status = "critical"
elif naval_count >= 2:
status = "elevated"
elif naval_count >= 1:
status = "advisory"
else:
status = "clear"
waterways.append(
{
"name": ww["name"],
"lat": ww["lat"],
"lon": ww["lon"],
"throughput": ww.get("throughput"),
"naval_warnings": naval_count,
"status": status,
"status_as_of": nav_data.get("newest_issue_date"),
"warning_details": naval_warnings[:5],
"total_nearby": entry["nearby"],
"nearby_by_match": {"proximity": entry["nearby"]},
"naval_by_match": {"proximity": naval_count},
}
)
data_gaps = [f"NGA feed: {gap}" for gap in nav_data.get("data_gaps") or []]
if feed_error and not data_gaps:
data_gaps.append(f"NGA feed: {feed_error}")
if currency_unknown:
data_gaps.append(
"every waterway reads unknown, not a threat level: how current the "
"NGA feed is cannot be checked (feed_stale null), so naval_warnings "
"is not scored as today's activity"
)
if feed_stale and not feed_error:
data_gaps.append(
"every waterway reads stale, not a threat level: naval_warnings "
"counts warnings from a feed last updated "
f"{nav_data.get('newest_issue_date')} (status_as_of)"
)
if unplaced_naval:
data_gaps.append(
f"{len(unplaced_naval)} naval warning(s) state no readable position, "
"so no waterway is credited with them (unplaced_naval_warnings): "
+ ", ".join(
f"{maritime._warning_label(w)} ({w['reason']})" for w in unplaced_naval
)
)
if truncated:
data_gaps.append(
f"{truncated} warning text(s) were cut at {maritime._MAX_TEXT_LENGTH} "
"characters; positions after the cut are not read"
)
response = {
"waterways": waterways,
"count": len(waterways),
"total_nav_warnings": len(all_warnings),
"total_naval_warnings": naval_total,
"unplaced_naval_warnings": unplaced_naval,
"matching_rule": {
"proximity_km": _WATERWAY_PROXIMITY_KM,
"rule": _VESSEL_MATCHING_RULE,
"area_codes": maritime.area_codes_view(),
},
"newest_issue_date": nav_data.get("newest_issue_date"),
"newest_issue_age_days": nav_data.get("newest_issue_age_days"),
"stale_after_days": nav_data.get("stale_after_days"),
"feed_stale": nav_data.get("feed_stale"),
"data_gaps": data_gaps,
"source": "nga-msi-vessel-snapshot",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}
if feed_error:
# Every waterway used to read "clear" when NGA was down.
response["error"] = f"NGA navigational warnings unavailable: {feed_error}"
response["degraded"] = True
response["reason"] = nav_data.get("reason") or "nav_warnings_unavailable"
elif nav_data.get("degraded") or currency_unknown:
response["degraded"] = True
return response
# ---------------------------------------------------------------------------
# Function 12: Infrastructure Cascade Analysis
# ---------------------------------------------------------------------------
async def fetch_cascade_analysis(
fetcher: Fetcher,
corridor: str | None = None,
) -> dict:
"""Simulate infrastructure cascade from corridor disruption.
1. Fetch current cable health (existing fetch_cable_health)
2. If corridor specified, simulate that corridor disrupted
3. If not, simulate each at_risk/disrupted corridor
4. Run analysis.cascade.simulate_cascade()
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
corridor: Optional specific corridor to simulate disruption of.
Returns:
Dict with scenarios, current health, source, and timestamp.
"""
now = datetime.now(timezone.utc)
from . import infrastructure
health_data = await infrastructure.fetch_cable_health(fetcher)
corridors_health = health_data.get("corridors", {})
scenarios: list[dict] = []
if corridor:
# Simulate specific corridor disruption
result = simulate_cascade([corridor], current_health=corridors_health)
scenarios.append(
{
"scenario": f"Disruption of {corridor}",
"corridors": [corridor],
**result,
}
)
else:
# Simulate each at_risk or disrupted corridor
at_risk_corridors = [
name
for name, info in corridors_health.items()
if info.get("status_score", 0) >= 2
]
if at_risk_corridors:
# Individual scenarios
for c in at_risk_corridors:
result = simulate_cascade([c], current_health=corridors_health)
scenarios.append(
{
"scenario": f"Disruption of {c}",
"corridors": [c],
**result,
}
)
# Combined worst-case scenario
if len(at_risk_corridors) >= 2:
result = simulate_cascade(
at_risk_corridors, current_health=corridors_health
)
scenarios.append(
{
"scenario": "Combined disruption (worst case)",
"corridors": at_risk_corridors,
**result,
}
)
else:
# No at-risk corridors; simulate red_sea as a common scenario
result = simulate_cascade(["red_sea"], current_health=corridors_health)
scenarios.append(
{
"scenario": "Hypothetical: Red Sea corridor disruption",
"corridors": ["red_sea"],
**result,
}
)
return {
"scenarios": scenarios,
"scenario_count": len(scenarios),
"current_health": {
name: {
"status_score": info.get("status_score"),
"status_label": info.get("status_label"),
}
for name, info in corridors_health.items()
},
"source": "cascade-analysis",
"timestamp": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
}