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

signalwire_agents/core/state/file_state_manager.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.
+"""
+
+"""
+File-based implementation of the StateManager interface
+"""
+
+import os
+import json
+import tempfile
+import time
+from datetime import datetime, timedelta
+from typing import Dict, Any, Optional, List
+
+from .state_manager import StateManager
+
+
+class FileStateManager(StateManager):
+    """
+    File-based state manager implementation
+    
+    This implementation stores state data as JSON files in a directory.
+    Each call's state is stored in a separate file named by call_id.
+    Files older than expiry_days are automatically cleaned up.
+    
+    This is suitable for development and low-volume deployments.
+    For production, consider using database or Redis implementations.
+    """
+    
+    def __init__(
+        self,
+        storage_dir: Optional[str] = None,
+        expiry_days: float = 1.0
+    ):
+        """
+        Initialize the file state manager
+        
+        Args:
+            storage_dir: Directory to store state files (default: system temp dir)
+            expiry_days: Days after which state files are considered expired
+        """
+        self.storage_dir = storage_dir or os.path.join(tempfile.gettempdir(), "signalwire_state")
+        self.expiry_days = expiry_days
+        
+        # Create storage directory if it doesn't exist
+        if not os.path.exists(self.storage_dir):
+            os.makedirs(self.storage_dir)
+    
+    def _get_file_path(self, call_id: str) -> str:
+        """Get the file path for a call_id"""
+        # Sanitize call_id to ensure it's safe for a filename
+        sanitized_id = "".join(c for c in call_id if c.isalnum() or c in "-_.")
+        return os.path.join(self.storage_dir, f"{sanitized_id}.json")
+    
+    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
+        """
+        try:
+            # Add metadata including timestamp
+            state_data = {
+                "call_id": call_id,
+                "created_at": datetime.now().isoformat(),
+                "last_updated": datetime.now().isoformat(),
+                "data": data
+            }
+            
+            file_path = self._get_file_path(call_id)
+            with open(file_path, "w") as f:
+                json.dump(state_data, f, indent=2)
+            return True
+        except Exception as e:
+            print(f"Error storing state for call {call_id}: {e}")
+            return False
+    
+    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
+        """
+        file_path = self._get_file_path(call_id)
+        if not os.path.exists(file_path):
+            return None
+            
+        try:
+            with open(file_path, "r") as f:
+                state_data = json.load(f)
+            
+            # Check if the file is expired
+            created_at = datetime.fromisoformat(state_data["created_at"])
+            if (datetime.now() - created_at) > timedelta(days=self.expiry_days):
+                # Expired, so delete it and return None
+                os.remove(file_path)
+                return None
+                
+            return state_data["data"]
+        except Exception as e:
+            print(f"Error retrieving state for call {call_id}: {e}")
+            return None
+    
+    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
+        """
+        file_path = self._get_file_path(call_id)
+        if not os.path.exists(file_path):
+            # If no existing data, just store new data
+            return self.store(call_id, data)
+            
+        try:
+            # Read existing data
+            with open(file_path, "r") as f:
+                state_data = json.load(f)
+                
+            # Update the data (deep merge)
+            existing_data = state_data["data"]
+            self._deep_update(existing_data, data)
+            
+            # Update metadata
+            state_data["last_updated"] = datetime.now().isoformat()
+            state_data["data"] = existing_data
+            
+            # Write back to file
+            with open(file_path, "w") as f:
+                json.dump(state_data, f, indent=2)
+                
+            return True
+        except Exception as e:
+            print(f"Error updating state for call {call_id}: {e}")
+            return False
+    
+    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
+        """
+        file_path = self._get_file_path(call_id)
+        if not os.path.exists(file_path):
+            return False
+            
+        try:
+            os.remove(file_path)
+            return True
+        except Exception as e:
+            print(f"Error deleting state for call {call_id}: {e}")
+            return False
+    
+    def cleanup_expired(self) -> int:
+        """
+        Clean up expired state files
+        
+        Returns:
+            Number of expired files cleaned up
+        """
+        count = 0
+        try:
+            # Get all state files
+            for filename in os.listdir(self.storage_dir):
+                if not filename.endswith(".json"):
+                    continue
+                    
+                file_path = os.path.join(self.storage_dir, filename)
+                
+                try:
+                    # Read the file to check creation time
+                    with open(file_path, "r") as f:
+                        state_data = json.load(f)
+                        
+                    # Check if the file is expired
+                    created_at = datetime.fromisoformat(state_data["created_at"])
+                    if (datetime.now() - created_at) > timedelta(days=self.expiry_days):
+                        os.remove(file_path)
+                        count += 1
+                except Exception:
+                    # Skip files that can't be processed
+                    continue
+                    
+            return count
+        except Exception as e:
+            print(f"Error cleaning up expired state files: {e}")
+            return count
+    
+    def _deep_update(self, d: Dict, u: Dict) -> None:
+        """Recursively update a nested dictionary"""
+        for k, v in u.items():
+            if isinstance(v, dict) and k in d and isinstance(d[k], dict):
+                self._deep_update(d[k], v)
+            else:
+                d[k] = v 

signalwire_agents/core/state/state_manager.py

@@ -0,0 +1,101 @@
+"""
+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.
+"""
+
+"""
+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,172 @@
+"""
+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.
+"""
+
+"""
+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,214 @@
+"""
+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.
+"""
+
+"""
+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