signalwire-agents 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

signalwire_agents/core/mixins/serverless_mixin.py

@@ -0,0 +1,368 @@
+"""
+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 json
+import sys
+from typing import Optional, Dict, Any
+
+from signalwire_agents.core.logging_config import get_execution_mode
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+
+class ServerlessMixin:
+    """
+    Mixin class containing all serverless/cloud platform methods for AgentBase
+    """
+    
+    def handle_serverless_request(self, event=None, context=None, mode=None):
+        """
+        Handle serverless environment requests (CGI, Lambda, Cloud Functions)
+        
+        Args:
+            event: Serverless event object (Lambda, Cloud Functions)
+            context: Serverless context object (Lambda, Cloud Functions)
+            mode: Override execution mode (from force_mode in run())
+            
+        Returns:
+            Response appropriate for the serverless platform
+        """
+        if mode is None:
+            mode = get_execution_mode()
+        
+        try:
+            if mode == 'cgi':
+                # Check authentication in CGI mode
+                if not self._check_cgi_auth():
+                    return self._send_cgi_auth_challenge()
+                
+                path_info = os.getenv('PATH_INFO', '').strip('/')
+                if not path_info:
+                    return self._render_swml()
+                else:
+                    # Parse CGI request for SWAIG function call
+                    args = {}
+                    call_id = None
+                    raw_data = None
+                    
+                    # Try to parse POST data from stdin for CGI
+                    import sys
+                    content_length = os.getenv('CONTENT_LENGTH')
+                    if content_length and content_length.isdigit():
+                        try:
+                            post_data = sys.stdin.read(int(content_length))
+                            if post_data:
+                                raw_data = json.loads(post_data)
+                                call_id = raw_data.get("call_id")
+                                
+                                # Extract arguments like the FastAPI handler does
+                                if "argument" in raw_data and isinstance(raw_data["argument"], dict):
+                                    if "parsed" in raw_data["argument"] and isinstance(raw_data["argument"]["parsed"], list) and raw_data["argument"]["parsed"]:
+                                        args = raw_data["argument"]["parsed"][0]
+                                    elif "raw" in raw_data["argument"]:
+                                        try:
+                                            args = json.loads(raw_data["argument"]["raw"])
+                                        except Exception:
+                                            pass
+                        except Exception:
+                            # If parsing fails, continue with empty args
+                            pass
+                    
+                    return self._execute_swaig_function(path_info, args, call_id, raw_data)
+            
+            elif mode == 'lambda':
+                # Check authentication in Lambda mode
+                if not self._check_lambda_auth(event):
+                    return self._send_lambda_auth_challenge()
+                
+                if event:
+                    path = event.get('pathParameters', {}).get('proxy', '') if event.get('pathParameters') else ''
+                    if not path:
+                        swml_response = self._render_swml()
+                        return {
+                            "statusCode": 200,
+                            "headers": {"Content-Type": "application/json"},
+                            "body": swml_response
+                        }
+                    else:
+                        # Parse Lambda event for SWAIG function call
+                        args = {}
+                        call_id = None
+                        raw_data = None
+                        
+                        # Parse request body if present
+                        body_content = event.get('body')
+                        if body_content:
+                            try:
+                                if isinstance(body_content, str):
+                                    raw_data = json.loads(body_content)
+                                else:
+                                    raw_data = body_content
+                                    
+                                call_id = raw_data.get("call_id")
+                                
+                                # Extract arguments like the FastAPI handler does
+                                if "argument" in raw_data and isinstance(raw_data["argument"], dict):
+                                    if "parsed" in raw_data["argument"] and isinstance(raw_data["argument"]["parsed"], list) and raw_data["argument"]["parsed"]:
+                                        args = raw_data["argument"]["parsed"][0]
+                                    elif "raw" in raw_data["argument"]:
+                                        try:
+                                            args = json.loads(raw_data["argument"]["raw"])
+                                        except Exception:
+                                            pass
+                            except Exception:
+                                # If parsing fails, continue with empty args
+                                pass
+                        
+                        result = self._execute_swaig_function(path, args, call_id, raw_data)
+                        return {
+                            "statusCode": 200,
+                            "headers": {"Content-Type": "application/json"},
+                            "body": json.dumps(result) if isinstance(result, dict) else str(result)
+                        }
+                else:
+                    # Handle case when event is None (direct Lambda call with no event)
+                    swml_response = self._render_swml()
+                    return {
+                        "statusCode": 200,
+                        "headers": {"Content-Type": "application/json"},
+                        "body": swml_response
+                    }
+            
+            elif mode == 'google_cloud_function':
+                # Check authentication in Google Cloud Functions mode
+                if not self._check_google_cloud_function_auth(event):
+                    return self._send_google_cloud_function_auth_challenge()
+                
+                return self._handle_google_cloud_function_request(event)
+            
+            elif mode == 'azure_function':
+                # Check authentication in Azure Functions mode
+                if not self._check_azure_function_auth(event):
+                    return self._send_azure_function_auth_challenge()
+                
+                return self._handle_azure_function_request(event)
+            
+                
+        except Exception as e:
+            import logging
+            logging.error(f"Error in serverless request handler: {e}")
+            if mode == 'lambda':
+                return {
+                    "statusCode": 500,
+                    "headers": {"Content-Type": "application/json"},
+                    "body": json.dumps({"error": str(e)})
+                }
+            else:
+                raise
+
+    def _execute_swaig_function(self, function_name: str, args: Optional[Dict[str, Any]] = None, call_id: Optional[str] = None, raw_data: Optional[Dict[str, Any]] = None):
+        """
+        Execute a SWAIG function in serverless context
+        
+        Args:
+            function_name: Name of the function to execute
+            args: Function arguments dictionary
+            call_id: Optional call ID
+            raw_data: Optional raw request data
+            
+        Returns:
+            Function execution result
+        """
+        # Use the existing logger
+        req_log = self.log.bind(
+            endpoint="serverless_swaig",
+            function=function_name
+        )
+        
+        if call_id:
+            req_log = req_log.bind(call_id=call_id)
+            
+        req_log.debug("serverless_function_call_received")
+        
+        try:
+            # Validate function exists
+            if function_name not in self._tool_registry._swaig_functions:
+                req_log.warning("function_not_found", available_functions=list(self._tool_registry._swaig_functions.keys()))
+                return {"error": f"Function '{function_name}' not found"}
+            
+            # Use empty args if not provided
+            if args is None:
+                args = {}
+                
+            # Use empty raw_data if not provided, but include function call structure
+            if raw_data is None:
+                raw_data = {
+                    "function": function_name,
+                    "argument": {
+                        "parsed": [args] if args else [],
+                        "raw": json.dumps(args) if args else "{}"
+                    }
+                }
+                if call_id:
+                    raw_data["call_id"] = call_id
+            
+            req_log.debug("executing_function", args=json.dumps(args))
+            
+            # Call the function using the existing on_function_call method
+            result = self.on_function_call(function_name, args, raw_data)
+            
+            # Convert result to dict if needed (same logic as in _handle_swaig_request)
+            if isinstance(result, SwaigFunctionResult):
+                result_dict = result.to_dict()
+            elif isinstance(result, dict):
+                result_dict = result
+            else:
+                result_dict = {"response": str(result)}
+            
+            req_log.info("serverless_function_executed_successfully")
+            req_log.debug("function_result", result=json.dumps(result_dict))
+            return result_dict
+            
+        except Exception as e:
+            req_log.error("serverless_function_execution_error", error=str(e))
+            return {"error": str(e), "function": function_name}
+
+    def _handle_google_cloud_function_request(self, request):
+        """
+        Handle Google Cloud Functions specific requests
+        
+        Args:
+            request: Flask request object from Google Cloud Functions
+            
+        Returns:
+            Flask response object
+        """
+        try:
+            # Get the path from the request
+            path = request.path.strip('/')
+            
+            if not path:
+                # Root request - return SWML
+                swml_response = self._render_swml()
+                from flask import Response
+                return Response(
+                    response=swml_response,
+                    status=200,
+                    headers={"Content-Type": "application/json"}
+                )
+            else:
+                # SWAIG function call
+                args = {}
+                call_id = None
+                raw_data = None
+                
+                # Parse request data
+                if request.method == 'POST':
+                    try:
+                        if request.is_json:
+                            raw_data = request.get_json()
+                        else:
+                            raw_data = json.loads(request.get_data(as_text=True))
+                        
+                        call_id = raw_data.get("call_id")
+                        
+                        # Extract arguments like the FastAPI handler does
+                        if "argument" in raw_data and isinstance(raw_data["argument"], dict):
+                            if "parsed" in raw_data["argument"] and isinstance(raw_data["argument"]["parsed"], list) and raw_data["argument"]["parsed"]:
+                                args = raw_data["argument"]["parsed"][0]
+                            elif "raw" in raw_data["argument"]:
+                                try:
+                                    args = json.loads(raw_data["argument"]["raw"])
+                                except Exception:
+                                    pass
+                    except Exception:
+                        # If parsing fails, continue with empty args
+                        pass
+                
+                result = self._execute_swaig_function(path, args, call_id, raw_data)
+                from flask import Response
+                return Response(
+                    response=json.dumps(result) if isinstance(result, dict) else str(result),
+                    status=200,
+                    headers={"Content-Type": "application/json"}
+                )
+                
+        except Exception as e:
+            import logging
+            logging.error(f"Error in Google Cloud Function request handler: {e}")
+            from flask import Response
+            return Response(
+                response=json.dumps({"error": str(e)}),
+                status=500,
+                headers={"Content-Type": "application/json"}
+            )
+
+    def _handle_azure_function_request(self, req):
+        """
+        Handle Azure Functions specific requests
+        
+        Args:
+            req: Azure Functions HttpRequest object
+            
+        Returns:
+            Azure Functions HttpResponse object
+        """
+        try:
+            import azure.functions as func
+            
+            # Get the path from the request
+            path = req.url.split('/')[-1] if req.url else ''
+            
+            if not path or path == 'api':
+                # Root request - return SWML
+                swml_response = self._render_swml()
+                return func.HttpResponse(
+                    body=swml_response,
+                    status_code=200,
+                    headers={"Content-Type": "application/json"}
+                )
+            else:
+                # SWAIG function call
+                args = {}
+                call_id = None
+                raw_data = None
+                
+                # Parse request data
+                if req.method == 'POST':
+                    try:
+                        body = req.get_body()
+                        if body:
+                            raw_data = json.loads(body.decode('utf-8'))
+                            call_id = raw_data.get("call_id")
+                            
+                            # Extract arguments like the FastAPI handler does
+                            if "argument" in raw_data and isinstance(raw_data["argument"], dict):
+                                if "parsed" in raw_data["argument"] and isinstance(raw_data["argument"]["parsed"], list) and raw_data["argument"]["parsed"]:
+                                    args = raw_data["argument"]["parsed"][0]
+                                elif "raw" in raw_data["argument"]:
+                                    try:
+                                        args = json.loads(raw_data["argument"]["raw"])
+                                    except Exception:
+                                        pass
+                    except Exception:
+                        # If parsing fails, continue with empty args
+                        pass
+                
+                result = self._execute_swaig_function(path, args, call_id, raw_data)
+                return func.HttpResponse(
+                    body=json.dumps(result) if isinstance(result, dict) else str(result),
+                    status_code=200,
+                    headers={"Content-Type": "application/json"}
+                )
+                
+        except Exception as e:
+            import logging
+            logging.error(f"Error in Azure Function request handler: {e}")
+            import azure.functions as func
+            return func.HttpResponse(
+                body=json.dumps({"error": str(e)}),
+                status_code=500,
+                headers={"Content-Type": "application/json"}
+            )

signalwire_agents/core/mixins/skill_mixin.py

@@ -0,0 +1,55 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire AI Agents SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+"""
+
+from typing import List, Dict, Any, Optional
+
+
+class SkillMixin:
+    """
+    Mixin class containing all skill management methods for AgentBase
+    """
+    
+    def add_skill(self, skill_name: str, params: Optional[Dict[str, Any]] = None) -> 'AgentBase':
+        """
+        Add a skill to this agent
+        
+        Args:
+            skill_name: Name of the skill to add
+            params: Optional parameters to pass to the skill for configuration
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            ValueError: If skill not found or failed to load with detailed error message
+        """
+        # Debug logging
+        self.log.debug("add_skill_called",
+                      skill_name=skill_name,
+                      agent_id=id(self),
+                      registry_id=id(self._tool_registry) if hasattr(self, '_tool_registry') else None,
+                      is_ephemeral=getattr(self, '_is_ephemeral', False))
+        
+        success, error_message = self.skill_manager.load_skill(skill_name, params=params)
+        if not success:
+            raise ValueError(f"Failed to load skill '{skill_name}': {error_message}")
+        return self
+
+    def remove_skill(self, skill_name: str) -> 'AgentBase':
+        """Remove a skill from this agent"""
+        self.skill_manager.unload_skill(skill_name)
+        return self
+
+    def list_skills(self) -> List[str]:
+        """List currently loaded skills"""
+        return self.skill_manager.list_loaded_skills()
+
+    def has_skill(self, skill_name: str) -> bool:
+        """Check if skill is loaded"""
+        return self.skill_manager.has_skill(skill_name)

