signalwire-agents 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

signalwire_agents/__init__.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 SignalWire AI Agents SDK
 =======================
@@ -5,7 +14,7 @@ SignalWire AI Agents SDK
 A package for building AI agents using SignalWire's AI and SWML capabilities.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 # Import core classes for easier access
 from signalwire_agents.core.agent_base import AgentBase

signalwire_agents/agent_server.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 AgentServer - Class for hosting multiple SignalWire AI Agents in a single server
 """
@@ -57,7 +66,7 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="0.1.0"
+            version="0.1.2"
         )
         
         # Keep track of registered agents
@@ -103,18 +112,25 @@ class AgentServer:
         self.logger.info(f"Registered agent '{agent.get_name()}' at route '{route}'")
         
         # If SIP routing is enabled and auto-mapping is on, register SIP usernames for this agent
-        if hasattr(self, '_sip_auto_map') and self._sip_auto_map and self._sip_routing_enabled:
-            self._auto_map_agent_sip_usernames(agent, route)
+        if self._sip_routing_enabled:
+            # Auto-map SIP usernames if enabled
+            if getattr(self, '_sip_auto_map', False):
+                self._auto_map_agent_sip_usernames(agent, route)
+            
+            # Register the SIP routing callback with this agent if we have one
+            if hasattr(self, '_sip_routing_callback') and self._sip_routing_callback:
+                agent.register_routing_callback(self._sip_routing_callback, path=self._sip_route)
             
     def setup_sip_routing(self, route: str = "/sip", auto_map: bool = True) -> None:
         """
         Set up central SIP-based routing for the server
         
-        This adds a special endpoint that can route SIP requests to the appropriate
-        agent based on the SIP username in the request.
+        This configures all agents to handle SIP requests at the specified path,
+        using a coordinated routing system where each agent checks if it can
+        handle SIP requests for specific usernames.
         
         Args:
-            route: The route for SIP requests
+            route: The path for SIP routing (default: "/sip")
             auto_map: Whether to automatically map SIP usernames to agent routes
         """
         if self._sip_routing_enabled:
@@ -136,48 +152,38 @@ class AgentServer:
         if auto_map:
             for agent_route, agent in self.agents.items():
                 self._auto_map_agent_sip_usernames(agent, agent_route)
-                
-        # Register the SIP endpoint
-        @self.app.post(f"{route}")
-        @self.app.post(f"{route}/")
-        async def handle_sip_request(request: Request):
-            """Handle SIP requests and route to the appropriate agent"""
-            self.logger.debug(f"Received request at SIP endpoint: {route}")
+        
+        # Create a unified routing callback that checks all registered usernames
+        def server_sip_routing_callback(request: Request, body: Dict[str, Any]) -> Optional[str]:
+            """Unified SIP routing callback that checks all registered usernames"""
+            # Extract the SIP username
+            sip_username = SWMLService.extract_sip_username(body)
             
-            try:
-                # Extract the request body
-                body = await request.json()
-                
-                # Extract the SIP username
-                sip_username = SWMLService.extract_sip_username(body)
+            if sip_username:
+                self.logger.info(f"Extracted SIP username: {sip_username}")
                 
-                if sip_username:
-                    self.logger.info(f"Extracted SIP username: {sip_username}")
-                    
-                    # Look up the route for this username
-                    target_route = self._lookup_sip_route(sip_username)
-                    
-                    if target_route:
-                        self.logger.info(f"Routing SIP request to {target_route}")
-                        
-                        # Create a redirect response to the target route
-                        # Use 307 Temporary Redirect to preserve the POST method
-                        response = Response(status_code=307)
-                        response.headers["Location"] = target_route
-                        return response
-                    else:
-                        self.logger.warning(f"No route found for SIP username: {sip_username}")
+                # Look up the route for this username
+                target_route = self._lookup_sip_route(sip_username)
                 
-                # If we get here, either no SIP username was found or no matching route exists
-                # Return a basic SWML response
-                return {"version": "1.0.0", "sections": {"main": []}}
-                
-            except Exception as e:
-                self.logger.error(f"Error processing SIP request: {str(e)}")
-                return {"version": "1.0.0", "sections": {"main": []}}
+                if target_route:
+                    self.logger.info(f"Routing SIP request to {target_route}")
+                    return target_route
+                else:
+                    self.logger.warning(f"No route found for SIP username: {sip_username}")
+            
+            # No routing needed (will be handled by the current agent)
+            return None
+        
+        # Save the callback for later use with new agents
+        self._sip_routing_callback = server_sip_routing_callback
+        
+        # Register this callback with each agent
+        for agent in self.agents.values():
+            # Each agent gets the same routing callback but at their own path
+            agent.register_routing_callback(server_sip_routing_callback, path=route)
+        
+        self.logger.info(f"SIP routing enabled at {route} on all agents")
         
-        self.logger.info(f"SIP routing enabled at {route}")
-                
     def register_sip_username(self, username: str, route: str) -> None:
         """
         Register a mapping from SIP username to agent route
