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

signalwire_agents/core/function_result.py

@@ -0,0 +1,123 @@
+"""
+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.
+"""
+
+"""
+SwaigFunctionResult class for handling the response format of SWAIG function calls
+"""
+
+from typing import Dict, List, Any, Optional, Union
+
+
+class SwaigFunctionResult:
+    """
+    Wrapper around SWAIG function responses that handles proper formatting
+    of response text and actions.
+    
+    Example:
+        return SwaigFunctionResult("Found your order")
+        
+        # With actions
+        return (
+            SwaigFunctionResult("I'll transfer you to support")
+            .add_action("transfer", {"dest": "support"})
+        )
+        
+        # With simple action value
+        return (
+            SwaigFunctionResult("I'll confirm that")
+            .add_action("confirm", True)
+        )
+        
+        # With multiple actions
+        return (
+            SwaigFunctionResult("Processing your request")
+            .add_actions([
+                {"set_global_data": {"key": "value"}},
+                {"play": {"url": "music.mp3"}}
+            ])
+        )
+    """
+    def __init__(self, response: Optional[str] = None):
+        """
+        Initialize a new SWAIG function result
+        
+        Args:
+            response: Optional natural language response to include
+        """
+        self.response = response or ""
+        self.action: List[Dict[str, Any]] = []
+    
+    def set_response(self, response: str) -> 'SwaigFunctionResult':
+        """
+        Set the natural language response text
+        
+        Args:
+            response: The text the AI should say
+            
+        Returns:
+            Self for method chaining
+        """
+        self.response = response
+        return self
+    
+    def add_action(self, name: str, data: Any) -> 'SwaigFunctionResult':
+        """
+        Add a structured action to the response
+        
+        Args:
+            name: The name/type of the action (e.g., "play", "transfer")
+            data: The data for the action - can be a string, boolean, object, or array
+            
+        Returns:
+            Self for method chaining
+        """
+        self.action.append({name: data})
+        return self
+    
+    def add_actions(self, actions: List[Dict[str, Any]]) -> 'SwaigFunctionResult':
+        """
+        Add multiple structured actions to the response
+        
+        Args:
+            actions: List of action objects to add to the response
+            
+        Returns:
+            Self for method chaining
+        """
+        self.action.extend(actions)
+        return self
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to the JSON structure expected by SWAIG
+        
+        The result must have at least one of:
+        - 'response': Text to be spoken by the AI
+        - 'action': Array of action objects
+        
+        Returns:
+            Dictionary in SWAIG function response format
+        """
+        # Create the result object
+        result = {}
+        
+        # Add response if present
+        if self.response:
+            result["response"] = self.response
+            
+        # Add action if present
+        if self.action:
+            result["action"] = self.action
+            
+        # Ensure we have at least one of response or action
+        if not result:
+            # Default response if neither is present
+            result["response"] = "Action completed."
+            
+        return result

signalwire_agents/core/pom_builder.py

@@ -0,0 +1,204 @@
+"""
+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.
+"""
+
+"""
+PomBuilder for creating structured POM prompts for SignalWire AI Agents
+"""
+
+try:
+    from signalwire_pom.pom import PromptObjectModel, Section
+except ImportError:
+    raise ImportError(
+        "signalwire-pom package is required. "
+        "Install it with: pip install signalwire-pom"
+    )
+
+from typing import List, Dict, Any, Optional, Union
+
+
+class PomBuilder:
+    """
+    Builder class for creating structured prompts using the Prompt Object Model.
+    
+    This class is a flexible wrapper around the POM API that allows for:
+    - Dynamic creation of sections on demand
+    - Adding content to existing sections
+    - Nesting subsections
+    - Rendering to markdown or XML
+    
+    Unlike previous implementations, there are no predefined section types -
+    you can create any section structure that fits your needs.
+    """
+    
+    def __init__(self):
+        """Initialize a new POM builder with an empty POM"""
+        self.pom = PromptObjectModel()
+        self._sections: Dict[str, Section] = {}
+    
+    def add_section(self, title: str, body: str = "", bullets: Optional[List[str]] = None, 
+                    numbered: bool = False, numbered_bullets: bool = False, 
+                    subsections: Optional[List[Dict[str, Any]]] = None) -> 'PomBuilder':
+        """
+        Add a new section to the POM
+        
+        Args:
+            title: Section title
+            body: Optional body text
+            bullets: Optional list of bullet points
+            numbered: Whether to number this section
+            numbered_bullets: Whether to number bullet points
+            subsections: Optional list of subsection objects
+            
+        Returns:
+            Self for method chaining
+        """
+        section = self.pom.add_section(
+            title=title, 
+            body=body, 
+            bullets=bullets or [],
+            numbered=numbered,
+            numberedBullets=numbered_bullets
+        )
+        self._sections[title] = section
+        
+        # Process subsections if provided
+        if subsections:
+            for subsection_data in subsections:
+                if 'title' in subsection_data:
+                    subsection_title = subsection_data['title']
+                    subsection_body = subsection_data.get('body', '')
+                    subsection_bullets = subsection_data.get('bullets', [])
+                    
+                    section.add_subsection(
+                        title=subsection_title,
+                        body=subsection_body,
+                        bullets=subsection_bullets or []
+                    )
+        
+        return self
+    
+    def add_to_section(self, title: str, body: Optional[str] = None, bullet: Optional[str] = None, bullets: Optional[List[str]] = None) -> 'PomBuilder':
+        """
+        Add content to an existing section
+        
+        Args:
+            title: Section title
+            body: Text to append to the section body
+            bullet: Single bullet to add
+            bullets: List of bullets to add
+            
+        Returns:
+            Self for method chaining
+        """
+        # Create section if it doesn't exist - auto-vivification
+        if title not in self._sections:
+            self.add_section(title)
+            
+        section = self._sections[title]
+        
+        # Add body text if provided
+        if body:
+            if hasattr(section, 'body') and section.body:
+                section.body = f"{section.body}\n\n{body}"
+            else:
+                section.body = body
+                
+        # Process bullets
+        if bullet:
+            section.bullets.append(bullet)
+                
+        if bullets:
+            section.bullets.extend(bullets)
+                
+        return self
+    
+    def add_subsection(self, parent_title: str, title: str, body: str = "", 
+                       bullets: Optional[List[str]] = None) -> 'PomBuilder':
+        """
+        Add a subsection to an existing section, creating the parent if needed
+        
+        Args:
+            parent_title: Title of the parent section
+            title: Title for the new subsection
+            body: Optional body text
+            bullets: Optional list of bullet points
+            
+        Returns:
+            Self for method chaining
+        """
+        # Create parent section if it doesn't exist - auto-vivification
+        if parent_title not in self._sections:
+            self.add_section(parent_title)
+            
+        parent = self._sections[parent_title]
+        subsection = parent.add_subsection(
+            title=title,
+            body=body,
+            bullets=bullets or []
+        )
+        return self
+    
+    def has_section(self, title: str) -> bool:
+        """
+        Check if a section with the given title exists
+        
+        Args:
+            title: Section title to check
+            
+        Returns:
+            True if the section exists, False otherwise
+        """
+        return title in self._sections
+    
+    def get_section(self, title: str) -> Optional[Section]:
+        """
+        Get a section by title
+        
+        Args:
+            title: Section title
+            
+        Returns:
+            Section object or None if not found
+        """
+        return self._sections.get(title)
+    
+    def render_markdown(self) -> str:
+        """Render the POM as markdown"""
+        return self.pom.render_markdown()
+    
+    def render_xml(self) -> str:
+        """Render the POM as XML"""
+        return self.pom.render_xml()
+    
+    def to_dict(self) -> List[Dict[str, Any]]:
+        """Convert the POM to a list of section dictionaries"""
+        return self.pom.to_dict()
+        
+    def to_json(self) -> str:
+        """Convert the POM to a JSON string"""
+        return self.pom.to_json()
+    
+    @classmethod
+    def from_sections(cls, sections: List[Dict[str, Any]]) -> 'PomBuilder':
+        """
+        Create a PomBuilder from a list of section dictionaries
+        
+        Args:
+            sections: List of section definition dictionaries
+            
+        Returns:
+            A new PomBuilder instance with the sections added
+        """
+        builder = cls()
+        builder.pom = PromptObjectModel.from_json(sections)
+        # Rebuild the sections dict
+        for section in builder.pom.sections:
+            if section.title:
+                builder._sections[section.title] = section
+        return builder

signalwire_agents/core/security/__init__.py

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

signalwire_agents/core/security/session_manager.py

@@ -0,0 +1,179 @@
+"""
+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.
+"""
+
+"""
+Session manager for handling call sessions and security tokens
+"""
+
+from typing import Dict, Any, Optional, Tuple
+import secrets
+import time
+from datetime import datetime
+
+
+class CallSession:
+    """
+    Represents a single call session with associated tokens and state
+    """
+    def __init__(self, call_id: str):
+        self.call_id = call_id
+        self.tokens: Dict[str, str] = {}  # function_name -> token
+        self.state = "pending"  # pending, active, expired
+        self.started_at = datetime.now()
+        self.metadata: Dict[str, Any] = {}  # Custom state for the call
+
+
+class SessionManager:
+    """
+    Manages call sessions and their associated security tokens
+    """
+    def __init__(self, token_expiry_secs: int = 600):
+        """
+        Initialize the session manager
+        
+        Args:
+            token_expiry_secs: Seconds until tokens expire (default: 10 minutes)
+        """
+        self._active_calls: Dict[str, CallSession] = {}
+        self.token_expiry_secs = token_expiry_secs
+    
+    def create_session(self, call_id: Optional[str] = None) -> str:
+        """
+        Create a new call session
+        
+        Args:
+            call_id: Optional call ID, generated if not provided
+            
+        Returns:
+            The call_id for the new session
+        """
+        # Generate call_id if not provided
+        if not call_id:
+            call_id = secrets.token_urlsafe(16)
+        
+        # Create new session
+        self._active_calls[call_id] = CallSession(call_id)
+        return call_id
+    
+    def generate_token(self, function_name: str, call_id: str) -> str:
+        """
+        Generate a secure token for a function call
+        
+        Args:
+            function_name: Name of the function to generate a token for
+            call_id: Call session ID
+            
+        Returns:
+            A secure random token
+            
+        Raises:
+            ValueError: If the call session does not exist
+        """
+        if call_id not in self._active_calls:
+            raise ValueError(f"No active session for call_id: {call_id}")
+        
+        token = secrets.token_urlsafe(24)
+        self._active_calls[call_id].tokens[function_name] = token
+        return token
+    
+    def validate_token(self, call_id: str, function_name: str, token: str) -> bool:
+        """
+        Validate a function call token
+        
+        Args:
+            call_id: Call session ID
+            function_name: Name of the function being called
+            token: Token to validate
+            
+        Returns:
+            True if valid, False otherwise
+        """
+        session = self._active_calls.get(call_id)
+        if not session or session.state != "active":
+            return False
+        
+        # Check if token matches and is not expired
+        expected_token = session.tokens.get(function_name)
+        if not expected_token or expected_token != token:
+            return False
+            
+        # Check expiry
+        now = datetime.now()
+        seconds_elapsed = (now - session.started_at).total_seconds()
+        if seconds_elapsed > self.token_expiry_secs:
+            session.state = "expired"
+            return False
+            
+        return True
+    
+    def activate_session(self, call_id: str) -> bool:
+        """
+        Activate a call session (called by startup_hook)
+        
+        Args:
+            call_id: Call session ID
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        session = self._active_calls.get(call_id)
+        if not session:
+            return False
+            
+        session.state = "active"
+        return True
+    
+    def end_session(self, call_id: str) -> bool:
+        """
+        End a call session (called by hangup_hook)
+        
+        Args:
+            call_id: Call session ID
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        if call_id in self._active_calls:
+            del self._active_calls[call_id]
+            return True
+        return False
+    
+    def get_session_metadata(self, call_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get custom metadata for a call session
+        
+        Args:
+            call_id: Call session ID
+            
+        Returns:
+            Metadata dict or None if session not found
+        """
+        session = self._active_calls.get(call_id)
+        if not session:
+            return None
+        return session.metadata
+    
+    def set_session_metadata(self, call_id: str, key: str, value: Any) -> bool:
+        """
+        Set custom metadata for a call session
+        
+        Args:
+            call_id: Call session ID
+            key: Metadata key
+            value: Metadata value
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        session = self._active_calls.get(call_id)
+        if not session:
+            return False
+            
+        session.metadata[key] = value
+        return True

signalwire_agents/core/state/__init__.py

@@ -0,0 +1,17 @@
+"""
+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.
+"""
+
+"""
+State management for SignalWire AI Agents
+"""
+
+from .state_manager import StateManager
+from .file_state_manager import FileStateManager
+
+__all__ = ['StateManager', 'FileStateManager']