signalwire_agents/core/mixins/state_mixin.py

@@ -0,0 +1,219 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire AI Agents SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+"""
+
+from typing import Callable
+
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+
+class StateMixin:
+    """
+    Mixin class containing all state and session management methods for AgentBase
+    """
+    
+    def _create_tool_token(self, tool_name: str, call_id: str) -> str:
+        """
+        Create a secure token for a tool call
+        
+        Args:
+            tool_name: Name of the tool
+            call_id: Call ID for this session
+            
+        Returns:
+            Secure token string
+        """
+        try:
+            # Ensure we have a session manager
+            if not hasattr(self, '_session_manager'):
+                self.log.error("no_session_manager")
+                return ""
+                
+            # Create the token using the session manager
+            return self._session_manager.create_tool_token(tool_name, call_id)
+        except Exception as e:
+            self.log.error("token_creation_error", error=str(e), tool=tool_name, call_id=call_id)
+            return ""
+    
+    def validate_tool_token(self, function_name: str, token: str, call_id: str) -> bool:
+        """
+        Validate a tool token
+        
+        Args:
+            function_name: Name of the function/tool
+            token: Token to validate
+            call_id: Call ID for the session
+            
+        Returns:
+            True if token is valid, False otherwise
+        """
+        try:
+            # Skip validation for non-secure tools
+            if function_name not in self._tool_registry._swaig_functions:
+                self.log.warning("unknown_function", function=function_name)
+                return False
+                
+            # Get the function and check if it's secure
+            func = self._tool_registry._swaig_functions[function_name]
+            is_secure = True  # Default to secure
+            
+            if isinstance(func, dict):
+                # For raw dictionaries (DataMap functions), they're always secure
+                is_secure = True
+            else:
+                # For SWAIGFunction objects, check the secure attribute
+                is_secure = func.secure
+                
+            # Always allow non-secure functions
+            if not is_secure:
+                self.log.debug("non_secure_function_allowed", function=function_name)
+                return True
+            
+            # Check if we have a session manager
+            if not hasattr(self, '_session_manager'):
+                self.log.error("no_session_manager")
+                return False
+            
+            # Handle missing token
+            if not token:
+                self.log.warning("missing_token", function=function_name)
+                return False
+                
+            # For debugging: Log token details
+            try:
+                # Capture original parameters
+                self.log.debug("token_validate_input", 
+                              function=function_name, 
+                              call_id=call_id, 
+                              token_length=len(token))
+                
+                # Try to decode token for debugging
+                if hasattr(self._session_manager, 'debug_token'):
+                    debug_info = self._session_manager.debug_token(token)
+                    self.log.debug("token_debug", debug_info=debug_info)
+                    
+                    # Extract token components
+                    if debug_info.get("valid_format") and "components" in debug_info:
+                        components = debug_info["components"]
+                        token_call_id = components.get("call_id")
+                        token_function = components.get("function")
+                        token_expiry = components.get("expiry")
+                        
+                        # Log parameter mismatches
+                        if token_function != function_name:
+                            self.log.warning("token_function_mismatch", 
+                                           expected=function_name, 
+                                           actual=token_function)
+                        
+                        if token_call_id != call_id:
+                            self.log.warning("token_call_id_mismatch", 
+                                           expected=call_id, 
+                                           actual=token_call_id)
+                            
+                        # Check expiration
+                        if debug_info.get("status", {}).get("is_expired"):
+                            self.log.warning("token_expired", 
+                                           expires_in=debug_info["status"].get("expires_in_seconds"))
+            except Exception as e:
+                self.log.error("token_debug_error", error=str(e))
+                
+            # Use call_id from token if the provided one is empty
+            if not call_id and hasattr(self._session_manager, 'debug_token'):
+                try:
+                    debug_info = self._session_manager.debug_token(token)
+                    if debug_info.get("valid_format") and "components" in debug_info:
+                        token_call_id = debug_info["components"].get("call_id")
+                        if token_call_id:
+                            self.log.debug("using_call_id_from_token", call_id=token_call_id)
+                            is_valid = self._session_manager.validate_tool_token(function_name, token, token_call_id)
+                            if is_valid:
+                                self.log.debug("token_valid_with_extracted_call_id")
+                                return True
+                except Exception as e:
+                    self.log.error("error_using_call_id_from_token", error=str(e))
+            
+            # Normal validation with provided call_id
+            is_valid = self._session_manager.validate_tool_token(function_name, token, call_id)
+            
+            if is_valid:
+                self.log.debug("token_valid", function=function_name)
+            else:
+                self.log.warning("token_invalid", function=function_name)
+                
+            return is_valid
+        except Exception as e:
+            self.log.error("token_validation_error", error=str(e), function=function_name)
+            return False
+    
+    # Note: set_dynamic_config_callback is implemented in WebMixin
+    
+    def _register_state_tracking_tools(self):
+        """
+        Register special tools for state tracking
+        
+        This adds startup_hook and hangup_hook SWAIG functions that automatically
+        activate and deactivate the session when called. These are useful for
+        tracking call state and cleaning up resources when a call ends.
+        """
+        # Register startup hook to activate session
+        self.define_tool(
+            name="startup_hook",
+            description="Called when a new conversation starts to initialize state",
+            parameters={},
+            handler=lambda args, raw_data: self._handle_startup_hook(args, raw_data),
+            secure=False  # No auth needed for this system function
+        )
+        
+        # Register hangup hook to end session
+        self.define_tool(
+            name="hangup_hook",
+            description="Called when conversation ends to clean up resources",
+            parameters={},
+            handler=lambda args, raw_data: self._handle_hangup_hook(args, raw_data),
+            secure=False  # No auth needed for this system function
+        )
+    
+    def _handle_startup_hook(self, args, raw_data):
+        """
+        Handle the startup hook function call
+        
+        Args:
+            args: Function arguments (empty for this hook)
+            raw_data: Raw request data containing call_id
+            
+        Returns:
+            Success response
+        """
+        call_id = raw_data.get("call_id") if raw_data else None
+        if call_id:
+            self.log.info("session_activated", call_id=call_id)
+            self._session_manager.activate_session(call_id)
+            return SwaigFunctionResult("Session activated")
+        else:
+            self.log.warning("session_activation_failed", error="No call_id provided")
+            return SwaigFunctionResult("Failed to activate session: No call_id provided")
+    
+    def _handle_hangup_hook(self, args, raw_data):
+        """
+        Handle the hangup hook function call
+        
+        Args:
+            args: Function arguments (empty for this hook)
+            raw_data: Raw request data containing call_id
+            
+        Returns:
+            Success response
+        """
+        call_id = raw_data.get("call_id") if raw_data else None
+        if call_id:
+            self.log.info("session_ended", call_id=call_id)
+            self._session_manager.end_session(call_id)
+            return SwaigFunctionResult("Session ended")
+        else:
+            self.log.warning("session_end_failed", error="No call_id provided")
+            return SwaigFunctionResult("Failed to end session: No call_id provided")