signalwire-agents 0.1.0__py3-none-any.whl → 0.1.1__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.1"
 
 # 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.1"
         )
         
         # 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-0.1.0.dist-info → signalwire_agents-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.0
+Version: 0.1.1
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
 Project-URL: Homepage, https://github.com/signalwire/signalwire-ai-agents
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: fastapi==0.115.12
 Requires-Dist: pydantic==2.11.4
 Requires-Dist: PyYAML==6.0.2
@@ -23,6 +24,7 @@ Requires-Dist: setuptools==66.1.1
 Requires-Dist: signalwire_pom==2.7.1
 Requires-Dist: structlog==25.3.0
 Requires-Dist: uvicorn==0.34.2
+Dynamic: license-file
 
 # SignalWire AI Agent SDK
 
@@ -33,8 +35,9 @@ 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
-- **Security Built-In**: Session management, per-call tokens, and basic auth
-- **State Management**: Persistent conversation state with lifecycle hooks
+- **Custom Routing**: Dynamic request handling for different paths and content
+- **Security Built-In**: Session management, function-specific security tokens, and basic auth
+- **State Management**: Persistent conversation state with automatic tracking
 - **Prefab Archetypes**: Ready-to-use agent types for common scenarios
 - **Multi-Agent Support**: Host multiple agents on a single server
 
@@ -53,12 +56,23 @@ from signalwire_agents.core.function_result import SwaigFunctionResult
 class SimpleAgent(AgentBase):
     def __init__(self):
         super().__init__(name="simple", route="/simple")
-        self.set_personality("You are a helpful assistant.")
-        self.set_goal("Help users with basic questions.")
-        self.add_instruction("Be concise and clear.")
+        
+        # Configure the agent's personality
+        self.prompt_add_section("Personality", body="You are a helpful assistant.")
+        self.prompt_add_section("Goal", body="Help users with basic questions.")
+        self.prompt_add_section("Instructions", bullets=["Be concise and clear."])
+        
+        # Alternative using convenience methods:
+        # self.setPersonality("You are a helpful assistant.")
+        # self.setGoal("Help users with basic questions.")
+        # self.setInstructions(["Be concise and clear."])
     
-    @AgentBase.tool(name="get_time", parameters={})
-    def get_time(self):
+    @AgentBase.tool(
+        name="get_time", 
+        description="Get the current time",
+        parameters={}
+    )
+    def get_time(self, args, raw_data):
         from datetime import datetime
         now = datetime.now().strftime("%H:%M:%S")
         return SwaigFunctionResult(f"The current time is {now}")
@@ -73,6 +87,7 @@ if __name__ == "__main__":
 
 ```python
 from signalwire_agents import AgentBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
 from signalwire_agents.core.state import FileStateManager
 
 class StatefulAgent(AgentBase):
@@ -86,21 +101,44 @@ class StatefulAgent(AgentBase):
             enable_state_tracking=True,  # Enable state tracking
             state_manager=state_manager  # Use custom state manager
         )
+        
+        # When enable_state_tracking=True, startup_hook and hangup_hook
+        # are automatically registered to track session lifecycle
     
-    # These methods are automatically registered when enable_state_tracking=True
-    def startup_hook(self, args, raw_data):
-        """Called when a conversation starts"""
+    # Custom tool for accessing and updating state
+    @AgentBase.tool(
+        name="save_preference",
+        description="Save a user preference",
+        parameters={
+            "preference_name": {
+                "type": "string",
+                "description": "Name of the preference to save"
+            },
+            "preference_value": {
+                "type": "string",
+                "description": "Value of the preference"
+            }
+        }
+    )
+    def save_preference(self, args, raw_data):
+        # Get the call ID from the raw data
         call_id = raw_data.get("call_id")
-        state = self.get_state(call_id) or {}
-        state["started_at"] = "2023-01-01T12:00:00Z"
-        self.update_state(call_id, state)
-        return "Call initialized"
         
-    def hangup_hook(self, args, raw_data):
-        """Called when a conversation ends"""
-        call_id = raw_data.get("call_id")
-        state = self.get_state(call_id)
-        return "Call completed"
+        if call_id:
+            # Get current state or empty dict if none exists
+            state = self.get_state(call_id) or {}
+            
+            # Update the state
+            preferences = state.get("preferences", {})
+            preferences[args.get("preference_name")] = args.get("preference_value")
+            state["preferences"] = preferences
+            
+            # Save the updated state
+            self.update_state(call_id, state)
+            
+            return SwaigFunctionResult("Preference saved successfully")
+        else:
+            return SwaigFunctionResult("Could not save preference: No call ID")
 ```
 
 ## Using Prefab Agents
