signalwire-agents 0.1.8__tar.gz → 0.1.9__tar.gz

{signalwire_agents-0.1.8/signalwire_agents.egg-info → signalwire_agents-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.8
+Version: 0.1.9
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
 Project-URL: Homepage, https://github.com/signalwire/signalwire-ai-agents
@@ -24,6 +24,8 @@ 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
+Requires-Dist: beautifulsoup4==4.12.3
+Requires-Dist: pytz==2023.3
 Dynamic: license-file
 
 # SignalWire AI Agent SDK
@@ -42,6 +44,47 @@ A Python SDK for creating, hosting, and securing SignalWire AI agents as microse
 - **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
+- **Modular Skills System**: Add capabilities to agents with simple one-liner calls
+
+## Skills System
+
+The SignalWire Agents SDK includes a powerful modular skills system that allows you to add complex capabilities to your agents with simple one-liner calls:
+
+```python
+from signalwire_agents import AgentBase
+
+# Create an agent
+agent = AgentBase("My Assistant", route="/assistant")
+
+# Add skills with one-liners
+agent.add_skill("web_search")   # Web search capability
+agent.add_skill("datetime")     # Current date/time info  
+agent.add_skill("math")         # Mathematical calculations
+
+# Configure skills with parameters
+agent.add_skill("web_search", {
+    "num_results": 3,  # Get 3 search results
+    "delay": 0.5       # Small delay between requests
+})
+
+agent.serve()
+```
+
+### Available Built-in Skills
+
+- **web_search**: Google Custom Search API integration with web scraping
+- **datetime**: Current date and time with timezone support
+- **math**: Safe mathematical expression evaluation
+
+### Benefits
+
+- **One-liner integration**: `agent.add_skill("skill_name")`
+- **Configurable parameters**: `agent.add_skill("skill_name", {"param": "value"})`
+- **Automatic discovery**: Skills are automatically found from the skills directory
+- **Dependency validation**: Clear error messages for missing requirements
+- **Modular architecture**: Skills are self-contained and reusable
+
+For detailed documentation, see [Skills System README](docs/SKILLS_SYSTEM_README.md).
 
 ## Installation
 

{signalwire_agents-0.1.8 → signalwire_agents-0.1.9}/README.md

@@ -14,6 +14,47 @@ A Python SDK for creating, hosting, and securing SignalWire AI agents as microse
 - **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
+- **Modular Skills System**: Add capabilities to agents with simple one-liner calls
+
+## Skills System
+
+The SignalWire Agents SDK includes a powerful modular skills system that allows you to add complex capabilities to your agents with simple one-liner calls:
+
+```python
+from signalwire_agents import AgentBase
+
+# Create an agent
+agent = AgentBase("My Assistant", route="/assistant")
+
+# Add skills with one-liners
+agent.add_skill("web_search")   # Web search capability
+agent.add_skill("datetime")     # Current date/time info  
+agent.add_skill("math")         # Mathematical calculations
+
+# Configure skills with parameters
+agent.add_skill("web_search", {
+    "num_results": 3,  # Get 3 search results
+    "delay": 0.5       # Small delay between requests
+})
+
+agent.serve()
+```
+
+### Available Built-in Skills
+
+- **web_search**: Google Custom Search API integration with web scraping
+- **datetime**: Current date and time with timezone support
+- **math**: Safe mathematical expression evaluation
+
+### Benefits
+
+- **One-liner integration**: `agent.add_skill("skill_name")`
+- **Configurable parameters**: `agent.add_skill("skill_name", {"param": "value"})`
+- **Automatic discovery**: Skills are automatically found from the skills directory
+- **Dependency validation**: Clear error messages for missing requirements
+- **Modular architecture**: Skills are self-contained and reusable
+
+For detailed documentation, see [Skills System README](docs/SKILLS_SYSTEM_README.md).
 
 ## Installation
 

{signalwire_agents-0.1.8 → signalwire_agents-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire_agents"
-version = "0.1.8"
+version = "0.1.9"
 description = "SignalWire AI Agents SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}
@@ -31,13 +31,15 @@ dependencies = [
     "signalwire_pom==2.7.1",
     "structlog==25.3.0",
     "uvicorn==0.34.2",
+    "beautifulsoup4==4.12.3",
+    "pytz==2023.3",
 ]
 
 [project.urls]
 Homepage = "https://github.com/signalwire/signalwire-ai-agents"
 
 [tool.setuptools]
-packages = ["signalwire_agents", "signalwire_agents.prefabs", "signalwire_agents.utils", "signalwire_agents.core", "signalwire_agents.core.state", "signalwire_agents.core.security"]
+packages = ["signalwire_agents", "signalwire_agents.prefabs", "signalwire_agents.utils", "signalwire_agents.core", "signalwire_agents.core.state", "signalwire_agents.core.security", "signalwire_agents.skills", "signalwire_agents.skills.web_search", "signalwire_agents.skills.datetime", "signalwire_agents.skills.math"]
 include-package-data = true
 
 [tool.setuptools.package-data]

{signalwire_agents-0.1.8 → signalwire_agents-0.1.9}/signalwire_agents/__init__.py

@@ -14,7 +14,7 @@ SignalWire AI Agents SDK
 A package for building AI agents using SignalWire's AI and SWML capabilities.
 """
 
-__version__ = "0.1.8"
+__version__ = "0.1.9"
 
 # Import core classes for easier access
 from signalwire_agents.core.agent_base import AgentBase
@@ -23,4 +23,7 @@ from signalwire_agents.core.swml_service import SWMLService
 from signalwire_agents.core.swml_builder import SWMLBuilder
 from signalwire_agents.core.state import StateManager, FileStateManager
 
+# Import skills to trigger discovery
+import signalwire_agents.skills
+
 __all__ = ["AgentBase", "AgentServer", "SWMLService", "SWMLBuilder", "StateManager", "FileStateManager"]

{signalwire_agents-0.1.8 → signalwire_agents-0.1.9}/signalwire_agents/core/agent_base.py

@@ -75,6 +75,7 @@ from signalwire_agents.core.security.session_manager import SessionManager
 from signalwire_agents.core.state import StateManager, FileStateManager
 from signalwire_agents.core.swml_service import SWMLService
 from signalwire_agents.core.swml_handler import AIVerbHandler
+from signalwire_agents.core.skill_manager import SkillManager
 
 # Create a logger
 logger = structlog.get_logger("agent_base")
@@ -404,6 +405,9 @@ class AgentBase(SWMLService):
         
         # Dynamic configuration callback
         self._dynamic_config_callback = None
+        
+        # Initialize skill manager
+        self.skill_manager = SkillManager(self)
     
     def _process_prompt_sections(self):
         """
@@ -2792,3 +2796,39 @@ class AgentBase(SWMLService):
             self.log.info("proxy_url_manually_set", proxy_url_base=self._proxy_url_base)
             
         return self
+
+    # ----------------------------------------------------------------------
+    # Skill Management Methods
+    # ----------------------------------------------------------------------
+
+    def add_skill(self, skill_name: str, params: Optional[Dict[str, Any]] = None) -> 'AgentBase':
+        """
+        Add a skill to this agent
+        
+        Args:
+            skill_name: Name of the skill to add
+            params: Optional parameters to pass to the skill for configuration
+            
+        Returns:
+            Self for method chaining
+            
+        Raises:
+            ValueError: If skill not found or failed to load with detailed error message
+        """
+        success, error_message = self.skill_manager.load_skill(skill_name, params=params)
+        if not success:
+            raise ValueError(f"Failed to load skill '{skill_name}': {error_message}")
+        return self
+
+    def remove_skill(self, skill_name: str) -> 'AgentBase':
+        """Remove a skill from this agent"""
+        self.skill_manager.unload_skill(skill_name)
+        return self
+
+    def list_skills(self) -> List[str]:
+        """List currently loaded skills"""
+        return self.skill_manager.list_loaded_skills()
+
+    def has_skill(self, skill_name: str) -> bool:
+        """Check if skill is loaded"""
+        return self.skill_manager.has_skill(skill_name)

signalwire_agents-0.1.9/signalwire_agents/core/skill_base.py

@@ -0,0 +1,87 @@
+"""
+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.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, TYPE_CHECKING, Optional
+import logging
+
+if TYPE_CHECKING:
+    from signalwire_agents.core.agent_base import AgentBase
+
+class SkillBase(ABC):
+    """Abstract base class for all agent skills"""
+    
+    # Subclasses must define these
+    SKILL_NAME: str = None           # Required: unique identifier
+    SKILL_DESCRIPTION: str = None    # Required: human-readable description
+    SKILL_VERSION: str = "1.0.0"     # Semantic version
+    REQUIRED_PACKAGES: List[str] = [] # Python packages needed
+    REQUIRED_ENV_VARS: List[str] = [] # Environment variables needed
+    
+    def __init__(self, agent: 'AgentBase', params: Optional[Dict[str, Any]] = None):
+        if self.SKILL_NAME is None:
+            raise ValueError(f"{self.__class__.__name__} must define SKILL_NAME")
+        if self.SKILL_DESCRIPTION is None:
+            raise ValueError(f"{self.__class__.__name__} must define SKILL_DESCRIPTION")
+            
+        self.agent = agent
+        self.params = params or {}
+        self.logger = logging.getLogger(f"skill.{self.SKILL_NAME}")
+        
+    @abstractmethod
+    def setup(self) -> bool:
+        """
+        Setup the skill (validate env vars, initialize APIs, etc.)
+        Returns True if setup successful, False otherwise
+        """
+        pass
+        
+    @abstractmethod
+    def register_tools(self) -> None:
+        """Register SWAIG tools with the agent"""
+        pass
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints for this skill"""
+        return []
+        
+    def get_global_data(self) -> Dict[str, Any]:
+        """Return data to add to agent's global context"""
+        return {}
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return []
+        
+    def cleanup(self) -> None:
+        """Cleanup when skill is removed or agent shuts down"""
+        pass
+        
+    def validate_env_vars(self) -> bool:
+        """Check if all required environment variables are set"""
+        import os
+        missing = [var for var in self.REQUIRED_ENV_VARS if not os.getenv(var)]
+        if missing:
+            self.logger.error(f"Missing required environment variables: {missing}")
+            return False
+        return True
+        
+    def validate_packages(self) -> bool:
+        """Check if all required packages are available"""
+        import importlib
+        missing = []
+        for package in self.REQUIRED_PACKAGES:
+            try:
+                importlib.import_module(package)
+            except ImportError:
+                missing.append(package)
+        if missing:
+            self.logger.error(f"Missing required packages: {missing}")
+            return False
+        return True 

signalwire_agents-0.1.9/signalwire_agents/core/skill_manager.py

@@ -0,0 +1,136 @@
+"""
+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.
+"""
+
+from typing import Dict, List, Type, Any, Optional
+import logging
+from signalwire_agents.core.skill_base import SkillBase
+
+class SkillManager:
+    """Manages loading and lifecycle of agent skills"""
+    
+    def __init__(self, agent):
+        self.agent = agent
+        self.loaded_skills: Dict[str, SkillBase] = {}
+        self.logger = logging.getLogger("skill_manager")
+        
+    def load_skill(self, skill_name: str, skill_class: Type[SkillBase] = None, params: Optional[Dict[str, Any]] = None) -> tuple[bool, str]:
+        """
+        Load and setup a skill by name
+        
+        Args:
+            skill_name: Name of the skill to load
+            skill_class: Optional skill class (if not provided, will try to find it)
+            params: Optional parameters to pass to the skill
+            
+        Returns:
+            tuple: (success, error_message) - error_message is empty string if successful
+        """
+        if skill_name in self.loaded_skills:
+            self.logger.warning(f"Skill '{skill_name}' is already loaded")
+            return True, ""
+            
+        # Get skill class from registry if not provided
+        if skill_class is None:
+            try:
+                from signalwire_agents.skills.registry import skill_registry
+                skill_class = skill_registry.get_skill_class(skill_name)
+                if skill_class is None:
+                    error_msg = f"Skill '{skill_name}' not found in registry"
+                    self.logger.error(error_msg)
+                    return False, error_msg
+            except ImportError:
+                error_msg = f"Skills registry not available. Cannot load skill '{skill_name}'"
+                self.logger.error(error_msg)
+                return False, error_msg
+        
+        try:
+            # Create skill instance with parameters
+            skill_instance = skill_class(self.agent, params)
+            
+            # Validate environment variables with specific error details
+            import os
+            missing_env_vars = [var for var in skill_instance.REQUIRED_ENV_VARS if not os.getenv(var)]
+            if missing_env_vars:
+                error_msg = f"Missing required environment variables: {missing_env_vars}"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Validate packages with specific error details  
+            import importlib
+            missing_packages = []
+            for package in skill_instance.REQUIRED_PACKAGES:
+                try:
+                    importlib.import_module(package)
+                except ImportError:
+                    missing_packages.append(package)
+            if missing_packages:
+                error_msg = f"Missing required packages: {missing_packages}"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Setup the skill
+            if not skill_instance.setup():
+                error_msg = f"Failed to setup skill '{skill_name}'"
+                self.logger.error(error_msg)
+                return False, error_msg
+                
+            # Register tools with agent
+            skill_instance.register_tools()
+            
+            # Add hints and global data to agent
+            hints = skill_instance.get_hints()
+            if hints:
+                self.agent.add_hints(hints)
+                
+            global_data = skill_instance.get_global_data()
+            if global_data:
+                self.agent.update_global_data(global_data)
+                
+            # Add prompt sections
+            prompt_sections = skill_instance.get_prompt_sections()
+            for section in prompt_sections:
+                self.agent.prompt_add_section(**section)
+            
+            # Store loaded skill
+            self.loaded_skills[skill_name] = skill_instance
+            self.logger.info(f"Successfully loaded skill '{skill_name}'")
+            return True, ""
+            
+        except Exception as e:
+            error_msg = f"Error loading skill '{skill_name}': {e}"
+            self.logger.error(error_msg)
+            return False, error_msg
+    
+    def unload_skill(self, skill_name: str) -> bool:
+        """Unload a skill and cleanup"""
+        if skill_name not in self.loaded_skills:
+            self.logger.warning(f"Skill '{skill_name}' is not loaded")
+            return False
+            
+        try:
+            skill_instance = self.loaded_skills[skill_name]
+            skill_instance.cleanup()
+            del self.loaded_skills[skill_name]
+            self.logger.info(f"Successfully unloaded skill '{skill_name}'")
+            return True
+        except Exception as e:
+            self.logger.error(f"Error unloading skill '{skill_name}': {e}")
+            return False
+    
+    def list_loaded_skills(self) -> List[str]:
+        """List names of currently loaded skills"""
+        return list(self.loaded_skills.keys())
+    
+    def has_skill(self, skill_name: str) -> bool:
+        """Check if skill is currently loaded"""
+        return skill_name in self.loaded_skills
+    
+    def get_skill(self, skill_name: str) -> Optional[SkillBase]:
+        """Get a loaded skill instance by name"""
+        return self.loaded_skills.get(skill_name) 

signalwire_agents-0.1.9/signalwire_agents/skills/__init__.py

@@ -0,0 +1,14 @@
+"""
+SignalWire Agent Skills Package
+
+This package contains built-in skills for SignalWire agents.
+Skills are automatically discovered from subdirectories.
+"""
+
+# Import the registry to make it available
+from .registry import skill_registry
+
+# Trigger skill discovery on import
+skill_registry.discover_skills()
+
+__all__ = ["skill_registry"] 

signalwire_agents-0.1.9/signalwire_agents/skills/datetime/__init__.py

@@ -0,0 +1 @@
+"""DateTime Skill for SignalWire Agents""" 

signalwire_agents-0.1.9/signalwire_agents/skills/datetime/skill.py

@@ -0,0 +1,109 @@
+"""
+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.
+"""
+
+from datetime import datetime, timezone
+import pytz
+from typing import List, Dict, Any
+
+from signalwire_agents.core.skill_base import SkillBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+class DateTimeSkill(SkillBase):
+    """Provides current date, time, and timezone information"""
+    
+    SKILL_NAME = "datetime"
+    SKILL_DESCRIPTION = "Get current date, time, and timezone information"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = ["pytz"]
+    REQUIRED_ENV_VARS = []
+    
+    def setup(self) -> bool:
+        """Setup the datetime skill"""
+        return self.validate_packages()
+        
+    def register_tools(self) -> None:
+        """Register datetime tools with the agent"""
+        
+        self.agent.define_tool(
+            name="get_current_time",
+            description="Get the current time, optionally in a specific timezone",
+            parameters={
+                "timezone": {
+                    "type": "string",
+                    "description": "Timezone name (e.g., 'America/New_York', 'Europe/London'). Defaults to UTC."
+                }
+            },
+            handler=self._get_time_handler
+        )
+        
+        self.agent.define_tool(
+            name="get_current_date",
+            description="Get the current date",
+            parameters={
+                "timezone": {
+                    "type": "string", 
+                    "description": "Timezone name for the date. Defaults to UTC."
+                }
+            },
+            handler=self._get_date_handler
+        )
+        
+    def _get_time_handler(self, args, raw_data):
+        """Handler for get_current_time tool"""
+        timezone_name = args.get("timezone", "UTC")
+        
+        try:
+            if timezone_name.upper() == "UTC":
+                tz = timezone.utc
+            else:
+                tz = pytz.timezone(timezone_name)
+                
+            now = datetime.now(tz)
+            time_str = now.strftime("%I:%M:%S %p %Z")
+            
+            return SwaigFunctionResult(f"The current time is {time_str}")
+            
+        except Exception as e:
+            return SwaigFunctionResult(f"Error getting time: {str(e)}")
+    
+    def _get_date_handler(self, args, raw_data):
+        """Handler for get_current_date tool"""
+        timezone_name = args.get("timezone", "UTC")
+        
+        try:
+            if timezone_name.upper() == "UTC":
+                tz = timezone.utc
+            else:
+                tz = pytz.timezone(timezone_name)
+                
+            now = datetime.now(tz)
+            date_str = now.strftime("%A, %B %d, %Y")
+            
+            return SwaigFunctionResult(f"Today's date is {date_str}")
+            
+        except Exception as e:
+            return SwaigFunctionResult(f"Error getting date: {str(e)}")
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        return ["time", "date", "today", "now", "current", "timezone"]
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return [
+            {
+                "title": "Date and Time Information", 
+                "body": "You can provide current date and time information.",
+                "bullets": [
+                    "Use get_current_time to tell users what time it is",
+                    "Use get_current_date to tell users today's date",
+                    "Both tools support different timezones"
+                ]
+            }
+        ] 

signalwire_agents-0.1.9/signalwire_agents/skills/math/__init__.py

@@ -0,0 +1 @@
+"""Math Skill for SignalWire Agents""" 

signalwire_agents-0.1.9/signalwire_agents/skills/math/skill.py

@@ -0,0 +1,88 @@
+"""
+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.
+"""
+
+import re
+from typing import List, Dict, Any
+
+from signalwire_agents.core.skill_base import SkillBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+class MathSkill(SkillBase):
+    """Provides basic mathematical calculation capabilities"""
+    
+    SKILL_NAME = "math"
+    SKILL_DESCRIPTION = "Perform basic mathematical calculations"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = []
+    REQUIRED_ENV_VARS = []
+    
+    def setup(self) -> bool:
+        """Setup the math skill"""
+        return True
+        
+    def register_tools(self) -> None:
+        """Register math tools with the agent"""
+        
+        self.agent.define_tool(
+            name="calculate",
+            description="Perform a mathematical calculation with basic operations (+, -, *, /, %, **)",
+            parameters={
+                "expression": {
+                    "type": "string",
+                    "description": "Mathematical expression to evaluate (e.g., '2 + 3 * 4', '(10 + 5) / 3')"
+                }
+            },
+            handler=self._calculate_handler
+        )
+        
+    def _calculate_handler(self, args, raw_data):
+        """Handler for calculate tool"""
+        expression = args.get("expression", "").strip()
+        
+        if not expression:
+            return SwaigFunctionResult("Please provide a mathematical expression to calculate.")
+        
+        # Security: only allow safe mathematical operations
+        safe_chars = re.compile(r'^[0-9+\-*/().\s%**]+$')
+        if not safe_chars.match(expression):
+            return SwaigFunctionResult(
+                "Invalid expression. Only numbers and basic math operators (+, -, *, /, %, **, parentheses) are allowed."
+            )
+        
+        try:
+            # Evaluate the expression safely
+            result = eval(expression, {"__builtins__": {}}, {})
+            
+            return SwaigFunctionResult(f"{expression} = {result}")
+            
+        except ZeroDivisionError:
+            return SwaigFunctionResult("Error: Division by zero is not allowed.")
+        except Exception as e:
+            return SwaigFunctionResult(f"Error calculating '{expression}': Invalid expression")
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        return [
+            "calculate", "math", "plus", "minus", "times", "multiply", 
+            "divide", "equals", "percent", "power", "squared"
+        ]
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return [
+            {
+                "title": "Mathematical Calculations",
+                "body": "You can perform mathematical calculations for users.",
+                "bullets": [
+                    "Use the calculate tool for any math expressions",
+                    "Supports basic operations: +, -, *, /, %, ** (power)",
+                    "Can handle parentheses for complex expressions"
+                ]
+            }
+        ] 

signalwire_agents-0.1.9/signalwire_agents/skills/registry.py

@@ -0,0 +1,98 @@
+"""
+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.
+"""
+
+import os
+import importlib
+import importlib.util
+import inspect
+from typing import Dict, List, Type, Optional
+from pathlib import Path
+import logging
+
+from signalwire_agents.core.skill_base import SkillBase
+
+class SkillRegistry:
+    """Global registry for discovering and managing skills"""
+    
+    def __init__(self):
+        self._skills: Dict[str, Type[SkillBase]] = {}
+        self.logger = logging.getLogger("skill_registry")
+        self._discovered = False
+    
+    def discover_skills(self) -> None:
+        """Discover skills from the skills directory"""
+        if self._discovered:
+            return
+            
+        # Get the skills directory path
+        skills_dir = Path(__file__).parent
+        
+        # Scan for skill directories
+        for item in skills_dir.iterdir():
+            if item.is_dir() and not item.name.startswith('__'):
+                self._load_skill_from_directory(item)
+        
+        self._discovered = True
+        self.logger.info(f"Discovered {len(self._skills)} skills")
+    
+    def _load_skill_from_directory(self, skill_dir: Path) -> None:
+        """Load a skill from a directory"""
+        skill_file = skill_dir / "skill.py"
+        if not skill_file.exists():
+            return
+            
+        try:
+            # Import the skill module
+            module_name = f"signalwire_agents.skills.{skill_dir.name}.skill"
+            spec = importlib.util.spec_from_file_location(module_name, skill_file)
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+            
+            # Find SkillBase subclasses in the module
+            for name, obj in inspect.getmembers(module):
+                if (inspect.isclass(obj) and 
+                    issubclass(obj, SkillBase) and 
+                    obj != SkillBase and
+                    obj.SKILL_NAME is not None):
+                    
+                    self.register_skill(obj)
+                    
+        except Exception as e:
+            self.logger.error(f"Failed to load skill from {skill_dir}: {e}")
+    
+    def register_skill(self, skill_class: Type[SkillBase]) -> None:
+        """Register a skill class"""
+        if skill_class.SKILL_NAME in self._skills:
+            self.logger.warning(f"Skill '{skill_class.SKILL_NAME}' already registered")
+            return
+            
+        self._skills[skill_class.SKILL_NAME] = skill_class
+        self.logger.debug(f"Registered skill '{skill_class.SKILL_NAME}'")
+    
+    def get_skill_class(self, skill_name: str) -> Optional[Type[SkillBase]]:
+        """Get skill class by name"""
+        self.discover_skills()  # Ensure skills are discovered
+        return self._skills.get(skill_name)
+    
+    def list_skills(self) -> List[Dict[str, str]]:
+        """List all registered skills with metadata"""
+        self.discover_skills()
+        return [
+            {
+                "name": skill_class.SKILL_NAME,
+                "description": skill_class.SKILL_DESCRIPTION,
+                "version": skill_class.SKILL_VERSION,
+                "required_packages": skill_class.REQUIRED_PACKAGES,
+                "required_env_vars": skill_class.REQUIRED_ENV_VARS
+            }
+            for skill_class in self._skills.values()
+        ]
+
+# Global registry instance
+skill_registry = SkillRegistry() 

signalwire_agents-0.1.9/signalwire_agents/skills/web_search/__init__.py

@@ -0,0 +1 @@
+"""Web Search Skill for SignalWire Agents""" 

signalwire_agents-0.1.9/signalwire_agents/skills/web_search/skill.py

@@ -0,0 +1,240 @@
+"""
+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.
+"""
+
+import os
+import requests
+import time
+from urllib.parse import urljoin, urlparse
+from bs4 import BeautifulSoup
+import json
+from typing import Optional, List, Dict, Any
+
+from signalwire_agents.core.skill_base import SkillBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+class GoogleSearchScraper:
+    """Google Search and Web Scraping functionality"""
+    
+    def __init__(self, api_key: str, search_engine_id: str):
+        self.api_key = api_key
+        self.search_engine_id = search_engine_id
+        self.session = requests.Session()
+        self.session.headers.update({
+            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'
+        })
+
+    def search_google(self, query: str, num_results: int = 5) -> list:
+        """Search Google using Custom Search JSON API"""
+        url = "https://www.googleapis.com/customsearch/v1"
+        
+        params = {
+            'key': self.api_key,
+            'cx': self.search_engine_id,
+            'q': query,
+            'num': min(num_results, 10)
+        }
+        
+        try:
+            response = self.session.get(url, params=params)
+            response.raise_for_status()
+            data = response.json()
+            
+            if 'items' not in data:
+                return []
+            
+            results = []
+            for item in data['items'][:num_results]:
+                results.append({
+                    'title': item.get('title', ''),
+                    'url': item.get('link', ''),
+                    'snippet': item.get('snippet', '')
+                })
+            
+            return results
+            
+        except Exception as e:
+            return []
+
+    def extract_text_from_url(self, url: str, timeout: int = 10) -> str:
+        """Scrape a URL and extract readable text content"""
+        try:
+            response = self.session.get(url, timeout=timeout)
+            response.raise_for_status()
+            
+            soup = BeautifulSoup(response.content, 'html.parser')
+            
+            # Remove unwanted elements
+            for script in soup(["script", "style", "nav", "footer", "header", "aside"]):
+                script.decompose()
+            
+            text = soup.get_text()
+            
+            # Clean up the text
+            lines = (line.strip() for line in text.splitlines())
+            chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
+            text = ' '.join(chunk for chunk in chunks if chunk)
+            
+            # Limit text length
+            if len(text) > 2000:
+                text = text[:2000] + "... [Content truncated]"
+            
+            return text
+            
+        except Exception as e:
+            return ""
+
+    def search_and_scrape(self, query: str, num_results: int = 3, delay: float = 0.5) -> str:
+        """Main function: search Google and scrape the resulting pages"""
+        search_results = self.search_google(query, num_results)
+        
+        if not search_results:
+            return f"No search results found for query: {query}"
+        
+        all_text = []
+        
+        for i, result in enumerate(search_results, 1):
+            text_content = f"=== RESULT {i} ===\n"
+            text_content += f"Title: {result['title']}\n"
+            text_content += f"URL: {result['url']}\n"
+            text_content += f"Snippet: {result['snippet']}\n"
+            text_content += f"Content:\n"
+            
+            page_text = self.extract_text_from_url(result['url'])
+            
+            if page_text:
+                text_content += page_text
+            else:
+                text_content += "Failed to extract content from this page."
+            
+            text_content += f"\n{'='*50}\n\n"
+            all_text.append(text_content)
+            
+            if i < len(search_results):
+                time.sleep(delay)
+        
+        return '\n'.join(all_text)
+
+
+class WebSearchSkill(SkillBase):
+    """Web search capability using Google Custom Search API"""
+    
+    SKILL_NAME = "web_search"
+    SKILL_DESCRIPTION = "Search the web for information using Google Custom Search API"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = ["bs4", "requests"]
+    REQUIRED_ENV_VARS = ["GOOGLE_SEARCH_API_KEY", "GOOGLE_SEARCH_ENGINE_ID"]
+    
+    def setup(self) -> bool:
+        """Setup the web search skill"""
+        if not self.validate_env_vars() or not self.validate_packages():
+            return False
+            
+        # Set default parameters
+        self.default_num_results = self.params.get('num_results', 1)
+        self.default_delay = self.params.get('delay', 0)
+        
+        # Initialize the search scraper
+        self.search_scraper = GoogleSearchScraper(
+            api_key=os.getenv('GOOGLE_SEARCH_API_KEY'),
+            search_engine_id=os.getenv('GOOGLE_SEARCH_ENGINE_ID')
+        )
+        
+        return True
+        
+    def register_tools(self) -> None:
+        """Register web search tool with the agent"""
+        self.agent.define_tool(
+            name="web_search",
+            description="Search the web for information on any topic and return detailed results with content from multiple sources",
+            parameters={
+                "query": {
+                    "type": "string",
+                    "description": "The search query - what you want to find information about"
+                },
+                "num_results": {
+                    "type": "integer", 
+                    "description": f"Number of web pages to search and extract content from (1-10, default: {self.default_num_results})",
+                    "minimum": 1,
+                    "maximum": 10
+                }
+            },
+            handler=self._web_search_handler
+        )
+        
+    def _web_search_handler(self, args, raw_data):
+        """Handler for web search tool"""
+        query = args.get("query", "").strip()
+        num_results = args.get("num_results", self.default_num_results)
+        
+        if not query:
+            return SwaigFunctionResult(
+                "Please provide a search query. What would you like me to search for?"
+            )
+        
+        # Validate num_results
+        try:
+            num_results = int(num_results)
+            num_results = max(1, min(num_results, 10))
+        except (ValueError, TypeError):
+            num_results = self.default_num_results
+        
+        self.logger.info(f"Web search requested: '{query}' ({num_results} results)")
+        
+        # Perform the search
+        try:
+            search_results = self.search_scraper.search_and_scrape(
+                query=query,
+                num_results=num_results,
+                delay=self.default_delay
+            )
+            
+            if not search_results or "No search results found" in search_results:
+                return SwaigFunctionResult(
+                    f"I couldn't find any results for '{query}'. "
+                    "This might be due to a very specific query or temporary issues. "
+                    "Try rephrasing your search or asking about a different topic."
+                )
+            
+            response = f"I found {num_results} results for '{query}':\n\n{search_results}"
+            return SwaigFunctionResult(response)
+            
+        except Exception as e:
+            self.logger.error(f"Error performing web search: {e}")
+            return SwaigFunctionResult(
+                "Sorry, I encountered an error while searching. Please try again later."
+            )
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        return [
+            "Google", "search", "internet", "web", "information",
+            "find", "look up", "research", "query", "results"
+        ]
+        
+    def get_global_data(self) -> Dict[str, Any]:
+        """Return global data for agent context"""
+        return {
+            "web_search_enabled": True,
+            "search_provider": "Google Custom Search"
+        }
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return [
+            {
+                "title": "Web Search Capability",
+                "body": "You can search the internet for current, accurate information on any topic.",
+                "bullets": [
+                    "Use the web_search tool when users ask for information you need to look up",
+                    "Search for news, current events, product information, or any current data",
+                    "Summarize search results in a clear, helpful way",
+                    "Include relevant URLs so users can read more if interested"
+                ]
+            }
+        ] 

{signalwire_agents-0.1.8 → signalwire_agents-0.1.9/signalwire_agents.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.8
+Version: 0.1.9
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
 Project-URL: Homepage, https://github.com/signalwire/signalwire-ai-agents
@@ -24,6 +24,8 @@ 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
+Requires-Dist: beautifulsoup4==4.12.3
+Requires-Dist: pytz==2023.3
 Dynamic: license-file
 
 # SignalWire AI Agent SDK
@@ -42,6 +44,47 @@ A Python SDK for creating, hosting, and securing SignalWire AI agents as microse
 - **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
+- **Modular Skills System**: Add capabilities to agents with simple one-liner calls
+
+## Skills System
+
+The SignalWire Agents SDK includes a powerful modular skills system that allows you to add complex capabilities to your agents with simple one-liner calls:
+
+```python
+from signalwire_agents import AgentBase
+
+# Create an agent
+agent = AgentBase("My Assistant", route="/assistant")
+
+# Add skills with one-liners
+agent.add_skill("web_search")   # Web search capability
+agent.add_skill("datetime")     # Current date/time info  
+agent.add_skill("math")         # Mathematical calculations
+
+# Configure skills with parameters
+agent.add_skill("web_search", {
+    "num_results": 3,  # Get 3 search results
+    "delay": 0.5       # Small delay between requests
+})
+
+agent.serve()
+```
+
+### Available Built-in Skills
+
+- **web_search**: Google Custom Search API integration with web scraping
+- **datetime**: Current date and time with timezone support
+- **math**: Safe mathematical expression evaluation
+
+### Benefits
+
+- **One-liner integration**: `agent.add_skill("skill_name")`
+- **Configurable parameters**: `agent.add_skill("skill_name", {"param": "value"})`
+- **Automatic discovery**: Skills are automatically found from the skills directory
+- **Dependency validation**: Clear error messages for missing requirements
+- **Modular architecture**: Skills are self-contained and reusable
+
+For detailed documentation, see [Skills System README](docs/SKILLS_SYSTEM_README.md).
 
 ## Installation
 

{signalwire_agents-0.1.8 → signalwire_agents-0.1.9}/signalwire_agents.egg-info/SOURCES.txt

@@ -15,6 +15,8 @@ signalwire_agents/core/__init__.py
 signalwire_agents/core/agent_base.py
 signalwire_agents/core/function_result.py
 signalwire_agents/core/pom_builder.py
+signalwire_agents/core/skill_base.py
+signalwire_agents/core/skill_manager.py
 signalwire_agents/core/swaig_function.py
 signalwire_agents/core/swml_builder.py
 signalwire_agents/core/swml_handler.py
@@ -31,6 +33,14 @@ signalwire_agents/prefabs/faq_bot.py
 signalwire_agents/prefabs/info_gatherer.py
 signalwire_agents/prefabs/receptionist.py
 signalwire_agents/prefabs/survey.py
+signalwire_agents/skills/__init__.py
+signalwire_agents/skills/registry.py
+signalwire_agents/skills/datetime/__init__.py
+signalwire_agents/skills/datetime/skill.py
+signalwire_agents/skills/math/__init__.py
+signalwire_agents/skills/math/skill.py
+signalwire_agents/skills/web_search/__init__.py
+signalwire_agents/skills/web_search/skill.py
 signalwire_agents/utils/__init__.py
 signalwire_agents/utils/pom_utils.py
 signalwire_agents/utils/schema_utils.py

{signalwire_agents-0.1.8 → signalwire_agents-0.1.9}/signalwire_agents.egg-info/requires.txt

@@ -6,3 +6,5 @@ setuptools==66.1.1
 signalwire_pom==2.7.1
 structlog==25.3.0
 uvicorn==0.34.2
+beautifulsoup4==4.12.3
+pytz==2023.3