openapi: 3.1.0
info:
  title: AggregatesAPI
  description: >-
    A microservice to provide rollups, leaderboards, and breadth metrics across
    entities.
  version: 0.1.0
paths:
  /aggregates/health:
    get:
      tags:
        - Utility
      summary: Health check endpoint
      operationId: health_check_aggregates_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /aggregates/breadth/{sector}:
    get:
      tags:
        - breadth
      summary: Get Sector-Level Breadth Indicators
      description: |-
        Returns key technical breadth indicators (e.g., Advance/Decline Line, 
        Stocks above 50-day SMA) for the specified sector.
      operationId: get_sector_breadth_aggregates_breadth__sector__get
      security:
        - HTTPBearer: []
      parameters:
        - name: sector
          in: path
          required: true
          schema:
            type: string
            title: Sector
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BreadthIndicator'
                title: Response Get Sector Breadth Aggregates Breadth  Sector  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /aggregates/summary/{theme}:
    get:
      tags:
        - summary
      summary: Get Theme-Level Summary Statistics
      description: >-
        Returns high-level statistical summaries for a specific investment
        theme, 

        such as average score, volatility, and top constituent stocks.
      operationId: get_theme_summary_aggregates_summary__theme__get
      security:
        - HTTPBearer: []
      parameters:
        - name: theme
          in: path
          required: true
          schema:
            type: string
            title: Theme
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThemeSummary'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /aggregates/top_flows:
    get:
      tags:
        - topFlows
      summary: Get Top Sectors/Themes by Flow
      description: |-
        Returns a ranked list of the top entities (sectors or themes) based on 
        inbound/outbound flow over the specified period.
      operationId: get_top_flows_aggregates_top_flows_get
      security:
        - HTTPBearer: []
      parameters:
        - name: scope
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/AggregateScope'
            description: The entity type to aggregate (sector or theme).
          description: The entity type to aggregate (sector or theme).
        - name: period
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/AggregatePeriod'
            description: The comparison period for the flow (WoW, DoD, MoM).
          description: The comparison period for the flow (WoW, DoD, MoM).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopFlowItem'
                title: Response Get Top Flows Aggregates Top Flows Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AggregatePeriod:
      type: string
      enum:
        - DoD
        - WoW
        - MoM
      title: AggregatePeriod
      description: Available periods for top flow comparison.
    AggregateScope:
      type: string
      enum:
        - sector
        - theme
      title: AggregateScope
      description: Available scope for top flow aggregation.
    BreadthIndicator:
      properties:
        indicator_name:
          type: string
          title: Indicator Name
        value:
          type: number
          title: Value
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - indicator_name
        - value
      title: BreadthIndicator
      description: Model for a single breadth indicator.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ThemeSummary:
      properties:
        themeId:
          type: string
          title: Themeid
        score_avg:
          type: number
          title: Score Avg
        volatility:
          type: number
          title: Volatility
        coverage_count:
          type: integer
          title: Coverage Count
        top_stocks:
          items:
            type: string
          type: array
          title: Top Stocks
      type: object
      required:
        - themeId
        - score_avg
        - volatility
        - coverage_count
        - top_stocks
      title: ThemeSummary
      description: Model for theme-level summary statistics.
    TopFlowItem:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        type:
          $ref: '#/components/schemas/AggregateScope'
        flow_value:
          type: number
          title: Flow Value
        change_pct:
          type: number
          title: Change Pct
      type: object
      required:
        - id
        - name
        - type
        - flow_value
        - change_pct
      title: TopFlowItem
      description: Model for a single item in the top_flows response.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
