Python Tools

Drop-in Python tools for catboi. Each subdirectory is automatically discovered and registered as an agent tool at startup.

Quick Start

1. Create a new directory under python-tools/:

   python-tools/
   └── my_tool/
       ├── tool.json
       └── main.py
   

2. Define your tool in tool.json:

   {
     "name": "my_tool",
     "description": "What the tool does",
     "parameters": {
       "param_name": {
         "type": "string",
         "description": "What this parameter is for"
       }
     },
     "required": ["param_name"]
   }
   

3. Implement the logic in main.py:

   import json
   import sys
   
   args = json.loads(sys.stdin.read())
   param = args.get("param_name", "")
   # ... your logic here ...
   print("result")
   

4. Restart catboi — the tool is picked up automatically.

How It Works

• The PythonToolLoader scans each subdirectory of python-tools/ for a tool.json manifest and main.py script.
• For each valid tool directory, a PythonBridgeTool is created and registered in AgentToolRegistry.
• When the LLM calls the tool, PythonBridgeTool executes main.py via ProcessBuilder:
  • Input: Tool arguments are passed as a JSON object to the script's stdin.
  • Output: The script's stdout is captured and returned as the tool result.
  • Errors: If the script exits with a non-zero code, stderr is returned as an error message.
  • Timeout: Scripts have a 30-second execution timeout.

tool.json Reference

Field	Type	Required	Description
name	string	Yes	Unique tool name (used for dispatching)
description	string	No	What the tool does (shown to the LLM)
parameters	object	No	Map of parameter name → property object
required	array of string	No	List of required parameter names

Each parameter property object:

Field	Type	Description
type	string	Parameter type (e.g. string, integer)
description	string	What this parameter is for

Tips

• Use any Python libraries you need — just make sure they're installed in the environment where catboi runs.
• For debugging, print to stderr (print("debug", file=sys.stderr)) — only stdout is captured as the tool result.
• Keep scripts fast — the default timeout is 30 seconds.
• The working directory is set to the tool's own directory, so you can read local data files with relative paths.