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

signalwire_agents/skills/joke/README.md

@@ -0,0 +1,149 @@
+# Joke Skill
+
+Tell jokes using the API Ninjas joke API with DataMap integration.
+
+## Description
+
+The Joke skill provides joke-telling capabilities to your SignalWire AI agents using the API Ninjas joke API. This skill demonstrates how to use DataMap for external API integration without requiring custom webhook endpoints.
+
+## Features
+
+- **Random Jokes**: Get random jokes from API Ninjas
+- **Dad Jokes**: Specifically request dad jokes
+- **DataMap Integration**: Uses DataMap for serverless API execution
+- **Configurable Tool Name**: Support for custom tool names
+- **Required Parameter Validation**: Ensures joke type is specified
+
+## Requirements
+
+- API Ninjas API key
+- No additional Python packages required (DataMap handles API calls)
+
+## Configuration
+
+### Required Parameters
+
+- `api_key`: Your API Ninjas API key
+
+### Optional Parameters
+
+- `tool_name`: Custom name for the joke function (default: "get_joke")
+
+## Usage
+
+### Basic Usage
+
+```python
+from signalwire_agents import AgentBase
+
+class MyAgent(AgentBase):
+    def __init__(self):
+        super().__init__(name="Joke Agent", route="/jokes")
+        
+        # Add joke skill
+        self.add_skill("joke", {
+            "api_key": "your-api-ninjas-api-key"
+        })
+
+agent = MyAgent()
+agent.serve()
+```
+
+### Advanced Usage
+
+```python
+# Custom tool name
+self.add_skill("joke", {
+    "api_key": "your-api-ninjas-api-key",
+    "tool_name": "tell_joke"
+})
+```
+
+## Function Details
+
+### `get_joke(type: str)`
+
+**Parameters:**
+- `type` (required): Type of joke to get
+  - `"jokes"` - Regular jokes
+  - `"dadjokes"` - Dad jokes
+
+**Returns:** A joke from the API Ninjas joke database
+
+**Example Usage:**
+- "Tell me a joke" (AI will choose the type)
+- "Tell me a dad joke" (AI will use type="dadjokes")
+- "Get me a regular joke" (AI will use type="jokes")
+
+## API Integration
+
+This skill integrates with the API Ninjas Jokes API:
+- **Endpoint**: `https://api.api-ninjas.com/v1/{type}`
+- **Method**: GET
+- **Authentication**: X-Api-Key header
+- **Response**: JSON array with joke objects
+
+## Getting an API Key
+
+1. Visit [API Ninjas](https://api.api-ninjas.com/)
+2. Sign up for a free account
+3. Get your API key from the dashboard
+4. Use the key in your skill configuration
+
+## Error Handling
+
+- Missing API key: Skill setup will fail with clear error message
+- Invalid joke type: Parameter validation ensures only valid types are accepted
+- API errors: Handled gracefully with user-friendly error messages
+
+## DataMap Implementation
+
+This skill demonstrates DataMap usage with:
+
+- **External API**: Calls API Ninjas joke endpoints
+- **Dynamic URLs**: Uses `${args.type}` for different joke types  
+- **Header Authentication**: Includes API key in request headers
+- **Response Processing**: Extracts joke from API response array
+- **Error Handling**: Handles API errors gracefully
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Missing required parameters: ['api_key']"**
+   - Ensure you provide a valid API Ninjas API key
+
+2. **"No jokes returned"**
+   - Check your API key is valid
+   - Verify API Ninjas service is accessible
+   - Check API quota/rate limits
+
+3. **"Tool not found"**
+   - Ensure skill loaded successfully
+   - Check for any setup errors in logs
+
+### Debugging
+
+Enable debug logging to see API requests:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## API Reference
+
+### API Ninjas Endpoints
+
+- `GET /v1/jokes` - Random jokes
+- `GET /v1/dadjokes` - Dad jokes
+
+### Response Format
+
+```json
+[
+  {
+    "joke": "Why don't scientists trust atoms? Because they make up everything!"
+  }
+]
+``` 

signalwire_agents/skills/joke/__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.
+"""
+
 """Joke Skill for SignalWire Agents using DataMap""" 

signalwire_agents/skills/joke/skill.py

@@ -23,6 +23,27 @@ class JokeSkill(SkillBase):
     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

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

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

signalwire_agents/skills/math/skill.py

@@ -29,7 +29,7 @@ class MathSkill(SkillBase):
     def register_tools(self) -> None:
         """Register math tools with the agent"""
         
-        self.agent.define_tool(
+        self.define_tool(
             name="calculate",
             description="Perform a mathematical calculation with basic operations (+, -, *, /, %, **)",
             parameters={
@@ -38,8 +38,7 @@ class MathSkill(SkillBase):
                     "description": "Mathematical expression to evaluate (e.g., '2 + 3 * 4', '(10 + 5) / 3')"
                 }
             },
-            handler=self._calculate_handler,
-            **self.swaig_fields
+            handler=self._calculate_handler
         )
         
     def _calculate_handler(self, args, raw_data):
@@ -88,4 +87,19 @@ class MathSkill(SkillBase):
                     "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"""