signalwire-agents 0.1.13__py3-none-any.whl → 1.0.17.dev4__py3-none-any.whl

signalwire_agents/core/security_config.py

@@ -0,0 +1,333 @@
+"""
+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.
+"""
+
+import os
+import secrets
+from typing import Dict, Any, Optional, Tuple, List, Union
+from signalwire_agents.core.logging_config import get_logger
+from signalwire_agents.core.config_loader import ConfigLoader
+
+logger = get_logger("security_config")
+
+
+class SecurityConfig:
+    """
+    Unified security configuration for SignalWire services.
+    
+    This class provides centralized security settings that can be used by
+    both SWML and Search services, ensuring consistent security behavior.
+    """
+    
+    # Security environment variable names
+    SSL_ENABLED = 'SWML_SSL_ENABLED'
+    SSL_CERT_PATH = 'SWML_SSL_CERT_PATH'
+    SSL_KEY_PATH = 'SWML_SSL_KEY_PATH'
+    SSL_DOMAIN = 'SWML_DOMAIN'
+    SSL_VERIFY_MODE = 'SWML_SSL_VERIFY_MODE'
+    
+    # Additional security settings
+    ALLOWED_HOSTS = 'SWML_ALLOWED_HOSTS'
+    CORS_ORIGINS = 'SWML_CORS_ORIGINS'
+    MAX_REQUEST_SIZE = 'SWML_MAX_REQUEST_SIZE'
+    RATE_LIMIT = 'SWML_RATE_LIMIT'
+    REQUEST_TIMEOUT = 'SWML_REQUEST_TIMEOUT'
+    USE_HSTS = 'SWML_USE_HSTS'
+    HSTS_MAX_AGE = 'SWML_HSTS_MAX_AGE'
+    
+    # Authentication
+    BASIC_AUTH_USER = 'SWML_BASIC_AUTH_USER'
+    BASIC_AUTH_PASSWORD = 'SWML_BASIC_AUTH_PASSWORD'
+    
+    # Defaults (secure by default)
+    DEFAULTS = {
+        SSL_ENABLED: False,  # Off by default, but secure when enabled
+        SSL_VERIFY_MODE: 'CERT_REQUIRED',
+        ALLOWED_HOSTS: '*',  # Accept all hosts by default for backward compatibility
+        CORS_ORIGINS: '*',  # Accept all origins by default for backward compatibility
+        MAX_REQUEST_SIZE: 10 * 1024 * 1024,  # 10MB
+        RATE_LIMIT: 60,  # Requests per minute
+        REQUEST_TIMEOUT: 30,  # Seconds
+        USE_HSTS: True,  # Enable HSTS when HTTPS is on
+        HSTS_MAX_AGE: 31536000,  # 1 year
+    }
+    
+    def __init__(self, config_file: Optional[str] = None, service_name: Optional[str] = None):
+        """
+        Initialize security configuration.
+        
+        Args:
+            config_file: Optional path to config file
+            service_name: Optional service name for finding service-specific config
+        """
+        # First, set defaults
+        self._set_defaults()
+        
+        # Then load from environment variables (backward compatibility)
+        self.load_from_env()
+        
+        # Finally, apply config file if available (highest priority)
+        self._load_config_file(config_file, service_name)
+    
+    def _set_defaults(self):
+        """Set default values for all configuration"""
+        # SSL configuration
+        self.ssl_enabled = self.DEFAULTS[self.SSL_ENABLED]
+        self.ssl_cert_path = None
+        self.ssl_key_path = None
+        self.domain = None
+        self.ssl_verify_mode = self.DEFAULTS[self.SSL_VERIFY_MODE]
+        
+        # Additional settings
+        self.allowed_hosts = self._parse_list(self.DEFAULTS[self.ALLOWED_HOSTS])
+        self.cors_origins = self._parse_list(self.DEFAULTS[self.CORS_ORIGINS])
+        self.max_request_size = self.DEFAULTS[self.MAX_REQUEST_SIZE]
+        self.rate_limit = self.DEFAULTS[self.RATE_LIMIT]
+        self.request_timeout = self.DEFAULTS[self.REQUEST_TIMEOUT]
+        self.use_hsts = self.DEFAULTS[self.USE_HSTS]
+        self.hsts_max_age = self.DEFAULTS[self.HSTS_MAX_AGE]
+        
+        # Authentication
+        self.basic_auth_user = None
+        self.basic_auth_password = None
+    
+    def _load_config_file(self, config_file: Optional[str], service_name: Optional[str]):
+        """Load configuration from config file if available"""
+        # Find config file
+        if not config_file:
+            config_file = ConfigLoader.find_config_file(service_name)
+        
+        if not config_file:
+            return
+        
+        # Load config
+        config_loader = ConfigLoader([config_file])
+        if not config_loader.has_config():
+            return
+        
+        logger.info("loading_config_from_file", file=config_file)
+        
+        # Get security section
+        security_config = config_loader.get_section('security')
+        if not security_config:
+            return
+        
+        # Apply security settings (config file takes precedence)
+        if 'ssl_enabled' in security_config:
+            self.ssl_enabled = security_config['ssl_enabled']
+        
+        if 'ssl_cert_path' in security_config:
+            self.ssl_cert_path = security_config['ssl_cert_path']
+            
+        if 'ssl_key_path' in security_config:
+            self.ssl_key_path = security_config['ssl_key_path']
+            
+        if 'domain' in security_config:
+            self.domain = security_config['domain']
+            
+        if 'ssl_verify_mode' in security_config:
+            self.ssl_verify_mode = security_config['ssl_verify_mode']
+        
+        # Additional settings
+        if 'allowed_hosts' in security_config:
+            self.allowed_hosts = self._parse_list(security_config['allowed_hosts'])
+            
+        if 'cors_origins' in security_config:
+            self.cors_origins = self._parse_list(security_config['cors_origins'])
+            
+        if 'max_request_size' in security_config:
+            self.max_request_size = int(security_config['max_request_size'])
+            
+        if 'rate_limit' in security_config:
+            self.rate_limit = int(security_config['rate_limit'])
+            
+        if 'request_timeout' in security_config:
+            self.request_timeout = int(security_config['request_timeout'])
+            
+        if 'use_hsts' in security_config:
+            self.use_hsts = security_config['use_hsts']
+            
+        if 'hsts_max_age' in security_config:
+            self.hsts_max_age = int(security_config['hsts_max_age'])
+        
+        # Authentication from config
+        auth_config = security_config.get('auth', {})
+        if isinstance(auth_config, dict):
+            basic_auth = auth_config.get('basic', {})
+            if isinstance(basic_auth, dict):
+                if 'user' in basic_auth:
+                    self.basic_auth_user = basic_auth['user']
+                if 'password' in basic_auth:
+                    self.basic_auth_password = basic_auth['password']
+        
+    def load_from_env(self):
+        """Load configuration from environment variables"""
+        # SSL configuration
+        ssl_enabled_env = os.environ.get(self.SSL_ENABLED, '').lower()
+        self.ssl_enabled = ssl_enabled_env in ('true', '1', 'yes')
+        self.ssl_cert_path = os.environ.get(self.SSL_CERT_PATH)
+        self.ssl_key_path = os.environ.get(self.SSL_KEY_PATH)
+        self.domain = os.environ.get(self.SSL_DOMAIN)
+        self.ssl_verify_mode = os.environ.get(self.SSL_VERIFY_MODE, self.DEFAULTS[self.SSL_VERIFY_MODE])
+        
+        # Additional security settings
+        self.allowed_hosts = self._parse_list(os.environ.get(self.ALLOWED_HOSTS, self.DEFAULTS[self.ALLOWED_HOSTS]))
+        self.cors_origins = self._parse_list(os.environ.get(self.CORS_ORIGINS, self.DEFAULTS[self.CORS_ORIGINS]))
+        self.max_request_size = int(os.environ.get(self.MAX_REQUEST_SIZE, self.DEFAULTS[self.MAX_REQUEST_SIZE]))
+        self.rate_limit = int(os.environ.get(self.RATE_LIMIT, self.DEFAULTS[self.RATE_LIMIT]))
+        self.request_timeout = int(os.environ.get(self.REQUEST_TIMEOUT, self.DEFAULTS[self.REQUEST_TIMEOUT]))
+        
+        # HSTS settings
+        use_hsts_env = os.environ.get(self.USE_HSTS, '').lower()
+        self.use_hsts = use_hsts_env != 'false' if use_hsts_env else self.DEFAULTS[self.USE_HSTS]
+        self.hsts_max_age = int(os.environ.get(self.HSTS_MAX_AGE, self.DEFAULTS[self.HSTS_MAX_AGE]))
+        
+        # Authentication
+        self.basic_auth_user = os.environ.get(self.BASIC_AUTH_USER)
+        self.basic_auth_password = os.environ.get(self.BASIC_AUTH_PASSWORD)
+        
+    def _parse_list(self, value: Union[str, list]) -> list:
+        """Parse comma-separated list from environment variable or list from config"""
+        if isinstance(value, list):
+            return value
+        if value == '*':
+            return ['*']
+        return [item.strip() for item in value.split(',') if item.strip()]
+    
+    def validate_ssl_config(self) -> Tuple[bool, Optional[str]]:
+        """
+        Validate SSL configuration.
+        
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not self.ssl_enabled:
+            return True, None
+            
+        if not self.ssl_cert_path:
+            return False, "SSL enabled but SWML_SSL_CERT_PATH not set"
+            
+        if not self.ssl_key_path:
+            return False, "SSL enabled but SWML_SSL_KEY_PATH not set"
+            
+        if not os.path.exists(self.ssl_cert_path):
+            return False, f"SSL certificate file not found: {self.ssl_cert_path}"
+            
+        if not os.path.exists(self.ssl_key_path):
+            return False, f"SSL key file not found: {self.ssl_key_path}"
+            
+        return True, None
+    
+    def get_ssl_context_kwargs(self) -> Dict[str, Any]:
+        """
+        Get SSL context kwargs for uvicorn.
+        
+        Returns:
+            Dictionary of SSL parameters for uvicorn
+        """
+        if not self.ssl_enabled:
+            return {}
+            
+        is_valid, error = self.validate_ssl_config()
+        if not is_valid:
+            logger.error("ssl_validation_failed", error=error)
+            return {}
+            
+        return {
+            'ssl_certfile': self.ssl_cert_path,
+            'ssl_keyfile': self.ssl_key_path,
+            # Additional SSL options can be added here
+        }
+    
+    def get_basic_auth(self) -> Tuple[str, str]:
+        """
+        Get basic auth credentials, generating if not set.
+        
+        Returns:
+            Tuple of (username, password)
+        """
+        username = self.basic_auth_user or "signalwire"
+        password = self.basic_auth_password or secrets.token_urlsafe(32)
+        
+        return username, password
+    
+    def get_security_headers(self, is_https: bool = False) -> Dict[str, str]:
+        """
+        Get security headers to add to responses.
+        
+        Args:
+            is_https: Whether the connection is over HTTPS
+            
+        Returns:
+            Dictionary of security headers
+        """
+        headers = {
+            'X-Content-Type-Options': 'nosniff',
+            'X-Frame-Options': 'DENY',
+            'X-XSS-Protection': '1; mode=block',
+            'Referrer-Policy': 'strict-origin-when-cross-origin',
+        }
+        
+        # Add HSTS header if HTTPS and enabled
+        if is_https and self.use_hsts:
+            headers['Strict-Transport-Security'] = f'max-age={self.hsts_max_age}; includeSubDomains'
+            
+        return headers
+    
+    def should_allow_host(self, host: str) -> bool:
+        """
+        Check if a host is allowed.
+        
+        Args:
+            host: The host to check
+            
+        Returns:
+            True if the host is allowed
+        """
+        if '*' in self.allowed_hosts:
+            return True
+            
+        return host in self.allowed_hosts
+    
+    def get_cors_config(self) -> Dict[str, Any]:
+        """
+        Get CORS configuration for FastAPI.
+        
+        Returns:
+            Dictionary of CORS settings
+        """
+        return {
+            'allow_origins': self.cors_origins,
+            'allow_credentials': True,
+            'allow_methods': ['*'],
+            'allow_headers': ['*'],
+        }
+    
+    def get_url_scheme(self) -> str:
+        """Get the URL scheme based on SSL configuration"""
+        return 'https' if self.ssl_enabled else 'http'
+    
+    def log_config(self, service_name: str):
+        """Log the current security configuration"""
+        logger.info(
+            "security_config_loaded",
+            service=service_name,
+            ssl_enabled=self.ssl_enabled,
+            domain=self.domain,
+            allowed_hosts=self.allowed_hosts,
+            cors_origins=self.cors_origins,
+            max_request_size=self.max_request_size,
+            rate_limit=self.rate_limit,
+            use_hsts=self.use_hsts,
+            has_basic_auth=bool(self.basic_auth_user and self.basic_auth_password)
+        )
+
+
+# Global instance for easy access (backward compatibility)
+# Services can create their own instances with specific config files
+security_config = SecurityConfig()

signalwire_agents/core/skill_base.py

@@ -53,6 +53,26 @@ class SkillBase(ABC):
         """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]:
