signalwire-agents 0.1.28__py3-none-any.whl → 0.1.30__py3-none-any.whl

signalwire_agents/core/config_loader.py

@@ -0,0 +1,259 @@
+"""
+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 re
+import json
+from typing import Any, Dict, List, Optional, Union
+from signalwire_agents.core.logging_config import get_logger
+
+logger = get_logger("config_loader")
+
+
+class ConfigLoader:
+    """
+    Configuration loader with environment variable substitution.
+    
+    Supports ${VAR|default} syntax for referencing environment variables
+    within JSON configuration files. This provides a clean pattern for
+    configuration across all SignalWire services.
+    """
+    
+    def __init__(self, config_paths: Optional[List[str]] = None):
+        """
+        Initialize config loader.
+        
+        Args:
+            config_paths: Optional list of config file paths to check.
+                         If not provided, uses default search paths.
+        """
+        self.config_paths = config_paths or self._get_default_paths()
+        self._config = None
+        self._config_file = None
+        self._load_config()
+    
+    def _get_default_paths(self) -> List[str]:
+        """Get default configuration file search paths."""
+        return [
+            "config.json",
+            "agent_config.json",
+            "swml_config.json",
+            ".swml/config.json",
+            os.path.expanduser("~/.swml/config.json"),
+            "/etc/swml/config.json"
+        ]
+    
+    def _load_config(self) -> None:
+        """Load configuration from the first available config file."""
+        for path in self.config_paths:
+            if os.path.exists(path):
+                try:
+                    with open(path, 'r') as f:
+                        self._config = json.load(f)
+                        self._config_file = path
+                        logger.info("config_loaded", path=path)
+                        break
+                except Exception as e:
+                    logger.error("config_load_error", path=path, error=str(e))
+    
+    def has_config(self) -> bool:
+        """Check if a configuration was loaded."""
+        return self._config is not None
+    
+    def get_config_file(self) -> Optional[str]:
+        """Get the path of the loaded config file."""
+        return self._config_file
+    
+    def get_config(self) -> Dict[str, Any]:
+        """Get the raw configuration (before substitution)."""
+        return self._config or {}
+    
+    def substitute_vars(self, value: Any) -> Any:
+        """
+        Recursively substitute environment variables in configuration values.
+        
+        Supports ${VAR|default} syntax where:
+        - VAR is the environment variable name
+        - default is the fallback value if VAR is not set
+        
+        Args:
+            value: The value to process (can be string, dict, list, etc.)
+            
+        Returns:
+            The value with all environment variables substituted
+        """
+        if isinstance(value, str):
+            # Pattern to match ${VAR} or ${VAR|default}
+            pattern = r'\$\{([^}|]+)(?:\|([^}]*))?\}'
+            
+            def replacer(match):
+                var_name = match.group(1)
+                default = match.group(2) if match.group(2) is not None else ''
+                return os.environ.get(var_name, default)
+            
+            # Substitute all variables
+            result = re.sub(pattern, replacer, value)
+            
+            # Try to parse as JSON to get proper types
+            if result.lower() in ('true', 'false'):
+                return result.lower() == 'true'
+            elif result.isdigit():
+                return int(result)
+            elif result.replace('.', '', 1).isdigit():
+                return float(result)
+            else:
+                return result
+                
+        elif isinstance(value, dict):
+            # Recursively process dictionary
+            return {k: self.substitute_vars(v) for k, v in value.items()}
+            
+        elif isinstance(value, list):
+            # Recursively process list
+            return [self.substitute_vars(item) for item in value]
+            
+        else:
+            # Return other types as-is
+            return value
+    
+    def get(self, key_path: str, default: Any = None) -> Any:
+        """
+        Get a configuration value by dot-notation path.
+        
+        Args:
+            key_path: Dot-separated path (e.g., "security.ssl_enabled")
+            default: Default value if path not found
+            
+        Returns:
+            The configuration value with variables substituted
+        """
+        if not self._config:
+            return default
+            
+        # Navigate through the config using the dot path
+        keys = key_path.split('.')
+        value = self._config
+        
+        for key in keys:
+            if isinstance(value, dict) and key in value:
+                value = value[key]
+            else:
+                return default
+        
+        # Substitute variables before returning
+        return self.substitute_vars(value)
+    
+    def get_section(self, section: str) -> Dict[str, Any]:
+        """
+        Get an entire configuration section.
+        
+        Args:
+            section: The section name (e.g., "security", "server")
+            
+        Returns:
+            The configuration section with all variables substituted
+        """
+        if not self._config or section not in self._config:
+            return {}
+            
+        return self.substitute_vars(self._config[section])
+    
+    def merge_with_env(self, env_prefix: str = "SWML_") -> Dict[str, Any]:
+        """
+        Merge configuration with environment variables.
+        
+        Config file takes precedence over environment variables,
+        but config can reference env vars via substitution.
+        
+        Args:
+            env_prefix: Prefix for environment variables to consider
+            
+        Returns:
+            Merged configuration dictionary
+        """
+        # Start with substituted config
+        result = self.substitute_vars(self._config) if self._config else {}
+        
+        # Only add env vars that aren't already in config
+        # This preserves config file precedence
+        for key, value in os.environ.items():
+            if key.startswith(env_prefix):
+                # Convert SWML_SSL_ENABLED to ssl_enabled
+                config_key = key[len(env_prefix):].lower()
+                
+                # Only set if not already in config
+                if not self._has_nested_key(result, config_key):
+                    self._set_nested_key(result, config_key, value)
+        
+        return result
+    
+    def _has_nested_key(self, data: Dict, key_path: str) -> bool:
+        """Check if a nested key exists in dictionary."""
+        keys = key_path.split('_')
+        current = data
+        
+        for key in keys:
+            if isinstance(current, dict) and key in current:
+                current = current[key]
+            else:
+                return False
+        return True
+    
+    def _set_nested_key(self, data: Dict, key_path: str, value: Any) -> None:
+        """Set a value in dictionary using underscore-separated path."""
+        keys = key_path.split('_')
+        current = data
+        
+        for key in keys[:-1]:
+            if key not in current:
+                current[key] = {}
+            current = current[key]
+            
+        current[keys[-1]] = value
+    
+    @staticmethod
+    def find_config_file(service_name: Optional[str] = None, 
+                        additional_paths: Optional[List[str]] = None) -> Optional[str]:
+        """
+        Static method to find a config file for a service.
+        
+        Args:
+            service_name: Optional service name for service-specific config
+            additional_paths: Additional paths to check
+            
+        Returns:
+            Path to the first config file found, or None
+        """
+        paths = []
+        
+        # Service-specific config
+        if service_name:
+            paths.extend([
+                f"{service_name}_config.json",
+                f".swml/{service_name}_config.json"
+            ])
+        
+        # Additional paths
+        if additional_paths:
+            paths.extend(additional_paths)
+        
+        # Default paths
+        paths.extend([
+            "config.json",
+            "agent_config.json",
+            ".swml/config.json",
+            os.path.expanduser("~/.swml/config.json"),
+            "/etc/swml/config.json"
+        ])
+        
+        for path in paths:
+            if os.path.exists(path):
+                return path
+                
+        return None

signalwire_agents/core/contexts.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 Contexts and Steps System for SignalWire Agents
 
@@ -259,6 +268,10 @@ class Context:
         # Context prompt (separate from system_prompt)
         self._prompt_text: Optional[str] = None
         self._prompt_sections: List[Dict[str, Any]] = []
+        
+        # Context fillers
+        self._enter_fillers: Optional[Dict[str, List[str]]] = None
+        self._exit_fillers: Optional[Dict[str, List[str]]] = None
     
     def add_step(self, name: str) -> Step:
         """
