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
7da202c25de0f55c797e87167031b22f2f6b9eed
worldmonitor/docs/api/IntelligenceService.openapi.yaml
Elie Habib 7da202c25d Phase 1 PR1: RegionalSnapshot proto + RPC handler (#2951) 
* feat(intelligence): add RegionalSnapshot proto definition

Defines the canonical RegionalSnapshot wire format for Phase 1 of the
Regional Intelligence Model. Mirrors the TypeScript contract in
shared/regions.types.d.ts that Phase 0 landed with.

New proto file: proto/worldmonitor/intelligence/v1/get_regional_snapshot.proto

Messages:
  - RegionalSnapshot (13 top-level fields matching the spec)
  - SnapshotMeta (11 fields including snapshot_id, narrative_provider,
    narrative_model, trigger_reason, snapshot_confidence, missing_inputs,
    stale_inputs, valid_until, versions)
  - RegimeState (label + transition history)
  - BalanceVector (7 axes: 4 pressures + 3 buffers + net_balance + decomposed
    drivers)
  - BalanceDriver (axis, magnitude, evidence_ids, orientation)
  - ActorState (leverage_score, role, domains, delta, evidence_ids)
  - LeverageEdge (actor-to-actor directed influence)
  - ScenarioSet + ScenarioLane (per-horizon distribution normalizing to 1.0)
  - TransmissionPath (typed fields: severity, confidence, latency_hours,
    magnitude range, asset class, template provenance)
  - TriggerLadder + Trigger + TriggerThreshold (structured operator/value/
    window/baseline)
  - MobilityState + AirspaceStatus + FlightCorridorStress + AirportNodeStatus
  - EvidenceItem (typed origin for the trust trail)
  - RegionalNarrative + NarrativeSection (LLM-synthesized text with
    evidence_ids on every section)

RPC: GetRegionalSnapshot(GetRegionalSnapshotRequest) -> GetRegionalSnapshotResponse
  - GET /api/intelligence/v1/get-regional-snapshot
  - region_id validated as lowercase kebab via buf.validate regex
  - No other parameters; the handler reads canonical state

Generated code committed alongside:
  - src/generated/client/worldmonitor/intelligence/v1/service_client.ts
  - src/generated/server/worldmonitor/intelligence/v1/service_server.ts
  - docs/api/IntelligenceService.openapi.{json,yaml}

The generated TypeScript types use camelCase per standard buf codegen, while
Phase 0 persists snapshots in Redis using the snake_case shape from
shared/regions.types.d.ts. The handler lands in a follow-up commit with a
localized snake_case -> camelCase adapter so Phase 0 code stays frozen.

Spec: docs/internal/pro-regional-intelligence-upgrade.md

* feat(intelligence): get-regional-snapshot RPC handler

Reads canonical persisted RegionalSnapshot for a region via the two-hop
lookup pattern established by the Phase 0 persist layer:

  1. GET intelligence:snapshot:v1:{region}:latest -> snapshot_id
  2. GET intelligence:snapshot-by-id:v1:{snapshot_id} -> full snapshot JSON

Returns empty response (snapshot omitted) when:
  - No latest pointer exists (seed has never run or unknown region)
  - Latest pointer references a pruned or TTL-expired snapshot
  - Snapshot JSON is malformed

The handler does NOT recompute on miss. One writer (the seed bundle),
canonical reads. Matches the architecture commitment in the spec.

Includes a full snake_case -> camelCase adapter so the persisted Phase 0
shape (shared/regions.types.d.ts) maps cleanly onto the camelCase proto
wire format generated by buf. The adapter is the single bridge between
the two shapes; Phase 0 code stays frozen. Adapter handles every nested
message: SnapshotMeta, RegimeState, BalanceVector (+pressures/buffers
drivers), ActorState, LeverageEdge, ScenarioSet (+lanes +transmissions),
TransmissionPath, TriggerLadder (+triggers +thresholds), MobilityState
(+airspace +flight corridors +airports), EvidenceItem, RegionalNarrative
(+5 sections +watch items).

Wiring:
  - Registered on intelligenceHandler in handler.ts
  - Added to PREMIUM_RPC_PATHS (src/shared/premium-paths.ts) so the
    gateway enforces Pro subscription or API key
  - Added to RPC_CACHE_TIER with 'slow' tier (300s browser, 1800s edge)
    matching similar premium intelligence RPCs

Not in this PR:
  - LLM narrative generator (follow-up PR2, wires into snapshot writer)
  - RegionalIntelligenceBoard panel UI (follow-up PR3)
  - ENDPOINT_ENTITLEMENTS tier-specific enforcement (PREMIUM_RPC_PATHS
    alone is the Pro gate; only stock-analysis endpoints currently use
    tier-specific enforcement)

* test(intelligence): unit tests for get-regional-snapshot adapter + structural checks

29 tests across 5 suites covering:

adaptSnapshot (18 tests): real unit tests of the snake_case -> camelCase
adapter with synthetic persisted snapshots. Covers every nested message
(SnapshotMeta, RegimeState, BalanceVector with 7 axes + decomposed drivers,
ActorState, LeverageEdge, ScenarioSet with nested lanes and transmissions,
TriggerLadder with all 3 buckets + TriggerThreshold, MobilityState with
airspace/flights/airports, EvidenceItem, RegionalNarrative with all 5
sections + watch_items). Also asserts empty-default behavior when
nested fields are missing.

Handler structural checks (8 tests): validates import of getCachedJson,
canonical key prefixes, two-hop lookup ordering, empty-response fallbacks
on missing pointer or malformed snapshot, and export signature matching
the service interface.

Registration (2 tests): confirms getRegionalSnapshot is imported and
registered on the intelligenceHandler object.

Security wiring (2 tests): confirms the endpoint is in PREMIUM_RPC_PATHS
and RPC_CACHE_TIER with 'slow' tier.

Proto definition (3 tests): confirms the RPC method declaration, region_id
validation regex, RegionalSnapshot top-level field layout, and
BalanceVector 7-axis declaration.

* fix(intelligence): address Greptile P2 review findings on #2951

Two P2 findings from Greptile on the RegionalSnapshot proto+RPC PR.

1) region_id regex permitted trailing and consecutive hyphens
   Old: ^[a-z][a-z0-9-]*$ — accepted "mena-", "east-asia-", "foo--bar"
   New: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ — strict kebab-case, every hyphen must be
   followed by at least one alphanumeric character. Regenerated openapi JSON/YAML
   via `make generate`. Test assertion updated to match.

2) RPC_CACHE_TIER entry looked like dead code for premium paths
   Greptile flagged that `isPremium` short-circuits the tier lookup to
   'slow-browser' before RPC_CACHE_TIER is consulted, so the entry is never read
   at runtime. Kept the entry because `tests/route-cache-tier.test.mjs` enforces
   a parity contract requiring every generated GET route to have an explicit
   tier. Added a NOTE comment in gateway.ts explaining the policy, and updated
   the security-wiring test with a rationale comment so future maintainers know
   the entry is intentional documentation, not a stale wire.
2026-04-11 20:19:56 +04:00

