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

signalwire_agents/core/function_result.py

@@ -188,7 +188,7 @@ class SwaigFunctionResult:
         self.action.append(swml_action)
         return self
 
-    def swml_transfer(self, dest: str, ai_response: str) -> 'SwaigFunctionResult':
+    def swml_transfer(self, dest: str, ai_response: str, final: bool = True) -> 'SwaigFunctionResult':
         """
         Add a SWML transfer action with AI response setup for when transfer completes.
         
@@ -202,22 +202,28 @@ class SwaigFunctionResult:
         Args:
             dest: Destination URL for the transfer (SWML endpoint, SIP address, etc.)
             ai_response: Message the AI should say when transfer completes and control returns
+            final: Whether this is a permanent transfer (True) or temporary (False).
+                  Defaults to True for permanent transfers (same as connect method).
                         
         Returns:
             Self for method chaining
             
         Example:
-            # Transfer with post-processing (speak first, then transfer)
+            # Permanent transfer (default)
             result = (
                 SwaigFunctionResult("I'm transferring you to support", post_process=True)
                 .swml_transfer(
                     "https://support.example.com/swml",
-                    "The support call is complete. How else can I help?"
+                    "Goodbye!"  # Won't be used since final=True by default
                 )
             )
             
-            # Or enable post-processing with method chaining
-            result.swml_transfer(dest, ai_response).set_post_process(True)
+            # Temporary transfer with return
+            result.swml_transfer(
+                dest, 
+                "The support call is complete. How else can I help?", 
+                final=False
+            )
         """
         # Create the SWML action structure directly
         swml_action = {
@@ -229,7 +235,8 @@ class SwaigFunctionResult:
                         {"transfer": {"dest": dest}}
                     ]
                 }
-            }
+            },
+            "transfer": str(final).lower()  # Convert boolean to "true"/"false" string
         }
         
         # Add to actions list directly
@@ -251,9 +258,89 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"set_global_data": data}
-        return self.add_action("set_global_data", action)
+        return self.add_action("set_global_data", data)
 
+    def swml_user_event(self, event_data: Dict[str, Any]) -> 'SwaigFunctionResult':
+        """
+        Send a user event through SWML to update the client UI.
+        
+        This is a convenience method for sending user events to connected clients,
+        commonly used for real-time UI updates in interactive applications.
+        
+        Args:
+            event_data: Dictionary containing the event type and any associated data
+                       Example: {"type": "cards_dealt", "player_hand": [...], "score": 21}
+            
+        Returns:
+            Self for method chaining
+            
+        Example:
+            result = (
+                SwaigFunctionResult("You have blackjack!")
+                .swml_user_event({
+                    "type": "cards_dealt",
+                    "player_hand": player_cards,
+                    "dealer_hand": dealer_cards,
+                    "player_score": 21
+                })
+            )
+        """
+        swml_action = {
+            "sections": {
+                "main": [{
+                    "user_event": {
+                        "event": event_data
+                    }
+                }]
+            },
+            "version": "1.0.0"
+        }
+        
+        return self.add_action("SWML", swml_action)
+    
+    def swml_change_step(self, step_name: str) -> 'SwaigFunctionResult':
+        """
+        Change the conversation step in the AI agent's workflow.
+        
+        This is a convenience method for transitioning between conversation steps,
+        allowing dynamic workflow control based on user interactions or game state.
+        
+        Args:
+            step_name: Name of the step to transition to (e.g., "betting", "playing", "hand_complete")
+            
+        Returns:
+            Self for method chaining
+            
+        Example:
+            result = (
+                SwaigFunctionResult("Starting a new hand")
+                .swml_change_step("betting")
+                .swml_user_event({"type": "game_reset", "chips": 1000})
+            )
+        """
+        return self.add_action("change_step", step_name)
+    
+    def swml_change_context(self, context_name: str) -> 'SwaigFunctionResult':
+        """
+        Change the conversation context in the AI agent's workflow.
+        
+        This is a convenience method for switching between different conversation contexts,
+        useful for agents that handle multiple distinct workflows or service modes.
+        
+        Args:
+            context_name: Name of the context to transition to (e.g., "support", "sales", "technical")
+            
+        Returns:
+            Self for method chaining
+            
+        Example:
+            result = (
+                SwaigFunctionResult("Transferring you to technical support")
+                .swml_change_context("technical_support")
+            )
+        """
+        return self.add_action("change_context", context_name)
+    
     def execute_swml(self, swml_content, transfer: bool = False) -> 'SwaigFunctionResult':
         """
         Execute SWML content with optional transfer behavior.
@@ -281,7 +368,7 @@ class SwaigFunctionResult:
         else:
             raise TypeError("swml_content must be string, dict, or SWML object")
         
-        action = {"SWML": swml_data}
+        action = swml_data
         if transfer:
             action["transfer"] = "true"
         
@@ -294,8 +381,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"hangup": True}
-        return self.add_action("hangup", action)
+        return self.add_action("hangup", True)
 
     def hold(self, timeout: int = 300) -> 'SwaigFunctionResult':
         """
