eliott/worldmonitor
1
0
Fork 0
mirror of https://github.com/koala73/worldmonitor.git synced 2026-04-25 17:14:57 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
worldmonitor/docs/api/IntelligenceService.openapi.json
Elie Habib e070a97c3d Phase 3 PR2: Weekly regional briefs (LLM seeder + RPC) (#2989) 
* feat(intelligence): weekly regional briefs (Phase 3 PR2)

Phase 3 PR2 of the Regional Intelligence Model. Adds LLM-powered
weekly intelligence briefs per region, completing the core feature set.

## New seeder: scripts/seed-regional-briefs.mjs

Standalone weekly cron script (not part of the 6h derived-signals bundle).
For each non-global region:
  1. Read the latest snapshot via two-hop Redis read
  2. Read recent regime transitions from the history log (#2981)
  3. Call the LLM once per region with regime trajectory + balance +
     triggers + narrative context
  4. Write structured brief to intelligence:regional-briefs:v1:weekly:{region}
     with 8-day TTL (survives one missed weekly run)

Reuses the same injectable-callLlm + parse-validation + provider-chain
pattern from narrative.mjs and weekly-brief.mjs.

## New module: scripts/regional-snapshot/weekly-brief.mjs

  generateWeeklyBrief(region, snapshot, transitions, opts?)
    -> { region_id, generated_at, period_start, period_end,
         situation_recap, regime_trajectory, key_developments[],
         risk_outlook, provider, model }

  buildBriefPrompt()    — pure prompt builder
  parseBriefJson()      — JSON parser with prose-extraction fallback
  emptyBrief()          — canonical empty shape

Global region is skipped. Provider chain: Groq -> OpenRouter. Validate
callback ensures only parseable responses pass (narrative.mjs PR #2960
review fix pattern).

## Proto + RPC: GetRegionalBrief

  proto/worldmonitor/intelligence/v1/get_regional_brief.proto

  - GetRegionalBriefRequest { region_id }
  - GetRegionalBriefResponse { brief: RegionalBrief }
  - RegionalBrief { region_id, generated_at, period_start, period_end,
                    situation_recap, regime_trajectory,
                    key_developments[], risk_outlook, provider, model }

## Server handler

  server/worldmonitor/intelligence/v1/get-regional-brief.ts

Simple getCachedJson read + adaptBrief snake->camel adapter.
Returns upstreamUnavailable: true on Redis failure so the gateway
skips caching (matching the get-regime-history pattern from #2981).

## Premium gating + cache tier

  src/shared/premium-paths.ts + server/gateway.ts RPC_CACHE_TIER

## Tests — 27 new unit tests

  buildBriefPrompt (5): region/balance/transitions/narrative rendered,
                        empty transitions handled, missing fields tolerated
  parseBriefJson (5): valid JSON, garbage, all-empty, cap at 5, prose extraction
  generateWeeklyBrief (6): success, global skip, LLM fail, garbage, exception,
                           period_start/end delta
  emptyBrief (2): region_id + empty fields
  handler (4): key prefix, adapter export, upstreamUnavailable, registration
  security (2): premium path + cache tier
  proto (3): RPC declared, import wired, RegionalBrief fields

## Verification

- npm run test:data: 4651/4651 pass
- npm run typecheck + typecheck:api: clean
- biome lint: clean

* fix(intelligence): address 3 review findings on #2989

P2 #1 — no consumer surface for GetRegionalBrief

Acknowledged. The consumer is the RegionalIntelligenceBoard panel,
which will call GetRegionalBrief and render a weekly brief block.
This wiring is Phase 3 PR3 (UI) scope — the RPC + Redis key are the
delivery mechanism, not the end surface. No code change in this commit;
the RPC is ready for the panel to consume.

P2 #2 — readRecentTransitions collapses failure to []

readRecentTransitions returned [] on Redis/network failure, which is
indistinguishable from a genuinely quiet week. The LLM then generates
a brief claiming "no regime transitions" when in reality the upstream
is down — fabricating false input.

Fix: return null on failure. The seeder skips the region with a clear
log message when transitions is null, so the brief is never written
with unreliable input. Empty array [] now only means genuinely no
transitions in the 7-day window.

P2 #3 — parseBriefJson accepts briefs the seeder rejects

parseBriefJson treated non-empty key_developments as valid even if
situation_recap was empty. The seeder gate only writes when
brief.situation_recap is truthy. That mismatch means the validator
pass + provider-fallback logic could accept a response that the seeder
then silently drops.

Fix: require situation_recap in parseBriefJson for valid=true, matching
the seeder gate. Now both checks agree on what constitutes a usable
brief, and the provider-fallback chain correctly falls through when
a provider returns a brief with developments but no recap.

* fix(intelligence): TTL path-segment fix + seed-meta always-write (Greptile P1+P2 on #2989)

P1 — TTL silently not applied (briefs never expire)

Upstash REST ignores query-string SET options (?EX=N). The correct
form is path-segment: /set/{key}/{value}/EX/{seconds}. Without this
fix every brief persists indefinitely and Redis storage grows
unboundedly across weekly runs.

P2 — seed-meta not written when all regions skipped

writeExtraKeyWithMeta was gated on generated > 0. If every region
was skipped (no snapshot yet, or LLM failed), seed-meta was never
written, making the seeder indistinguishable from "never ran" in
health tooling. Now writes seed-meta whenever failed === 0,
carrying regionsSkipped count.

P2 #3 (validate gate) — already fixed in previous commit (parseBriefJson
now requires situation_recap for valid=true).

* fix(intelligence): register regional-briefs in health.js SEED_META + STANDALONE_KEYS (review P2 on #2989)

* fix(intelligence): register regional-briefs in api/seed-health.js (review P2 on #2989)

* fix(intelligence): raise brief TTL to 15 days to cover missed weekly cycle (review P2 on #2989)

* fix(intelligence): distinguish missing-key from Redis-error + coverage-gated health (review P2s on #2989)

P2 #1 — false upstreamUnavailable before first seed

getCachedJson returns null for both "key missing" and "Redis failed",
so the handler was advertising an outage for every region before the
first weekly seed ran. Switched to getRawJson (throws on Redis errors)
so null = genuinely missing key → clean empty 200, and thrown error =
upstream failure → upstreamUnavailable: true for gateway no-store.

P2 #2 — partial run hides coverage loss in health

The seed-meta was written with generated count even if only 1 of 7
regions produced a brief. /api/health treats any positive recordCount
as healthy, so broad regional failure was invisible to operators.

Fix: recordCount is set to 0 when generated < ceil(expectedRegions/2).
This makes /api/health report EMPTY_DATA for severely partial runs
while still writing seed-meta (so the seeder is confirmed to have run).
coverageOk flag in the summary payload lets operators drill into the
exact coverage state.

* fix(intelligence): tighten coverage gate to expectedRegions-1 (review P2 on #2989)
2026-04-12 09:56:35 +04:00

1 line
76 KiB
JSON
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{"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"},"GetRegionalBriefRequest":{"properties":{"regionId":{"maxLength":32,"minLength":1,"pattern":"^[a-z][a-z0-9]*(-[a-z0-9]+)*$","type":"string"}},"required":["regionId"],"type":"object"},"GetRegionalBriefResponse":{"properties":{"brief":{"$ref":"#/components/schemas/RegionalBrief"}},"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"},"RegionalBrief":{"description":"RegionalBrief is a weekly LLM-synthesized intelligence summary for one\n region. Written by scripts/seed-regional-briefs.mjs on a weekly cron.","properties":{"generatedAt":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"keyDevelopments":{"items":{"type":"string"},"type":"array"},"model":{"type":"string"},"periodEnd":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"periodStart":{"description":"Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"provider":{"type":"string"},"regimeTrajectory":{"type":"string"},"regionId":{"type":"string"},"riskOutlook":{"type":"string"},"situationRecap":{"type":"string"}},"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-brief":{"get":{"description":"GetRegionalBrief returns the latest weekly intelligence brief for a region.\n Written by scripts/seed-regional-briefs.mjs on a weekly cron. Premium-gated.","operationId":"GetRegionalBrief","parameters":[{"in":"query","name":"region_id","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRegionalBriefResponse"}}},"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":"GetRegionalBrief","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"]}}}}
Reference in New Issue View Git Blame Copy Permalink