signalwire-agents 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

signalwire_agents/core/function_result.py

@@ -188,7 +188,7 @@ class SwaigFunctionResult:
         self.action.append(swml_action)
         return self
 
-    def swml_transfer(self, dest: str, ai_response: str) -> 'SwaigFunctionResult':
+    def swml_transfer(self, dest: str, ai_response: str, final: bool = True) -> 'SwaigFunctionResult':
         """
         Add a SWML transfer action with AI response setup for when transfer completes.
         
@@ -202,22 +202,28 @@ class SwaigFunctionResult:
         Args:
             dest: Destination URL for the transfer (SWML endpoint, SIP address, etc.)
             ai_response: Message the AI should say when transfer completes and control returns
+            final: Whether this is a permanent transfer (True) or temporary (False).
+                  Defaults to True for permanent transfers (same as connect method).
                         
         Returns:
             Self for method chaining
             
         Example:
-            # Transfer with post-processing (speak first, then transfer)
+            # Permanent transfer (default)
             result = (
                 SwaigFunctionResult("I'm transferring you to support", post_process=True)
                 .swml_transfer(
                     "https://support.example.com/swml",
-                    "The support call is complete. How else can I help?"
+                    "Goodbye!"  # Won't be used since final=True by default
                 )
             )
             
-            # Or enable post-processing with method chaining
-            result.swml_transfer(dest, ai_response).set_post_process(True)
+            # Temporary transfer with return
+            result.swml_transfer(
+                dest, 
+                "The support call is complete. How else can I help?", 
+                final=False
+            )
         """
         # Create the SWML action structure directly
         swml_action = {
@@ -229,7 +235,8 @@ class SwaigFunctionResult:
                         {"transfer": {"dest": dest}}
                     ]
                 }
-            }
+            },
+            "transfer": str(final).lower()  # Convert boolean to "true"/"false" string
         }
         
         # Add to actions list directly
@@ -251,8 +258,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"set_global_data": data}
-        return self.add_action("set_global_data", action)
+        return self.add_action("set_global_data", data)
 
     def execute_swml(self, swml_content, transfer: bool = False) -> 'SwaigFunctionResult':
         """
@@ -294,8 +300,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"hangup": True}
-        return self.add_action("hangup", action)
+        return self.add_action("hangup", True)
 
     def hold(self, timeout: int = 300) -> 'SwaigFunctionResult':
         """
@@ -309,8 +314,7 @@ class SwaigFunctionResult:
         """
         # Clamp timeout to valid range
         timeout = max(0, min(timeout, 900))
-        action = {"hold": timeout}
-        return self.add_action("hold", action)
+        return self.add_action("hold", timeout)
 
     def wait_for_user(self, enabled: Optional[bool] = None, timeout: Optional[int] = None, answer_first: bool = False) -> 'SwaigFunctionResult':
         """
@@ -333,8 +337,7 @@ class SwaigFunctionResult:
         else:
             wait_value = True
             
-        action = {"wait_for_user": wait_value}
-        return self.add_action("wait_for_user", action)
+        return self.add_action("wait_for_user", wait_value)
 
     def stop(self) -> 'SwaigFunctionResult':
         """
@@ -343,8 +346,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"stop": True}
-        return self.add_action("stop", action)
+        return self.add_action("stop", True)
 
     def say(self, text: str) -> 'SwaigFunctionResult':
         """
@@ -356,8 +358,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"say": text}
-        return self.add_action("say", action)
+        return self.add_action("say", text)
 
     def play_background_file(self, filename: str, wait: bool = False) -> 'SwaigFunctionResult':
         """
@@ -395,8 +396,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"end_of_speech_timeout": milliseconds}
-        return self.add_action("end_of_speech_timeout", action)
+        return self.add_action("end_of_speech_timeout", milliseconds)
 
     def set_speech_event_timeout(self, milliseconds: int) -> 'SwaigFunctionResult':
         """
@@ -409,8 +409,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"speech_event_timeout": milliseconds}
-        return self.add_action("speech_event_timeout", action)
+        return self.add_action("speech_event_timeout", milliseconds)
 
     def remove_global_data(self, keys: Union[str, List[str]]) -> 'SwaigFunctionResult':
         """
@@ -422,8 +421,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"unset_global_data": keys}
-        return self.add_action("unset_global_data", action)
+        return self.add_action("unset_global_data", keys)
 
     def set_metadata(self, data: Dict[str, Any]) -> 'SwaigFunctionResult':
         """
@@ -435,8 +433,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"set_meta_data": data}
-        return self.add_action("set_meta_data", action)
+        return self.add_action("set_meta_data", data)
 
     def remove_metadata(self, keys: Union[str, List[str]]) -> 'SwaigFunctionResult':
         """
@@ -448,8 +445,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"unset_meta_data": keys}
-        return self.add_action("unset_meta_data", action)
+        return self.add_action("unset_meta_data", keys)
 
     def toggle_functions(self, function_toggles: List[Dict[str, Any]]) -> 'SwaigFunctionResult':
         """
