signalwire-agents 0.1.13__py3-none-any.whl → 1.0.17.dev4__py3-none-any.whl

signalwire_agents/__init__.py

@@ -18,41 +18,120 @@ A package for building AI agents using SignalWire's AI and SWML capabilities.
 from .core.logging_config import configure_logging
 configure_logging()
 
-__version__ = "0.1.13"
+__version__ = "1.0.17.dev4"
 
 # Import core classes for easier access
 from .core.agent_base import AgentBase
 from .core.contexts import ContextBuilder, Context, Step, create_simple_context
 from .core.data_map import DataMap, create_simple_api_tool, create_expression_tool
-from .core.state import StateManager, FileStateManager
 from signalwire_agents.agent_server import AgentServer
 from signalwire_agents.core.swml_service import SWMLService
 from signalwire_agents.core.swml_builder import SWMLBuilder
 from signalwire_agents.core.function_result import SwaigFunctionResult
 from signalwire_agents.core.swaig_function import SWAIGFunction
+from signalwire_agents.agents.bedrock import BedrockAgent
 
-# Import skills to trigger discovery
-import signalwire_agents.skills
+# Import WebService for static file serving
+from signalwire_agents.web import WebService
 
-# Import convenience functions from the CLI (if available)
-try:
-    from signalwire_agents.cli.helpers import start_agent, run_agent, list_skills
-except ImportError:
-    # CLI helpers not available, define minimal versions
-    def start_agent(*args, **kwargs):
+# Lazy import skills to avoid slow startup for CLI tools
+# Skills are now loaded on-demand when requested
+def _get_skill_registry():
+    """Lazy import and return skill registry"""
+    import signalwire_agents.skills
+    return signalwire_agents.skills.skill_registry
+
+# Lazy import convenience functions from the CLI (if available)
+def start_agent(*args, **kwargs):
+    """Start an agent (lazy import)"""
+    try:
+        from signalwire_agents.cli.helpers import start_agent as _start_agent
+        return _start_agent(*args, **kwargs)
+    except ImportError:
         raise NotImplementedError("CLI helpers not available")
-    def run_agent(*args, **kwargs):
+
+def run_agent(*args, **kwargs):
+    """Run an agent (lazy import)"""
+    try:
+        from signalwire_agents.cli.helpers import run_agent as _run_agent
+        return _run_agent(*args, **kwargs)
+    except ImportError:
         raise NotImplementedError("CLI helpers not available")
-    def list_skills(*args, **kwargs):
+
+def list_skills(*args, **kwargs):
+    """List available skills (lazy import)"""
+    try:
+        from signalwire_agents.cli.helpers import list_skills as _list_skills
+        return _list_skills(*args, **kwargs)
+    except ImportError:
         raise NotImplementedError("CLI helpers not available")
 