@@ -114,4 +134,67 @@ class SkillBase(ABC):
             
         # 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}" 
+        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

@@ -8,7 +8,7 @@ See LICENSE file in the project root for full license information.
 """
 
 from typing import Dict, List, Type, Any, Optional
-import logging
+from signalwire_agents.core.logging_config import get_logger
 from signalwire_agents.core.skill_base import SkillBase
 
 class SkillManager:
@@ -17,7 +17,7 @@ class SkillManager:
     def __init__(self, agent):
         self.agent = agent
         self.loaded_skills: Dict[str, SkillBase] = {}
-        self.logger = logging.getLogger("skill_manager")
+        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]:
         """
@@ -45,6 +45,53 @@ class SkillManager:
                 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)
@@ -111,6 +158,16 @@ class SkillManager:
             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)
@@ -134,13 +191,6 @@ class SkillManager:
         if skill_identifier in self.loaded_skills:
             instance_key = skill_identifier
             skill_instance = self.loaded_skills[skill_identifier]
-        else:
-            # Try to find by skill name (for backwards compatibility)
-            for key, instance in self.loaded_skills.items():
-                if instance.SKILL_NAME == skill_identifier:
-                    instance_key = key
-                    skill_instance = instance
-                    break
         
         if skill_instance is None:
             self.logger.warning(f"Skill '{skill_identifier}' is not loaded")
