signalwire-agents 0.1.10__py3-none-any.whl → 0.1.12__py3-none-any.whl

signalwire_agents/core/logging_config.py

@@ -0,0 +1,232 @@
+"""
+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.
+"""
+
+"""
+Central logging configuration for SignalWire Agents SDK
+
+This module provides a single point of control for all logging across the SDK
+and applications built with it. All components should use get_logger() instead
+of direct logging module usage or print() statements.
+
+The StructuredLoggerWrapper provides backward compatibility with existing 
+structured logging calls (e.g., log.info("message", key=value)) while using
+standard Python logging underneath. This allows the entire codebase to work
+without changes while providing centralized logging control.
+"""
+
+import logging
+import os
+import sys
+from typing import Optional, Any, Dict
+
+# Global flag to ensure configuration only happens once
+_logging_configured = False
+
+
+class StructuredLoggerWrapper:
+    """
+    A wrapper that provides structured logging interface while using standard Python logging
+    
+    This allows existing structured logging calls to work without changes while
+    giving us centralized control over logging behavior.
+    """
+    
+    def __init__(self, logger: logging.Logger):
+        self._logger = logger
+    
+    def _format_structured_message(self, message: str, **kwargs) -> str:
+        """Format a message with structured keyword arguments"""
+        if not kwargs:
+            return message
+            
+        # Convert kwargs to readable string format
+        parts = []
+        for key, value in kwargs.items():
+            # Handle different value types appropriately
+            if isinstance(value, str):
+                parts.append(f"{key}={value}")
+            elif isinstance(value, (list, dict)):
+                parts.append(f"{key}={str(value)}")
+            else:
+                parts.append(f"{key}={value}")
+        
+        if parts:
+            return f"{message} ({', '.join(parts)})"
+        else:
+            return message
+    
+    def debug(self, message: str, **kwargs) -> None:
+        """Log debug message with optional structured data"""
+        formatted = self._format_structured_message(message, **kwargs)
+        self._logger.debug(formatted)
+    
+    def info(self, message: str, **kwargs) -> None:
+        """Log info message with optional structured data"""
+        formatted = self._format_structured_message(message, **kwargs)
+        self._logger.info(formatted)
+    
+    def warning(self, message: str, **kwargs) -> None:
+        """Log warning message with optional structured data"""
+        formatted = self._format_structured_message(message, **kwargs)
+        self._logger.warning(formatted)
+    
+    def error(self, message: str, **kwargs) -> None:
+        """Log error message with optional structured data"""
+        formatted = self._format_structured_message(message, **kwargs)
+        self._logger.error(formatted)
+    
+    def critical(self, message: str, **kwargs) -> None:
+        """Log critical message with optional structured data"""
+        formatted = self._format_structured_message(message, **kwargs)
+        self._logger.critical(formatted)
+    
+    # Also support the 'warn' alias
+    warn = warning
+    
+    # Support direct access to underlying logger attributes if needed
+    def __getattr__(self, name: str) -> Any:
+        """Delegate any unknown attributes to the underlying logger"""
+        return getattr(self._logger, name)
+
+
+def get_execution_mode() -> str:
+    """
+    Determine the execution mode based on environment variables
+    
+    Returns:
+        'cgi' if running in CGI mode
+        'lambda' if running in AWS Lambda 
+        'server' for normal server mode
+    """
+    if os.getenv('GATEWAY_INTERFACE'):
+        return 'cgi'
+    if os.getenv('AWS_LAMBDA_FUNCTION_NAME') or os.getenv('LAMBDA_TASK_ROOT'):
+        return 'lambda'
+    return 'server'
+
+
+def configure_logging():
+    """
+    Configure logging system once, globally, based on environment variables
+    
+    Environment Variables:
+        SIGNALWIRE_LOG_MODE: off, stderr, default, auto
+        SIGNALWIRE_LOG_LEVEL: debug, info, warning, error, critical
+    """
+    global _logging_configured
+    
+    if _logging_configured:
+        return
+    
+    # Get configuration from environment
+    log_mode = os.getenv('SIGNALWIRE_LOG_MODE', '').lower()
+    log_level = os.getenv('SIGNALWIRE_LOG_LEVEL', 'info').lower()
+    
+    # Determine log mode if auto or not specified
+    if not log_mode or log_mode == 'auto':
+        execution_mode = get_execution_mode()
+        if execution_mode == 'cgi':
+            log_mode = 'off'
+        else:
+            log_mode = 'default'
+    
+    # Configure based on mode
+    if log_mode == 'off':
+        _configure_off_mode()
+    elif log_mode == 'stderr':
+        _configure_stderr_mode(log_level)
+    else:  # default mode
+        _configure_default_mode(log_level)
+    
+    _logging_configured = True
+
+
+def _configure_off_mode():
+    """Suppress all logging output"""
+    # Redirect to devnull
+    null_file = open(os.devnull, 'w')
+    
+    # Clear existing handlers and configure to devnull
+    logging.getLogger().handlers.clear()
+    logging.basicConfig(
+        stream=null_file,
+        level=logging.CRITICAL,
+        format=''
+    )
+    
+    # Set all known loggers to CRITICAL to prevent any output
+    logger_names = [
+        '', 'signalwire_agents', 'skill_registry', 'swml_service', 
+        'agent_base', 'AgentServer', 'uvicorn', 'fastapi'
+    ]
+    for name in logger_names:
+        logging.getLogger(name).setLevel(logging.CRITICAL)
+    
+    # Configure structlog if available
+    try:
+        import structlog
+        structlog.configure(
+            processors=[],
+            wrapper_class=structlog.make_filtering_bound_logger(logging.CRITICAL),
+            logger_factory=structlog.PrintLoggerFactory(file=null_file),
+            cache_logger_on_first_use=True,
+        )
+    except ImportError:
+        pass
+
+
+def _configure_stderr_mode(log_level: str):
+    """Configure logging to stderr"""
+    # Clear existing handlers
+    logging.getLogger().handlers.clear()
+    
+    # Convert log level
+    numeric_level = getattr(logging, log_level.upper(), logging.INFO)
+    
+    # Configure to stderr
+    logging.basicConfig(
+        stream=sys.stderr,
+        level=numeric_level,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+
+
+def _configure_default_mode(log_level: str):
+    """Configure standard logging behavior"""
+    # Convert log level
+    numeric_level = getattr(logging, log_level.upper(), logging.INFO)
+    
+    # Configure standard logging
+    logging.basicConfig(
+        level=numeric_level,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+
+
+def get_logger(name: str) -> StructuredLoggerWrapper:
+    """
+    Get a logger instance for the specified name with structured logging support
+    
+    This is the single entry point for all logging in the SDK.
+    All modules should use this instead of direct logging module usage.
+    
+    Args:
+        name: Logger name, typically __name__
+        
+    Returns:
+        StructuredLoggerWrapper that supports both regular and structured logging
+    """
+    # Ensure logging is configured
+    configure_logging()
+    
+    # Get the standard Python logger
+    python_logger = logging.getLogger(name)
+    
+    # Wrap it with our structured logging interface
+    return StructuredLoggerWrapper(python_logger) 

signalwire_agents/core/skill_base.py

@@ -24,6 +24,9 @@ class SkillBase(ABC):
     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")
@@ -50,42 +53,7 @@ class SkillBase(ABC):
         """Register SWAIG tools with the agent"""
         pass
         
-    def define_tool_with_swaig_fields(
-        self, 
-        name: str, 
-        description: str, 
-        parameters: Dict[str, Any], 
-        handler,
-        **additional_kwargs
-    ):
-        """
-        Helper method to define a tool with swaig_fields merged in
-        
-        Args:
-            name: Function name
-            description: Function description
-            parameters: Function parameters schema
-            handler: Function handler
-            **additional_kwargs: Additional keyword arguments for define_tool
-            
-        This method automatically merges the swaig_fields from skill params
-        into the tool definition, allowing the skill loader to customize
-        SWAIG function properties.
-        """
-        # Start with the additional kwargs passed to this method
-        tool_kwargs = additional_kwargs.copy()
-        
-        # Merge in the swaig_fields from params (swaig_fields take precedence)
-        tool_kwargs.update(self.swaig_fields)
-        
-        # Call the agent's define_tool with all parameters
-        self.agent.define_tool(
-            name=name,
-            description=description,
-            parameters=parameters,
-            handler=handler,
-            **tool_kwargs
-        )
+
         
     def get_hints(self) -> List[str]:
         """Return speech recognition hints for this skill"""
@@ -124,4 +92,26 @@ class SkillBase(ABC):
         if missing:
             self.logger.error(f"Missing required packages: {missing}")
             return False
-        return True 
+        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}" 

signalwire_agents/core/skill_manager.py

@@ -31,10 +31,6 @@ class SkillManager:
         Returns:
             tuple: (success, error_message) - error_message is empty string if successful
         """
-        if skill_name in self.loaded_skills:
-            self.logger.warning(f"Skill '{skill_name}' is already loaded")
-            return True, ""
-            
         # Get skill class from registry if not provided
         if skill_class is None:
             try:
@@ -50,8 +46,21 @@ class SkillManager:
                 return False, error_msg
         
         try:
-            # Create skill instance with parameters
+            # 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
@@ -97,9 +106,9 @@ class SkillManager:
             for section in prompt_sections:
                 self.agent.prompt_add_section(**section)
             
-            # Store loaded skill
-            self.loaded_skills[skill_name] = skill_instance
-            self.logger.info(f"Successfully loaded skill '{skill_name}'")
+            # 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 Exception as e:
@@ -107,30 +116,87 @@ class SkillManager:
             self.logger.error(error_msg)
             return False, error_msg
     
-    def unload_skill(self, skill_name: str) -> bool:
-        """Unload a skill and cleanup"""
-        if skill_name not in self.loaded_skills:
-            self.logger.warning(f"Skill '{skill_name}' is not loaded")
+    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]
+        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")
             return False
             
         try:
-            skill_instance = self.loaded_skills[skill_name]
             skill_instance.cleanup()
-            del self.loaded_skills[skill_name]
-            self.logger.info(f"Successfully unloaded skill '{skill_name}'")
+            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_name}': {e}")
+            self.logger.error(f"Error unloading skill '{skill_identifier}': {e}")
             return False
     
     def list_loaded_skills(self) -> List[str]:
-        """List names of currently loaded skills"""
+        """List instance keys of currently loaded skills"""
         return list(self.loaded_skills.keys())
     
-    def has_skill(self, skill_name: str) -> bool:
-        """Check if skill is currently loaded"""
-        return skill_name in self.loaded_skills
+    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
+        
+        # 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_name: str) -> Optional[SkillBase]:
-        """Get a loaded skill instance by name"""
-        return self.loaded_skills.get(skill_name) 
+    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]
+        
+        # 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 

signalwire_agents/core/swaig_function.py

@@ -27,7 +27,9 @@ 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,
+        webhook_url: Optional[str] = None,
+        **extra_swaig_fields
     ):
         """
         Initialize a new SWAIG function
@@ -39,6 +41,8 @@ class SWAIGFunction:
             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
+            webhook_url: Optional external webhook URL to use instead of local handling
+            **extra_swaig_fields: Additional SWAIG fields to include in function definition
         """
         self.name = name
         self.handler = handler
@@ -46,6 +50,11 @@ class SWAIGFunction:
         self.parameters = parameters or {}
         self.secure = secure
         self.fillers = fillers
+        self.webhook_url = webhook_url
+        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:
         """
@@ -165,6 +174,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
 

signalwire_agents/core/swml_handler.py

@@ -93,17 +93,33 @@ class AIVerbHandler(SWMLVerbHandler):
         """
         errors = []
         
-        # Check required fields
+        # Check that prompt is present
         if "prompt" not in config:
             errors.append("Missing required field 'prompt'")
+            return False, errors
         
-        # Validate prompt structure if present
-        if "prompt" in config:
-            prompt = config["prompt"]
-            if not isinstance(prompt, dict):
-                errors.append("'prompt' must be an object")
-            elif "text" not in prompt and "pom" not in prompt:
-                errors.append("'prompt' must contain either 'text' or 'pom'")
+        prompt = config["prompt"]
+        if not isinstance(prompt, dict):
+            errors.append("'prompt' must be an object")
+            return False, errors
+        
+        # Check that prompt contains one of: text, pom, or contexts
+        has_text = "text" in prompt
+        has_pom = "pom" in prompt
+        has_contexts = "contexts" in prompt
+        
+        options_count = sum([has_text, has_pom, has_contexts])
+        
+        if options_count == 0:
+            errors.append("'prompt' must contain one of: 'text', 'pom', or 'contexts'")
+        elif options_count > 1:
+            errors.append("'prompt' can only contain one of: 'text', 'pom', or 'contexts'")
+        
+        # Validate contexts structure if present
+        if has_contexts:
+            contexts = prompt["contexts"]
+            if not isinstance(contexts, dict):
+                errors.append("'prompt.contexts' must be an object")
         
         # Validate SWAIG structure if present
         if "SWAIG" in config:
@@ -116,6 +132,7 @@ class AIVerbHandler(SWMLVerbHandler):
     def build_config(self, 
                     prompt_text: Optional[str] = None,
                     prompt_pom: Optional[List[Dict[str, Any]]] = None,
+                    contexts: Optional[Dict[str, Any]] = None,
                     post_prompt: Optional[str] = None,
                     post_prompt_url: Optional[str] = None,
                     swaig: Optional[Dict[str, Any]] = None,
@@ -124,8 +141,9 @@ class AIVerbHandler(SWMLVerbHandler):
         Build a configuration for the AI verb
         
         Args:
-            prompt_text: Text prompt for the AI (mutually exclusive with prompt_pom)
-            prompt_pom: POM structure for the AI prompt (mutually exclusive with prompt_text)
+            prompt_text: Text prompt for the AI (mutually exclusive with prompt_pom and contexts)
+            prompt_pom: POM structure for the AI prompt (mutually exclusive with prompt_text and contexts)
+            contexts: Contexts and steps configuration (mutually exclusive with prompt_text and prompt_pom)
             post_prompt: Optional post-prompt text
             post_prompt_url: Optional URL for post-prompt processing
             swaig: Optional SWAIG configuration
@@ -136,13 +154,19 @@ class AIVerbHandler(SWMLVerbHandler):
         """
         config = {}
         
-        # Add prompt (either text or POM)
+        # Add prompt (either text, POM, or contexts - mutually exclusive)
+        prompt_options_count = sum(x is not None for x in [prompt_text, prompt_pom, contexts])
+        if prompt_options_count == 0:
+            raise ValueError("One of prompt_text, prompt_pom, or contexts must be provided")
+        elif prompt_options_count > 1:
+            raise ValueError("prompt_text, prompt_pom, and contexts are mutually exclusive")
+        
         if prompt_text is not None:
             config["prompt"] = {"text": prompt_text}
         elif prompt_pom is not None:
             config["prompt"] = {"pom": prompt_pom}
-        else:
-            raise ValueError("Either prompt_text or prompt_pom must be provided")
+        elif contexts is not None:
+            config["prompt"] = {"contexts": contexts}
         
         # Add post-prompt if provided
         if post_prompt is not None: