signalwire-agents 0.1.6__py3-none-any.whl → 1.0.7__py3-none-any.whl

signalwire_agents/core/skill_base.py

@@ -0,0 +1,200 @@
+"""
+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.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, TYPE_CHECKING, Optional
+import logging
+
+if TYPE_CHECKING:
+    from signalwire_agents.core.agent_base import AgentBase
+
+class SkillBase(ABC):
+    """Abstract base class for all agent skills"""
+    
+    # Subclasses must define these
+    SKILL_NAME: str = None           # Required: unique identifier
+    SKILL_DESCRIPTION: str = None    # Required: human-readable description
+    SKILL_VERSION: str = "1.0.0"     # Semantic version
+    REQUIRED_PACKAGES: List[str] = [] # Python packages needed
+    REQUIRED_ENV_VARS: List[str] = [] # Environment variables needed
+    
+    # Multiple instance support
+    SUPPORTS_MULTIPLE_INSTANCES: bool = False  # Set to True to allow multiple instances
+    
+    def __init__(self, agent: 'AgentBase', params: Optional[Dict[str, Any]] = None):
+        if self.SKILL_NAME is None:
+            raise ValueError(f"{self.__class__.__name__} must define SKILL_NAME")
+        if self.SKILL_DESCRIPTION is None:
+            raise ValueError(f"{self.__class__.__name__} must define SKILL_DESCRIPTION")
+            
+        self.agent = agent
+        self.params = params or {}
+        self.logger = logging.getLogger(f"skill.{self.SKILL_NAME}")
+        
+        # Extract swaig_fields from params for merging into tool definitions
+        self.swaig_fields = self.params.pop('swaig_fields', {})
+        
+    @abstractmethod
+    def setup(self) -> bool:
+        """
+        Setup the skill (validate env vars, initialize APIs, etc.)
+        Returns True if setup successful, False otherwise
+        """
+        pass
+        
+    @abstractmethod
+    def register_tools(self) -> None:
+        """Register SWAIG tools with the agent"""
+        pass
+        
+    def define_tool(self, **kwargs) -> None:
+        """
+        Wrapper method that automatically includes swaig_fields when defining tools.
+        
+        This method delegates to self.agent.define_tool() but automatically merges
+        any swaig_fields configured for this skill. Skills should use this method
+        instead of calling self.agent.define_tool() directly.
+        
+        Args:
+            **kwargs: All arguments supported by agent.define_tool()
+                     (name, description, parameters, handler, etc.)
+        """
+        # Merge swaig_fields with any explicitly passed fields
+        # Explicit fields take precedence over swaig_fields
+        merged_kwargs = dict(self.swaig_fields)
+        merged_kwargs.update(kwargs)
+        
+        # Call the agent's define_tool with merged arguments
+        return self.agent.define_tool(**merged_kwargs)
+        
+
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints for this skill"""
+        return []
+        
+    def get_global_data(self) -> Dict[str, Any]:
+        """Return data to add to agent's global context"""
+        return {}
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return []
+        
+    def cleanup(self) -> None:
+        """Cleanup when skill is removed or agent shuts down"""
+        pass
+        
+    def validate_env_vars(self) -> bool:
+        """Check if all required environment variables are set"""
+        import os
+        missing = [var for var in self.REQUIRED_ENV_VARS if not os.getenv(var)]
+        if missing:
+            self.logger.error(f"Missing required environment variables: {missing}")
+            return False
+        return True
+        
+    def validate_packages(self) -> bool:
+        """Check if all required packages are available"""
+        import importlib
+        missing = []
+        for package in self.REQUIRED_PACKAGES:
+            try:
+                importlib.import_module(package)
+            except ImportError:
+                missing.append(package)
+        if missing:
+            self.logger.error(f"Missing required packages: {missing}")
+            return False
+        return True
+        
+    def get_instance_key(self) -> str:
+        """
+        Get the key used to track this skill instance
+        
+        For skills that support multiple instances (SUPPORTS_MULTIPLE_INSTANCES = True),
+        this method can be overridden to provide a unique key for each instance.
+        
+        Default implementation:
+        - If SUPPORTS_MULTIPLE_INSTANCES is False: returns SKILL_NAME
+        - If SUPPORTS_MULTIPLE_INSTANCES is True: returns SKILL_NAME + "_" + tool_name
+          (where tool_name comes from params['tool_name'] or defaults to the skill name)
+        
+        Returns:
+            str: Unique key for this skill instance
+        """
+        if not self.SUPPORTS_MULTIPLE_INSTANCES:
+            return self.SKILL_NAME
+            
+        # For multi-instance skills, create key from skill name + tool name
+        tool_name = self.params.get('tool_name', self.SKILL_NAME)
+        return f"{self.SKILL_NAME}_{tool_name}"
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """
+        Get the parameter schema for this skill
+        
+        This method returns metadata about all parameters the skill accepts,
+        including their types, descriptions, default values, and whether they
+        are required or should be hidden (e.g., API keys).
+        
+        The base implementation provides common parameters available to all skills.
+        Subclasses should override this method and merge their specific parameters
+        with the base schema.
+        
+        Returns:
+            Dict[str, Dict[str, Any]]: Parameter schema where keys are parameter names
+            and values are dictionaries containing:
+                - type: Parameter type ("string", "integer", "number", "boolean", "object", "array")
+                - description: Human-readable description
+                - default: Default value if not provided (optional)
+                - required: Whether the parameter is required (default: False)
+                - hidden: Whether to hide this field in UIs (for secrets/keys)
+                - env_var: Environment variable that can provide this value (optional)
+                - enum: List of allowed values (optional)
+                - min/max: Minimum/maximum values for numeric types (optional)
+        
+        Example:
+            {
+                "tool_name": {
+                    "type": "string",
+                    "description": "Name for the tool when using multiple instances",
+                    "default": "my_skill",
+                    "required": False
+                },
+                "api_key": {
+                    "type": "string",
+                    "description": "API key for the service",
+                    "required": True,
+                    "hidden": True,
+                    "env_var": "MY_API_KEY"
+                }
+            }
+        """
+        schema = {}
+        
+        # Add swaig_fields parameter (available to all skills)
+        schema["swaig_fields"] = {
+            "type": "object",
+            "description": "Additional SWAIG function metadata to merge into tool definitions",
+            "default": {},
+            "required": False
+        }
+        
+        # Add tool_name for multi-instance skills
+        if cls.SUPPORTS_MULTIPLE_INSTANCES:
+            schema["tool_name"] = {
+                "type": "string",
+                "description": "Custom name for this skill instance (for multiple instances)",
+                "default": cls.SKILL_NAME,
+                "required": False
+            }
+        
+        return schema 