@@ -450,6 +463,70 @@ class Context:
         self._prompt_sections.append({"title": title, "bullets": bullets})
         return self
     
+    def set_enter_fillers(self, enter_fillers: Dict[str, List[str]]) -> 'Context':
+        """
+        Set fillers that the AI says when entering this context
+        
+        Args:
+            enter_fillers: Dictionary mapping language codes (or "default") to lists of filler phrases
+                          Example: {"en-US": ["Welcome...", "Hello..."], "default": ["Entering..."]}
+            
+        Returns:
+            Self for method chaining
+        """
+        if enter_fillers and isinstance(enter_fillers, dict):
+            self._enter_fillers = enter_fillers
+        return self
+    
+    def set_exit_fillers(self, exit_fillers: Dict[str, List[str]]) -> 'Context':
+        """
+        Set fillers that the AI says when exiting this context
+        
+        Args:
+            exit_fillers: Dictionary mapping language codes (or "default") to lists of filler phrases
+                         Example: {"en-US": ["Goodbye...", "Thank you..."], "default": ["Exiting..."]}
+            
+        Returns:
+            Self for method chaining
+        """
+        if exit_fillers and isinstance(exit_fillers, dict):
+            self._exit_fillers = exit_fillers
+        return self
+    
+    def add_enter_filler(self, language_code: str, fillers: List[str]) -> 'Context':
+        """
+        Add enter fillers for a specific language
+        
+        Args:
+            language_code: Language code (e.g., "en-US", "es") or "default" for catch-all
+            fillers: List of filler phrases for entering this context
+            
+        Returns:
+            Self for method chaining
+        """
+        if language_code and fillers and isinstance(fillers, list):
+            if self._enter_fillers is None:
+                self._enter_fillers = {}
+            self._enter_fillers[language_code] = fillers
+        return self
+    
+    def add_exit_filler(self, language_code: str, fillers: List[str]) -> 'Context':
+        """
+        Add exit fillers for a specific language
+        
+        Args:
+            language_code: Language code (e.g., "en-US", "es") or "default" for catch-all
+            fillers: List of filler phrases for exiting this context
+            
+        Returns:
+            Self for method chaining
+        """
+        if language_code and fillers and isinstance(fillers, list):
+            if self._exit_fillers is None:
+                self._exit_fillers = {}
+            self._exit_fillers[language_code] = fillers
+        return self
+    
     def _render_prompt(self) -> Optional[str]:
         """Render the context's prompt text"""
         if self._prompt_text is not None:
@@ -533,6 +610,13 @@ class Context:
         elif self._prompt_text is not None:
             # Use string format
             context_dict["prompt"] = self._prompt_text
+        
+        # Add enter and exit fillers if defined
+        if self._enter_fillers is not None:
+            context_dict["enter_fillers"] = self._enter_fillers
+        
+        if self._exit_fillers is not None:
+            context_dict["exit_fillers"] = self._exit_fillers
             
         return context_dict
 

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()