@@ -334,3 +340,26 @@ class AgentServer:
             port=port,
             log_level=self.log_level
         )
+
+    def register_global_routing_callback(self, callback_fn: Callable[[Request, Dict[str, Any]], Optional[str]], 
+                                        path: str) -> None:
+        """
+        Register a routing callback across all agents
+        
+        This allows you to add unified routing logic to all agents at the same path.
+        
+        Args:
+            callback_fn: The callback function to register
+            path: The path to register the callback at
+        """
+        # Normalize the path
+        if not path.startswith("/"):
+            path = f"/{path}"
+        
+        path = path.rstrip("/")
+        
+        # Register with all existing agents
+        for agent in self.agents.values():
+            agent.register_routing_callback(callback_fn, path=path)
+        
+        self.logger.info(f"Registered global routing callback at {path} on all agents")

signalwire_agents/core/__init__.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 Core components for SignalWire AI Agents
 """

signalwire_agents/core/agent_base.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 AgentBase - Core foundation class for all SignalWire AI Agents
 """
@@ -195,6 +204,10 @@ class AgentBase(SWMLService):
         self._session_manager = SessionManager(token_expiry_secs=token_expiry_secs)
         self._enable_state_tracking = enable_state_tracking
         
+        # URL override variables
+        self._web_hook_url_override = None
+        self._post_prompt_url_override = None
+        
         # Register the tool decorator on this instance
         self.tool = self._tool_decorator
         
@@ -895,6 +908,10 @@ class AgentBase(SWMLService):
         # Get the default webhook URL with auth
         default_webhook_url = self._build_webhook_url("swaig", query_params)
         
+        # Use override if set
+        if hasattr(self, '_web_hook_url_override') and self._web_hook_url_override:
+            default_webhook_url = self._web_hook_url_override
+        
         # Prepare SWAIG object (correct format)
         swaig_obj = {}
         
@@ -952,6 +969,10 @@ class AgentBase(SWMLService):
         post_prompt_url = None
         if post_prompt:
             post_prompt_url = self._build_webhook_url("post_prompt", {})
+            
+            # Use override if set
+            if hasattr(self, '_post_prompt_url_override') and self._post_prompt_url_override:
+                post_prompt_url = self._post_prompt_url_override
         
         # Add answer verb with auto-answer enabled
         self.add_answer_verb()
@@ -1151,8 +1172,11 @@ class AgentBase(SWMLService):
     
     async def _handle_root_request(self, request: Request):
         """Handle GET/POST requests to the root endpoint"""
+        # Check if this is a callback path request
+        callback_path = getattr(request.state, "callback_path", None)
+        
         req_log = self.log.bind(
-            endpoint="root",
+            endpoint="root" if not callback_path else f"callback:{callback_path}",
             method=request.method,
             path=request.url.path
         )
@@ -1202,6 +1226,25 @@ class AgentBase(SWMLService):
                 req_log = req_log.bind(call_id=call_id)
                 req_log.debug("call_id_identified")
             
+            # Check if this is a callback path and we need to apply routing
+            if callback_path and hasattr(self, '_routing_callbacks') and callback_path in self._routing_callbacks:
+                callback_fn = self._routing_callbacks[callback_path]
+                
+                if request.method == "POST" and body:
+                    req_log.debug("processing_routing_callback", path=callback_path)
+                    # Call the routing callback
+                    try:
+                        route = callback_fn(request, body)
+                        if route is not None:
+                            req_log.info("routing_request", route=route)
+                            # Return a redirect to the new route
+                            return Response(
+                                status_code=307,  # 307 Temporary Redirect preserves the method and body
+                                headers={"Location": route}
+                            )
+                    except Exception as e:
+                        req_log.error("error_in_routing_callback", error=str(e), traceback=traceback.format_exc())
+            
             # Allow subclasses to inspect/modify the request
             modifications = None
             if body:
@@ -1669,28 +1712,34 @@ class AgentBase(SWMLService):
         async def handle_post_prompt_with_slash(request: Request):
             return await self._handle_post_prompt_request(request)
         
