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

signalwire_agents/skills/weather_api/README.md

@@ -0,0 +1,178 @@
+# Weather API Skill
+
+A configurable skill for getting current weather information from WeatherAPI.com with customizable temperature units and TTS-optimized natural language responses.
+
+## Features
+
+- **Configurable Temperature Units**: Choose between Fahrenheit and Celsius
+- **TTS-Friendly Responses**: Natural language numbers without abbreviations or symbols
+- **Real-time Weather Data**: Current conditions via WeatherAPI.com
+- **DataMap Efficiency**: Serverless webhook execution, no agent processing load
+- **Error Handling**: Graceful fallback for API failures or invalid locations
+- **Comprehensive Weather Info**: Temperature, conditions, wind, clouds, feels-like
+
+## Configuration
+
+### Basic Structure
+
+```python
+agent.add_skill("weather_api", {
+    "tool_name": "get_weather",
+    "api_key": "your_weatherapi_key", 
+    "temperature_unit": "fahrenheit"  # or "celsius"
+})
+```
+
+### Parameters
+
+- **tool_name** (string, optional): Custom name for the generated SWAIG function (default: "get_weather")
+- **api_key** (string, required): Your WeatherAPI.com API key
+- **temperature_unit** (string, optional): "fahrenheit" or "celsius" (default: "fahrenheit")
+
+## Usage Examples
+
+### Fahrenheit Weather (Default)
+
+```python
+agent.add_skill("weather_api", {
+    "tool_name": "get_weather",
+    "api_key": "your_weatherapi_key"
+})
+```
+
+**Generated Tool**: `get_weather(location)`
+**Temperature Format**: "seventy two degrees Fahrenheit"
+
+### Celsius Weather
+
+```python
+agent.add_skill("weather_api", {
+    "tool_name": "get_weather_celsius",
+    "api_key": "your_weatherapi_key",
+    "temperature_unit": "celsius"
+})
+```
+
+**Generated Tool**: `get_weather_celsius(location)`
+**Temperature Format**: "twenty two degrees Celsius"
+
+### Custom Tool Name
+
+```python
+agent.add_skill("weather_api", {
+    "tool_name": "check_current_weather",
+    "api_key": "your_weatherapi_key",
+    "temperature_unit": "fahrenheit"
+})
+```
+
+**Generated Tool**: `check_current_weather(location)`
+
+## Generated SWAIG Function
+
+For the Fahrenheit example above, the skill generates:
+
+```json
+{
+    "function": "get_weather",
+    "description": "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": {
+        "webhook": {
+            "url": "https://api.weatherapi.com/v1/current.json?key=your_api_key&q=%{enc:args.location}&aqi=no",
+            "method": "GET"
+        },
+        "output": {
+            "response": "Tell the user the current weather conditions. Express all temperatures in Fahrenheit using natural language numbers without abbreviations or symbols for clear text-to-speech pronunciation. For example, say 'seventy two degrees Fahrenheit' instead of '72F' or '72°F'. Include the condition, current temperature, wind direction and speed, cloud coverage percentage, and what the temperature feels like. Current conditions: ${current.condition.text}. Temperature: ${current.temp_f} degrees Fahrenheit. Wind: ${current.wind_dir} at ${current.wind_mph} miles per hour. Cloud coverage: ${current.cloud} percent. Feels like: ${current.feelslike_f} degrees Fahrenheit."
+        },
+        "error_keys": ["error"],
+        "fallback_output": {
+            "response": "Sorry, I cannot get weather information right now. Please try again later or check if the location name is correct."
+        }
+    }
+}
+```
+
+## TTS Optimization
+
+The skill is specifically designed for text-to-speech systems:
+
+### Natural Language Numbers
+- ✅ "seventy two degrees Fahrenheit"
+- ❌ "72F" or "72°F"
+
+### Full Pronunciation
+- ✅ "twenty two degrees Celsius" 
+- ❌ "22C" or "22°C"
+
+### Complete Weather Description
+- Current conditions description
+- Temperature in natural language
+- Wind direction and speed
+- Cloud coverage percentage
+- Feels-like temperature
+
+## Execution Flow
+
+1. **AI calls function**: `get_weather(location: "New York")`
+2. **DataMap webhook**: `GET https://api.weatherapi.com/v1/current.json?key=...&q=New%20York&aqi=no`
+3. **API response**: Weather data with current conditions
+4. **AI responds**: "Tell the user the current weather conditions. Express all temperatures in Fahrenheit using natural language numbers... Current conditions: Partly cloudy. Temperature: seventy two degrees Fahrenheit. Wind: Southwest at fifteen miles per hour. Cloud coverage: twenty five percent. Feels like: seventy five degrees Fahrenheit."
+
+## WeatherAPI.com Integration
+
+The skill integrates with WeatherAPI.com's current weather endpoint:
+
+- **Endpoint**: `https://api.weatherapi.com/v1/current.json`
+- **Parameters**: `key`, `q` (location), `aqi=no`
+- **Response**: Real-time weather data including temperature, conditions, wind, clouds
+- **Location Support**: Cities, states, countries, coordinates, airports, etc.
+
+## Temperature Unit Support
+
+### Fahrenheit Configuration
+```python
+"temperature_unit": "fahrenheit"
+```
+- Uses `temp_f` and `feelslike_f` fields
+- Displays as "degrees Fahrenheit"
+
+### Celsius Configuration  
+```python
+"temperature_unit": "celsius"
+```
+- Uses `temp_c` and `feelslike_c` fields
+- Displays as "degrees Celsius"
+
+## Error Handling
+
+- **Invalid API Key**: Validation during skill initialization
+- **Invalid Temperature Unit**: Must be "fahrenheit" or "celsius"
+- **API Failures**: Graceful fallback response for network/API issues
+- **Invalid Locations**: Fallback suggests checking location name
+
+## Benefits
+
+- **TTS Optimized**: Natural language responses perfect for voice agents
+- **Configurable**: Easy temperature unit switching without code changes
+- **Efficient**: DataMap webhook execution, no agent processing load
+- **Reliable**: Real-time data from established weather service
+- **User Friendly**: Clear error messages and location flexibility
+- **Professional**: Production-ready with comprehensive error handling
+
+## Implementation Notes
+
+- Temperature unit determines which API fields to use (`temp_f`/`temp_c`, `feelslike_f`/`feelslike_c`)
+- Response includes detailed TTS instructions for natural pronunciation
+- URL encoding automatically applied to location parameter
+- Wind speed always reported in miles per hour regardless of temperature unit
+- No air quality data requested to keep responses focused 

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/wikipedia_search/README.md

