quartermaster-tools

Lightweight tool abstraction framework for AI agent orchestration.

Features

• @tool() decorator -- the primary way to create tools from plain functions
• FunctionTool instances with metadata introspection (info(), parameters())
• Built-in tools: file I/O, web requests, data parsing, math evaluation, code execution, and more
• ToolRegistry with version-aware lookup, plugin discovery via entry points, and decorator registration
• Chain-of-Responsibility pattern for composable data processing pipelines
• LLM bridge methods: to_openai_tools(), to_anthropic_tools(), to_mcp_tools() on both ToolDescriptor and ToolRegistry
• AbstractTool base class available for advanced use cases
• Zero required dependencies (httpx optional for WebRequestTool)

New in v0.5.0

• duckduckgo_search UA fix -- realistic Chrome UA + Accept/Referer headers.

What shipped in v0.4.0

• Local-GPU cost tracker -- cost_tracker tool now accepts duration_seconds + local_gpu_cost_per_hour for self-hosted inference cost accounting.

Installation

pip install quartermaster-tools

# With optional HTTP support for WebRequestTool
pip install quartermaster-tools[web]

# With quartermaster-providers bridge for to_tool_definition()
pip install quartermaster-tools[llm]

Quick Start

Creating a Tool with @tool()

The @tool() decorator is the primary way to define tools. It extracts parameter metadata from the function signature, type hints, and Google-style docstring automatically.

from quartermaster_tools import tool


@tool()
def analyze_sentiment(text: str, language: str = "en") -> dict:
    """Analyze text sentiment.

    Returns positive, negative, or neutral sentiment with a confidence score.

    Args:
        text: Text to analyze for sentiment.
        language: ISO language code for the input text.
    """
    # Your sentiment logic here
    return {"sentiment": "positive", "score": 0.92}


# Call it like a normal function
result = analyze_sentiment(text="I love this product!")

# Or execute via the tool interface (returns ToolResult)
tool_result = analyze_sentiment.run(text="I love this product!")
print(tool_result.data)  # {"sentiment": "positive", "score": 0.92}

# Introspect metadata
print(analyze_sentiment.name())  # "analyze_sentiment"
print(
    analyze_sentiment.parameters()
)  # [ToolParameter(name="text", ...), ToolParameter(name="language", ...)]

# Export JSON Schema for LLM function calling
schema = analyze_sentiment.info().to_input_schema()

You can override the tool name and description:

@tool(name="sentiment_v2", description="Advanced sentiment analysis")
def analyze(text: str) -> dict: ...

Using the Tool Registry

from quartermaster_tools import ToolRegistry, tool

registry = ToolRegistry()

# Register existing FunctionTool instances (built-in tools are already FunctionTool instances)
from quartermaster_tools import ReadFileTool, WriteFileTool, WebRequestTool

registry.register(ReadFileTool)
registry.register(WriteFileTool)
registry.register(WebRequestTool)


# Or use the registry's own @tool decorator to create and register in one step
@registry.tool()
def summarize(text: str, max_length: int = 100) -> dict:
    """Summarize text to a given length.

    Args:
        text: The text to summarize.
        max_length: Maximum length of the summary.
    """
    return {"summary": text[:max_length]}


# Lookup by name (returns latest version)
reader = registry.get("read_file")
result = reader.run(path="/tmp/data.txt")

# List all registered tools
for desc in registry.list_tools():
    print(f"{desc.name} v{desc.version}: {desc.short_description}")

# Export for LLM function calling
openai_tools = registry.to_openai_tools()
anthropic_tools = registry.to_anthropic_tools()
mcp_tools = registry.to_mcp_tools()
json_schemas = registry.to_json_schema()

Building a Handler Chain

from quartermaster_tools import Chain, Handler


class ValidateInput(Handler):
    def handle(self, data: dict) -> dict:
        if "query" not in data:
            raise ValueError("Missing required field: query")
        return data


class NormalizeText(Handler):
    def handle(self, data: dict) -> dict:
        data["query"] = data["query"].strip().lower()
        return data


class AddTimestamp(Handler):
    def handle(self, data: dict) -> dict:
        from datetime import datetime

        data["timestamp"] = datetime.now().isoformat()
        return data


chain = (
    Chain().add_handler(ValidateInput()).add_handler(NormalizeText()).add_handler(AddTimestamp())
)

result = chain.run({"query": "  Hello World  "})
# {"query": "hello world", "timestamp": "2025-01-15T10:30:00"}

Advanced: Creating a Tool with AbstractTool

For cases where you need full control over tool construction (e.g., custom validation logic, stateful tools), subclass AbstractTool directly:

from quartermaster_tools import AbstractTool, ToolDescriptor, ToolParameter, ToolResult


class DatabaseQueryTool(AbstractTool):
    def __init__(self, connection_string: str):
        self._conn = connection_string

    def name(self) -> str:
        return "db_query"

    def parameters(self) -> list[ToolParameter]:
        return [
            ToolParameter(
                name="sql", description="SQL query to execute", type="string", required=True
            ),
        ]

    def info(self) -> ToolDescriptor:
        return ToolDescriptor(
            name=self.name(),
            short_description="Execute a database query",
            long_description="Runs a SQL query against the configured database.",
            version=self.version(),
            parameters=self.parameters(),
        )

    def run(self, **kwargs) -> ToolResult:
        sql = kwargs.get("sql", "")
        # Execute query...
        return ToolResult(success=True, data={"rows": []})


tool = DatabaseQueryTool(connection_string="sqlite:///mydb.db")
result = tool.safe_run(sql="SELECT * FROM users LIMIT 10")

API Reference

@tool() Decorator

Converts a plain function into a FunctionTool instance. Parameters are extracted from the function signature and type hints. Descriptions come from the Google-style docstring.

FunctionTool

A tool created by the @tool() decorator. Subclass of AbstractTool.

AbstractTool

The base class for advanced tool implementations.

AbstractLocalTool

Extends AbstractTool for subprocess-based tools.

ToolDescriptor

Metadata describing a tool, with LLM bridge methods.

ToolRegistry

Central registry with version-aware lookup and plugin discovery.

Built-in Tools

All built-in tools are FunctionTool instances created with @tool(). The *Tool names (e.g., ReadFileTool) are backward-compatible aliases pointing to the same FunctionTool instance.

79 tools across 15 categories:

Decorator Registration

from quartermaster_tools import register_tool, get_default_registry, AbstractTool


@register_tool
class MyTool(AbstractTool): ...


# The tool is automatically registered in the default registry
registry = get_default_registry()
tool = registry.get("my_tool")

Plugin Discovery

Register tools as entry points in your pyproject.toml:

[project.entry-points.quartermaster_tools]
my_tool = "my_package.tools:MyTool"

The registry discovers and loads these automatically on first access.

Integration with Sibling Packages

With quartermaster-nodes (tool execution in agent graphs)

from quartermaster_tools import ToolRegistry, ReadFileTool

registry = ToolRegistry()
registry.register(ReadFileTool)

# Convert tool descriptors to node-compatible format
for desc in registry.list_tools():
    openai_format = desc.to_openai_tools()
    # Pass to agent nodes for LLM function calling

With quartermaster-providers (LLM provider integration)

from quartermaster_tools import ToolRegistry, ReadFileTool, WriteFileTool

registry = ToolRegistry()
registry.register(ReadFileTool)
registry.register(WriteFileTool)

# Export tools in the format your LLM provider expects
anthropic_tools = registry.to_anthropic_tools()
openai_tools = registry.to_openai_tools()

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache License 2.0 -- see LICENSE for details.