router.yaml

openapi: 3.0.3
info:
  title: Agent Router API
  description: API for routing tasks between light and heavy workers
  version: 1.0.0
  contact:
    name: Agent Team
    email: support@agent.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:9006
    description: Development server
  - url: https://api.agent.dev
    description: Production server

security:
  - ApiKeyAuth: []
  - BearerAuth: []

paths:
  /solve:
    post:
      summary: Solve a task
      description: Routes a task to the appropriate worker (light or heavy) based on complexity and requirements
      operationId: solveTask
      tags:
        - Tasks
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
            example:
              id: "task-123"
              domain: "algorithms"
              spec:
                success_criteria: ["sorted_non_decreasing"]
                props:
                  type: "sort"
                metrics_weights:
                  cases_passed: 1.0
              input:
                numbers: [3, 1, 2]
              flags:
                requires_sandbox: false
                max_complexity: 3
              budget:
                timeout: "30s"
      responses:
        '200':
          description: Task solved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
              example:
                success: true
                output:
                  sorted_numbers: [1, 2, 3]
                metrics:
                  cases_passed: 1
                  cases_total: 1
                cost: 0.001
                duration: "150ms"
        '400':
          description: Bad request - invalid task data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /health:
    get:
      summary: Health check
      description: Returns the health status of the router
      operationId: healthCheck
      tags:
        - System
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"
                  service:
                    type: string
                    example: "agent-router"
                  light_worker:
                    type: string
                    example: "http://localhost:9004"
                  heavy_worker:
                    type: string
                    example: "http://localhost:9002"
                  timestamp:
                    type: string
                    format: date-time

  /ready:
    get:
      summary: Readiness check
      description: Returns the readiness status of the router and its dependencies
      operationId: readinessCheck
      tags:
        - System
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ready"
                  workers:
                    type: object
                    properties:
                      light:
                        type: boolean
                        example: true
                      heavy:
                        type: boolean
                        example: true
        '503':
          description: Service not ready
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "not_ready"
                  workers:
                    type: object
                    properties:
                      light:
                        type: boolean
                        example: false
                      heavy:
                        type: boolean
                        example: true

  /caps:
    get:
      summary: Get capabilities
      description: Returns the capabilities of the router and its workers
      operationId: getCapabilities
      tags:
        - System
      responses:
        '200':
          description: Capabilities retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  light_worker:
                    type: object
                    properties:
                      url:
                        type: string
                        example: "http://localhost:9004"
                      capabilities:
                        type: object
                        properties:
                          use_kb:
                            type: boolean
                            example: true
                          use_wasm:
                            type: boolean
                            example: false
                          use_llm:
                            type: boolean
                            example: false
                  heavy_worker:
                    type: object
                    properties:
                      url:
                        type: string
                        example: "http://localhost:9002"
                      capabilities:
                        type: object
                        properties:
                          use_kb:
                            type: boolean
                            example: true
                          use_wasm:
                            type: boolean
                            example: true
                          use_llm:
                            type: boolean
                            example: true
                  routing_rules:
                    type: object
                    properties:
                      requires_sandbox:
                        type: string
                        example: "heavy"
                      max_complexity_threshold:
                        type: integer
                        example: 5
                      high_complexity:
                        type: string
                        example: "heavy"
                      default:
                        type: string
                        example: "light"

  /metrics:
    get:
      summary: Get metrics
      description: Returns Prometheus-compatible metrics
      operationId: getMetrics
      tags:
        - System
      responses:
        '200':
          description: Metrics retrieved successfully
          content:
            text/plain:
              schema:
                type: string
                example: |
                  # HELP agent_router_requests_total Total number of requests
                  # TYPE agent_router_requests_total counter
                  agent_router_requests_total{worker_type="light"} 100
                  agent_router_requests_total{worker_type="heavy"} 50
                  
                  # HELP agent_router_request_duration_seconds Request duration in seconds
                  # TYPE agent_router_request_duration_seconds histogram
                  agent_router_request_duration_seconds_bucket{worker_type="light",le="0.1"} 80
                  agent_router_request_duration_seconds_bucket{worker_type="light",le="0.5"} 95
                  agent_router_request_duration_seconds_bucket{worker_type="light",le="1.0"} 100

components:
  schemas:
    Task:
      type: object
      required:
        - id
        - domain
        - spec
        - input
        - flags
        - budget
      properties:
        id:
          type: string
          description: Unique task identifier
          example: "task-123"
        domain:
          type: string
          description: Task domain (e.g., algorithms, data_processing)
          example: "algorithms"
        spec:
          $ref: '#/components/schemas/Spec'
        input:
          type: object
          description: Task input data
          example:
            numbers: [3, 1, 2]
        flags:
          $ref: '#/components/schemas/TaskFlags'
        budget:
          $ref: '#/components/schemas/Budget'

    Spec:
      type: object
      required:
        - success_criteria
        - metrics_weights
      properties:
        success_criteria:
          type: array
          items:
            type: string
          description: List of success criteria
          example: ["sorted_non_decreasing"]
        props:
          type: object
          description: Additional properties
          example:
            type: "sort"
        metrics_weights:
          type: object
          additionalProperties:
            type: number
          description: Weights for different metrics
          example:
            cases_passed: 1.0
            cases_total: 0.0

    TaskFlags:
      type: object
      properties:
        requires_sandbox:
          type: boolean
          description: Whether the task requires WASM sandbox
          example: false
        max_complexity:
          type: integer
          description: Maximum complexity level
          example: 3

    Budget:
      type: object
      required:
        - timeout
      properties:
        timeout:
          type: string
          description: Task timeout duration
          example: "30s"
        max_cost:
          type: number
          description: Maximum cost for the task
          example: 0.01

    Result:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: Whether the task was solved successfully
          example: true
        output:
          type: object
          description: Task output data
          example:
            sorted_numbers: [1, 2, 3]
        metrics:
          type: object
          additionalProperties:
            type: number
          description: Task metrics
          example:
            cases_passed: 1
            cases_total: 1
        cost:
          type: number
          description: Cost of solving the task
          example: 0.001
        duration:
          type: string
          description: Time taken to solve the task
          example: "150ms"
        error:
          type: string
          description: Error message if task failed
          example: "Invalid input data"

    Error:
      type: object
      required:
        - error
        - message
        - code
      properties:
        error:
          type: string
          description: Error type
          example: "InvalidInput"
        message:
          type: string
          description: Error message
          example: "Invalid task data provided"
        code:
          type: integer
          description: HTTP status code
          example: 400
        type:
          type: string
          description: Error type
          example: "InvalidInput"

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for authentication

tags:
  - name: Tasks
    description: Task solving operations
  - name: System
    description: System health and status operations