feat(specs): predict model endpoints

specs/predict/common/parameters.yml

@@ -5,3 +5,11 @@ userID:
   schema:
     type: string
   description: User ID for authenticated users or cookie ID for non-authenticated repeated users (visitors).
+
+modelID:
+  name: modelID
+  in: path
+  required: true
+  schema:
+    type: string
+  description: The ID of the model to retrieve.

specs/predict/common/schemas/modelsParams.yml

@@ -0,0 +1,76 @@
+activateModelParams:
+  type: object
+  properties:
+    type:
+      $ref: '../../common/schemas/Params.yml#/modelsToRetrieve'
+    name:
+      $ref: '#/name'
+    sourceID:
+      $ref: '#/sourceID'
+    index:
+      $ref: '#/index'
+    affinities:
+      type: array
+      items:
+        $ref: '#/affinities'
+    contentAttributes:
+      type: array
+      items:
+        $ref: '#/contentAttributes'
+  required:
+    - type
+    - name
+    - sourceID
+    - index
+
+updateModelParams:
+  type: object
+  properties:
+    name:
+      $ref: '#/name'
+    affinities:
+      type: array
+      items:
+        $ref: '#/affinities'
+    contentAttributes:
+      type: array
+      items:
+        $ref: '#/contentAttributes'
+    status:
+      $ref: '#/status'
+  required:
+    - modelID
+    - sourceID
+    - index
+
+type:
+  type: string
+  enum: ['funnel_stage', 'order_value', 'affinities']
+  description: The model's type.
+
+name:
+  type: string
+  description: The model’s instance name.
+
+sourceID:
+  type: string
+  description: The data source ID, as returned by the (external) sources API.
+
+index:
+  type: string
+  description: The index name.
+
+affinities:
+  type: string
+  description: List of items attributes that will be used as affinities. This param is required if `type=affinities`.
+
+contentAttributes:
+  type: string
+  description: List of items attributes that will be used for embeddings, for ex. titles or descriptions.
+
+status:
+  type: string
+  enum: [active, inactive]
+  description: |
+    `active` - model is running and generating predictions. The active value is allowed only if the current status of the model is `inactive`. \
+    `inactive` - model training and inference have been paused. The inactive value is allowed only if the current status of the model is `active`.

specs/predict/paths/models/getAvailableModelTypes.yml

@@ -0,0 +1,53 @@
+get:
+  tags:
+    - models
+  operationId: getAvailableModelTypes
+  summary: Get a list of available model types.
+  description: Get a list of all available model types. Each model type can be activated more than once, by selecting a different data source.
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: getAvailableModelTypesResponse
+            type: array
+            items:
+              type: object
+              additionalProperties: false
+              properties:
+                name:
+                  type: string
+                  description: Name of the model.
+                type:
+                  type: string
+                  description: Description of the model.
+                compatibleSources:
+                  type: array
+                  items:
+                    type: string
+                    $ref: '../../responses/ModelTypes.yml#/compatibleSources'
+                dataRequirements:
+                  type: object
+                  additionalProperties: false
+                  properties:
+                    minUsers:
+                      type: integer
+                      description: Minimum number of users required for this model.
+                    minDays:
+                      type: integer
+                      description: Minimum number of days model needs to run.
+                  required:
+                    - minUsers
+                    - minDays
+              required:
+                - name
+                - type
+                - compatibleSources
+                - dataRequirements
+    '401':
+      $ref: '../../responses/InvalidCredentials.yml'
+    '422':
+      $ref: '../../../common/responses/UnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'

specs/predict/paths/models/getModelMetrics.yml

@@ -0,0 +1,26 @@
+get:
+  tags:
+    - models
+  operationId: getModelMetrics
+  summary: Get a model’s instance metrics.
+  description: Get the model instance’ training metrics.
+  parameters:
+    - $ref: '../../common/parameters.yml#/modelID'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: getModelMetricsResponse
+            type: array
+            items:
+              $ref: '../../responses/Models.yml#/modelMetrics'
+    '401':
+      $ref: '../../responses/InvalidCredentials.yml'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '422':
+      $ref: '../../../common/responses/UnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'

