openapi: 3.0.2
info:
  version: 0.0.1
  title: RxInferServer OpenAPI specification
  description: |
    API for RxInferServer.jl - A Julia server for RxInfer probabilistic programming framework
    **Warning** The specification is not yet stable and may undergo significant changes.
  contact:
    name: RxInferServer Team
    url: https://github.com/lazydynamics/RxInferServer
  license:
    name: AGPL-3.0
    url: https://github.com/lazydynamics/RxInferServer/blob/main/LICENSE
externalDocs:
  description: RxInferServer official documentation
  url: https://server.rxinfer.com/
servers:
  - url: 'http://localhost:{port}/{basePath}'
    description: Local development server
    variables:
      port:
        default: '8000'
        description: The port of the local server, defaults to "8000"
      basePath:
        default: 'v1'
        description: The base path of the server, defaults to "v1"
  - url: 'https://rxinfer.lazydynamics.app/{basePath}'
    description: Public server provided by Lazy Dynamics team - https://lazydynamics.com/
    variables:
      basePath:
        default: 'v1'
        description: The base path of the server, defaults to "v1"
tags:
  - name: Server
    description: Server management endpoints
  - name: Authentication
    description: Authentication related endpoints
  - name: Models
    description: Model management endpoints
# Global security - apply to all endpoints by default
security:
  - ApiKeyAuth: []
