signalwire-agents 0.1.0__py3-none-any.whl

signalwire_agents/core/state/state_manager.py

@@ -0,0 +1,92 @@
+"""
+Abstract base class for state management
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+
+
+class StateManager(ABC):
+    """
+    Abstract base class for state management
+    
+    This defines the interface that all state manager implementations
+    must follow. State managers are responsible for storing, retrieving,
+    and managing call-specific state data.
+    """
+    
+    @abstractmethod
+    def store(self, call_id: str, data: Dict[str, Any]) -> bool:
+        """
+        Store state data for a call
+        
+        Args:
+            call_id: Unique identifier for the call
+            data: Dictionary of state data to store
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+    
+    @abstractmethod
+    def retrieve(self, call_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve state data for a call
+        
+        Args:
+            call_id: Unique identifier for the call
+            
+        Returns:
+            Dictionary of state data or None if not found
+        """
+        pass
+    
+    @abstractmethod
+    def update(self, call_id: str, data: Dict[str, Any]) -> bool:
+        """
+        Update state data for a call
+        
+        Args:
+            call_id: Unique identifier for the call
+            data: Dictionary of state data to update (merged with existing)
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+    
+    @abstractmethod
+    def delete(self, call_id: str) -> bool:
+        """
+        Delete state data for a call
+        
+        Args:
+            call_id: Unique identifier for the call
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+    
+    @abstractmethod
+    def cleanup_expired(self) -> int:
+        """
+        Clean up expired state data
+        
+        Returns:
+            Number of expired items cleaned up
+        """
+        pass
+    
+    def exists(self, call_id: str) -> bool:
+        """
+        Check if state exists for a call
+        
+        Args:
+            call_id: Unique identifier for the call
+            
+        Returns:
+            True if state exists, False otherwise
+        """
+        return self.retrieve(call_id) is not None 

signalwire_agents/core/swaig_function.py

@@ -0,0 +1,163 @@
+"""
+SwaigFunction class for defining and managing SWAIG function interfaces
+"""
+
+from typing import Dict, Any, Optional, Callable, List, Type, Union
+import inspect
+import logging
+
+
+class SWAIGFunction:
+    """
+    Represents a SWAIG function for AI integration
+    """
+    def __init__(
+        self, 
+        name: str, 
+        handler: Callable, 
+        description: str,
+        parameters: Dict[str, Dict] = None,
+        secure: bool = False,
+        fillers: Optional[Dict[str, List[str]]] = None
+    ):
+        """
+        Initialize a new SWAIG function
+        
+        Args:
+            name: Name of the function to appear in SWML
+            handler: Function to call when this SWAIG function is invoked
+            description: Human-readable description of the function
+            parameters: Dictionary of parameters, keys are parameter names, values are param definitions
+            secure: Whether this function requires token validation
+            fillers: Optional dictionary of filler phrases by language code
+        """
+        self.name = name
+        self.handler = handler
+        self.description = description
+        self.parameters = parameters or {}
+        self.secure = secure
+        self.fillers = fillers
+        
+    def _ensure_parameter_structure(self) -> Dict:
+        """
+        Ensure the parameters are correctly structured for SWML
+        
+        Returns:
+            Parameters dict with correct structure
+        """
+        if not self.parameters:
+            return {"type": "object", "properties": {}}
+            
+        # Check if we already have the correct structure 
+        if "type" in self.parameters and "properties" in self.parameters:
+            return self.parameters
+            
+        # Otherwise, wrap the parameters in the expected structure
+        return {
+            "type": "object",
+            "properties": self.parameters
+        }
+        
+    def __call__(self, *args, **kwargs):
+        """
+        Call the underlying handler function
+        """
+        return self.handler(*args, **kwargs)
+
+    def execute(self, args: Dict[str, Any], raw_data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Execute the function with the given arguments
+        
+        Args:
+            args: Parsed arguments for the function
+            raw_data: Optional raw request data
+            
+        Returns:
+            Function result as a dictionary (from SwaigFunctionResult.to_dict())
+        """
+        try:
+            # Raw data is mandatory, but we'll handle the case where it's null for robustness
+            if raw_data is None:
+                raw_data = {}  # Provide an empty dict as fallback
+
+            # Call the handler with both args and raw_data
+            result = self.handler(args, raw_data)
+                
+            # Import here to avoid circular imports
+            from signalwire_agents.core.function_result import SwaigFunctionResult
+            
+            # Handle different result types - everything must end up as a SwaigFunctionResult
+            if isinstance(result, SwaigFunctionResult):
+                # Already a SwaigFunctionResult - just convert to dict
+                return result.to_dict()
+            elif isinstance(result, dict) and "response" in result:
+                # Already in the correct format - use as is
+                return result
+            elif isinstance(result, dict):
+                # Dictionary without response - create a SwaigFunctionResult
+                return SwaigFunctionResult("Function completed successfully").to_dict()
+            else:
+                # String or other type - create a SwaigFunctionResult with the string representation
+                return SwaigFunctionResult(str(result)).to_dict()
+                
+        except Exception as e:
+            # Log the error for debugging but don't expose details to the AI
+            logging.error(f"Error executing SWAIG function {self.name}: {str(e)}")
+            # Return a generic error message
+            return SwaigFunctionResult(
+                "Sorry, I couldn't complete that action. Please try again or contact support if the issue persists."
+            ).to_dict()
+        
+    def validate_args(self, args: Dict[str, Any]) -> bool:
+        """
+        Validate the arguments against the parameter schema
+        
+        Args:
+            args: Arguments to validate
+            
+        Returns:
+            True if valid, False otherwise
+        """
+        # TODO: Implement JSON Schema validation
+        return True
+        
+    def to_swaig(self, base_url: str, token: Optional[str] = None, call_id: Optional[str] = None, include_auth: bool = True) -> Dict[str, Any]:
+        """
+        Convert this function to a SWAIG-compatible JSON object for SWML
+        
+        Args:
+            base_url: Base URL for the webhook
+            token: Optional auth token to include
+            call_id: Optional call ID for session tracking
+            include_auth: Whether to include auth credentials in URL
+            
+        Returns:
+            Dictionary representation for the SWAIG array in SWML
+        """
+        # All functions use a single /swaig endpoint
+        url = f"{base_url}/swaig"
+        
+        # Add token and call_id parameters if provided
+        if token and call_id:
+            url = f"{url}?token={token}&call_id={call_id}"
+        
+        # Create properly structured function definition
+        function_def = {
+            "function": self.name,
+            "description": self.description,
+            "parameters": self._ensure_parameter_structure(),
+        }
+        
+        # Only add web_hook_url if not using defaults
+        # This will be handled by the defaults section in the SWAIG array
+        if url:
+            function_def["web_hook_url"] = url
+            
+        # Add fillers if provided
+        if self.fillers and len(self.fillers) > 0:
+            function_def["fillers"] = self.fillers
+            
+        return function_def
+
+# Add an alias for backward compatibility
+SwaigFunction = SWAIGFunction

signalwire_agents/core/swml_builder.py

@@ -0,0 +1,205 @@
+"""
+SWML Builder - Fluent API for building SWML documents
+
+This module provides a fluent builder API for creating SWML documents.
+It allows for chaining method calls to build up a document step by step.
+"""
+
+from typing import Dict, List, Any, Optional, Union, Self, TypeVar
+
+from signalwire_agents.core.swml_service import SWMLService
+
+
+T = TypeVar('T', bound='SWMLBuilder')
+
+
+class SWMLBuilder:
+    """
+    Fluent builder for SWML documents
+    
+    This class provides a fluent interface for building SWML documents
+    by chaining method calls. It delegates to an underlying SWMLService
+    instance for the actual document creation.
+    """
+    
+    def __init__(self, service: SWMLService):
+        """
+        Initialize with a SWMLService instance
+        
+        Args:
+            service: The SWMLService to delegate to
+        """
+        self.service = service
+    
+    def answer(self, max_duration: Optional[int] = None, codecs: Optional[str] = None) -> Self:
+        """
+        Add an 'answer' verb to the main section
+        
+        Args:
+            max_duration: Maximum duration in seconds
+            codecs: Comma-separated list of codecs
+            
+        Returns:
+            Self for method chaining
+        """
+        self.service.add_answer_verb(max_duration, codecs)
+        return self
+    
+    def hangup(self, reason: Optional[str] = None) -> Self:
+        """
+        Add a 'hangup' verb to the main section
+        
+        Args:
+            reason: Optional reason for hangup
+            
+        Returns:
+            Self for method chaining
+        """
+        self.service.add_hangup_verb(reason)
+        return self
+    
+    def ai(self, 
+          prompt_text: Optional[str] = None,
+          prompt_pom: Optional[List[Dict[str, Any]]] = None,
+          post_prompt: Optional[str] = None,
+          post_prompt_url: Optional[str] = None,
+          swaig: Optional[Dict[str, Any]] = None,
+          **kwargs) -> Self:
+        """
+        Add an 'ai' verb to the main section
+        
+        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)
+            post_prompt: Optional post-prompt text
+            post_prompt_url: Optional URL for post-prompt processing
+            swaig: Optional SWAIG configuration
+            **kwargs: Additional AI parameters
+            
+        Returns:
+            Self for method chaining
+        """
+        self.service.add_ai_verb(
+            prompt_text=prompt_text,
+            prompt_pom=prompt_pom,
+            post_prompt=post_prompt,
+            post_prompt_url=post_prompt_url,
+            swaig=swaig,
+            **kwargs
+        )
+        return self
+    
+    def play(self, url: Optional[str] = None, urls: Optional[List[str]] = None, 
+             volume: Optional[float] = None, say_voice: Optional[str] = None, 
+             say_language: Optional[str] = None, say_gender: Optional[str] = None,
+             auto_answer: Optional[bool] = None) -> Self:
+        """
+        Add a 'play' verb to the main section
+        
+        Args:
+            url: Single URL to play (mutually exclusive with urls)
+            urls: List of URLs to play (mutually exclusive with url)
+            volume: Volume level (-40 to 40)
+            say_voice: Voice for text-to-speech
+            say_language: Language for text-to-speech
+            say_gender: Gender for text-to-speech
+            auto_answer: Whether to auto-answer the call
+            
+        Returns:
+            Self for method chaining
+        """
+        # Create base config
+        config = {}
+        
+        # Add play config (either single URL or list)
+        if url is not None:
+            config["url"] = url
+        elif urls is not None:
+            config["urls"] = urls
+        else:
+            raise ValueError("Either url or urls must be provided")
+        
+        # Add optional parameters
+        if volume is not None:
+            config["volume"] = volume
+        if say_voice is not None:
+            config["say_voice"] = say_voice
+        if say_language is not None:
+            config["say_language"] = say_language
+        if say_gender is not None:
+            config["say_gender"] = say_gender
+        if auto_answer is not None:
+            config["auto_answer"] = auto_answer
+        
+        # Add the verb
+        self.service.add_verb("play", config)
+        return self
+    
+    def say(self, text: str, voice: Optional[str] = None, 
+            language: Optional[str] = None, gender: Optional[str] = None,
+            volume: Optional[float] = None) -> Self:
+        """
+        Add a 'play' verb with say: prefix for text-to-speech
+        
+        Args:
+            text: Text to speak
+            voice: Voice for text-to-speech
+            language: Language for text-to-speech
+            gender: Gender for text-to-speech
+            volume: Volume level (-40 to 40)
+            
+        Returns:
+            Self for method chaining
+        """
+        # Create play config with say: prefix
+        url = f"say:{text}"
+        
+        # Add the verb
+        return self.play(
+            url=url,
+            say_voice=voice,
+            say_language=language,
+            say_gender=gender,
+            volume=volume
+        )
+    
+    def add_section(self, section_name: str) -> Self:
+        """
+        Add a new section to the document
+        
+        Args:
+            section_name: Name of the section to add
+            
+        Returns:
+            Self for method chaining
+        """
+        self.service.add_section(section_name)
+        return self
+    
+    def build(self) -> Dict[str, Any]:
+        """
+        Build and return the SWML document
+        
+        Returns:
+            The complete SWML document as a dictionary
+        """
+        return self.service.get_document()
+    
+    def render(self) -> str:
+        """
+        Build and render the SWML document as a JSON string
+        
+        Returns:
+            The complete SWML document as a JSON string
+        """
+        return self.service.render_document()
+    
+    def reset(self) -> Self:
+        """
+        Reset the document to an empty state
+        
+        Returns:
+            Self for method chaining
+        """
+        self.service.reset_document()
+        return self 

signalwire_agents/core/swml_handler.py

@@ -0,0 +1,218 @@
+"""
+SWML Verb Handlers - Interface and implementations for SWML verb handling
+
+This module defines the base interface for SWML verb handlers and provides
+implementations for specific verbs that require special handling.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, List, Any, Optional, Tuple
+
+
+class SWMLVerbHandler(ABC):
+    """
+    Base interface for SWML verb handlers
+    
+    This abstract class defines the interface that all SWML verb handlers
+    must implement. Verb handlers provide specialized logic for complex
+    SWML verbs that cannot be handled generically.
+    """
+    
+    @abstractmethod
+    def get_verb_name(self) -> str:
+        """
+        Get the name of the verb this handler handles
+        
+        Returns:
+            The verb name as a string
+        """
+        pass
+    
+    @abstractmethod
+    def validate_config(self, config: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        """
+        Validate the configuration for this verb
+        
+        Args:
+            config: The configuration dictionary for this verb
+            
+        Returns:
+            (is_valid, error_messages) tuple
+        """
+        pass
+    
+    @abstractmethod
+    def build_config(self, **kwargs) -> Dict[str, Any]:
+        """
+        Build a configuration for this verb from the provided arguments
+        
+        Args:
+            **kwargs: Keyword arguments specific to this verb
+            
+        Returns:
+            Configuration dictionary
+        """
+        pass
+
+
+class AIVerbHandler(SWMLVerbHandler):
+    """
+    Handler for the SWML 'ai' verb
+    
+    The 'ai' verb is complex and requires specialized handling, particularly
+    for managing prompts, SWAIG functions, and AI configurations.
+    """
+    
+    def get_verb_name(self) -> str:
+        """
+        Get the name of the verb this handler handles
+        
+        Returns:
+            "ai" as the verb name
+        """
+        return "ai"
+    
+    def validate_config(self, config: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        """
+        Validate the configuration for the AI verb
+        
+        Args:
+            config: The configuration dictionary for the AI verb
+            
+        Returns:
+            (is_valid, error_messages) tuple
+        """
+        errors = []
+        
+        # Check required fields
+        if "prompt" not in config:
+            errors.append("Missing required field 'prompt'")
+        
+        # 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'")
+        
+        # Validate SWAIG structure if present
+        if "SWAIG" in config:
+            swaig = config["SWAIG"]
+            if not isinstance(swaig, dict):
+                errors.append("'SWAIG' must be an object")
+        
+        return len(errors) == 0, errors
+    
+    def build_config(self, 
+                    prompt_text: Optional[str] = None,
+                    prompt_pom: Optional[List[Dict[str, Any]]] = None,
+                    post_prompt: Optional[str] = None,
+                    post_prompt_url: Optional[str] = None,
+                    swaig: Optional[Dict[str, Any]] = None,
+                    **kwargs) -> Dict[str, Any]:
+        """
+        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)
+            post_prompt: Optional post-prompt text
+            post_prompt_url: Optional URL for post-prompt processing
+            swaig: Optional SWAIG configuration
+            **kwargs: Additional AI parameters
+            
+        Returns:
+            AI verb configuration dictionary
+        """
+        config = {}
+        
+        # Add prompt (either text or POM)
+        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")
+        
+        # Add post-prompt if provided
+        if post_prompt is not None:
+            config["post_prompt"] = {"text": post_prompt}
+        
+        # Add post-prompt URL if provided
+        if post_prompt_url is not None:
+            config["post_prompt_url"] = post_prompt_url
+        
+        # Add SWAIG if provided
+        if swaig is not None:
+            config["SWAIG"] = swaig
+        
+        # Add any additional parameters
+        if "params" not in config:
+            config["params"] = {}
+            
+        for key, value in kwargs.items():
+            # Special handling for certain parameters
+            if key == "languages":
+                config["languages"] = value
+            elif key == "hints":
+                config["hints"] = value
+            elif key == "pronounce":
+                config["pronounce"] = value
+            elif key == "global_data":
+                config["global_data"] = value
+            else:
+                # Add to params object
+                config["params"][key] = value
+        
+        return config
+
+
+class VerbHandlerRegistry:
+    """
+    Registry for SWML verb handlers
+    
+    This class maintains a registry of handlers for special SWML verbs
+    and provides methods for accessing and using them.
+    """
+    
+    def __init__(self):
+        """Initialize the registry with default handlers"""
+        self._handlers = {}
+        
+        # Register default handlers
+        self.register_handler(AIVerbHandler())
+    
+    def register_handler(self, handler: SWMLVerbHandler) -> None:
+        """
+        Register a new verb handler
+        
+        Args:
+            handler: The handler to register
+        """
+        verb_name = handler.get_verb_name()
+        self._handlers[verb_name] = handler
+    
+    def get_handler(self, verb_name: str) -> Optional[SWMLVerbHandler]:
+        """
+        Get the handler for a specific verb
+        
+        Args:
+            verb_name: The name of the verb
+            
+        Returns:
+            The handler if found, None otherwise
+        """
+        return self._handlers.get(verb_name)
+    
+    def has_handler(self, verb_name: str) -> bool:
+        """
+        Check if a handler exists for a specific verb
+        
+        Args:
+            verb_name: The name of the verb
+            
+        Returns:
+            True if a handler exists, False otherwise
+        """
+        return verb_name in self._handlers