signalwire-agents 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

signalwire_agents/core/state/state_manager.py

@@ -1,92 +0,0 @@
-"""
-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

@@ -1,163 +0,0 @@
-"""
-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

@@ -1,205 +0,0 @@
-"""
-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

@@ -1,218 +0,0 @@
-"""
-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