signalwire-agents 0.1.6__py3-none-any.whl → 1.0.7__py3-none-any.whl

signalwire_agents/core/swml_builder.py

@@ -14,7 +14,12 @@ 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
+import types
+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
 
@@ -39,6 +44,12 @@ class SWMLBuilder:
             service: The SWMLService to delegate to
         """
         self.service = service
+        
+        # Dictionary to cache dynamically created methods
+        self._verb_methods_cache = {}
+        
+        # Create auto-vivified methods for all verbs
+        self._create_verb_methods()
     
     def answer(self, max_duration: Optional[int] = None, codecs: Optional[str] = None) -> Self:
         """
@@ -51,7 +62,12 @@ class SWMLBuilder:
         Returns:
             Self for method chaining
         """
-        self.service.add_answer_verb(max_duration, codecs)
+        config = {}
+        if max_duration is not None:
+            config["max_duration"] = max_duration
+        if codecs is not None:
+            config["codecs"] = codecs
+        self.service.add_verb("answer", config)
         return self
     
     def hangup(self, reason: Optional[str] = None) -> Self:
@@ -64,7 +80,10 @@ class SWMLBuilder:
         Returns:
             Self for method chaining
         """
-        self.service.add_hangup_verb(reason)
+        config = {}
+        if reason is not None:
+            config["reason"] = reason
+        self.service.add_verb("hangup", config)
         return self
     
     def ai(self, 
@@ -88,14 +107,26 @@ class SWMLBuilder:
         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
-        )
+        config = {}
+        
+        # Handle prompt (either text or POM, but not both)
+        if prompt_text is not None:
+            config["prompt"] = prompt_text
+        elif prompt_pom is not None:
+            config["prompt"] = prompt_pom
+        
+        # Add optional parameters
+        if post_prompt is not None:
+            config["post_prompt"] = post_prompt
+        if post_prompt_url is not None:
+            config["post_prompt_url"] = post_prompt_url
+        if swaig is not None:
+            config["SWAIG"] = swaig
+        
+        # Add any additional kwargs
+        config.update(kwargs)
+        
+        self.service.add_verb("ai", config)
         return self
     
     def play(self, url: Optional[str] = None, urls: Optional[List[str]] = None, 
@@ -211,4 +242,173 @@ class SWMLBuilder:
             Self for method chaining
         """
         self.service.reset_document()
-        return self 
+        return self
+    
+    def _create_verb_methods(self) -> None:
+        """
+        Create auto-vivified methods for all verbs at initialization time
+        
+        This creates methods for all SWML verbs defined in the schema,
+        allowing for fluent chaining like builder.denoise().goto().play()
+        """
+        # Get all verb names from the schema
+        if not hasattr(self.service, 'schema_utils') or not self.service.schema_utils:
+            return
+            
+        verb_names = self.service.schema_utils.get_all_verb_names()
+        
+        # Create a method for each verb
+        for verb_name in verb_names:
+            # Skip verbs that already have specific methods
+            if hasattr(self, verb_name):
+                continue
+            
+            # Handle sleep verb specially since it takes an integer directly
+            if verb_name == "sleep":
+                def sleep_method(self_instance, duration=None, **kwargs):
+                    """
+                    Add the sleep verb to the document.
+                    
+                    Args:
+                        duration: The amount of time to sleep in milliseconds
+                    """
+                    # Sleep verb takes a direct integer parameter in SWML
+                    if duration is not None:
+                        self_instance.service.add_verb("sleep", duration)
+                    elif kwargs:
+                        # Try to get the value from kwargs
+                        self_instance.service.add_verb("sleep", next(iter(kwargs.values())))
+                    else:
+                        raise TypeError("sleep() missing required argument: 'duration'")
+                    return self_instance
+                
+                # Set it as an attribute of self
+                setattr(self, verb_name, types.MethodType(sleep_method, self))
+                
+                # Also cache it for later
+                self._verb_methods_cache[verb_name] = sleep_method
+                continue
+                
+            # Generate the method implementation for normal verbs
+            def make_verb_method(name):
+                def verb_method(self_instance, **kwargs):
+                    """
+                    Dynamically generated method for SWML verb - returns self for chaining
+                    """
+                    config = {}
+                    for key, value in kwargs.items():
+                        if value is not None:
+                            config[key] = value
+                    self_instance.service.add_verb(name, config)
+                    return self_instance
+                
+                # Add docstring to the method
+                if hasattr(self.service.schema_utils, 'get_verb_properties'):
+                    verb_properties = self.service.schema_utils.get_verb_properties(name)
+                    if "description" in verb_properties:
+                        verb_method.__doc__ = f"Add the {name} verb to the document.\n\n{verb_properties['description']}\n\nReturns: Self for method chaining"
+                    else:
+                        verb_method.__doc__ = f"Add the {name} verb to the document.\n\nReturns: Self for method chaining"
+                else:
+                    verb_method.__doc__ = f"Add the {name} verb to the document.\n\nReturns: Self for method chaining"
+                
+                return verb_method
+            
+            # Create the method with closure over the verb name
+            method = make_verb_method(verb_name)
+            
+            # Set it as an attribute of self
+            setattr(self, verb_name, types.MethodType(method, self))
+            
+            # Also cache it for later
+            self._verb_methods_cache[verb_name] = method
+    
+    def __getattr__(self, name: str) -> Any:
+        """
+        Dynamically generate and return SWML verb methods when accessed
+        
+        This method is called when an attribute lookup fails through the normal
+        mechanisms. It checks if the attribute name corresponds to a SWML verb
+        defined in the schema, and if so, dynamically creates a method for that verb.
+        
+        Args:
+            name: The name of the attribute being accessed
+            
+        Returns:
+            The dynamically created verb method if name is a valid SWML verb,
+            otherwise raises AttributeError
+            
+        Raises:
+            AttributeError: If name is not a valid SWML verb
+        """
+        # First check if this is a valid SWML verb
+        if not hasattr(self.service, 'schema_utils') or not self.service.schema_utils:
+            msg = f"'{self.__class__.__name__}' object has no attribute '{name}' (no schema available)"
+            raise AttributeError(msg)
+            
+        verb_names = self.service.schema_utils.get_all_verb_names()
+        
+        if name in verb_names:
+            # Check if we already have this method in the cache
+            if not hasattr(self, '_verb_methods_cache'):
+                self._verb_methods_cache = {}
+                
+            if name in self._verb_methods_cache:
+                return types.MethodType(self._verb_methods_cache[name], self)
+            
+            # Handle sleep verb specially since it takes an integer directly
+            if name == "sleep":
+                def sleep_method(self_instance, duration=None, **kwargs):
+                    """
+                    Add the sleep verb to the document.
+                    
+                    Args:
+                        duration: The amount of time to sleep in milliseconds
+                    """
+                    # Sleep verb takes a direct integer parameter in SWML
+                    if duration is not None:
+                        self_instance.service.add_verb("sleep", duration)
+                    elif kwargs:
+                        # Try to get the value from kwargs
+                        self_instance.service.add_verb("sleep", next(iter(kwargs.values())))
+                    else:
+                        raise TypeError("sleep() missing required argument: 'duration'")
+                    return self_instance
+                
+                # Cache the method for future use
+                self._verb_methods_cache[name] = sleep_method
+                
+                # Return the bound method
+                return types.MethodType(sleep_method, self)
+            
+            # Generate the method implementation for normal verbs
+            def verb_method(self_instance, **kwargs):
+                """
+                Dynamically generated method for SWML verb - returns self for chaining
+                """
+                config = {}
+                for key, value in kwargs.items():
+                    if value is not None:
+                        config[key] = value
+                self_instance.service.add_verb(name, config)
+                return self_instance
+            
+            # Add docstring to the method
+            if hasattr(self.service.schema_utils, 'get_verb_properties'):
+                verb_properties = self.service.schema_utils.get_verb_properties(name)
+                if "description" in verb_properties:
+                    verb_method.__doc__ = f"Add the {name} verb to the document.\n\n{verb_properties['description']}\n\nReturns: Self for method chaining"
+                else:
+                    verb_method.__doc__ = f"Add the {name} verb to the document.\n\nReturns: Self for method chaining"
+            else:
+                verb_method.__doc__ = f"Add the {name} verb to the document.\n\nReturns: Self for method chaining"
+            
+            # Cache the method for future use
+            self._verb_methods_cache[name] = verb_method
+            
+            # Return the bound method
+            return types.MethodType(verb_method, self)
+        
+        # Not a valid verb
+        msg = f"'{self.__class__.__name__}' object has no attribute '{name}'"
+        raise AttributeError(msg) 

signalwire_agents/core/swml_handler.py

@@ -93,17 +93,33 @@ class AIVerbHandler(SWMLVerbHandler):
         """
         errors = []
         
-        # Check required fields
+        # Check that prompt is present
         if "prompt" not in config:
             errors.append("Missing required field 'prompt'")
+            return False, errors
         
-        # Validate prompt structure if present
-        if "prompt" in config:
-            prompt = config["prompt"]
-            if not isinstance(prompt, dict):
-                errors.append("'prompt' must be an object")
-            elif "text" not in prompt and "pom" not in prompt:
-                errors.append("'prompt' must contain either 'text' or 'pom'")
+        prompt = config["prompt"]
+        if not isinstance(prompt, dict):
+            errors.append("'prompt' must be an object")
+            return False, errors
+        
+        # Check that prompt contains either text or pom (required)
+        has_text = "text" in prompt
+        has_pom = "pom" in prompt
+        has_contexts = "contexts" in prompt
+        
+        # Require either text or pom (mutually exclusive)
+        base_prompt_count = sum([has_text, has_pom])
+        if base_prompt_count == 0:
+            errors.append("'prompt' must contain either 'text' or 'pom' as base prompt")
+        elif base_prompt_count > 1:
+            errors.append("'prompt' can only contain one of: 'text' or 'pom' (mutually exclusive)")
+        
+        # Contexts are optional and can be combined with text or pom
+        if has_contexts:
+            contexts = prompt["contexts"]
+            if not isinstance(contexts, dict):
+                errors.append("'prompt.contexts' must be an object")
         
         # Validate SWAIG structure if present
         if "SWAIG" in config:
@@ -116,6 +132,7 @@ class AIVerbHandler(SWMLVerbHandler):
     def build_config(self, 
                     prompt_text: Optional[str] = None,
                     prompt_pom: Optional[List[Dict[str, Any]]] = None,
+                    contexts: Optional[Dict[str, Any]] = None,
                     post_prompt: Optional[str] = None,
                     post_prompt_url: Optional[str] = None,
                     swaig: Optional[Dict[str, Any]] = None,
@@ -126,6 +143,7 @@ class AIVerbHandler(SWMLVerbHandler):
         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)
+            contexts: Optional contexts and steps configuration (can be combined with text or pom)
             post_prompt: Optional post-prompt text
             post_prompt_url: Optional URL for post-prompt processing
             swaig: Optional SWAIG configuration
@@ -136,13 +154,25 @@ class AIVerbHandler(SWMLVerbHandler):
         """
         config = {}
         
-        # Add prompt (either text or POM)
+        # Require either text or pom as base prompt (mutually exclusive)
+        base_prompt_count = sum(x is not None for x in [prompt_text, prompt_pom])
+        if base_prompt_count == 0:
+            raise ValueError("Either prompt_text or prompt_pom must be provided as base prompt")
+        elif base_prompt_count > 1:
+            raise ValueError("prompt_text and prompt_pom are mutually exclusive")
+        
+        # Build prompt object with base prompt
+        prompt_config = {}
         if prompt_text is not None:
-            config["prompt"] = {"text": prompt_text}
+            prompt_config["text"] = prompt_text
         elif prompt_pom is not None:
-            config["prompt"] = {"pom": prompt_pom}
-        else:
-            raise ValueError("Either prompt_text or prompt_pom must be provided")
+            prompt_config["pom"] = prompt_pom
+            
+        # Add contexts if provided (optional, activates steps feature)
+        if contexts is not None:
+            prompt_config["contexts"] = contexts
+            
+        config["prompt"] = prompt_config
         
         # Add post-prompt if provided
         if post_prompt is not None: