signalwire-agents 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

signalwire_agents/core/skill_base.py

@@ -0,0 +1,87 @@
+"""
+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 abc import ABC, abstractmethod
+from typing import List, Dict, Any, TYPE_CHECKING, Optional
+import logging
+
+if TYPE_CHECKING:
+    from signalwire_agents.core.agent_base import AgentBase
+
+class SkillBase(ABC):
+    """Abstract base class for all agent skills"""
+    
+    # Subclasses must define these
+    SKILL_NAME: str = None           # Required: unique identifier
+    SKILL_DESCRIPTION: str = None    # Required: human-readable description
+    SKILL_VERSION: str = "1.0.0"     # Semantic version
+    REQUIRED_PACKAGES: List[str] = [] # Python packages needed
+    REQUIRED_ENV_VARS: List[str] = [] # Environment variables needed
+    
+    def __init__(self, agent: 'AgentBase', params: Optional[Dict[str, Any]] = None):
+        if self.SKILL_NAME is None:
+            raise ValueError(f"{self.__class__.__name__} must define SKILL_NAME")
+        if self.SKILL_DESCRIPTION is None:
+            raise ValueError(f"{self.__class__.__name__} must define SKILL_DESCRIPTION")
+            
+        self.agent = agent
+        self.params = params or {}
+        self.logger = logging.getLogger(f"skill.{self.SKILL_NAME}")
+        
+    @abstractmethod
+    def setup(self) -> bool:
+        """
+        Setup the skill (validate env vars, initialize APIs, etc.)
+        Returns True if setup successful, False otherwise
+        """
+        pass
+        
+    @abstractmethod
+    def register_tools(self) -> None:
+        """Register SWAIG tools with the agent"""
+        pass
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints for this skill"""
+        return []
+        
+    def get_global_data(self) -> Dict[str, Any]:
+        """Return data to add to agent's global context"""
+        return {}
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return []
+        
+    def cleanup(self) -> None:
+        """Cleanup when skill is removed or agent shuts down"""
+        pass
+        
+    def validate_env_vars(self) -> bool:
+        """Check if all required environment variables are set"""
+        import os
+        missing = [var for var in self.REQUIRED_ENV_VARS if not os.getenv(var)]
+        if missing:
+            self.logger.error(f"Missing required environment variables: {missing}")
+            return False
+        return True
+        
+    def validate_packages(self) -> bool:
+        """Check if all required packages are available"""
+        import importlib
+        missing = []
+        for package in self.REQUIRED_PACKAGES:
+            try:
+                importlib.import_module(package)
+            except ImportError:
+                missing.append(package)
+        if missing:
+            self.logger.error(f"Missing required packages: {missing}")
+            return False
+        return True 

signalwire_agents/core/skill_manager.py