signalwire_agents/core/skill_manager.py

@@ -0,0 +1,244 @@
+"""
+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.
+"""
+
+from typing import Dict, List, Type, Any, Optional
+from signalwire_agents.core.logging_config import get_logger
+from signalwire_agents.core.skill_base import SkillBase
+
+class SkillManager:
+    """Manages loading and lifecycle of agent skills"""
+    
+    def __init__(self, agent):
+        self.agent = agent
+        self.loaded_skills: Dict[str, SkillBase] = {}
+        self.logger = get_logger("skill_manager")
+        
+    def load_skill(self, skill_name: str, skill_class: Type[SkillBase] = None, params: Optional[Dict[str, Any]] = None) -> tuple[bool, str]:
+        """
+        Load and setup a skill by name
+        
+        Args:
+            skill_name: Name of the skill to load
+            skill_class: Optional skill class (if not provided, will try to find it)
+            params: Optional parameters to pass to the skill
+            
+        Returns:
+            tuple: (success, error_message) - error_message is empty string if successful
+        """
+        # Get skill class from registry if not provided
+        if skill_class is None:
+            try:
+                from signalwire_agents.skills.registry import skill_registry
+                skill_class = skill_registry.get_skill_class(skill_name)
+                if skill_class is None:
+                    error_msg = f"Skill '{skill_name}' not found in registry"
+                    self.logger.error(error_msg)
+                    return False, error_msg
+            except ImportError:
+                error_msg = f"Skills registry not available. Cannot load skill '{skill_name}'"
+                self.logger.error(error_msg)
+                return False, error_msg
+        
+        # Validate that the skill has a proper parameter schema
+        if not hasattr(skill_class, 'get_parameter_schema') or not callable(getattr(skill_class, 'get_parameter_schema')):
+            error_msg = f"Skill '{skill_name}' must have get_parameter_schema() classmethod"
+            self.logger.error(error_msg)
+            return False, error_msg
+        
+        try:
+            # Validate the parameter schema
+            schema = skill_class.get_parameter_schema()
+            if not isinstance(schema, dict):
+                error_msg = f"Skill '{skill_name}'.get_parameter_schema() must return a dictionary"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Ensure it's not an empty schema
+            if not schema:
+                error_msg = f"Skill '{skill_name}'.get_parameter_schema() returned empty dictionary"
+                self.logger.error(error_msg)
+                return False, error_msg
+            
+            # Check if the skill has overridden the method
+            from signalwire_agents.core.skill_base import SkillBase
+            skill_method = getattr(skill_class, 'get_parameter_schema', None)
+            base_method = getattr(SkillBase, 'get_parameter_schema', None)
+            
+            if skill_method and base_method:
+                # For class methods, check the underlying function
+                skill_func = skill_method.__func__ if hasattr(skill_method, '__func__') else skill_method
+                base_func = base_method.__func__ if hasattr(base_method, '__func__') else base_method
+                
+                if skill_func is base_func:
+                    # Get base schema to check if skill added any parameters
+                    base_schema = SkillBase.get_parameter_schema()
+                    if set(schema.keys()) == set(base_schema.keys()):
+                        error_msg = f"Skill '{skill_name}' must override get_parameter_schema() to define its specific parameters"
+                        self.logger.error(error_msg)
+                        return False, error_msg
+                
+        except AttributeError as e:
+            error_msg = f"Skill '{skill_name}' must properly implement get_parameter_schema() classmethod"
+            self.logger.error(error_msg)
+            return False, error_msg
+        except Exception as e:
+            error_msg = f"Skill '{skill_name}'.get_parameter_schema() failed: {e}"
+            self.logger.error(error_msg)
+            return False, error_msg
+        
+        try:
+            # Create skill instance with parameters to get the instance key
+            skill_instance = skill_class(self.agent, params)
+            instance_key = skill_instance.get_instance_key()
+            
+            # Check if this instance is already loaded
+            if instance_key in self.loaded_skills:
+                # For single-instance skills, this is an error
+                if not skill_instance.SUPPORTS_MULTIPLE_INSTANCES:
+                    error_msg = f"Skill '{skill_name}' is already loaded and does not support multiple instances"
+                    self.logger.error(error_msg)
+                    return False, error_msg
+                else:
+                    # For multi-instance skills, just warn and return success
+                    self.logger.warning(f"Skill instance '{instance_key}' is already loaded")
+                    return True, ""
+            
+            # Validate environment variables with specific error details
+            import os
+            missing_env_vars = [var for var in skill_instance.REQUIRED_ENV_VARS if not os.getenv(var)]
+            if missing_env_vars:
+                error_msg = f"Missing required environment variables: {missing_env_vars}"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Validate packages with specific error details  
+            import importlib
+            missing_packages = []
+            for package in skill_instance.REQUIRED_PACKAGES:
+                try:
+                    importlib.import_module(package)
+                except ImportError:
+                    missing_packages.append(package)
+            if missing_packages:
+                error_msg = f"Missing required packages: {missing_packages}"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Setup the skill
+            if not skill_instance.setup():
+                error_msg = f"Failed to setup skill '{skill_name}'"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Register tools with agent
+            skill_instance.register_tools()
+            
+            # Add hints and global data to agent
+            hints = skill_instance.get_hints()
+            if hints:
+                self.agent.add_hints(hints)
+                
+            global_data = skill_instance.get_global_data()
+            if global_data:
+                self.agent.update_global_data(global_data)
+                
+            # Add prompt sections
+            prompt_sections = skill_instance.get_prompt_sections()
+            for section in prompt_sections:
+                self.agent.prompt_add_section(**section)
+            
+            # Store loaded skill using instance key
+            self.loaded_skills[instance_key] = skill_instance
+            self.logger.info(f"Successfully loaded skill instance '{instance_key}' (skill: '{skill_name}')")
+            return True, ""
+            
+        except ValueError as e:
+            # Check if this is a duplicate tool registration (expected during agent cloning)
+            if "already exists" in str(e):
+                debug_msg = f"Skill '{skill_name}' already loaded, skipping duplicate registration"
+                self.logger.debug(debug_msg)
+                return True, ""  # Not an error, skill is already available
+            else:
+                error_msg = f"Error loading skill '{skill_name}': {e}"
+                self.logger.error(error_msg)
+                return False, error_msg
+        except Exception as e:
+            error_msg = f"Error loading skill '{skill_name}': {e}"
+            self.logger.error(error_msg)
+            return False, error_msg
+    
+    def unload_skill(self, skill_identifier: str) -> bool:
+        """
+        Unload a skill and cleanup
+        
+        Args:
+            skill_identifier: Either a skill name or an instance key
+            
+        Returns:
+            bool: True if successfully unloaded, False otherwise
+        """
+        # Try to find the skill by identifier (could be skill name or instance key)
+        skill_instance = None
+        instance_key = None
+        
+        # First try as direct instance key
+        if skill_identifier in self.loaded_skills:
+            instance_key = skill_identifier
+            skill_instance = self.loaded_skills[skill_identifier]
+        
+        if skill_instance is None:
+            self.logger.warning(f"Skill '{skill_identifier}' is not loaded")
+            return False
+            
+        try:
+            skill_instance.cleanup()
+            del self.loaded_skills[instance_key]
+            self.logger.info(f"Successfully unloaded skill instance '{instance_key}'")
+            return True
+        except Exception as e:
+            self.logger.error(f"Error unloading skill '{skill_identifier}': {e}")
+            return False
+    
+    def list_loaded_skills(self) -> List[str]:
+        """List instance keys of currently loaded skills"""
+        return list(self.loaded_skills.keys())
+    
+    def has_skill(self, skill_identifier: str) -> bool:
+        """
+        Check if skill is currently loaded
+        
+        Args:
+            skill_identifier: Either a skill name or an instance key
+            
+        Returns:
+            bool: True if loaded, False otherwise
+        """
+        # First try as direct instance key
+        if skill_identifier in self.loaded_skills:
+            return True
+        
+        return False
+    
+    def get_skill(self, skill_identifier: str) -> Optional[SkillBase]:
+        """
+        Get a loaded skill instance by identifier
+        
+        Args:
+            skill_identifier: Either a skill name or an instance key
+            
+        Returns:
+            SkillBase: The skill instance if found, None otherwise
+        """
+        # First try as direct instance key
+        if skill_identifier in self.loaded_skills:
+            return self.loaded_skills[skill_identifier]
+        
+        return None
+    
+ 

