Skip to content

Tools

The tools module provides a flexible tool registration and discovery system for Python functions. It enables you to mark functions as discoverable tools with metadata like categories and descriptions, then automatically register and introspect them at runtime.

Key Features

  • Tool Decorator: Mark any function as a tool with optional category and description metadata
  • Automatic Discovery: Scan modules to find all decorated tool functions
  • Rich Metadata: Extract function signatures, parameter types, defaults, and return types
  • Dynamic Registration: Build tool registries at runtime for plugin systems and extensible applications

Use Cases

The tool system is ideal for:

  • Building plugin architectures where tools can be dynamically discovered
  • Creating command-line interfaces with auto-generated help text
  • Implementing chatbot or AI assistant function calling
  • Organizing utility functions with categorization and documentation

Basic Usage

from spoc.tools import tool, register_tools

# Simple tool with default category
@tool
def hello():
    """Say hello"""
    return "Hello, world!"

# Tool with custom category and description
@tool(category="math", description="Add two numbers together")
def add(a: int, b: int) -> int:
    return a + b

# Register all tools in current module
import sys
tools = register_tools(sys.modules[__name__])

spoc.tools

Generic tools for working with Python modules.

This module provides utilities for creating and managing tool functions that can be registered, discovered, and called dynamically.

tool(func=None, *, category='general', description=None)

Decorator to mark a function as a tool.

Parameters:

  • func (Optional[F], default: None ) –

    The function to mark as a tool

  • category (str, default: 'general' ) –

    The category this tool belongs to (default: "general")

  • description (Optional[str], default: None ) –

    Custom description for the tool (defaults to function docstring)

Returns:

  • Union[F, Callable[[F], F]] –

    The decorated function with tool attributes

Example

@tool def my_tool(): '''This is a tool''' return "result"

@tool(category="math", description="Add two numbers") def add(a, b): return a + b

register_tools(module)

Find and register all tool functions in a module.

Parameters:

  • module (ModuleType) –

    The module containing tool functions

Returns:

  • Dict[str, Dict[str, Any]] –

    A dictionary mapping tool names to their metadata

Example

import my_tools tools_dict = register_tools(my_tools)

get_submodules(module)

Get a list of non-private attributes from a module.

Parameters:

  • module (ModuleType) –

    The module to inspect

Returns:

  • List[str] –

    A list of module attribute names that don't start or end with underscore