@@ -0,0 +1,136 @@
+"""
+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 Dict, List, Type, Any, Optional
+import logging
+from signalwire_agents.core.skill_base import SkillBase
+
+class SkillManager:
+    """Manages loading and lifecycle of agent skills"""
+    
+    def __init__(self, agent):
+        self.agent = agent
+        self.loaded_skills: Dict[str, SkillBase] = {}
+        self.logger = logging.getLogger("skill_manager")
+        
+    def load_skill(self, skill_name: str, skill_class: Type[SkillBase] = None, params: Optional[Dict[str, Any]] = None) -> tuple[bool, str]:
+        """
+        Load and setup a skill by name
+        
+        Args:
+            skill_name: Name of the skill to load
+            skill_class: Optional skill class (if not provided, will try to find it)
+            params: Optional parameters to pass to the skill
+            
+        Returns:
+            tuple: (success, error_message) - error_message is empty string if successful
+        """
+        if skill_name in self.loaded_skills:
+            self.logger.warning(f"Skill '{skill_name}' is already loaded")
+            return True, ""
+            
+        # Get skill class from registry if not provided
+        if skill_class is None:
+            try:
+                from signalwire_agents.skills.registry import skill_registry
+                skill_class = skill_registry.get_skill_class(skill_name)
+                if skill_class is None:
+                    error_msg = f"Skill '{skill_name}' not found in registry"
+                    self.logger.error(error_msg)
+                    return False, error_msg
+            except ImportError:
+                error_msg = f"Skills registry not available. Cannot load skill '{skill_name}'"
+                self.logger.error(error_msg)
+                return False, error_msg
+        
+        try:
+            # Create skill instance with parameters
+            skill_instance = skill_class(self.agent, params)
+            
+            # Validate environment variables with specific error details
+            import os
+            missing_env_vars = [var for var in skill_instance.REQUIRED_ENV_VARS if not os.getenv(var)]
+            if missing_env_vars:
+                error_msg = f"Missing required environment variables: {missing_env_vars}"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Validate packages with specific error details  
+            import importlib
+            missing_packages = []
+            for package in skill_instance.REQUIRED_PACKAGES:
+                try:
+                    importlib.import_module(package)
+                except ImportError:
+                    missing_packages.append(package)
+            if missing_packages:
+                error_msg = f"Missing required packages: {missing_packages}"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Setup the skill
+            if not skill_instance.setup():
+                error_msg = f"Failed to setup skill '{skill_name}'"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Register tools with agent
+            skill_instance.register_tools()
+            
+            # Add hints and global data to agent
+            hints = skill_instance.get_hints()
+            if hints:
+                self.agent.add_hints(hints)
+                
+            global_data = skill_instance.get_global_data()
+            if global_data:
+                self.agent.update_global_data(global_data)
+                
+            # Add prompt sections
+            prompt_sections = skill_instance.get_prompt_sections()
+            for section in prompt_sections:
+                self.agent.prompt_add_section(**section)
+            
+            # Store loaded skill
+            self.loaded_skills[skill_name] = skill_instance
+            self.logger.info(f"Successfully loaded skill '{skill_name}'")
+            return True, ""
+            
+        except Exception as e:
+            error_msg = f"Error loading skill '{skill_name}': {e}"
+            self.logger.error(error_msg)
+            return False, error_msg
+    
+    def unload_skill(self, skill_name: str) -> bool:
+        """Unload a skill and cleanup"""
+        if skill_name not in self.loaded_skills:
+            self.logger.warning(f"Skill '{skill_name}' is not loaded")
+            return False
+            
+        try:
+            skill_instance = self.loaded_skills[skill_name]
+            skill_instance.cleanup()
+            del self.loaded_skills[skill_name]
+            self.logger.info(f"Successfully unloaded skill '{skill_name}'")
+            return True
+        except Exception as e:
+            self.logger.error(f"Error unloading skill '{skill_name}': {e}")
+            return False
+    
+    def list_loaded_skills(self) -> List[str]:
+        """List names of currently loaded skills"""
+        return list(self.loaded_skills.keys())
+    
+    def has_skill(self, skill_name: str) -> bool:
+        """Check if skill is currently loaded"""
+        return skill_name in self.loaded_skills
+    
+    def get_skill(self, skill_name: str) -> Optional[SkillBase]:
+        """Get a loaded skill instance by name"""
+        return self.loaded_skills.get(skill_name) 

signalwire_agents/core/swml_builder.py

@@ -14,7 +14,11 @@ 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 typing import Dict, List, Any, Optional, Union, TypeVar
+try:
+    from typing import Self  # Python 3.11+
+except ImportError:
+    from typing_extensions import Self  # For Python 3.9-3.10
 
 from signalwire_agents.core.swml_service import SWMLService
 

signalwire_agents/prefabs/info_gatherer.py

@@ -9,9 +9,12 @@ See LICENSE file in the project root for full license information.
 
 """
 InfoGathererAgent - Prefab agent for collecting answers to a series of questions
