signalwire-agents 0.1.6__py3-none-any.whl → 1.0.7__py3-none-any.whl

signalwire_agents/skills/joke/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 typing import List, Dict, Any
+
+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 JokeSkill(SkillBase):
+    """Joke telling capability using API Ninjas with DataMap"""
+    
+    SKILL_NAME = "joke"
+    SKILL_DESCRIPTION = "Tell jokes using the API Ninjas joke API"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = []  # DataMap doesn't require local packages
+    REQUIRED_ENV_VARS = []  # API key comes from parameters
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """Get parameter schema for joke skill"""
+        schema = super().get_parameter_schema()
+        schema.update({
+            "api_key": {
+                "type": "string",
+                "description": "API Ninjas API key for joke service",
+                "required": True,
+                "hidden": True,
+                "env_var": "API_NINJAS_KEY"
+            },
+            "tool_name": {
+                "type": "string",
+                "description": "Custom name for the joke tool",
+                "default": "get_joke",
+                "required": False
+            }
+        })
+        return schema
+        
+    def setup(self) -> bool:
+        """Setup the joke skill"""
+        # Validate required parameters
+        required_params = ['api_key']
+        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
+            
+        # Set parameters from config
+        self.api_key = self.params['api_key']
+        
+        # Optional parameters with defaults
+        self.tool_name = self.params.get('tool_name', 'get_joke')
+        
+        return True
+        
+    def register_tools(self) -> None:
+        """Register joke tool using DataMap"""
+        
+        # Create DataMap tool for jokes - uses required enum parameter
+        joke_tool = (DataMap(self.tool_name)
+            .description('Get a random joke from API Ninjas')
+            .parameter('type', 'string', 'Type of joke to get', 
+                      required=True, enum=['jokes', 'dadjokes'])
+            .webhook('GET', "https://api.api-ninjas.com/v1/${args.type}", 
+                     headers={'X-Api-Key': self.api_key})
+            .output(SwaigFunctionResult('Here\'s a joke: ${array[0].joke}'))
+            .error_keys(['error'])
+            .fallback_output(SwaigFunctionResult('Sorry, there is a problem with the joke service right now. Please try again later.'))
+        )
+        
+        # Register the DataMap tool with the agent
+        self.agent.register_swaig_function(joke_tool.to_swaig_function())
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        # Currently no hints are provided, but you could add them like:
+        # return [
+        #     "joke", "tell me a joke", "funny", "humor", "dad joke", 
+        #     "regular joke", "make me laugh", "comedy"
+        # ]
+        return []
+        
+    def get_global_data(self) -> Dict[str, Any]:
+        """Return global data to be available in DataMap variables"""
+        return {
+            "joke_skill_enabled": True
+        }
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return [
+            {
+                "title": "Joke Telling", 
+                "body": "You can tell jokes to entertain users.",
+                "bullets": [
+                    f"Use {self.tool_name} to tell jokes when users ask for humor",
+                    "You can tell regular jokes or dad jokes",
+                    "Be enthusiastic and fun when sharing jokes"
+                ]
+            }
+        ] 

signalwire_agents/skills/math/README.md

