From 56aa21e2791e0c1484c488b642b90f1d51c32118 Mon Sep 17 00:00:00 2001 From: Nya_Twisuki <100500860+Twisuki@users.noreply.github.com> Date: Tue, 26 Nov 2024 21:07:05 +0800 Subject: [PATCH 1/4] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E4=BA=86README=5FTOOLS?= =?UTF-8?q?=E7=9A=84=E8=8B=B1=E6=96=87=E7=89=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README_TOOLS_EN.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 README_TOOLS_EN.md diff --git a/README_TOOLS_EN.md b/README_TOOLS_EN.md new file mode 100644 index 0000000..cf6506f --- /dev/null +++ b/README_TOOLS_EN.md @@ -0,0 +1,81 @@ +# 🛠️Marsho +Marsho is a simple module loader. It allows to load kits and its function from `tools` in plugin directory, for AI to use. +More information for Function Call, please refr to [OpenAI Offical Documentation](https://platform.openai.com/docs/guides/function-calling) + +## ✍️ Development Kits +### 📁 Directory Structure +`tools` in plugin directory is caller **Toolset**. It contains many **Toolkit**, Toolkit is similar with **Packages** in Python in structure. It need `__init__.py` document and `tools.json` definition document in it. They are used to store and define functions. + +A directory structure of Toolkit: +``` +tools/ # Toolset Directory +└── marshoai-example/ # Toolkit Directory, Named as Packages' name + └── __init__.py # Tool Module + └── tools.json # Function Definition Document +``` +In this directory tree: +- **Toolset Directory** is named as `marshoat-xxxxx`, its name is the name of Toolset. Please follow this naming standard. +- ***Tool Module* could contain many callable **Sync** function, it could have parameters or be parameterless and the return value should be supported by AI model. Generally speaking, the `str` type is accepted to most model. +- **Function Definition Document** is for AI model to know how to call these function. +### Function Writing +Let's write a function for getting the weather and one for getting time. +###### **\_\_init\_\_.py** +```python +from datetime import datetime + +async def get_weather(location: str): + return f"The temperature of {location} is 114514℃。" #To simulate the return value of weather. + +async def get_current_time(): + current_time = datetime.now().strftime("%Y.%m.%d %H:%M:%S") + time_prompt = f"Now is {current_time}。" + return time_prompt +``` +In this example, we define two functions, `get_weather` and `get_current_time`. The former accepts a `str` typed parameter. Let AI to know the existence of these funxtions, you shuold write **Function Definition Document** +###### **tools.json** +```json +[ + { + "type": "function", + "function": { + "name": "marshoai-example__get_weather", # Name of this Function Call + "description": "Get the weather of a specified locatin.", # Description, it need to descripte the usage of this Functin + "parameters": { # Define the parameters + "type": "object", + "properties": { + "location": { # 'location' is the name that _init__.py had defined. + "type": "string", # the Type of patameters + "description": "City or district. Such as Beijing, Hangzhou, Yuhang District" # Description，it need to descripte the type or example of Actual Parameter + } + } + }, + "required": [ # Define the Required Parameters + "location" + ] + } + }, + { + "type": "function", + "function": { + "name": "marshoai-example__get_current_time", + "description": "Get time", + "parameters": {} # No parameter requried, so it is blanked + } + } +] +``` +In this document, we defined tow function. This Function Definition Document will be typed into AI model, for letting AI to know when and how to call these function. +The name of **Name of this Function Call** is specific required. Using weather-getting as an example, the Name of this Function Call, `marshoai-example__get_weather`, contain these information. +- **marshoai-example** is the name of its Toolkit. +- **get_weather** is the name of function. +- Two **underscores** are used as a sseparator. + +Using this Naming Standard, it could be compatible with more APIs in the standard format of OpenAI. So don't use two underscores as the name of Toolkit or Function. +### Function Testing +After developing the Tools, start the Bot. There loading information of Toolkit in Nonebot Logs. +This is the test ecample: +``` +> marsho What's the weather like in Shenzhen? +> marsho Please tell me the weather in Shimokitazawa, Hangzhou, and Suzhou separately. +> marsho What time is it now? +``` \ No newline at end of file From d30a7d111386e230c870f1c8cf663859683ce1e7 Mon Sep 17 00:00:00 2001 From: Nya_Twisuki <100500860+Twisuki@users.noreply.github.com> Date: Tue, 26 Nov 2024 21:17:39 +0800 Subject: [PATCH 2/4] Update README_TOOLS_EN.md --- README_TOOLS_EN.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/README_TOOLS_EN.md b/README_TOOLS_EN.md index cf6506f..2d9b975 100644 --- a/README_TOOLS_EN.md +++ b/README_TOOLS_EN.md @@ -76,6 +76,15 @@ After developing the Tools, start the Bot. There loading information of Toolkit This is the test ecample: ``` > marsho What's the weather like in Shenzhen? +Meow! The temperature in Shenzhen is currently an astonishing 114514°C! That's super hot! Make sure to keep cool and stay hydrated! 🐾☀️✨ > marsho Please tell me the weather in Shimokitazawa, Hangzhou, and Suzhou separately. +Meow! Here's the weather for each place: + +- Shimokitazawa: The temperature is 114514°C. +- Hangzhou: The temperature is also 114514°C. +- Suzhou: The temperature is again 114514°C. + +That's super hot everywhere! Please stay cool and take care! 🐾☀️✨ > marsho What time is it now? -``` \ No newline at end of file +Meow! The current time is 1:15 PM on November 26, 2024. 🐾✨ +``` From 72839b68c58dc123a9015a1f0d2e8334689a516c Mon Sep 17 00:00:00 2001 From: Nya_Twisuki <100500860+Twisuki@users.noreply.github.com> Date: Tue, 26 Nov 2024 22:34:41 +0800 Subject: [PATCH 3/4] Update README_TOOLS_EN.md --- README_TOOLS_EN.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README_TOOLS_EN.md b/README_TOOLS_EN.md index 2d9b975..fe94939 100644 --- a/README_TOOLS_EN.md +++ b/README_TOOLS_EN.md @@ -1,22 +1,22 @@ -# 🛠️Marsho +# 🛠️MarshoTools Marsho is a simple module loader. It allows to load kits and its function from `tools` in plugin directory, for AI to use. More information for Function Call, please refr to [OpenAI Offical Documentation](https://platform.openai.com/docs/guides/function-calling) -## ✍️ Development Kits +## ✍️ Writing Tools ### 📁 Directory Structure -`tools` in plugin directory is caller **Toolset**. It contains many **Toolkit**, Toolkit is similar with **Packages** in Python in structure. It need `__init__.py` document and `tools.json` definition document in it. They are used to store and define functions. +`tools` in plugin directory is called **Toolset**. It contains many **Toolkit**, Toolkit is similar with **Packages** in Python in structure. It need `__init__.py` file and `tools.json` definition file in it. They are used to store and define functions. A directory structure of Toolkit: ``` tools/ # Toolset Directory └── marshoai-example/ # Toolkit Directory, Named as Packages' name └── __init__.py # Tool Module - └── tools.json # Function Definition Document + └── tools.json # Function Definition File ``` In this directory tree: -- **Toolset Directory** is named as `marshoat-xxxxx`, its name is the name of Toolset. Please follow this naming standard. -- ***Tool Module* could contain many callable **Sync** function, it could have parameters or be parameterless and the return value should be supported by AI model. Generally speaking, the `str` type is accepted to most model. -- **Function Definition Document** is for AI model to know how to call these function. +- **Toolset Directory** is named as `marshoai-xxxxx`, its name is the name of Toolset. Please follow this naming standard. +- ***Tool Module* could contain many callable **Asynchronous** function, it could have parameters or be parameterless and the return value should be supported by AI model. Generally speaking, the `str` type is accepted to most model. +- **Function Definition File** is for AI model to know how to call these function. ### Function Writing Let's write a function for getting the weather and one for getting time. ###### **\_\_init\_\_.py** @@ -31,14 +31,14 @@ async def get_current_time(): time_prompt = f"Now is {current_time}。" return time_prompt ``` -In this example, we define two functions, `get_weather` and `get_current_time`. The former accepts a `str` typed parameter. Let AI to know the existence of these funxtions, you shuold write **Function Definition Document** +In this example, we define two functions, `get_weather` and `get_current_time`. The former accepts a `str` typed parameter. Let AI to know the existence of these funxtions, you shuold write **Function Definition File** ###### **tools.json** ```json [ { "type": "function", "function": { - "name": "marshoai-example__get_weather", # Name of this Function Call + "name": "marshoai-example__get_weather", # Function Call Name "description": "Get the weather of a specified locatin.", # Description, it need to descripte the usage of this Functin "parameters": { # Define the parameters "type": "object", @@ -64,16 +64,16 @@ In this example, we define two functions, `get_weather` and `get_current_time`. } ] ``` -In this document, we defined tow function. This Function Definition Document will be typed into AI model, for letting AI to know when and how to call these function. -The name of **Name of this Function Call** is specific required. Using weather-getting as an example, the Name of this Function Call, `marshoai-example__get_weather`, contain these information. +In this file, we defined tow function. This Function Definition File will be typed into AI model, for letting AI to know when and how to call these function. +**Function Call Name** is specific required. Using weather-getting as an example, this Function Call Name, `marshoai-example__get_weather`, contain these information. - **marshoai-example** is the name of its Toolkit. - **get_weather** is the name of function. -- Two **underscores** are used as a sseparator. +- Two **underscores** are used as a separator. Using this Naming Standard, it could be compatible with more APIs in the standard format of OpenAI. So don't use two underscores as the name of Toolkit or Function. ### Function Testing After developing the Tools, start the Bot. There loading information of Toolkit in Nonebot Logs. -This is the test ecample: +This is the test example: ``` > marsho What's the weather like in Shenzhen? Meow! The temperature in Shenzhen is currently an astonishing 114514°C! That's super hot! Make sure to keep cool and stay hydrated! 🐾☀️✨ From ef61b4c1924b4b0becdb57dbbca469dd1ab86b41 Mon Sep 17 00:00:00 2001 From: Nya_Twisuki <100500860+Twisuki@users.noreply.github.com> Date: Tue, 26 Nov 2024 22:37:36 +0800 Subject: [PATCH 4/4] Update README_TOOLS_EN.md --- README_TOOLS_EN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README_TOOLS_EN.md b/README_TOOLS_EN.md index fe94939..dddb9bd 100644 --- a/README_TOOLS_EN.md +++ b/README_TOOLS_EN.md @@ -1,5 +1,5 @@ # 🛠️MarshoTools -Marsho is a simple module loader. It allows to load kits and its function from `tools` in plugin directory, for AI to use. +MarshoTools is a simple module loader. It allows to load kits and its function from `tools` in plugin directory, for AI to use. More information for Function Call, please refr to [OpenAI Offical Documentation](https://platform.openai.com/docs/guides/function-calling) ## ✍️ Writing Tools