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

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-0.1.7.dist-info → signalwire_agents-0.1.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.7
+Version: 0.1.8
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
 Project-URL: Homepage, https://github.com/signalwire/signalwire-ai-agents
@@ -35,6 +35,7 @@ A Python SDK for creating, hosting, and securing SignalWire AI agents as microse
 - **Self-Contained Agents**: Each agent is both a web app and an AI persona
 - **Prompt Object Model**: Structured prompt composition using POM
 - **SWAIG Integration**: Easily define and handle AI tools/functions
+- **Dynamic Configuration**: Configure agents per-request for multi-tenant apps and personalization
 - **Custom Routing**: Dynamic request handling for different paths and content
 - **SIP Integration**: Route SIP calls to agents based on SIP usernames
 - **Security Built-In**: Session management, function-specific security tokens, and basic auth
@@ -165,6 +166,73 @@ Available prefabs include:
 - `FAQBotAgent`: Answers questions based on a knowledge base
 - `ConciergeAgent`: Routes users to specialized agents
 - `SurveyAgent`: Conducts structured surveys with questions and rating scales
+- `ReceptionistAgent`: Greets callers and transfers them to appropriate departments
+
+## Dynamic Agent Configuration
+
+Configure agents dynamically based on request parameters for multi-tenant applications, A/B testing, and personalization.
+
+### Static vs Dynamic Configuration
+
+- **Static**: Agent configured once at startup (traditional approach)
+- **Dynamic**: Agent configured fresh for each request based on parameters
+
+### Basic Example
+
+```python
+from signalwire_agents import AgentBase
+
+class DynamicAgent(AgentBase):
+    def __init__(self):
+        super().__init__(name="dynamic-agent", route="/dynamic")
+        
+        # Set up dynamic configuration callback
+        self.set_dynamic_config_callback(self.configure_per_request)
+    
+    def configure_per_request(self, query_params, body_params, headers, agent):
+        """Configure agent based on request parameters"""
+        
+        # Extract parameters from request
+        tier = query_params.get('tier', 'standard')
+        language = query_params.get('language', 'en')
+        customer_id = query_params.get('customer_id')
+        
+        # Configure voice and language
+        if language == 'es':
+            agent.add_language("Spanish", "es-ES", "rime.spore:mistv2")
+        else:
+            agent.add_language("English", "en-US", "rime.spore:mistv2")
+        
+        # Configure based on service tier
+        if tier == 'premium':
+            agent.set_params({"end_of_speech_timeout": 300})  # Faster response
+            agent.prompt_add_section("Service Level", "You provide premium support.")
+        else:
+            agent.set_params({"end_of_speech_timeout": 500})  # Standard response
+            agent.prompt_add_section("Service Level", "You provide standard support.")
+        
+        # Personalize with customer data
+        global_data = {"tier": tier, "language": language}
+        if customer_id:
+            global_data["customer_id"] = customer_id
+        agent.set_global_data(global_data)
+
+# Usage examples:
+# curl "http://localhost:3000/dynamic?tier=premium&language=es&customer_id=123"
+# curl "http://localhost:3000/dynamic?tier=standard&language=en"
+```
+
+### Use Cases
+
+- **Multi-tenant SaaS**: Different configurations per customer/organization
+- **A/B Testing**: Test different agent behaviors with different user groups
+- **Personalization**: Customize voice, prompts, and behavior per user
+- **Localization**: Language and cultural adaptation based on user location
+- **Dynamic Pricing**: Adjust features and capabilities based on subscription tiers
+
+The `EphemeralAgentConfig` object provides all the same familiar methods as `AgentBase` (like `add_language()`, `prompt_add_section()`, `set_global_data()`) but applies them per-request instead of at startup.
+
+For detailed documentation and advanced examples, see the [Agent Guide](docs/agent_guide.md#dynamic-agent-configuration).
 
 ## Configuration
 
@@ -189,7 +257,7 @@ To enable HTTPS directly (without a reverse proxy), set `SWML_SSL_ENABLED` to "t
 
 The package includes comprehensive documentation in the `docs/` directory:
 
-- [Agent Guide](docs/agent_guide.md) - Detailed guide to creating and customizing agents
+- [Agent Guide](docs/agent_guide.md) - Detailed guide to creating and customizing agents, including dynamic configuration
 - [Architecture](docs/architecture.md) - Overview of the SDK architecture and core concepts
 - [SWML Service Guide](docs/swml_service_guide.md) - Guide to the underlying SWML service
 

{signalwire_agents-0.1.7.dist-info → signalwire_agents-0.1.8.dist-info}/RECORD

@@ -1,12 +1,12 @@
-signalwire_agents/__init__.py,sha256=WMXWZxEE3QuDgEKy6MBcL6hxdSDA3_gFd2XAQYmEwMg,800
+signalwire_agents/__init__.py,sha256=0epKP_LHIiz6nCNxn-hQvDfdYGfKvTxpu9oe-OThvEc,800
 signalwire_agents/agent_server.py,sha256=se_YzOQE5UUoRUKCbTnOg9qr4G3qN7iVuQLutwXEwFU,12850
 signalwire_agents/schema.json,sha256=M8Mn6pQda2P9jhbmkALrLr1wt-fRuhYRqdmEi9Rbhqk,178075
 signalwire_agents/core/__init__.py,sha256=mVDLbpq1pg_WwiqsQR28NNZwJ6-VUXFIfg-vN7pk0ew,806
-signalwire_agents/core/agent_base.py,sha256=D8ZiRRYDxF24cOjXoT253SWODEvmDZ-l8kwWMnr18Bw,103118
-signalwire_agents/core/function_result.py,sha256=vD8eBDJBQNNnss1jShadfogCZw_prODB6eBkTuVgZKA,3538
+signalwire_agents/core/agent_base.py,sha256=GLnjisSPNEqJMG4-eb3TS_fBtNLPbvgjd1cTVWxqxJ4,112500
+signalwire_agents/core/function_result.py,sha256=OXzm4GOvA6TKbzZFsdz3iBU5vQs9LXxsmQue7zWVolE,43538
 signalwire_agents/core/pom_builder.py,sha256=ywuiIfP8BeLBPo_G4X1teZlG6zTCMkW71CZnmyoDTAQ,6636
 signalwire_agents/core/swaig_function.py,sha256=WoHGQuCmU9L9k39pttRunmfRtIa_PnNRn9W0Xq3MfIk,6316
-signalwire_agents/core/swml_builder.py,sha256=Y_eHThVVso-_Hz4f73eEuu3HJstsM9PtBl-36GvAXhI,6594
+signalwire_agents/core/swml_builder.py,sha256=Q1ikU9pedgjW888mjbqDFv-jMDvDZ-tZgfyMfu4qQN0,6719
 signalwire_agents/core/swml_handler.py,sha256=KvphI_YY47VWGVXaix_N3SuQSyygHEUr9We6xESQK44,7002
 signalwire_agents/core/swml_renderer.py,sha256=iobMWWoBR7dkHndI3Qlwf4C0fg2p7DmAU2Rb7ZmmLhA,13891
 signalwire_agents/core/swml_service.py,sha256=4zTtpIKDtL59MzKgkBdpPmBCT6s1wVIikWEzZ1hqnyc,49309
@@ -18,17 +18,17 @@ signalwire_agents/core/state/state_manager.py,sha256=76B4mDutMb826dK4c_IJhOXH09B
 signalwire_agents/prefabs/__init__.py,sha256=MW11J63XH7KxF2MWguRsMFM9iqMWexaEO9ynDPL_PDM,715
 signalwire_agents/prefabs/concierge.py,sha256=FQxSUBAVH2ECtNs4GGa3f0EPiOrAKaz14h7byNFy5K8,10106
 signalwire_agents/prefabs/faq_bot.py,sha256=NrUn5AGmtdzYTyxTHPt8BZ14ZN1sh4xKA2SVQUlfPPQ,10834
-signalwire_agents/prefabs/info_gatherer.py,sha256=NkRc6FSaslDMhvF3a2rAvTqD9V8t17OV6_awwtQPPRM,10219
-signalwire_agents/prefabs/receptionist.py,sha256=Bpb_okc5MnxEdrrO-PkXXo5Zp9awgyt4bvYJOahSbYE,10555
+signalwire_agents/prefabs/info_gatherer.py,sha256=dr9UUgNGX7MIKdCMth3jDVLf6OrHov5G6_zIuNvnrOY,15468
+signalwire_agents/prefabs/receptionist.py,sha256=8EyQ6M0Egs3g7KKWukHFiO9UPoVUxT4MLkvyT3V8o64,10585
 signalwire_agents/prefabs/survey.py,sha256=IIIQfgvMlfVNjEEEdWUn4lAJqVsCDlBsIAkOJ1ckyAE,14796
 signalwire_agents/utils/__init__.py,sha256=4Mr7baQ_xR_hfJ72YxQRAT_GFa663YjFX_PumJ35Xds,191
 signalwire_agents/utils/pom_utils.py,sha256=4Mr7baQ_xR_hfJ72YxQRAT_GFa663YjFX_PumJ35Xds,191
 signalwire_agents/utils/schema_utils.py,sha256=LvFCFvJTQk_xYK0B-NXbkXKEF7Zmv-LqpV_vfpPnOb4,13473
 signalwire_agents/utils/token_generators.py,sha256=4Mr7baQ_xR_hfJ72YxQRAT_GFa663YjFX_PumJ35Xds,191
 signalwire_agents/utils/validators.py,sha256=4Mr7baQ_xR_hfJ72YxQRAT_GFa663YjFX_PumJ35Xds,191
-signalwire_agents-0.1.7.data/data/schema.json,sha256=M8Mn6pQda2P9jhbmkALrLr1wt-fRuhYRqdmEi9Rbhqk,178075
-signalwire_agents-0.1.7.dist-info/licenses/LICENSE,sha256=NYvAsB-rTcSvG9cqHt9EUHAWLiA9YzM4Qfz-mPdvDR0,1067
-signalwire_agents-0.1.7.dist-info/METADATA,sha256=rlAExY7ealJ5HzZIx-IOHnH9MZn3zfXcuISBgnIRJbw,7486
-signalwire_agents-0.1.7.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
-signalwire_agents-0.1.7.dist-info/top_level.txt,sha256=kDGS6ZYv84K9P5Kyg9_S8P_pbUXoHkso0On_DB5bbWc,18
-signalwire_agents-0.1.7.dist-info/RECORD,,
+signalwire_agents-0.1.8.data/data/schema.json,sha256=M8Mn6pQda2P9jhbmkALrLr1wt-fRuhYRqdmEi9Rbhqk,178075
+signalwire_agents-0.1.8.dist-info/licenses/LICENSE,sha256=NYvAsB-rTcSvG9cqHt9EUHAWLiA9YzM4Qfz-mPdvDR0,1067
+signalwire_agents-0.1.8.dist-info/METADATA,sha256=kTDyXqy-gZ6JMfVCr6EIsj-EB2hKtgN5wxp1VPBnNek,10507
+signalwire_agents-0.1.8.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+signalwire_agents-0.1.8.dist-info/top_level.txt,sha256=kDGS6ZYv84K9P5Kyg9_S8P_pbUXoHkso0On_DB5bbWc,18
+signalwire_agents-0.1.8.dist-info/RECORD,,

{signalwire_agents-0.1.7.dist-info → signalwire_agents-0.1.8.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.7.1)
+Generator: setuptools (80.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any