signalwire-agents 1.0.2__tar.gz → 1.0.4__tar.gz

{signalwire_agents-1.0.2/signalwire_agents.egg-info → signalwire_agents-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 1.0.2
+Version: 1.0.4
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT

{signalwire_agents-1.0.2 → signalwire_agents-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire_agents"
-version = "1.0.2"
+version = "1.0.4"
 description = "SignalWire AI Agents SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}

{signalwire_agents-1.0.2 → signalwire_agents-1.0.4}/signalwire_agents/__init__.py

@@ -18,7 +18,7 @@ A package for building AI agents using SignalWire's AI and SWML capabilities.
 from .core.logging_config import configure_logging
 configure_logging()
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"
 
 # Import core classes for easier access
 from .core.agent_base import AgentBase

{signalwire_agents-1.0.2 → signalwire_agents-1.0.4}/signalwire_agents/core/agent_base.py

@@ -266,7 +266,21 @@ class AgentBase(
         
         # Initialize SWAIG query params for dynamic config
         self._swaig_query_params = {}
-    
+
+        # Initialize verb insertion points for call flow customization
+        self._pre_answer_verbs = []    # Verbs to run before answer (e.g., ringback, screening)
+        self._answer_config = {}        # Configuration for the answer verb
+        self._post_answer_verbs = []    # Verbs to run after answer, before AI (e.g., announcements)
+        self._post_ai_verbs = []        # Verbs to run after AI ends (e.g., cleanup, transfers)
+
+    # Verb categories for pre-answer validation
+    _PRE_ANSWER_SAFE_VERBS = {
+        "transfer", "execute", "return", "label", "goto", "request",
+        "switch", "cond", "if", "eval", "set", "unset", "hangup",
+        "send_sms", "sleep", "stop_record_call", "stop_denoise", "stop_tap"
+    }
+    _AUTO_ANSWER_VERBS = {"play", "connect"}
+
     @staticmethod
     def _load_service_config(config_file: Optional[str], service_name: str) -> dict:
         """Load service configuration from config file if available"""
@@ -380,14 +394,166 @@ class AgentBase(
     def on_summary(self, summary: Optional[Dict[str, Any]], raw_data: Optional[Dict[str, Any]] = None) -> None:
         """
         Called when a post-prompt summary is received
-        
+
         Args:
             summary: The summary object or None if no summary was found
             raw_data: The complete raw POST data from the request
         """
         # Default implementation does nothing
         pass
-    
+
+    # ==================== Call Flow Verb Insertion Methods ====================
+
+    def add_pre_answer_verb(self, verb_name: str, config: Dict[str, Any]) -> 'AgentBase':
+        """
+        Add a verb to run before the call is answered.
+
+        Pre-answer verbs execute while the call is still ringing. Only certain
+        verbs are safe to use before answering:
+
+        Safe verbs: transfer, execute, return, label, goto, request, switch,
+                   cond, if, eval, set, unset, hangup, send_sms, sleep,
+                   stop_record_call, stop_denoise, stop_tap
+
+        Verbs with auto_answer option (play, connect): Must include
+        "auto_answer": False in config to prevent automatic answering.
+
+        Args:
+            verb_name: The SWML verb name (e.g., "play", "sleep", "request")
+            config: Verb configuration dictionary
+
+        Returns:
+            Self for method chaining
+
+        Raises:
+            ValueError: If verb is not safe for pre-answer use
+
+        Example:
+            # Play ringback tone before answering
+            agent.add_pre_answer_verb("play", {
+                "urls": ["ring:us"],
+                "auto_answer": False
+            })
+        """
+        # Validate verb is safe for pre-answer use
+        if verb_name in self._AUTO_ANSWER_VERBS:
+            if not config.get("auto_answer") is False:
+                self.log.warning(
+                    "pre_answer_verb_will_answer",
+                    verb=verb_name,
+                    hint=f"Add 'auto_answer': False to prevent {verb_name} from answering the call"
+                )
+        elif verb_name not in self._PRE_ANSWER_SAFE_VERBS:
+            raise ValueError(
+                f"Verb '{verb_name}' is not safe for pre-answer use. "
+                f"Safe verbs: {', '.join(sorted(self._PRE_ANSWER_SAFE_VERBS))}"
+            )
+
+        self._pre_answer_verbs.append((verb_name, config))
+        return self
+
+    def add_answer_verb(self, config: Optional[Dict[str, Any]] = None) -> 'AgentBase':
+        """
+        Configure the answer verb.
+
+        The answer verb connects the call. Use this method to customize
+        answer behavior, such as setting max_duration.
+
+        Args:
+            config: Optional answer verb configuration (e.g., {"max_duration": 3600})
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            # Set maximum call duration to 1 hour
+            agent.add_answer_verb({"max_duration": 3600})
+        """
+        self._answer_config = config or {}
+        return self
+
+    def add_post_answer_verb(self, verb_name: str, config: Dict[str, Any]) -> 'AgentBase':
+        """
+        Add a verb to run after the call is answered but before the AI starts.
+
+        Post-answer verbs run after the call is connected. Common uses include
+        welcome messages, legal disclaimers, and hold music.
+
+        Args:
+            verb_name: The SWML verb name (e.g., "play", "sleep")
+            config: Verb configuration dictionary
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            # Play welcome message
+            agent.add_post_answer_verb("play", {
+                "url": "say:Welcome to Acme Corporation."
+            })
+            # Brief pause
+            agent.add_post_answer_verb("sleep", {"time": 500})
+        """
+        self._post_answer_verbs.append((verb_name, config))
+        return self
+
+    def add_post_ai_verb(self, verb_name: str, config: Dict[str, Any]) -> 'AgentBase':
+        """
+        Add a verb to run after the AI conversation ends.
+
+        Post-AI verbs run when the AI completes its conversation. Common uses
+        include clean disconnects, transfers, and logging.
+
+        Args:
+            verb_name: The SWML verb name (e.g., "hangup", "transfer", "request")
+            config: Verb configuration dictionary
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            # Log call completion and hang up
+            agent.add_post_ai_verb("request", {
+                "url": "https://api.example.com/call-complete",
+                "method": "POST"
+            })
+            agent.add_post_ai_verb("hangup", {})
+        """
+        self._post_ai_verbs.append((verb_name, config))
+        return self
+
+    def clear_pre_answer_verbs(self) -> 'AgentBase':
+        """
+        Remove all pre-answer verbs.
+
+        Returns:
+            Self for method chaining
+        """
+        self._pre_answer_verbs = []
+        return self
+
+    def clear_post_answer_verbs(self) -> 'AgentBase':
+        """
+        Remove all post-answer verbs.
+
+        Returns:
+            Self for method chaining
+        """
+        self._post_answer_verbs = []
+        return self
+
+    def clear_post_ai_verbs(self) -> 'AgentBase':
+        """
+        Remove all post-AI verbs.
+
+        Returns:
+            Self for method chaining
+        """
+        self._post_ai_verbs = []
+        return self
+
+    # ==================== End Call Flow Verb Insertion Methods ====================
+
     def enable_sip_routing(self, auto_map: bool = True, path: str = "/sip") -> 'AgentBase':
         """
         Enable SIP-based routing for this agent
@@ -746,15 +912,29 @@ class AgentBase(
             if hasattr(agent_to_use, '_post_prompt_url_override') and agent_to_use._post_prompt_url_override:
                 post_prompt_url = agent_to_use._post_prompt_url_override
                 
-        # Add answer verb with auto-answer enabled
-        agent_to_use.add_verb("answer", {})
-        
-        # Add recording if enabled
+        # ========== PHASE 1: PRE-ANSWER VERBS ==========
+        # These run while the call is still ringing
+        for verb_name, verb_config in agent_to_use._pre_answer_verbs:
+            agent_to_use.add_verb(verb_name, verb_config)
+
+        # ========== PHASE 2: ANSWER VERB ==========
+        # Only add answer verb if auto_answer is enabled
+        if agent_to_use._auto_answer:
+            agent_to_use.add_verb("answer", agent_to_use._answer_config)
+
+        # ========== PHASE 3: POST-ANSWER VERBS ==========
+        # These run after answer but before AI
+
+        # Add recording if enabled (this is a post-answer verb)
         if agent_to_use._record_call:
             agent_to_use.add_verb("record_call", {
                 "format": agent_to_use._record_format,
                 "stereo": agent_to_use._record_stereo
             })
+
+        # Add user-defined post-answer verbs
+        for verb_name, verb_config in agent_to_use._post_answer_verbs:
+            agent_to_use.add_verb(verb_name, verb_config)
         
         # Use the AI verb handler to build and validate the AI verb config
         ai_config = {}
@@ -881,10 +1061,16 @@ class AgentBase(
         
         if agent_to_use._global_data and "global_data" not in ai_config:
             ai_config["global_data"] = agent_to_use._global_data
-        
+
+        # ========== PHASE 4: AI VERB ==========
         # Add the AI verb to the document
         agent_to_use.add_verb("ai", ai_config)
-        
+
+        # ========== PHASE 5: POST-AI VERBS ==========
+        # These run after the AI conversation ends
+        for verb_name, verb_config in agent_to_use._post_ai_verbs:
+            agent_to_use.add_verb(verb_name, verb_config)
+
         # Apply any modifications from the callback to agent state
         if modifications and isinstance(modifications, dict):
             # Handle global_data modifications by updating the AI config directly
@@ -900,16 +1086,31 @@ class AgentBase(
             
             # Clear and rebuild the document with the modified AI config
             agent_to_use.reset_document()
-            agent_to_use.add_verb("answer", {})
-            
-            # Add recording if enabled
+
+            # Rebuild with 5-phase approach
+            # PHASE 1: Pre-answer verbs
+            for verb_name, verb_config in agent_to_use._pre_answer_verbs:
+                agent_to_use.add_verb(verb_name, verb_config)
+
+            # PHASE 2: Answer verb (if auto_answer enabled)
+            if agent_to_use._auto_answer:
+                agent_to_use.add_verb("answer", agent_to_use._answer_config)
+
+            # PHASE 3: Post-answer verbs
             if agent_to_use._record_call:
                 agent_to_use.add_verb("record_call", {
                     "format": agent_to_use._record_format,
                     "stereo": agent_to_use._record_stereo
                 })
-            
+            for verb_name, verb_config in agent_to_use._post_answer_verbs:
+                agent_to_use.add_verb(verb_name, verb_config)
+
+            # PHASE 4: AI verb
             agent_to_use.add_verb("ai", ai_config)
+
+            # PHASE 5: Post-AI verbs
+            for verb_name, verb_config in agent_to_use._post_ai_verbs:
+                agent_to_use.add_verb(verb_name, verb_config)
         
         # Return the rendered document as a string
         return agent_to_use.render_document()
@@ -1015,7 +1216,13 @@ class AgentBase(
         ephemeral_agent._pronounce = copy.deepcopy(self._pronounce)
         ephemeral_agent._global_data = copy.deepcopy(self._global_data)
         ephemeral_agent._function_includes = copy.deepcopy(self._function_includes)
-        
+
+        # Deep copy verb insertion points for call flow customization
+        ephemeral_agent._pre_answer_verbs = copy.deepcopy(self._pre_answer_verbs)
+        ephemeral_agent._answer_config = copy.deepcopy(self._answer_config)
+        ephemeral_agent._post_answer_verbs = copy.deepcopy(self._post_answer_verbs)
+        ephemeral_agent._post_ai_verbs = copy.deepcopy(self._post_ai_verbs)
+
         # Deep copy LLM parameters
         ephemeral_agent._prompt_llm_params = copy.deepcopy(self._prompt_llm_params)
         ephemeral_agent._post_prompt_llm_params = copy.deepcopy(self._post_prompt_llm_params)

{signalwire_agents-1.0.2 → signalwire_agents-1.0.4}/signalwire_agents/schema.json

@@ -60,6 +60,9 @@
                 {
                     "$ref": "#/$defs/Denoise"
                 },
+                {
+                    "$ref": "#/$defs/EnterQueue"
+                },
                 {
                     "$ref": "#/$defs/Execute"
                 },
@@ -303,6 +306,23 @@
             },
             "title": "Denoise object"
         },
+        "EnterQueue": {
+            "type": "object",
+            "properties": {
+                "enter_queue": {
+                    "$ref": "#/$defs/EnterQueueObject",
+                    "description": "Place the call in a queue.",
+                    "title": "enter_queue"
+                }
+            },
+            "required": [
+                "enter_queue"
+            ],
+            "unevaluatedProperties": {
+                "not": {}
+            },
+            "title": "EnterQueue object"
+        },
         "Execute": {
             "type": "object",
             "properties": {
@@ -311,7 +331,7 @@
                     "properties": {
                         "dest": {
                             "type": "string",
-                            "description": "Specifies what to execute. The value can be one of: \n<section_name> - section in the current document to execute.\nhttps://<URL>\" - URL pointing to the document to execute. Sends HTTP POST."
+                            "description": "Specifies what to execute. The value can be one of:\n- `<section_name>` - section in the current document to execute\n- A URL (http or https) that returns a SWML document - Sends HTTP POST\n- An inline SWML document (as a JSON string)"
                         },
                         "params": {
                             "type": "object",
@@ -1561,7 +1581,7 @@
                     "properties": {
                         "dest": {
                             "type": "string",
-                            "description": "Specifies where to transfer the call. The value can be one of:\n    - `<section_name>` - section in the SWML document to jump to.\n    - `https://<URL>` - URL pointing to the document to transfer to. Sends HTTP POST."
+                            "description": "Specifies where to transfer the call. The value can be one of:\n- `<section_name>` - section in the SWML document to jump to\n- A URL (http or https) that returns a SWML document - Sends HTTP POST\n- An inline SWML document (as a JSON string)"
                         },
                         "params": {
                             "type": "object",
@@ -1642,7 +1662,7 @@
                         "payment_connector_url": {
                             "type": "string",
                             "format": "uri",
-                            "description": "The URL to make POST requests with all the gathered payment details.\nThis URL is used to process the final payment transaction and return the results through the response.\n\nVisit https://developer.signalwire.com//swml/methods/pay/payment_connector_url for more important information."
+                            "description": "The URL to make POST requests with all the gathered payment details.\nThis URL is used to process the final payment transaction and return the results through the response.\n\nVisit https://developer.signalwire.com/swml/methods/pay/payment_connector_url for more important information."
                         },
                         "charge_amount": {
                             "type": "string",
@@ -2223,6 +2243,17 @@
                     "format": "uri",
                     "description": "http or https URL to deliver call status events"
                 },
+                "transfer_after_bridge": {
+                    "anyOf": [
+                        {
+                            "type": "string"
+                        },
+                        {
+                            "$ref": "#/$defs/SWMLVar"
+                        }
+                    ],
+                    "description": "SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends.\nCan be either:\n- A URL (http or https) that returns a SWML document\n- An inline SWML document (as a JSON string)\n\n**Note:** This parameter is REQUIRED when connecting to a queue (when `to` starts with \"queue:\")"
+                },
                 "call_state_events": {
                     "type": "array",
                     "items": {
@@ -2235,7 +2266,7 @@
                 },
                 "to": {
                     "type": "string",
-                    "description": "The SIP URI or phone number to dial."
+                    "description": "Destination to dial. Can be:\n- Phone number in E.164 format (e.g., \"+15552345678\")\n- SIP URI (e.g., \"sip:alice@example.com\")\n- Call Fabric Resource address (e.g., \"/public/test_room\")\n- Queue (e.g., \"queue:support\")"
                 }
             },
             "required": [
@@ -2398,6 +2429,17 @@
                     "format": "uri",
                     "description": "http or https URL to deliver call status events"
                 },
+                "transfer_after_bridge": {
+                    "anyOf": [
+                        {
+                            "type": "string"
+                        },
+                        {
+                            "$ref": "#/$defs/SWMLVar"
+                        }
+                    ],
+                    "description": "SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends.\nCan be either:\n- A URL (http or https) that returns a SWML document\n- An inline SWML document (as a JSON string)\n\n**Note:** This parameter is REQUIRED when connecting to a queue (when `to` starts with \"queue:\")"
+                },
                 "call_state_events": {
                     "type": "array",
                     "items": {
@@ -2575,6 +2617,17 @@
                     "format": "uri",
                     "description": "http or https URL to deliver call status events"
                 },
+                "transfer_after_bridge": {
+                    "anyOf": [
+                        {
+                            "type": "string"
+                        },
+                        {
+                            "$ref": "#/$defs/SWMLVar"
+                        }
+                    ],
+                    "description": "SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends.\nCan be either:\n- A URL (http or https) that returns a SWML document\n- An inline SWML document (as a JSON string)\n\n**Note:** This parameter is REQUIRED when connecting to a queue (when `to` starts with \"queue:\")"
+                },
                 "call_state_events": {
                     "type": "array",
                     "items": {
@@ -2753,6 +2806,17 @@
                     "format": "uri",
                     "description": "http or https URL to deliver call status events"
                 },
+                "transfer_after_bridge": {
+                    "anyOf": [
+                        {
+                            "type": "string"
+                        },
+                        {
+                            "$ref": "#/$defs/SWMLVar"
+                        }
+                    ],
+                    "description": "SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends.\nCan be either:\n- A URL (http or https) that returns a SWML document\n- An inline SWML document (as a JSON string)\n\n**Note:** This parameter is REQUIRED when connecting to a queue (when `to` starts with \"queue:\")"
+                },
                 "call_state_events": {
                     "type": "array",
                     "items": {
@@ -2782,6 +2846,63 @@
             },
             "title": "ConnectDeviceSerialParallel object"
         },
+        "EnterQueueObject": {
+            "type": "object",
+            "properties": {
+                "queue_name": {
+                    "type": "string",
+                    "description": "Name of the queue to enter."
+                },
+                "transfer_after_bridge": {
+                    "anyOf": [
+                        {
+                            "type": "string"
+                        },
+                        {
+                            "$ref": "#/$defs/SWMLVar"
+                        }
+                    ],
+                    "description": "SWML to execute after the bridge completes. This defines what should happen after the call is connected to an agent and the bridge ends.\nCan be either:\n- A URL (http or https) that returns a SWML document\n- An inline SWML document (as a JSON string)"
+                },
+                "status_url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "HTTP or HTTPS URL to deliver queue status events. Default not set"
+                },
+                "wait_url": {
+                    "anyOf": [
+                        {
+                            "type": "string",
+                            "format": "uri"
+                        },
+                        {
+                            "$ref": "#/$defs/SWMLVar"
+                        }
+                    ],
+                    "description": "URL for media to play while waiting in the queue. Default hold music will be played if not set"
+                },
+                "wait_time": {
+                    "anyOf": [
+                        {
+                            "type": "integer"
+                        },
+                        {
+                            "$ref": "#/$defs/SWMLVar"
+                        }
+                    ],
+                    "minimum": 1,
+                    "description": "Maximum time in seconds to wait in the queue before timeout. Default `3600`"
+                }
+            },
+            "required": [
+                "queue_name",
+                "transfer_after_bridge"
+            ],
+            "unevaluatedProperties": {
+                "not": {}
+            },
+            "title": "EnterQueueObject object"
+        },
         "ExecuteSwitch": {
             "type": "object",
             "properties": {
@@ -8665,6 +8786,12 @@
                 {
                     "$ref": "#/$defs/SWMLAction"
                 },
+                {
+                    "$ref": "#/$defs/ChangeContextAction"
+                },
+                {
+                    "$ref": "#/$defs/ChangeStepAction"
+                },
                 {
                     "$ref": "#/$defs/ContextSwitchAction"
                 },
@@ -8860,6 +8987,40 @@
             },
             "title": "SWMLAction object"
         },
+        "ChangeContextAction": {
+            "type": "object",
+            "properties": {
+                "change_context": {
+                    "type": "string",
+                    "description": "The name of the context to switch to. The context must be defined in the AI's prompt.contexts configuration.",
+                    "title": "change_context"
+                }
+            },
+            "required": [
+                "change_context"
+            ],
+            "unevaluatedProperties": {
+                "not": {}
+            },
+            "title": "ChangeContextAction object"
+        },
+        "ChangeStepAction": {
+            "type": "object",
+            "properties": {
+                "change_step": {
+                    "type": "string",
+                    "description": "The name of the step to switch to. The step must be defined in the current context's steps array.",
+                    "title": "change_step"
+                }
+            },
+            "required": [
+                "change_step"
+            ],
+            "unevaluatedProperties": {
+                "not": {}
+            },
+            "title": "ChangeStepAction object"
+        },
         "ContextSwitchAction": {
             "type": "object",
             "properties": {

{signalwire_agents-1.0.2 → signalwire_agents-1.0.4/signalwire_agents.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 1.0.2
+Version: 1.0.4
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT