mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-26 01:24:59 +02:00
19d67cea94
* feat(intelligence): regime drift history (Phase 3 PR1)
Phase 3 PR1 of the Regional Intelligence Model. Adds an append-only
regime transition log per region plus a premium-gated RPC to read it.
## What landed
### New writer module: scripts/regional-snapshot/regime-history.mjs
Single public entry point:
recordRegimeTransition(region, snapshot, diff, opts?)
-> { recorded, entry, pushed, trimmed }
Pure builder + Redis-ops orchestrator + dependency-injected publisher.
Flow:
1. buildTransitionEntry() returns null when diff has no regime_changed
(steady-state snapshots produce no entry — pure transition stream)
2. publishTransitionWithOps() LPUSHes onto
intelligence:regime-history:v1:{region}, then LTRIMs to keep the
most recent REGIME_HISTORY_MAX (100) entries
3. defaultPublisher binds real Upstash REST calls; tests inject an
in-memory ops object for offline coverage
LTRIM failure is non-fatal — entry already landed, next cycle will
re-trim. LPUSH failure short-circuits and reports pushed=false. The
recorder NEVER throws and is wrapped in its own try/catch in the seed
loop so snapshot persist is never blocked.
### seed-regional-snapshots.mjs hook
Added a regime-history call alongside the existing alert-emitter call,
right after persistSnapshot success. Same best-effort contract:
unconditional try/catch, log warn on throw, continue main loop.
### Proto + RPC: GetRegimeHistory
proto/worldmonitor/intelligence/v1/get_regime_history.proto
- GetRegimeHistoryRequest { region_id, limit (0..100) }
- GetRegimeHistoryResponse { transitions: RegimeTransition[] }
- RegimeTransition { region_id, label, previous_label,
transitioned_at, transition_driver, snapshot_id }
region_id validated as strict kebab-case (same regex as
get-regional-snapshot). limit capped server-side at MAX_LIMIT=100,
defaulting to 50 when omitted.
Added to IntelligenceService in service.proto. Generated openapi
JSON/YAML committed via `make generate`.
### Server handler: server/worldmonitor/intelligence/v1/get-regime-history.ts
LRANGE-based read (newest-first because the writer LPUSHes). adapter
is a dedicated exported function adaptTransition(raw) for testability.
LRANGE helper is inlined here because server/_shared/redis.ts has no
list helpers yet — this is the first list-reading handler in the
intelligence service. If a second list reader lands, the helper can
be promoted to a shared util.
Empty list / Redis miss / failed JSON parse all return
{ transitions: [] } so the client can distinguish "never changed" from
"upstream broken" via the HTTP status code, not the body.
Registered in handler.ts.
### Premium gating + cache tier
src/shared/premium-paths.ts: added /api/intelligence/v1/get-regime-history
server/gateway.ts RPC_CACHE_TIER: same path with 'slow' tier (matches
route-parity contract enforced by
tests/route-cache-tier.test.mjs)
## Tests — 44 new unit tests
tests/regional-snapshot-regime-history.test.mjs (22 tests):
buildTransitionEntry (7):
- null on missing diff/region/snapshot
- returns entry on regime change
- first-ever transition (empty previous_label)
- falls back to generated_at when transitioned_at is missing
- preserves snapshot_id
publishTransitionWithOps (8):
- happy path (LPUSH + LTRIM both succeed)
- canonical key prefix
- LTRIM uses REGIME_HISTORY_MAX-1 stop
- LPUSH failure → not pushed, LTRIM not called
- LTRIM failure → pushed=true, trimmed=false (non-fatal)
- LPUSH/LTRIM throwing caught and reported
- null/empty entry → no-op
recordRegimeTransition (5):
- no-op on no regime change
- records on regime change
- publisher returning false → recorded=false
- publisher exceptions swallowed
- critical escalation labels preserved
module constants (2): key prefix + max are valid
tests/get-regime-history.test.mts (22 tests):
adaptTransition (4):
- all fields snake → camel
- missing fields → empty/zero defaults
- first-ever transition shape preserved
- non-numeric transitioned_at → 0
handler structural checks (7): canonical key prefix, LRANGE usage,
adapter export, handler export signature, MAX_LIMIT cap matches
writer, missing-region short-circuit, malformed-entry filter
intelligence handler registration (2): import + registration
security wiring (2): premium path + cache-tier entry
proto definition (7): RPC method declared, import wired, request
shape, kebab regex, limit bounds, RegimeTransition fields,
response shape
## Verification
- node --test tests/regional-snapshot-regime-history.test.mjs: 22/22 pass
- npx tsx --test tests/get-regime-history.test.mts: 22/22 pass
- npm run test:data: 4621/4621 pass
- npm run typecheck: clean
- npm run typecheck:api: clean
- biome lint on touched files: clean
## Deferred to future iterations
- Phase 3 PR2: weekly regional briefs LLM seeder (consumes regime history
to highlight drift events in the weekly summary)
- Phase 3 PR3: UI block in RegionalIntelligenceBoard for regime drift
timeline (can ride alongside or after PR2)
- Drift analytics: % of last N days spent in each regime, transition
frequency rolling window, regime cycle detection
- Alert triggers on drift cycles (e.g., "thrashed between regimes 3 times
in 7 days")
* fix(intelligence): address 2 review findings on #2981
P2 #1 — transition_driver always empty in the live path
buildRegimeState(balance, previousLabel, '') at Step 11 passed an empty
driver because the diff hasn't been computed yet. The regime-history
recorder reads snapshot.regime.transition_driver which was therefore
always '' in production, despite tests exercising synthetic fixtures
with a populated driver.
Fix: after Step 15 derives triggerReason via inferTriggerReason(diff),
backfill regime.transition_driver = triggerReason when a genuine regime
change occurred. This ensures both the persisted snapshot's regime block
AND the regime-history entry carry the real driver (e.g., 'regime_shift',
'trigger_activation', 'corridor_break').
Added 2 regression tests: populated driver flows through, and pre-fix
empty-driver snapshots remain back-compatible.
P2 #2 — Redis failure returns cached false-empty history
get-regime-history.ts returned 200 {transitions:[]} on LRANGE failure.
The gateway caches 200 GET responses at the slow tier, so a transient
Upstash outage would be pinned as a false-empty history until the cache
TTL expired.
Fix: when redisLrange returns null (Redis unavailable or credentials
missing), the response now includes upstreamUnavailable: true in the
body. The gateway already checks for this flag in the response body
(line 434) and sets Cache-Control: no-store, so transient failures are
not cached.
Added 1 structural test asserting the upstreamUnavailable flag is set.
Verification:
- 24/24 writer tests, 23/23 handler tests, 4624/4624 full suite pass
- npm run typecheck: clean
- biome lint on touched files: clean
* fix(intelligence): correct misleading 'log once per region' comment (Greptile P2)
1 line
75 KiB
JSON
1 line
75 KiB
JSON
{"components":{"schemas":{"ActorState":{"description":"ActorState is one geopolitical actor's leverage score in the region.","properties":{"actorId":{"type":"string"},"delta":{"format":"double","type":"number"},"evidenceIds":{"items":{"type":"string"},"type":"array"},"leverageDomains":{"items":{"description":"leverage_domains: energy | military | diplomatic | economic | maritime","type":"string"},"type":"array"},"leverageScore":{"format":"double","type":"number"},"name":{"type":"string"},"role":{"description":"role: aggressor | stabilizer | swing | broker","type":"string"}},"type":"object"},"AirportNodeStatus":{"description":"AirportNodeStatus captures airport-level disruption state.","properties":{"disruptionReason":{"type":"string"},"icao":{"type":"string"},"name":{"type":"string"},"status":{"description":"status: normal | disrupted | closed","type":"string"}},"type":"object"},"AirspaceStatus":{"description":"AirspaceStatus captures FIR-level airspace state.","properties":{"airspaceId":{"type":"string"},"reason":{"type":"string"},"status":{"description":"status: open | restricted | closed","type":"string"}},"type":"object"},"BalanceDriver":{"description":"BalanceDriver is one contributor to an axis score. Links back to evidence.","properties":{"axis":{"type":"string"},"description":{"type":"string"},"evidenceIds":{"items":{"type":"string"},"type":"array"},"magnitude":{"format":"double","type":"number"},"orientation":{"description":"orientation: \"pressure\" | \"buffer\"","type":"string"}},"type":"object"},"BalanceVector":{"description":"BalanceVector is the 7-axis regional balance score with pressures/buffers\n split. See docs/internal/pro-regional-intelligence-appendix-scoring.md for\n the per-axis formulas.","properties":{"allianceCohesion":{"description":"Buffers (high = good)","format":"double","type":"number"},"buffers":{"items":{"$ref":"#/components/schemas/BalanceDriver"},"type":"array"},"capitalStress":{"format":"double","type":"number"},"coercivePressure":{"description":"Pressures (high = bad)","format":"double","type":"number"},"domesticFragility":{"format":"double","type":"number"},"energyLeverage":{"format":"double","type":"number"},"energyVulnerability":{"format":"double","type":"number"},"maritimeAccess":{"format":"double","type":"number"},"netBalance":{"description":"Derived: mean(buffers) - mean(pressures), range [-1, +1]","format":"double","type":"number"},"pressures":{"items":{"$ref":"#/components/schemas/BalanceDriver"},"type":"array"}},"type":"object"},"ByCountryEntry":{"properties":{"key":{"type":"string"},"value":{"type":"string"}},"type":"object"},"ByTypeEntry":{"properties":{"key":{"type":"string"},"value":{"format":"int32","type":"integer"}},"type":"object"},"CiiComponents":{"description":"CiiComponents represents the contributing factors to a CII score.","properties":{"ciiContribution":{"description":"CII index contribution (0-100).","format":"double","maximum":100,"minimum":0,"type":"number"},"geoConvergence":{"description":"Geographic convergence score (0-100).","format":"double","maximum":100,"minimum":0,"type":"number"},"militaryActivity":{"description":"Military activity contribution (0-100).","format":"double","maximum":100,"minimum":0,"type":"number"},"newsActivity":{"description":"News activity signal contribution (0-100).","format":"double","maximum":100,"minimum":0,"type":"number"}},"type":"object"},"CiiScore":{"description":"CiiScore represents a Composite Instability Index score for a region or country.","properties":{"combinedScore":{"description":"Combined weighted score (0-100).","format":"double","maximum":100,"minimum":0,"type":"number"},"components":{"$ref":"#/components/schemas/CiiComponents"},"computedAt":{"description":"Last computation time, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"dynamicScore":{"description":"Dynamic real-time score (0-100).","format":"double","maximum":100,"minimum":0,"type":"number"},"region":{"description":"Region or country identifier.","type":"string"},"staticBaseline":{"description":"Static baseline score (0-100).","format":"double","maximum":100,"minimum":0,"type":"number"},"trend":{"description":"TrendDirection represents the directional movement of a metric over time.\n Used in markets, GDELT tension scores, and risk assessments.","enum":["TREND_DIRECTION_UNSPECIFIED","TREND_DIRECTION_RISING","TREND_DIRECTION_STABLE","TREND_DIRECTION_FALLING"],"type":"string"}},"type":"object"},"ClassifyEventRequest":{"description":"ClassifyEventRequest specifies an event to classify using AI.","properties":{"country":{"description":"Country context (ISO 3166-1 alpha-2).","type":"string"},"description":{"description":"Event description or body text.","type":"string"},"source":{"description":"Event source (e.g., \"reuters\", \"acled\").","type":"string"},"title":{"description":"Event title or headline.","minLength":1,"type":"string"}},"required":["title"],"type":"object"},"ClassifyEventResponse":{"description":"ClassifyEventResponse contains the AI-generated event classification.","properties":{"classification":{"$ref":"#/components/schemas/EventClassification"}},"type":"object"},"CompanySignal":{"properties":{"engagement":{"$ref":"#/components/schemas/SignalEngagement"},"source":{"type":"string"},"sourceTier":{"description":"Data quality tier (1 is authoritative, 5 is low confidence).","format":"int32","type":"integer"},"strength":{"description":"Qualitative strength of the signal (e.g. \"Strong\", \"Emerging\").","type":"string"},"timestampMs":{"description":"Unix timestamp in milliseconds of the event occurrence.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"title":{"type":"string"},"type":{"description":"Classification type (e.g. \"Hiring\", \"Product Launch\", \"Expansion\").","type":"string"},"url":{"type":"string"}},"type":"object"},"ComputeEnergyShockScenarioRequest":{"properties":{"chokepointId":{"type":"string"},"countryCode":{"type":"string"},"disruptionPct":{"format":"int32","type":"integer"},"fuelMode":{"type":"string"}},"type":"object"},"ComputeEnergyShockScenarioResponse":{"properties":{"assessment":{"type":"string"},"chokepointConfidence":{"type":"string"},"chokepointId":{"type":"string"},"comtradeCoverage":{"type":"boolean"},"countryCode":{"type":"string"},"coverageLevel":{"type":"string"},"crudeLossKbd":{"format":"double","type":"number"},"dataAvailable":{"type":"boolean"},"degraded":{"type":"boolean"},"disruptionPct":{"format":"int32","type":"integer"},"effectiveCoverDays":{"format":"int32","type":"integer"},"gasImpact":{"$ref":"#/components/schemas/GasImpact"},"gulfCrudeShare":{"format":"double","type":"number"},"ieaStocksCoverage":{"type":"boolean"},"jodiOilCoverage":{"description":"v2 fields","type":"boolean"},"limitations":{"items":{"type":"string"},"type":"array"},"liveFlowRatio":{"format":"double","type":"number"},"portwatchCoverage":{"type":"boolean"},"products":{"items":{"$ref":"#/components/schemas/ProductImpact"},"type":"array"}},"type":"object"},"CountryPortActivityResponse":{"properties":{"available":{"type":"boolean"},"fetchedAt":{"type":"string"},"ports":{"items":{"$ref":"#/components/schemas/PortActivityEntry"},"type":"array"}},"type":"object"},"CrossSourceSignal":{"description":"CrossSourceSignal represents a single detected cross-domain signal event.","properties":{"contributingTypes":{"items":{"description":"For COMPOSITE_ESCALATION: list of contributing signal type names.","type":"string"},"type":"array"},"detectedAt":{"description":"Detection timestamp (Unix epoch milliseconds).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"id":{"description":"Unique signal identifier.","type":"string"},"severity":{"description":"CrossSourceSignalSeverity indicates the urgency tier of a detected signal.","enum":["CROSS_SOURCE_SIGNAL_SEVERITY_UNSPECIFIED","CROSS_SOURCE_SIGNAL_SEVERITY_LOW","CROSS_SOURCE_SIGNAL_SEVERITY_MEDIUM","CROSS_SOURCE_SIGNAL_SEVERITY_HIGH","CROSS_SOURCE_SIGNAL_SEVERITY_CRITICAL"],"type":"string"},"severityScore":{"description":"Raw severity score used for ranking (higher = more severe).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"double","type":"number"},"signalCount":{"description":"For COMPOSITE_ESCALATION: number of co-firing signals in theater.","format":"int32","type":"integer"},"summary":{"description":"Human-readable summary of the signal.","type":"string"},"theater":{"description":"Theater / geographic context (e.g. \"Eastern Europe\", \"Red Sea\", \"Global Markets\").","type":"string"},"type":{"description":"CrossSourceSignalType enumerates all monitored cross-domain signal categories.","enum":["CROSS_SOURCE_SIGNAL_TYPE_UNSPECIFIED","CROSS_SOURCE_SIGNAL_TYPE_COMPOSITE_ESCALATION","CROSS_SOURCE_SIGNAL_TYPE_THERMAL_SPIKE","CROSS_SOURCE_SIGNAL_TYPE_GPS_JAMMING","CROSS_SOURCE_SIGNAL_TYPE_MILITARY_FLIGHT_SURGE","CROSS_SOURCE_SIGNAL_TYPE_UNREST_SURGE","CROSS_SOURCE_SIGNAL_TYPE_OREF_ALERT_CLUSTER","CROSS_SOURCE_SIGNAL_TYPE_VIX_SPIKE","CROSS_SOURCE_SIGNAL_TYPE_COMMODITY_SHOCK","CROSS_SOURCE_SIGNAL_TYPE_CYBER_ESCALATION","CROSS_SOURCE_SIGNAL_TYPE_SHIPPING_DISRUPTION","CROSS_SOURCE_SIGNAL_TYPE_SANCTIONS_SURGE","CROSS_SOURCE_SIGNAL_TYPE_EARTHQUAKE_SIGNIFICANT","CROSS_SOURCE_SIGNAL_TYPE_RADIATION_ANOMALY","CROSS_SOURCE_SIGNAL_TYPE_INFRASTRUCTURE_OUTAGE","CROSS_SOURCE_SIGNAL_TYPE_WILDFIRE_ESCALATION","CROSS_SOURCE_SIGNAL_TYPE_DISPLACEMENT_SURGE","CROSS_SOURCE_SIGNAL_TYPE_FORECAST_DETERIORATION","CROSS_SOURCE_SIGNAL_TYPE_MARKET_STRESS","CROSS_SOURCE_SIGNAL_TYPE_WEATHER_EXTREME","CROSS_SOURCE_SIGNAL_TYPE_MEDIA_TONE_DETERIORATION","CROSS_SOURCE_SIGNAL_TYPE_RISK_SCORE_SPIKE"],"type":"string"}},"type":"object"},"DeductSituationRequest":{"properties":{"framework":{"description":"Optional analytical framework instructions.","type":"string"},"geoContext":{"type":"string"},"query":{"type":"string"}},"type":"object"},"DeductSituationResponse":{"properties":{"analysis":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"}},"type":"object"},"EnrichedCompany":{"properties":{"description":{"type":"string"},"domain":{"type":"string"},"founded":{"format":"int32","type":"integer"},"location":{"type":"string"},"name":{"type":"string"},"website":{"type":"string"}},"type":"object"},"EnrichedGithub":{"properties":{"avatarUrl":{"type":"string"},"followers":{"format":"int32","type":"integer"},"publicRepos":{"format":"int32","type":"integer"}},"type":"object"},"Error":{"description":"Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.","properties":{"message":{"description":"Error message (e.g., 'user not found', 'database connection failed')","type":"string"}},"type":"object"},"EventClassification":{"description":"EventClassification represents an AI-generated classification of a real-world event.","properties":{"analysis":{"description":"Brief AI-generated analysis.","type":"string"},"category":{"description":"Event category (e.g., \"military\", \"economic\", \"social\").","type":"string"},"confidence":{"description":"Classification confidence (0.0 to 1.0).","format":"double","maximum":1,"minimum":0,"type":"number"},"entities":{"items":{"description":"Related entities identified.","type":"string"},"type":"array"},"severity":{"description":"SeverityLevel represents a three-tier severity classification used across domains.\n Maps to existing TS unions: 'low' | 'medium' | 'high'.","enum":["SEVERITY_LEVEL_UNSPECIFIED","SEVERITY_LEVEL_LOW","SEVERITY_LEVEL_MEDIUM","SEVERITY_LEVEL_HIGH"],"type":"string"},"subcategory":{"description":"Event subcategory.","type":"string"}},"type":"object"},"EvidenceItem":{"description":"EvidenceItem is one upstream data point linked from balance drivers,\n narrative sections, and triggers.","properties":{"confidence":{"format":"double","type":"number"},"corridor":{"type":"string"},"id":{"type":"string"},"observedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"source":{"description":"source: AIS | ADSB | GDELT | ACLED | Yahoo | OREF | NOTAM | ...","type":"string"},"summary":{"type":"string"},"theater":{"type":"string"},"type":{"description":"type: vessel_track | flight_surge | news_headline | cii_spike |\n chokepoint_status | sanctions_move | market_signal | mobility_disruption","type":"string"}},"type":"object"},"FieldViolation":{"description":"FieldViolation describes a single validation error for a specific field.","properties":{"description":{"description":"Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')","type":"string"},"field":{"description":"The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')","type":"string"}},"required":["field","description"],"type":"object"},"FlightCorridorStress":{"description":"FlightCorridorStress captures per-corridor reroute intensity.","properties":{"corridor":{"type":"string"},"reroutedFlights24h":{"format":"int32","type":"integer"},"stressLevel":{"format":"double","type":"number"}},"type":"object"},"GasImpact":{"properties":{"assessment":{"type":"string"},"dataAvailable":{"type":"boolean"},"dataSource":{"type":"string"},"deficitPct":{"format":"double","type":"number"},"lngDisruptionTj":{"format":"double","type":"number"},"lngImportsTj":{"format":"double","type":"number"},"lngShareOfImports":{"format":"double","type":"number"},"storage":{"$ref":"#/components/schemas/GasStorageBuffer"},"totalDemandTj":{"format":"double","type":"number"}},"type":"object"},"GasStorageBuffer":{"properties":{"bufferDays":{"format":"double","type":"number"},"date":{"type":"string"},"fillPct":{"format":"double","type":"number"},"gasTwh":{"format":"double","type":"number"},"scope":{"type":"string"},"trend":{"type":"string"}},"type":"object"},"GdeltArticle":{"description":"GdeltArticle represents a single article from the GDELT document API.","properties":{"date":{"description":"Publication date string.","type":"string"},"image":{"description":"Article image URL.","type":"string"},"language":{"description":"Article language code.","type":"string"},"source":{"description":"Source domain name.","type":"string"},"title":{"description":"Article headline.","type":"string"},"tone":{"description":"GDELT tone score (negative = negative tone, positive = positive tone).","format":"double","type":"number"},"url":{"description":"Article URL.","type":"string"}},"type":"object"},"GdeltTensionPair":{"description":"GdeltTensionPair represents a bilateral tension score between two countries from GDELT.","properties":{"changePercent":{"description":"Percentage change from previous period.","format":"double","type":"number"},"countries":{"items":{"description":"Country pair (ISO 3166-1 alpha-2 codes).","type":"string"},"type":"array"},"id":{"description":"Pair identifier.","type":"string"},"label":{"description":"Human-readable label (e.g., \"US-China\").","type":"string"},"region":{"description":"Geographic region.","type":"string"},"score":{"description":"Tension score (0-100).","format":"double","maximum":100,"minimum":0,"type":"number"},"trend":{"description":"TrendDirection represents the directional movement of a metric over time.\n Used in markets, GDELT tension scores, and risk assessments.","enum":["TREND_DIRECTION_UNSPECIFIED","TREND_DIRECTION_RISING","TREND_DIRECTION_STABLE","TREND_DIRECTION_FALLING"],"type":"string"}},"type":"object"},"GdeltTimelinePoint":{"description":"GdeltTimelinePoint is a single data point in a tone or volume timeline.","properties":{"date":{"description":"Date string from GDELT (e.g. \"20240101T000000\").","type":"string"},"value":{"description":"Tone or volume value at this point.","format":"double","type":"number"}},"type":"object"},"GetCompanyEnrichmentRequest":{"description":"Request to fetch enrichment data for a company.\n Requires either domain (e.g. \"github.com\") or name (e.g. \"GitHub\").","properties":{"domain":{"type":"string"},"name":{"type":"string"}},"type":"object"},"GetCompanyEnrichmentResponse":{"description":"Aggregated company data from multiple public sources.","properties":{"company":{"$ref":"#/components/schemas/EnrichedCompany"},"enrichedAtMs":{"description":"Unix timestamp in milliseconds when this data was fetched.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"github":{"$ref":"#/components/schemas/EnrichedGithub"},"hackerNewsMentions":{"items":{"$ref":"#/components/schemas/HNMention"},"type":"array"},"secFilings":{"$ref":"#/components/schemas/SecFilings"},"sources":{"items":{"description":"List of sources successfully reached (e.g. \"github\", \"sec_edgar\").","type":"string"},"type":"array"},"techStack":{"items":{"$ref":"#/components/schemas/TechStackItem"},"type":"array"}},"type":"object"},"GetCountryEnergyProfileRequest":{"properties":{"countryCode":{"type":"string"}},"type":"object"},"GetCountryEnergyProfileResponse":{"properties":{"coalShare":{"format":"double","type":"number"},"crudeImportsKbd":{"format":"double","type":"number"},"dieselDemandKbd":{"format":"double","type":"number"},"dieselImportsKbd":{"format":"double","type":"number"},"electricityAvailable":{"description":"Phase 2 — EU electricity (ENTSO-E countries: DE FR ES IT NL BE PL PT GB NO SE)\n US electricity is stored by EIA balancing area, not ISO2 — not available here","type":"boolean"},"electricityDate":{"type":"string"},"electricityPriceMwh":{"format":"double","type":"number"},"electricitySource":{"type":"string"},"emberAvailable":{"type":"boolean"},"emberCoalShare":{"format":"double","type":"number"},"emberDataMonth":{"type":"string"},"emberDemandTwh":{"format":"double","type":"number"},"emberFossilShare":{"description":"Phase 3 — Ember monthly electricity mix","format":"double","type":"number"},"emberGasShare":{"format":"double","type":"number"},"emberNuclearShare":{"format":"double","type":"number"},"emberRenewShare":{"format":"double","type":"number"},"gasLngImportsTj":{"format":"double","type":"number"},"gasLngShare":{"format":"double","type":"number"},"gasPipeImportsTj":{"format":"double","type":"number"},"gasShare":{"format":"double","type":"number"},"gasStorageAvailable":{"description":"Phase 2 — EU gas storage","type":"boolean"},"gasStorageChange1d":{"format":"double","type":"number"},"gasStorageDate":{"type":"string"},"gasStorageFillPct":{"format":"double","type":"number"},"gasStorageTrend":{"type":"string"},"gasTotalDemandTj":{"format":"double","type":"number"},"gasolineDemandKbd":{"format":"double","type":"number"},"gasolineImportsKbd":{"format":"double","type":"number"},"hydroShare":{"format":"double","type":"number"},"ieaBelowObligation":{"type":"boolean"},"ieaDaysOfCover":{"format":"int32","type":"integer"},"ieaNetExporter":{"type":"boolean"},"ieaStocksAvailable":{"description":"Phase 2.5 — IEA oil stocks (~31 IEA members)","type":"boolean"},"ieaStocksDataMonth":{"type":"string"},"importShare":{"format":"double","type":"number"},"jetDemandKbd":{"format":"double","type":"number"},"jetImportsKbd":{"format":"double","type":"number"},"jodiGasAvailable":{"description":"Phase 2.5 — JODI Gas","type":"boolean"},"jodiGasDataMonth":{"type":"string"},"jodiOilAvailable":{"description":"Phase 2.5 — JODI Oil (~90+ countries)","type":"boolean"},"jodiOilDataMonth":{"type":"string"},"lpgDemandKbd":{"format":"double","type":"number"},"lpgImportsKbd":{"format":"double","type":"number"},"mixAvailable":{"description":"Phase 1 — OWID structural mix (~200 countries)","type":"boolean"},"mixYear":{"format":"int32","type":"integer"},"nuclearShare":{"format":"double","type":"number"},"oilShare":{"format":"double","type":"number"},"renewShare":{"format":"double","type":"number"},"solarShare":{"format":"double","type":"number"},"sprAsOf":{"type":"string"},"sprAvailable":{"type":"boolean"},"sprCapacityMb":{"format":"double","type":"number"},"sprIeaMember":{"type":"boolean"},"sprNote":{"type":"string"},"sprOperator":{"type":"string"},"sprRegime":{"description":"Phase 4 — SPR policy classification","type":"string"},"sprSource":{"type":"string"},"sprStockholdingModel":{"type":"string"},"windShare":{"format":"double","type":"number"}},"type":"object"},"GetCountryFactsRequest":{"properties":{"countryCode":{"pattern":"^[A-Z]{2}$","type":"string"}},"required":["countryCode"],"type":"object"},"GetCountryFactsResponse":{"properties":{"areaSqKm":{"format":"double","type":"number"},"capital":{"type":"string"},"countryName":{"type":"string"},"currencies":{"items":{"type":"string"},"type":"array"},"headOfState":{"type":"string"},"headOfStateTitle":{"type":"string"},"languages":{"items":{"type":"string"},"type":"array"},"population":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"wikipediaSummary":{"type":"string"},"wikipediaThumbnailUrl":{"type":"string"}},"type":"object"},"GetCountryIntelBriefRequest":{"description":"GetCountryIntelBriefRequest specifies which country to generate a brief for.","properties":{"countryCode":{"description":"ISO 3166-1 alpha-2 country code.","pattern":"^[A-Z]{2}$","type":"string"},"framework":{"description":"Optional analytical framework instructions to append to system prompt. Max 2000 chars enforced at handler level.","type":"string"}},"required":["countryCode"],"type":"object"},"GetCountryIntelBriefResponse":{"description":"GetCountryIntelBriefResponse contains an AI-generated intelligence brief for a country.","properties":{"brief":{"description":"AI-generated intelligence brief text.","type":"string"},"countryCode":{"description":"ISO 3166-1 alpha-2 country code.","type":"string"},"countryName":{"description":"Country name.","type":"string"},"generatedAt":{"description":"Brief generation time, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"model":{"description":"AI model used for generation.","type":"string"}},"type":"object"},"GetCountryPortActivityRequest":{"properties":{"countryCode":{"type":"string"}},"type":"object"},"GetCountryRiskRequest":{"description":"GetCountryRiskRequest specifies which country to retrieve risk intelligence for.","properties":{"countryCode":{"description":"ISO 3166-1 alpha-2 country code.","pattern":"^[A-Z]{2}$","type":"string"}},"required":["countryCode"],"type":"object"},"GetCountryRiskResponse":{"description":"GetCountryRiskResponse contains composite risk intelligence for a specific country.","properties":{"advisoryLevel":{"description":"Travel advisory level from government sources (e.g. \"do-not-travel\", \"reconsider\", \"caution\"). Empty if none.","type":"string"},"cii":{"$ref":"#/components/schemas/CiiScore"},"countryCode":{"description":"ISO 3166-1 alpha-2 country code.","type":"string"},"countryName":{"description":"Country name.","type":"string"},"fetchedAt":{"description":"Data freshness timestamp derived from CII computedAt, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"sanctionsActive":{"description":"Whether this country has active OFAC sanctions designations.","type":"boolean"},"sanctionsCount":{"description":"Count of sanctioned entities associated with this country.","format":"int32","type":"integer"},"upstreamUnavailable":{"description":"True when all upstream Redis keys were unavailable. Signals CDN cache bypass.","type":"boolean"}},"type":"object"},"GetGdeltTopicTimelineRequest":{"description":"GetGdeltTopicTimelineRequest retrieves tone and volume timelines for a GDELT intel topic.","properties":{"topic":{"description":"Topic ID (military, cyber, nuclear, sanctions, intelligence, maritime).","type":"string"}},"type":"object"},"GetGdeltTopicTimelineResponse":{"description":"GetGdeltTopicTimelineResponse contains tone and volume timelines for a topic.","properties":{"error":{"description":"Error message if fetch failed.","type":"string"},"fetchedAt":{"description":"ISO timestamp when this data was fetched.","type":"string"},"tone":{"items":{"$ref":"#/components/schemas/GdeltTimelinePoint"},"type":"array"},"topic":{"description":"Topic ID.","type":"string"},"vol":{"items":{"$ref":"#/components/schemas/GdeltTimelinePoint"},"type":"array"}},"type":"object"},"GetPizzintStatusRequest":{"description":"GetPizzintStatusRequest specifies parameters for retrieving PizzINT and GDELT data.","properties":{"includeGdelt":{"description":"Whether to include GDELT tension pairs in the response.","type":"boolean"}},"type":"object"},"GetPizzintStatusResponse":{"description":"GetPizzintStatusResponse contains Pentagon Pizza Index and GDELT tension data.","properties":{"pizzint":{"$ref":"#/components/schemas/PizzintStatus"},"tensionPairs":{"items":{"$ref":"#/components/schemas/GdeltTensionPair"},"type":"array"}},"type":"object"},"GetRegimeHistoryRequest":{"description":"GetRegimeHistoryRequest asks for the recent regime transition log for a\n region. Returns newest-first. Phase 3 PR1 — see\n scripts/regional-snapshot/regime-history.mjs for the writer that\n populates the underlying Redis list on every regime change.","properties":{"limit":{"description":"Optional cap on how many entries to return. Defaults to 50 server-side\n when omitted or \u003c= 0. Hard cap enforced by the handler at 100 (= the\n writer-side LTRIM cap in regime-history.mjs).","format":"int32","maximum":100,"minimum":0,"type":"integer"},"regionId":{"description":"Display region id (e.g. \"mena\", \"east-asia\", \"europe\"). See shared/geography.js.\n Kebab-case: lowercase alphanumeric groups separated by single hyphens, no\n trailing or consecutive hyphens.","maxLength":32,"minLength":1,"pattern":"^[a-z][a-z0-9]*(-[a-z0-9]+)*$","type":"string"}},"required":["regionId"],"type":"object"},"GetRegimeHistoryResponse":{"description":"GetRegimeHistoryResponse returns the region's regime transition log\n newest-first. The list is append-only from the seed writer's perspective:\n only diffs with regime_changed set produce an entry, so this is a pure\n transition stream (no steady-state noise).","properties":{"transitions":{"items":{"$ref":"#/components/schemas/RegimeTransition"},"type":"array"}},"type":"object"},"GetRegionalSnapshotRequest":{"description":"GetRegionalSnapshotRequest asks for the latest persisted RegionalSnapshot\n for a given region. See shared/geography.ts for the canonical region ids.","properties":{"regionId":{"description":"Display region id (e.g. \"mena\", \"east-asia\", \"europe\"). See shared/geography.js.\n Kebab-case: lowercase alphanumeric groups separated by single hyphens, no\n trailing or consecutive hyphens.","maxLength":32,"minLength":1,"pattern":"^[a-z][a-z0-9]*(-[a-z0-9]+)*$","type":"string"}},"required":["regionId"],"type":"object"},"GetRegionalSnapshotResponse":{"description":"GetRegionalSnapshotResponse returns the latest RegionalSnapshot for the\n requested region. The snapshot is written by scripts/seed-regional-snapshots.mjs\n on a 6h cron; this handler only reads canonical state.","properties":{"snapshot":{"$ref":"#/components/schemas/RegionalSnapshot"}},"type":"object"},"GetRiskScoresRequest":{"description":"GetRiskScoresRequest specifies parameters for retrieving risk scores.","properties":{"region":{"description":"Optional region filter. Empty returns all tracked regions.","type":"string"}},"type":"object"},"GetRiskScoresResponse":{"description":"GetRiskScoresResponse contains composite risk scores and strategic assessments.","properties":{"ciiScores":{"items":{"$ref":"#/components/schemas/CiiScore"},"type":"array"},"strategicRisks":{"items":{"$ref":"#/components/schemas/StrategicRisk"},"type":"array"}},"type":"object"},"GetSocialVelocityRequest":{"type":"object"},"GetSocialVelocityResponse":{"properties":{"fetchedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"posts":{"items":{"$ref":"#/components/schemas/SocialVelocityPost"},"type":"array"}},"type":"object"},"GpsJamHex":{"description":"GpsJamHex represents a geographic hexagon with detected GPS interference.","properties":{"aircraftCount":{"description":"Number of unique aircraft that reported in this hex.","format":"int32","type":"integer"},"h3":{"description":"H3 index of the hexagon.","minLength":1,"type":"string"},"lat":{"description":"Centroid latitude.","format":"double","type":"number"},"level":{"description":"InterferenceLevel represents the severity of detected signal interference.","enum":["INTERFERENCE_LEVEL_UNSPECIFIED","INTERFERENCE_LEVEL_LOW","INTERFERENCE_LEVEL_MEDIUM","INTERFERENCE_LEVEL_HIGH"],"type":"string"},"lon":{"description":"Centroid longitude.","format":"double","type":"number"},"npAvg":{"description":"Average Navigation Precision (np) - lower means more interference.","format":"double","type":"number"},"sampleCount":{"description":"Number of samples in this hex.","format":"int32","type":"integer"}},"required":["h3"],"type":"object"},"GpsJamStats":{"description":"GpsJamStats contains aggregate statistics for GPS interference.","properties":{"highCount":{"format":"int32","type":"integer"},"mediumCount":{"format":"int32","type":"integer"},"totalHexes":{"format":"int32","type":"integer"}},"type":"object"},"HNMention":{"properties":{"comments":{"format":"int32","type":"integer"},"createdAtMs":{"description":"Unix timestamp in milliseconds when the post was created.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"points":{"format":"int32","type":"integer"},"title":{"type":"string"},"url":{"type":"string"}},"type":"object"},"LeverageEdge":{"description":"LeverageEdge is a directed influence relationship between two actors.","properties":{"evidenceIds":{"items":{"type":"string"},"type":"array"},"fromActorId":{"type":"string"},"mechanism":{"description":"mechanism: sanctions | naval_posture | energy_supply | alliance_shift | trade_friction","type":"string"},"strength":{"format":"double","type":"number"},"toActorId":{"type":"string"}},"type":"object"},"ListCompanySignalsRequest":{"description":"Request to discover and classify company signals (hiring, funding, tech changes).","properties":{"company":{"type":"string"},"domain":{"type":"string"}},"type":"object"},"ListCompanySignalsResponse":{"description":"Discovered company signals with classification and engagement metrics.","properties":{"company":{"type":"string"},"discoveredAtMs":{"description":"Unix timestamp in milliseconds when signals were discovered.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"domain":{"type":"string"},"signals":{"items":{"$ref":"#/components/schemas/CompanySignal"},"type":"array"},"summary":{"$ref":"#/components/schemas/SignalSummary"}},"type":"object"},"ListCrossSourceSignalsRequest":{"description":"ListCrossSourceSignalsRequest has no required parameters (returns all signals).","type":"object"},"ListCrossSourceSignalsResponse":{"description":"ListCrossSourceSignalsResponse contains ranked cross-domain signals.","properties":{"compositeCount":{"description":"Total number of composite escalation zones detected.","format":"int32","type":"integer"},"evaluatedAt":{"description":"Timestamp when the aggregator last ran (Unix epoch milliseconds).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"signals":{"items":{"$ref":"#/components/schemas/CrossSourceSignal"},"type":"array"}},"type":"object"},"ListGpsInterferenceRequest":{"description":"ListGpsInterferenceRequest specifies filters for GPS interference data.","properties":{"region":{"description":"Optional region filter.","type":"string"}},"type":"object"},"ListGpsInterferenceResponse":{"description":"ListGpsInterferenceResponse contains GPS interference data and stats.","properties":{"fetchedAt":{"description":"Data fetch time, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"hexes":{"items":{"$ref":"#/components/schemas/GpsJamHex"},"type":"array"},"source":{"description":"Data source name.","type":"string"},"stats":{"$ref":"#/components/schemas/GpsJamStats"}},"type":"object"},"ListMarketImplicationsRequest":{"properties":{"frameworkId":{"type":"string"}},"type":"object"},"ListMarketImplicationsResponse":{"properties":{"cards":{"items":{"$ref":"#/components/schemas/MarketImplicationCard"},"type":"array"},"degraded":{"type":"boolean"},"emptyReason":{"type":"string"},"generatedAt":{"type":"string"}},"type":"object"},"ListOrefAlertsRequest":{"description":"Request to fetch Israeli Red Alerts (OREF).","properties":{"mode":{"enum":["MODE_UNSPECIFIED","MODE_HISTORY"],"type":"string"}},"type":"object"},"ListOrefAlertsResponse":{"description":"OREF alert wave snapshot.","properties":{"alerts":{"items":{"$ref":"#/components/schemas/OrefAlert"},"type":"array"},"configured":{"description":"Whether the OREF bridge is configured.","type":"boolean"},"error":{"description":"Optional error message from the relay.","type":"string"},"history":{"items":{"$ref":"#/components/schemas/OrefWave"},"type":"array"},"historyCount24h":{"description":"Number of alerts in the last 24 hours.","format":"int32","type":"integer"},"timestampMs":{"description":"Unix timestamp in milliseconds of the response generation.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"totalHistoryCount":{"description":"Total alerts in the historical buffer.","format":"int32","type":"integer"}},"type":"object"},"ListSatellitesRequest":{"description":"ListSatellitesRequest specifies filters for orbital data.","properties":{"country":{"description":"Filter by country code. Empty returns all.","type":"string"}},"type":"object"},"ListSatellitesResponse":{"description":"ListSatellitesResponse contains the current orbital snapshot.","properties":{"satellites":{"items":{"$ref":"#/components/schemas/Satellite"},"type":"array"}},"type":"object"},"ListSecurityAdvisoriesRequest":{"type":"object"},"ListSecurityAdvisoriesResponse":{"properties":{"advisories":{"items":{"$ref":"#/components/schemas/SecurityAdvisoryItem"},"type":"array"},"byCountry":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"ListTelegramFeedRequest":{"description":"Request to fetch real-time Telegram OSINT feed.","properties":{"channel":{"description":"Filter by specific channel ID or name.","type":"string"},"limit":{"description":"Maximum number of messages to return (default 50).","format":"int32","type":"integer"},"topic":{"description":"Filter by topic keyword (e.g. \"military\", \"cyber\").","type":"string"}},"type":"object"},"ListTelegramFeedResponse":{"description":"OSINT feed containing validated Telegram messages.","properties":{"count":{"description":"Total count of messages in the current window.","format":"int32","type":"integer"},"enabled":{"description":"Whether the bridge is currently active.","type":"boolean"},"error":{"description":"Detailed error message if the fetch failed.","type":"string"},"messages":{"items":{"$ref":"#/components/schemas/TelegramMessage"},"type":"array"}},"type":"object"},"MarketImplicationCard":{"properties":{"confidence":{"type":"string"},"direction":{"type":"string"},"driver":{"type":"string"},"name":{"type":"string"},"narrative":{"type":"string"},"riskCaveat":{"type":"string"},"ticker":{"type":"string"},"timeframe":{"type":"string"},"title":{"type":"string"},"transmissionChain":{"items":{"$ref":"#/components/schemas/TransmissionNode"},"type":"array"}},"type":"object"},"MobilityState":{"description":"MobilityState captures airspace, flight corridor, and airport node status\n for the region. Phase 0 ships empty; Phase 2 wires the data plane.","properties":{"airports":{"items":{"$ref":"#/components/schemas/AirportNodeStatus"},"type":"array"},"airspace":{"items":{"$ref":"#/components/schemas/AirspaceStatus"},"type":"array"},"flightCorridors":{"items":{"$ref":"#/components/schemas/FlightCorridorStress"},"type":"array"},"notamClosures":{"items":{"type":"string"},"type":"array"},"rerouteIntensity":{"format":"double","type":"number"}},"type":"object"},"NarrativeSection":{"description":"NarrativeSection is one block of narrative text plus its supporting evidence.","properties":{"evidenceIds":{"items":{"type":"string"},"type":"array"},"text":{"type":"string"}},"type":"object"},"OrefAlert":{"description":"A single Red Alert event.","properties":{"cat":{"type":"string"},"data":{"items":{"type":"string"},"type":"array"},"desc":{"type":"string"},"id":{"type":"string"},"timestampMs":{"description":"Unix timestamp in milliseconds for when the alert was issued.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"title":{"type":"string"}},"type":"object"},"OrefWave":{"description":"A wave of alerts occurring at the same time.","properties":{"alerts":{"items":{"$ref":"#/components/schemas/OrefAlert"},"type":"array"},"timestampMs":{"description":"Unix timestamp in milliseconds for this wave.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"PizzintLocation":{"description":"PizzintLocation represents a single monitored pizza location near the Pentagon.","properties":{"address":{"description":"Street address.","type":"string"},"currentPopularity":{"description":"Current popularity score (0-200+).","format":"int32","type":"integer"},"dataFreshness":{"description":"DataFreshness represents how current the data is.","enum":["DATA_FRESHNESS_UNSPECIFIED","DATA_FRESHNESS_FRESH","DATA_FRESHNESS_STALE"],"type":"string"},"dataSource":{"description":"Data source identifier.","type":"string"},"isClosedNow":{"description":"Whether the location is currently closed.","type":"boolean"},"isSpike":{"description":"Whether activity constitutes a spike.","type":"boolean"},"lat":{"description":"Latitude of the location.","format":"double","type":"number"},"lng":{"description":"Longitude of the location.","format":"double","type":"number"},"name":{"description":"Location name.","type":"string"},"percentageOfUsual":{"description":"Percentage of usual activity. Zero if unavailable.","format":"int32","type":"integer"},"placeId":{"description":"Google Places ID.","type":"string"},"recordedAt":{"description":"Recording timestamp as ISO 8601 string.","type":"string"},"spikeMagnitude":{"description":"Spike magnitude above baseline. Zero if no spike.","format":"double","type":"number"}},"type":"object"},"PizzintStatus":{"description":"PizzintStatus represents the Pentagon Pizza Index status (proxy for late-night DC activity).","properties":{"activeSpikes":{"description":"Number of active spike locations.","format":"int32","type":"integer"},"aggregateActivity":{"description":"Aggregate activity score.","format":"double","type":"number"},"dataFreshness":{"description":"DataFreshness represents how current the data is.","enum":["DATA_FRESHNESS_UNSPECIFIED","DATA_FRESHNESS_FRESH","DATA_FRESHNESS_STALE"],"type":"string"},"defconLabel":{"description":"Human-readable DEFCON label.","type":"string"},"defconLevel":{"description":"DEFCON-style level (1-5).","format":"int32","maximum":5,"minimum":1,"type":"integer"},"locations":{"items":{"$ref":"#/components/schemas/PizzintLocation"},"type":"array"},"locationsMonitored":{"description":"Total monitored locations.","format":"int32","type":"integer"},"locationsOpen":{"description":"Currently open locations.","format":"int32","type":"integer"},"updatedAt":{"description":"Last data update time, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"PortActivityEntry":{"properties":{"anomalySignal":{"type":"boolean"},"exportTankerDwt":{"format":"double","type":"number"},"importTankerDwt":{"format":"double","type":"number"},"lat":{"format":"double","type":"number"},"lon":{"format":"double","type":"number"},"portId":{"type":"string"},"portName":{"type":"string"},"tankerCalls30d":{"format":"int32","type":"integer"},"trendDeltaPct":{"format":"double","type":"number"}},"type":"object"},"ProductImpact":{"properties":{"deficitPct":{"format":"double","type":"number"},"demandKbd":{"format":"double","type":"number"},"outputLossKbd":{"format":"double","type":"number"},"product":{"type":"string"}},"type":"object"},"RegimeState":{"description":"RegimeState captures the current regime label and transition history.","properties":{"label":{"description":"label: calm | stressed_equilibrium | coercive_stalemate |\n fragmentation_risk | managed_deescalation | escalation_ladder","type":"string"},"previousLabel":{"type":"string"},"transitionDriver":{"type":"string"},"transitionedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"RegimeTransition":{"description":"RegimeTransition is a single recorded regime change moment. One of these\n lands in the log each time diffRegionalSnapshot() reports regime_changed.","properties":{"label":{"description":"Current regime label (the label the region just moved INTO).","type":"string"},"previousLabel":{"description":"Previous regime label (the label the region was in before). Empty for\n the first-ever recorded transition for a region.","type":"string"},"regionId":{"type":"string"},"snapshotId":{"description":"Snapshot id that materialized this transition. Points back to the\n full snapshot via intelligence:snapshot-by-id:v1:{snapshot_id}.","type":"string"},"transitionDriver":{"description":"Free-text driver string from the seed writer (e.g. \"cross_source_surge\").\n May be empty.","type":"string"},"transitionedAt":{"description":"Unix ms when the transition was recorded. Mirrors\n snapshot.regime.transitioned_at when available.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"RegionalNarrative":{"description":"RegionalNarrative is the LLM-synthesized narrative layer. Every section\n links back to evidence via evidence_ids.","properties":{"balanceAssessment":{"$ref":"#/components/schemas/NarrativeSection"},"outlook24h":{"$ref":"#/components/schemas/NarrativeSection"},"outlook30d":{"$ref":"#/components/schemas/NarrativeSection"},"outlook7d":{"$ref":"#/components/schemas/NarrativeSection"},"situation":{"$ref":"#/components/schemas/NarrativeSection"},"watchItems":{"items":{"$ref":"#/components/schemas/NarrativeSection"},"type":"array"}},"type":"object"},"RegionalSnapshot":{"description":"RegionalSnapshot is the canonical intelligence object for one region.\n See docs/internal/pro-regional-intelligence-upgrade.md for the full spec\n and shared/regions.types.d.ts for the authoritative TypeScript contract.","properties":{"actors":{"items":{"$ref":"#/components/schemas/ActorState"},"type":"array"},"balance":{"$ref":"#/components/schemas/BalanceVector"},"evidence":{"items":{"$ref":"#/components/schemas/EvidenceItem"},"type":"array"},"generatedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"leverageEdges":{"items":{"$ref":"#/components/schemas/LeverageEdge"},"type":"array"},"meta":{"$ref":"#/components/schemas/SnapshotMeta"},"mobility":{"$ref":"#/components/schemas/MobilityState"},"narrative":{"$ref":"#/components/schemas/RegionalNarrative"},"regime":{"$ref":"#/components/schemas/RegimeState"},"regionId":{"type":"string"},"scenarioSets":{"items":{"$ref":"#/components/schemas/ScenarioSet"},"type":"array"},"transmissionPaths":{"items":{"$ref":"#/components/schemas/TransmissionPath"},"type":"array"},"triggers":{"$ref":"#/components/schemas/TriggerLadder"}},"type":"object"},"Satellite":{"description":"Satellite represents an orbital asset tracked by WorldMonitor.","properties":{"alt":{"description":"Orbital altitude in kilometers.","format":"double","type":"number"},"country":{"description":"ISO country code of the operator/owner.","type":"string"},"id":{"description":"NORAD identifier (e.g., \"25544\").","minLength":1,"type":"string"},"inclination":{"description":"Orbital inclination in degrees.","format":"double","type":"number"},"line1":{"description":"TLE line 1.","type":"string"},"line2":{"description":"TLE line 2.","type":"string"},"name":{"description":"Name of the satellite.","type":"string"},"type":{"description":"Purpose category (e.g., \"sar\", \"optical\", \"military\").","type":"string"},"velocity":{"description":"Velocity in km/s.","format":"double","type":"number"}},"required":["id"],"type":"object"},"ScenarioLane":{"description":"ScenarioLane is one outcome branch within a horizon set.","properties":{"consequences":{"items":{"type":"string"},"type":"array"},"name":{"description":"name: base | escalation | containment | fragmentation","type":"string"},"probability":{"format":"double","type":"number"},"transmissions":{"items":{"$ref":"#/components/schemas/TransmissionPath"},"type":"array"},"triggerIds":{"items":{"type":"string"},"type":"array"}},"type":"object"},"ScenarioSet":{"description":"ScenarioSet bundles scenario lanes for one time horizon. Lane probabilities\n sum to 1.0 within a set.","properties":{"horizon":{"description":"horizon: 24h | 7d | 30d","type":"string"},"lanes":{"items":{"$ref":"#/components/schemas/ScenarioLane"},"type":"array"}},"type":"object"},"SearchGdeltDocumentsRequest":{"description":"SearchGdeltDocumentsRequest specifies filters for searching GDELT news articles.","properties":{"maxRecords":{"description":"Maximum number of articles to return (1-250).","format":"int32","maximum":250,"minimum":1,"type":"integer"},"query":{"description":"Search query string.","minLength":1,"type":"string"},"sort":{"description":"Sort mode: \"DateDesc\" (default), \"ToneDesc\", \"ToneAsc\", \"HybridRel\".","type":"string"},"timespan":{"description":"Time span filter (e.g., \"15min\", \"1h\", \"24h\").","type":"string"},"toneFilter":{"description":"Tone filter appended to query (e.g., \"tone\u003e5\" for positive, \"tone\u003c-5\" for negative).\n Left empty to skip tone filtering.","type":"string"}},"required":["query"],"type":"object"},"SearchGdeltDocumentsResponse":{"description":"SearchGdeltDocumentsResponse contains GDELT article search results.","properties":{"articles":{"items":{"$ref":"#/components/schemas/GdeltArticle"},"type":"array"},"error":{"description":"Error message if the search failed.","type":"string"},"query":{"description":"Echo of the search query.","type":"string"}},"type":"object"},"SecFiling":{"properties":{"description":{"type":"string"},"fileDate":{"type":"string"},"form":{"type":"string"}},"type":"object"},"SecFilings":{"properties":{"recentFilings":{"items":{"$ref":"#/components/schemas/SecFiling"},"type":"array"},"totalFilings":{"format":"int32","type":"integer"}},"type":"object"},"SecurityAdvisoryItem":{"properties":{"country":{"type":"string"},"level":{"type":"string"},"link":{"type":"string"},"pubDate":{"type":"string"},"source":{"type":"string"},"sourceCountry":{"type":"string"},"title":{"type":"string"}},"type":"object"},"SignalEngagement":{"properties":{"comments":{"format":"int32","type":"integer"},"forks":{"format":"int32","type":"integer"},"mentions":{"format":"int32","type":"integer"},"points":{"format":"int32","type":"integer"},"stars":{"format":"int32","type":"integer"}},"type":"object"},"SignalSummary":{"properties":{"byType":{"additionalProperties":{"format":"int32","type":"integer"},"type":"object"},"signalDiversity":{"format":"int32","type":"integer"},"strongestSignal":{"$ref":"#/components/schemas/CompanySignal"},"totalSignals":{"format":"int32","type":"integer"}},"type":"object"},"SnapshotMeta":{"description":"SnapshotMeta carries the trust trail (versions, confidence, input freshness,\n narrative provenance, idempotency id).","properties":{"geographyVersion":{"type":"string"},"missingInputs":{"items":{"type":"string"},"type":"array"},"modelVersion":{"type":"string"},"narrativeModel":{"type":"string"},"narrativeProvider":{"type":"string"},"scoringVersion":{"type":"string"},"snapshotConfidence":{"format":"double","type":"number"},"snapshotId":{"type":"string"},"staleInputs":{"items":{"type":"string"},"type":"array"},"triggerReason":{"description":"trigger_reason: scheduled_6h | regime_shift | trigger_activation |\n corridor_break | leverage_shift","type":"string"},"validUntil":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"SocialVelocityPost":{"description":"SocialVelocityPost represents a trending Reddit post with velocity scoring.","properties":{"createdAt":{"description":"Unix epoch milliseconds when posted.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"id":{"description":"Reddit post ID.","type":"string"},"numComments":{"description":"Number of comments.","format":"int32","type":"integer"},"score":{"description":"Reddit score (upvotes - downvotes).","format":"int32","type":"integer"},"subreddit":{"description":"Subreddit name (without r/ prefix).","type":"string"},"title":{"description":"Post title.","type":"string"},"upvoteRatio":{"description":"Upvote ratio (0.0–1.0).","format":"double","type":"number"},"url":{"description":"Direct URL to the post.","type":"string"},"velocityScore":{"description":"Composite velocity score accounting for recency, score, and ratio.","format":"double","type":"number"}},"type":"object"},"StrategicRisk":{"description":"StrategicRisk represents a strategic risk assessment for a country or region.","properties":{"factors":{"items":{"description":"Risk factors contributing to the assessment.","type":"string"},"type":"array"},"level":{"description":"SeverityLevel represents a three-tier severity classification used across domains.\n Maps to existing TS unions: 'low' | 'medium' | 'high'.","enum":["SEVERITY_LEVEL_UNSPECIFIED","SEVERITY_LEVEL_LOW","SEVERITY_LEVEL_MEDIUM","SEVERITY_LEVEL_HIGH"],"type":"string"},"region":{"description":"Country or region identifier.","type":"string"},"score":{"description":"Risk score (0-100).","format":"double","maximum":100,"minimum":0,"type":"number"},"trend":{"description":"TrendDirection represents the directional movement of a metric over time.\n Used in markets, GDELT tension scores, and risk assessments.","enum":["TREND_DIRECTION_UNSPECIFIED","TREND_DIRECTION_RISING","TREND_DIRECTION_STABLE","TREND_DIRECTION_FALLING"],"type":"string"}},"type":"object"},"TechStackItem":{"properties":{"category":{"type":"string"},"confidence":{"format":"float","type":"number"},"name":{"type":"string"}},"type":"object"},"TelegramMessage":{"description":"Validated OSINT post from Telegram channels.","properties":{"channelId":{"description":"Identifier of the originating channel.","type":"string"},"channelName":{"description":"Human-readable name of the channel.","type":"string"},"id":{"description":"Unique message identifier.","type":"string"},"mediaUrls":{"items":{"description":"Direct links to associated media (images, videos).","type":"string"},"type":"array"},"sourceUrl":{"description":"Link to the original post on Telegram.","type":"string"},"text":{"description":"Sanitized message content.","type":"string"},"timestampMs":{"description":"Unix timestamp in milliseconds for when the message was posted.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"topic":{"description":"Auto-classified topic based on content.","type":"string"}},"type":"object"},"TransmissionNode":{"properties":{"impactType":{"type":"string"},"logic":{"type":"string"},"node":{"type":"string"}},"type":"object"},"TransmissionPath":{"description":"TransmissionPath describes how a regional event propagates to markets,\n logistics, mobility, or other domains. Typed for ranking and calibration.","properties":{"confidence":{"format":"double","type":"number"},"corridorId":{"type":"string"},"end":{"type":"string"},"impactedAssetClass":{"description":"impacted_asset_class: crude | lng | container | fx | equity | agri | metals | ...","type":"string"},"impactedRegions":{"items":{"type":"string"},"type":"array"},"latencyHours":{"format":"int32","type":"integer"},"magnitudeHigh":{"format":"double","type":"number"},"magnitudeLow":{"format":"double","type":"number"},"magnitudeUnit":{"description":"magnitude_unit: usd_bbl | pct | usd_teu | basis_points | ...","type":"string"},"mechanism":{"type":"string"},"severity":{"description":"severity: critical | high | medium | low","type":"string"},"start":{"type":"string"},"templateId":{"type":"string"},"templateVersion":{"type":"string"}},"type":"object"},"Trigger":{"description":"Trigger is a structured threshold assertion against a named metric.","properties":{"activated":{"type":"boolean"},"activatedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"description":{"type":"string"},"evidenceIds":{"items":{"type":"string"},"type":"array"},"id":{"type":"string"},"scenarioLane":{"description":"scenario_lane: base | escalation | containment | fragmentation","type":"string"},"threshold":{"$ref":"#/components/schemas/TriggerThreshold"}},"type":"object"},"TriggerLadder":{"description":"TriggerLadder buckets triggers by activation state.","properties":{"active":{"items":{"$ref":"#/components/schemas/Trigger"},"type":"array"},"dormant":{"items":{"$ref":"#/components/schemas/Trigger"},"type":"array"},"watching":{"items":{"$ref":"#/components/schemas/Trigger"},"type":"array"}},"type":"object"},"TriggerThreshold":{"description":"TriggerThreshold defines the metric/operator/value/window/baseline for\n deterministic trigger evaluation.","properties":{"baseline":{"description":"baseline: trailing_7d | trailing_30d | fixed","type":"string"},"metric":{"type":"string"},"operator":{"description":"operator: gt | gte | lt | lte | delta_gt | delta_lt","type":"string"},"value":{"format":"double","type":"number"},"windowMinutes":{"format":"int32","type":"integer"}},"type":"object"},"ValidationError":{"description":"ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.","properties":{"violations":{"description":"List of validation violations","items":{"$ref":"#/components/schemas/FieldViolation"},"type":"array"}},"required":["violations"],"type":"object"}}},"info":{"title":"IntelligenceService API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/intelligence/v1/classify-event":{"get":{"description":"ClassifyEvent analyzes a news event using AI models.","operationId":"ClassifyEvent","parameters":[{"description":"Event title or headline.","in":"query","name":"title","required":false,"schema":{"type":"string"}},{"description":"Event description or body text.","in":"query","name":"description","required":false,"schema":{"type":"string"}},{"description":"Event source (e.g., \"reuters\", \"acled\").","in":"query","name":"source","required":false,"schema":{"type":"string"}},{"description":"Country context (ISO 3166-1 alpha-2).","in":"query","name":"country","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyEventResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ClassifyEvent","tags":["IntelligenceService"]}},"/api/intelligence/v1/compute-energy-shock":{"get":{"description":"ComputeEnergyShockScenario computes on-demand product supply shock for a given country + chokepoint.","operationId":"ComputeEnergyShockScenario","parameters":[{"in":"query","name":"country_code","required":false,"schema":{"type":"string"}},{"in":"query","name":"chokepoint_id","required":false,"schema":{"type":"string"}},{"in":"query","name":"disruption_pct","required":false,"schema":{"format":"int32","type":"integer"}},{"in":"query","name":"fuel_mode","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeEnergyShockScenarioResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ComputeEnergyShockScenario","tags":["IntelligenceService"]}},"/api/intelligence/v1/deduct-situation":{"post":{"description":"DeductSituation performs broad situational analysis using LLMs.","operationId":"DeductSituation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeductSituationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeductSituationResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"DeductSituation","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-company-enrichment":{"get":{"description":"GetCompanyEnrichment aggregates company data from multiple public sources (GitHub, SEC, HN).","operationId":"GetCompanyEnrichment","parameters":[{"in":"query","name":"domain","required":false,"schema":{"type":"string"}},{"in":"query","name":"name","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCompanyEnrichmentResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetCompanyEnrichment","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-country-energy-profile":{"get":{"description":"GetCountryEnergyProfile aggregates Phase 1/2/2.5 energy data per country.","operationId":"GetCountryEnergyProfile","parameters":[{"in":"query","name":"country_code","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCountryEnergyProfileResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetCountryEnergyProfile","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-country-facts":{"get":{"description":"GetCountryFacts retrieves factual country data from RestCountries and Wikipedia.","operationId":"GetCountryFacts","parameters":[{"in":"query","name":"country_code","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCountryFactsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetCountryFacts","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-country-intel-brief":{"get":{"description":"GetCountryIntelBrief generates a strategic brief for a specific country.","operationId":"GetCountryIntelBrief","parameters":[{"description":"ISO 3166-1 alpha-2 country code.","in":"query","name":"country_code","required":false,"schema":{"type":"string"}},{"description":"Optional analytical framework instructions to append to system prompt. Max 2000 chars enforced at handler level.","in":"query","name":"framework","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCountryIntelBriefResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetCountryIntelBrief","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-country-port-activity":{"get":{"description":"GetCountryPortActivity returns port-level tanker traffic and trade volumes for a country.","operationId":"GetCountryPortActivity","parameters":[{"in":"query","name":"country_code","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryPortActivityResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetCountryPortActivity","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-country-risk":{"get":{"description":"GetCountryRisk retrieves composite risk intelligence for a specific country.","operationId":"GetCountryRisk","parameters":[{"description":"ISO 3166-1 alpha-2 country code.","in":"query","name":"country_code","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCountryRiskResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetCountryRisk","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-gdelt-topic-timeline":{"get":{"description":"GetGdeltTopicTimeline retrieves tone and volume timelines for a GDELT intel topic.","operationId":"GetGdeltTopicTimeline","parameters":[{"description":"Topic ID (military, cyber, nuclear, sanctions, intelligence, maritime).","in":"query","name":"topic","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetGdeltTopicTimelineResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetGdeltTopicTimeline","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-pizzint-status":{"get":{"description":"GetPizzintStatus retrieves Pentagon Pizza Index and GDELT tension data.","operationId":"GetPizzintStatus","parameters":[{"description":"Whether to include GDELT tension pairs in the response.","in":"query","name":"include_gdelt","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPizzintStatusResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetPizzintStatus","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-regime-history":{"get":{"description":"GetRegimeHistory returns the region's regime transition log newest-first.\n Entries are append-only from the seed writer, recorded only when\n diffRegionalSnapshot reports regime_changed. Premium-gated.","operationId":"GetRegimeHistory","parameters":[{"description":"Display region id (e.g. \"mena\", \"east-asia\", \"europe\"). See shared/geography.js.\n Kebab-case: lowercase alphanumeric groups separated by single hyphens, no\n trailing or consecutive hyphens.","in":"query","name":"region_id","required":false,"schema":{"type":"string"}},{"description":"Optional cap on how many entries to return. Defaults to 50 server-side\n when omitted or \u003c= 0. Hard cap enforced by the handler at 100 (= the\n writer-side LTRIM cap in regime-history.mjs).","in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRegimeHistoryResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetRegimeHistory","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-regional-snapshot":{"get":{"description":"GetRegionalSnapshot returns the latest persisted RegionalSnapshot for a\n region. The snapshot is written every 6h by scripts/seed-regional-snapshots.mjs;\n this handler only reads canonical state. Premium-gated.","operationId":"GetRegionalSnapshot","parameters":[{"description":"Display region id (e.g. \"mena\", \"east-asia\", \"europe\"). See shared/geography.js.\n Kebab-case: lowercase alphanumeric groups separated by single hyphens, no\n trailing or consecutive hyphens.","in":"query","name":"region_id","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRegionalSnapshotResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetRegionalSnapshot","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-risk-scores":{"get":{"description":"GetRiskScores retrieves composite risk scores and strategic assessments.","operationId":"GetRiskScores","parameters":[{"description":"Optional region filter. Empty returns all tracked regions.","in":"query","name":"region","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRiskScoresResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetRiskScores","tags":["IntelligenceService"]}},"/api/intelligence/v1/get-social-velocity":{"get":{"description":"GetSocialVelocity returns trending Reddit posts from r/worldnews and r/geopolitics ranked by velocity.","operationId":"GetSocialVelocity","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSocialVelocityResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetSocialVelocity","tags":["IntelligenceService"]}},"/api/intelligence/v1/list-company-signals":{"get":{"description":"ListCompanySignals discovers activity signals for a company from public sources.","operationId":"ListCompanySignals","parameters":[{"in":"query","name":"company","required":false,"schema":{"type":"string"}},{"in":"query","name":"domain","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListCompanySignalsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListCompanySignals","tags":["IntelligenceService"]}},"/api/intelligence/v1/list-cross-source-signals":{"get":{"description":"ListCrossSourceSignals returns cross-domain signals ranked by severity with composite escalation detection.","operationId":"ListCrossSourceSignals","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListCrossSourceSignalsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListCrossSourceSignals","tags":["IntelligenceService"]}},"/api/intelligence/v1/list-gps-interference":{"get":{"description":"ListGpsInterference retrieves detected GPS/GNSS interference data (jamming).","operationId":"ListGpsInterference","parameters":[{"description":"Optional region filter.","in":"query","name":"region","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGpsInterferenceResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListGpsInterference","tags":["IntelligenceService"]}},"/api/intelligence/v1/list-market-implications":{"get":{"description":"ListMarketImplications returns AI-generated trade-implication cards from live world state.","operationId":"ListMarketImplications","parameters":[{"in":"query","name":"frameworkId","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMarketImplicationsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListMarketImplications","tags":["IntelligenceService"]}},"/api/intelligence/v1/list-oref-alerts":{"get":{"description":"ListOrefAlerts retrieves Israeli Home Front Command alerts (Red Alerts).","operationId":"ListOrefAlerts","parameters":[{"description":"Mode selection. MODE_UNSPECIFIED defaults to active alerts.","in":"query","name":"mode","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListOrefAlertsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListOrefAlerts","tags":["IntelligenceService"]}},"/api/intelligence/v1/list-satellites":{"get":{"description":"ListSatellites retrieves current orbital positions and metadata.","operationId":"ListSatellites","parameters":[{"description":"Filter by country code. Empty returns all.","in":"query","name":"country","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSatellitesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListSatellites","tags":["IntelligenceService"]}},"/api/intelligence/v1/list-security-advisories":{"get":{"description":"ListSecurityAdvisories retrieves pre-seeded travel and health advisories.","operationId":"ListSecurityAdvisories","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSecurityAdvisoriesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListSecurityAdvisories","tags":["IntelligenceService"]}},"/api/intelligence/v1/list-telegram-feed":{"get":{"description":"ListTelegramFeed retrieves real-time OSINT messages from monitored Telegram channels.","operationId":"ListTelegramFeed","parameters":[{"description":"Maximum number of messages to return (default 50).","in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Filter by topic keyword (e.g. \"military\", \"cyber\").","in":"query","name":"topic","required":false,"schema":{"type":"string"}},{"description":"Filter by specific channel ID or name.","in":"query","name":"channel","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTelegramFeedResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListTelegramFeed","tags":["IntelligenceService"]}},"/api/intelligence/v1/search-gdelt-documents":{"get":{"description":"SearchGdeltDocuments searches the GDELT GKG API for relevant documentation.","operationId":"SearchGdeltDocuments","parameters":[{"description":"Search query string.","in":"query","name":"query","required":false,"schema":{"type":"string"}},{"description":"Maximum number of articles to return (1-250).","in":"query","name":"max_records","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Time span filter (e.g., \"15min\", \"1h\", \"24h\").","in":"query","name":"timespan","required":false,"schema":{"type":"string"}},{"description":"Tone filter appended to query (e.g., \"tone\u003e5\" for positive, \"tone\u003c-5\" for negative).\n Left empty to skip tone filtering.","in":"query","name":"tone_filter","required":false,"schema":{"type":"string"}},{"description":"Sort mode: \"DateDesc\" (default), \"ToneDesc\", \"ToneAsc\", \"HybridRel\".","in":"query","name":"sort","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchGdeltDocumentsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"SearchGdeltDocuments","tags":["IntelligenceService"]}}}} |