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
"""Alert digest and weekly trends analysis for world-intel-mcp.
Provides cross-domain alert aggregation (intel_alert_digest) and
temporal trend analysis (intel_weekly_trends). Both use lazy imports
to avoid circular dependencies with source modules.
"""
import asyncio
import logging
import math
import os
import sqlite3
from datetime import datetime, timezone
from pathlib import Path
logger = logging.getLogger("world-intel-mcp.analysis.alerts")
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _utc_now_iso() -> str:
return datetime.now(timezone.utc).isoformat()
async def _safe_fetch(coro, label: str) -> dict:
"""Run a coroutine safely, returning empty dict on failure."""
try:
return await coro
except Exception as exc:
logger.warning("Alert digest: %s failed: %s", label, exc)
return {}
# ---------------------------------------------------------------------------
# Alert Digest
# ---------------------------------------------------------------------------
_ALERT_THRESHOLDS: dict[str, dict] = {
"space_weather": {
"field": "current_kp",
"threshold": 5.0,
"priority": "high",
"domain": "space",
"message_template": "Geomagnetic storm: Kp={value} ({level})",
},
"instability": {
"field": "countries",
"threshold": 70,
"priority": "critical",
"domain": "political",
"message_template": "{count} countries above instability threshold",
},
"military_surge": {
"field": "surge_count",
"threshold": 1,
"priority": "high",
"domain": "military",
"message_template": "{count} military surge anomalies detected",
},
"cable_health": {
"field": "corridors",
"threshold": 2,
"priority": "high",
"domain": "infrastructure",
"message_template": "{count} cable corridors at risk",
},
"hotspot_escalation": {
"field": "hotspots",
"threshold": 60,
"priority": "critical",
"domain": "security",
"message_template": "{count} hotspots above escalation threshold",
},
"internet_outages": {
"field": "outage_count",
"threshold": 5,
"priority": "medium",
"domain": "infrastructure",
"message_template": "{count} internet outages active",
},
"shipping_stress": {
"field": "stress_score",
"threshold": 30.0,
"priority": "medium",
"domain": "economic",
"message_template": "Shipping stress index at {value}",
},
}
async def fetch_alert_digest(fetcher) -> dict:
"""Aggregate alerts from 7 intelligence domains.
Calls existing source functions in parallel, applies threshold-based
alerting, and returns a prioritized alert list.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
Returns:
Dict with alerts, alert_count, by_priority, domains_checked, source.
"""
# Lazy imports to avoid circular deps
from ..sources import space_weather, infrastructure
from ..sources import intelligence
from ..sources import shipping
# Fetch all sources in parallel
(
sw_data,
instability_data,
surge_data,
cable_data,
hotspot_data,
outage_data,
shipping_data,
) = await asyncio.gather(
_safe_fetch(space_weather.fetch_space_weather(fetcher), "space_weather"),
_safe_fetch(intelligence.fetch_instability_index(fetcher), "instability"),
_safe_fetch(intelligence.fetch_military_surge(fetcher), "military_surge"),
_safe_fetch(infrastructure.fetch_cable_health(fetcher), "cable_health"),
_safe_fetch(intelligence.fetch_hotspot_escalation(fetcher), "hotspot_escalation"),
_safe_fetch(infrastructure.fetch_internet_outages(fetcher), "internet_outages"),
_safe_fetch(shipping.fetch_shipping_index(fetcher), "shipping"),
)
alerts: list[dict] = []
# Space weather: Kp >= 5
kp = sw_data.get("current_kp")
if kp is not None and kp >= _ALERT_THRESHOLDS["space_weather"]["threshold"]:
alerts.append({
"domain": "space",
"priority": "high",
"message": f"Geomagnetic storm: Kp={kp} ({sw_data.get('kp_level', 'Unknown')})",
"value": kp,
})
# Instability: countries above threshold
countries = instability_data.get("countries", [])
high_instability = [c for c in countries if c.get("instability_index", 0) >= 70]
if high_instability:
alerts.append({
"domain": "political",
"priority": "critical",
"message": f"{len(high_instability)} countries above instability threshold (>=70)",
"countries": [c.get("country_name", c.get("country_code")) for c in high_instability[:5]],
"value": len(high_instability),
})
# Military surge
surge_count = surge_data.get("surge_count", 0)
if surge_count >= 1:
alerts.append({
"domain": "military",
"priority": "high",
"message": f"{surge_count} military surge anomalies detected",
"surges": surge_data.get("surges", [])[:3],
"value": surge_count,
})
# Cable health: corridors with status_score >= 2
corridors = cable_data.get("corridors", {})
at_risk = [
name for name, info in corridors.items()
if isinstance(info, dict) and info.get("status_score", 0) >= 2
]
if at_risk:
alerts.append({
"domain": "infrastructure",
"priority": "high",
"message": f"{len(at_risk)} cable corridors at elevated risk: {', '.join(at_risk[:3])}",
"corridors": at_risk,
"value": len(at_risk),
})
# Hotspot escalation: hotspots with score >= 60
hotspots = hotspot_data.get("hotspots", [])
hot = [h for h in hotspots if h.get("score", 0) >= 60]
if hot:
alerts.append({
"domain": "security",
"priority": "critical",
"message": f"{len(hot)} hotspots above escalation threshold",
"hotspots": [h.get("name") for h in hot[:5]],
"value": len(hot),
})
# Internet outages
outage_count = outage_data.get("outage_count", 0)
if outage_count >= 5:
alerts.append({
"domain": "infrastructure",
"priority": "medium",
"message": f"{outage_count} internet outages active",
"value": outage_count,
})
# Shipping stress
stress = shipping_data.get("stress_score", 0)
if stress >= 30:
alerts.append({
"domain": "economic",
"priority": "medium" if stress < 60 else "high",
"message": f"Shipping stress index at {stress} ({shipping_data.get('assessment', 'unknown')})",
"value": stress,
})
# Sort: critical > high > medium
priority_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
alerts.sort(key=lambda a: priority_order.get(a.get("priority", "low"), 4))
# Group by priority
by_priority: dict[str, int] = {}
for a in alerts:
p = a.get("priority", "unknown")
by_priority[p] = by_priority.get(p, 0) + 1
return {
"alerts": alerts,
"alert_count": len(alerts),
"by_priority": by_priority,
"domains_checked": [
"space_weather", "instability", "military_surge",
"cable_health", "hotspot_escalation", "internet_outages",
"shipping_stress",
],
"source": "alert-digest",
"timestamp": _utc_now_iso(),
}
# ---------------------------------------------------------------------------
# Weekly Trends
# ---------------------------------------------------------------------------
# A metric needs this many observations before its volatility is reported.
_MIN_TREND_OBSERVATIONS = 5
def _read_baselines(db_path: str) -> tuple[list[tuple], str | None]:
"""Every baseline row, or the reason none could be read.
The file is opened read-only: reading trends must never leave an empty
database where the baselines were expected.
"""
if not os.path.exists(db_path):
return [], f"no temporal baseline database at {db_path}"
try:
conn = sqlite3.connect(f"{Path(db_path).absolute().as_uri()}?mode=ro", uri=True)
try:
rows = conn.execute(
"SELECT key, count, mean, m2, updated_at FROM baselines"
).fetchall()
finally:
conn.close()
except (sqlite3.Error, OSError) as exc:
logger.warning("Failed to read temporal baselines: %s", exc)
return [], f"could not read {db_path}: {exc}"
return rows, None
async def fetch_weekly_trends(fetcher) -> dict:
"""Analyze weekly trends from temporal baselines.
Reads the TemporalBaseline SQLite database to compute volatility
(coefficient of variation) for each tracked metric, and calls
temporal_anomalies to get current deviations.
A failed input never reads as zero. ``data_gaps`` names every input
that failed or has no history to judge by. When the baseline database
is missing or unreadable, ``trend_count`` is None and ``error`` says
why; when anomaly detection fails, ``current_anomaly_count`` is None.
Args:
fetcher: Shared HTTP fetcher with caching and circuit breaking.
Returns:
Dict with trends, trend_count, current_anomalies,
current_anomaly_count, data_gaps, analysis_period, source, and
error when the baselines could not be read.
"""
from ..analysis.temporal import _default_db_path
from ..sources import intelligence
db_path = _default_db_path()
# Anomaly detection records this cycle's observations and creates the
# database on first use, so look first: a baseline born in this call has
# no history, which is not the same as a quiet week.
baseline_existed = os.path.exists(db_path)
data_gaps: list[str] = []
# Get current anomalies
current_anomalies: list[dict] = []
current_anomaly_count: int | None = None
try:
anomaly_data = await intelligence.fetch_temporal_anomalies(fetcher)
except Exception as exc:
logger.warning("Weekly trends: temporal anomalies failed: %s", exc)
data_gaps.append(f"Current anomalies: {type(exc).__name__}: {exc}")
else:
anomalies = (
anomaly_data.get("anomalies") if isinstance(anomaly_data, dict) else None
)
if isinstance(anomalies, list):
current_anomalies = anomalies
current_anomaly_count = len(anomalies)
data_gaps.extend(
f"Current anomalies: {gap}" for gap in anomaly_data.get("data_gaps") or []
)
else:
data_gaps.append(
"Current anomalies: anomaly detection returned no anomaly list"
)
# Read baselines from SQLite
rows, baseline_problem = _read_baselines(db_path)
trends: list[dict] = []
trend_count: int | None = None
if baseline_problem is not None:
data_gaps.append(f"Baselines: {baseline_problem}")
else:
for key, n, mean, m2, updated_at in rows:
if n < _MIN_TREND_OBSERVATIONS:
continue
parts = key.split(":")
if len(parts) < 2:
continue
event_type = parts[0]
region = parts[1]
weekday = parts[2] if len(parts) > 2 else ""
month = parts[3] if len(parts) > 3 else ""
# Compute coefficient of variation (volatility)
variance = m2 / (n - 1) if n > 1 else 0.0
std = math.sqrt(variance) if variance > 0 else 0.0
cv = (std / mean * 100) if mean > 0 else 0.0
trends.append({
"metric": event_type,
"region": region,
"weekday": weekday,
"month": month,
"observations": n,
"mean": round(mean, 2),
"std_dev": round(std, 2),
"volatility_cv": round(cv, 1),
"last_updated": updated_at,
})
trend_count = len(trends)
if not baseline_existed:
data_gaps.append(
f"Baselines: none existed at {db_path} before this call, so "
"trends and anomalies have no history yet"
)
elif not any(row[1] >= _MIN_TREND_OBSERVATIONS for row in rows):
data_gaps.append(
"Baselines: no tracked metric has the "
f"{_MIN_TREND_OBSERVATIONS} observations volatility needs yet "
f"({len(rows)} tracked)"
)
# Sort by volatility descending
trends.sort(key=lambda t: t.get("volatility_cv", 0), reverse=True)
result = {
"trends": trends[:50],
"trend_count": trend_count,
"current_anomalies": current_anomalies,
"current_anomaly_count": current_anomaly_count,
"data_gaps": data_gaps,
"analysis_period": "weekly (by weekday+month seasonality)",
"source": "temporal-weekly-trends",
"timestamp": _utc_now_iso(),
}
if baseline_problem is not None:
result["error"] = f"Temporal baselines unavailable: {baseline_problem}"
return result