slipstream/discordbot
slipstream/discordbot
1
1
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: sync tool guide and components

Browse Source
This commit is contained in:
Slipstream 2025-06-11 23:02:11 +00:00
parent 2b75955c4f
commit 10b89f28ae
Signed by: slipstream
GPG Key ID: 13E498CE010AC6FD
2 changed files with 150 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

168
docs/ai_agent_tool_syntax_v2_xml.md
View File

@ -1,24 +1,25 @@
# Project: Refactor AI Agent Tool Syntax to XML
# AI Agent XML Tool Syntax
**Date:** 2025-05-31
**Updated:** 2025-06-11
**Goal:** To refactor the AI agent's tool calling mechanism from a custom regex-parsed format to a standardized XML-based format. This aims to improve robustness, ease of AI generation, parsing simplicity, extensibility, and standardization.
The AI agent defined in `cogs/ai_code_agent_cog.py` uses an XML-based format for all tool calls. When the agent needs to perform an action it responds **only** with an XML block. The name of the root element corresponds to the tool to invoke and the child elements provide the parameters.
**1. Current State:**
The AI agent in `cogs/ai_code_agent_cog.py` uses a custom, line-based syntax for tool calls, defined in `AGENT_SYSTEM_PROMPT` and parsed using regular expressions in `_parse_and_execute_tool_call`.
The following sections document the currently supported tools and their parameters.
**2. Proposed Change: XML-Based Tool Calls**
The AI will be instructed to output *only* an XML block when calling a tool. The root element of the XML block will be the tool's name.
**2.1. New XML Tool Call Syntax Definitions:**
**Tool Call Syntax Examples:**
* **ReadFile:**
```xml
<ReadFile>
<path>path/to/file.ext</path>
</ReadFile>
```
```xml
<ReadFile>
<path>path/to/file.ext</path>
<!-- Optional line range -->
<start_line>10</start_line>
<end_line>20</end_line>
<!-- Optional peeking helpers -->
<peek_first_n_lines>5</peek_first_n_lines>
<peek_last_n_lines>5</peek_last_n_lines>
</ReadFile>
```
* **WriteFile:**
```xml
@ -56,12 +57,16 @@ The AI will be instructed to output *only* an XML block when calling a tool. The
```
* **ListFiles:**
```xml
<ListFiles>
<path>path/to/search</path>
<recursive>true</recursive> <!-- boolean: "true" or "false", defaults to false if tag omitted or value is not "true" -->
</ListFiles>
```
```xml
<ListFiles>
<path>path/to/search</path>
<recursive>true</recursive> <!-- "true" or "false", defaults to false -->
<!-- Optional filtering -->
<filter_extensions>.py,.txt</filter_extensions>
<filter_regex_name>test_.*\.py</filter_regex_name>
<include_metadata>true</include_metadata>
</ListFiles>
```
* **WebSearch:**
```xml
@ -77,6 +82,102 @@ The AI will be instructed to output *only* an XML block when calling a tool. The
</TaskComplete>
```
* **LintFile:**
```xml
<LintFile>
<path>path/to/python_file.py</path>
<linter>pylint</linter>
</LintFile>
```
* **GetCodeStructure:**
```xml
<GetCodeStructure>
<path>path/to/python_file.py</path>
</GetCodeStructure>
```
* **FindSymbolDefinition:**
```xml
<FindSymbolDefinition>
<symbol_name>my_function</symbol_name>
<search_path>./cogs</search_path>
<file_pattern>*.py</file_pattern>
</FindSymbolDefinition>
```
* **ManageCog:**
```xml
<ManageCog>
<action>reload</action>
<cog_name>cogs.example_cog</cog_name>
</ManageCog>
```
* **RunTests:**
```xml
<RunTests>
<test_path_or_pattern>tests/test_module.py</test_path_or_pattern>
<framework>pytest</framework>
</RunTests>
```
* **PythonREPL:**
```xml
<PythonREPL>
<code_snippet><![CDATA[
print("Hello from REPL")
]]></code_snippet>
<session_id>optional_id</session_id>
</PythonREPL>
```
* **CreateNamedSnapshot:**
```xml
<CreateNamedSnapshot>
<snapshot_name>feature_snapshot</snapshot_name>
<description>Optional description</description>
</CreateNamedSnapshot>
```
* **CompareSnapshots:**
```xml
<CompareSnapshots>
<base_ref>snapshot_a</base_ref>
<compare_ref>snapshot_b</compare_ref>
</CompareSnapshots>
```
* **DryRunApplyDiff:**
```xml
<DryRunApplyDiff>
<path>path/to/file.ext</path>
<diff_block><![CDATA[
[SEARCH_BLOCK_START]
:start_line:10
-------
old line
\=======
new line
[REPLACE_BLOCK_END]
]]></diff_block>
</DryRunApplyDiff>
```
* **DryRunWriteFile:**
```xml
<DryRunWriteFile>
<path>path/to/file.ext</path>
</DryRunWriteFile>
```
* **ReadWebPageRaw:**
```xml
<ReadWebPageRaw>
<url>https://example.com/raw.txt</url>
</ReadWebPageRaw>
```
**3. Parsing Logic in `_parse_and_execute_tool_call` (Python):**
* The method will attempt to parse the `ai_response_text` as XML using `xml.etree.ElementTree`.
@ -123,6 +224,17 @@ graph TD
E -- ExecuteCommand --> I[Call _execute_tool_execute_command];
E -- ListFiles --> J[Call _execute_tool_list_files];
E -- WebSearch --> K[Call _execute_tool_web_search];
E -- LintFile --> R[Call _execute_tool_lint_file];
E -- GetCodeStructure --> S[Call _execute_tool_get_code_structure];
E -- FindSymbolDefinition --> T[Call _execute_tool_find_symbol_definition];
E -- ManageCog --> U[Call _execute_tool_manage_cog];
E -- RunTests --> V[Call _execute_tool_run_tests];
E -- PythonREPL --> W[Call _execute_tool_python_repl];
E -- CreateNamedSnapshot --> X[Call _execute_tool_create_named_snapshot];
E -- CompareSnapshots --> Y[Call _execute_tool_compare_snapshots];
E -- DryRunApplyDiff --> Z[Call _execute_tool_dry_run_apply_diff];
E -- DryRunWriteFile --> AA[Call _execute_tool_dry_run_write_file];
E -- ReadWebPageRaw --> AB[Call _execute_tool_read_web_page_raw];
E -- TaskComplete --> L[Process TaskComplete];
E -- Unknown Tool --> M[Handle Unknown Tool / Error];
B -- Invalid XML / Not a Tool --> N[Return "NO_TOOL" status];
@ -132,7 +244,19 @@ graph TD
I --> O;
J --> O;
K --> O;
R --> O;
S --> O;
T --> O;
U --> O;
V --> O;
W --> O;
X --> O;
Y --> O;
Z --> O;
AA --> O;
AB --> O;
L --> P[End Interaction];
M --> P;
N --> P;
O --> Q[Add to History, Continue Loop];
O --> Q[Add to History, Continue Loop];
```

8
docs/components.md
View File

@ -299,7 +299,7 @@ class InfoView(discord.ui.LayoutView):
## See Also
More examples can be found in the
`examples <examples>`{.interpreted-text role="resource"} directory.
Refer to the `interactions/api`{.interpreted-text role="doc"} page for
an exhaustive API reference.
For additional usage examples, refer to the official `discord.py`
documentation. This repository does not include the example suite from
the library. See the `interactions/api` reference for an exhaustive API
overview.