signalwire-agents 0.1.23__py3-none-any.whl → 0.1.24__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/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/native_vector_search/skill.py

@@ -190,6 +190,37 @@ class NativeVectorSearchSkill(SkillBase):
             **self.swaig_fields
         )
         
+        # Add our tool to the Knowledge Search section
+        search_mode = "remote search server" if self.use_remote else "local document indexes"
+        section_title = "Knowledge Search"
+        
+        # Try to check if section exists, but handle if method doesn't exist
+        section_exists = False
+        try:
+            if hasattr(self.agent, 'prompt_has_section'):
+                section_exists = self.agent.prompt_has_section(section_title)
+        except Exception:
+            # Method might not work, assume section doesn't exist
+            pass
+        
+        if section_exists:
+            # Add bullet to existing section
+            self.agent.prompt_add_to_section(
+                title=section_title,
+                bullet=f"Use {self.tool_name} to search {search_mode}: {description}"
+            )
+        else:
+            # Create the section with this tool
+            self.agent.prompt_add_section(
+                title=section_title,
+                body="You can search various knowledge sources using the following tools:",
+                bullets=[
+                    f"Use {self.tool_name} to search {search_mode}: {description}",
+                    "Search for relevant information using clear, specific queries",
+                    "If no results are found, suggest the user try rephrasing their question or try another knowledge source"
+                ]
+            )
+        
     def _search_handler(self, args, raw_data):
         """Handle search requests"""
         
@@ -365,19 +396,8 @@ class NativeVectorSearchSkill(SkillBase):
         
     def get_prompt_sections(self) -> List[Dict[str, Any]]:
         """Return prompt sections to add to agent"""
-        search_mode = "remote search server" if self.use_remote else "local document indexes"
-        return [
-            {
-                "title": "Document Search",
-                "body": f"You can search {search_mode} using the {self.tool_name} tool.",
-                "bullets": [
-                    f"Use the {self.tool_name} tool when users ask questions about topics that might be in the indexed documents",
-                    "Search for relevant information using clear, specific queries",
-                    "Provide helpful summaries of the search results",
-                    "If no results are found, suggest the user try rephrasing their question or ask about different topics"
-                ]
-            }
-        ]
+        # We'll handle this in register_tools after the agent is set
+        return []
     
     def _add_prompt_section(self, agent):
         """Add prompt section to agent (called during skill loading)"""

signalwire_agents/skills/play_background_file/README.md

