Skip to content

Commit 2738bad

Browse files
authored
tool interface (opensearch-project#1692)
* tool interface Signed-off-by: Jing Zhang <jngz@amazon.com> * remove sync run method Signed-off-by: Jing Zhang <jngz@amazon.com> --------- Signed-off-by: Jing Zhang <jngz@amazon.com>
1 parent 500fff9 commit 2738bad

File tree

4 files changed

+179
-0
lines changed

4 files changed

+179
-0
lines changed
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
/*
2+
* Copyright OpenSearch Contributors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package org.opensearch.ml.common.spi;
7+
8+
import org.opensearch.ml.common.spi.tools.Tool;
9+
10+
import java.util.List;
11+
12+
/**
13+
* ml-commons extension interface.
14+
*/
15+
public interface MLCommonsExtension {
16+
17+
/**
18+
* Get tool factories.
19+
* @return A list of tool factories
20+
*/
21+
List<Tool.Factory<? extends Tool>> getToolFactories();
22+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
/*
2+
* Copyright OpenSearch Contributors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package org.opensearch.ml.common.spi.tools;
7+
8+
/**
9+
* General parser interface.
10+
* @param <S> The input type
11+
* @param <T> The return type
12+
*/
13+
public interface Parser<S, T> {
14+
15+
/**
16+
* Parse input.
17+
* @param input the parser input
18+
* @return output the parser output
19+
*/
20+
T parse(S input);
21+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
/*
2+
* Copyright OpenSearch Contributors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package org.opensearch.ml.common.spi.tools;
7+
8+
import org.opensearch.core.action.ActionListener;
9+
import java.util.Map;
10+
11+
/**
12+
* General tool interface.
13+
*/
14+
public interface Tool {
15+
16+
/**
17+
* Run tool and return response asynchronously.
18+
* @param parameters input parameters
19+
* @param listener an action listener for the response
20+
* @param <T> The output type
21+
*/
22+
default <T> void run(Map<String, String> parameters, ActionListener<T> listener) {};
23+
24+
/**
25+
* Set input parser.
26+
* @param parser the parser to set
27+
*/
28+
default void setInputParser(Parser<?, ?> parser) {};
29+
30+
/**
31+
* Set output parser.
32+
* @param parser the parser to set
33+
*/
34+
default void setOutputParser(Parser<?, ?> parser) {};
35+
36+
/**
37+
* Get tool type.
38+
* Agent uses the type to find the tool.
39+
* @return the tool type
40+
*/
41+
String getType();
42+
43+
/**
44+
* Get tool version.
45+
* @return the tool version
46+
*/
47+
String getVersion();
48+
49+
/**
50+
* Get tool name which is displayed in prompt.
51+
* @return the tool name
52+
*/
53+
String getName();
54+
55+
/**
56+
* Set tool name which is displayed in prompt.
57+
* @param name the tool name
58+
*/
59+
void setName(String name);
60+
61+
/**
62+
* Get tool description.
63+
* @return the tool description
64+
*/
65+
String getDescription();
66+
67+
/**
68+
* Set tool description.
69+
* @param description the description to set
70+
*/
71+
void setDescription(String description);
72+
73+
/**
74+
* Validate if the input is good.
75+
* @param parameters input parameters
76+
* @return true if the input is valid
77+
*/
78+
boolean validate(Map<String, String> parameters);
79+
80+
/**
81+
* Check if should end the whole CoT immediately.
82+
* For example, if some critical error detected like high memory pressure,
83+
* the tool may end the whole CoT process by returning true.
84+
* @param input tool input string
85+
* @param toolParameters map of input parameters
86+
* @return true as a signal to CoT to end the chain, false to continue CoT
87+
*/
88+
default boolean end(String input, Map<String, String> toolParameters) {
89+
return false;
90+
}
91+
92+
/**
93+
* The tool runs against the original human input.
94+
* @return
95+
*/
96+
default boolean useOriginalInput() {
97+
return false;
98+
}
99+
100+
/**
101+
* Tool factory which can create instance of {@link Tool}.
102+
* @param <T> The subclass this factory produces
103+
*/
104+
interface Factory<T extends Tool> {
105+
/**
106+
* Create an instance of this tool.
107+
*
108+
* @param params Parameters for the tool
109+
* @return an instance of this tool
110+
*/
111+
T create(Map<String, Object> params);
112+
113+
/**
114+
* Get the default description of this tool.
115+
* @return the default description
116+
*/
117+
String getDefaultDescription();
118+
}
119+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
/*
2+
* Copyright OpenSearch Contributors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package org.opensearch.ml.common.spi.tools;
7+
8+
import java.lang.annotation.ElementType;
9+
import java.lang.annotation.Retention;
10+
import java.lang.annotation.RetentionPolicy;
11+
import java.lang.annotation.Target;
12+
13+
@Retention(RetentionPolicy.RUNTIME)
14+
@Target(ElementType.TYPE)
15+
public @interface ToolAnnotation {
16+
String value();
17+
}

0 commit comments

Comments
 (0)