@@ -461,8 +457,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"toggle_functions": function_toggles}
-        return self.add_action("toggle_functions", action)
+        return self.add_action("toggle_functions", function_toggles)
 
     def enable_functions_on_timeout(self, enabled: bool = True) -> 'SwaigFunctionResult':
         """
@@ -474,8 +469,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"functions_on_speaker_timeout": enabled}
-        return self.add_action("functions_on_speaker_timeout", action)
+        return self.add_action("functions_on_speaker_timeout", enabled)
 
     def enable_extensive_data(self, enabled: bool = True) -> 'SwaigFunctionResult':
         """
@@ -488,8 +482,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"extensive_data": enabled}
-        return self.add_action("extensive_data", action)
+        return self.add_action("extensive_data", enabled)
 
     def update_settings(self, settings: Dict[str, Any]) -> 'SwaigFunctionResult':
         """
@@ -510,8 +503,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"settings": settings}
-        return self.add_action("settings", action)
+        return self.add_action("settings", settings)
 
     def switch_context(self, system_prompt: Optional[str] = None, user_prompt: Optional[str] = None, 
                       consolidate: bool = False, full_reset: bool = False) -> 'SwaigFunctionResult':
@@ -529,7 +521,7 @@ class SwaigFunctionResult:
         """
         if system_prompt and not user_prompt and not consolidate and not full_reset:
             # Simple string context switch
-            action = {"context_switch": system_prompt}
+            return self.add_action("context_switch", system_prompt)
         else:
             # Advanced object context switch
             context_data = {}
@@ -541,9 +533,7 @@ class SwaigFunctionResult:
                 context_data["consolidate"] = True
             if full_reset:
                 context_data["full_reset"] = True
-            action = {"context_switch": context_data}
-            
-        return self.add_action("context_switch", action)
+            return self.add_action("context_switch", context_data)
 
     def simulate_user_input(self, text: str) -> 'SwaigFunctionResult':
         """
@@ -555,8 +545,7 @@ class SwaigFunctionResult:
         Returns:
             self for method chaining
         """
