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

signalwire_agents/skills/swml_transfer/skill.py

@@ -0,0 +1,359 @@
+"""
+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 List, Dict, Any
+import re
+
+from signalwire_agents.core.skill_base import SkillBase
+from signalwire_agents.core.data_map import DataMap
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+
+class SWMLTransferSkill(SkillBase):
+    """Skill for transferring calls between agents using SWML with pattern matching"""
+    
+    SKILL_NAME = "swml_transfer"
+    SKILL_DESCRIPTION = "Transfer calls between agents based on pattern matching"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = []
+    REQUIRED_ENV_VARS = []
+    
+    # Enable multiple instances support
+    SUPPORTS_MULTIPLE_INSTANCES = True
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """Get parameter schema for SWML Transfer skill"""
+        schema = super().get_parameter_schema()
+        schema.update({
+            "transfers": {
+                "type": "object",
+                "description": "Transfer configurations mapping patterns to destinations",
+                "required": True,
+                "additionalProperties": {
+                    "type": "object",
+                    "properties": {
+                        "url": {
+                            "type": "string",
+                            "description": "SWML endpoint URL for agent transfer"
+                        },
+                        "address": {
+                            "type": "string", 
+                            "description": "Phone number or SIP address for direct connect"
+                        },
+                        "message": {
+                            "type": "string",
+                            "description": "Message to say before transferring",
+                            "default": "Transferring you now..."
+                        },
+                        "return_message": {
+                            "type": "string",
+                            "description": "Message when returning from transfer",
+                            "default": "The transfer is complete. How else can I help you?"
+                        },
+                        "post_process": {
+                            "type": "boolean",
+                            "description": "Whether to process message with AI before saying",
+                            "default": True
+                        },
+                        "final": {
+                            "type": "boolean",
+                            "description": "Whether transfer is permanent (true) or temporary (false)",
+                            "default": True
+                        },
+                        "from_addr": {
+                            "type": "string",
+                            "description": "Caller ID for connect action (optional)"
+                        }
+                    }
+                }
+            },
+            "description": {
+                "type": "string",
+                "description": "Description for the transfer tool",
+                "default": "Transfer call based on pattern matching",
+                "required": False
+            },
+            "parameter_name": {
+                "type": "string",
+                "description": "Name of the parameter that accepts the transfer type",
+                "default": "transfer_type",
+                "required": False
+            },
+            "parameter_description": {
+                "type": "string",
+                "description": "Description for the transfer type parameter",
+                "default": "The type of transfer to perform",
+                "required": False
+            },
+            "default_message": {
+                "type": "string",
+                "description": "Message when no pattern matches",
+                "default": "Please specify a valid transfer type.",
+                "required": False
+            },
+            "default_post_process": {
+                "type": "boolean",
+                "description": "Whether to process default message with AI",
+                "default": False,
+                "required": False
+            },
+            "required_fields": {
+                "type": "object",
+                "description": "Additional required fields to collect before transfer",
+                "default": {},
+                "required": False,
+                "additionalProperties": {
+                    "type": "string",
+                    "description": "Field description"
+                }
+            }
+        })
+        return schema
+    
+    def get_instance_key(self) -> str:
+        """
+        Get the key used to track this skill instance
+        
+        For SWML transfer, we use the tool name to differentiate instances
+        """
+        tool_name = self.params.get('tool_name', 'transfer_call')
+        return f"{self.SKILL_NAME}_{tool_name}"
+    
+    def setup(self) -> bool:
+        """Setup and validate skill configuration"""
+        # Validate required parameters
+        required_params = ['transfers']
+        missing_params = [param for param in required_params if not self.params.get(param)]
+        if missing_params:
+            self.logger.error(f"Missing required parameters: {missing_params}")
+            return False
+        
+        # Validate transfers structure
+        transfers = self.params.get('transfers', {})
+        if not isinstance(transfers, dict):
+            self.logger.error("'transfers' parameter must be a dictionary")
+            return False
+        
+        # Validate each transfer configuration
+        for pattern, config in transfers.items():
+            if not isinstance(config, dict):
+                self.logger.error(f"Transfer config for pattern '{pattern}' must be a dictionary")
+                return False
+            
+            # Must have either 'url' or 'address'
+            if 'url' not in config and 'address' not in config:
+                self.logger.error(f"Transfer config for pattern '{pattern}' must include either 'url' or 'address'")
+                return False
+            
+            if 'url' in config and 'address' in config:
+                self.logger.error(f"Transfer config for pattern '{pattern}' cannot have both 'url' and 'address'")
+                return False
+            
+            # Set defaults for optional fields
+            config.setdefault('message', f"Transferring you now...")
+            config.setdefault('return_message', "The transfer is complete. How else can I help you?")
+            config.setdefault('post_process', True)
+            config.setdefault('final', True)  # Default to permanent transfer
+            # from_addr is optional for connect action only
+        
+        # Store configuration
+        self.tool_name = self.params.get('tool_name', 'transfer_call')
+        self.description = self.params.get('description', 'Transfer call based on pattern matching')
+        self.parameter_name = self.params.get('parameter_name', 'transfer_type')
+        self.parameter_description = self.params.get('parameter_description', 'The type of transfer to perform')
+        self.transfers = transfers
+        self.default_message = self.params.get('default_message', 'Please specify a valid transfer type.')
+        self.default_post_process = self.params.get('default_post_process', False)
+        
+        # Required fields configuration
+        self.required_fields = self.params.get('required_fields', {})
+        
+        return True
+    
+    def register_tools(self) -> None:
+        """Register the transfer tool with pattern matching"""
+        
+        # Build the DataMap tool with all patterns
+        transfer_tool = (DataMap(self.tool_name)
+            .description(self.description)
+            .parameter(self.parameter_name, 'string', self.parameter_description, required=True)
+        )
+        
+        # Add required fields as parameters
+        for field_name, field_description in self.required_fields.items():
+            transfer_tool = transfer_tool.parameter(
+                field_name, 
+                'string', 
+                field_description, 
+                required=True
+            )
+        
+        # Add expression for each pattern
+        for pattern, config in self.transfers.items():
+            # Create the function result with transfer
+            result = SwaigFunctionResult(
+                config['message'], 
+                post_process=config['post_process']
+            )
+            
+            # Add required fields to global data under call_data key
+            if self.required_fields:
+                call_data = {}
+                for field_name in self.required_fields.keys():
+                    call_data[field_name] = f"${{args.{field_name}}}"
+                result = result.update_global_data({
+                    "call_data": call_data
+                })
+            
+            # Add the transfer action based on whether url or address is provided
+            if 'url' in config:
+                # Use swml_transfer for SWML endpoints
+                result = result.swml_transfer(
+                    config['url'], 
+                    config['return_message'],
+                    config.get('final', True)
+                )
+            else:
+                # Use connect for addresses (phone numbers, SIP, etc.)
+                result = result.connect(
+                    config['address'],
+                    config.get('final', True),
+                    config.get('from_addr', None)
+                )
+            
+            # Add the expression to the DataMap
+            transfer_tool = transfer_tool.expression(
+                f'${{{f"args.{self.parameter_name}"}}}',
+                pattern,
+                result
+            )
+        
+        # Add default fallback expression
+        default_result = SwaigFunctionResult(
+            self.default_message,
+            post_process=self.default_post_process
+        )
+        
+        # For fallback, still save required fields if provided
+        if self.required_fields:
+            call_data = {}
+            for field_name in self.required_fields.keys():
+                call_data[field_name] = f"${{args.{field_name}}}"
+            default_result = default_result.update_global_data({
+                "call_data": call_data
+            })
+        
+        transfer_tool = transfer_tool.expression(
+            f'${{{f"args.{self.parameter_name}"}}}',
+            r'/.*/',  # Match anything as fallback
+            default_result
+        )
+        
+        # Register the tool with the agent
+        if hasattr(self.agent, 'register_swaig_function'):
+            self.agent.register_swaig_function(transfer_tool.to_swaig_function())
+        else:
+            # Fallback to define_tool if register_swaig_function is not available
+            self.logger.error("Agent does not have register_swaig_function method")
+    
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        hints = []
+        
+        # Extract common words from patterns for hints
+        for pattern in self.transfers.keys():
+            # Remove regex delimiters and flags
+            clean_pattern = pattern
+            # Remove leading and trailing slashes
+            if clean_pattern.startswith('/'):
+                clean_pattern = clean_pattern[1:]
+            if clean_pattern.endswith('/'):
+                clean_pattern = clean_pattern[:-1]
+            # Remove flags after the pattern (e.g., 'i' for case-insensitive)
+            elif clean_pattern.endswith('/i'):
+                clean_pattern = clean_pattern[:-2]
+            
+            # Only add if it's not a catch-all pattern
+            if clean_pattern and not clean_pattern.startswith('.'):
+                # Handle patterns with alternatives (e.g., "sales|billing")
+                if '|' in clean_pattern:
+                    for part in clean_pattern.split('|'):
+                        hints.append(part.strip().lower())
+                else:
+                    hints.append(clean_pattern.lower())
+        
+        # Add common transfer-related words
+        hints.extend(['transfer', 'connect', 'speak to', 'talk to'])
+        
+        return hints
+    
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        sections = []
+        
+        # Build a list of transfer destinations with their patterns
+        if self.transfers:
+            transfer_bullets = []
+            
+            for pattern, config in self.transfers.items():
+                # Extract meaningful name from pattern
+                # Remove regex delimiters and flags
+                clean_pattern = pattern
+                # Remove leading and trailing slashes
+                if clean_pattern.startswith('/'):
+                    clean_pattern = clean_pattern[1:]
+                if clean_pattern.endswith('/'):
+                    clean_pattern = clean_pattern[:-1]
+                # Remove flags after the pattern (e.g., 'i' for case-insensitive)
+                elif clean_pattern.endswith('/i'):
+                    clean_pattern = clean_pattern[:-2]
+                
+                # Only add if it's not a catch-all pattern
+                if clean_pattern and not clean_pattern.startswith('.'):
+                    # Create a description for this transfer destination
+                    if 'url' in config:
+                        destination = config['url']
+                    else:
+                        destination = config['address']
+                    transfer_desc = f'"{clean_pattern}" - transfers to {destination}'
+                    transfer_bullets.append(transfer_desc)
+            
+            # Add the Transferring section
+            sections.append({
+                "title": "Transferring",
+                "body": f"You can transfer calls using the {self.tool_name} function with the following destinations:",
+                "bullets": transfer_bullets
+            })
+            
+            # Add usage instructions
+            bullets = [
+                f"Use the {self.tool_name} function when a transfer is needed",
+                f"Pass the destination type to the '{self.parameter_name}' parameter"
+            ]
+            
+            # Add required fields instructions if configured
+            if self.required_fields:
+                bullets.append("You must provide the following information before transferring:")
+                for field_name, field_description in self.required_fields.items():
+                    bullets.append(f"  - {field_name}: {field_description}")
+                bullets.append("All required information will be saved under 'call_data' for the next agent")
+            
+            bullets.extend([
+                f"The system will match patterns and handle the transfer automatically",
+                "After transfer completes, you'll regain control of the conversation"
+            ])
+            
+            sections.append({
+                "title": "Transfer Instructions",
+                "body": f"How to use the transfer capability:",
+                "bullets": bullets
+            })
+        
+        return sections

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/weather_api/__init__.py

@@ -0,0 +1,12 @@
+"""
+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 .skill import WeatherApiSkill
+
+__all__ = ['WeatherApiSkill']