+
+Supports both static (questions provided at init) and dynamic (questions determined 
+by a callback function) configuration modes.
 """
 
-from typing import List, Dict, Any, Optional, Union
+from typing import List, Dict, Any, Optional, Union, Callable
 import json
 
 from signalwire_agents.core.agent_base import AgentBase
@@ -39,7 +42,7 @@ class InfoGathererAgent(AgentBase):
     
     def __init__(
         self,
-        questions: List[Dict[str, str]],
+        questions: Optional[List[Dict[str, str]]] = None,
         name: str = "info_gatherer", 
         route: str = "/info_gatherer",
         enable_state_tracking: bool = True,  # Enable state tracking by default for InfoGatherer
@@ -49,7 +52,8 @@ class InfoGathererAgent(AgentBase):
         Initialize an information gathering agent
         
         Args:
-            questions: List of questions to ask, each with:
+            questions: Optional list of questions to ask. If None, questions will be determined
+                      dynamically via a callback function. Each question dict should have:
                 - key_name: Identifier for storing the answer
                 - question_text: The actual question to ask the user
                 - confirm: (Optional) If set to True, the agent will confirm the answer before submitting
@@ -67,39 +71,84 @@ class InfoGathererAgent(AgentBase):
             **kwargs
         )
         
-        # Validate questions format
-        self._validate_questions(questions)
-        
-        # Set up global data with questions and initial state
-        self.set_global_data({
-            "questions": questions,
-            "question_index": 0,
-            "answers": []
-        })
+        # Store whether we're in static or dynamic mode
+        self._static_questions = questions
+        self._question_callback = None
         
-        # Build a minimal prompt
-        self._build_prompt()
+        if questions is not None:
+            # Static mode: validate questions and set up immediately
+            self._validate_questions(questions)
+            self.set_global_data({
+                "questions": questions,
+                "question_index": 0,
+                "answers": []
+            })
+            # Build prompt for static configuration
+            self._build_prompt()
+        else:
+            # Dynamic mode: questions will be set up via callback in on_swml_request
+            # Build a generic prompt
+            self._build_prompt("dynamic")
         
         # Configure additional agent settings
         self._configure_agent_settings()
     
+    def set_question_callback(self, callback: Callable[[dict, dict, dict], List[Dict[str, str]]]):
+        """
+        Set a callback function for dynamic question configuration
+        
+        Args:
+            callback: Function that takes (query_params, body_params, headers) and returns
+                     a list of question dictionaries. Each question dict should have:
+                     - key_name: Identifier for storing the answer
+                     - question_text: The actual question to ask the user
+                     - confirm: (Optional) If True, agent will confirm answer before submitting
+                     
+        Example:
+            def my_question_callback(query_params, body_params, headers):
+                question_set = query_params.get('set', 'default')
+                if question_set == 'support':
+                    return [
+                        {"key_name": "name", "question_text": "What is your name?"},
+                        {"key_name": "issue", "question_text": "What's the issue?"}
+                    ]
+                else:
+                    return [{"key_name": "name", "question_text": "What is your name?"}]
+            
+            agent.set_question_callback(my_question_callback)
+        """
+        self._question_callback = callback
+    
     def _validate_questions(self, questions):
         """Validate that questions are in the correct format"""
         if not questions:
             raise ValueError("At least one question is required")
             
+        if not isinstance(questions, list):
+            raise ValueError("Questions must be a list")
+            
         for i, question in enumerate(questions):
+            if not isinstance(question, dict):
+                raise ValueError(f"Question {i+1} must be a dictionary")
             if "key_name" not in question:
                 raise ValueError(f"Question {i+1} is missing 'key_name' field")
             if "question_text" not in question:
                 raise ValueError(f"Question {i+1} is missing 'question_text' field")
     
-    def _build_prompt(self):
+    def _build_prompt(self, mode="static"):
         """Build a minimal prompt with just the objective"""
-        self.prompt_add_section(
-            "Objective", 
-            body="Your role is to get answers to a series of questions. Begin by asking the user if they are ready to answer some questions. If they confirm they are ready, call the start_questions function to begin the process."
-        )
+        if mode == "dynamic":
+            # Generic prompt for dynamic mode - will be customized later
+            self.prompt_add_section(
+                "Objective", 
+                body="Your role is to gather information by asking questions. Begin by asking the user if they are ready to answer some questions. If they confirm they are ready, call the start_questions function to begin the process."
+            )
+        else:
+            # Original static prompt
+            self.prompt_add_section(
+                "Objective", 
+                body="Your role is to get answers to a series of questions. Begin by asking the user if they are ready to answer some questions. If they confirm they are ready, call the start_questions function to begin the process."
+            )
     
     def _configure_agent_settings(self):
         """Configure additional agent settings"""
@@ -109,6 +158,77 @@ class InfoGathererAgent(AgentBase):
             "speech_event_timeout": 1000  # Slightly longer for thoughtful responses
         })
     
+    def on_swml_request(self, request_data=None, callback_path=None, request=None):
+        """
+        Handle dynamic configuration using the callback function
+        
+        This method is called when SWML is requested and allows us to configure
+        the agent just-in-time using the provided callback.
+        """
+        # Only process if we're in dynamic mode (no static questions)
+        if self._static_questions is not None:
+            return None
+            
+        # If no callback is set, provide a basic fallback
+        if self._question_callback is None:
+            fallback_questions = [
+                {"key_name": "name", "question_text": "What is your name?"},
+                {"key_name": "message", "question_text": "How can I help you today?"}
+            ]
+            return {
+                "global_data": {
+                    "questions": fallback_questions,
+                    "question_index": 0,
+                    "answers": []
+                }
+            }
+        
+        # Extract request information for callback
+        query_params = {}
+        body_params = request_data or {}
+        headers = {}
+        
+        if request and hasattr(request, 'query_params'):
+            query_params = dict(request.query_params)
+        
+        if request and hasattr(request, 'headers'):
+            headers = dict(request.headers)
+        
+        try:
+            # Call the user-provided callback to get questions
+            print(f"Calling question callback with query_params: {query_params}")
+            questions = self._question_callback(query_params, body_params, headers)
+            print(f"Callback returned {len(questions)} questions")
+            
+            # Validate the returned questions
+            self._validate_questions(questions)
+            
+            # Return global data modifications
+            return {
+                "global_data": {
+                    "questions": questions,
+                    "question_index": 0,
+                    "answers": []
+                }
+            }
+            
+        except Exception as e:
+            # Log error and fall back to basic questions
+            print(f"Error in question callback: {e}")
+            fallback_questions = [
+                {"key_name": "name", "question_text": "What is your name?"},
+                {"key_name": "message", "question_text": "How can I help you today?"}
+            ]
+            return {
+                "global_data": {
+                    "questions": fallback_questions,
+                    "question_index": 0,
+                    "answers": []
+                }
+            }
+    
+
+    
     def _generate_question_instruction(self, question_text: str, needs_confirmation: bool, is_first_question: bool = False) -> str:
         """
         Generate the instruction text for asking a question