-        action = {"user_input": text}
-        return self.add_action("user_input", action)
+        return self.add_action("user_input", text)
 
     def send_sms(self, to_number: str, from_number: str, body: Optional[str] = None, 
                 media: Optional[List[str]] = None, tags: Optional[List[str]] = None, 

signalwire_agents/core/mixins/__init__.py

@@ -0,0 +1,28 @@
+"""
+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 .prompt_mixin import PromptMixin
+from .tool_mixin import ToolMixin
+from .web_mixin import WebMixin
+from .auth_mixin import AuthMixin
+from .skill_mixin import SkillMixin
+from .ai_config_mixin import AIConfigMixin
+from .serverless_mixin import ServerlessMixin
+from .state_mixin import StateMixin
+
+__all__ = [
+    'PromptMixin',
+    'ToolMixin',
+    'WebMixin',
+    'AuthMixin',
+    'SkillMixin',
+    'AIConfigMixin',
+    'ServerlessMixin',
+    'StateMixin'
+]

signalwire_agents/core/mixins/ai_config_mixin.py

@@ -0,0 +1,373 @@
+"""
+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 List, Dict, Any, Optional
+
+
+class AIConfigMixin:
+    """
+    Mixin class containing all AI configuration methods for AgentBase
+    """
+    
+    def add_hint(self, hint: str) -> 'AgentBase':
+        """
+        Add a simple string hint to help the AI agent understand certain words better
+        
+        Args:
+            hint: The hint string to add
+            
+        Returns:
+            Self for method chaining
+        """
+        if isinstance(hint, str) and hint:
+            self._hints.append(hint)
+        return self
+
+    def add_hints(self, hints: List[str]) -> 'AgentBase':
+        """
+        Add multiple string hints
+        
+        Args:
+            hints: List of hint strings
+            
+        Returns:
+            Self for method chaining
+        """
+        if hints and isinstance(hints, list):
+            for hint in hints:
+                if isinstance(hint, str) and hint:
+                    self._hints.append(hint)
+        return self
+
+    def add_pattern_hint(self, 
+                         hint: str, 
+                         pattern: str, 
+                         replace: str, 
+                         ignore_case: bool = False) -> 'AgentBase':
+        """
+        Add a complex hint with pattern matching
+        
+        Args:
+            hint: The hint to match
+            pattern: Regular expression pattern
+            replace: Text to replace the hint with
+            ignore_case: Whether to ignore case when matching
+            
+        Returns:
+            Self for method chaining
+        """
+        if hint and pattern and replace:
+            self._hints.append({
+                "hint": hint,
+                "pattern": pattern,
+                "replace": replace,
+                "ignore_case": ignore_case
+            })
+        return self
+
+    def add_language(self, 
+                     name: str, 
+                     code: str, 
+                     voice: str,
+                     speech_fillers: Optional[List[str]] = None,
+                     function_fillers: Optional[List[str]] = None,
+                     engine: Optional[str] = None,
+                     model: Optional[str] = None) -> 'AgentBase':
+        """
+        Add a language configuration to support multilingual conversations
+        
+        Args:
+            name: Name of the language (e.g., "English", "French")
+            code: Language code (e.g., "en-US", "fr-FR")
+            voice: TTS voice to use. Can be a simple name (e.g., "en-US-Neural2-F") 
+                  or a combined format "engine.voice:model" (e.g., "elevenlabs.josh:eleven_turbo_v2_5")
+            speech_fillers: Optional list of filler phrases for natural speech
+            function_fillers: Optional list of filler phrases during function calls
+            engine: Optional explicit engine name (e.g., "elevenlabs", "rime")
+            model: Optional explicit model name (e.g., "eleven_turbo_v2_5", "arcana")
+            
+        Returns:
+            Self for method chaining
+            
+        Examples:
+            # Simple voice name
+            agent.add_language("English", "en-US", "en-US-Neural2-F")
+            
+            # Explicit parameters
+            agent.add_language("English", "en-US", "josh", engine="elevenlabs", model="eleven_turbo_v2_5")
+            
+            # Combined format
+            agent.add_language("English", "en-US", "elevenlabs.josh:eleven_turbo_v2_5")
+        """
+        language = {
+            "name": name,
+            "code": code
+        }
+        
+        # Handle voice formatting (either explicit params or combined string)
+        if engine or model:
+            # Use explicit parameters if provided
+            language["voice"] = voice
+            if engine:
+                language["engine"] = engine
+            if model:
+                language["model"] = model
+        elif "." in voice and ":" in voice:
+            # Parse combined string format: "engine.voice:model"
+            try:
+                engine_voice, model_part = voice.split(":", 1)
+                engine_part, voice_part = engine_voice.split(".", 1)
+                
+                language["voice"] = voice_part
+                language["engine"] = engine_part
+                language["model"] = model_part
+            except ValueError:
+                # If parsing fails, use the voice string as-is
+                language["voice"] = voice
+        else:
+            # Simple voice string
+            language["voice"] = voice
+        
+        # Add fillers if provided
+        if speech_fillers and function_fillers:
+            language["speech_fillers"] = speech_fillers
+            language["function_fillers"] = function_fillers
+        elif speech_fillers or function_fillers:
+            # If only one type of fillers is provided, use the deprecated "fillers" field
+            fillers = speech_fillers or function_fillers
+            language["fillers"] = fillers
+        
+        self._languages.append(language)
+        return self
+
+    def set_languages(self, languages: List[Dict[str, Any]]) -> 'AgentBase':
+        """
+        Set all language configurations at once
+        
+        Args:
+            languages: List of language configuration dictionaries
+            
+        Returns:
+            Self for method chaining
+        """
+        if languages and isinstance(languages, list):
+            self._languages = languages
+        return self
+
+    def add_pronunciation(self, 
+                         replace: str, 
+                         with_text: str, 
+                         ignore_case: bool = False) -> 'AgentBase':
+        """
+        Add a pronunciation rule to help the AI speak certain words correctly
+        
+        Args:
+            replace: The expression to replace
+            with_text: The phonetic spelling to use instead
+            ignore_case: Whether to ignore case when matching
+            
+        Returns:
+            Self for method chaining
+        """
+        if replace and with_text:
+            rule = {
+                "replace": replace,
+                "with": with_text
+            }
+            if ignore_case:
+                rule["ignore_case"] = True
+            
+            self._pronounce.append(rule)
+        return self
+
+    def set_pronunciations(self, pronunciations: List[Dict[str, Any]]) -> 'AgentBase':
+        """
+        Set all pronunciation rules at once
+        
+        Args:
+            pronunciations: List of pronunciation rule dictionaries
+            
+        Returns:
+            Self for method chaining
+        """
+        if pronunciations and isinstance(pronunciations, list):
+            self._pronounce = pronunciations
+        return self
+
+    def set_param(self, key: str, value: Any) -> 'AgentBase':
+        """
+        Set a single AI parameter
+        
+        Args:
+            key: Parameter name
+            value: Parameter value
+            
+        Returns:
+            Self for method chaining
+        """
+        if key:
+            self._params[key] = value
+        return self
+
+    def set_params(self, params: Dict[str, Any]) -> 'AgentBase':
+        """
+        Set multiple AI parameters at once
+        
+        Args:
+            params: Dictionary of parameter name/value pairs
+            
+        Returns:
+            Self for method chaining
+        """
+        if params and isinstance(params, dict):
+            self._params.update(params)
+        return self
+
+    def set_global_data(self, data: Dict[str, Any]) -> 'AgentBase':
+        """
+        Set the global data available to the AI throughout the conversation
+        
+        Args:
+            data: Dictionary of global data
+            
+        Returns:
+            Self for method chaining
+        """
+        if data and isinstance(data, dict):
+            self._global_data = data
+        return self
+
+    def update_global_data(self, data: Dict[str, Any]) -> 'AgentBase':
+        """
+        Update the global data with new values
+        
+        Args:
+            data: Dictionary of global data to update
+            
+        Returns:
+            Self for method chaining
+        """
+        if data and isinstance(data, dict):
+            self._global_data.update(data)
+        return self
+
+    def set_native_functions(self, function_names: List[str]) -> 'AgentBase':
+        """
+        Set the list of native functions to enable
+        
+        Args:
+            function_names: List of native function names
+            
+        Returns:
+            Self for method chaining
+        """
+        if function_names and isinstance(function_names, list):
+            self.native_functions = [name for name in function_names if isinstance(name, str)]
+        return self
+
+    def set_internal_fillers(self, internal_fillers: Dict[str, Dict[str, List[str]]]) -> 'AgentBase':
+        """
+        Set internal fillers for native SWAIG functions
+        
+        Internal fillers provide custom phrases the AI says while executing
+        internal/native functions like check_time, wait_for_user, next_step, etc.
+        
+        Args:
+            internal_fillers: Dictionary mapping function names to language-specific filler phrases
+                            Format: {"function_name": {"language_code": ["phrase1", "phrase2"]}}
+                            Example: {"next_step": {"en-US": ["Moving to the next step...", "Great, let's continue..."]}}
+            
+        Returns:
+            Self for method chaining
+            
+        Example:
+            agent.set_internal_fillers({
+                "next_step": {
+                    "en-US": ["Moving to the next step...", "Great, let's continue..."],
+                    "es": ["Pasando al siguiente paso...", "Excelente, continuemos..."]
+                },
+                "check_time": {
+                    "en-US": ["Let me check the time...", "Getting the current time..."]
+                }
+            })
+        """
+        if internal_fillers and isinstance(internal_fillers, dict):
+            if not hasattr(self, '_internal_fillers'):
+                self._internal_fillers = {}
+            self._internal_fillers.update(internal_fillers)
+        return self
+
+    def add_internal_filler(self, function_name: str, language_code: str, fillers: List[str]) -> 'AgentBase':
+        """
+        Add internal fillers for a specific function and language
+        
+        Args:
+            function_name: Name of the internal function (e.g., 'next_step', 'check_time')
+            language_code: Language code (e.g., 'en-US', 'es', 'fr')
+            fillers: List of filler phrases for this function and language
+            
+        Returns:
+            Self for method chaining
+            
+        Example:
+            agent.add_internal_filler("next_step", "en-US", ["Moving to the next step...", "Great, let's continue..."])
+        """
+        if function_name and language_code and fillers and isinstance(fillers, list):
+            if not hasattr(self, '_internal_fillers'):
+                self._internal_fillers = {}
+            
+            if function_name not in self._internal_fillers:
+                self._internal_fillers[function_name] = {}
+                
+            self._internal_fillers[function_name][language_code] = fillers
+        return self
+
+    def add_function_include(self, url: str, functions: List[str], meta_data: Optional[Dict[str, Any]] = None) -> 'AgentBase':
+        """
+        Add a remote function include to the SWAIG configuration
+        
+        Args:
+            url: URL to fetch remote functions from
+            functions: List of function names to include
+            meta_data: Optional metadata to include with the function include
+            
+        Returns:
+            Self for method chaining
+        """
+        if url and functions and isinstance(functions, list):
+            include = {
+                "url": url,
+                "functions": functions
+            }
+            if meta_data and isinstance(meta_data, dict):
+                include["meta_data"] = meta_data
+            
+            self._function_includes.append(include)
+        return self
+
+    def set_function_includes(self, includes: List[Dict[str, Any]]) -> 'AgentBase':
+        """
+        Set the complete list of function includes
+        
+        Args:
+            includes: List of include objects, each with url and functions properties
+            
+        Returns:
+            Self for method chaining
+        """
+        if includes and isinstance(includes, list):
+            # Validate each include has required properties
+            valid_includes = []
+            for include in includes:
+                if isinstance(include, dict) and "url" in include and "functions" in include:
+                    if isinstance(include["functions"], list):
+                        valid_includes.append(include)
+            
+            self._function_includes = valid_includes
+        return self