openapi: 3.1.0
info:
  title: Vantage API
  description: Agentic Market Intelligence Read-side API Layer
  version: 1.0.0
paths:
  /api/chat:
    post:
      summary: Chat
      operationId: chat_api_chat_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/gaps:
    get:
      summary: Get Gaps
      description: Retrieve the top opportunity gaps from the Knowledge Graph database.
      operationId: get_gaps_api_gaps_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          description: The maximum number of gaps to return.
          default: 10
          title: Limit
        description: The maximum number of gaps to return.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GapItem'
                title: Response Get Gaps Api Gaps Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/graph/{topic}:
    get:
      summary: Get Entities For Topic
      description: Retrieve all identified key entities linked to a specific topic
        in the graph.
      operationId: get_entities_for_topic_api_graph__topic__get
      parameters:
      - name: topic
        in: path
        required: true
        schema:
          type: string
          description: The topic to look up in the Knowledge Graph.
          title: Topic
        description: The topic to look up in the Knowledge Graph.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicEntitiesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/signals:
    get:
      summary: Get Signals
      description: Retrieve external market signals sorted by highest momentum.
      operationId: get_signals_api_signals_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          description: The maximum number of trending keywords to return.
          default: 10
          title: Limit
        description: The maximum number of trending keywords to return.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SignalItem'
                title: Response Get Signals Api Signals Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ChatRequest:
      properties:
        message:
          type: string
          title: Message
          description: The user query or prompt.
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
          description: Optional conversation tracking ID. Auto-generated if omitted.
      type: object
      required:
      - message
      title: ChatRequest
      description: Payload for conversational interaction with the Vantage agent.
    ChatResponse:
      properties:
        answer:
          type: string
          title: Answer
          description: The synthesized, grounded answer from Vantage.
        tools_called:
          items:
            type: string
          type: array
          title: Tools Called
          description: The tools called during this specific turn.
        thread_id:
          type: string
          title: Thread Id
          description: The thread ID used for continuing the conversation.
      type: object
      required:
      - answer
      - tools_called
      - thread_id
      title: ChatResponse
      description: The final synthesized response from the agent.
    GapItem:
      properties:
        topic:
          type: string
          title: Topic
          description: The name of the topic.
        gap_score:
          type: number
          title: Gap Score
          description: 'Calculated GapScore: Momentum * (1 - Coverage).'
        entities:
          items:
            type: string
          type: array
          title: Entities
          description: Associated key named entities from spaCy NER.
      type: object
      required:
      - topic
      - gap_score
      title: GapItem
      description: A single topic gap with its associated momentum, coverage, and
        score.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SignalItem:
      properties:
        keyword:
          type: string
          title: Keyword
          description: The trending search keyword/topic.
        momentum_percentile:
          type: number
          title: Momentum Percentile
          description: The percentile momentum score [0, 1] relative to other topics.
      type: object
      required:
      - keyword
      - momentum_percentile
      title: SignalItem
      description: External market signal metric for a given keyword.
    TopicEntitiesResponse:
      properties:
        topic:
          type: string
          title: Topic
          description: The query topic name.
        entities:
          items:
            type: string
          type: array
          title: Entities
          description: List of related companies, people, and locations.
      type: object
      required:
      - topic
      - entities
      title: TopicEntitiesResponse
      description: The mapping of a topic to its identified key entities in the graph.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError