# 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

```python
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

```python
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.

```python
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:

```python
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

```python
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.