openapi: 3.0.0
info:
  title: generative API
  description: Set of endpoints related to generative-api
  contact:
    email: auradev@tid.es
tags:
  - name: generative
    description: Endpoints related to generative-api.
servers:
  - url: "http://localhost:8989"
    description: Local server
  - url: "https://svc-ap-current.auracognitive.com"
    description: ap-current
paths:
  /aura-services/v2/aiservices/generative/prompts:
    post:
      tags:
        - generative
      description: Generate new prompt and sent it to OpenAI.
      operationId: postPrompts
      x-router-controller: routes
      security:
        - ApiKeyHeaderAuth: []
      parameters:
        - name: correlator
          in: header
          description: Unique identifier of a request to be used as correlator in all systems
          required: false
          schema:
            type: string
            format: uuid
        - name: x-token-info
          in: header
          description:
            User authentication data. It might contain JWT object, plain or
            encoded (to keep backwards compatibility).
          required: true
          schema:
            type: string
        - name: x-correlator
          in: header
          description:
            unique identifier of a request to be used as correlator in all
            systems
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerativeApiMessage"
            example:
              message: "What is aura?"
              application:
                id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
                preset: "openai-gpt-3"
      responses:
        "200":
          $ref: "#/components/responses/ValidRequestGenerative"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
components:
  responses:
    ValidRequestGenerative:
      description: Incoming HTTP request format is valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GenerativeApiResponse"
          example:
            message: "Hello I am Aura, how can I help you?"
            session:
              id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
              sequence: 1
              parameters:
                window: 10
                timeout: 30
            prompt_info:
              sizes:
                completion: 100
                prompt: 50
                total: 150
              model_params:
                max_tokens: 100
                temperature: 0.5
                top_p: 0.5
              prompt:
                - role: "user"
                  content: "I want to know more about the beach"
              input: "I want to know more about the beach"
    InvalidRequest:
      description: Incoming HTTP request format is not valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    Unauthorized:
      description: Incoming HTTP request authorization is not valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    NotFound:
      description: Incoming HTTP request is not found
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    InternalError:
      description: Incoming HTTP request produces an internal error
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
    TooManyRequests:
      description: The user has sent too many requests in a given amount of time
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuraError"
  securitySchemes:
    ApiKeyHeaderAuth:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    AuraError:
      type: object
      description: Error response
      properties:
        code:
          type: string
          description: Unique id of the error
        message:
          type: string
          description: Specific and descriptive text of the error
        errors:
          description: With validation error. Swagger error information
          type: array
          items:
            type: object
    BasicMessage:
      type: object
      description: Contains the basic object message to be sent
      required:
        - message
      properties:
        message:
          type: string
          description: Contains the message to be sent
          pattern: '^(?!\s*$).+'
          minLength: 1
    GenerativeApiMessage:
      description: Contains the message to be sent to the generative API
      allOf:
        - $ref: "#/components/schemas/BasicMessage"
        - type: object
          required:
            - application
            - message
          properties:
            userId:
              type: string
              description: Identifier of the user sending the message
            application:
              $ref: "#/components/schemas/ApplicationGenerative"
            session_id:
              description: Contains the session id. Unique string to identify the session. If not provided, a new session will be created.
              allOf:
                - $ref: "#/components/schemas/StringWithoutSpaces"
            reset:
              type: boolean
              example: true
              description: If true, the session will be reset before processing the query. All previous requests will be deleted of the context.
            prompt_params:
              $ref: "#/components/schemas/PromptParams"
            model_params:
              type: object
              description: Contains parameters to configure the request to the llm.
              minProperties: 1
              additionalProperties: true
    Application:
      type: object
      description: Contains the application who is sending the message
      anyOf:
        - properties:
            id:
              description: The application identifier
              type: string
          required:
            - id
        - properties:
            name:
              description: The application name
              type: string
          required:
            - name
    ApplicationGenerative:
      description: Contains the application who is sending the generative message
      allOf:
        - $ref: "#/components/schemas/Application"
        - type: object
          required:
            - preset
          properties:
            preset:
              type: string
              description: The preset to use for this application
    PromptParams:
      type: object
      description: Contains the prompt parameters to be used
      properties:
        preamble:
          type: string
          description: This will override the system part of the prompt that was defined in the preset
          example: "I am Aura, how can I help {name} ?"
        template:
          type: string
          description: "This will override (or add, if not defined) the template for the user message, as defined in the preset (note: templates allow framing the user message to mitigate prompt injection attacks)"
        fields_mapped:
          type: object
          description: >-
            A dictionary of parameters to be inserted into the user and/or system templates when building the prompt
            With this example, the preamble will be "I am Aura, how can I help John ?"
          example:
            name: "John"
        examples:
          type: array
          description: "This will override (or add, if not defined) the examples added to the system prompt, as defined in the preset. Note: they can also be included at the end of the preamble, with the same effect)"
          items:
            type: string
            description: "This will override (or add, if not defined) the examples added to the system prompt, as defined in the preset. Note: they can also be included at the end of the preamble, with the same effect)"
    SessionParams:
      type: object
      description: Contains the session parameters
      properties:
        window:
          type: number
          example: 2
          description: The size of the session window, in queries
        timeout:
          type: number
          example: 3600
          description: The time in seconds after which the session will be closed if no queries are received
    Session:
      type: object
      description: Contains the session information
      required:
        - id
        - sequence
      properties:
        id:
          description: session identifier. Unique string that identifies the session.
          allOf:
            - $ref: "#/components/schemas/StringWithoutSpaces"
        sequence:
          type: number
          description: The sequence number message of the session
        parameters:
          $ref: "#/components/schemas/SessionParams"
    PromptInfo:
      type: object
      description: Contains the prompt information
      required:
        - input
      properties:
        sizes:
          $ref: "#/components/schemas/GenerateResponseSizes"
        model_params:
          type: object
          description: Contains parameters to configure the request to the llm.
          minProperties: 1
          additionalProperties: true
        prompt:
          description: The prompts used to generate the output
          type: array
          items:
            $ref: "#/components/schemas/Prompt"
        input:
          type: string
          description: Repeats the user query
    Prompt:
      type: object
      description: The prompt used to generate the output
      required:
        - role
        - content
      properties:
        role:
          type: string
          description: "The role of the prompt: either user or system"
        content:
          type: string
          description: The text of the prompt
    GenerateResponseSizes:
      description: A dictionary containing the number of input, output and total tokens involved in the generation
      type: object
      required:
        - completion
        - prompt
        - total
      properties:
        completion:
          type: number
          description: Number of tokens in the completion
        prompt:
          type: number
          description: Number of tokens in the prompt
        total:
          type: number
          description: Total number of tokens involved in the generation
    GenerativeApiResponse:
      description: >-
        Message response
      type: object
      required:
        - message
        - session
      properties:
        message:
          description: Contains the message.
          type: string
        session:
          $ref: "#/components/schemas/Session"
        prompt_info:
          $ref: "#/components/schemas/PromptInfo"
        references:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Reference"
    StringWithoutSpaces:
      type: string
      description: Regular expresion of string without spaces
      example: "79e2646a-a8bb-4355-b79f-42722c066155"
      pattern: '^\S+$'
      minLength: 1
    Reference:
      type: object
      description: Contains the reference information
      required:
        - title
      properties:
        url:
          type: string
          description: The url of the file that has been used to generate the response
          example: "https://my.server.org/docs/project/example-data.pdf"
        title:
          type: string
          description: The name of the document that has been used to generate the response
          example: "example-data.pdf"
        metadata:
          type: object
          description: The metadata of the document that has been used to generate the response
          example: { "page-number": 1 }
