Tools System

@dataclass
class ToolDefinition:
    name: str                    # Unique tool identifier
    summary: str                 # Short description (~15 tokens) for discovery
    description: str             # Full description for LLM tool binding
    category: str                # "calendar", "gmail", "tasks"
    actions: List[str]           # ["search", "create", "delete", etc.]
    is_write: bool              # Requires confirmation for destructive ops
    schema: Type[BaseModel]      # Pydantic model for parameters
    method_name: str             # Method name on AgentTools class

TOOL_DEFINITIONS = {
    "add_calendar_event": ToolDefinition(
        name="add_calendar_event",
        summary="Create a new calendar event with title, time, and optional attendees",
        description="Add a new event to the user's Google Calendar. Use this when the user wants to schedule a meeting, appointment, or any calendar event.",
        category="calendar",
        actions=["create", "write"],
        is_write=True,
        schema=schemas.AddCalendarEventParams,
    ),
    "delete_calendar_event": ToolDefinition(
        name="delete_calendar_event",
        summary="Delete a calendar event by its ID",
        description="Delete an event from the user's Google Calendar by its event ID. Always confirm with the user before deleting.",
        category="calendar",
        actions=["delete", "write"],
        is_write=True,
        schema=schemas.DeleteCalendarEventParams,
    ),
    # ... more tools
}

class AgentTools:
    """Collection of tool wrapper functions for the agent."""
    
    def __init__(self, calendar_service, gmail_service, tasks_service, default_timezone="UTC"):
        self.calendar = calendar_service
        self.gmail = gmail_service
        self.tasks = tasks_service
        self.default_timezone = default_timezone
        
        # Build tool registry from definitions
        self._tool_registry = self._build_tool_registry()
    
    def _build_tool_registry(self) -> dict[str, dict]:
        """Build registry mapping tool names to functions and schemas."""
        registry = {}
        
        for name, defn in TOOL_DEFINITIONS.items():
            # Get the method from this instance
            method = getattr(self, defn.method_name, None)
            if method is None:
                raise AttributeError(f"Tool '{name}' references method '{defn.method_name}' which does not exist")
            
            registry[name] = {
                "function": method,
                "model": defn.schema,
                "description": defn.description,
            }
        
        return registry

def execute_tool(self, name: str, arguments: dict) -> dict:
    """Execute a tool by name with given arguments."""
    tool = self._tool_registry.get(name)
    if not tool:
        return {
            "success": False,
            "message": f"Unknown tool: {name}",
            "error": f"Tool '{name}' not found in registry",
        }
    
    try:
        # Validate arguments with Pydantic model
        model = tool["model"]
        validated_params = model(**arguments)
        
        # Execute the function
        func = tool["function"]
        result = func(**validated_params.model_dump())
        return result
        
    except Exception as e:
        return {
            "success": False,
            "message": f"Error executing {name}: {str(e)}",
            "error": str(e),
        }

class AddCalendarEventParams(BaseModel):
    """Parameters for adding a calendar event."""
    title: str = Field(..., description="Event title")
    start_time: str = Field(..., description="Start time (natural language or ISO format)")
    end_time: Optional[str] = Field(None, description="End time (defaults to start_time + 1 hour)")
    duration: Optional[str] = Field(None, description="Duration like '2 hours' or '30 minutes'")
    description: str = Field("", description="Event description")
    attendees: Optional[List[str]] = Field(None, description="List of attendee email addresses")
    timezone: str = Field("UTC", description="Timezone (e.g., 'America/New_York')")

class DeleteCalendarEventParams(BaseModel):
    """Parameters for deleting a calendar event."""
    event_id: str = Field(..., description="Calendar event ID")

class MetaTools:
    """Meta-tools for lazy tool loading."""
    
    def __init__(self, tool_registry):
        self.tool_registry = tool_registry
        self._pending_confirmation = None
    
    def discover_tools(self, categories=None, actions=None, query=None) -> Dict[str, Any]:
        """Find available tools by category and/or action type."""
        return _discover_tools(categories=categories, actions=actions, query=query)
    
    def get_tool_schema(self, tool_name: str) -> Dict[str, Any]:
        """Get the complete parameter schema for a specific tool."""
        registry = self.tool_registry.get_tool_registry()
        tool_info = registry.get(tool_name)
        
        if not tool_info:
            return {"error": f"Unknown tool: {tool_name}"}
        
        # Get schema from Pydantic model
        model = tool_info["model"]
        schema = model.model_json_schema()
        
        return {
            "name": tool_name,
            "description": tool_info["description"],
            "parameters": schema.get("properties", {}),
            "required": schema.get("required", []),
        }
    
    def invoke_tool(self, tool_name: str, parameters=None) -> Dict[str, Any]:
        """Execute a tool with the given parameters."""
        if parameters is None:
            parameters = {}
        
        # Check if this is a destructive operation
        meta = TOOL_INDEX.get(tool_name)
        if meta and meta.is_write and "delete" in meta.actions:
            # Return confirmation request instead of executing
            return {
                "status": "pending_confirmation",
                "tool_name": tool_name,
                "parameters": parameters,
                "message": "This action requires user confirmation before execution",
            }
        
        # Execute the tool
        return self.tool_registry.execute_tool(tool_name, parameters)

def add_calendar_event(
    self,
    title: str,
    start_time: str,
    end_time: Optional[str] = None,
    duration: Optional[str] = None,
    description: str = "",
    attendees: Optional[list[str]] = None,
    timezone: str = "UTC",
) -> dict:
    """Add a new event to the calendar with parsed times."""
    try:
        # Parse natural language dates
        parsed_start, is_all_day = parse_datetime(start_time, timezone)
        
        if is_all_day:
            return self.calendar.add_event(
                title=title,
                start_time=parsed_start + "T00:00:00",
                end_time=parsed_start + "T23:59:59",
                description=description,
                attendees=attendees,
                timezone=timezone,
            )
        
        # Handle end_time or duration
        if end_time:
            parsed_end, _ = parse_datetime(end_time, timezone)
        elif duration:
            parsed_end = calculate_end_time(parsed_start, duration)
        else:
            parsed_end = calculate_end_time(parsed_start, "1 hour")
        
        # Call service layer
        return self.calendar.add_event(
            title=title,
            start_time=parsed_start,
            end_time=parsed_end,
            description=description,
            attendees=attendees,
            timezone=timezone,
        )
    
    except ValueError as e:
        return {
            "success": False,
            "message": f"Invalid date/time: {e}",
            "error": str(e),
        }