@@ -0,0 +1,218 @@
+# Play Background File Skill
+
+A configurable skill for managing background file playback with custom tool names and multiple file collections. Supports both audio and video files with serverless DataMap execution.
+
+## Features
+
+- **Multiple Instances**: Create different tools with unique names and file sets
+- **Dynamic Enum Generation**: Function parameters built from your file configuration
+- **Audio & Video Support**: Works with any background file type
+- **DataMap Efficiency**: Serverless execution, no agent processing load
+- **Post-Processing**: AI speaks first, then executes the action
+- **Configurable Wait**: Control attention-getting behavior per file
+
+## Configuration
+
+### Basic Structure
+
+```python
+agent.add_skill("play_background_file", {
+    "tool_name": "your_custom_tool_name",
+    "files": [
+        {
+            "key": "unique_identifier",
+            "description": "Human readable description",
+            "url": "https://example.com/file.mp4",
+            "wait": True  # Optional, defaults to False
+        }
+    ]
+})
+```
+
+### Parameters
+
+- **tool_name** (string): Custom name for the generated SWAIG function (default: "play_background_file")
+- **files** (array): List of file objects to manage
+
+### File Object Properties
+
+- **key** (string, required): Unique identifier for the file (alphanumeric, underscores, hyphens only)
+- **description** (string, required): Human-readable description used in AI responses
+- **url** (string, required): URL to the audio/video file
+- **wait** (boolean, optional): Whether to suppress attention-getting behavior during playback (default: false)
+
+## Usage Examples
+
+### Single File Testimonial
+
+```python
+agent.add_skill("play_background_file", {
+    "tool_name": "play_testimonial",
+    "files": [
+        {
+            "key": "massey_success",
+            "description": "Customer success story from Massey Energy",
+            "url": "https://tatooine.cantina.cloud/vids/massey.mp4",
+            "wait": True
+        }
+    ]
+})
+```
+
+**Generated Tool**: `play_testimonial(action)`
+**Actions**: `["start_massey_success", "stop"]`
+
+### Multiple Demo Videos
+
+```python
+agent.add_skill("play_background_file", {
+    "tool_name": "play_demo",
+    "files": [
+        {
+            "key": "product_overview",
+            "description": "Product overview demonstration",
+            "url": "https://example.com/overview.mp4",
+            "wait": False
+        },
+        {
+            "key": "advanced_features",
+            "description": "Advanced features walkthrough", 
+            "url": "https://example.com/advanced.mp4",
+            "wait": True
+        }
+    ]
+})
+```
+
+**Generated Tool**: `play_demo(action)`
+**Actions**: `["start_product_overview", "start_advanced_features", "stop"]`
+
+### Music Playlist
+
+```python
+agent.add_skill("play_background_file", {
+    "tool_name": "play_music",
+    "files": [
+        {
+            "key": "jazz",
+            "description": "smooth jazz background music",
+            "url": "https://example.com/jazz.mp3"
+        },
+        {
+            "key": "classical",
+            "description": "classical piano background music",
+            "url": "https://example.com/classical.mp3"
+        }
+    ]
+})
+```
+
+## Generated SWAIG Function
+
+For the testimonial example above, the skill generates:
+
+```json
+{
+    "function": "play_testimonial",
+    "description": "Control background file playback for play testimonial",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "description": "Action to perform. Options: start_massey_success: Customer success story from Massey Energy; stop: Stop any currently playing background file",
+                "enum": ["start_massey_success", "stop"]
+            }
+        },
+        "required": ["action"]
+    },
+    "data_map": {
+        "expressions": [
+            {
+                "string": "${args.action}",
+                "pattern": "/start_massey_success/i",
+                "output": {
+                    "response": "Tell the user you are now going to play Customer success story from Massey Energy for them.",
+                    "action": [
+                        {
+                            "playback_bg": {
+                                "file": "https://tatooine.cantina.cloud/vids/massey.mp4",
+                                "wait": true
+                            }
+                        }
+                    ],
+                    "post_process": true
+                }
+            },
+            {
+                "string": "${args.action}",
+                "pattern": "/stop/i",
+                "output": {
+                    "response": "Tell the user you have stopped the background file playback.",
+                    "action": [
+                        {
+                            "stop_playback_bg": true
+                        }
+                    ],
+                    "post_process": true
+                }
+            }
+        ]
+    }
+}
+```
+
+## Execution Flow
+
+1. **AI calls function**: `play_testimonial(action: "start_massey_success")`
+2. **DataMap matches pattern**: `/start_massey_success/i`
+3. **AI receives instruction**: "Tell the user you are now going to play Customer success story from Massey Energy for them."
+4. **AI responds naturally**: The AI interprets this and responds in its own voice
+5. **Action executes**: Background video starts playing
+6. **User experience**: Natural AI announcement before action
+
+## Multiple Instances
+
+You can add multiple instances of this skill with different tool names:
+
+```python
+# Testimonials
+agent.add_skill("play_background_file", {
+    "tool_name": "play_testimonial",
+    "files": [{"key": "massey", "description": "Massey Energy success story", "url": "..."}]
+})
+
+# Demos  
+agent.add_skill("play_background_file", {
+    "tool_name": "play_demo",
+    "files": [
+        {"key": "overview", "description": "Product overview", "url": "..."},
+        {"key": "features", "description": "Advanced features", "url": "..."}
+    ]
+})
+
+# Music
+agent.add_skill("play_background_file", {
+    "tool_name": "play_music", 
+    "files": [{"key": "jazz", "description": "Jazz music", "url": "..."}]
+})
+```
+
+This creates three separate tools: `play_testimonial`, `play_demo`, and `play_music`.
+
+## Benefits
+
+- **Reusable**: Same skill manages different file collections
+- **Configurable**: Easy to add/remove files without code changes  
+- **Efficient**: DataMap serverless execution
+- **Type Safe**: Enum parameters prevent invalid file references
+- **Natural**: AI speaks before actions with post-processing
+- **Maintainable**: Centralized file management logic
+
+## Implementation Notes
+
+- File keys are converted to `start_{key}` enum values
+- All tools include a "stop" action to halt playback
+- Post-processing is enabled by default for natural conversation flow
+- The skill validates all configuration parameters at initialization
+- Instance keys combine skill name and tool name for uniqueness