@@ -0,0 +1,161 @@
+# Math Skill
+
+The math skill provides safe mathematical calculation capabilities for agents. It allows users to perform basic arithmetic operations and complex mathematical expressions with security protections against code injection.
+
+## Features
+
+- Safe mathematical expression evaluation
+- Support for basic arithmetic operations
+- Parentheses support for complex expressions
+- Division by zero protection
+- Security filtering to prevent code injection
+- No external dependencies required
+
+## Requirements
+
+- **Packages**: None (uses built-in Python functionality)
+- **No external APIs required**
+
+## Parameters
+
+### Optional Parameters
+
+- `swaig_fields` (dict): Additional SWAIG function configuration
+  - `secure` (boolean): Override security settings for the calculation function
+  - `fillers` (dict): Language-specific filler phrases while calculating
+  - Any other SWAIG function parameters
+
+**Note**: This skill does not require any configuration parameters beyond the optional swaig_fields. It works out-of-the-box with no setup.
+
+## Tools Created
+
+- `calculate` - Perform a mathematical calculation with basic operations
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+# No configuration needed - works immediately
+agent.add_skill("math")
+```
+
+### With Custom Fillers
+
+```python
+agent.add_skill("math", {
+    "swaig_fields": {
+        "fillers": {
+            "en-US": [
+                "Let me calculate that for you...",
+                "Crunching the numbers...",
+                "Computing the result...",
+                "Working out the math..."
+            ],
+            "es-ES": [
+                "Déjame calcular eso...",
+                "Procesando los números...",
+                "Calculando el resultado..."
+            ]
+        }
+    }
+})
+```
+
+### Disabling Security (if needed)
+
+```python
+agent.add_skill("math", {
+    "swaig_fields": {
+        "secure": False  # Allow unauthenticated calculation requests
+    }
+})
+```
+
+## How It Works
+
+### Calculation Function
+- **Input**: Mathematical expression as a string
+- **Processing**: Validates expression for safety, then evaluates it
+- **Output**: Shows the original expression and the calculated result
+- **Example**: "2 + 3 * 4 = 14"
+
+### Supported Operations
+
+- **Addition**: `+` (e.g., "5 + 3")
+- **Subtraction**: `-` (e.g., "10 - 7")
+- **Multiplication**: `*` (e.g., "6 * 8")
+- **Division**: `/` (e.g., "15 / 3")
+- **Modulo**: `%` (e.g., "17 % 5")
+- **Exponentiation**: `**` (e.g., "2 ** 3")
+- **Parentheses**: `()` for grouping (e.g., "(2 + 3) * 4")
+
+### Expression Examples
+
+- Simple: `"2 + 3"` → "2 + 3 = 5"
+- Complex: `"(10 + 5) * 2 / 3"` → "(10 + 5) * 2 / 3 = 10.0"
+- With decimals: `"3.14 * 2"` → "3.14 * 2 = 6.28"
+- Powers: `"2 ** 8"` → "2 ** 8 = 256"
+- Modulo: `"17 % 5"` → "17 % 5 = 2"
+
+## Function Parameters
+
+The calculate tool accepts one parameter:
+
+- `expression` (string, required): Mathematical expression to evaluate
+  - Must contain only numbers, operators, and parentheses
+  - Operators allowed: `+`, `-`, `*`, `/`, `%`, `**`, `(`, `)`
+  - Decimal numbers are supported
+  - Spaces are allowed and ignored
+
+## Security Features
+
+### Input Validation
+- Only allows safe mathematical characters: numbers, operators, parentheses, spaces, decimal points
+- Blocks any potentially dangerous code or function calls
+- Uses regex pattern matching for character validation
+
+### Safe Evaluation
+- Uses Python's `eval()` with restricted builtins (empty `__builtins__`)
+- No access to system functions or imports
+- Cannot execute arbitrary code
+
+### Error Handling
+- **Division by Zero**: Returns friendly error message
+- **Invalid Syntax**: Returns error for malformed expressions
+- **Illegal Characters**: Rejects expressions with non-math characters
+- **Empty Input**: Prompts user to provide an expression
+
+## Error Examples
+
+- **Division by zero**: "Error: Division by zero is not allowed."
+- **Invalid characters**: "Invalid expression. Only numbers and basic math operators are allowed."
+- **Syntax error**: "Error calculating '2 + + 3': Invalid expression"
+- **Empty input**: "Please provide a mathematical expression to calculate."
+
+## Common Use Cases
+
+1. **Basic Arithmetic**: "What's 15 + 27?"
+2. **Percentage Calculations**: "What's 15% of 200?" → "200 * 0.15"
+3. **Complex Expressions**: "Calculate (100 + 50) * 0.08"
+4. **Powers and Roots**: "What's 2 to the power of 10?"
+5. **Financial Calculations**: "If I have $500 and spend $125, how much is left?"
+
+## Best Practices
+
+1. **Default Behavior**: The skill works immediately without configuration
+2. **User Education**: Help users understand they can use parentheses for complex calculations
+3. **Expression Formatting**: The skill is forgiving with spaces and formatting
+4. **Error Recovery**: Provide helpful guidance when users make syntax errors
+5. **Security**: The skill is designed to be safe even with malicious input
+
+## Agent Integration
+
+When added to an agent, this skill automatically:
+
+- Adds speech recognition hints for math-related words
+- Provides prompt guidance about calculation capabilities
+- Enables the agent to respond to mathematical questions
+- Shows both the original expression and result for transparency
+
+The skill is designed to be completely self-contained and secure, making it safe for any agent to use for mathematical calculations. 

signalwire_agents/skills/math/__init__.py

@@ -0,0 +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.
+"""
+
+"""Math Skill for SignalWire Agents""" 

signalwire_agents/skills/math/skill.py

@@ -0,0 +1,105 @@
+"""
+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.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"""
+        # Currently no hints provided, but you could add them like:
+        # return [
+        #     "calculate", "math", "plus", "minus", "times", "multiply", 
+        #     "divide", "equals", "percent", "power", "squared"
+        # ]
+        return []
+        
+    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"
+                ]
+            }
+        ]
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """
+        Get the parameter schema for the math skill
+        
+        The math skill has no custom parameters - it inherits only
+        the base parameters from SkillBase.
+        """
+        # Get base schema from parent
+        schema = super().get_parameter_schema()
+        
+        # No additional parameters for math skill
+        
+        return schema 

signalwire_agents/skills/mcp_gateway/README.md

@@ -0,0 +1,230 @@
+# MCP Gateway Skill
+
+Bridge MCP (Model Context Protocol) servers with SignalWire SWAIG functions, allowing agents to seamlessly interact with MCP-based tools.
+
+## Description
+
+The MCP Gateway skill connects SignalWire agents to MCP servers through a centralized gateway service. It dynamically discovers and registers MCP tools as SWAIG functions, maintaining session state throughout each call.
+
+## Features
+
+- Dynamic tool discovery from MCP servers
+- Session management tied to SignalWire call IDs
+- Automatic cleanup on call hangup
+- Support for multiple MCP services
+- Selective tool loading
+- HTTPS support with SSL verification
+- Retry logic for resilient connections
+
+## Requirements
+
+- Running MCP Gateway service
+- Network access to gateway
+- Gateway credentials (username/password)
+
+## Configuration
+
+### Required Parameters
+
+Either Basic Auth credentials OR Bearer token:
+- `gateway_url`: URL of the MCP gateway service (default: "http://localhost:8100")
+- `auth_user` + `auth_password`: Basic auth credentials
+- OR `auth_token`: Bearer token for authentication
+
+### Optional Parameters
+
+- `services`: Array of services to load (default: all available)
+  - `name`: Service name
+  - `tools`: Array of tool names or "*" for all (default: all)
+- `session_timeout`: Session timeout in seconds (default: 300)
+- `tool_prefix`: Prefix for SWAIG function names (default: "mcp_")
+- `retry_attempts`: Number of retry attempts (default: 3)
+- `request_timeout`: HTTP request timeout in seconds (default: 30)
+- `verify_ssl`: Verify SSL certificates (default: true)
+
+## Usage
+
+### Basic Usage (All Services)
+
+```python
+from signalwire_agents import AgentBase
+
+class MyAgent(AgentBase):
+    def __init__(self):
+        super().__init__(name="My Agent")
+        
+        # Load all available MCP services
+        self.add_skill("mcp_gateway", {
+            "gateway_url": "http://localhost:8080",
+            "auth_user": "admin",
+            "auth_password": "changeme"
+        })
+
+agent = MyAgent()
+agent.run()
+```
+
+### Selective Service Loading
+
+```python
+# Load specific services with specific tools
+self.add_skill("mcp_gateway", {
+    "gateway_url": "https://gateway.example.com",
+    "auth_user": "admin",
+    "auth_password": "secret",
+    "services": [
+        {
+            "name": "todo",
+            "tools": ["add_todo", "list_todos"]  # Only these tools
+        },
+        {
+            "name": "calculator",
+            "tools": "*"  # All calculator tools
+        }
+    ],
+    "session_timeout": 600,
+    "tool_prefix": "ext_"
+})
+```
+
+### HTTPS with Self-Signed Certificate
+
+```python
+self.add_skill("mcp_gateway", {
+    "gateway_url": "https://localhost:8443",
+    "auth_user": "admin",
+    "auth_password": "secret",
+    "verify_ssl": False  # For self-signed certificates
+})
+```
+
+### Bearer Token Authentication
+
+```python
+self.add_skill("mcp_gateway", {
+    "gateway_url": "https://gateway.example.com",
+    "auth_token": "your-bearer-token-here",
+    "services": [{
+        "name": "todo"
+    }]
+})
+```
+
+## Generated Functions
+
+The skill dynamically generates SWAIG functions based on discovered MCP tools. Function names follow the pattern:
+
+`{tool_prefix}{service_name}_{tool_name}`
+
+For example, with default settings:
+- `mcp_todo_add_todo` - Add a todo item
+- `mcp_todo_list_todos` - List todo items
+- `mcp_calculator_add` - Calculator addition
+
+## Example Conversations
+
+### Using Todo Service
+
+```
+User: "Add a task to buy milk"
+Assistant: "I'll add that to your todo list."
+[Calls mcp_todo_add_todo with text="buy milk"]
+Assistant: "I've added 'buy milk' to your todo list."
+
+User: "What's on my todo list?"
+Assistant: "Let me check your todos."
+[Calls mcp_todo_list_todos]
+Assistant: "Here are your current todos:
+○ #1 [medium] buy milk"
+```
+
+### Multiple Services
+
+```
+User: "Add 'finish report' to my todos and calculate 15% of 200"
+Assistant: "I'll add that todo and do the calculation for you."
+[Calls mcp_todo_add_todo with text="finish report"]
+[Calls mcp_calculator_percent with value=200, percent=15]
+Assistant: "I've added 'finish report' to your todos. 15% of 200 is 30."
+```
+
+## Session Management
+
+- Each SignalWire call gets its own MCP session
+- Sessions persist across multiple tool calls
+- Automatic cleanup on call hangup
+- Configurable timeout for inactive sessions
+
+### Custom Session ID
+
+You can override the session ID by setting `mcp_call_id` in global_data:
+
+```python
+# In your agent code
+self.set_global_data({
+    "mcp_call_id": "custom-session-123"
+})
+
+# Or in a SWAIG function
+result = SwaigFunctionResult("Session changed")
+result.add_action("set_global_data", {"mcp_call_id": "new-session-456"})
+```
+
+This is useful for:
+- Managing multiple MCP sessions within a single call
+- Sharing MCP sessions across different calls
+- Custom session management strategies
+
+## Troubleshooting
+
+### Gateway Connection Failed
+
+Check:
+1. Gateway service is running
+2. Correct URL and credentials
+3. Network connectivity
+4. Firewall rules
+
+### SSL Certificate Errors
+
+For self-signed certificates:
+```python
+"verify_ssl": False
+```
+
+For custom CA certificates, ensure they're in the system trust store.
+
+### Tool Not Found
+
+Verify:
+1. Service name is correct
+2. Tool name matches exactly
+3. Tool is included in service configuration
+4. MCP server is returning tools correctly
+
+### Session Timeouts
+
+Increase timeout if needed:
+```python
+"session_timeout": 600  # 10 minutes
+```
+
+## Gateway Setup
+
+To run the MCP Gateway service:
+
+```bash
+cd mcp_gateway
+python3 gateway_service.py
+
+# Or with custom config
+python3 gateway_service.py -c myconfig.json
+```
+
+## Security Considerations
+
+1. Always use HTTPS in production
+2. Use strong authentication credentials
+3. Limit service access to required tools only
+4. Monitor gateway logs for suspicious activity
+5. Set appropriate session timeouts

signalwire_agents/skills/mcp_gateway/__init__.py

@@ -0,0 +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.
+"""
+
+"""MCP Gateway Skill for SignalWire Agents"""