@@ -239,13 +359,11 @@ class InfoGathererAgent(AgentBase):
             # Create response with the global data update and next question
             result = SwaigFunctionResult(instruction)
             
-            # Add actions to update global data
-            result.add_actions([
-                {"set_global_data": {
-                    "answers": new_answers,
-                    "question_index": new_question_index
-                }}
-            ])
+            # Use the helper method to update global data
+            result.update_global_data({
+                "answers": new_answers,
+                "question_index": new_question_index
+            })
             
             return result
         else:
@@ -254,13 +372,11 @@ class InfoGathererAgent(AgentBase):
                 "Thank you! All questions have been answered. You can now summarize the information collected or ask if there's anything else the user would like to discuss."
             )
             
-            # Add actions to update global data
-            result.add_actions([
-                {"set_global_data": {
-                    "answers": new_answers,
-                    "question_index": new_question_index
-                }}
-            ])
+            # Use the helper method to update global data
+            result.update_global_data({
+                "answers": new_answers,
+                "question_index": new_question_index
+            })
             
             return result
 

signalwire_agents/prefabs/receptionist.py

@@ -40,7 +40,7 @@ class ReceptionistAgent(AgentBase):
         name: str = "receptionist", 
         route: str = "/receptionist",
         greeting: str = "Thank you for calling. How can I help you today?",
-        voice: str = "elevenlabs.josh",
+        voice: str = "rime.spore",
         enable_state_tracking: bool = True,  # Enable state tracking by default
         **kwargs
     ):
@@ -261,28 +261,20 @@ class ReceptionistAgent(AgentBase):
         # Get transfer number
         transfer_number = department.get("number", "")
         
-        # Create result with transfer SWML
-        result = SwaigFunctionResult(f"I'll transfer you to our {department_name} department now. Thank you for calling, {name}!")
+        # Create result with transfer using the connect helper method
+        # post_process=True allows the AI to speak the response before executing the transfer
+        result = SwaigFunctionResult(
+            f"I'll transfer you to our {department_name} department now. Thank you for calling, {name}!",
+            post_process=True
+        )
         