@@ -309,8 +395,7 @@ class SwaigFunctionResult:
         """
         # Clamp timeout to valid range
         timeout = max(0, min(timeout, 900))
-        action = {"hold": timeout}
-        return self.add_action("hold", action)
+        return self.add_action("hold", timeout)
 
     def wait_for_user(self, enabled: Optional[bool] = None, timeout: Optional[int] = None, answer_first: bool = False) -> 'SwaigFunctionResult':
         """
@@ -333,8 +418,7 @@ class SwaigFunctionResult:
         else:
             wait_value = True
             
-        action = {"wait_for_user": wait_value}
-        return self.add_action("wait_for_user", action)
+        return self.add_action("wait_for_user", wait_value)
 
     def stop(self) -> 'SwaigFunctionResult':
         """
@@ -343,8 +427,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"stop": True}
-        return self.add_action("stop", action)
+        return self.add_action("stop", True)
 
     def say(self, text: str) -> 'SwaigFunctionResult':
         """
@@ -356,8 +439,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"say": text}
-        return self.add_action("say", action)
+        return self.add_action("say", text)
 
     def play_background_file(self, filename: str, wait: bool = False) -> 'SwaigFunctionResult':
         """
@@ -395,8 +477,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"end_of_speech_timeout": milliseconds}
-        return self.add_action("end_of_speech_timeout", action)
+        return self.add_action("end_of_speech_timeout", milliseconds)
 
     def set_speech_event_timeout(self, milliseconds: int) -> 'SwaigFunctionResult':
         """
@@ -409,8 +490,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"speech_event_timeout": milliseconds}
-        return self.add_action("speech_event_timeout", action)
+        return self.add_action("speech_event_timeout", milliseconds)
 
     def remove_global_data(self, keys: Union[str, List[str]]) -> 'SwaigFunctionResult':
         """
@@ -422,8 +502,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"unset_global_data": keys}
-        return self.add_action("unset_global_data", action)
+        return self.add_action("unset_global_data", keys)
 
     def set_metadata(self, data: Dict[str, Any]) -> 'SwaigFunctionResult':
         """
@@ -435,8 +514,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"set_meta_data": data}
-        return self.add_action("set_meta_data", action)
+        return self.add_action("set_meta_data", data)
 
     def remove_metadata(self, keys: Union[str, List[str]]) -> 'SwaigFunctionResult':
         """
@@ -448,8 +526,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"unset_meta_data": keys}
-        return self.add_action("unset_meta_data", action)
+        return self.add_action("unset_meta_data", keys)
 
     def toggle_functions(self, function_toggles: List[Dict[str, Any]]) -> 'SwaigFunctionResult':
         """
@@ -461,8 +538,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"toggle_functions": function_toggles}
-        return self.add_action("toggle_functions", action)
+        return self.add_action("toggle_functions", function_toggles)
 
     def enable_functions_on_timeout(self, enabled: bool = True) -> 'SwaigFunctionResult':
         """
@@ -474,8 +550,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"functions_on_speaker_timeout": enabled}
-        return self.add_action("functions_on_speaker_timeout", action)
+        return self.add_action("functions_on_speaker_timeout", enabled)
 
     def enable_extensive_data(self, enabled: bool = True) -> 'SwaigFunctionResult':
         """
@@ -488,8 +563,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"extensive_data": enabled}
-        return self.add_action("extensive_data", action)
+        return self.add_action("extensive_data", enabled)
 
     def update_settings(self, settings: Dict[str, Any]) -> 'SwaigFunctionResult':
         """
@@ -510,8 +584,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"settings": settings}
-        return self.add_action("settings", action)
+        return self.add_action("settings", settings)
 
     def switch_context(self, system_prompt: Optional[str] = None, user_prompt: Optional[str] = None, 
                       consolidate: bool = False, full_reset: bool = False) -> 'SwaigFunctionResult':
@@ -529,7 +602,7 @@ class SwaigFunctionResult:
         """
         if system_prompt and not user_prompt and not consolidate and not full_reset:
             # Simple string context switch
-            action = {"context_switch": system_prompt}
+            return self.add_action("context_switch", system_prompt)
         else:
             # Advanced object context switch
             context_data = {}
@@ -541,9 +614,7 @@ class SwaigFunctionResult:
                 context_data["consolidate"] = True
             if full_reset:
                 context_data["full_reset"] = True