-        # Check if SIP routing is enabled for this agent
-        # (The agent will have _sip_usernames if enable_sip_routing was called)
-        if hasattr(self, '_sip_usernames') and self._sip_usernames:
-            self.log.info("registering_sip_endpoint", usernames=list(self._sip_usernames))
-            
-            # SIP endpoint - without trailing slash
-            @app.get("/sip")
-            @app.post("/sip")
-            async def handle_sip_no_slash(request: Request):
-                return await self._handle_root_request(request)
+        # Register routes for all routing callbacks
+        if hasattr(self, '_routing_callbacks') and self._routing_callbacks:
+            for callback_path, callback_fn in self._routing_callbacks.items():
+                # Skip the root path as it's already handled
+                if callback_path == "/":
+                    continue
                 
-            # SIP endpoint - with trailing slash
-            @app.get("/sip/")
-            @app.post("/sip/")
-            async def handle_sip_with_slash(request: Request):
-                return await self._handle_root_request(request)
+                # Register the endpoint without trailing slash
+                callback_route = callback_path
+                self.log.info("registering_callback_route", path=callback_route)
                 
-            # Log that SIP endpoint was added
-            self.log.info("sip_endpoint_registered", path="/sip")
-            
-            # Add SIP routes to the printed information
-            print(f"SIP endpoint available at: http://{self.host}:{self.port}/sip")
+                @app.get(callback_route)
+                @app.post(callback_route)
+                async def handle_callback_no_slash(request: Request, path_param=callback_route):
+                    # Store the callback path in request state for _handle_root_request to use
+                    request.state.callback_path = path_param
+                    return await self._handle_root_request(request)
+                
+                # Register the endpoint with trailing slash if it doesn't already have one
+                if not callback_route.endswith('/'):
+                    slash_route = f"{callback_route}/"
+                    
+                    @app.get(slash_route)
+                    @app.post(slash_route)
+                    async def handle_callback_with_slash(request: Request, path_param=callback_route):
+                        # Store the callback path in request state for _handle_root_request to use
+                        request.state.callback_path = path_param
+                        return await self._handle_root_request(request)
         
         # Log all registered routes
         routes = [f"{route.methods} {route.path}" for route in app.routes]
@@ -2042,16 +2091,24 @@ class AgentBase(SWMLService):
         print(f"URL: http://{host}:{port}{self.route}")
         print(f"Basic Auth: {username}:{password} (source: {source})")
         
-        # Check if SIP routing is enabled and print additional info
+        # Check if SIP usernames are registered and print that info
         if hasattr(self, '_sip_usernames') and self._sip_usernames:
-            print(f"SIP endpoint: http://{host}:{port}/sip")
-            print(f"SIP usernames: {', '.join(self._sip_usernames)}")
+            print(f"Registered SIP usernames: {', '.join(sorted(self._sip_usernames))}")
+        
+        # Check if callback endpoints are registered and print them
+        if hasattr(self, '_routing_callbacks') and self._routing_callbacks:
+            for path in sorted(self._routing_callbacks.keys()):
+                if hasattr(self, '_sip_usernames') and path == "/sip":
+                    print(f"SIP endpoint: http://{host}:{port}{path}")
+                else:
+                    print(f"Callback endpoint: http://{host}:{port}{path}")
         
         # Configure Uvicorn for production
         uvicorn_log_config = uvicorn.config.LOGGING_CONFIG
         uvicorn_log_config["formatters"]["access"]["fmt"] = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
         uvicorn_log_config["formatters"]["default"]["fmt"] = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
         