@@ -0,0 +1,228 @@
+# Wikipedia Search Skill
+
+The Wikipedia Search skill provides agents with the ability to search Wikipedia articles and retrieve factual information. This skill uses the Wikipedia API to search for articles and return their introductory content, making it perfect for answering factual questions about people, places, concepts, and more.
+
+## Features
+
+- **Free Wikipedia API**: No API keys or credentials required
+- **Article Summaries**: Returns introductory content from Wikipedia articles
+- **Multiple Results**: Can return multiple article summaries for broader topics
+- **Customizable Messages**: Custom no-results messages with query placeholders
+- **Error Handling**: Graceful handling of network errors and API issues
+- **Speech Recognition**: Includes hints for better voice recognition accuracy
+
+## Requirements
+
+- **Python Packages**: `requests` (automatically installed with SignalWire Agents)
+- **API Keys**: None required - uses free Wikipedia API
+- **Environment Variables**: None required
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `num_results` | int | 1 | Number of Wikipedia articles to return (minimum: 1) |
+| `no_results_message` | str | Auto-generated | Custom message when no results found. Use `{query}` as placeholder |
+| `swaig_fields` | dict | {} | Additional SWAIG function configuration (fillers, etc.) |
+
+## Tools Created
+
+This skill creates one SWAIG tool:
+
+### `search_wiki`
+- **Description**: Search Wikipedia for information about a topic and get article summaries
+- **Parameters**:
+  - `query` (string, required): The search term or topic to look up on Wikipedia
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+from signalwire_agents import AgentBase
+
+agent = AgentBase("Wikipedia Assistant")
+
+# Add Wikipedia search with default settings
+agent.add_skill("wikipedia_search")
+```
+
+### Custom Configuration
+
+```python
+# Custom number of results and no-results message
+agent.add_skill("wikipedia_search", {
+    "num_results": 2,  # Return up to 2 articles
+    "no_results_message": "Sorry, I couldn't find any Wikipedia articles about '{query}'. Try different keywords or check the spelling."
+})
+```
+
+### With SWAIG Fields (Fillers)
+
+```python
+# Add custom fillers for better user experience
+agent.add_skill("wikipedia_search", {
+    "num_results": 1,
+    "swaig_fields": {
+        "fillers": {
+            "en-US": [
+                "Let me check Wikipedia for that...",
+                "Searching Wikipedia...",
+                "Looking that up on Wikipedia...",
+                "Checking the encyclopedia..."
+            ]
+        }
+    }
+})
+```
+
+### Advanced Configuration
+
+```python
+# Full configuration example
+agent.add_skill("wikipedia_search", {
+    "num_results": 3,
+    "no_results_message": "I searched Wikipedia but couldn't find information about '{query}'. You might want to try rephrasing your question or searching for related topics.",
+    "swaig_fields": {
+        "fillers": {
+            "en-US": [
+                "Searching Wikipedia for factual information...",
+                "Let me look that up in the encyclopedia...",
+                "Checking Wikipedia's knowledge base..."
+            ]
+        },
+        "meta": {
+            "description": "Search Wikipedia for reliable, factual information"
+        }
+    }
+})
+```
+
+## Multiple Instance Support
+
+**This skill does NOT support multiple instances.** You can only load one instance of the Wikipedia search skill per agent. This is because:
+
+- Wikipedia search is a general-purpose tool that doesn't need specialization
+- The tool name `search_wiki` is fixed and meaningful
+- Multiple instances would create confusion without added benefit
+
+If you need different Wikipedia search behaviors, use the `num_results` parameter to control the scope of results.
+
+## API Details
+
+The skill uses the Wikipedia API with two steps:
+
+1. **Search**: Uses the `action=query&list=search` endpoint to find matching articles
+2. **Extract**: Uses the `action=query&prop=extracts` endpoint to get article summaries
+
+### Search Process
+
+```
+1. Search for articles matching the query
+   → GET https://en.wikipedia.org/w/api.php?action=query&list=search&format=json&srsearch={query}&srlimit={num_results}
+
+2. For each result, get the article extract
+   → GET https://en.wikipedia.org/w/api.php?action=query&prop=extracts&exintro&explaintext&format=json&titles={title}
+
+3. Format and return the results
+```
+
+## Response Format
+
+### Single Result
+```
+**Article Title**
+
+Article content summary...
+```
+
+### Multiple Results
+```
+**First Article Title**
+
+First article content summary...
+
+==================================================
+
+**Second Article Title**
+
+Second article content summary...
+```
+
+## Error Handling
+
+The skill handles various error conditions gracefully:
+
+- **No Results**: Returns the custom `no_results_message` with the query
+- **Network Errors**: Returns "Error accessing Wikipedia: {error details}"
+- **API Errors**: Returns "Error searching Wikipedia: {error details}"
+- **Empty Extracts**: Returns "No summary available for this article"
+
+## Speech Recognition Hints
+
+The skill provides these hints to improve voice recognition:
+
+- "Wikipedia"
+- "wiki" 
+- "search Wikipedia"
+- "look up"
+- "tell me about"
+- "what is"
+- "who is"
+- "information about"
+- "facts about"
+
+## Best Practices
+
+### Query Optimization
+- Use specific terms for better results
+- Try both full names and common names (e.g., "Einstein" vs "Albert Einstein")
+- For disambiguation, be more specific (e.g., "Python programming language" vs "Python")
+
+### Result Management
+- Use `num_results: 1` for specific factual queries
+- Use `num_results: 2-3` for broader topics that might have multiple relevant articles
+- Avoid very high numbers as it can overwhelm users
+
+### Error Messages
+- Customize `no_results_message` to match your agent's personality
+- Include suggestions for alternative searches
+- Use the `{query}` placeholder to reference what the user searched for
+
+### Integration Tips
+- Combine with web search for comprehensive information gathering
+- Use for factual verification of claims
+- Great for educational and reference applications
+
+## Example Conversations
+
+**User**: "Tell me about quantum physics"
+**Agent**: *Searching Wikipedia...* "Here's what I found about quantum physics: **Quantum mechanics** - Quantum mechanics is a fundamental theory that describes the behavior of nature at and below the scale of atoms..."
+
+**User**: "Who was Marie Curie?"
+**Agent**: *Let me check Wikipedia for that...* "**Marie Curie** - Marie Salomea Skłodowska-Curie was a Polish and naturalized-French physicist and chemist who conducted pioneering research on radioactivity..."
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Skill not loading**: Ensure `requests` package is installed
+2. **No results for valid topics**: Try different search terms or check spelling
+3. **Network timeouts**: The skill has a 10-second timeout for API calls
+
+### Debug Information
+
+The skill logs initialization and search activities:
+```
+Wikipedia search skill initialized with {num_results} max results
+```
+
+Enable debug logging to see detailed API interactions and error information.
+
+## Related Skills
+
+- **web_search**: For current information and broader web content
+- **datasphere**: For searching custom knowledge bases
+- **datetime**: For current date/time context in historical queries
+
+The Wikipedia skill is perfect for factual, encyclopedic information, while web search is better for current events and specific products/services. 

{signalwire_agents-0.1.23.dist-info → signalwire_agents-0.1.24.dist-info}/METADATA

@@ -1,9 +1,11 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.23
+Version: 0.1.24
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
+License: MIT
 Project-URL: Homepage, https://github.com/signalwire/signalwire-agents
+Keywords: signalwire,ai,agents,voice,telephony,swaig,swml
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -26,6 +28,7 @@ Requires-Dist: structlog==25.3.0
 Requires-Dist: uvicorn==0.34.2
 Requires-Dist: beautifulsoup4==4.12.3
 Requires-Dist: pytz==2023.3
+Requires-Dist: lxml>=4.9.0
 Provides-Extra: search-queryonly
 Requires-Dist: numpy>=1.24.0; extra == "search-queryonly"
 Requires-Dist: scikit-learn>=1.3.0; extra == "search-queryonly"
@@ -735,7 +738,49 @@ class DynamicAgent(AgentBase):
 - **Localization**: Language and cultural adaptation based on user location
 - **Dynamic Pricing**: Adjust features and capabilities based on subscription tiers
 
-The `EphemeralAgentConfig` object provides all the same familiar methods as `AgentBase` (like `add_language()`, `prompt_add_section()`, `set_global_data()`) but applies them per-request instead of at startup.
+### Preserving Dynamic State in SWAIG Callbacks
+
+When using dynamic configuration to add skills or tools based on request parameters, there's a challenge: SWAIG webhook callbacks are separate HTTP requests that won't have the original query parameters. The SDK provides `add_swaig_query_params()` to solve this:
+
+```python
+class DynamicAgent(AgentBase):
+    def __init__(self):
+        super().__init__(name="dynamic-agent", route="/agent")
+        self.set_dynamic_config_callback(self.configure_per_request)
+    
+    def configure_per_request(self, query_params, body_params, headers, agent):
+        tier = query_params.get('tier', 'basic')
+        region = query_params.get('region', 'us-east')
+        
+        if tier == 'premium':
+            # Add premium skills dynamically
+            agent.add_skill('advanced_search', {
+                'api_key': 'your-api-key',
+                'num_results': 5
+            })
+            
+            # IMPORTANT: Preserve parameters for SWAIG callbacks
+            agent.add_swaig_query_params({
+                'tier': tier,
+                'region': region
+            })
+            
+            # Now when SignalWire calls the SWAIG webhook, these params
+            # will be included, triggering the same dynamic configuration
+
+# Initial request: GET /agent?tier=premium&region=eu-west
+# SWAIG callback: POST /swaig/?tier=premium&region=eu-west
+# Result: Premium skills are available in both requests!
+```
+
+**Key Points:**
+
+- **Problem**: Dynamically added skills/tools won't exist during SWAIG callbacks without the original request parameters
+- **Solution**: Use `add_swaig_query_params()` to include critical parameters in all SWAIG webhook URLs
+- **Clear State**: Use `clear_swaig_query_params()` if needed to reset parameters between requests
+- **Token Safety**: The SDK automatically renames security tokens from `token` to `__token` to avoid parameter collisions
+
+This ensures that any dynamic configuration based on request parameters is consistently applied across the initial SWML request and all subsequent SWAIG function callbacks.
 
 For detailed documentation and advanced examples, see the [Agent Guide](docs/agent_guide.md#dynamic-agent-configuration).