openapi: 3.0.0
info:
  title: Single Inference API (chat_completion)
  version: 0.0.1
components:
  schemas:
    Tool:
      type: object
      description: A tool that can be used by an agent to perform specific tasks.
      properties:
        name:
          type: string
          description: The name of the tool.
        description:
          type: string
          description: A brief description of what the tool does and how it should be used.
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/ToolParameter'
        returnValue:
          $ref: '#/components/schemas/ToolReturnValue'
    ToolParameter:
      type: object
      properties:
        type:
          type: string
          enum: [string, int, float, list, bool]
          description: The data type of the parameter.
        itemType:
          type: string
          description: The type of items in the parameter if it is a list.
        description:
          type: string
          description: Details about what the parameter is used for and any constraints.
    ToolReturnValue:
      type: object
      properties:
        type:
          type: string
          enum: [string, int, float, list, bool]
          description: The data type of the return value.
        itemType:
          type: string
          description: The type of items in the return value if it is a list.
        description:
          type: string
          description: Details about the significance of the return value.
    Attachment:
      type: object
      properties:
        uri:
          type: string
          description: URI of the attachment.
        mime-type:
          type: string
          description: MIME type of the attachment.
    Message:
      type: object
      properties:
        role:
          type: string
          description: Role of the entity in the message.
        text:
          type: string
          description: Text content of the message.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    Completion:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the completion.
        role:
          type: string
          description: Role of the entity generating the completion.
        text:
          type: string
          description: Text content of the completion.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        tokens:
          type: array
          items:
            type: integer
        logprobs:
          type: array
          items:
            type: number
        finish_reason:
          type: string
          description: Reason for completion termination.
        # TODO: Add `tool_choice` --
        # for eg. "auto": use model's guess, how to force to use particular tool, how to disbale inbuilt tools
paths:
  /chat_completion/:
    post:
      summary: Submit a chat completion request
      description: Submit a chat completion request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    $ref: '#/components/schemas/Message'
                model:
                  type: string
                  description: Model identifier
                logprobs:
                  type: boolean
                  description: Whether to include log probabilities in the output
                max_tokens:
                  type: integer
                  description: Maximum number of tokens to generate
                n_completions:
                  type: integer
                  description: Number of completions to generate
                temperature:
                  type: number
                  format: float
                  description: Temperature setting for the generation
                top_p:
                  type: number
                  format: float
                  description: Top p setting for the generation
                tools:
                  type: array
                  items:
                    $ref: '#/components/schemas/Tool'
      responses:
        '200':
          description: Chat completion request processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for the completion request
                  completions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Completion'
                  model:
                    type: string
                    description: Model used for generating completions