signalwire-agents 0.1.23__py3-none-any.whl → 0.1.24__py3-none-any.whl

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__ = "0.1.23"
+__version__ = "0.1.24"
 
 # Import core classes for easier access
 from .core.agent_base import AgentBase

signalwire_agents/agent_server.py

@@ -610,8 +610,9 @@ class AgentServer:
         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: {protocol}://{display_host}{route}")
+            self.logger.info(f"URL: {agent_url}")
             self.logger.info(f"Basic Auth: {username}:{password}")
         
         # Start the server with or without SSL

signalwire_agents/cli/config.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""
+Configuration constants for the CLI tools
+"""
+
+# Default values for call configuration
+DEFAULT_CALL_TYPE = "webrtc"
+DEFAULT_CALL_DIRECTION = "inbound"
+DEFAULT_CALL_STATE = "created"
+DEFAULT_HTTP_METHOD = "POST"
+DEFAULT_TOKEN_EXPIRY = 3600
+
+# Default fake data values
+DEFAULT_PROJECT_ID = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+DEFAULT_SPACE_ID = "zzzzzzzz-yyyy-xxxx-wwww-vvvvvvvvvvvv"
+DEFAULT_SPACE_NAME = "example-space"
+DEFAULT_ENVIRONMENT = "production"
+
+# Request timeouts
+HTTP_REQUEST_TIMEOUT = 30
+
+# Output formatting
+RESULT_LINE_SEP = "-" * 60
+
+# Platform-specific constants
+SERVERLESS_PLATFORMS = ["lambda", "cgi", "cloud_function", "azure_function"]
+
+# AWS Lambda defaults
+AWS_DEFAULT_REGION = "us-east-1"
+AWS_DEFAULT_STAGE = "prod"
+
+# Google Cloud defaults
+GCP_DEFAULT_REGION = "us-central1"
+
+# Error messages
+ERROR_MISSING_AGENT = "Error: Missing required argument."
+ERROR_MULTIPLE_AGENTS = "Multiple agents found in file. Please specify --agent-class"
+ERROR_NO_AGENTS = "No agents found in file: {file_path}"
+ERROR_AGENT_NOT_FOUND = "Agent class '{class_name}' not found in file: {file_path}"
+ERROR_FUNCTION_NOT_FOUND = "Function '{function_name}' not found in agent"
+ERROR_CGI_HOST_REQUIRED = "CGI simulation requires --cgi-host"
+
+# Help messages
+HELP_DESCRIPTION = "Test SWAIG functions and generate SWML documents for SignalWire AI agents"
+HELP_EPILOG_SHORT = """
+examples:
+  # Execute a function
+  %(prog)s agent.py --exec search --query "test" --limit 5
+  
+  # Generate SWML
+  %(prog)s agent.py --dump-swml --raw | jq '.'
+  
+  # Test with specific agent
+  %(prog)s multi_agent.py --agent-class MattiAgent --list-tools
+  
+  # Simulate serverless
+  %(prog)s agent.py --simulate-serverless lambda --exec my_function
+
+For platform-specific options: %(prog)s --help-platforms
+For more examples: %(prog)s --help-examples
+"""

signalwire_agents/cli/core/__init__.py

@@ -0,0 +1 @@
+"""Core functionality for CLI tools"""

signalwire_agents/cli/core/agent_loader.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""
+Agent discovery and loading functionality
+"""
+
+import importlib.util
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+# Import after checking if available
+try:
+    from signalwire_agents.core.agent_base import AgentBase
+    AGENT_BASE_AVAILABLE = True
+except ImportError:
+    AgentBase = None
+    AGENT_BASE_AVAILABLE = False
+
+
+def discover_agents_in_file(agent_path: str) -> List[Dict[str, Any]]:
+    """
+    Discover all available agents in a Python file without instantiating them
+    
+    Args:
+        agent_path: Path to the Python file containing agents
+        
+    Returns:
+        List of dictionaries with agent information
+        
+    Raises:
+        ImportError: If the file cannot be imported
+        FileNotFoundError: If the file doesn't exist
+    """
+    if not AGENT_BASE_AVAILABLE:
+        raise ImportError("AgentBase not available. Please install signalwire-agents package.")
+    
+    agent_path = Path(agent_path).resolve()
+    
+    if not agent_path.exists():
+        raise FileNotFoundError(f"Agent file not found: {agent_path}")
+    
+    if not agent_path.suffix == '.py':
+        raise ValueError(f"Agent file must be a Python file (.py): {agent_path}")
+    
+    # Load the module, but prevent main() execution by setting __name__ to something other than "__main__"
+    spec = importlib.util.spec_from_file_location("agent_module", agent_path)
+    module = importlib.util.module_from_spec(spec)
+    
+    try:
+        # Set __name__ to prevent if __name__ == "__main__": blocks from running
+        module.__name__ = "agent_module"
+        spec.loader.exec_module(module)
+    except Exception as e:
+        raise ImportError(f"Failed to load agent module: {e}")
+    
+    agents_found = []
+    
+    # Look for AgentBase instances
+    for name, obj in vars(module).items():
+        if isinstance(obj, AgentBase):
+            agents_found.append({
+                'name': name,
+                'class_name': obj.__class__.__name__,
+                'type': 'instance',
+                'agent_name': getattr(obj, 'name', 'Unknown'),
+                'route': getattr(obj, 'route', 'Unknown'),
+                'description': obj.__class__.__doc__,
+                'object': obj
+            })
+    
+    # Look for AgentBase subclasses (that could be instantiated)
+    for name, obj in vars(module).items():
+        if (isinstance(obj, type) and 
+            issubclass(obj, AgentBase) and 
+            obj != AgentBase):
+            # Check if we already found an instance of this class
+            instance_found = any(agent['class_name'] == name for agent in agents_found)
+            if not instance_found:
+                try:
+                    # Try to get class information without instantiating
+                    agent_info = {
+                        'name': name,
+                        'class_name': name,
+                        'type': 'class',
+                        'agent_name': 'Unknown (not instantiated)',
+                        'route': 'Unknown (not instantiated)',
+                        'description': obj.__doc__,
+                        'object': obj
+                    }
+                    agents_found.append(agent_info)
+                except Exception:
+                    # If we can't get info, still record that the class exists
+                    agents_found.append({
+                        'name': name,
+                        'class_name': name,
+                        'type': 'class',
+                        'agent_name': 'Unknown (not instantiated)',
+                        'route': 'Unknown (not instantiated)',
+                        'description': obj.__doc__ or 'No description available',
+                        'object': obj
+                    })
+    
+    return agents_found
+
+
+def load_agent_from_file(agent_path: str, agent_class_name: Optional[str] = None) -> 'AgentBase':
+    """
+    Load an agent from a Python file
+    
+    Args:
+        agent_path: Path to the Python file containing the agent
+        agent_class_name: Optional name of the agent class to instantiate
+        
+    Returns:
+        AgentBase instance
+        
+    Raises:
+        ImportError: If the file cannot be imported
+        ValueError: If no agent is found in the file
+    """
+    if not AGENT_BASE_AVAILABLE:
+        raise ImportError("AgentBase not available. Please install signalwire-agents package.")
+    
+    agent_path = Path(agent_path).resolve()
+    
+    if not agent_path.exists():
+        raise FileNotFoundError(f"Agent file not found: {agent_path}")
+    
+    if not agent_path.suffix == '.py':
+        raise ValueError(f"Agent file must be a Python file (.py): {agent_path}")
+    
+    # Load the module, but prevent main() execution by setting __name__ to something other than "__main__"
+    spec = importlib.util.spec_from_file_location("agent_module", agent_path)
+    module = importlib.util.module_from_spec(spec)
+    
+    try:
+        # Set __name__ to prevent if __name__ == "__main__": blocks from running
+        module.__name__ = "agent_module"
+        spec.loader.exec_module(module)
+    except Exception as e:
+        raise ImportError(f"Failed to load agent module: {e}")
+    
+    # Find the agent instance
+    agent = None
+    
+    # If agent_class_name is specified, try to instantiate that specific class first
+    if agent_class_name:
+        if hasattr(module, agent_class_name):
+            obj = getattr(module, agent_class_name)
+            if isinstance(obj, type) and issubclass(obj, AgentBase) and obj != AgentBase:
+                try:
+                    agent = obj()
+                    if agent and not agent.route.endswith('dummy'):  # Avoid test agents with dummy routes
+                        pass  # Successfully created specific agent
+                    else:
+                        agent = obj()  # Create anyway if requested specifically
+                except Exception as e:
+                    raise ValueError(f"Failed to instantiate agent class '{agent_class_name}': {e}")
+            else:
+                raise ValueError(f"'{agent_class_name}' is not a valid AgentBase subclass")
+        else:
+            raise ValueError(f"Agent class '{agent_class_name}' not found in {agent_path}")
+    
+    # Strategy 1: Look for 'agent' variable (most common pattern)
+    if agent is None and hasattr(module, 'agent') and isinstance(module.agent, AgentBase):
+        agent = module.agent
+    
+    # Strategy 2: Look for any AgentBase instance in module globals
+    if agent is None:
+        agents_found = []
+        for name, obj in vars(module).items():
+            if isinstance(obj, AgentBase):
+                agents_found.append((name, obj))
+        
+        if len(agents_found) == 1:
+            agent = agents_found[0][1]
+        elif len(agents_found) > 1:
+            # Multiple agents found, prefer one named 'agent'
+            for name, obj in agents_found:
+                if name == 'agent':
+                    agent = obj
+                    break
+            # If no 'agent' variable, use the first one
+            if agent is None:
+                agent = agents_found[0][1]
+                print(f"Warning: Multiple agents found, using '{agents_found[0][0]}'")
+                print(f"Hint: Use --agent-class parameter to choose specific agent")
+    
+    # Strategy 3: Look for AgentBase subclass and try to instantiate it
+    if agent is None:
+        agent_classes_found = []
+        for name, obj in vars(module).items():
+            if (isinstance(obj, type) and 
+                issubclass(obj, AgentBase) and 
+                obj != AgentBase):
+                agent_classes_found.append((name, obj))
+        
+        if len(agent_classes_found) == 1:
+            try:
+                agent = agent_classes_found[0][1]()
+            except Exception as e:
+                print(f"Warning: Failed to instantiate {agent_classes_found[0][0]}: {e}")
+        elif len(agent_classes_found) > 1:
+            # Multiple agent classes found
+            class_names = [name for name, _ in agent_classes_found]
+            raise ValueError(f"Multiple agent classes found: {', '.join(class_names)}. "
+                           f"Please specify which agent class to use with --agent-class parameter. "
+                           f"Usage: swaig-test {agent_path} [tool_name] [args] --agent-class <AgentClassName>")
+        else:
+            # Try instantiating any AgentBase class we can find
+            for name, obj in vars(module).items():
+                if (isinstance(obj, type) and 
+                    issubclass(obj, AgentBase) and 
+                    obj != AgentBase):
+                    try:
+                        agent = obj()
+                        break
+                    except Exception as e:
+                        print(f"Warning: Failed to instantiate {name}: {e}")
+    
+    # Strategy 4: Try calling a modified main() function that doesn't start the server
+    if agent is None and hasattr(module, 'main'):
+        print("Warning: No agent instance found, attempting to call main() without server startup")
+        try:
+            # Temporarily patch AgentBase.serve to prevent server startup
+            original_serve = AgentBase.serve
+            captured_agent = []
+            
+            def mock_serve(self, *args, **kwargs):
+                captured_agent.append(self)
+                print(f"  (Intercepted serve() call, agent captured for testing)")
+                return self
+            
+            AgentBase.serve = mock_serve
+            
+            try:
+                result = module.main()
+                if isinstance(result, AgentBase):
+                    agent = result
+                elif captured_agent:
+                    agent = captured_agent[0]
+            finally:
+                # Restore original serve method
+                AgentBase.serve = original_serve
+                
+        except Exception as e:
+            print(f"Warning: Failed to call main() function: {e}")
+    
+    if agent is None:
+        raise ValueError(f"No agent found in {agent_path}. The file must contain either:\n"
+                        f"- An AgentBase instance (e.g., agent = MyAgent())\n"
+                        f"- An AgentBase subclass that can be instantiated\n"
+                        f"- A main() function that creates and returns an agent")
+    
+    return agent