2943 lines
114 KiB
YAML
Raw 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.
openapi: 3.1.0
info:
title: IntelligenceService API
version: 1.0.0
paths:
/api/intelligence/v1/get-risk-scores:
get:
tags:
- IntelligenceService
summary: GetRiskScores
description: GetRiskScores retrieves composite risk scores and strategic assessments.
operationId: GetRiskScores
parameters:
- name: region
in: query
description: Optional region filter. Empty returns all tracked regions.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetRiskScoresResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-pizzint-status:
get:
tags:
- IntelligenceService
summary: GetPizzintStatus
description: GetPizzintStatus retrieves Pentagon Pizza Index and GDELT tension data.
operationId: GetPizzintStatus
parameters:
- name: include_gdelt
in: query
description: Whether to include GDELT tension pairs in the response.
required: false
schema:
type: boolean
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetPizzintStatusResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/classify-event:
get:
tags:
- IntelligenceService
summary: ClassifyEvent
description: ClassifyEvent analyzes a news event using AI models.
operationId: ClassifyEvent
parameters:
- name: title
in: query
description: Event title or headline.
required: false
schema:
type: string
- name: description
in: query
description: Event description or body text.
required: false
schema:
type: string
- name: source
in: query
description: Event source (e.g., "reuters", "acled").
required: false
schema:
type: string
- name: country
in: query
description: Country context (ISO 3166-1 alpha-2).
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ClassifyEventResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-country-risk:
get:
tags:
- IntelligenceService
summary: GetCountryRisk
description: GetCountryRisk retrieves composite risk intelligence for a specific country.
operationId: GetCountryRisk
parameters:
- name: country_code
in: query
description: ISO 3166-1 alpha-2 country code.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCountryRiskResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-country-intel-brief:
get:
tags:
- IntelligenceService
summary: GetCountryIntelBrief
description: GetCountryIntelBrief generates a strategic brief for a specific country.
operationId: GetCountryIntelBrief
parameters:
- name: country_code
in: query
description: ISO 3166-1 alpha-2 country code.
required: false
schema:
type: string
- name: framework
in: query
description: Optional analytical framework instructions to append to system prompt. Max 2000 chars enforced at handler level.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCountryIntelBriefResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/search-gdelt-documents:
get:
tags:
- IntelligenceService
summary: SearchGdeltDocuments
description: SearchGdeltDocuments searches the GDELT GKG API for relevant documentation.
operationId: SearchGdeltDocuments
parameters:
- name: query
in: query
description: Search query string.
required: false
schema:
type: string
- name: max_records
in: query
description: Maximum number of articles to return (1-250).
required: false
schema:
type: integer
format: int32
- name: timespan
in: query
description: Time span filter (e.g., "15min", "1h", "24h").
required: false
schema:
type: string
- name: tone_filter
in: query
description: |-
Tone filter appended to query (e.g., "tone>5" for positive, "tone<-5" for negative).
Left empty to skip tone filtering.
required: false
schema:
type: string
- name: sort
in: query
description: 'Sort mode: "DateDesc" (default), "ToneDesc", "ToneAsc", "HybridRel".'
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchGdeltDocumentsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/deduct-situation:
post:
tags:
- IntelligenceService
summary: DeductSituation
description: DeductSituation performs broad situational analysis using LLMs.
operationId: DeductSituation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeductSituationRequest'
required: true
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/DeductSituationResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/list-satellites:
get:
tags:
- IntelligenceService
summary: ListSatellites
description: ListSatellites retrieves current orbital positions and metadata.
operationId: ListSatellites
parameters:
- name: country
in: query
description: Filter by country code. Empty returns all.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListSatellitesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/list-gps-interference:
get:
tags:
- IntelligenceService
summary: ListGpsInterference
description: ListGpsInterference retrieves detected GPS/GNSS interference data (jamming).
operationId: ListGpsInterference
parameters:
- name: region
in: query
description: Optional region filter.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListGpsInterferenceResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/list-oref-alerts:
get:
tags:
- IntelligenceService
summary: ListOrefAlerts
description: ListOrefAlerts retrieves Israeli Home Front Command alerts (Red Alerts).
operationId: ListOrefAlerts
parameters:
- name: mode
in: query
description: Mode selection. MODE_UNSPECIFIED defaults to active alerts.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListOrefAlertsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/list-telegram-feed:
get:
tags:
- IntelligenceService
summary: ListTelegramFeed
description: ListTelegramFeed retrieves real-time OSINT messages from monitored Telegram channels.
operationId: ListTelegramFeed
parameters:
- name: limit
in: query
description: Maximum number of messages to return (default 50).
required: false
schema:
type: integer
format: int32
- name: topic
in: query
description: Filter by topic keyword (e.g. "military", "cyber").
required: false
schema:
type: string
- name: channel
in: query
description: Filter by specific channel ID or name.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListTelegramFeedResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-company-enrichment:
get:
tags:
- IntelligenceService
summary: GetCompanyEnrichment
description: GetCompanyEnrichment aggregates company data from multiple public sources (GitHub, SEC, HN).
operationId: GetCompanyEnrichment
parameters:
- name: domain
in: query
required: false
schema:
type: string
- name: name
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCompanyEnrichmentResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/list-company-signals:
get:
tags:
- IntelligenceService
summary: ListCompanySignals
description: ListCompanySignals discovers activity signals for a company from public sources.
operationId: ListCompanySignals
parameters:
- name: company
in: query
required: false
schema:
type: string
- name: domain
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListCompanySignalsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-country-facts:
get:
tags:
- IntelligenceService
summary: GetCountryFacts
description: GetCountryFacts retrieves factual country data from RestCountries and Wikipedia.
operationId: GetCountryFacts
parameters:
- name: country_code
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCountryFactsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/list-security-advisories:
get:
tags:
- IntelligenceService
summary: ListSecurityAdvisories
description: ListSecurityAdvisories retrieves pre-seeded travel and health advisories.
operationId: ListSecurityAdvisories
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListSecurityAdvisoriesResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-gdelt-topic-timeline:
get:
tags:
- IntelligenceService
summary: GetGdeltTopicTimeline
description: GetGdeltTopicTimeline retrieves tone and volume timelines for a GDELT intel topic.
operationId: GetGdeltTopicTimeline
parameters:
- name: topic
in: query
description: Topic ID (military, cyber, nuclear, sanctions, intelligence, maritime).
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetGdeltTopicTimelineResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/list-cross-source-signals:
get:
tags:
- IntelligenceService
summary: ListCrossSourceSignals
description: ListCrossSourceSignals returns cross-domain signals ranked by severity with composite escalation detection.
operationId: ListCrossSourceSignals
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListCrossSourceSignalsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/list-market-implications:
get:
tags:
- IntelligenceService
summary: ListMarketImplications
description: ListMarketImplications returns AI-generated trade-implication cards from live world state.
operationId: ListMarketImplications
parameters:
- name: frameworkId
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListMarketImplicationsResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-social-velocity:
get:
tags:
- IntelligenceService
summary: GetSocialVelocity
description: GetSocialVelocity returns trending Reddit posts from r/worldnews and r/geopolitics ranked by velocity.
operationId: GetSocialVelocity
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetSocialVelocityResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-country-energy-profile:
get:
tags:
- IntelligenceService
summary: GetCountryEnergyProfile
description: GetCountryEnergyProfile aggregates Phase 1/2/2.5 energy data per country.
operationId: GetCountryEnergyProfile
parameters:
- name: country_code
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCountryEnergyProfileResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/compute-energy-shock:
get:
tags:
- IntelligenceService
summary: ComputeEnergyShockScenario
description: ComputeEnergyShockScenario computes on-demand product supply shock for a given country + chokepoint.
operationId: ComputeEnergyShockScenario
parameters:
- name: country_code
in: query
required: false
schema:
type: string
- name: chokepoint_id
in: query
required: false
schema:
type: string
- name: disruption_pct
in: query
required: false
schema:
type: integer
format: int32
- name: fuel_mode
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ComputeEnergyShockScenarioResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-country-port-activity:
get:
tags:
- IntelligenceService
summary: GetCountryPortActivity
description: GetCountryPortActivity returns port-level tanker traffic and trade volumes for a country.
operationId: GetCountryPortActivity
parameters:
- name: country_code
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/CountryPortActivityResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/intelligence/v1/get-regional-snapshot:
get:
tags:
- IntelligenceService
summary: GetRegionalSnapshot
description: |-
GetRegionalSnapshot returns the latest persisted RegionalSnapshot for a
region. The snapshot is written every 6h by scripts/seed-regional-snapshots.mjs;
this handler only reads canonical state. Premium-gated.
operationId: GetRegionalSnapshot
parameters:
- name: region_id
in: query
description: |-
Display region id (e.g. "mena", "east-asia", "europe"). See shared/geography.js.
Kebab-case: lowercase alphanumeric groups separated by single hyphens, no
trailing or consecutive hyphens.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetRegionalSnapshotResponse'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
default:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
properties:
message:
type: string
description: Error message (e.g., 'user not found', 'database connection failed')
description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
FieldViolation:
type: object
properties:
field:
type: string
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')
description:
type: string
description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
required:
- field
- description
description: FieldViolation describes a single validation error for a specific field.
ValidationError:
type: object
properties:
violations:
type: array
items:
$ref: '#/components/schemas/FieldViolation'
description: List of validation violations
required:
- violations
description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
GetRiskScoresRequest:
type: object
properties:
region:
type: string
description: Optional region filter. Empty returns all tracked regions.
description: GetRiskScoresRequest specifies parameters for retrieving risk scores.
GetRiskScoresResponse:
type: object
properties:
ciiScores:
type: array
items:
$ref: '#/components/schemas/CiiScore'
strategicRisks:
type: array
items:
$ref: '#/components/schemas/StrategicRisk'
description: GetRiskScoresResponse contains composite risk scores and strategic assessments.
CiiScore:
type: object
properties:
region:
type: string
description: Region or country identifier.
staticBaseline:
type: number
maximum: 100
minimum: 0
format: double
description: Static baseline score (0-100).
dynamicScore:
type: number
maximum: 100
minimum: 0
format: double
description: Dynamic real-time score (0-100).
combinedScore:
type: number
maximum: 100
minimum: 0
format: double
description: Combined weighted score (0-100).
trend:
type: string
enum:
- TREND_DIRECTION_UNSPECIFIED
- TREND_DIRECTION_RISING
- TREND_DIRECTION_STABLE
- TREND_DIRECTION_FALLING
description: |-
TrendDirection represents the directional movement of a metric over time.
Used in markets, GDELT tension scores, and risk assessments.
components:
$ref: '#/components/schemas/CiiComponents'
computedAt:
type: integer
format: int64
description: 'Last computation time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: CiiScore represents a Composite Instability Index score for a region or country.
CiiComponents:
type: object
properties:
newsActivity:
type: number
maximum: 100
minimum: 0
format: double
description: News activity signal contribution (0-100).
ciiContribution:
type: number
maximum: 100
minimum: 0
format: double
description: CII index contribution (0-100).
geoConvergence:
type: number
maximum: 100
minimum: 0
format: double
description: Geographic convergence score (0-100).
militaryActivity:
type: number
maximum: 100
minimum: 0
format: double
description: Military activity contribution (0-100).
description: CiiComponents represents the contributing factors to a CII score.
StrategicRisk:
type: object
properties:
region:
type: string
description: Country or region identifier.
level:
type: string
enum:
- SEVERITY_LEVEL_UNSPECIFIED
- SEVERITY_LEVEL_LOW
- SEVERITY_LEVEL_MEDIUM
- SEVERITY_LEVEL_HIGH
description: |-
SeverityLevel represents a three-tier severity classification used across domains.
Maps to existing TS unions: 'low' | 'medium' | 'high'.
score:
type: number
maximum: 100
minimum: 0
format: double
description: Risk score (0-100).
factors:
type: array
items:
type: string
description: Risk factors contributing to the assessment.
trend:
type: string
enum:
- TREND_DIRECTION_UNSPECIFIED
- TREND_DIRECTION_RISING
- TREND_DIRECTION_STABLE
- TREND_DIRECTION_FALLING
description: |-
TrendDirection represents the directional movement of a metric over time.
Used in markets, GDELT tension scores, and risk assessments.
description: StrategicRisk represents a strategic risk assessment for a country or region.
GetPizzintStatusRequest:
type: object
properties:
includeGdelt:
type: boolean
description: Whether to include GDELT tension pairs in the response.
description: GetPizzintStatusRequest specifies parameters for retrieving PizzINT and GDELT data.
GetPizzintStatusResponse:
type: object
properties:
pizzint:
$ref: '#/components/schemas/PizzintStatus'
tensionPairs:
type: array
items:
$ref: '#/components/schemas/GdeltTensionPair'
description: GetPizzintStatusResponse contains Pentagon Pizza Index and GDELT tension data.
PizzintStatus:
type: object
properties:
defconLevel:
type: integer
maximum: 5
minimum: 1
format: int32
description: DEFCON-style level (1-5).
defconLabel:
type: string
description: Human-readable DEFCON label.
aggregateActivity:
type: number
format: double
description: Aggregate activity score.
activeSpikes:
type: integer
format: int32
description: Number of active spike locations.
locationsMonitored:
type: integer
format: int32
description: Total monitored locations.
locationsOpen:
type: integer
format: int32
description: Currently open locations.
updatedAt:
type: integer
format: int64
description: 'Last data update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
dataFreshness:
type: string
enum:
- DATA_FRESHNESS_UNSPECIFIED
- DATA_FRESHNESS_FRESH
- DATA_FRESHNESS_STALE
description: DataFreshness represents how current the data is.
locations:
type: array
items:
$ref: '#/components/schemas/PizzintLocation'
description: PizzintStatus represents the Pentagon Pizza Index status (proxy for late-night DC activity).
PizzintLocation:
type: object
properties:
placeId:
type: string
description: Google Places ID.
name:
type: string
description: Location name.
address:
type: string
description: Street address.
currentPopularity:
type: integer
format: int32
description: Current popularity score (0-200+).
percentageOfUsual:
type: integer
format: int32
description: Percentage of usual activity. Zero if unavailable.
isSpike:
type: boolean
description: Whether activity constitutes a spike.
spikeMagnitude:
type: number
format: double
description: Spike magnitude above baseline. Zero if no spike.
dataSource:
type: string
description: Data source identifier.
recordedAt:
type: string
description: Recording timestamp as ISO 8601 string.
dataFreshness:
type: string
enum:
- DATA_FRESHNESS_UNSPECIFIED
- DATA_FRESHNESS_FRESH
- DATA_FRESHNESS_STALE
description: DataFreshness represents how current the data is.
isClosedNow:
type: boolean
description: Whether the location is currently closed.
lat:
type: number
format: double
description: Latitude of the location.
lng:
type: number
format: double
description: Longitude of the location.
description: PizzintLocation represents a single monitored pizza location near the Pentagon.
GdeltTensionPair:
type: object
properties:
id:
type: string
description: Pair identifier.
countries:
type: array
items:
type: string
description: Country pair (ISO 3166-1 alpha-2 codes).
label:
type: string
description: Human-readable label (e.g., "US-China").
score:
type: number
maximum: 100
minimum: 0
format: double
description: Tension score (0-100).
trend:
type: string
enum:
- TREND_DIRECTION_UNSPECIFIED
- TREND_DIRECTION_RISING
- TREND_DIRECTION_STABLE
- TREND_DIRECTION_FALLING
description: |-
TrendDirection represents the directional movement of a metric over time.
Used in markets, GDELT tension scores, and risk assessments.
changePercent:
type: number
format: double
description: Percentage change from previous period.
region:
type: string
description: Geographic region.
description: GdeltTensionPair represents a bilateral tension score between two countries from GDELT.
ClassifyEventRequest:
type: object
properties:
title:
type: string
minLength: 1
description: Event title or headline.
description:
type: string
description: Event description or body text.
source:
type: string
description: Event source (e.g., "reuters", "acled").
country:
type: string
description: Country context (ISO 3166-1 alpha-2).
required:
- title
description: ClassifyEventRequest specifies an event to classify using AI.
ClassifyEventResponse:
type: object
properties:
classification:
$ref: '#/components/schemas/EventClassification'
description: ClassifyEventResponse contains the AI-generated event classification.
EventClassification:
type: object
properties:
category:
type: string
description: Event category (e.g., "military", "economic", "social").
subcategory:
type: string
description: Event subcategory.
severity:
type: string
enum:
- SEVERITY_LEVEL_UNSPECIFIED
- SEVERITY_LEVEL_LOW
- SEVERITY_LEVEL_MEDIUM
- SEVERITY_LEVEL_HIGH
description: |-
SeverityLevel represents a three-tier severity classification used across domains.
Maps to existing TS unions: 'low' | 'medium' | 'high'.
confidence:
type: number
maximum: 1
minimum: 0
format: double
description: Classification confidence (0.0 to 1.0).
analysis:
type: string
description: Brief AI-generated analysis.
entities:
type: array
items:
type: string
description: Related entities identified.
description: EventClassification represents an AI-generated classification of a real-world event.
GetCountryRiskRequest:
type: object
properties:
countryCode:
type: string
pattern: ^[A-Z]{2}$
description: ISO 3166-1 alpha-2 country code.
required:
- countryCode
description: GetCountryRiskRequest specifies which country to retrieve risk intelligence for.
GetCountryRiskResponse:
type: object
properties:
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code.
countryName:
type: string
description: Country name.
cii:
$ref: '#/components/schemas/CiiScore'
advisoryLevel:
type: string
description: Travel advisory level from government sources (e.g. "do-not-travel", "reconsider", "caution"). Empty if none.
sanctionsActive:
type: boolean
description: Whether this country has active OFAC sanctions designations.
sanctionsCount:
type: integer
format: int32
description: Count of sanctioned entities associated with this country.
fetchedAt:
type: integer
format: int64
description: 'Data freshness timestamp derived from CII computedAt, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
upstreamUnavailable:
type: boolean
description: True when all upstream Redis keys were unavailable. Signals CDN cache bypass.
description: GetCountryRiskResponse contains composite risk intelligence for a specific country.
GetCountryIntelBriefRequest:
type: object
properties:
countryCode:
type: string
pattern: ^[A-Z]{2}$
description: ISO 3166-1 alpha-2 country code.
framework:
type: string
description: Optional analytical framework instructions to append to system prompt. Max 2000 chars enforced at handler level.
required:
- countryCode
description: GetCountryIntelBriefRequest specifies which country to generate a brief for.
GetCountryIntelBriefResponse:
type: object
properties:
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code.
countryName:
type: string
description: Country name.
brief:
type: string
description: AI-generated intelligence brief text.
model:
type: string
description: AI model used for generation.
generatedAt:
type: integer
format: int64
description: 'Brief generation time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: GetCountryIntelBriefResponse contains an AI-generated intelligence brief for a country.
SearchGdeltDocumentsRequest:
type: object
properties:
query:
type: string
minLength: 1
description: Search query string.
maxRecords:
type: integer
maximum: 250
minimum: 1
format: int32
description: Maximum number of articles to return (1-250).
timespan:
type: string
description: Time span filter (e.g., "15min", "1h", "24h").
toneFilter:
type: string
description: |-
Tone filter appended to query (e.g., "tone>5" for positive, "tone<-5" for negative).
Left empty to skip tone filtering.
sort:
type: string
description: 'Sort mode: "DateDesc" (default), "ToneDesc", "ToneAsc", "HybridRel".'
required:
- query
description: SearchGdeltDocumentsRequest specifies filters for searching GDELT news articles.
SearchGdeltDocumentsResponse:
type: object
properties:
articles:
type: array
items:
$ref: '#/components/schemas/GdeltArticle'
query:
type: string
description: Echo of the search query.
error:
type: string
description: Error message if the search failed.
description: SearchGdeltDocumentsResponse contains GDELT article search results.
GdeltArticle:
type: object
properties:
title:
type: string
description: Article headline.
url:
type: string
description: Article URL.
source:
type: string
description: Source domain name.
date:
type: string
description: Publication date string.
image:
type: string
description: Article image URL.
language:
type: string
description: Article language code.
tone:
type: number
format: double
description: GDELT tone score (negative = negative tone, positive = positive tone).
description: GdeltArticle represents a single article from the GDELT document API.
DeductSituationRequest:
type: object
properties:
query:
type: string
geoContext:
type: string
framework:
type: string
description: Optional analytical framework instructions.
DeductSituationResponse:
type: object
properties:
analysis:
type: string
model:
type: string
provider:
type: string
ListSatellitesRequest:
type: object
properties:
country:
type: string
description: Filter by country code. Empty returns all.
description: ListSatellitesRequest specifies filters for orbital data.
ListSatellitesResponse:
type: object
properties:
satellites:
type: array
items:
$ref: '#/components/schemas/Satellite'
description: ListSatellitesResponse contains the current orbital snapshot.
Satellite:
type: object
properties:
id:
type: string
minLength: 1
description: NORAD identifier (e.g., "25544").
name:
type: string
description: Name of the satellite.
country:
type: string
description: ISO country code of the operator/owner.
type:
type: string
description: Purpose category (e.g., "sar", "optical", "military").
alt:
type: number
format: double
description: Orbital altitude in kilometers.
velocity:
type: number
format: double
description: Velocity in km/s.
inclination:
type: number
format: double
description: Orbital inclination in degrees.
line1:
type: string
description: TLE line 1.
line2:
type: string
description: TLE line 2.
required:
- id
description: Satellite represents an orbital asset tracked by WorldMonitor.
ListGpsInterferenceRequest:
type: object
properties:
region:
type: string
description: Optional region filter.
description: ListGpsInterferenceRequest specifies filters for GPS interference data.
ListGpsInterferenceResponse:
type: object
properties:
hexes:
type: array
items:
$ref: '#/components/schemas/GpsJamHex'
stats:
$ref: '#/components/schemas/GpsJamStats'
source:
type: string
description: Data source name.
fetchedAt:
type: integer
format: int64
description: 'Data fetch time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: ListGpsInterferenceResponse contains GPS interference data and stats.
GpsJamHex:
type: object
properties:
h3:
type: string
minLength: 1
description: H3 index of the hexagon.
lat:
type: number
format: double
description: Centroid latitude.
lon:
type: number
format: double
description: Centroid longitude.
level:
type: string
enum:
- INTERFERENCE_LEVEL_UNSPECIFIED
- INTERFERENCE_LEVEL_LOW
- INTERFERENCE_LEVEL_MEDIUM
- INTERFERENCE_LEVEL_HIGH
description: InterferenceLevel represents the severity of detected signal interference.
npAvg:
type: number
format: double
description: Average Navigation Precision (np) - lower means more interference.
sampleCount:
type: integer
format: int32
description: Number of samples in this hex.
aircraftCount:
type: integer
format: int32
description: Number of unique aircraft that reported in this hex.
required:
- h3
description: GpsJamHex represents a geographic hexagon with detected GPS interference.
GpsJamStats:
type: object
properties:
totalHexes:
type: integer
format: int32
highCount:
type: integer
format: int32
mediumCount:
type: integer
format: int32
description: GpsJamStats contains aggregate statistics for GPS interference.
ListOrefAlertsRequest:
type: object
properties:
mode:
type: string
enum:
- MODE_UNSPECIFIED
- MODE_HISTORY
description: Request to fetch Israeli Red Alerts (OREF).
ListOrefAlertsResponse:
type: object
properties:
configured:
type: boolean
description: Whether the OREF bridge is configured.
alerts:
type: array
items:
$ref: '#/components/schemas/OrefAlert'
history:
type: array
items:
$ref: '#/components/schemas/OrefWave'
historyCount24h:
type: integer
format: int32
description: Number of alerts in the last 24 hours.
totalHistoryCount:
type: integer
format: int32
description: Total alerts in the historical buffer.
timestampMs:
type: integer
format: int64
description: 'Unix timestamp in milliseconds of the response generation.. Warning: Values > 2^53 may lose precision in JavaScript'
error:
type: string
description: Optional error message from the relay.
description: OREF alert wave snapshot.
OrefAlert:
type: object
properties:
id:
type: string
cat:
type: string
title:
type: string
data:
type: array
items:
type: string
desc:
type: string
timestampMs:
type: integer
format: int64
description: 'Unix timestamp in milliseconds for when the alert was issued.. Warning: Values > 2^53 may lose precision in JavaScript'
description: A single Red Alert event.
OrefWave:
type: object
properties:
alerts:
type: array
items:
$ref: '#/components/schemas/OrefAlert'
timestampMs:
type: integer
format: int64
description: 'Unix timestamp in milliseconds for this wave.. Warning: Values > 2^53 may lose precision in JavaScript'
description: A wave of alerts occurring at the same time.
ListTelegramFeedRequest:
type: object
properties:
limit:
type: integer
format: int32
description: Maximum number of messages to return (default 50).
topic:
type: string
description: Filter by topic keyword (e.g. "military", "cyber").
channel:
type: string
description: Filter by specific channel ID or name.
description: Request to fetch real-time Telegram OSINT feed.
ListTelegramFeedResponse:
type: object
properties:
enabled:
type: boolean
description: Whether the bridge is currently active.
messages:
type: array
items:
$ref: '#/components/schemas/TelegramMessage'
count:
type: integer
format: int32
description: Total count of messages in the current window.
error:
type: string
description: Detailed error message if the fetch failed.
description: OSINT feed containing validated Telegram messages.
TelegramMessage:
type: object
properties:
id:
type: string
description: Unique message identifier.
channelId:
type: string
description: Identifier of the originating channel.
channelName:
type: string
description: Human-readable name of the channel.
text:
type: string
description: Sanitized message content.
timestampMs:
type: integer
format: int64
description: 'Unix timestamp in milliseconds for when the message was posted.. Warning: Values > 2^53 may lose precision in JavaScript'
mediaUrls:
type: array
items:
type: string
description: Direct links to associated media (images, videos).
sourceUrl:
type: string
description: Link to the original post on Telegram.
topic:
type: string
description: Auto-classified topic based on content.
description: Validated OSINT post from Telegram channels.
GetCompanyEnrichmentRequest:
type: object
properties:
domain:
type: string
name:
type: string
description: |-
Request to fetch enrichment data for a company.
Requires either domain (e.g. "github.com") or name (e.g. "GitHub").
GetCompanyEnrichmentResponse:
type: object
properties:
company:
$ref: '#/components/schemas/EnrichedCompany'
github:
$ref: '#/components/schemas/EnrichedGithub'
techStack:
type: array
items:
$ref: '#/components/schemas/TechStackItem'
secFilings:
$ref: '#/components/schemas/SecFilings'
hackerNewsMentions:
type: array
items:
$ref: '#/components/schemas/HNMention'
enrichedAtMs:
type: integer
format: int64
description: 'Unix timestamp in milliseconds when this data was fetched.. Warning: Values > 2^53 may lose precision in JavaScript'
sources:
type: array
items:
type: string
description: List of sources successfully reached (e.g. "github", "sec_edgar").
description: Aggregated company data from multiple public sources.
EnrichedCompany:
type: object
properties:
name:
type: string
domain:
type: string
description:
type: string
location:
type: string
website:
type: string
founded:
type: integer
format: int32
EnrichedGithub:
type: object
properties:
publicRepos:
type: integer
format: int32
followers:
type: integer
format: int32
avatarUrl:
type: string
TechStackItem:
type: object
properties:
name:
type: string
category:
type: string
confidence:
type: number
format: float
SecFilings:
type: object
properties:
totalFilings:
type: integer
format: int32
recentFilings:
type: array
items:
$ref: '#/components/schemas/SecFiling'
SecFiling:
type: object
properties:
form:
type: string
fileDate:
type: string
description:
type: string
HNMention:
type: object
properties:
title:
type: string
url:
type: string
points:
type: integer
format: int32
comments:
type: integer
format: int32
createdAtMs:
type: integer
format: int64
description: 'Unix timestamp in milliseconds when the post was created.. Warning: Values > 2^53 may lose precision in JavaScript'
ListCompanySignalsRequest:
type: object
properties:
company:
type: string
domain:
type: string
description: Request to discover and classify company signals (hiring, funding, tech changes).
ListCompanySignalsResponse:
type: object
properties:
company:
type: string
domain:
type: string
signals:
type: array
items:
$ref: '#/components/schemas/CompanySignal'
summary:
$ref: '#/components/schemas/SignalSummary'
discoveredAtMs:
type: integer
format: int64
description: 'Unix timestamp in milliseconds when signals were discovered.. Warning: Values > 2^53 may lose precision in JavaScript'
description: Discovered company signals with classification and engagement metrics.
CompanySignal:
type: object
properties:
type:
type: string
description: Classification type (e.g. "Hiring", "Product Launch", "Expansion").
title:
type: string
url:
type: string
source:
type: string
sourceTier:
type: integer
format: int32
description: Data quality tier (1 is authoritative, 5 is low confidence).
timestampMs:
type: integer
format: int64
description: 'Unix timestamp in milliseconds of the event occurrence.. Warning: Values > 2^53 may lose precision in JavaScript'
strength:
type: string
description: Qualitative strength of the signal (e.g. "Strong", "Emerging").
engagement:
$ref: '#/components/schemas/SignalEngagement'
SignalEngagement:
type: object
properties:
points:
type: integer
format: int32
comments:
type: integer
format: int32
stars:
type: integer
format: int32
forks:
type: integer
format: int32
mentions:
type: integer
format: int32
SignalSummary:
type: object
properties:
totalSignals:
type: integer
format: int32
byType:
type: object
additionalProperties:
type: integer
format: int32
strongestSignal:
$ref: '#/components/schemas/CompanySignal'
signalDiversity:
type: integer
format: int32
ByTypeEntry:
type: object
properties:
key:
type: string
value:
type: integer
format: int32
GetCountryFactsRequest:
type: object
properties:
countryCode:
type: string
pattern: ^[A-Z]{2}$
required:
- countryCode
GetCountryFactsResponse:
type: object
properties:
headOfState:
type: string
headOfStateTitle:
type: string
wikipediaSummary:
type: string
wikipediaThumbnailUrl:
type: string
population:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
capital:
type: string
languages:
type: array
items:
type: string
currencies:
type: array
items:
type: string
areaSqKm:
type: number
format: double
countryName:
type: string
ListSecurityAdvisoriesRequest:
type: object
ListSecurityAdvisoriesResponse:
type: object
properties:
advisories:
type: array
items:
$ref: '#/components/schemas/SecurityAdvisoryItem'
byCountry:
type: object
additionalProperties:
type: string
ByCountryEntry:
type: object
properties:
key:
type: string
value:
type: string
SecurityAdvisoryItem:
type: object
properties:
title:
type: string
link:
type: string
pubDate:
type: string
source:
type: string
sourceCountry:
type: string
level:
type: string
country:
type: string
GetGdeltTopicTimelineRequest:
type: object
properties:
topic:
type: string
description: Topic ID (military, cyber, nuclear, sanctions, intelligence, maritime).
description: GetGdeltTopicTimelineRequest retrieves tone and volume timelines for a GDELT intel topic.
GetGdeltTopicTimelineResponse:
type: object
properties:
topic:
type: string
description: Topic ID.
tone:
type: array
items:
$ref: '#/components/schemas/GdeltTimelinePoint'
vol:
type: array
items:
$ref: '#/components/schemas/GdeltTimelinePoint'
fetchedAt:
type: string
description: ISO timestamp when this data was fetched.
error:
type: string
description: Error message if fetch failed.
description: GetGdeltTopicTimelineResponse contains tone and volume timelines for a topic.
GdeltTimelinePoint:
type: object
properties:
date:
type: string
description: Date string from GDELT (e.g. "20240101T000000").
value:
type: number
format: double
description: Tone or volume value at this point.
description: GdeltTimelinePoint is a single data point in a tone or volume timeline.
ListCrossSourceSignalsRequest:
type: object
description: ListCrossSourceSignalsRequest has no required parameters (returns all signals).
ListCrossSourceSignalsResponse:
type: object
properties:
signals:
type: array
items:
$ref: '#/components/schemas/CrossSourceSignal'
evaluatedAt:
type: integer
format: int64
description: 'Timestamp when the aggregator last ran (Unix epoch milliseconds).. Warning: Values > 2^53 may lose precision in JavaScript'
compositeCount:
type: integer
format: int32
description: Total number of composite escalation zones detected.
description: ListCrossSourceSignalsResponse contains ranked cross-domain signals.
CrossSourceSignal:
type: object
properties:
id:
type: string
description: Unique signal identifier.
type:
type: string
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
description: CrossSourceSignalType enumerates all monitored cross-domain signal categories.
theater:
type: string
description: Theater / geographic context (e.g. "Eastern Europe", "Red Sea", "Global Markets").
summary:
type: string
description: Human-readable summary of the signal.
severity:
type: string
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
description: CrossSourceSignalSeverity indicates the urgency tier of a detected signal.
severityScore:
type: number
format: double
description: 'Raw severity score used for ranking (higher = more severe).. Warning: Values > 2^53 may lose precision in JavaScript'
detectedAt:
type: integer
format: int64
description: 'Detection timestamp (Unix epoch milliseconds).. Warning: Values > 2^53 may lose precision in JavaScript'
contributingTypes:
type: array
items:
type: string
description: 'For COMPOSITE_ESCALATION: list of contributing signal type names.'
signalCount:
type: integer
format: int32
description: 'For COMPOSITE_ESCALATION: number of co-firing signals in theater.'
description: CrossSourceSignal represents a single detected cross-domain signal event.
ListMarketImplicationsRequest:
type: object
properties:
frameworkId:
type: string
ListMarketImplicationsResponse:
type: object
properties:
cards:
type: array
items:
$ref: '#/components/schemas/MarketImplicationCard'
degraded:
type: boolean
emptyReason:
type: string
generatedAt:
type: string
MarketImplicationCard:
type: object
properties:
ticker:
type: string
name:
type: string
direction:
type: string
timeframe:
type: string
confidence:
type: string
title:
type: string
narrative:
type: string
riskCaveat:
type: string
driver:
type: string
transmissionChain:
type: array
items:
$ref: '#/components/schemas/TransmissionNode'
TransmissionNode:
type: object
properties:
node:
type: string
impactType:
type: string
logic:
type: string
GetSocialVelocityRequest:
type: object
GetSocialVelocityResponse:
type: object
properties:
posts:
type: array
items:
$ref: '#/components/schemas/SocialVelocityPost'
fetchedAt:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
SocialVelocityPost:
type: object
properties:
id:
type: string
description: Reddit post ID.
title:
type: string
description: Post title.
subreddit:
type: string
description: Subreddit name (without r/ prefix).
url:
type: string
description: Direct URL to the post.
score:
type: integer
format: int32
description: Reddit score (upvotes - downvotes).
upvoteRatio:
type: number
format: double
description: Upvote ratio (0.0–1.0).
numComments:
type: integer
format: int32
description: Number of comments.
velocityScore:
type: number
format: double
description: Composite velocity score accounting for recency, score, and ratio.
createdAt:
type: integer
format: int64
description: 'Unix epoch milliseconds when posted.. Warning: Values > 2^53 may lose precision in JavaScript'
description: SocialVelocityPost represents a trending Reddit post with velocity scoring.
GetCountryEnergyProfileRequest:
type: object
properties:
countryCode:
type: string
GetCountryEnergyProfileResponse:
type: object
properties:
mixAvailable:
type: boolean
description: Phase 1 — OWID structural mix (~200 countries)
mixYear:
type: integer
format: int32
coalShare:
type: number
format: double
gasShare:
type: number
format: double
oilShare:
type: number
format: double
nuclearShare:
type: number
format: double
renewShare:
type: number
format: double
windShare:
type: number
format: double
solarShare:
type: number
format: double
hydroShare:
type: number
format: double
importShare:
type: number
format: double
gasStorageAvailable:
type: boolean
description: Phase 2 — EU gas storage
gasStorageFillPct:
type: number
format: double
gasStorageChange1d:
type: number
format: double
gasStorageTrend:
type: string
gasStorageDate:
type: string
electricityAvailable:
type: boolean
description: |-
Phase 2 — EU electricity (ENTSO-E countries: DE FR ES IT NL BE PL PT GB NO SE)
US electricity is stored by EIA balancing area, not ISO2 — not available here
electricityPriceMwh:
type: number
format: double
electricitySource:
type: string
electricityDate:
type: string
jodiOilAvailable:
type: boolean
description: Phase 2.5 — JODI Oil (~90+ countries)
jodiOilDataMonth:
type: string
gasolineDemandKbd:
type: number
format: double
gasolineImportsKbd:
type: number
format: double
dieselDemandKbd:
type: number
format: double
dieselImportsKbd:
type: number
format: double
jetDemandKbd:
type: number
format: double
jetImportsKbd:
type: number
format: double
lpgDemandKbd:
type: number
format: double
crudeImportsKbd:
type: number
format: double
lpgImportsKbd:
type: number
format: double
jodiGasAvailable:
type: boolean
description: Phase 2.5 — JODI Gas
jodiGasDataMonth:
type: string
gasTotalDemandTj:
type: number
format: double
gasLngImportsTj:
type: number
format: double
gasPipeImportsTj:
type: number
format: double
gasLngShare:
type: number
format: double
ieaStocksAvailable:
type: boolean
description: Phase 2.5 — IEA oil stocks (~31 IEA members)
ieaStocksDataMonth:
type: string
ieaDaysOfCover:
type: integer
format: int32
ieaNetExporter:
type: boolean
ieaBelowObligation:
type: boolean
emberFossilShare:
type: number
format: double
description: Phase 3 — Ember monthly electricity mix
emberRenewShare:
type: number
format: double
emberNuclearShare:
type: number
format: double
emberCoalShare:
type: number
format: double
emberGasShare:
type: number
format: double
emberDemandTwh:
type: number
format: double
emberDataMonth:
type: string
emberAvailable:
type: boolean
sprRegime:
type: string
description: Phase 4 — SPR policy classification
sprCapacityMb:
type: number
format: double
sprOperator:
type: string
sprIeaMember:
type: boolean
sprStockholdingModel:
type: string
sprNote:
type: string
sprSource:
type: string
sprAsOf:
type: string
sprAvailable:
type: boolean
ComputeEnergyShockScenarioRequest:
type: object
properties:
countryCode:
type: string
chokepointId:
type: string
disruptionPct:
type: integer
format: int32
fuelMode:
type: string
ComputeEnergyShockScenarioResponse:
type: object
properties:
countryCode:
type: string
chokepointId:
type: string
disruptionPct:
type: integer
format: int32
gulfCrudeShare:
type: number
format: double
crudeLossKbd:
type: number
format: double
products:
type: array
items:
$ref: '#/components/schemas/ProductImpact'
effectiveCoverDays:
type: integer
format: int32
assessment:
type: string
dataAvailable:
type: boolean
jodiOilCoverage:
type: boolean
description: v2 fields
comtradeCoverage:
type: boolean
ieaStocksCoverage:
type: boolean
portwatchCoverage:
type: boolean
coverageLevel:
type: string
limitations:
type: array
items:
type: string
degraded:
type: boolean
chokepointConfidence:
type: string
liveFlowRatio:
type: number
format: double
gasImpact:
$ref: '#/components/schemas/GasImpact'
ProductImpact:
type: object
properties:
product:
type: string
outputLossKbd:
type: number
format: double
demandKbd:
type: number
format: double
deficitPct:
type: number
format: double
GasImpact:
type: object
properties:
lngShareOfImports:
type: number
format: double
lngImportsTj:
type: number
format: double
lngDisruptionTj:
type: number
format: double
totalDemandTj:
type: number
format: double
deficitPct:
type: number
format: double
dataAvailable:
type: boolean
assessment:
type: string
storage:
$ref: '#/components/schemas/GasStorageBuffer'
dataSource:
type: string
GasStorageBuffer:
type: object
properties:
fillPct:
type: number
format: double
gasTwh:
type: number
format: double
bufferDays:
type: number
format: double
trend:
type: string
date:
type: string
scope:
type: string
GetCountryPortActivityRequest:
type: object
properties:
countryCode:
type: string
CountryPortActivityResponse:
type: object
properties:
ports:
type: array
items:
$ref: '#/components/schemas/PortActivityEntry'
fetchedAt:
type: string
available:
type: boolean
PortActivityEntry:
type: object
properties:
portId:
type: string
portName:
type: string
lat:
type: number
format: double
lon:
type: number
format: double
tankerCalls30d:
type: integer
format: int32
trendDeltaPct:
type: number
format: double
importTankerDwt:
type: number
format: double
exportTankerDwt:
type: number
format: double
anomalySignal:
type: boolean
GetRegionalSnapshotRequest:
type: object
properties:
regionId:
type: string
maxLength: 32
minLength: 1
pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$
description: |-
Display region id (e.g. "mena", "east-asia", "europe"). See shared/geography.js.
Kebab-case: lowercase alphanumeric groups separated by single hyphens, no
trailing or consecutive hyphens.
required:
- regionId
description: |-
GetRegionalSnapshotRequest asks for the latest persisted RegionalSnapshot
for a given region. See shared/geography.ts for the canonical region ids.
GetRegionalSnapshotResponse:
type: object
properties:
snapshot:
$ref: '#/components/schemas/RegionalSnapshot'
description: |-
GetRegionalSnapshotResponse returns the latest RegionalSnapshot for the
requested region. The snapshot is written by scripts/seed-regional-snapshots.mjs
on a 6h cron; this handler only reads canonical state.
RegionalSnapshot:
type: object
properties:
regionId:
type: string
generatedAt:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
meta:
$ref: '#/components/schemas/SnapshotMeta'
regime:
$ref: '#/components/schemas/RegimeState'
balance:
$ref: '#/components/schemas/BalanceVector'
actors:
type: array
items:
$ref: '#/components/schemas/ActorState'
leverageEdges:
type: array
items:
$ref: '#/components/schemas/LeverageEdge'
scenarioSets:
type: array
items:
$ref: '#/components/schemas/ScenarioSet'
transmissionPaths:
type: array
items:
$ref: '#/components/schemas/TransmissionPath'
triggers:
$ref: '#/components/schemas/TriggerLadder'
mobility:
$ref: '#/components/schemas/MobilityState'
evidence:
type: array
items:
$ref: '#/components/schemas/EvidenceItem'
narrative:
$ref: '#/components/schemas/RegionalNarrative'
description: |-
RegionalSnapshot is the canonical intelligence object for one region.
See docs/internal/pro-regional-intelligence-upgrade.md for the full spec
and shared/regions.types.d.ts for the authoritative TypeScript contract.
SnapshotMeta:
type: object
properties:
snapshotId:
type: string
modelVersion:
type: string
scoringVersion:
type: string
geographyVersion:
type: string
snapshotConfidence:
type: number
format: double
missingInputs:
type: array
items:
type: string
staleInputs:
type: array
items:
type: string
validUntil:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
triggerReason:
type: string
description: |-
trigger_reason: scheduled_6h | regime_shift | trigger_activation |
corridor_break | leverage_shift
narrativeProvider:
type: string
narrativeModel:
type: string
description: |-
SnapshotMeta carries the trust trail (versions, confidence, input freshness,
narrative provenance, idempotency id).
RegimeState:
type: object
properties:
label:
type: string
description: |-
label: calm | stressed_equilibrium | coercive_stalemate |
fragmentation_risk | managed_deescalation | escalation_ladder
previousLabel:
type: string
transitionedAt:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
transitionDriver:
type: string
description: RegimeState captures the current regime label and transition history.
BalanceVector:
type: object
properties:
coercivePressure:
type: number
format: double
description: Pressures (high = bad)
domesticFragility:
type: number
format: double
capitalStress:
type: number
format: double
energyVulnerability:
type: number
format: double
allianceCohesion:
type: number
format: double
description: Buffers (high = good)
maritimeAccess:
type: number
format: double
energyLeverage:
type: number
format: double
netBalance:
type: number
format: double
description: 'Derived: mean(buffers) - mean(pressures), range [-1, +1]'
pressures:
type: array
items:
$ref: '#/components/schemas/BalanceDriver'
buffers:
type: array
items:
$ref: '#/components/schemas/BalanceDriver'
description: |-
BalanceVector is the 7-axis regional balance score with pressures/buffers
split. See docs/internal/pro-regional-intelligence-appendix-scoring.md for
the per-axis formulas.
BalanceDriver:
type: object
properties:
axis:
type: string
description:
type: string
magnitude:
type: number
format: double
evidenceIds:
type: array
items:
type: string
orientation:
type: string
description: 'orientation: "pressure" | "buffer"'
description: BalanceDriver is one contributor to an axis score. Links back to evidence.
ActorState:
type: object
properties:
actorId:
type: string
name:
type: string
role:
type: string
description: 'role: aggressor | stabilizer | swing | broker'
leverageDomains:
type: array
items:
type: string
description: 'leverage_domains: energy | military | diplomatic | economic | maritime'
leverageScore:
type: number
format: double
delta:
type: number
format: double
evidenceIds:
type: array
items:
type: string
description: ActorState is one geopolitical actor's leverage score in the region.
LeverageEdge:
type: object
properties:
fromActorId:
type: string
toActorId:
type: string
mechanism:
type: string
description: 'mechanism: sanctions | naval_posture | energy_supply | alliance_shift | trade_friction'
strength:
type: number
format: double
evidenceIds:
type: array
items:
type: string
description: LeverageEdge is a directed influence relationship between two actors.
ScenarioSet:
type: object
properties:
horizon:
type: string
description: 'horizon: 24h | 7d | 30d'
lanes:
type: array
items:
$ref: '#/components/schemas/ScenarioLane'
description: |-
ScenarioSet bundles scenario lanes for one time horizon. Lane probabilities
sum to 1.0 within a set.
ScenarioLane:
type: object
properties:
name:
type: string
description: 'name: base | escalation | containment | fragmentation'
probability:
type: number
format: double
triggerIds:
type: array
items:
type: string
consequences:
type: array
items:
type: string
transmissions:
type: array
items:
$ref: '#/components/schemas/TransmissionPath'
description: ScenarioLane is one outcome branch within a horizon set.
TransmissionPath:
type: object
properties:
start:
type: string
mechanism:
type: string
end:
type: string
severity:
type: string
description: 'severity: critical | high | medium | low'
corridorId:
type: string
confidence:
type: number
format: double
latencyHours:
type: integer
format: int32
impactedAssetClass:
type: string
description: 'impacted_asset_class: crude | lng | container | fx | equity | agri | metals | ...'
impactedRegions:
type: array
items:
type: string
magnitudeLow:
type: number
format: double
magnitudeHigh:
type: number
format: double
magnitudeUnit:
type: string
description: 'magnitude_unit: usd_bbl | pct | usd_teu | basis_points | ...'
templateId:
type: string
templateVersion:
type: string
description: |-
TransmissionPath describes how a regional event propagates to markets,
logistics, mobility, or other domains. Typed for ranking and calibration.
TriggerLadder:
type: object
properties:
active:
type: array
items:
$ref: '#/components/schemas/Trigger'
watching:
type: array
items:
$ref: '#/components/schemas/Trigger'
dormant:
type: array
items:
$ref: '#/components/schemas/Trigger'
description: TriggerLadder buckets triggers by activation state.
Trigger:
type: object
properties:
id:
type: string
description:
type: string
threshold:
$ref: '#/components/schemas/TriggerThreshold'
activated:
type: boolean
activatedAt:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
scenarioLane:
type: string
description: 'scenario_lane: base | escalation | containment | fragmentation'
evidenceIds:
type: array
items:
type: string
description: Trigger is a structured threshold assertion against a named metric.
TriggerThreshold:
type: object
properties:
metric:
type: string
operator:
type: string
description: 'operator: gt | gte | lt | lte | delta_gt | delta_lt'
value:
type: number
format: double
windowMinutes:
type: integer
format: int32
baseline:
type: string
description: 'baseline: trailing_7d | trailing_30d | fixed'
description: |-
TriggerThreshold defines the metric/operator/value/window/baseline for
deterministic trigger evaluation.
MobilityState:
type: object
properties:
airspace:
type: array
items:
$ref: '#/components/schemas/AirspaceStatus'
flightCorridors:
type: array
items:
$ref: '#/components/schemas/FlightCorridorStress'
airports:
type: array
items:
$ref: '#/components/schemas/AirportNodeStatus'
rerouteIntensity:
type: number
format: double
notamClosures:
type: array
items:
type: string
description: |-
MobilityState captures airspace, flight corridor, and airport node status
for the region. Phase 0 ships empty; Phase 2 wires the data plane.
AirspaceStatus:
type: object
properties:
airspaceId:
type: string
status:
type: string
description: 'status: open | restricted | closed'
reason:
type: string
description: AirspaceStatus captures FIR-level airspace state.
FlightCorridorStress:
type: object
properties:
corridor:
type: string
stressLevel:
type: number
format: double
reroutedFlights24h:
type: integer
format: int32
description: FlightCorridorStress captures per-corridor reroute intensity.
AirportNodeStatus:
type: object
properties:
icao:
type: string
name:
type: string
status:
type: string
description: 'status: normal | disrupted | closed'
disruptionReason:
type: string
description: AirportNodeStatus captures airport-level disruption state.
EvidenceItem:
type: object
properties:
id:
type: string
type:
type: string
description: |-
type: vessel_track | flight_surge | news_headline | cii_spike |
chokepoint_status | sanctions_move | market_signal | mobility_disruption
source:
type: string
description: 'source: AIS | ADSB | GDELT | ACLED | Yahoo | OREF | NOTAM | ...'
summary:
type: string
confidence:
type: number
format: double
observedAt:
type: integer
format: int64
description: 'Warning: Values > 2^53 may lose precision in JavaScript'
theater:
type: string
corridor:
type: string
description: |-
EvidenceItem is one upstream data point linked from balance drivers,
narrative sections, and triggers.
RegionalNarrative:
type: object
properties:
situation:
$ref: '#/components/schemas/NarrativeSection'
balanceAssessment:
$ref: '#/components/schemas/NarrativeSection'
outlook24h:
$ref: '#/components/schemas/NarrativeSection'
outlook7d:
$ref: '#/components/schemas/NarrativeSection'
outlook30d:
$ref: '#/components/schemas/NarrativeSection'
watchItems:
type: array
items:
$ref: '#/components/schemas/NarrativeSection'
description: |-
RegionalNarrative is the LLM-synthesized narrative layer. Every section
links back to evidence via evidence_ids.
NarrativeSection:
type: object
properties:
text:
type: string
evidenceIds:
type: array
items:
type: string
description: NarrativeSection is one block of narrative text plus its supporting evidence.
Reference in New Issue View Git Blame Copy Permalink