signalwire-agents 0.1.20__py3-none-any.whl → 0.1.23__py3-none-any.whl

signalwire_agents/core/agent/tools/decorator.py

@@ -0,0 +1,95 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire AI Agents SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+"""
+
+"""Tool decorator functionality."""
+
+from functools import wraps
+from typing import Callable, Optional, Dict, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ToolDecorator:
+    """Handles tool decoration logic."""
+    
+    @staticmethod
+    def create_instance_decorator(registry):
+        """
+        Create instance tool decorator.
+        
+        Args:
+            registry: ToolRegistry instance to register with
+            
+        Returns:
+            Decorator function
+        """
+        def decorator(name=None, **kwargs):
+            """
+            Decorator for defining SWAIG tools in a class.
+            
+            Used as:
+            
+            @agent.tool(name="example_function", parameters={...})
+            def example_function(self, param1):
+                # ...
+            """
+            def inner_decorator(func):
+                nonlocal name
+                if name is None:
+                    name = func.__name__
+                    
+                parameters = kwargs.pop("parameters", {})
+                description = kwargs.pop("description", func.__doc__ or f"Function {name}")
+                secure = kwargs.pop("secure", True)
+                fillers = kwargs.pop("fillers", None)
+                webhook_url = kwargs.pop("webhook_url", None)
+                
+                registry.define_tool(
+                    name=name,
+                    description=description,
+                    parameters=parameters,
+                    handler=func,
+                    secure=secure,
+                    fillers=fillers,
+                    webhook_url=webhook_url,
+                    **kwargs  # Pass through any additional swaig_fields
+                )
+                return func
+            return inner_decorator
+        return decorator
+    
+    @classmethod
+    def create_class_decorator(cls):
+        """
+        Create class tool decorator.
+        
+        Returns:
+            Decorator function
+        """
+        def tool(name=None, **kwargs):
+            """
+            Class method decorator for defining SWAIG tools.
+            
+            Used as:
+            
+            @AgentBase.tool(name="example_function", parameters={...})
+            def example_function(self, param1):
+                # ...
+            """
+            def decorator(func):
+                # Mark the function as a tool
+                func._is_tool = True
+                func._tool_name = name if name else func.__name__
+                func._tool_params = kwargs
+                
+                # Return the original function
+                return func
+            return decorator
+        return tool

signalwire_agents/core/agent/tools/registry.py

@@ -0,0 +1,192 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire AI Agents SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+"""
+
+"""Tool registration and management."""
+
+from typing import Dict, Any, Optional, List, Callable, Union
+import inspect
+import logging
+
+from signalwire_agents.core.swaig_function import SWAIGFunction
+
+logger = logging.getLogger(__name__)
+
+
+class ToolRegistry:
+    """Manages SWAIG function registration."""
+    
+    def __init__(self, agent):
+        """
+        Initialize ToolRegistry with reference to parent agent.
+        
+        Args:
+            agent: Parent AgentBase instance
+        """
+        self.agent = agent
+        self._swaig_functions = {}
+        self._class_decorated_tools = []
+    
+    def define_tool(
+        self, 
+        name: str, 
+        description: str, 
+        parameters: Dict[str, Any], 
+        handler: Callable,
+        secure: bool = True,
+        fillers: Optional[Dict[str, List[str]]] = None,
+        webhook_url: Optional[str] = None,
+        **swaig_fields
+    ) -> None:
+        """
+        Define a SWAIG function that the AI can call.
+        
+        Args:
+            name: Function name (must be unique)
+            description: Function description for the AI
+            parameters: JSON Schema of parameters
+            handler: Function to call when invoked
+            secure: Whether to require token validation
+            fillers: Optional dict mapping language codes to arrays of filler phrases
+            webhook_url: Optional external webhook URL to use instead of local handling
+            **swaig_fields: Additional SWAIG fields to include in function definition
+            
+        Raises:
+            ValueError: If tool name already exists
+        """
+        if name in self._swaig_functions:
+            raise ValueError(f"Tool with name '{name}' already exists")
+            
+        self._swaig_functions[name] = SWAIGFunction(
+            name=name,
+            description=description,
+            parameters=parameters,
+            handler=handler,
+            secure=secure,
+            fillers=fillers,
+            webhook_url=webhook_url,
+            **swaig_fields
+        )
+        
+        logger.debug(f"Defined tool: {name}")
+    
+    def register_swaig_function(self, function_dict: Dict[str, Any]) -> None:
+        """
+        Register a raw SWAIG function dictionary (e.g., from DataMap.to_swaig_function()).
+        
+        Args:
+            function_dict: Complete SWAIG function definition dictionary
+            
+        Raises:
+            ValueError: If function name missing or already exists
+        """
+        function_name = function_dict.get('function')
+        if not function_name:
+            raise ValueError("Function dictionary must contain 'function' field with the function name")
+            
+        if function_name in self._swaig_functions:
+            raise ValueError(f"Tool with name '{function_name}' already exists")
+        
+        # Store the raw function dictionary for data_map tools
+        # These don't have handlers since they execute on SignalWire's server
+        self._swaig_functions[function_name] = function_dict
+        
+        logger.debug(f"Registered SWAIG function: {function_name}")
+    
+    def register_class_decorated_tools(self) -> None:
+        """
+        Register tools defined with @AgentBase.tool class decorator.
+        
+        This method scans the class for methods decorated with @AgentBase.tool
+        and registers them automatically.
+        """
+        # Get the class of this instance
+        cls = self.agent.__class__
+        
+        # Loop through all attributes in the class
+        for name in dir(cls):
+            # Get the attribute
+            attr = getattr(cls, name)
+            
+            # Check if it's a method decorated with @AgentBase.tool
+            if inspect.ismethod(attr) or inspect.isfunction(attr):
+                if hasattr(attr, "_is_tool") and getattr(attr, "_is_tool", False):
+                    # Extract tool information
+                    tool_name = getattr(attr, "_tool_name", name)
+                    tool_params = getattr(attr, "_tool_params", {})
+                    
+                    # Extract known parameters and pass through the rest as swaig_fields
+                    tool_params_copy = tool_params.copy()
+                    description = tool_params_copy.pop("description", attr.__doc__ or f"Function {tool_name}")
+                    parameters = tool_params_copy.pop("parameters", {})
+                    secure = tool_params_copy.pop("secure", True)
+                    fillers = tool_params_copy.pop("fillers", None)
+                    webhook_url = tool_params_copy.pop("webhook_url", None)
+                    
+                    # Register the tool with any remaining params as swaig_fields
+                    self.define_tool(
+                        name=tool_name,
+                        description=description,
+                        parameters=parameters,
+                        handler=attr.__get__(self.agent, cls),  # Bind the method to this instance
+                        secure=secure,
+                        fillers=fillers,
+                        webhook_url=webhook_url,
+                        **tool_params_copy  # Pass through any additional swaig_fields
+                    )
+                    
+                    logger.debug(f"Registered class-decorated tool: {tool_name}")
+    
+    def get_function(self, name: str) -> Optional[Union[SWAIGFunction, Dict[str, Any]]]:
+        """
+        Get a registered function by name.
+        
+        Args:
+            name: Function name
+            
+        Returns:
+            SWAIGFunction instance or raw function dict, or None if not found
+        """
+        return self._swaig_functions.get(name)
+    
+    def get_all_functions(self) -> Dict[str, Union[SWAIGFunction, Dict[str, Any]]]:
+        """
+        Get all registered functions.
+        
+        Returns:
+            Dictionary of function name to function object/dict
+        """
+        return self._swaig_functions.copy()
+    
+    def has_function(self, name: str) -> bool:
+        """
+        Check if a function is registered.
+        
+        Args:
+            name: Function name
+            
+        Returns:
+            True if function exists, False otherwise
+        """
+        return name in self._swaig_functions
+    
+    def remove_function(self, name: str) -> bool:
+        """
+        Remove a registered function.
+        
+        Args:
+            name: Function name
+            
+        Returns:
+            True if removed, False if not found
+        """
+        if name in self._swaig_functions:
+            del self._swaig_functions[name]
+            logger.debug(f"Removed function: {name}")
+            return True
+        return False