specs/predict/paths/models/modelInstances.yml

@@ -0,0 +1,101 @@
+get:
+  tags:
+    - models
+  operationId: getModelInstanceConfig
+  summary: Get a model’s instance configuration.
+  description: Get the configuration for a model that was activated.
+  parameters:
+    - $ref: '../../common/parameters.yml#/modelID'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: getModelInstanceConfigResponse
+            $ref: '../../responses/Models.yml#/modelInstance'
+    '401':
+      $ref: '../../responses/InvalidCredentials.yml'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '422':
+      $ref: '../../../common/responses/UnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'
+
+post:
+  tags:
+    - models
+  operationId: updateModelInstance
+  summary: Update a model instance.
+  description: Update a model’s configuration.
+  parameters:
+    - $ref: '../../common/parameters.yml#/modelID'
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../../common/schemas/modelsParams.yml#/updateModelParams'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: updateModelInstanceResponse
+            type: object
+            additionalProperties: false
+            properties:
+              modelID:
+                type: string
+                description: The ID of the model.
+              updatedAt:
+                $ref: '../../../common/responses/common.yml#/updatedAt'
+            required:
+              - modelID
+              - updatedAt
+    '401':
+      $ref: '../../responses/InvalidCredentials.yml'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '422':
+      $ref: '../../../common/responses/UnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'
+
+delete:
+  tags:
+    - models
+  operationId: deleteModelInstance
+  summary: Delete a model instance.
+  description: Delete the model’s configuration, pipelines and generated predictions.
+  parameters:
+    - $ref: '../../common/parameters.yml#/modelID'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: deleteModelInstanceResponse
+            type: object
+            additionalProperties: false
+            properties:
+              modelID:
+                type: string
+                description: The ID of the model.
+              deletedUntil:
+                type: string
+                description: The date until which you can safely consider the data as being deleted.
+            required:
+              - modelID
+              - deletedUntil
+    '401':
+      $ref: '../../responses/InvalidCredentials.yml'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'
+    '422':
+      $ref: '../../../common/responses/UnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'

specs/predict/paths/models/models.yml

@@ -0,0 +1,63 @@
+get:
+  tags:
+    - models
+  operationId: getModelInstances
+  summary: Get model instances.
+  description: Get a list of all model instances.
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: getModelInstancesResponse
+            type: array
+            items:
+              $ref: '../../responses/Models.yml#/modelInstance'
+    '401':
+      $ref: '../../responses/InvalidCredentials.yml'
+    '422':
+      $ref: '../../../common/responses/UnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'
+
+post:
+  tags:
+    - models
+  operationId: activateModelInstance
+  summary: Activate a model instance.
+  description: >
+    Activate an existing model template. This action triggers the training and inference pipelines for the selected model. 
+    The model is added with `status=pending`.
+    If a model with the exact same source & index already exists, the API endpoint returns an error.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../../common/schemas/modelsParams.yml#/activateModelParams'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            title: activateModelInstanceResponse
+            type: object
+            additionalProperties: false
+            properties:
+              modelID:
+                type: string
+                description: The ID of the model.
+              updatedAt:
+                $ref: '../../../common/responses/common.yml#/updatedAt'
+            required:
+              - modelID
+              - updatedAt
+
+    '401':
+      $ref: '../../responses/InvalidCredentials.yml'
+    '422':
+      $ref: '../../../common/responses/UnprocessableEntity.yml'
+    '500':
+      $ref: '../../../common/responses/InternalError.yml'

specs/predict/responses/ModelTypes.yml

@@ -0,0 +1,3 @@
+compatibleSources:
+  type: string
+  enum: [bigquery]