Add SPI subproject and interfaces for Tools

Signed-off-by: Daniel Widdis <[email protected]>

.gitignore

@@ -7,3 +7,7 @@ ml-algorithms/build/
 plugin/build/
 plugin/src/test/resources/bwc/*
 .DS_Store
+*/bin/
+.classpath
+.project
+.settings

spi/src/main/java/org/opensearch/ml/common/spi/MLCommonsExtension.java

@@ -1,3 +1,8 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 package org.opensearch.ml.common.spi;
 
 import org.opensearch.ml.common.spi.tools.Tool;
@@ -11,13 +16,13 @@ public interface MLCommonsExtension {
 
     /**
      * Get tools.
-     * @return
+     * @return A list of provided tools
      */
     List<Tool> getTools();
 
     /**
      * Get tool factories.
-     * @return
+     * @return A list of tool factories
      */
-    List<Tool.Factory> getToolFactories();
-}
+    List<Tool.Factory<? extends Tool>> getToolFactories();
+}

spi/src/main/java/org/opensearch/ml/common/spi/tools/Parser.java

@@ -1,16 +1,21 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 package org.opensearch.ml.common.spi.tools;
 
 /**
  * General parser interface.
- * @param <S>
- * @param <T>
+ * @param <S> The input type
+ * @param <T> The return type
  */
 public interface Parser<S, T> {
 
     /**
      * Parse input.
      * @param input
-     * @return
+     * @return output
      */
     T parse(S input);
 }

spi/src/main/java/org/opensearch/ml/common/spi/tools/Tool.java

@@ -16,24 +16,26 @@ public interface Tool {
     /**
      * Run tool and return response.
      * @param parameters input parameters
-     * @return
-     * @param <T>
+     * @return the tool's output
+     * @param <T> The output type
      */
-    default <T> T run(Map<String, String> parameters) {return null;};
+    default <T> T run(Map<String, String> parameters) {
+        return null;
+    };
 
     default <T> void run(Map<String, String> parameters, ActionListener<T> listener) {};
 
     /**
      * Set input parser.
      * @param parser
      */
-    default void setInputParser(Parser parser){};
+    default void setInputParser(Parser<?, ?> parser) {};
 
     /**
      * Set output parser.
      * @param parser
      */
-    default void setOutputParser(Parser parser){};
+    default void setOutputParser(Parser<?, ?> parser) {};
 
     /**
      * Get tool name.
@@ -78,13 +80,15 @@ public interface Tool {
      * the tool may end the whole CoT process by returning true.
      * @param input
      * @param toolParameters
-     * @return
+     * @return true as a signal to CoT to end the chain, false to continue CoT
      */
-    default boolean end(String input, Map<String, String> toolParameters){return false;}
+    default boolean end(String input, Map<String, String> toolParameters) {
+        return false;
+    }
 
     /**
      * Tool factory which can create instance of {@link Tool}.
-     * @param <T>
+     * @param <T> The subclass this factory produces
      */
     interface Factory<T extends Tool> {
         T create(Map<String, Object> params);

spi/src/main/java/org/opensearch/ml/common/spi/tools/ToolAnnotation.java

@@ -1,3 +1,8 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
 package org.opensearch.ml.common.spi.tools;
 
 import java.lang.annotation.ElementType;