signalwire_agents/cli/core/argparse_helpers.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+Custom argument parsing and function argument parsing
+"""
+
+import sys
+import argparse
+from typing import List, Dict, Any
+
+
+class CustomArgumentParser(argparse.ArgumentParser):
+    """Custom ArgumentParser with better error handling"""
+    
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._suppress_usage = False
+    
+    def _print_message(self, message, file=None):
+        """Override to suppress usage output for specific errors"""
+        if self._suppress_usage:
+            return
+        super()._print_message(message, file)
+    
+    def error(self, message):
+        """Override error method to provide user-friendly error messages"""
+        if "required" in message.lower() and "agent_path" in message:
+            self._suppress_usage = True
+            print("Error: Missing required argument.")
+            print()
+            print(f"Usage: {self.prog} <agent_path> [options]")
+            print()
+            print("Examples:")
+            print(f"  {self.prog} examples/my_agent.py --list-tools")
+            print(f"  {self.prog} examples/my_agent.py --dump-swml")
+            print(f"  {self.prog} examples/my_agent.py --exec my_function --param value")
+            print()
+            print(f"For full help: {self.prog} --help")
+            sys.exit(2)
+        else:
+            # For other errors, use the default behavior
+            super().error(message)
+    
+    def print_usage(self, file=None):
+        """Override print_usage to suppress output when we want custom error handling"""
+        if self._suppress_usage:
+            return
+        super().print_usage(file)
+    
+    def parse_args(self, args=None, namespace=None):
+        """Override parse_args to provide custom error handling for missing arguments"""
+        # Check if no arguments provided (just the program name)
+        if args is None:
+            args = sys.argv[1:]
+        
+        # If no arguments provided, show custom error
+        if not args:
+            print("Error: Missing required argument.")
+            print()
+            print(f"Usage: {self.prog} <agent_path> [options]")
+            print()
+            print("Examples:")
+            print(f"  {self.prog} examples/my_agent.py --list-tools")
+            print(f"  {self.prog} examples/my_agent.py --dump-swml")
+            print(f"  {self.prog} examples/my_agent.py --exec my_function --param value")
+            print()
+            print(f"For full help: {self.prog} --help")
+            sys.exit(2)
+        
+        # Otherwise, use default parsing
+        return super().parse_args(args, namespace)
+
+
+def parse_function_arguments(function_args_list: List[str], func_schema: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Parse function arguments from command line with type coercion based on schema
+    
+    Args:
+        function_args_list: List of command line arguments after --args
+        func_schema: Function schema with parameter definitions
+        
+    Returns:
+        Dictionary of parsed function arguments
+    """
+    parsed_args = {}
+    i = 0
+    
+    # Get parameter schema
+    parameters = {}
+    required_params = []
+    
+    if isinstance(func_schema, dict):
+        # DataMap function
+        if 'parameters' in func_schema:
+            params = func_schema['parameters']
+            if 'properties' in params:
+                parameters = params['properties']
+                required_params = params.get('required', [])
+            else:
+                parameters = params
+        else:
+            parameters = func_schema
+    else:
+        # Regular SWAIG function
+        if hasattr(func_schema, 'parameters') and func_schema.parameters:
+            params = func_schema.parameters
+            if 'properties' in params:
+                parameters = params['properties']
+                required_params = params.get('required', [])
+            else:
+                parameters = params
+    
+    # Parse arguments
+    while i < len(function_args_list):
+        arg = function_args_list[i]
+        
+        if arg.startswith('--'):
+            param_name = arg[2:]  # Remove --
+            
+            # Convert kebab-case to snake_case for parameter lookup
+            param_key = param_name.replace('-', '_')
+            
+            # Check if this parameter exists in schema
+            param_schema = parameters.get(param_key, {})
+            param_type = param_schema.get('type', 'string')
+            
+            if param_type == 'boolean':
+                # Check if next arg is a boolean value or if this is a flag
+                if i + 1 < len(function_args_list) and function_args_list[i + 1].lower() in ['true', 'false']:
+                    parsed_args[param_key] = function_args_list[i + 1].lower() == 'true'
+                    i += 2
+                else:
+                    # Treat as flag (present = true)
+                    parsed_args[param_key] = True
+                    i += 1
+            else:
+                # Need a value
+                if i + 1 >= len(function_args_list):
+                    raise ValueError(f"Parameter --{param_name} requires a value")
+                
+                value = function_args_list[i + 1]
+                
+                # Type coercion
+                if param_type == 'integer':
+                    try:
+                        parsed_args[param_key] = int(value)
+                    except ValueError:
+                        raise ValueError(f"Parameter --{param_name} must be an integer, got: {value}")
+                elif param_type == 'number':
+                    try:
+                        parsed_args[param_key] = float(value)
+                    except ValueError:
+                        raise ValueError(f"Parameter --{param_name} must be a number, got: {value}")
+                elif param_type == 'array':
+                    # Handle comma-separated arrays
+                    parsed_args[param_key] = [item.strip() for item in value.split(',')]
+                else:
+                    # String (default)
+                    parsed_args[param_key] = value
+                
+                i += 2
+        else:
+            raise ValueError(f"Expected parameter name starting with --, got: {arg}")
+    
+    return parsed_args

