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

signalwire_agents/skills/weather_api/skill.py

@@ -0,0 +1,191 @@
+"""
+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.
+"""
+
+"""
+Weather API Skill
+
+A configurable skill for getting weather information from WeatherAPI.com with customizable
+temperature units and TTS-friendly responses.
+"""
+
+from typing import Dict, Any, List
+from signalwire_agents.core import SwaigFunctionResult
+from signalwire_agents.core.skill_base import SkillBase
+
+
+class WeatherApiSkill(SkillBase):
+    """
+    Skill for getting weather information from WeatherAPI.com.
+    
+    Provides current weather data with configurable temperature units and
+    TTS-optimized natural language responses.
+    
+    Configuration:
+    - tool_name: Custom name for the generated SWAIG function
+    - api_key: WeatherAPI.com API key
+    - temperature_unit: "fahrenheit" or "celsius" for temperature display
+    
+    Example:
+        agent.add_skill("weather_api", {
+            "tool_name": "get_weather",
+            "api_key": "your_weatherapi_key",
+            "temperature_unit": "fahrenheit"
+        })
+    """
+    
+    SKILL_NAME = "weather_api"
+    SKILL_DESCRIPTION = "Get current weather information from WeatherAPI.com"
+    SUPPORTS_MULTIPLE_INSTANCES = False
+    REQUIRED_ENV_VARS = []  # API key can be passed via params
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """Get parameter schema for weather API skill"""
+        schema = super().get_parameter_schema()
+        schema.update({
+            "api_key": {
+                "type": "string",
+                "description": "WeatherAPI.com API key",
+                "required": True,
+                "hidden": True,
+                "env_var": "WEATHER_API_KEY"
+            },
+            "tool_name": {
+                "type": "string",
+                "description": "Custom name for the weather tool",
+                "default": "get_weather",
+                "required": False
+            },
+            "temperature_unit": {
+                "type": "string",
+                "description": "Temperature unit to display",
+                "default": "fahrenheit",
+                "required": False,
+                "enum": ["fahrenheit", "celsius"]
+            }
+        })
+        return schema
+    
+    def __init__(self, agent, params: Dict[str, Any] = None):
+        """
+        Initialize the skill with configuration parameters.
+        
+        Args:
+            agent: The agent instance this skill belongs to
+            params: Configuration dictionary containing:
+                - tool_name: Custom tool name (default: "get_weather")
+                - api_key: WeatherAPI.com API key (required)
+                - temperature_unit: "fahrenheit" or "celsius" (default: "fahrenheit")
+        """
+        super().__init__(agent, params)
+        
+        # Extract configuration
+        self.tool_name = self.params.get('tool_name', 'get_weather')
+        self.api_key = self.params.get('api_key')
+        self.temperature_unit = self.params.get('temperature_unit', 'fahrenheit')
+        
+        # Validate configuration
+        self._validate_config()
+    
+    def _validate_config(self):
+        """Validate the skill configuration."""
+        # Validate API key
+        if not self.api_key or not isinstance(self.api_key, str):
+            raise ValueError("api_key parameter is required and must be a non-empty string")
+        
+        # Validate temperature unit
+        if self.temperature_unit not in ['fahrenheit', 'celsius']:
+            raise ValueError("temperature_unit must be either 'fahrenheit' or 'celsius'")
+    
+    def setup(self) -> bool:
+        """
+        Setup the skill - validates API key is available.
+        
+        Returns:
+            True if setup successful
+        """
+        # API key validation already done in _validate_config
+        return True
+    
+    def register_tools(self) -> None:
+        """Register SWAIG tools with the agent"""
+        tools = self.get_tools()
+        for tool in tools:
+            # Merge any swaig_fields from params into the tool
+            if self.swaig_fields:
+                tool.update(self.swaig_fields)
+            self.agent.register_swaig_function(tool)
+    
+    def get_tools(self) -> List[Dict[str, Any]]:
+        """
+        Generate the SWAIG tool with DataMap webhook.
+        
+        Returns:
+            List containing the generated tool configuration
+        """
+        # Determine temperature fields based on unit
+        if self.temperature_unit == 'fahrenheit':
+            temp_field = 'temp_f'
+            feels_like_field = 'feelslike_f'
+            unit_name = 'Fahrenheit'
+        else:
+            temp_field = 'temp_c'
+            feels_like_field = 'feelslike_c'
+            unit_name = 'Celsius'
+        
+        # Create TTS-friendly response instruction
+        response_instruction = (
+            f"Tell the user the current weather conditions. "
+            f"Express all temperatures in {unit_name} using natural language numbers "
+            f"without abbreviations or symbols for clear text-to-speech pronunciation. "
+            f"For example, say 'seventy two degrees {unit_name}' instead of '72F' or '72°F'. "
+            f"Include the condition, current temperature, wind direction and speed, "
+            f"cloud coverage percentage, and what the temperature feels like."
+        )
+        
+        # Build the weather data template
+        weather_template = (
+            f"{response_instruction} "
+            f"Current conditions: ${{current.condition.text}}. "
+            f"Temperature: ${{current.{temp_field}}} degrees {unit_name}. "
+            f"Wind: ${{current.wind_dir}} at ${{current.wind_mph}} miles per hour. "
+            f"Cloud coverage: ${{current.cloud}} percent. "
+            f"Feels like: ${{current.{feels_like_field}}} degrees {unit_name}."
+        )
+        
+        # Create the tool configuration with DataMap webhook
+        tool = {
+            "function": self.tool_name,
+            "description": f"Get current weather information for any location",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "location": {
+                        "type": "string",
+                        "description": "The city, state, country, or location to get weather for"
+                    }
+                },
+                "required": ["location"]
+            },
+            "data_map": {
+                "webhooks": [
+                    {
+                        "url": f"https://api.weatherapi.com/v1/current.json?key={self.api_key}&q=${{lc:enc:args.location}}&aqi=no",
+                        "method": "GET",
+                        "output": SwaigFunctionResult(weather_template).to_dict()
+                    }
+                ],
+                "error_keys": ["error"],
+                "output": SwaigFunctionResult(
+                    "Sorry, I cannot get weather information right now. Please try again later or check if the location name is correct."
+                ).to_dict()
+            }
+        }
+        
+        return [tool] 

