Add ML Execute Algorithm API (#811)

* Added Execute Algorithm ML API. Signed-off-by: Nathalie Jonathan <nathhjo@amazon.com> * Changed version in test execute API. Signed-off-by: Nathalie Jonathan <nathhjo@amazon.com> * Change execute test version. Signed-off-by: Nathalie Jonathan <nathhjo@amazon.com> * Add execute schema property. Signed-off-by: Nathalie Jonathan <nathhjo@amazon.com> --------- Signed-off-by: Nathalie Jonathan <nathhjo@amazon.com>
opensearch-project · Feb 5, 2025 · 5644cab · 5644cab
1 parent b9dcb25
commit 5644cab
Show file tree

Hide file tree

Showing 4 changed files with 226 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -57,6 +57,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `time` field to the `GetStats` schema in `_common.yml` ([#803](https://github.com/opensearch-project/opensearch-api-specification/pull/803))
 - Added version for `POST /_plugins/_ml/_train/{algorithm_name}`, `_predict/{algorithm_name}/{model_id}`, and `_train_predict/{algorithm_name}` ([#763](https://github.com/opensearch-project/opensearch-api-specification/pull/763))
 - Added `POST _plugins/_security/api/internalusers/{username}` response `201` ([#810](https://github.com/opensearch-project/opensearch-api-specification/pull/810))
+- Added `POST /_plugins/_ml/_execute/{algorithm_name}` ([#811](https://github.com/opensearch-project/opensearch-api-specification/pull/811))
 
 ### Removed
 - Removed unsupported `_common.mapping:SourceField`'s `mode` field and associated `_common.mapping:SourceFieldMode` enum ([#652](https://github.com/opensearch-project/opensearch-api-specification/pull/652))

diff --git a/spec/namespaces/ml.yaml b/spec/namespaces/ml.yaml
@@ -827,6 +827,19 @@ paths:
       responses:
         '200':
           $ref: '#/components/responses/ml.get_tool@200'
+  /_plugins/_ml/_execute/{algorithm_name}:
+    post:
+      operationId: ml.execute_algorithm.0
+      x-operation-group: ml.execute_algorithm
+      x-version-added: '2.0'
+      description: Execute an algorithm.
+      parameters:
+        - $ref: '#/components/parameters/ml.execute_algorithm::path.algorithm_name'
+      requestBody:
+        $ref: '#/components/requestBodies/ml.execute_algorithm'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.execute_algorithm@200'
 components:
   requestBodies:
     ml.register_model_group:
@@ -1483,6 +1496,62 @@ components:
         application/json:
           schema:
             $ref: '../schemas/ml._common.yaml#/components/schemas/ProfileRequest'
+    ml.execute_algorithm:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              operation:
+                type: string
+                description: The calculator operation.
+                enum:
+                  - max
+                  - min
+                  - sum
+              input_data:
+                type: array
+                items:
+                  type: number
+                description: The input data.
+              index_name:
+                type: string
+                description: The index name.
+              attribute_field_names:
+                type: array
+                items:
+                  type: string
+                description: The attribute field names
+              aggregations:
+                type: array
+                items:
+                  $ref: '../schemas/ml._common.yaml#/components/schemas/Aggregation'
+              time_field_name:
+                type: string
+                description: The time field name.
+              start_time:
+                type: integer
+                format: int64
+                description: The start time.
+              end_time:
+                type: integer
+                format: int64
+                description: The end time.
+              min_time_interval:
+                type: integer
+                format: int64
+                description: The minimum time interval.
+              num_outputs:
+                type: integer
+                format: int64
+                description: The number of outputs.
+              metrics:
+                type: array
+                items:
+                  type: array
+                  items:
+                    type: number
+                description: The metrics input.
   responses:
     ml.register_model_group@200:
       content:
@@ -1918,6 +1987,11 @@ components:
         application/json:
           schema:
             $ref: '../schemas/ml._common.yaml#/components/schemas/Tool'
+    ml.execute_algorithm@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/ml._common.yaml#/components/schemas/ExecuteAlgorithmResponse'
   parameters:
     ml.get_all_memories::query.max_results:
       name: max_results
@@ -2260,4 +2334,13 @@ components:
           - SearchIndexTool
           - SearchMonitorsTool
           - VectorDBTool
-          - VisualizationTool
+          - VisualizationTool
+    ml.execute_algorithm::path.algorithm_name:
+      name: algorithm_name
+      in: path
+      required: true
+      schema:
+        type: string
+        enum:
+          - anomaly_localization
+          - local_sample_calculator
diff --git a/spec/schemas/ml._common.yaml b/spec/schemas/ml._common.yaml
@@ -1418,6 +1418,8 @@ components:
           $ref: '#/components/schemas/ModelStats'
         train_predict:
           $ref: '#/components/schemas/ModelStats'
+        execute:
+          $ref: '#/components/schemas/ModelStats'
     PredictRequestStats:
       type: object
       properties:
@@ -1560,6 +1562,8 @@ components:
           $ref: '#/components/schemas/ModelStats'
         train_predict:
           $ref: '#/components/schemas/ModelStats'
+        execute:
+          $ref: '#/components/schemas/ModelStats'
     ModelStats:
       type: object
       properties:
@@ -1580,6 +1584,8 @@ components:
       properties:
         sum:
           $ref: '#/components/schemas/Aggregation'
+        max:
+          $ref: '#/components/schemas/Aggregation'
         field:
           type: string
           description: The field name.
@@ -1596,4 +1602,71 @@ components:
           type: string
           description: The tool type.
         version:
-          $ref: '_common.yaml#/components/schemas/VersionString'
+          $ref: '_common.yaml#/components/schemas/VersionString'
+    ExecuteAlgorithmResponse:
+      oneOf:
+        - $ref: '#/components/schemas/ExecuteLocalSampleCalculatorResponse'
+        - type: object
+          properties:
+            results:
+              type: array
+              items:
+                $ref: '#/components/schemas/ExecuteAnomalyLocalizationResponse'
+    ExecuteLocalSampleCalculatorResponse:
+      type: object
+      properties:
+        result:
+          type: number
+          description: The result.
+    ExecuteAnomalyLocalizationResponse:
+      type: object
+      properties:
+        name:
+          type: string
+        result:
+          $ref: '#/components/schemas/Result'
+    Result:
+      type: object
+      properties:
+        buckets:
+          type: array
+          items:
+            $ref: '#/components/schemas/Buckets'
+    Buckets:
+      type: object
+      properties:
+        start_time:
+          type: integer
+          format: int64
+          description: The start time.
+        end_time:
+          type: integer
+          format: int64
+          description: The end time.
+        overall_aggregate_value:
+          type: number
+          format: double
+          description: The overall aggregate value.
+        entities:
+          type: array
+          items:
+            $ref: '#/components/schemas/Entity'
+    Entity:
+      type: object
+      properties:
+        key:
+          type: array
+          items:
+            type: string
+        contribution_value:
+          type: number
+          format: double
+          description: The contribution value.
+        base_value:
+          type: number
+          format: double
+          description: The base value.
+        new_value:
+          type: number
+          format: double
+          description: The new value.
diff --git a/tests/plugins/ml/ml/execute.yaml b/tests/plugins/ml/ml/execute.yaml
@@ -0,0 +1,67 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test the execution of algorithms.
+version: '>= 2.19'
+prologues:
+  - path: /_cluster/settings
+    method: PUT
+    request:
+      payload:
+        persistent:
+          plugins.ml_commons.only_run_on_ml_node: false
+  - path: /{index}
+    method: PUT
+    request:
+      payload:
+        mappings:
+          properties:
+            timestamp:
+              type: date
+            attribute:
+              type: keyword
+            value:
+              type: float
+    parameters:
+      index: test-index
+epilogues:
+  - path: /{index}
+    method: DELETE
+    status: [200, 404]
+    parameters:
+      index: test-index
+chapters:
+  - synopsis: Execute local sample calculator algorithm.
+    path: /_plugins/_ml/_execute/{algorithm_name}
+    method: POST
+    parameters:
+      algorithm_name: local_sample_calculator
+    request:
+      payload:
+        operation: max
+        input_data:
+          - 1
+          - 2
+          - 3
+    response:
+      status: 200
+  - synopsis: Execute anomaly localization algorithm.
+    path: /_plugins/_ml/_execute/{algorithm_name}
+    method: POST
+    parameters:
+      algorithm_name: anomaly_localization
+    request:
+      payload:
+        index_name: test-index
+        attribute_field_names:
+          - attribute
+        aggregations:
+          - max:
+              max:
+                field: value
+        time_field_name: timestamp
+        start_time: 1620630000000
+        end_time: 1620975600000
+        min_time_interval: 86400000
+        num_outputs: 10
+    response:
+      status: 200