signalwire_agents/core/swaig_function.py

@@ -15,6 +15,8 @@ from typing import Dict, Any, Optional, Callable, List, Type, Union
 import inspect
 import logging
 
+# Import here to avoid circular imports
+from signalwire_agents.core.function_result import SwaigFunctionResult
 
 class SWAIGFunction:
     """
@@ -27,7 +29,12 @@ class SWAIGFunction:
         description: str,
         parameters: Dict[str, Dict] = None,
         secure: bool = False,
-        fillers: Optional[Dict[str, List[str]]] = None
+        fillers: Optional[Dict[str, List[str]]] = None,
+        wait_file: Optional[str] = None,
+        wait_file_loops: Optional[int] = None,
+        webhook_url: Optional[str] = None,
+        required: Optional[List[str]] = None,
+        **extra_swaig_fields
     ):
         """
         Initialize a new SWAIG function
@@ -38,14 +45,27 @@ class SWAIGFunction:
             description: Human-readable description of the function
             parameters: Dictionary of parameters, keys are parameter names, values are param definitions
             secure: Whether this function requires token validation
-            fillers: Optional dictionary of filler phrases by language code
+            fillers: Optional dictionary of filler phrases by language code (deprecated, use wait_file)
+            wait_file: Optional URL to audio file to play while function executes
+            wait_file_loops: Optional number of times to loop the wait_file
+            webhook_url: Optional external webhook URL to use instead of local handling
+            required: Optional list of required parameter names
+            **extra_swaig_fields: Additional SWAIG fields to include in function definition
         """
         self.name = name
         self.handler = handler
         self.description = description
         self.parameters = parameters or {}
         self.secure = secure
-        self.fillers = fillers
+        self.fillers = fillers  # Text phrases to say while processing
+        self.wait_file = wait_file  # URL to audio/video file to play while waiting
+        self.wait_file_loops = wait_file_loops
+        self.webhook_url = webhook_url
+        self.required = required or []
+        self.extra_swaig_fields = extra_swaig_fields
+        
+        # Mark as external if webhook_url is provided
+        self.is_external = webhook_url is not None
         
     def _ensure_parameter_structure(self) -> Dict:
         """
@@ -62,11 +82,17 @@ class SWAIGFunction:
             return self.parameters
             
         # Otherwise, wrap the parameters in the expected structure
-        return {
+        result = {
             "type": "object",
             "properties": self.parameters
         }
         
+        # Add required fields if specified
+        if self.required:
+            result["required"] = self.required
+            
+        return result
+        
     def __call__(self, *args, **kwargs):
         """
         Call the underlying handler function
@@ -92,9 +118,6 @@ class SWAIGFunction:
             # Call the handler with both args and raw_data
             result = self.handler(args, raw_data)
                 
-            # Import here to avoid circular imports
-            from signalwire_agents.core.function_result import SwaigFunctionResult
-            
             # Handle different result types - everything must end up as a SwaigFunctionResult
             if isinstance(result, SwaigFunctionResult):
                 # Already a SwaigFunctionResult - just convert to dict
@@ -165,8 +188,9 @@ class SWAIGFunction:
         # Add fillers if provided
         if self.fillers and len(self.fillers) > 0:
             function_def["fillers"] = self.fillers
+        
+        # Add any extra SWAIG fields
+        function_def.update(self.extra_swaig_fields)
             
         return function_def
 
-# Add an alias for backward compatibility
-SwaigFunction = SWAIGFunction