diff --git a/docs/custom_tool.rst b/docs/custom_tool.rst index b5e30a60..0fb26b48 100644 --- a/docs/custom_tool.rst +++ b/docs/custom_tool.rst @@ -1,16 +1,57 @@ -Creating a Custom Tool for gptme -================================= +Custom Tools +============ Introduction ------------ -In gptme, a custom tool allows you to extend the functionality of the assistant by -defining new tools that can be executed. -This guide will walk you through the process of creating and registering a custom tool. +There are two main approaches to extending gptme's functionality: + +1. **Custom Tools**: Native gptme tools that integrate deeply with the assistant. +2. **Script Tools**: Standalone scripts that can be called via the shell tool. + +This guide covers both approaches and when to use each. + +Script-based Tools +------------------ + +The simplest way to extend gptme is by writing standalone scripts. These can be: + +- Written in any language +- Run independently of gptme +- Called via the shell tool +- Easily tested and maintained + +Benefits of script-based tools: + - Simple to create and maintain + - Can be run and tested independently + - No gptme dependency + - Flexible language choice + - Isolated dependencies + +Limitations: + - Requires shell tool access + - Can't attach files/images to messages + - Not listed in tools section + - No built-in argument validation + +For script-based tools, no registration is needed. Simply include them in the gptme context to make the agent aware of them. + +1. Place scripts in a ``tools/`` directory (or any other location) +2. Make them executable (``chmod +x tools/script.py``) +3. Use via the shell tool (``gptme 'test our new tool' tools/script.py``) Creating a Custom Tool ------------------------ -To create a custom tool, you need to define a new instance of the ``ToolSpec`` class. -This class requires several parameters: +---------------------- + +When you need deeper integration with gptme, you can create a custom tool by defining a new instance of the ``ToolSpec`` class. + +Custom tools are necessary when you need to: + - Attach files/images to messages + - Get included in the tools section + - Use without shell tool access + - Validate arguments + - Handle complex interactions + +The ``ToolSpec`` class requires these parameters: - **name**: The name of the tool. - **desc**: A description of what the tool does. @@ -20,55 +61,84 @@ This class requires several parameters: - **block_types**: The block types to detects. - **parameters**: A list of parameters that the tool accepts. -Here is a basic example of defining a custom tool: +Examples +-------- + +Script-based Tools +~~~~~~~~~~~~~~~~~~ +For examples of script-based tools, see: + +**gptme-contrib** + A collection of community-contributed tools and scripts: + + - `Twitter CLI `_: Twitter client with OAuth support + - `Perplexity CLI `_: Perplexity search tool + +**Standalone Tools** + Independent tool repositories: + + - `gptme-rag `_: Document indexing and retrieval + +Custom Tools +~~~~~~~~~~~~ +For examples of custom tools, see: + +- `Screenshot tool `_: Takes screenshots +- `Browser tool `_: Web browsing and screenshots +- `Vision tool `_: Image viewing and analysis + +Basic Custom Tool Example +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here's a minimal example of a custom tool: .. code-block:: python - import random from gptme.tools import ToolSpec, Parameter, ToolUse from gptme.message import Message def execute(code, args, kwargs, confirm): - - if code is None and kwargs is not None: - code = kwargs.get('side_count') - - yield Message('system', f"Result: {random.randint(1,code)}") - - def examples(tool_format): - return f""" - > User: Throw a dice and give me the result. - > Assistant: - {ToolUse("dice", [], "6").to_output(tool_format)} - > System: 3 - > assistant: The result is 3 - """.strip() + name = kwargs.get('name', 'World') + yield Message('system', f"Hello, {name}!") tool = ToolSpec( - name="dice", - desc="A dice simulator.", - instructions="This tool generate a random integer value like a dice.", - examples=examples, + name="hello", + desc="A simple greeting tool", + instructions="Greets the user by name", execute=execute, - block_types=["dice"], + block_types=["hello"], parameters=[ Parameter( - name="side_count", - type="integer", - description="The number of faces of the dice to throw.", - required=True, + name="name", + type="string", + description="Name to greet", + required=False, ), ], ) +Choosing an Approach +-------------------- +Use **script-based tools** when you need: + - Standalone functionality + - Independent testing/development + - Language/framework flexibility + - Isolated dependencies + +Use **custom tools** when you need: + - File/image attachments + - Tool listing in system prompt + - Complex argument validation + - Operation without shell access + Registering the Tool ---------------------- +-------------------- To ensure your tool is available for use, you can specify the module in the ``TOOL_MODULES`` env variable or setting in your :doc:`project configuration file `, which will automatically load your custom tools. .. code-block:: toml - TOOL_MODULES = "gptme.tools,path.to.your.custom_tool_module" + TOOL_MODULES = "gptme.tools,yourpackage.your_custom_tool_module" Don't remove the ``gptme.tools`` package unless you know exactly what you are doing. @@ -80,5 +150,20 @@ or by temporarily modifying the `PYTHONPATH` environment variable. For example: export PYTHONPATH=$PYTHONPATH:/path/to/your/module - This lets Python locate your module during development and testing without requiring installation. + +Community Tools +--------------- +The `gptme-contrib `_ repository provides a collection of community-contributed tools and scripts. +This makes it easier to: + +- Share tools between agents +- Maintain consistent quality +- Learn from examples +- Contribute your own tools + +To use these tools, you can either: + +1. Clone the repository and use the scripts directly +2. Copy specific scripts to your local workspace +3. Fork the repository to create your own collection