openapi: 3.0.0
info:
  title: Atria Model Gateway server API
  description: API definition for model gateway
  version: 1.1.1
servers:
  - url: "http://localhost:6391"
    description: Local server
paths:
  /status:
    get:
      tags:
        - Basic management
      description: Returns info about status of API
      responses:
        "200":
          $ref: "#/components/responses/StatusResponse"
  /aura-services/v1/atria-model-gw/generate:
    post:
      tags:
        - Generate output
      description: Call the model to generate output
      parameters:
        - name: correlator
          in: header
          description: Correlation ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateRequest"
      responses:
        "200":
          $ref: "#/components/responses/GenerateResponse"
        "400":
          $ref: "#/components/responses/CommonError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/QuotaError"
        "500":
          $ref: "#/components/responses/InternalError"
  /aura-services/v1/atria-model-gw/presets:
    get:
      tags:
        - Preset management
      description: List presets
      parameters:
        - in: header
          name: correlator
          description: Correlation ID
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: application_name
          description: Application name
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          $ref: "#/components/responses/ListPresetsResponse"
        "400":
          $ref: "#/components/responses/CommonError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
  /aura-services/v1/atria-model-gw/preset/{preset}:
    get:
      tags:
        - Preset management
      description: List presets
      parameters:
        - in: path
          name: preset
          required: true
          description: Preset name
          schema:
            type: string
        - in: header
          name: correlator
          description: Correlation ID
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: application_name
          description: Application name
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          $ref: "#/components/responses/GetPresetResponse"
        "400":
          $ref: "#/components/responses/CommonError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
  /aura-services/v1/atria-model-gw/models:
    get:
      tags:
        - Models management
      description: "Return the list of models available for preset creation for the calling user"
      parameters:
        - in: header
          name: correlator
          description: Correlation ID
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: application_name
          description: Application name
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          $ref: "#/components/responses/ModelsResponse"
        "400":
          $ref: "#/components/responses/CommonError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
  /aura-services/v1/atria-model-gw/message/{session_id}:
    post:
      tags:
        - Feedback
      description: A method to send a custom message associated to a given session
      parameters:
        - in: path
          name: session_id
          description: Session ID
          required: true
          schema:
            type: string
            format: uuid
        - in: header
          name: correlator
          description: Correlation ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessageRequest"
      responses:
        "200":
          $ref: "#/components/responses/MessageResponse"
        "400":
          $ref: "#/components/responses/CommonError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
  /aura-services/v1/atria-model-gw/reset/{session_id}:
    get:
      tags:
        - Session management
      description: "This method is used to reset a session, i.e. make the backend forget all previous interactions for this session and start a new conversation"
      parameters:
        - in: path
          name: session_id
          description: Session ID
          required: true
          schema:
            type: string
            format: uuid
        - in: header
          name: correlator
          description: Correlation ID
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: application_name
          description: Application name
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          $ref: "#/components/responses/ResetResponse"
        "400":
          $ref: "#/components/responses/CommonError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
  /metrics:
    get:
      tags:
        - Prometheus metrics
      description: "Return the Prometheus metrics"
      responses:
        "200":
          description: "Prometheus metrics"
          content:
            text/plain:
              schema:
                type: string
                example: "# HELP http_request_duration_seconds Duration in seconds for all requests\n# TYPE http_request_duration_seconds summary\nhttp_request_duration_seconds_count{method=\"POST\",path=\"domain1\",status_code=\"200\",application=\"app_name\"} 1.0\nhttp_request_duration_seconds_sum{method=\"POST\",path=\"domain1\",status_code=\"200\",application=\"app_name\"} 32.0\n# TYPE http_request_duration_seconds_created gauge\nhttp_request_duration_seconds_created{method=\"POST\",path=\"/domain1\",status_code=\"200\",application=\"app_name\"} 1.7247525571283042e+09\n"