signalwire_agents/cli/core/dynamic_config.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""
+Apply dynamic configuration to agents
+"""
+
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from signalwire_agents.core.agent_base import AgentBase
+    from ..simulation.mock_env import MockRequest
+
+
+def apply_dynamic_config(agent: 'AgentBase', mock_request: Optional['MockRequest'] = None, verbose: bool = False) -> None:
+    """
+    Apply dynamic configuration callback if the agent has one
+    
+    Args:
+        agent: The agent instance
+        mock_request: Optional mock request object
+        verbose: Whether to print verbose output
+    """
+    # Check if dynamic config has already been applied to this agent
+    if hasattr(agent, '_dynamic_config_applied') and agent._dynamic_config_applied:
+        if verbose:
+            print("Dynamic configuration already applied, skipping...")
+        return
+    
+    # Check if agent has dynamic config callback
+    if hasattr(agent, '_dynamic_config_callback') and agent._dynamic_config_callback:
+        try:
+            # Create mock request data if not provided
+            if mock_request is None:
+                from ..simulation.mock_env import create_mock_request
+                mock_request = create_mock_request()
+            
+            # Extract request data
+            query_params = dict(mock_request.query_params)
+            body_params = {}  # Empty for GET requests
+            headers = dict(mock_request.headers)
+            
+            if verbose:
+                print("Applying dynamic configuration callback...")
+            
+            # Call the user's configuration callback directly with the agent
+            # This is what pc_builder_service.py expects - to get the agent itself
+            agent._dynamic_config_callback(query_params, body_params, headers, agent)
+            
+            # Mark that dynamic config has been applied to prevent duplicate application
+            agent._dynamic_config_applied = True
+            
+            if verbose:
+                print("Dynamic configuration callback applied successfully")
+                # Show loaded skills after dynamic config
+                skills = agent.list_skills()
+                if skills:
+                    print(f"Skills loaded by dynamic config: {', '.join(skills)}")
+                
+        except Exception as e:
+            if verbose:
+                print(f"Warning: Failed to apply dynamic configuration: {e}")
+                import traceback
+                traceback.print_exc()

signalwire_agents/cli/execution/__init__.py

@@ -0,0 +1 @@
+"""Function execution modules"""