+        # Start the server
         try:
             # Run the server
             uvicorn.run(
@@ -2368,18 +2425,19 @@ class AgentBase(SWMLService):
             self._function_includes = valid_includes
         return self
 
-    def enable_sip_routing(self, auto_map: bool = True) -> 'AgentBase':
+    def enable_sip_routing(self, auto_map: bool = True, path: str = "/sip") -> 'AgentBase':
         """
         Enable SIP-based routing for this agent
         
         This allows the agent to automatically route SIP requests based on SIP usernames.
-        When enabled, a global `/sip` endpoint is automatically created that will handle
-        SIP requests and deliver them to this agent.
+        When enabled, an endpoint at the specified path is automatically created
+        that will handle SIP requests and deliver them to this agent.
         
         Args:
             auto_map: Whether to automatically map common SIP usernames to this agent
                      (based on the agent name and route path)
-            
+            path: The path to register the SIP routing endpoint (default: "/sip")
+        
         Returns:
             Self for method chaining
         """
@@ -2391,11 +2449,19 @@ class AgentBase(SWMLService):
             if sip_username:
                 self.log.info("sip_username_extracted", username=sip_username)
                 
-                # This route is already being handled by the agent, no need to redirect
-                return None
-                
-        # Register the callback with the SWMLService
-        self.register_routing_callback(sip_routing_callback)
+                # Check if this username is registered with this agent
+                if hasattr(self, '_sip_usernames') and sip_username.lower() in self._sip_usernames:
+                    self.log.info("sip_username_matched", username=sip_username)
+                    # This route is already being handled by the agent, no need to redirect
+                    return None
+                else:
+                    self.log.info("sip_username_not_matched", username=sip_username)
+                    # Not registered with this agent, let routing continue
+                    
+            return None
+            
+        # Register the callback with the SWMLService, specifying the path
+        self.register_routing_callback(sip_routing_callback, path=path)
         
         # Auto-map common usernames if requested
         if auto_map:
@@ -2447,3 +2513,29 @@ class AgentBase(SWMLService):
                 self.register_sip_username(no_vowels)
                 
         return self
+
+    def set_web_hook_url(self, url: str) -> 'AgentBase':
+        """
+        Override the default web_hook_url with a supplied URL string
+        
+        Args:
+            url: The URL to use for SWAIG function webhooks
+            
+        Returns:
+            Self for method chaining
+        """
+        self._web_hook_url_override = url
+        return self
+        
+    def set_post_prompt_url(self, url: str) -> 'AgentBase':
+        """
+        Override the default post_prompt_url with a supplied URL string
+        
+        Args:
+            url: The URL to use for post-prompt summary delivery
+            
+        Returns:
+            Self for method chaining
+        """
+        self._post_prompt_url_override = url
+        return self

signalwire_agents/core/function_result.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 SwaigFunctionResult class for handling the response format of SWAIG function calls
 """
@@ -5,18 +14,6 @@ SwaigFunctionResult class for handling the response format of SWAIG function cal
 from typing import Dict, List, Any, Optional, Union
 
 
-class SwaigActionTypes:
-    """Constants for standard SWAIG action types"""
-    PLAY = "play"
-    TRANSFER = "transfer"
-    SEND_SMS = "send_sms"
-    JOIN_ROOM = "join_room"
-    RETURN = "return"
-    HANG_UP = "hang_up"
-    RECORD = "record"
-    COLLECT = "collect"
-
-
 class SwaigFunctionResult:
     """
     Wrapper around SWAIG function responses that handles proper formatting
@@ -36,6 +33,15 @@ class SwaigFunctionResult:
             SwaigFunctionResult("I'll confirm that")
             .add_action("confirm", True)
         )
+        
+        # With multiple actions
+        return (
+            SwaigFunctionResult("Processing your request")
+            .add_actions([
+                {"set_global_data": {"key": "value"}},
+                {"play": {"url": "music.mp3"}}
+            ])
+        )
     """
     def __init__(self, response: Optional[str] = None):
         """
@@ -74,6 +80,19 @@ class SwaigFunctionResult:
         self.action.append({name: data})
         return self
     
+    def add_actions(self, actions: List[Dict[str, Any]]) -> 'SwaigFunctionResult':
+        """
+        Add multiple structured actions to the response
+        
+        Args:
+            actions: List of action objects to add to the response
+            
+        Returns:
+            Self for method chaining
+        """
+        self.action.extend(actions)
+        return self
+    
     def to_dict(self) -> Dict[str, Any]:
         """
         Convert to the JSON structure expected by SWAIG

signalwire_agents/core/pom_builder.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 PomBuilder for creating structured POM prompts for SignalWire AI Agents
 """

signalwire_agents/core/security/__init__.py

@@ -0,0 +1,9 @@
+"""
+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.
+"""
+

signalwire_agents/core/security/session_manager.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 Session manager for handling call sessions and security tokens
 """

signalwire_agents/core/state/__init__.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 State management for SignalWire AI Agents
 """

signalwire_agents/core/state/file_state_manager.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 File-based implementation of the StateManager interface
 """

signalwire_agents/core/state/state_manager.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 Abstract base class for state management
 """

signalwire_agents/core/swaig_function.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 SwaigFunction class for defining and managing SWAIG function interfaces
 """

signalwire_agents/core/swml_builder.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 SWML Builder - Fluent API for building SWML documents
 

signalwire_agents/core/swml_handler.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 SWML Verb Handlers - Interface and implementations for SWML verb handling
 

signalwire_agents/core/swml_renderer.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 SwmlRenderer for generating complete SWML documents for SignalWire AI Agents
 """