IntelligenceService.openapi.yaml

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 instability and strategic risk 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 pair 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 classifies a real-world event using AI (Groq).
            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-intel-brief:
        get:
            tags:
                - IntelligenceService
            summary: GetCountryIntelBrief
            description: GetCountryIntelBrief generates an AI intelligence brief for a country (OpenRouter).
            operationId: GetCountryIntelBrief
            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/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 2.0 Doc API for news articles.
            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 AI-powered situational analysis and deduction.
            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'
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.
        GetCountryIntelBriefRequest:
            type: object
            properties:
                countryCode:
                    type: string
                    pattern: ^[A-Z]{2}$
                    description: ISO 3166-1 alpha-2 country code.
            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
        DeductSituationResponse:
            type: object
            properties:
                analysis:
                    type: string
                model:
                    type: string
                provider:
                    type: string