mirror of
https://github.com/hanzoai/stack.git
synced 2026-11-19 03:06:57 +00:00
12 KiB
12 KiB
hanzo-tools Package Design
The hanzo-tools package extracts the tool framework from hanzo-mcp to provide a reusable foundation for building tools across all Hanzo packages.
Package Structure
pkg/hanzo-tools/
├── pyproject.toml
├── README.md
├── src/
│ └── hanzo_tools/
│ ├── __init__.py
│ ├── base.py # BaseTool abstract class
│ ├── registry.py # ToolRegistry for registration
│ ├── context.py # ToolContext management
│ ├── permissions.py # PermissionManager
│ ├── decorators.py # @tool decorator
│ ├── batch.py # BatchTool for parallel execution
│ ├── pagination.py # Pagination support
│ ├── streaming.py # StreamingTool base
│ ├── errors.py # Tool-specific exceptions
│ └── utils.py # Utility functions
└── tests/
├── test_base.py
├── test_registry.py
├── test_permissions.py
└── test_batch.py
Core Components
1. BaseTool (base.py)
from abc import ABC, abstractmethod
from typing import Any, Dict, Optional, TypeVar, Generic
T = TypeVar('T', bound='BaseTool')
class BaseTool(ABC, Generic[T]):
"""Abstract base class for all tools."""
name: str
description: str
version: str = "1.0.0"
def __init__(self, permission_manager: Optional['PermissionManager'] = None):
self.permission_manager = permission_manager
self._validate()
@abstractmethod
async def call(self, context: 'ToolContext', **kwargs) -> Any:
"""Execute the tool with given context and arguments."""
pass
def _validate(self) -> None:
"""Validate tool configuration."""
if not self.name:
raise ValueError("Tool must have a name")
if not self.description:
raise ValueError("Tool must have a description")
@classmethod
def register(cls: type[T], registry: 'ToolRegistry') -> T:
"""Register this tool with a registry."""
tool = cls()
registry.register(tool)
return tool
2. ToolRegistry (registry.py)
from typing import Dict, List, Optional, Protocol
import inspect
class ToolProtocol(Protocol):
"""Protocol for tool registration."""
name: str
description: str
async def call(self, context: 'ToolContext', **kwargs) -> Any: ...
class ToolRegistry:
"""Registry for managing tools."""
def __init__(self):
self._tools: Dict[str, ToolProtocol] = {}
self._categories: Dict[str, List[str]] = {}
def register(self, tool: ToolProtocol, category: str = "general") -> None:
"""Register a tool."""
if tool.name in self._tools:
raise ValueError(f"Tool '{tool.name}' already registered")
self._tools[tool.name] = tool
if category not in self._categories:
self._categories[category] = []
self._categories[category].append(tool.name)
def get(self, name: str) -> Optional[ToolProtocol]:
"""Get a tool by name."""
return self._tools.get(name)
def list_tools(self) -> List[str]:
"""List all registered tool names."""
return list(self._tools.keys())
def list_by_category(self, category: str) -> List[str]:
"""List tools in a category."""
return self._categories.get(category, [])
3. Tool Decorator (decorators.py)
from functools import wraps
from typing import Callable, Any, Optional
import inspect
def tool(
name: Optional[str] = None,
description: Optional[str] = None,
category: str = "general",
permissions: Optional[List[str]] = None
):
"""Decorator to create a tool from a function."""
def decorator(func: Callable) -> 'FunctionTool':
tool_name = name or func.__name__
tool_desc = description or func.__doc__ or "No description"
# Extract parameters from function signature
sig = inspect.signature(func)
params = {}
for param_name, param in sig.parameters.items():
if param_name not in ['self', 'context']:
params[param_name] = {
'type': param.annotation,
'required': param.default == param.empty,
'default': param.default if param.default != param.empty else None
}
class FunctionTool(BaseTool):
name = tool_name
description = tool_desc
parameters = params
required_permissions = permissions or []
async def call(self, context: ToolContext, **kwargs):
# Check permissions
if self.permission_manager and self.required_permissions:
for perm in self.required_permissions:
if not self.permission_manager.has_permission(perm):
raise PermissionError(f"Missing permission: {perm}")
# Call the wrapped function
if inspect.iscoroutinefunction(func):
return await func(context=context, **kwargs)
else:
return func(context=context, **kwargs)
return FunctionTool()
return decorator
4. BatchTool (batch.py)
import asyncio
from typing import List, Dict, Any, Callable
from concurrent.futures import ThreadPoolExecutor
class BatchTool(BaseTool):
"""Tool for executing multiple operations in parallel."""
name = "batch"
description = "Execute multiple tool calls in parallel"
def __init__(self, registry: ToolRegistry, max_workers: int = 10):
super().__init__()
self.registry = registry
self.max_workers = max_workers
async def call(self, context: ToolContext, operations: List[Dict[str, Any]]) -> List[Any]:
"""Execute multiple operations in parallel.
Args:
context: Tool context
operations: List of dicts with 'tool' and 'args' keys
Returns:
List of results in the same order as operations
"""
tasks = []
for op in operations:
tool_name = op.get('tool')
args = op.get('args', {})
tool = self.registry.get(tool_name)
if not tool:
raise ValueError(f"Unknown tool: {tool_name}")
# Create task for this operation
task = asyncio.create_task(tool.call(context, **args))
tasks.append(task)
# Wait for all tasks to complete
results = await asyncio.gather(*tasks, return_exceptions=True)
# Process results
processed_results = []
for i, result in enumerate(results):
if isinstance(result, Exception):
processed_results.append({
'error': str(result),
'tool': operations[i]['tool']
})
else:
processed_results.append({
'result': result,
'tool': operations[i]['tool']
})
return processed_results
5. Permissions (permissions.py)
from typing import Set, List, Optional
from pathlib import Path
import fnmatch
class PermissionManager:
"""Manage permissions for tool execution."""
def __init__(self):
self._allowed_paths: Set[Path] = set()
self._denied_paths: Set[Path] = set()
self._permissions: Set[str] = set()
def add_allowed_path(self, path: str) -> None:
"""Add an allowed path."""
self._allowed_paths.add(Path(path).resolve())
def add_denied_path(self, path: str) -> None:
"""Add a denied path."""
self._denied_paths.add(Path(path).resolve())
def is_path_allowed(self, path: str) -> bool:
"""Check if a path is allowed."""
p = Path(path).resolve()
# Check denied paths first
for denied in self._denied_paths:
if p.is_relative_to(denied):
return False
# Check allowed paths
for allowed in self._allowed_paths:
if p.is_relative_to(allowed):
return True
# Default deny if no allowed paths configured
return len(self._allowed_paths) == 0
def grant_permission(self, permission: str) -> None:
"""Grant a permission."""
self._permissions.add(permission)
def revoke_permission(self, permission: str) -> None:
"""Revoke a permission."""
self._permissions.discard(permission)
def has_permission(self, permission: str) -> bool:
"""Check if a permission is granted."""
return permission in self._permissions
Usage Examples
Creating a Simple Tool
from hanzo_tools import tool, ToolContext
@tool(name="greet", description="Greet someone", category="social")
async def greet_tool(context: ToolContext, name: str, formal: bool = False) -> str:
if formal:
return f"Good day, {name}."
return f"Hello, {name}!"
Creating a Class-Based Tool
from hanzo_tools import BaseTool, ToolContext
class FileReadTool(BaseTool):
name = "read_file"
description = "Read contents of a file"
async def call(self, context: ToolContext, path: str) -> str:
# Check permissions
if not self.permission_manager.is_path_allowed(path):
raise PermissionError(f"Access denied: {path}")
with open(path, 'r') as f:
return f.read()
Using the Registry
from hanzo_tools import ToolRegistry, PermissionManager
# Create registry and permission manager
registry = ToolRegistry()
pm = PermissionManager()
pm.add_allowed_path("/workspace")
# Register tools
greet_tool.register(registry)
FileReadTool(pm).register(registry)
# Use tools
context = ToolContext()
result = await registry.get("greet").call(context, name="World")
Batch Execution
from hanzo_tools import BatchTool
batch = BatchTool(registry)
results = await batch.call(context, operations=[
{"tool": "greet", "args": {"name": "Alice"}},
{"tool": "greet", "args": {"name": "Bob", "formal": True}},
{"tool": "read_file", "args": {"path": "/workspace/readme.txt"}}
])
Integration with MCP
hanzo-mcp would use hanzo-tools as its foundation:
# In hanzo-mcp
from hanzo_tools import BaseTool, ToolRegistry, tool
from mcp.server import FastMCP
class MCPToolAdapter:
"""Adapt hanzo-tools for MCP server."""
def __init__(self, mcp_server: FastMCP, registry: ToolRegistry):
self.mcp = mcp_server
self.registry = registry
def register_all(self):
"""Register all tools with MCP server."""
for tool_name in self.registry.list_tools():
tool = self.registry.get(tool_name)
self._register_mcp_tool(tool)
def _register_mcp_tool(self, tool: BaseTool):
"""Register a single tool with MCP."""
@self.mcp.tool(name=tool.name, description=tool.description)
async def mcp_handler(context, **kwargs):
# Convert MCP context to ToolContext
tool_context = self._convert_context(context)
return await tool.call(tool_context, **kwargs)
Benefits
- Reusable: Any package can use hanzo-tools to create tools
- Consistent: Same tool patterns everywhere
- Extensible: Easy to add new tool types
- Testable: Built-in test utilities
- Type-Safe: Full type hints throughout
- Async-First: Designed for async/await patterns