+def list_skills_with_params():
+    """
+    Get complete schema for all available skills including parameter metadata
+    
+    This function returns a comprehensive schema for all available skills,
+    including their metadata and parameter definitions. This is useful for
+    GUI configuration tools, API documentation, or programmatic skill discovery.
+    
+    Returns:
+        Dict[str, Dict[str, Any]]: Complete skill schema where keys are skill names
+        
+    Example:
+        >>> schema = list_skills_with_params()
+        >>> print(schema['web_search']['parameters']['api_key'])
+        {
+            'type': 'string',
+            'description': 'Google Custom Search API key',
+            'required': True,
+            'hidden': True,
+            'env_var': 'GOOGLE_SEARCH_API_KEY'
+        }
+    """
+    from signalwire_agents.skills.registry import skill_registry
+    return skill_registry.get_all_skills_schema()
+
+def register_skill(skill_class):
+    """
+    Register a custom skill class
+    
+    This allows third-party code to register skill classes directly without
+    requiring them to be in a specific directory structure.
+    
+    Args:
+        skill_class: A class that inherits from SkillBase
+        
+    Example:
+        >>> from my_custom_skills import MyWeatherSkill
+        >>> register_skill(MyWeatherSkill)
+        >>> # Now you can use it in agents:
+        >>> agent.add_skill('my_weather')
+    """
+    from signalwire_agents.skills.registry import skill_registry
+    return skill_registry.register_skill(skill_class)
+
+def add_skill_directory(path):
+    """
+    Add a directory to search for skills
+    
+    This allows third-party skill collections to be registered by path.
+    Skills in these directories should follow the same structure as built-in skills.
+    
+    Args:
+        path: Path to directory containing skill subdirectories
+        
+    Example:
+        >>> add_skill_directory('/opt/custom_skills')
+        >>> # Now agent.add_skill('my_custom_skill') will search in this directory
+    """
+    from signalwire_agents.skills.registry import skill_registry
+    return skill_registry.add_skill_directory(path)
+
 __all__ = [
     "AgentBase",
     "AgentServer", 
     "SWMLService",
     "SWMLBuilder",
-    "StateManager",
-    "FileStateManager",
     "SwaigFunctionResult",
     "SWAIGFunction",
     "DataMap",
@@ -62,7 +141,12 @@ __all__ = [
     "Context", 
     "Step",
     "create_simple_context",
+    "WebService",
     "start_agent",
     "run_agent",
-    "list_skills"
+    "list_skills",
+    "list_skills_with_params",
+    "register_skill",
+    "add_skill_directory",
+    "BedrockAgent"
 ]

signalwire_agents/agent_server.py

@@ -11,6 +11,7 @@ See LICENSE file in the project root for full license information.
 AgentServer - Class for hosting multiple SignalWire AI Agents in a single server
 """
 
+import os
 import re
 from typing import Dict, Any, Optional, List, Tuple, Callable
 
@@ -60,17 +61,28 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="0.1.2",
+            version="1.0.17.dev4",
             redirect_slashes=False
         )
         
         # Keep track of registered agents
         self.agents: Dict[str, AgentBase] = {}
-        
+
         # Keep track of SIP routing configuration
         self._sip_routing_enabled = False
         self._sip_route = None
         self._sip_username_mapping: Dict[str, str] = {}  # Maps SIP usernames to routes
+
+        # Register health endpoints immediately so they're available
+        # whether using server.run() or server.app with gunicorn
+        self._register_health_endpoints()
+
+        # Register catch-all handler on startup (not in __init__) so it runs AFTER
+        # all other routes are registered. This ensures custom routes like /get_token
+        # don't get overshadowed by the catch-all /{full_path:path} route.
+        @self.app.on_event("startup")
+        async def _setup_catch_all():
+            self._register_catch_all_handler()
     
     def register(self, agent: AgentBase, route: Optional[str] = None) -> None:
         """
@@ -99,12 +111,12 @@ class AgentServer:
             
         # Store the agent
         self.agents[route] = agent
-        
+
         # Get the router and register it using the standard approach
         # The agent's router already handles both trailing slash versions properly
         router = agent.as_router()
         self.app.include_router(router, prefix=route)
-        
+
         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
@@ -518,13 +530,13 @@ class AgentServer:
         sys.stdout.flush()
         
         return response
-    
-    def _run_server(self, host: Optional[str] = None, port: Optional[int] = None) -> None:
-        """Original server mode logic"""
-        if not self.agents:
-            self.logger.warning("Starting server with no registered agents")
-            
-        # Add a health check endpoint
+
+    def _register_health_endpoints(self) -> None:
+        """Register health and readiness endpoints.
+
+        Called during __init__ so endpoints are available whether using
+        server.run() or accessing server.app directly with gunicorn.
+        """
         @self.app.get("/health")
         def health_check():
             return {
@@ -532,8 +544,209 @@ class AgentServer:
                 "agents": len(self.agents),
                 "routes": list(self.agents.keys())
             }
-            
-        # Add catch-all route handler to handle both trailing slash and non-trailing slash versions
+
+        @self.app.get("/ready")
+        def readiness_check():
+            return {
+                "status": "ready",
+                "agents": len(self.agents)
+            }
+
+    def _run_server(self, host: Optional[str] = None, port: Optional[int] = None) -> None:
+        """Original server mode logic"""
+        if not self.agents:
+            self.logger.warning("Starting server with no registered agents")
+
+        # Set host and port
+        host = host or self.host
+        port = port or self.port
+        
+        # Check for SSL configuration from environment variables
+        ssl_enabled_env = os.environ.get('SWML_SSL_ENABLED', '').lower()
+        ssl_enabled = ssl_enabled_env in ('true', '1', 'yes')
+        ssl_cert_path = os.environ.get('SWML_SSL_CERT_PATH')
+        ssl_key_path = os.environ.get('SWML_SSL_KEY_PATH')
+        domain = os.environ.get('SWML_DOMAIN')
+        
+        # Validate SSL configuration if enabled
+        if ssl_enabled:
+            if not ssl_cert_path or not os.path.exists(ssl_cert_path):
+                self.logger.warning(f"SSL cert not found: {ssl_cert_path}")
+                ssl_enabled = False
+            elif not ssl_key_path or not os.path.exists(ssl_key_path):
+                self.logger.warning(f"SSL key not found: {ssl_key_path}")
+                ssl_enabled = False
+        
+        # Update server info display with correct protocol
+        protocol = "https" if ssl_enabled else "http"
+        
+        # Determine display host - include port unless it's the standard port for the protocol
+        if ssl_enabled and domain:
+            # Use domain, but include port if it's not the standard HTTPS port (443)
+            display_host = f"{domain}:{port}" if port != 443 else domain
+        else:
+            # Use host:port for HTTP or when no domain is specified
+            display_host = f"{host}:{port}"
+        
+        self.logger.info(f"Starting server on {protocol}://{display_host}")
+        for route, agent in self.agents.items():
+            username, password = agent.get_basic_auth_credentials()
+            agent_url = agent.get_full_url(include_auth=False)
+            self.logger.info(f"Agent '{agent.get_name()}' available at:")
+            self.logger.info(f"URL: {agent_url}")
+            self.logger.info(f"Basic Auth: {username}:{password}")
+        
+        # Start the server with or without SSL
+        if ssl_enabled and ssl_cert_path and ssl_key_path:
+            self.logger.info(f"Starting with SSL - cert: {ssl_cert_path}, key: {ssl_key_path}")
+            uvicorn.run(
+                self.app,
+                host=host,
+                port=port,
+                log_level=self.log_level,
+                ssl_certfile=ssl_cert_path,
+                ssl_keyfile=ssl_key_path
+            )
+        else:
+            uvicorn.run(
+                self.app,
+                host=host,
+                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")
+
+    def serve_static_files(self, directory: str, route: str = "/") -> None:
+        """
+        Serve static files from a directory.
+
+        This method properly integrates static file serving with agent routes,
+        ensuring that agent routes take priority over static files.
+
+        Unlike using StaticFiles.mount("/", ...) directly on self.app, this method
+        uses explicit route handlers that work correctly with agent routes.
+
+        Args:
+            directory: Path to the directory containing static files
+            route: URL path prefix for static files (default: "/" for root)
+
+        Example:
+            server = AgentServer()
+            server.register(SupportAgent(), "/support")
+            server.serve_static_files("./web")  # Serves at /
+            # /support -> SupportAgent
+            # /index.html -> ./web/index.html
+            # / -> ./web/index.html
+        """
+        from pathlib import Path
+        from fastapi.responses import FileResponse
+        from fastapi import HTTPException
+
+        # Normalize directory path
+        static_dir = Path(directory).resolve()
+
+        if not static_dir.exists():
+            raise ValueError(f"Directory does not exist: {directory}")
+
+        if not static_dir.is_dir():
+            raise ValueError(f"Path is not a directory: {directory}")
+
+        # Normalize route
+        if not route.startswith("/"):
+            route = f"/{route}"
+        route = route.rstrip("/")
+
+        # Store static directory config for use by catch-all handler
+        if not hasattr(self, '_static_directories'):
+            self._static_directories = {}
+
+        self._static_directories[route] = static_dir
+
+        self.logger.info(f"Serving static files from '{directory}' at route '{route or '/'}'")
+
+
+    def _serve_static_file(self, file_path: str, route: str = "/") -> Optional[Response]:
+        """
+        Internal method to serve a static file.
+
+        Args:
+            file_path: The requested file path
+            route: The route prefix
+
+        Returns:
+            FileResponse if file exists, None otherwise
+        """
+        from pathlib import Path
+        from fastapi.responses import FileResponse
+
+        if not hasattr(self, '_static_directories'):
+            return None
+
+        static_dir = self._static_directories.get(route)
+        if not static_dir:
+            return None
+
+        # Default to index.html for empty path
+        if not file_path:
+            file_path = "index.html"
+
+        full_path = static_dir / file_path
+
+        # Security: prevent path traversal
+        try:
+            full_path = full_path.resolve()
+            if not str(full_path).startswith(str(static_dir)):
+                return None
+        except Exception:
+            return None
+
+        # Handle directory requests
+        if full_path.is_dir():
+            index_path = full_path / "index.html"
+            if index_path.exists():
+                full_path = index_path
+            else:
+                return None
+
+        if not full_path.exists():
+            return None
+
+        return FileResponse(full_path)
+
+    def _register_catch_all_handler(self) -> None:
+        """
+        Register catch-all route handler for agent routing and static files.
+
+        This handler is needed for:
+        1. Routing requests without trailing slashes to agents (e.g., /santa instead of /santa/)
+        2. Serving static files from directories registered with serve_static_files()
+
+        Called via startup event (not __init__) to ensure it runs AFTER all other routes
+        are registered. This prevents the catch-all from overshadowing custom routes
+        like /get_token that users may add to server.app.
+        """
         @self.app.get("/{full_path:path}")
         @self.app.post("/{full_path:path}")
         async def handle_all_routes(request: Request, full_path: str):
@@ -548,11 +761,11 @@ class AgentServer:
                     # This is a request to an agent's sub-path
                     relative_path = full_path[len(route.lstrip("/")):]
                     relative_path = relative_path.lstrip("/")
-                    
+
                     # Route to appropriate handler based on path
                     if not relative_path or relative_path == "/":
                         return await agent._handle_root_request(request)
-                    
+
                     clean_path = relative_path.rstrip("/")
                     if clean_path == "debug":
                         return await agent._handle_debug_request(request)
@@ -563,7 +776,7 @@ class AgentServer:
                         return await agent._handle_post_prompt_request(request)
                     elif clean_path == "check_for_input":
                         return await agent._handle_check_for_input_request(request)
-                    
+
                     # Check for custom routing callbacks
                     if hasattr(agent, '_routing_callbacks'):
                         for callback_path, callback_fn in agent._routing_callbacks.items():
@@ -571,48 +784,23 @@ class AgentServer:
                             if clean_path == cb_path_clean:
                                 request.state.callback_path = callback_path
                                 return await agent._handle_root_request(request)
-            
-            # No matching agent found
-            return {"error": "Not Found"}
-            
-        # Print server info
-        host = host or self.host
-        port = port or self.port
-        
-        self.logger.info(f"Starting server on {host}:{port}")
-        for route, agent in self.agents.items():
-            username, password = agent.get_basic_auth_credentials()
-            self.logger.info(f"Agent '{agent.get_name()}' available at:")
-            self.logger.info(f"URL: http://{host}:{port}{route}")
-            self.logger.info(f"Basic Auth: {username}:{password}")
-            
-        # Start the server
-        uvicorn.run(
-            self.app,
-            host=host,
-            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")
+            # No matching agent - check for static files
+            if hasattr(self, '_static_directories'):
+                # Check each static directory route
+                for static_route, static_dir in self._static_directories.items():
+                    # For root static route, serve any unmatched path
+                    if static_route == "" or static_route == "/":
+                        response = self._serve_static_file(full_path, "")
+                        if response:
+                            return response
+                    # For prefixed static routes, check if path matches
+                    elif full_path.startswith(static_route.lstrip("/") + "/") or full_path == static_route.lstrip("/"):
+                        relative_path = full_path[len(static_route.lstrip("/")):].lstrip("/")
+                        response = self._serve_static_file(relative_path, static_route)
+                        if response:
+                            return response
+
+            # No matching agent or static file found
+            from fastapi import HTTPException
+            raise HTTPException(status_code=404, detail="Not Found")