Tools & ToolManager

The Tools module provides an abstract tool interface and a central tool dispatcher (ToolManager) for agentic multi-turn rollouts. Tools follow the OpenAI function-calling schema for seamless integration with LLM tool-use capabilities.

Tool Base Class

from abc import ABC, abstractmethod
from twinkle.data_format import Tool as ToolInfo

class Tool(ABC):

    @abstractmethod
    def __call__(self, tool_name: str, arguments: Dict[str, Any]) -> str:
        """Execute the tool and return a string result."""
        raise NotImplementedError

    @abstractmethod
    def tool_info(self) -> ToolInfo:
        """Return OpenAI-compatible tool schema."""
        raise NotImplementedError

Implementing a Custom Tool

from twinkle_agentic.tools.base import Tool

class SearchTool(Tool):

    def __call__(self, tool_name: str, arguments: dict) -> str:
        query = arguments.get('query', '')
        # Perform search logic
        return f'Search results for: {query}'

    def tool_info(self):
        return {
            'type': 'function',
            'function': {
                'name': 'search',
                'description': 'Search the web for information.',
                'parameters': {
                    'type': 'object',
                    'properties': {
                        'query': {
                            'type': 'string',
                            'description': 'The search query.',
                        },
                    },
                    'required': ['query'],
                },
            },
        }

ToolManager

ToolManager is a registry and dispatcher for tools. It resolves tool calls from the LLM’s structured output and routes them to the correct tool implementation.

from twinkle_agentic.tools.tool_manager import ToolManager

# Initialize with a list of Tool instances
manager = ToolManager([search_tool, calculator_tool])

# Or with a dict
manager = ToolManager({'search': search_tool, 'calc': calculator_tool})

# Or register dynamically
manager = ToolManager()
manager.register(search_tool)
manager.register(calculator_tool)

Key Methods

Method	Description
`register(tool)`	Register a tool (name extracted from `tool_info()`).
`unregister(name)`	Remove a tool by name.
`names()`	List all registered tool names.
`copy()`	Create a shallow copy of the manager.
`tool_infos()`	Return a list of all tool schemas (for API requests).
`__call__(tool_call)`	Dispatch a tool call and return the result string.

Dispatching Tool Calls

ToolManager accepts OpenAI-shaped tool call dicts:

tool_call = {
    'id': 'call_1',
    'type': 'function',
    'function': {
        'name': 'search',
        'arguments': '{"query": "Python tutorials"}',
    },
}

result = manager(tool_call)
# result: 'Search results for: Python tutorials'

Error handling: If the tool name is unknown, arguments are invalid JSON, or the tool raises an exception, ToolManager returns a descriptive error string instead of raising — this keeps the rollout loop running.

Integration with Rollout

from twinkle_agentic.rollout.multi_turn import MultiTurnRollout

rollout = MultiTurnRollout(
    sampler=sampler,
    template=template,
    tool_manager=manager,  # Pass manager to rollout
    max_turns=6,
)

The rollout engine calls manager(tool_call) for each tool call generated by the model, and appends the result as a {'role': 'tool', 'content': result} message.