@@ -113,12 +151,20 @@ agent = InfoGathererAgent(
         {"name": "full_name", "prompt": "What is your full name?"},
         {"name": "reason", "prompt": "How can I help you today?"}
     ],
-    confirmation_template="Thanks {full_name}, I'll help you with {reason}."
+    confirmation_template="Thanks {full_name}, I'll help you with {reason}.",
+    name="info-gatherer",
+    route="/info-gatherer"
 )
 
-agent.serve(host="0.0.0.0", port=8000, route="/support")
+agent.serve(host="0.0.0.0", port=8000)
 ```
 
+Available prefabs include:
+- `InfoGathererAgent`: Collects structured information from users
+- `FAQBotAgent`: Answers questions based on a knowledge base
+- `ConciergeAgent`: Routes users to specialized agents
+- `SurveyAgent`: Conducts structured surveys with questions and rating scales
+
 ## Configuration
 
 ### Environment Variables
@@ -132,6 +178,7 @@ The SDK supports the following environment variables:
 - `SWML_SSL_CERT_PATH`: Path to SSL certificate file
 - `SWML_SSL_KEY_PATH`: Path to SSL private key file
 - `SWML_DOMAIN`: Domain name for SSL certificate and external URLs
+- `SWML_SCHEMA_PATH`: Optional path to override the location of the schema.json file
 
 When the auth environment variables are set, they will be used for all agents instead of generating random credentials. The proxy URL base is useful when your service is behind a reverse proxy or when you need external services to access your webhooks.
 
@@ -139,15 +186,13 @@ To enable HTTPS directly (without a reverse proxy), set `SWML_SSL_ENABLED` to "t
 
 ## Documentation
 
-See the [full documentation](https://docs.signalwire.com/ai-agents) for details on:
+The package includes comprehensive documentation in the `docs/` directory:
+
+- [Agent Guide](docs/agent_guide.md) - Detailed guide to creating and customizing agents
+- [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
 
-- Creating custom agents
-- Using prefab agents
-- SWAIG function definitions
-- State management and persistence
-- Security model
-- Deployment options
-- Multi-agent hosting
+These documents provide in-depth explanations of the features, APIs, and usage patterns.
 
 ## License
 

signalwire_agents-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+signalwire_agents/__init__.py,sha256=fOxVP6ME-O9x_nCGn9-VcssR7QnOD6cG6YlHP0dts4M,800
+signalwire_agents/agent_server.py,sha256=cyHVjsCSXHBVtJCB-eNgIPZNLKe-VT1fDFQR82TOkzY,12850
+signalwire_agents/schema.json,sha256=M8Mn6pQda2P9jhbmkALrLr1wt-fRuhYRqdmEi9Rbhqk,178075
+signalwire_agents-0.1.1.data/data/schema.json,sha256=M8Mn6pQda2P9jhbmkALrLr1wt-fRuhYRqdmEi9Rbhqk,178075
+signalwire_agents-0.1.1.dist-info/licenses/LICENSE,sha256=NYvAsB-rTcSvG9cqHt9EUHAWLiA9YzM4Qfz-mPdvDR0,1067
+signalwire_agents-0.1.1.dist-info/METADATA,sha256=yK8j3RqoCVO40A5MxR7UnGFCXCVJv7VS07-7WXQtbKw,7414
+signalwire_agents-0.1.1.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
+signalwire_agents-0.1.1.dist-info/top_level.txt,sha256=kDGS6ZYv84K9P5Kyg9_S8P_pbUXoHkso0On_DB5bbWc,18
+signalwire_agents-0.1.1.dist-info/RECORD,,

{signalwire_agents-0.1.0.dist-info → signalwire_agents-0.1.1.dist-info}/WHEEL

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

signalwire_agents-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SignalWire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

signalwire_agents/core/__init__.py

@@ -1,20 +0,0 @@
-"""
-Core components for SignalWire AI Agents
-"""
-
-from signalwire_agents.core.agent_base import AgentBase
-from signalwire_agents.core.function_result import SwaigFunctionResult
-from signalwire_agents.core.swaig_function import SwaigFunction
-from signalwire_agents.core.swml_service import SWMLService
-from signalwire_agents.core.swml_handler import SWMLVerbHandler, VerbHandlerRegistry
-from signalwire_agents.core.swml_builder import SWMLBuilder
-
-__all__ = [
-    'AgentBase', 
-    'SwaigFunctionResult', 
-    'SwaigFunction',
-    'SWMLService',
-    'SWMLVerbHandler',
-    'VerbHandlerRegistry',
-    'SWMLBuilder'
-]