-            action = {"context_switch": context_data}
-            
-        return self.add_action("context_switch", action)
+            return self.add_action("context_switch", context_data)
 
     def simulate_user_input(self, text: str) -> 'SwaigFunctionResult':
         """
@@ -555,8 +626,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"user_input": text}
-        return self.add_action("user_input", action)
+        return self.add_action("user_input", text)
 
     def send_sms(self, to_number: str, from_number: str, body: Optional[str] = None, 
                 media: Optional[List[str]] = None, tags: Optional[List[str]] = None, 
@@ -622,7 +692,8 @@ class SwaigFunctionResult:
            currency: str = "usd", language: str = "en-US", voice: str = "woman",
            description: Optional[str] = None, valid_card_types: str = "visa mastercard amex",
            parameters: Optional[List[Dict[str, str]]] = None,
-           prompts: Optional[List[Dict[str, Any]]] = None) -> 'SwaigFunctionResult':
+           prompts: Optional[List[Dict[str, Any]]] = None,
+           ai_response: Optional[str] = "The payment status is ${pay_result}, do not mention anything else about collecting payment if successful.") -> 'SwaigFunctionResult':
         """
         Process payment using SWML pay action.
         
@@ -690,6 +761,7 @@ class SwaigFunctionResult:
             "version": "1.0.0",
             "sections": {
                 "main": [
+                    {"set": {"ai_response": ai_response}},
                     {"pay": pay_params}
                 ]
             }

signalwire_agents/core/logging_config.py

@@ -89,28 +89,85 @@ class StructuredLoggerWrapper:
     # Also support the 'warn' alias
     warn = warning
     
+    def bind(self, **kwargs) -> 'StructuredLoggerWrapper':
+        """
+        Create a new logger instance with bound context data
+        
+        This maintains compatibility with structlog's bind() method.
+        The bound data will be included in all subsequent log messages.
+        """
+        # Create a new wrapper that includes the bound context
+        return BoundStructuredLoggerWrapper(self._logger, kwargs)
+    
     # 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:
+class BoundStructuredLoggerWrapper(StructuredLoggerWrapper):
+    """
+    A structured logger wrapper that includes bound context data in all messages
+    """
+    
+    def __init__(self, logger: logging.Logger, bound_data: Dict[str, Any]):
+        super().__init__(logger)
+        self._bound_data = bound_data
+    
+    def _format_structured_message(self, message: str, **kwargs) -> str:
+        """Format a message with both bound data and additional keyword arguments"""
+        # Combine bound data with additional kwargs
+        all_kwargs = {**self._bound_data, **kwargs}
+        return super()._format_structured_message(message, **all_kwargs)
+    
+    def bind(self, **kwargs) -> 'BoundStructuredLoggerWrapper':
+        """Create a new logger with additional bound context"""
+        # Combine existing bound data with new data
+        new_bound_data = {**self._bound_data, **kwargs}
+        return BoundStructuredLoggerWrapper(self._logger, new_bound_data)
+
+
+def get_execution_mode():
     """
     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
+        str: 'server', 'cgi', 'lambda', 'google_cloud_function', 'azure_function', or 'unknown'
     """
+    # Check for CGI environment
     if os.getenv('GATEWAY_INTERFACE'):
         return 'cgi'
+    
+    # Check for AWS Lambda environment
     if os.getenv('AWS_LAMBDA_FUNCTION_NAME') or os.getenv('LAMBDA_TASK_ROOT'):
         return 'lambda'
+    
+    # Check for Google Cloud Functions environment
+    if (os.getenv('FUNCTION_TARGET') or 
+        os.getenv('K_SERVICE') or 
+        os.getenv('GOOGLE_CLOUD_PROJECT')):
+        return 'google_cloud_function'
+    
+    # Check for Azure Functions environment
+    if (os.getenv('AZURE_FUNCTIONS_ENVIRONMENT') or 
+        os.getenv('FUNCTIONS_WORKER_RUNTIME') or
+        os.getenv('AzureWebJobsStorage')):
+        return 'azure_function'
+    
+    # Default to server mode
     return 'server'
 
 