paths:
  /info:
    get:
      tags:
        - Server
      summary: Get server information
      operationId: getServerInfo
      description: Returns information about the server, such as the RxInferServer version, RxInfer version, Julia version, server edition and API version
      responses:
        '200':
          description: Successfully retrieved server information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInfo'
              examples:
                known_versions:
                  value:
                    rxinfer_version: "4.2.0"
                    server_version: "1.0.0-DEV"
                    server_edition: "CommunityEdition"
                    julia_version: "1.11.3"
                    api_version: "v1"
                unknown_versions:
                  value:
                    rxinfer_version: "unknown"
                    server_version: "unknown" 
                    server_edition: "CommunityEdition"
                    julia_version: "1.11.3"
                    api_version: "v1"
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'

  /ping:
    get:
      tags:
        - Server
      summary: Health check endpoint
      operationId: pingServer
      description: Simple endpoint to check if the server is alive and running
      # This endpoint doesn't require authentication
      security: []
      responses:
        '200':
          description: Successfully pinged the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
              example:
                status: "ok"

  /token/generate:
    post:
      tags:
        - Authentication
      summary: Generate authentication token
      operationId: tokenGenerate
      description: Generates a new authentication token for accessing protected endpoints
      # This endpoint doesn't require authentication
      security: []
      responses:
        '200':
          description: Successfully generated authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenGenerateResponse'
        '400':
          description: Unable to generate token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Bad Request"
                message: "Unable to generate token due to internal error"
  /token/roles:
    get:
      tags:
        - Authentication
      summary: Get token roles
      operationId: tokenRoles
      description: Retrieve the list of roles for a specific token
      responses:
        '200':
          description: Successfully retrieved token roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRolesResponse'
              examples:
                user:
                  value:
                    roles:
                      - "user"
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'

  /models/available:
    get:
      tags:
        - Models
      summary: Get models available for creation
      operationId: getAvailableModels
      description: |
        Retrieve the list of models available for creation for a given token.
        This list specifies names and available arguments for each model.
        
        **Note** The list of available models might differ for different access tokens.
        For example, a token with only the "user" role might not have access to all models.
      responses:
        '200':
          description: Successfully retrieved list of models available for creation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvailableModel'
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'

  /models/available/{model_name}:
    get:
      tags:
        - Models
      summary: Get information about a specific model available for creation
      operationId: getAvailableModel
      description: Retrieve detailed information about a specific model available for creation
      parameters:
        - name: model_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the model to retrieve information for (including version identifier if applicable, e.g. "BetaBernoulli-v1")
      responses:
        '200':
          description: Successfully retrieved model details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableModel'
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model cannot be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
  
  /models/create-instance:
    post:
      tags:
        - Models
      summary: Create a new model instance
      operationId: createModelInstance
      description: Creates a new instance of a model with the specified configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelInstanceRequest'
      responses:
        '200':
          description: Model instance created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateModelInstanceResponse'
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'

  /models/instances:
    get:
      tags:
        - Models
      summary: Get all created model instances
      operationId: getModelInstances
      description: Retrieve detailed information about all created model instances for a specific token
      responses:
        '200':
          description: Successfully retrieved list of created model instances
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ModelInstance'
        '401':
          description: Access token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'

  /models/i/{instance_id}:
    get:
      tags:
        - Models
      summary: Get model instance information
      operationId: getModelInstance
      description: Retrieve detailed information about a specific model instance
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to retrieve information for
      responses:
        '200':
          description: Successfully retrieved model information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelInstance'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
    delete:
      tags:
        - Models
      summary: Delete a model instance
      operationId: deleteModelInstance
      description: Delete a specific model instance by its ID
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to delete
      responses:
        '200':
          description: Model successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                message: "Model deleted successfully"
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
    
  /models/i/{instance_id}/state:
    get:
      tags:
        - Models
      summary: Get the state of a model instance
      operationId: getModelInstanceState
      description: Retrieve the state of a specific model instance
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to retrieve state for
      responses:
        '200':
          description: Successfully retrieved model state. Each model has its own state, which is a dictionary of arbitrary key-value pairs. Check model-specific documentation for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelInstanceState'
        '400':
          description: Model state cannot be retrieved due to internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'

  /models/i/{instance_id}/parameters:
    get:
      tags:
        - Models
      summary: Get the parameters of a model instance (current episode)
      operationId: getModelInstanceParameters
      description: Retrieve the parameters of a specific model instance. These parameters reflect the current episode's learned parameters.
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved model parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelInstanceParameters'
        '400':
          description: Model parameters cannot be retrieved due to internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
  /models/i/{instance_id}/infer:
    post:
      tags:
        - Models
      summary: Run inference
      operationId: runInference
      description: Run inference on a specific model instance
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to run inference on
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InferRequest'
      responses:
        '200':
          description: Successfully ran inference on the model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferResponse'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json: 
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'

  /models/i/{instance_id}/learn:
    post:
      tags:
        - Models
      summary: Learn from previous observations
      operationId: runLearning
      description: Learn from previous episodes for a specific model
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LearnRequest'
      responses:
        '200':
          description: Successfully ran learning on the model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LearnResponse'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'    

  /models/i/{instance_id}/create-episode:
    post:
      tags:
        - Models
      summary: Create a new episode for a model instance
      operationId: createEpisode
      description: | 
        Create a new episode for a specific model instance.
        Note that the default episode is created automatically when the model instance is created. 
        When a new episode is created, it becomes the current episode for the model instance.
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to create episode for
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEpisodeRequest'
      responses:
        '200':
          description: Successfully created episode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeInfo'
        '400':
          description: Episode cannot be created, e.g. it already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Bad Request"
                message: "The requested episode already exists"
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'  

  /models/i/{instance_id}/episodes:
    get:
      tags:
        - Models
      summary: Get all episodes for a model instance
      operationId: getEpisodes
      description: Retrieve all episodes for a specific model instance
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to retrieve episodes for
      responses:
        '200':
          description: Successfully retrieved list of episodes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EpisodeInfo'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'

  /models/i/{instance_id}/episodes/{episode_name}:
    get:
      tags:
        - Models
      summary: Get episode information
      operationId: getEpisodeInfo
      description: Retrieve information about a specific episode of a model
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to retrieve episode for
        - name: episode_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the episode to retrieve
      responses:
        '200':
          description: Successfully retrieved episode information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeInfo'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model or episode not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
    delete:
      tags:
        - Models
      summary: Delete an episode for a model
      operationId: deleteEpisode
      description: | 
        Delete a specific episode for a model instance.
        Note that the default episode cannot be deleted, but you can wipe data from it.
        If the deleted episode was the current episode, the default episode will become the current episode.
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to delete episode for
        - name: episode_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the episode to delete
      responses:
        '200':
          description: Successfully deleted episode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Episode cannot be deleted, e.g. it is the default episode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Bad Request"
                message: "Default episode cannot be deleted, wipe data instead"
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model or episode not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'

  /models/i/{instance_id}/episodes/{episode_name}/attach-events:
    post:
      tags:
        - Models
      summary: Attach events to an episode
      operationId: attachEventsToEpisode
      description: Attach events to a specific episode for a model
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to attach events to
        - name: episode_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the episode to attach events to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachEventsToEpisodeRequest'
      responses:
        '200':
          description: Successfully attached events to the episode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request, e.g. invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model or episode not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'

  /models/i/{instance_id}/episodes/{episode_name}/wipe:
    post:
      tags:
        - Models
      summary: Wipe all events from an episode
      operationId: wipeEpisode
      description: Wipe all events from a specific episode for a model
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to wipe episode for
        - name: episode_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the episode to wipe
      responses:
        '200':
          description: Successfully wiped episode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model or episode not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'    

  /models/i/{instance_id}/episodes/{episode_name}/events/{event_id}/attach-metadata:
    post:
      tags:
        - Models
      summary: Attach metadata to an event
      operationId: attachMetadataToEvent
      description: Attach metadata to a specific event for a model
      parameters:
        - name: instance_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the model instance to attach metadata to
        - name: episode_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the episode to attach metadata to
        - name: event_id
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: ID of the event to attach metadata to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachMetadataToEventRequest'
      responses:
        '200':
          description: Successfully attached metadata to the event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Access token is missing, invalid or has no access to the specific model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: Model or episode not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
                      
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: Simple token authentication. Use the Authorization header with the Bearer scheme.
  schemas:
    SuccessResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Success message
      example:
        message: "Model deleted successfully"

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message explaining the failure
        message:
          type: string
          description: Additional message providing details about the failure
      example:
        error: "Unauthorized"
        message: "The request requires authentication, generate a token using the /generate-token endpoint"

    NotFoundResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error type, always "Not Found" for this error
          enum: ["Not Found"]
        message:
          type: string
          description: Detailed message explaining why the resource was not found
      example:
        error: "Not Found"
        message: "The requested resource could not be found"

    UnauthorizedResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error type, always "Unauthorized" for this error
          enum: ["Unauthorized"]
        message:
          type: string
          description: Detailed message explaining why authentication failed
      example:
        error: "Unauthorized"
        message: "The request requires authentication, generate a token using the /generate-token endpoint"

    PingResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: Status of the server
          default: "ok"

    ServerInfo:
      type: object
      required:
        - rxinfer_version
        - server_version
        - server_edition
        - julia_version
        - api_version
      properties:
        rxinfer_version:
          type: string
          description: The version of RxInfer that the server is using, returns unknown if the version is unknown or hidden
        server_version:
          type: string
          description: The version of the RxInferServer, returns unknown if the version is unknown or hidden
        server_edition:
          type: string
          description: The edition of the RxInferServer, as set in RXINFER_EDITION environment variable
        julia_version:
          type: string
          description: The version of Julia as presented in VERSION
        api_version:
          type: string
          description: The version of the API being used
          default: "v1"

    TokenGenerateResponse:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: The token to use in the Authorization header with the format "Bearer {token}"

    TokenRolesResponse:
      type: object
      required:
        - roles
      properties:
        roles:
          type: array
          description: List of roles for the token
          items:
            type: string
            description: Role identifier
          example:
            - "user"

    AvailableModel:
      type: object
      required:
        - details
        - config
      properties:
        details:
          type: object
          description: | 
            Primary model details. Note that these are also included in the `config` object.
          properties:
            name:
              type: string
              description: Name of the model (usually with the version identifier, e.g. "BetaBernoulli-v1")
            description:
              type: string
              description: Brief description of the model
            author:
              type: string
              description: Author of the model
            roles:
              type: array
              description: List of roles that can access the model
              items:
                type: string
                description: Role identifier
        config:
          type: object
          description: |
            The entire model configuration as in the `config.yaml` file. 
            May include arbitrary fields, which are not part of the public interface.
            Note that this information also includes the properties from the `details` object.
          additionalProperties: true

    CreateModelInstanceRequest:
      type: object
      required:
        - model_name
      properties:
        model_name:
          type: string
          description: The name of the model to create (including version identifier if applicable, e.g. "BetaBernoulli-v1")
        arguments:
          type: object
          description: Model-specific configuration arguments
          additionalProperties: true
        description:
          type: string
          maxLength: 128
          description: Optional description of the model instance

    CreateModelInstanceResponse:
      type: object
      required:
        - instance_id
      properties:
        instance_id:
          type: string
          format: uuid
          description: Unique identifier for the created model instance

    ModelInstance:
      type: object
      required:
        - instance_id
        - model_name
        - created_at
        - description
        - arguments
        - current_episode
      properties:
        instance_id:
          type: string
          format: uuid
          description: Unique identifier for the created model instance
        model_name:
          type: string
          description: Name of the model (including version identifier if applicable, e.g. "BetaBernoulli-v1")
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the model was created
        description:
          type: string
          description: Description of the created model instance
        arguments:
          type: object
          description: Model-specific configuration arguments
          additionalProperties: true
        current_episode:
          type: string
          description: Name of the current episode for this model
          example: "default"

    DeleteModelInstanceRequest:
      type: object
      required:
        - instance_id
      properties:
        instance_id:
          type: string
          format: uuid
          description: ID of the model instance to delete

    ModelInstanceState:
      type: object
      required:
        - state
      properties:
        state:
          type: object
          description: |
            An object containing the current state of the model instance. 
            May include arbitrary fields specific to the model. See the model documentation for more details.
          additionalProperties: true

    ModelInstanceParameters:
      type: object
      required:
        - parameters
      properties:
        parameters:
          type: object
          description: |
            An object containing the current parameters of the model instance.
            The keys are the parameter names as defined in the model configuration, and the values are the parameter values.
          additionalProperties: true

    InferRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          description: Model-specific data to run inference on
          additionalProperties: true
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the inference request, used to mark the event in the episode
          example: "2024-03-20T12:00:00Z"
        episode_name:
          type: string
          description: Name of the episode to run inference on
          default: "default"
          example: "default"

    InferResponse:
      type: object
      required:
        - event_id
        - results
        - errors
      properties:
        event_id:
          type: integer
          format: int64
          description: Unique identifier for the inference event
        results:
          type: object
          description: Model-specific results of the inference
          additionalProperties: true
        errors:
          type: array
          description: List of errors that occurred during the inference call, but were not fatal and the inference was still completed successfully
          items:
            $ref: '#/components/schemas/ErrorResponse'
    
    LearnRequest:
      type: object
      required:
        - episodes
      properties:
        episodes:
          type: array
          description: List of episodes to learn from
          default: ["default"]
          items:
            type: string
        relearn:
          type: boolean
          description: If true, reset episode parameters and process all events from scratch. If false, only process unprocessed events for incremental learning.
          default: false

    LearnResponse:
      type: object
      required:
        - learned_parameters
      properties:
        learned_parameters:
          type: object
          description: A dictionary of learned parameters and their values
          additionalProperties: true

    CreateEpisodeRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the episode to create

    EpisodeInfo:
      type: object
      required:
        - instance_id
        - episode_name
        - created_at
        - events
        - parameters
      properties:
        instance_id:
          type: string
          format: uuid
          description: ID of the model instance this episode belongs to
        episode_name:
          type: string
          description: Name of the episode
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the episode was created
        events:
          type: array
          description: List of events that have occurred in the episode
          items:
            type: object
            additionalProperties: true
        parameters:
          type: object
          description: Learned parameters of the episode
          additionalProperties: true
      example:
        instance_id: "123e4567-e89b-12d3-a456-426614174000"
        episode_name: "default"
        created_at: "2024-03-20T12:00:00Z"
        events: []
        parameters: {}

    AttachEventsToEpisodeRequest:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          description: List of events to attach to the episode
          items:
            type: object
            properties:
              timestamp:
                type: string
                format: date-time
                description: Timestamp of the event
              data:
                type: object
                description: Arbitrary data to attach to the event, model-specific
                additionalProperties: true
              metadata:
                type: object
                description: Arbitrary metadata to attach to the event, model-specific
                additionalProperties: true
              processed:
                type: boolean
                description: Whether this event has been used in a learning procedure
                default: false

    AttachMetadataToEventRequest:
      type: object
      required:
        - metadata
      properties:
        metadata:
          type: object
          description: Metadata to attach to the event
          additionalProperties: true