Added _ml/agents and ml/connectors specs (#585)

* Add Ml api Spec , /connector/_register and /connector/{connector_id} with test Signed-off-by: Junwei Dai <[email protected]> * Add Ml api Spec , /agents/_register and /agents/{agent_id} with test Signed-off-by: Junwei Dai <[email protected]> * fix: agent_id error Signed-off-by: Junwei Dai <[email protected]> * Update CHANGELOG.md Co-authored-by: Daniel (dB.) Doubrovkine <[email protected]> Signed-off-by: Junwei Dai <[email protected]> * Readded empty line Signed-off-by: Junwei Dai <[email protected]> --------- Signed-off-by: Junwei Dai <[email protected]> Signed-off-by: Junwei Dai <[email protected]> Co-authored-by: Junwei Dai <[email protected]> Co-authored-by: Daniel (dB.) Doubrovkine <[email protected]>
opensearch-project · Sep 20, 2024 · c6c0c41 · c6c0c41
1 parent 2487252
commit c6c0c41
Show file tree

Hide file tree

Showing 5 changed files with 320 additions and 3 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -95,6 +95,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `/_plugins/_flow_framework/`, `_search`, `state/_search`, `_provision`, `_deprovision`, `_steps`, and `_status` ([#508](https://github.com/opensearch-project/opensearch-api-specification/issues/508)) ([#833](https://github.com/opensearch-project/flow-framework/issues/833))
 - Added `/_plugins/_ism/policies`, `add`, `remove`, `change_policy`, `explain`, and `retry` ([#568](https://github.com/opensearch-project/opensearch-api-specification/pull/568)) ([#578](https://github.com/opensearch-project/opensearch-api-specification/pull/578))
 - Added `/_plugins/refresh_search_analyzers` ([#578](https://github.com/opensearch-project/opensearch-api-specification/pull/578))
+- Added `/_plugins/_ml/agents/_register`, `/_plugins/_ml/connectors/_create`, `DELETE /_plugins/_ml/agents/{agent_id}`, `DELETE /_plugins/_ml/connectors/{connector_id}` ([#228](https://github.com/opensearch-project/opensearch-api-specification/issues/228))
 - Added the `context` query param to the `put_script` APIs ([#586](https://github.com/opensearch-project/opensearch-api-specification/pull/586))
 
 ### Changed

diff --git a/spec/namespaces/ml.yaml b/spec/namespaces/ml.yaml
@@ -102,6 +102,46 @@ paths:
       responses:
         '200':
           $ref: '#/components/responses/ml.search_models@200'
+  /_plugins/_ml/connectors/_create:
+    post:
+      operationId: ml.create_connector.0
+      x-operation-group: ml.create_connector
+      description: Creates a standalone connector.
+      requestBody:
+        $ref: '#/components/requestBodies/ml.create_connector'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.create_connector@200'
+  /_plugins/_ml/connectors/{connector_id}:
+    delete:
+      operationId: ml.delete_connector.0
+      x-operation-group: ml.delete_connector
+      description: Deletes a standalone connector.
+      parameters:
+        - $ref: '#/components/parameters/ml.delete_connector::path.connector_id'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.delete_connector@200'
+  /_plugins/_ml/agents/_register:
+    post:
+      operationId: ml.register_agents.0
+      x-operation-group: ml.register_agents
+      description: Register an agent.
+      requestBody:
+        $ref: '#/components/requestBodies/ml.register_agents'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.register_agents@200'
+  /_plugins/_ml/agents/{agent_id}:
+    delete:
+      operationId: ml.delete_agent.0
+      x-operation-group: ml.delete_agent
+      description: Delete an agent.
+      parameters:
+        - $ref: '#/components/parameters/ml.delete_agent::path.agent_id'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.delete_agent@200'
 components:
   requestBodies:
     ml.register_model_group:
@@ -110,7 +150,7 @@ components:
           schema:
             type: object
             properties:
-              name: 
+              name:
                 type: string
                 description: The model group name.
               description:
@@ -136,7 +176,7 @@ components:
           schema:
             type: object
             properties:
-              name: 
+              name:
                 type: string
                 description: The model name.
               version:
@@ -161,6 +201,16 @@ components:
         application/json:
           schema:
             $ref: '../schemas/ml._common.yaml#/components/schemas/SearchModelsQuery'
+    ml.create_connector:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/ml._common.yaml#/components/schemas/CreateConnectorRequest'
+    ml.register_agents:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/ml._common.yaml#/components/schemas/RegisterAgentsRequest'
   responses:
     ml.register_model_group@200:
       content:
@@ -230,6 +280,32 @@ components:
         application/json:
           schema:
             $ref: '../schemas/ml._common.yaml#/components/schemas/SearchModelsResponse'
+    ml.create_connector@200:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              connector_id:
+                type: string
+    ml.delete_connector@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/_common.yaml#/components/schemas/WriteResponseBase'
+    ml.register_agents@200:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              agent_id:
+                type: string
+    ml.delete_agent@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/_common.yaml#/components/schemas/WriteResponseBase'
   parameters:
     ml.get_model_group::path.model_group_id:
       name: model_group_id
@@ -267,9 +343,21 @@ components:
       required: true
       schema:
         type: string
+    ml.delete_connector::path.connector_id:
+      name: connector_id
+      in: path
+      required: true
+      schema:
+        type: string
+    ml.delete_agent::path.agent_id:
+      name: agent_id
+      in: path
+      required: true
+      schema:
+        type: string
     ml.get_task::path.task_id:
       name: task_id
       in: path
       required: true
       schema:
-        type: string
+        type: string
diff --git a/spec/schemas/ml._common.yaml b/spec/schemas/ml._common.yaml
@@ -156,3 +156,131 @@ components:
     UndeployModelNodeStats:
       type: object
       additionalProperties: true
+    CreateConnectorRequest:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        version:
+          type: integer
+        protocol:
+          type: string
+        credential:
+          $ref: '#/components/schemas/Credential'
+        parameters:
+          $ref: '#/components/schemas/Parameters'
+        client_config:
+          $ref: '#/components/schemas/ClientConfig'
+        actions:
+          type: array
+          items:
+            $ref: '#/components/schemas/Action'
+      required:
+        - actions
+        - credential
+        - description
+        - name
+        - parameters
+        - protocol
+        - version
+    Credential:
+      type: object
+      properties:
+        access_key:
+          type: string
+        secret_key:
+          type: string
+        session_token:
+          type: string
+      additionalProperties: true
+    Parameters:
+      type: object
+      additionalProperties: true
+    ClientConfig:
+      type: object
+      properties:
+        max_connection:
+          type: integer
+        connection_timeout:
+          type: integer
+        read_timeout:
+          type: integer
+        retry_backoff_policy:
+          type: string
+        max_retry_times:
+          type: integer
+        retry_backoff_millis:
+          type: integer
+        retry_timeout_seconds:
+          type: integer
+    Action:
+      type: object
+      properties:
+        action_type:
+          type: string
+        method:
+          type: string
+        headers:
+          $ref: '#/components/schemas/Headers'
+        url:
+          type: string
+        request_body:
+          type: string
+        pre_process_function:
+          type: string
+        post_process_function:
+          type: string
+    RegisterAgentsRequest:
+      type: object
+      properties:
+        name:
+          type: string
+        type:
+          type: string
+        description:
+          type: string
+        tools:
+          type: array
+          items:
+            $ref: '#/components/schemas/ToolItems'
+        parameters:
+          $ref: '#/components/schemas/Parameters'
+        app_type:
+          type: string
+        memory:
+          $ref: '#/components/schemas/Memory'
+        llm:
+          $ref: '#/components/schemas/LLM'
+      required:
+        - name
+        - type
+    LLM:
+      type: object
+      properties:
+        model_id:
+          type: string
+        parameters:
+          $ref: '#/components/schemas/Parameters'
+    Memory:
+      type: object
+      properties:
+        type:
+          type: string
+    ToolItems:
+      type: object
+      properties:
+        name:
+          type: string
+        type:
+          type: string
+        parameters:
+          $ref: '#/components/schemas/Parameters'
+      additionalProperties: true
+    Headers:
+      type: object
+      properties:
+        content_type:
+          type: string
+      additionalProperties: true
diff --git a/tests/plugins/ml/ml/agents.yaml b/tests/plugins/ml/ml/agents.yaml
@@ -0,0 +1,50 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test the register of Agents.
+distributions:
+  excluded:
+    - amazon-managed
+    - amazon-serverless
+version: '>= 2.11'
+epilogues:
+  - path: /_plugins/_ml/agents/{agent_id}
+    method: DELETE
+    status: [200, 404]
+    parameters:
+      agent_id: ${register_agent.test_agent_id}
+chapters:
+  - synopsis: Register agent.
+    warnings:
+      multiple-paths-detected: false
+    id: register_agent
+    path: /_plugins/_ml/agents/_register
+    method: POST
+    request:
+      payload:
+        name: Test_Agent_For_RAG
+        type: flow
+        description: this is a test agent
+        tools:
+          - type: VectorDBTool
+            parameters:
+              model_id: YOUR_TEXT_EMBEDDING_MODEL_ID
+              index: my_test_data
+              embedding_field: embedding
+              source_field:
+                - text
+              input: test_question
+          - type: MLModelTool
+            description: A general tool to answer any question
+            parameters:
+              model_id: YOUR_LLM_MODEL_ID
+    response:
+      status: 200
+    output:
+      test_agent_id: payload.agent_id
+  - synopsis: Delete agent.
+    path: /_plugins/_ml/agents/{agent_id}
+    method: DELETE
+    parameters:
+      agent_id: ${register_agent.test_agent_id}
+    response:
+      status: 200
diff --git a/tests/plugins/ml/ml/connectors.yaml b/tests/plugins/ml/ml/connectors.yaml
@@ -0,0 +1,50 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test the creation of connectors.
+distributions:
+  excluded:
+    - amazon-managed
+    - amazon-serverless
+version: '>= 2.11'
+epilogues:
+  - path: /_plugins/_ml/connectors/{connector_id}
+    method: DELETE
+    status: [200, 404]
+    parameters:
+      connector_id: ${create_connector.test_connector_id}
+chapters:
+  - synopsis: Create connector.
+    warnings:
+      multiple-paths-detected: false
+    id: create_connector
+    path: /_plugins/_ml/connectors/_create
+    method: POST
+    request:
+      payload:
+        name: OpenAI Chat Connector
+        description: The connector to public OpenAI model service for GPT 3.5
+        version: 1
+        protocol: http
+        parameters:
+          endpoint: api.openai.com
+          model: gpt-3.5-turbo
+        credential:
+          openAI_key: test_api_key
+        actions:
+          - action_type: predict
+            method: POST
+            url: 'https://${parameters.endpoint}/v1/chat/completions'
+            headers:
+              Authorization: 'Bearer ${credential.openAI_key}'
+            request_body: '{ "model": "${parameters.model}", "messages": ${parameters.messages} }'
+    response:
+      status: 200
+    output:
+      test_connector_id: payload.connector_id
+  - synopsis: Delete connector.
+    path: /_plugins/_ml/connectors/{connector_id}
+    method: DELETE
+    parameters:
+      connector_id: ${create_connector.test_connector_id}
+    response:
+      status: 200