​
Creating Custom Tools in PySpur using @tool_function

This guide will walk you through the process of converting an arbitrary Python function into a PySpur tool using the @tool_function decorator. This allows you to integrate custom logic into your PySpur workflows seamlessly.

​
Prerequisites

  • Ensure you have initialized a PySpur project using the pyspur init command.

​
Step-by-Step Guide

​
Step 1: Create a Tool File

  1. Navigate to the tools directory in your PySpur project. This directory is created automatically when you initialize your project.

  2. Create a new Python file for your tool. For example, my_custom_tool.py.

​
Step 2: Define Your Function

  1. In your new tool file, define the Python function you want to convert into a tool. This function should contain the logic you wish to execute.
def foo(param1: str, param2: int = 42) -> dict:
    """A simple example function."""
    return {"param1": param1, "param2": param2}

​
Step 3: Decorate Your Function

  1. Import the tool_function decorator from the appropriate module.

  2. Use the @tool_function decorator to register your function as a tool. You can specify optional parameters such as name, description, category, and output_model.

from pyspur.nodes.decorator import tool_function

@tool_function(
    name="bar", 
    description="A custom tool example", 
    category="Custom")
def foo(param1: str, param2: int = 42) -> dict:
    """A simple example function."""
    return {"param1": param1, "param2": param2}

​
@tool_function Parameters

  • name (Optional[str]): The name of the tool. Defaults to the function name if not provided.
  • display_name (Optional[str]): A human-readable name for the tool, used in the UI. Defaults to a title-cased version of the function name.
  • description (Optional[str]): A brief description of what the tool does. Defaults to the function’s docstring if not provided.
  • category (Optional[str]): A category for organizing the tool within the UI. Useful for grouping similar tools.
  • visual_tag (Optional[Dict[str, str]]): Visual styling options for the tool in the UI.
  • has_fixed_output (bool): Indicates whether the tool has a fixed output schema. Defaults to True.
  • output_model (Optional[Type[BaseNodeOutput]]): A custom output model to use instead of generating one automatically@tool_function

​
Returns

  • ToolFunction: The decorated function, which can still be called normally but is now also registered as a PySpur tool.

​
Step 4: Using the Tool in a SpuNow you should be able to see the

A tool named bar will now appear in the tools panel in the app under the Custom section. This tool can be used in your Spur workflows just like any other built-in tool.