+def reset_logging_configuration():
+    """
+    Reset the logging configuration flag to allow reconfiguration
+    
+    This is useful when environment variables change after initial configuration.
+    """
+    global _logging_configured
+    _logging_configured = False
+
+
 def configure_logging():
     """
     Configure logging system once, globally, based on environment variables
@@ -182,31 +239,39 @@ def _configure_off_mode():
 
 
 def _configure_stderr_mode(log_level: str):
-    """Configure logging to stderr"""
+    """Configure logging to stderr with colored formatting"""
     # 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'
-    )
+    # Create handler with colored formatter
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(ColoredFormatter())
+    
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(numeric_level)
+    root_logger.addHandler(handler)
 
 
 def _configure_default_mode(log_level: str):
-    """Configure standard logging behavior"""
+    """Configure standard logging behavior with colored formatting"""
+    # Clear existing handlers
+    logging.getLogger().handlers.clear()
+    
     # 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'
-    )
+    # Create handler with colored formatter
+    handler = logging.StreamHandler()
+    handler.setFormatter(ColoredFormatter())
+    
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(numeric_level)
+    root_logger.addHandler(handler)
 
 
 def get_logger(name: str) -> StructuredLoggerWrapper:
@@ -229,4 +294,83 @@ def get_logger(name: str) -> StructuredLoggerWrapper:
     python_logger = logging.getLogger(name)
     
     # Wrap it with our structured logging interface
-    return StructuredLoggerWrapper(python_logger) 
+    return StructuredLoggerWrapper(python_logger)
+
+
+class ColoredFormatter(logging.Formatter):
+    """
+    A beautiful colored logging formatter that makes logs easy to read and visually appealing
+    """
+    
+    # ANSI color codes
+    COLORS = {
+        'DEBUG': '\033[36m',     # Cyan
+        'INFO': '\033[32m',      # Green  
+        'WARNING': '\033[33m',   # Yellow
+        'ERROR': '\033[31m',     # Red
+        'CRITICAL': '\033[35m',  # Magenta
+        'RESET': '\033[0m',      # Reset
+        'BOLD': '\033[1m',       # Bold
+        'DIM': '\033[2m',        # Dim
+        'WHITE': '\033[37m',     # White
+        'BLUE': '\033[34m',      # Blue
+        'BLACK': '\033[30m',     # Black (for brackets)
+    }
+    
+    def __init__(self):
+        super().__init__()
+    
+    def format(self, record):
+        # Check if we should use colors (not in raw mode, and stdout is a tty)
+        use_colors = (
+            hasattr(sys.stdout, 'isatty') and sys.stdout.isatty() and
+            os.getenv('SIGNALWIRE_LOG_MODE') != 'off' and
+            '--raw' not in sys.argv and '--dump-swml' not in sys.argv
+        )
+        
+        if use_colors:
+            # Get colors
+            level_color = self.COLORS.get(record.levelname, self.COLORS['WHITE'])
+            reset = self.COLORS['RESET']
+            dim = self.COLORS['DIM']
+            bold = self.COLORS['BOLD']
+            blue = self.COLORS['BLUE']
+            black = self.COLORS['BLACK']
+            
+            # Format timestamp in a compact, readable way
+            timestamp = self.formatTime(record, '%H:%M:%S')
+            
+            # Format level with appropriate color and consistent width
+            level_name = f"{level_color}{record.levelname:<8}{reset}"
+            
+            # Format logger name - keep it short and readable
+            logger_name = record.name
+            if len(logger_name) > 15:
+                # Truncate long logger names but keep the end (most specific part)
+                logger_name = "..." + logger_name[-12:]
+            
+            # Get function and line info if available
+            func_info = ""
+            if hasattr(record, 'funcName') and hasattr(record, 'lineno'):
+                func_name = getattr(record, 'funcName', '')
+                line_no = getattr(record, 'lineno', 0)
+                if func_name and func_name != '<module>':
+                    func_info = f" {dim}({func_name}:{line_no}){reset}"
+            
+            # Format the message
+            message = record.getMessage()
+            
+            # Create the final formatted message with a clean, readable layout
+            formatted = (
+                f"{black}[{reset}{dim}{timestamp}{reset}{black}]{reset} "
+                f"{level_name} "
+                f"{blue}{logger_name:<15}{reset}"
+                f"{func_info} "
+                f"{message}"
+            )
+            
+            return formatted
+        else:
+            # Non-colored format (fallback for files, pipes, etc.)
+            timestamp = self.formatTime(record, '%Y-%m-%d %H:%M:%S')
+            return f"{timestamp} {record.levelname:<8} {record.name} {record.getMessage()}" 

signalwire_agents/core/mixins/__init__.py

@@ -0,0 +1,28 @@
+"""
+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 .prompt_mixin import PromptMixin
+from .tool_mixin import ToolMixin
+from .web_mixin import WebMixin
+from .auth_mixin import AuthMixin
+from .skill_mixin import SkillMixin
+from .ai_config_mixin import AIConfigMixin
+from .serverless_mixin import ServerlessMixin
+from .state_mixin import StateMixin
+
+__all__ = [
+    'PromptMixin',
+    'ToolMixin',
+    'WebMixin',
+    'AuthMixin',
+    'SkillMixin',
+    'AIConfigMixin',
+    'ServerlessMixin',
+    'StateMixin'
+]