-        # Add the SWML to execute the transfer
-                    # Add actions to update global data
-        result.add_actions([
-            {
-                "SWML": {
-                    "sections": {
-                        "main": [
-                            {
-                                "connect": {
-                                    "to": transfer_number
-                                }
-                            }
-                        ]
-                    },
-                    "version": "1.0.0"
-                },
-                "transfer": "true"
-            }
-        ])
+        # Use the connect helper instead of manually constructing SWML
+        # final=True means this is a permanent transfer (call exits the agent)
+        result.connect(transfer_number, final=True)
+        
+        # Alternative: Immediate transfer without AI speaking (faster but less friendly)
+        # result = SwaigFunctionResult()  # No response text needed
+        # result.connect(transfer_number, final=True)  # Executes immediately from function call
         
         return result
         

signalwire_agents/skills/__init__.py

@@ -0,0 +1,14 @@
+"""
+SignalWire Agent Skills Package
+
+This package contains built-in skills for SignalWire agents.
+Skills are automatically discovered from subdirectories.
+"""
+
+# Import the registry to make it available
+from .registry import skill_registry
+
+# Trigger skill discovery on import
+skill_registry.discover_skills()
+
+__all__ = ["skill_registry"] 

signalwire_agents/skills/datetime/__init__.py

@@ -0,0 +1 @@
+"""DateTime Skill for SignalWire Agents""" 

signalwire_agents/skills/datetime/skill.py

@@ -0,0 +1,109 @@
+"""
+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 datetime import datetime, timezone
+import pytz
+from typing import List, Dict, Any
+
+from signalwire_agents.core.skill_base import SkillBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+class DateTimeSkill(SkillBase):
+    """Provides current date, time, and timezone information"""
+    
+    SKILL_NAME = "datetime"
+    SKILL_DESCRIPTION = "Get current date, time, and timezone information"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = ["pytz"]
+    REQUIRED_ENV_VARS = []
+    
+    def setup(self) -> bool:
+        """Setup the datetime skill"""
+        return self.validate_packages()
+        
+    def register_tools(self) -> None:
+        """Register datetime tools with the agent"""
+        
+        self.agent.define_tool(
+            name="get_current_time",
+            description="Get the current time, optionally in a specific timezone",
+            parameters={
+                "timezone": {
+                    "type": "string",
+                    "description": "Timezone name (e.g., 'America/New_York', 'Europe/London'). Defaults to UTC."
+                }
+            },
+            handler=self._get_time_handler
+        )
+        
+        self.agent.define_tool(
+            name="get_current_date",
+            description="Get the current date",
+            parameters={
+                "timezone": {
+                    "type": "string", 
+                    "description": "Timezone name for the date. Defaults to UTC."
+                }
+            },
+            handler=self._get_date_handler
+        )
+        
+    def _get_time_handler(self, args, raw_data):
+        """Handler for get_current_time tool"""
+        timezone_name = args.get("timezone", "UTC")
+        
+        try:
+            if timezone_name.upper() == "UTC":
+                tz = timezone.utc
+            else:
+                tz = pytz.timezone(timezone_name)
+                
+            now = datetime.now(tz)
+            time_str = now.strftime("%I:%M:%S %p %Z")
+            
+            return SwaigFunctionResult(f"The current time is {time_str}")
+            
+        except Exception as e:
+            return SwaigFunctionResult(f"Error getting time: {str(e)}")
+    
+    def _get_date_handler(self, args, raw_data):
+        """Handler for get_current_date tool"""
+        timezone_name = args.get("timezone", "UTC")
+        
+        try:
+            if timezone_name.upper() == "UTC":
+                tz = timezone.utc
+            else:
+                tz = pytz.timezone(timezone_name)
+                
+            now = datetime.now(tz)
+            date_str = now.strftime("%A, %B %d, %Y")
+            
+            return SwaigFunctionResult(f"Today's date is {date_str}")
+            
+        except Exception as e:
+            return SwaigFunctionResult(f"Error getting date: {str(e)}")
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        return ["time", "date", "today", "now", "current", "timezone"]
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return [
+            {
+                "title": "Date and Time Information", 
+                "body": "You can provide current date and time information.",
+                "bullets": [
+                    "Use get_current_time to tell users what time it is",
+                    "Use get_current_date to tell users today's date",
+                    "Both tools support different timezones"
+                ]
+            }
+        ] 

signalwire_agents/skills/math/__init__.py

@@ -0,0 +1 @@
+"""Math Skill for SignalWire Agents"""