components:
  responses:
    StatusResponse:
      description: Status response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StatusSchema"
    GenerateResponse:
      description: Generate response
      headers:
        correlator:
          description: Correlation ID
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GenerateResponseSchema"
    GetPresetResponse:
      description: Get preset response
      headers:
        correlator:
          description: Correlation ID
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GetPresetResponseSchema"
    MessageResponse:
      description: Message response
      headers:
        correlator:
          description: Correlation ID
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MessageResponseSchema"
    ModelsResponse:
      description: Models response
      headers:
        correlator:
          description: Correlation ID
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ModelsResponseSchema"
    ResetResponse:
      description: Reset response
      headers:
        correlator:
          description: Correlation ID
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ResetResponseSchema"
    ListPresetsResponse:
      description: List presets response
      headers:
        correlator:
          description: Correlation ID
          schema:
            type: string
            format: uuid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListPresetsResponseSchema"
    CommonError:
      description: Incoming HTTP request produces an common error
      headers:
        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
      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
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuraError'
    QuotaError:
      description: Incoming HTTP request needs more quota
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        retry-after:
          description: Time to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuraError'
  schemas:
    AuraError:
      type: object
      required:
        - code
        - message
      description: Error response
      properties:
        code:
          type: string
          description: Unique id of the error
        message:
          type: string
          description: Specific and descriptive text of the error
    GenerateRequest:
      type: object
      required:
        - preset
        - query
        - application_name
      properties:
        application_name:
          type: string
          example: "app_name"
          description: Application ID
        preset:
          type: string
          example: openai_preset
          description: preset name
        reset:
          type: boolean
          example: true
          description: "If true, the session will be reset before processing the query"
        query:
          type: string
          example: "Qué es AURA?"
          description: "The query to be sent to the model"
        session_id:
          type: string
          example: "69e47ef8-253a-4f17-a572-5caf3aa8ba24"
          description: "Session ID"
        prompt_params:
          $ref: "#/components/schemas/PromptParamsSchema"
        model_params:
          $ref: "#/components/schemas/ModelParamsSchema"
        query_args:
          $ref: "#/components/schemas/QueryArgsSchema"
    PromptParamsSchema:
      type: object
      properties:
        preamble:
          type: string
          example: "Habla como si fueras Napoleón"
          description: "This will override (or add, if not defined) the system part of the prompt that was defined in the preset"
        template:
          type: string
          example: "Elimina los puntos y comas de la frase"
          description: "This will override (or add, if not defined) the template for the user message, as defined in the preset"
        examples:
          type: array
          example:
            - "example1"
            - "example2"
          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)"
    ModelParamsSchema:
      type: object
      description: "An object describing the model configuration for this preset. In order use a parameter, it must be defined in the preset config first"
      properties:
        max_tokens:
          type: number
          example: 200
          description: Max tokens to generate
        top_p:
          type: number
          example: 0.7
          description: A floating-point number between 0.0 and 1.0
        temperature:
          type: number
          example: 1.0
          description: A floating-point number between 0.0 and 2.0
        max_ref:
          type: number
          example: 3
          description: "Maximum number of returned references (a negative number means unbounded, which may be up to 4 times the number of retrievers)"
        language:
          type: string
          default: "en"
          example: "en"
          enum:
            - "en"
            - "es"
          description: "Two-letter ISO 639-1 code to select the language used by prompts"
        sticky_context:
          type: string
          example: "ask_llm"
          enum:
            - "ask_llm"
            - "include_context"
            - "recreate_question"
          description: >
            Strategy to include the context into the new query. If not specified, the optional context in the request is ignored:
              * ask_llm: an LLM-call is made to discern whether the context applies to the current query. If so, a recreate_question is performed, if not the context is ignored and a clear_context field is added into the response
              * include_context: the context will be inserted as is into the query 
              * recreate_question: an LLM-call will try to recreate the question by using the context
        candidates_post_filtering:
          type: string
          example: "llm_filter"
          enum:
            - "llm_filter"
          description: >
            If specified, a post-retrieval filtering is applied to the candidates. Valid option are :
             * llm_filter: for each candidate a very short request is made to the LLM requesting to identify whether the candidate is relevant to answer the query. If 'no' is decided, the candidate is filtered out
        candidates:
          type: boolean
          example: true
          default: false
          description: "Whether to return the candidates in raw (useful for evaluation purposes)"
        candidates_only:
          type: boolean
          example: true
          default: false
          description: "whether to run just the retrieval phase (if sticky_context is active an LLM-call may still be made)"
        clean_query:
          type: boolean
          example: true
          default: false
          description: "try to remove prompt injection attempts using an LLM call "
    QueryArgsSchema:
      type: object
      properties:
        media:
          type: array
          items:
            $ref: "#/components/schemas/MediaSchema"
        fields:
          type: object
          description: "A dictionary of parameters to be inserted into the user and/or system templates when building the prompt"
        query_id:
          type: string
          example: "cd2a00b5-5cdf-44a4-8d55-2b4f6ff75e33"
          description: "An identifier for this query, to be used to indicate it corresponds to a query suggestion sent by the server"
    MediaSchema:
      type: object
      anyOf:
        - properties:
            url:
              type: string
              example: "https://upload.wikimedia.org/wikipedia/commons/4/4b/Beach_and_cottages.jpg"
              description: An URL from which an image can be downloaded
          required:
            - url
        - properties:
            data:
              description: The contents of an image, as a base64-encoded string
              type: string
          required:
            - data
    ListPresetsResponseSchema:
      type: object
      required:
        - presets
        - default
        - groups
        - models
        - base_level
        - access
      properties:
        presets:
          type: array
          items:
            $ref: "#/components/schemas/PresetSimpleInfoSchema"
        default:
          type: string
          description: "Default preset for the user"
          example: "openai_preset"
        groups:
          type: array
          items:
            type: string
          description: "A list of the groups that the user has access to"
          example:
            - test
        models:
          type: array
          items:
            type: string
          description: "A list of the models that the user has access to"
          example:
            - openai
        base_level:
          type: string
          example: "USER"
        access:
          $ref: "#/components/schemas/UserAccessSchema"
    UserAccessSchema:
      type: object
      properties:
          prompt:
              type: boolean
              example: true
              description: "The user access level is at least USER"
          update:
              type: boolean
              example: true
              description: "The user access level is at least UPDATER"
          creator:
            type: boolean
            example: true
            description: "The user access level is at least CREATOR"
    UserAccessPresetSimpleSchema:
      type: object
      properties:
        prompt:
          type: boolean
          example: true
          description: "The user access level is at least USER"
        update:
          type: boolean
          example: true
          description: "The user access level is at least UPDATER"
    PresetSimpleInfoSchema:
      type: object
      required:
        - id
        - name
        - description
        - group
      properties:
        id:
          type: string
          description: Preset ID
          example: "openai_preset"
        name:
          type: string
          description: Preset name
          example: "openai"
        description:
          type: string
          description: Preset description
          example: "openai model"
        group:
          type: string
          enum:
            - "simple_ai"
            - "enriched_ai"
          description: Preset group
          example: simple_ai
    GetPresetResponseSchema:
      type: object
      required:
        - session_id
        - access
        - preset
        - model
      properties:
        session_id:
          type: string
          description: Session ID
          example: "69e47ef8-253a-4f17-a572-5caf3aa8ba24"
        access:
          $ref: "#/components/schemas/UserAccessPresetSimpleSchema"
        preset:
          $ref: "#/components/schemas/PresetDetailInfoSchema"
        model:
          $ref: "#/components/schemas/ModelSimpleInfoSchema"
        suggestions:
          type: array
          items:
            $ref: "#/components/schemas/SuggestionSchema"
    PresetDetailInfoSchema:
      allOf:
        - $ref: "#/components/schemas/PresetSimpleInfoSchema"
        - type: object
          required:
            - source
            - session_params
            - model_params
          properties:
            source:
              type: string
              example: "config"
              description: Indicates the source of the preset
            preamble:
              type: array
              items:
                  type: string
                  example: "Habla como si fueras Napoleón"
              description: Indicates the preamble of the preset when this not in the prompt params
            prompt_params:
              $ref: "#/components/schemas/PromptParamsSchema"
            session_params:
              $ref: "#/components/schemas/SessionParamsSchema"
            model_params:
              $ref: "#/components/schemas/ModelParamsSchema"
    ModelSimpleInfoSchema:
      type: object
      required:
        - id
        - type
        - name
      properties:
        id:
          type: string
          example: "openai_model"
          description: Model ID
        type:
          type: string
          example: "openai/azure"
          description: Model type
        name:
          type: string
          example: "openai"
          description: Model name
        description_params:
          type: object
          example: { "context_window": 300 }
          description: Model description params
    SuggestionSchema:
      type: object
      required:
        - id
        - category
        - value
      properties:
        id:
          type: string
          example: "cd2a00b5-5cdf-44a4-8d55-2b4f6ff75e33"
          description: Suggestion ID
        category:
          type: string
          example: "aura"
          description: Suggestion category
        value:
          type: string
          example: "Qué es AURA?"
          description: Suggestion value
    GenerateResponseSchema:
      type: object
      required:
        - session_id
        - input
        - output
        - sequence
      properties:
        session_id:
          type: string
          description: Session ID
          example: "69e47ef8-253a-4f17-a572-5caf3aa8ba24"
        input:
          type: string
          description: Repeats the user query
          example: "Hola, ¿qué es AURA?"
        output:
          type: string
          description: "main output: the text generated by the model"
          example: "¡Hola! AURA es una plataforma de IA que te permite interactuar con diferentes modelos de lenguaje. ¿En qué puedo ayudarte hoy?"
        media:
          type: array
          description: "In cases the response includes additional non-textual content, this will be a list of objects, each one describing a media item associated with the result"
          items:
            $ref: "#/components/schemas/MediaResponseSchema"
        references:
          type: array
          description: "In cases the response includes references, this will be a list of objects, each one describing a reference item associated with the result"
          items:
            $ref: "#/components/schemas/ReferenceResponseSchema"
        sizes:
          $ref: "#/components/schemas/GenerateResponseSizesSchema"
        sequence:
          type: number
        model_params:
          $ref: "#/components/schemas/ModelParamsSchema"
        session_params:
          $ref: "#/components/schemas/SessionParamsSchema"
        prompt:
          type: array
          items:
            $ref: "#/components/schemas/PromptSchema"
    DataItemResponseSchema:
      type: object
      properties:
        url:
          type: string
          example: "https://upload.wikimedia.org/wikipedia/commons/4/4b/Beach_and_cottages.jpg"
          description: An URL from which an image can be downloaded
        data:
          type: string
          description: The contents of an image, as a base64-encoded string
        content-type:
          type: string
          example: "image/jpeg"
          description: The MIME type of the media content
        display:
          type: string
          enum:
            - "inline"
            - "link"
          example: "inline"
          description: "The intended method to render the element: either inline or link"
        title:
          type: string
          example: "Beach and cottages"
          description: "A text title for the item. If not present, the last path component in the URL should be used"
        metadata:
          type: object
          example: { "page-number": 1 }
          description: "Additional fields describing the item and its relation to the model result"
    MediaResponseSchema:
      $ref: "#/components/schemas/DataItemResponseSchema"
    ReferenceResponseSchema:
      $ref: "#/components/schemas/DataItemResponseSchema"
    PromptSchema:
      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"
    GenerateResponseSizesSchema:
      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
          example: 11
        prompt:
          type: number
          description: Number of tokens in the prompt
          example: 9
        total:
          type: number
          description: Total number of tokens involved in the generation
          example: 20
    SessionParamsSchema:
      type: object
      description: "An object describing the session configuration for this preset (including the size of the session window, in the field window)"
      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"
    StatusOutputSchema:
      type: object
      required:
        - status
        - start
        - runtime
        - server_name
        - app_version
      properties:
        status:
          type: boolean
        start:
          type: string
          example: "2022-01-01T00:00:00Z"
        runtime:
          type: string
          example: "0:10:51.087357"
        server_name:
          type: string
          example: "server_name"
        app_version:
          type: string
          example: "1.0.0"
    MessageRequest:
      type: object
      required:
        - type
        - user_ok
        - application_name
        - msg_corrid
      properties:
        type:
          type: string
          enum:
            - feedback
          description: A string with content feedback
        user_ok:
          type: boolean
          description: "An indicator true/false that signals whether the user considers the response good or not"
        application_name:
          type: string
          example: "app_name"
          description: Application ID
        msg_corrid:
          type: string
          example: "79e2646a-a8bb-4355-b79f-42722c066155"
          description: Message correlator
    MessageResponseSchema:
      type: object
      required:
        - session_id
        - command
        - data
      properties:
        session_id:
          type: string
          example: "69e47ef8-253a-4f17-a572-5caf3aa8ba24"
          description: Session ID
        command:
          type: string
          example: "message"
          description: A fixed string with the value message
        data:
          $ref: "#/components/schemas/DataMessageResponseSchema"
    DataMessageResponseSchema:
      type: object
      required:
          - type
          - user_ok
          - application_name
      properties:
        type:
            type: string
            description: A string with content feedback
        user_ok:
            type: boolean
            description: "An indicator true/false that signals whether the user considers the response good or not"
        application_name:
          type: string
          example: "app_name"
          description: Application name
    ResetResponseSchema:
      type: object
      required:
        - session_id
        - command
        - preset
      properties:
        session_id:
          type: string
          example: "69e47ef8-253a-4f17-a572-5caf3aa8ba24"
          description: Session ID
        command:
          type: string
          example: reset
          description: A fixed string with the value reset
        preset:
          type: string
          example: openai_preset
          description: the preset that will be active for this session
    ModelsResponseSchema:
      type: object
      required:
        - models
      properties:
        models:
          type: array
          items:
            $ref: "#/components/schemas/ModelSimpleInfoSchema"
    StatusSchema:
      type: object
      required:
        - output
      properties:
        output:
          $ref: "#/components/schemas/StatusOutputSchema"