mistk-api.yaml

swagger: '2.0'
info:
  version: 1.0.0
  title: Model Integration Software ToolKit
basePath: /v1/mistk
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
  
paths:

##########################
# Model Plugin Endpoints #
##########################

  /initialize:
    post:
      operationId: initializeModel
      x-swagger-router-controller: mistk.model.service
      summary: Initialize the model
      description: Instructs the model instance to initialize.
      tags: [Model Instance Endpoint]
      parameters:
      - in: body
        name: initializationParameters
        description: >
          Initialization parameters for the model including the objectives, properties, and hparams.
          Objectives are a list of objectives for this model instance from the following options 
          {train, predict, stream_predict, generate, transfer_learning}.
          Properties are a dictionary of properties for this model instance. 
          Hparams are a dictionary of hyperparameters for this model instance.
        required: true
        schema:
          $ref: "../smlcore/sml-api.yaml#/definitions/ModelInstanceInitParams"
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"

  /loadData:
    post:
      operationId: loadData
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Loads data for the model
      description: Loads data onto a staging area for use by the model
      parameters:
      - in: body
        name: datasets
        description: >
          A dictionary mapping objectives to MistkDataset objects. 
          Dictionary keys must be one of the following {train, test, generate}
        required: true
        schema:
          type: object
          additionalProperties:
            schema:
              $ref: '#/definitions/MistkDataset'
          example:
            train:
              object_info:
                name: 'image_training_dataset'
                kind: 'MistkDataset'
              modality: 'image'
              format: 'image'
            test:
              object_info:
                name: 'image_testing_dataset'
                kind: 'MistkDataset'
              modality: 'image'
              format: 'image'
            generate:
              object_info:
                name: 'image_generation_dataset'
                kind: 'MistkDataset'
              modality: 'text'
              format: 'raw'
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"


  /buildModel:
    post:
      operationId: buildModel
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Build the model
      description: Instructs the container to construct the model
      parameters:
      - in: query
        name: modelPath
        description: >
          The absolute path to the directory where the model's checkpoint/snapshot
          file can be found. 
        required: false
        type: string        
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"

  /train:
    post:
      operationId: train
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Train the model
      description: Trains the model with the training dataset previously loaded
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"

  /saveModel:
    post:
      operationId: saveModel
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Save the model snapshot
      description: >
        Instructs the container to serialize the model to the specified path
      parameters:
      - in: query
        name: modelPath
        required: true
        type: string
        description: >
          A path pointing to the directory where the model is to be saved.
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"

  /predict:
    post:
      operationId: predict
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Perform predictions with the model
      description: Perform predictions with the test dataset previously loaded
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"

  /streamPredict:
    post:
      operationId: streamPredict
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Perform streaming predictions with the model
      description: Perform predictions with the test dataset previously loaded
      parameters:
      - in: body
        name: dataMap
        required: true
        description: Dictionary of IDs to b64 encoded data
        schema:
          type: object
          additionalProperties:
            type: string
      - name: details
        in: query
        description: >
          Boolean flag to indicate whether prediction details (markdown) should be included
          in predictions dictionary. 
        required: false
        type: boolean
        default: "False"  
      responses:
        '200':
          description: Dictionary of IDs to predictions
          schema:
            type: object
            additionalProperties: true
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"

  /updateStreamProperties:
    post:
      operationId: updateStreamProperties
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Updates streaming properties with the model
      description: Update streaming properties 
      parameters:
      - in: body
        name: props
        required: true
        description: Dictionary of metadata properties to be used by the model
        schema:
          type: object
          additionalProperties: true
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"

  /savePredictions:
    post:
      operationId: savePredictions
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Save the predictions made by the model
      description: >
        Instructs the container to save the predictions to the specified path
      parameters:
      - in: query
        name: dataPath
        required: true
        type: string
        description: >
          A path pointing to the directory where the
          predictions are to be saved.
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
  
  /generate:
    post:
      operationId: generate
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Perform generations with the model
      description: Perform generations with the model
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
  
  /saveGenerations:
    post:
      operationId: saveGenerations
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Save the generations made by the model
      description: >
        Instructs the container to save the generations to the specified path
      parameters:
      - in: query
        name: dataPath
        required: true
        type: string
        description: >
          A path pointing to the directory where the
          generations are to be saved.
      responses:
        '200':
          description: Returns 200 if the task was successfully submitted.
        '400':
          description: Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
          
  /pause:
    post:
      operationId: pause
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Pause the model
      description: >
        Instructs the container to pause the current training or 
        prediction activity
      responses:
        '200':
          description: >
            Returns 200 if the task was successfully submitted.
        '400':
          description: >
            Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"

  /resumeTraining:
    post:
      operationId: resumeTraining
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Resume training on a paused model
      description: >
        Resumes the training activity
      responses:
        '200':
          description: >
            Returns 200 if the task was successfully submitted.
        '400':
          description: >
            Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
          
  /resumePredict:
    post:
      operationId: resumePredict
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      summary: Resume predicitons on a paused model
      description: >
        Resumes the training activity
      responses:
        '200':
          description: >
            Returns 200 if the task was successfully submitted.
        '400':
          description: >
            Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"    
 
  /status:
    get:
      summary: Get the status of the model
      description: Retrieves the current status of the model
      x-swagger-router-controller: mistk.model.service
      tags: [Model Instance Endpoint]
      operationId: getStatus
      parameters:
        - name: watch
          description: >
            Watch for changes to the described resources and return them as a
            stream of add, update, and remove notifications.
            Specify resourceVersion.
          required: false
          in: query
          type: boolean
          default: "False"
        - name: resourceVersion
          description: >
            When specified with a watch call, shows changes that occur after
            that particular version of a resource. Defaults to changes from the
            beginning of history.
          required: false
          in: query
          type: integer
      responses:
        '200':
          description: Returns the status
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ModelInstanceStatus"

  /shutdown:
    post:
      operationId: terminate
      x-swagger-router-controller: mistk.model.service
      summary: Shut down the model
      description: Shuts down the model 
      tags: [Model Instance Endpoint]
      responses:
        '200':
          description: >
            Returns 200 if the task was successfully submitted.
        '400':
          description: >
            Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"

  /reset:
    post:
      operationId: reset
      x-swagger-router-controller: mistk.model.service
      summary: Resets the model
      description: Resets the model
      tags: [Model Instance Endpoint]
      responses:
        '200':
          description: >
            Returns 200 if the task was successfully submitted.
        '400':
          description: >
            Returns 400 if there is a task running when called.
          schema:
            $ref: "../smlcore/sml-api.yaml#/definitions/ServiceError"
        '500':
          description: General server runtime exception

  /apiVersion:
    get:
      operationId: getApiVersion
      x-swagger-router-controller: mistk.model.service
      summary: Returns the version of the MISTK API
      description: Returns the version of the MISTK API
      tags: [Model Instance Endpoint]
      responses:
        '200':
          description: >
            The MISTK API Version.
          schema:
            type: string
        '500':
          description: General server runtime exception
      

definitions:
  MistkDataset:
    allOf:
      - $ref: '../smlcore/sml-api.yaml#/definitions/Dataset'
      - type: object
        properties:
          dataPath:
            type: string
    example:
      objectInfo:
        name: 'example_dataset'
        kind: 'MistkDataset'
      dataPath: '/tmp'
      modality: 'image'
      format: 'image'
  MistkMetric:
    allOf:
      - $ref: '../smlcore/sml-api.yaml#/definitions/Metric'
  MistkMetricList:
    description: A list of Metrics.
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/MistkMetric'
      continueToken:
        type: string
  MistkDataRecord:
      allOf:
        - $ref: '../smlcore/sml-api.yaml#/definitions/DataRecord'
  MistkWatchEvent:
    allOf:
      - $ref: '../smlcore/sml-api.yaml#/definitions/WatchEvent'