@@ -173,11 +223,6 @@ class SkillManager:
         if skill_identifier in self.loaded_skills:
             return True
         
-        # Try to find by skill name (for backwards compatibility)
-        for instance in self.loaded_skills.values():
-            if instance.SKILL_NAME == skill_identifier:
-                return True
-        
         return False
     
     def get_skill(self, skill_identifier: str) -> Optional[SkillBase]:
@@ -194,9 +239,6 @@ class SkillManager:
         if skill_identifier in self.loaded_skills:
             return self.loaded_skills[skill_identifier]
         
-        # Try to find by skill name (for backwards compatibility)
-        for instance in self.loaded_skills.values():
-            if instance.SKILL_NAME == skill_identifier:
-                return instance
-        
-        return None 
+        return None
+    
+ 

signalwire_agents/core/swaig_function.py

@@ -30,7 +30,10 @@ class SWAIGFunction:
         parameters: Dict[str, Dict] = None,
         secure: bool = False,
         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
     ):
         """
@@ -42,8 +45,11 @@ 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
@@ -51,8 +57,11 @@ class SWAIGFunction:
         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
@@ -73,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
@@ -179,5 +194,3 @@ class SWAIGFunction:
             
         return function_def
 
-# Add an alias for backward compatibility
-SwaigFunction = SWAIGFunction