signalwire_agents/skills/web_search/README.md

@@ -0,0 +1,163 @@
+# Web Search Skill
+
+The web_search skill provides web search capabilities using Google Custom Search API with web scraping functionality. It allows agents to search the internet for current information and extract content from the resulting web pages.
+
+## Features
+
+- Google Custom Search API integration
+- Web page content scraping and extraction
+- Configurable number of search results
+- Configurable delay between requests
+- Custom no-results messages with query placeholders
+- **Multiple instance support** - run multiple search engines with different configurations
+
+## Requirements
+
+- **Packages**: `beautifulsoup4`, `requests`
+- **API Access**: Google Custom Search API key and Search Engine ID
+
+## Parameters
+
+### Required Parameters
+
+- `api_key` (string): Google Custom Search API key
+- `search_engine_id` (string): Google Custom Search Engine ID
+
+### Optional Parameters
+
+- `num_results` (integer, default: 1): Number of search results to return (max: 10)
+- `delay` (float, default: 0): Delay in seconds between web page requests
+- `tool_name` (string, default: "web_search"): Custom name for the search tool (enables multiple instances)
+- `no_results_message` (string): Custom message when no results are found
+  - Default: "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."
+  - Use `{query}` as placeholder for the search query
+
+### Advanced Parameters
+
+- `swaig_fields` (dict): Additional SWAIG function configuration
+  - `secure` (boolean): Override security settings
+  - `fillers` (dict): Language-specific filler phrases during search
+  - Any other SWAIG function parameters
+
+## Tools Created
+
+- **Default**: `web_search` - Search the web for information
+- **Custom**: Uses the `tool_name` parameter value
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+# Minimal configuration
+agent.add_skill("web_search", {
+    "api_key": "your-google-api-key",
+    "search_engine_id": "your-search-engine-id"
+})
+```
+
+### Advanced Configuration
+
+```python
+# Comprehensive results with delay
+agent.add_skill("web_search", {
+    "api_key": "your-google-api-key",
+    "search_engine_id": "your-search-engine-id",
+    "num_results": 5,
+    "delay": 1.0,
+    "no_results_message": "Sorry, I couldn't find information about '{query}'. Try a different search term."
+})
+```
+
+### Multiple Instances
+
+```python
+# General web search
+agent.add_skill("web_search", {
+    "api_key": "your-api-key",
+    "search_engine_id": "general-search-engine-id",
+    "tool_name": "search_general",
+    "num_results": 1
+})
+
+# News-specific search
+agent.add_skill("web_search", {
+    "api_key": "your-api-key", 
+    "search_engine_id": "news-search-engine-id",
+    "tool_name": "search_news",
+    "num_results": 3,
+    "delay": 0.5
+})
+
+# Quick search for fast answers
+agent.add_skill("web_search", {
+    "api_key": "your-api-key",
+    "search_engine_id": "quick-search-engine-id", 
+    "tool_name": "quick_search",
+    "num_results": 1,
+    "delay": 0
+})
+```
+
+### With Custom Fillers
+
+```python
+agent.add_skill("web_search", {
+    "api_key": "your-api-key",
+    "search_engine_id": "your-search-engine-id",
+    "swaig_fields": {
+        "fillers": {
+            "en-US": [
+                "Let me search the web for that...",
+                "Looking that up online...",
+                "Searching the internet now..."
+            ],
+            "es-ES": [
+                "Déjame buscar eso en internet...",
+                "Buscando en línea..."
+            ]
+        }
+    }
+})
+```
+
+## How It Works
+
+1. **Search**: Uses Google Custom Search API to find relevant web pages
+2. **Scrape**: Downloads and extracts readable content from each result page
+3. **Format**: Presents results with titles, URLs, snippets, and extracted content
+4. **Filter**: Removes unwanted elements (scripts, styles, navigation) for clean text
+
+## Multiple Instance Support
+
+The web_search skill supports multiple instances, allowing you to:
+
+- Use different Google search engines for different types of content
+- Have different configurations (number of results, delays) per instance
+- Create specialized search tools (news, products, support, etc.)
+- Customize tool names for clarity (`search_news`, `search_products`, etc.)
+
+Each instance is uniquely identified by its `search_engine_id` and `tool_name` combination.
+
+## Error Handling
+
+- **No Results**: Returns custom `no_results_message` with query placeholder
+- **Network Issues**: Returns friendly error message for timeouts/connectivity issues
+- **Invalid Pages**: Gracefully handles pages that can't be scraped
+- **Rate Limiting**: Built-in delay support to respect API limits
+
+## Best Practices
+
+1. **For Speed**: Use `num_results: 1` and `delay: 0` for customer service
+2. **For Research**: Use `num_results: 3-5` and `delay: 0.5-1.0` for comprehensive results  
+3. **For News**: Use a news-specific search engine ID with higher result count
+4. **Rate Limiting**: Add delays when making frequent searches to respect API quotas
+5. **Custom Messages**: Tailor `no_results_message` to your agent's personality and use case
+
+## Getting Google Custom Search Setup
+
+1. Create a Google Cloud Project
+2. Enable the Custom Search JSON API
+3. Create a Custom Search Engine at https://cse.google.com/
+4. Get your API key from Google Cloud Console
+5. Get your Search Engine ID from the Custom Search Engine settings 

signalwire_agents/skills/web_search/__init__.py

@@ -1 +1,10 @@
+"""
+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.
+"""
+
 """Web Search Skill for SignalWire Agents"""