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

signalwire_agents/skills/datasphere_serverless/skill.py

@@ -0,0 +1,237 @@
+"""
+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 base64
+from typing import Optional, 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 DataSphereServerlessSkill(SkillBase):
+    """SignalWire DataSphere knowledge search using DataMap (serverless execution)"""
+    
+    SKILL_NAME = "datasphere_serverless"
+    SKILL_DESCRIPTION = "Search knowledge using SignalWire DataSphere with serverless DataMap execution"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = []  # DataMap handles API calls serverlessly
+    REQUIRED_ENV_VARS = []  # No required env vars since all config comes from params
+    
+    # Enable multiple instances support
+    SUPPORTS_MULTIPLE_INSTANCES = True
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """Get parameter schema for DataSphere Serverless skill"""
+        schema = super().get_parameter_schema()
+        schema.update({
+            "space_name": {
+                "type": "string",
+                "description": "SignalWire space name (e.g., 'mycompany' from mycompany.signalwire.com)",
+                "required": True
+            },
+            "project_id": {
+                "type": "string",
+                "description": "SignalWire project ID",
+                "required": True,
+                "env_var": "SIGNALWIRE_PROJECT_ID"
+            },
+            "token": {
+                "type": "string",
+                "description": "SignalWire API token",
+                "required": True,
+                "hidden": True,
+                "env_var": "SIGNALWIRE_TOKEN"
+            },
+            "document_id": {
+                "type": "string",
+                "description": "DataSphere document ID to search within",
+                "required": True
+            },
+            "count": {
+                "type": "integer",
+                "description": "Number of search results to return",
+                "default": 1,
+                "required": False,
+                "minimum": 1,
+                "maximum": 10
+            },
+            "distance": {
+                "type": "number",
+                "description": "Maximum distance threshold for results (lower is more relevant)",
+                "default": 3.0,
+                "required": False,
+                "minimum": 0.0,
+                "maximum": 10.0
+            },
+            "tags": {
+                "type": "array",
+                "description": "Tags to filter search results",
+                "required": False,
+                "items": {
+                    "type": "string"
+                }
+            },
+            "language": {
+                "type": "string",
+                "description": "Language code for query expansion (e.g., 'en', 'es')",
+                "required": False
+            },
+            "pos_to_expand": {
+                "type": "array",
+                "description": "Parts of speech to expand with synonyms",
+                "required": False,
+                "items": {
+                    "type": "string",
+                    "enum": ["NOUN", "VERB", "ADJ", "ADV"]
+                }
+            },
+            "max_synonyms": {
+                "type": "integer",
+                "description": "Maximum number of synonyms to use for query expansion",
+                "required": False,
+                "minimum": 1,
+                "maximum": 10
+            },
+            "no_results_message": {
+                "type": "string",
+                "description": "Message to return when no results are found",
+                "default": "I couldn't find any relevant information for '{query}' in the knowledge base. Try rephrasing your question or asking about a different topic.",
+                "required": False
+            }
+        })
+        return schema
+    
+    def get_instance_key(self) -> str:
+        """
+        Get the key used to track this skill instance
+        
+        For DataSphere Serverless, we use 'search_knowledge' as the default tool name
+        """
+        tool_name = self.params.get('tool_name', 'search_knowledge')
+        return f"{self.SKILL_NAME}_{tool_name}"
+    
+    def setup(self) -> bool:
+        """Setup the datasphere serverless skill"""
+        # Validate required parameters
+        required_params = ['space_name', 'project_id', 'token', 'document_id']
+        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 required parameters
+        self.space_name = self.params['space_name']
+        self.project_id = self.params['project_id'] 
+        self.token = self.params['token']
+        self.document_id = self.params['document_id']
+        
+        # Set optional parameters with defaults
+        self.count = self.params.get('count', 1)
+        self.distance = self.params.get('distance', 3.0)
+        self.tags = self.params.get('tags', None)  
+        self.language = self.params.get('language', None)  
+        self.pos_to_expand = self.params.get('pos_to_expand', None)  
+        self.max_synonyms = self.params.get('max_synonyms', None)  
+        
+        # Tool name (for multiple instances)
+        self.tool_name = self.params.get('tool_name', 'search_knowledge')
+        
+        # No results message
+        self.no_results_message = self.params.get('no_results_message',
+            "I couldn't find any relevant information for '{query}' in the knowledge base. "
+            "Try rephrasing your question or asking about a different topic."
+        )
+        
+        # Build API URL
+        self.api_url = f"https://{self.space_name}.signalwire.com/api/datasphere/documents/search"
+        
+        # Build auth header for DataMap
+        auth_string = f"{self.project_id}:{self.token}"
+        self.auth_header = base64.b64encode(auth_string.encode()).decode()
+        
+        return True
+        
+    def register_tools(self) -> None:
+        """Register knowledge search tool using DataMap"""
+        
+        # Build webhook params with configuration values
+        webhook_params = {
+            "document_id": self.document_id,
+            "query_string": "${args.query}",  # Only this is dynamic from user input
+            "count": self.count
+        }
+        
+        # Add optional parameters only if they were provided
+        if self.tags is not None:
+            webhook_params["tags"] = self.tags
+        if self.language is not None:
+            webhook_params["language"] = self.language
+        if self.pos_to_expand is not None:
+            webhook_params["pos_to_expand"] = self.pos_to_expand
+        if self.max_synonyms is not None:
+            webhook_params["max_synonyms"] = self.max_synonyms
+        
+        # Create DataMap tool for DataSphere search
+        datasphere_tool = (DataMap(self.tool_name)
+            .description("Search the knowledge base for information on any topic and return relevant results")
+            .parameter('query', 'string', 'The search query - what information you\'re looking for in the knowledge base', required=True)
+            .webhook('POST', self.api_url,
+                     headers={
+                         'Content-Type': 'application/json',
+                         'Authorization': f'Basic {self.auth_header}'
+                     })
+            .params(webhook_params)
+            .foreach({
+                "input_key": "chunks",
+                "output_key": "formatted_results",
+                "max": self.count,
+                "append": "=== RESULT ===\n${this.text}\n" + "="*50 + "\n\n"
+            })
+            .output(SwaigFunctionResult('I found results for "${args.query}":\n\n${formatted_results}'))
+            .error_keys(['error'])
+            .fallback_output(SwaigFunctionResult(self.no_results_message.replace('{query}', '${args.query}')))
+        )
+        
+        # Convert DataMap to SWAIG function and apply swaig_fields
+        swaig_function = datasphere_tool.to_swaig_function()
+        
+        # Merge swaig_fields from skill params into the function definition
+        swaig_function.update(self.swaig_fields)
+        
+        # Register the enhanced DataMap tool with the agent
+        self.agent.register_swaig_function(swaig_function)
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        return []
+        
+    def get_global_data(self) -> Dict[str, Any]:
+        """Return global data for agent context"""
+        return {
+            "datasphere_serverless_enabled": True,
+            "document_id": self.document_id,
+            "knowledge_provider": "SignalWire DataSphere (Serverless)"
+        }
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return [
+            {
+                "title": "Knowledge Search Capability (Serverless)",
+                "body": f"You can search a knowledge base for information using the {self.tool_name} tool.",
+                "bullets": [
+                    f"Use the {self.tool_name} tool when users ask for information that might be in the knowledge base",
+                    "Search for relevant information using clear, specific queries",
+                    "Summarize search results in a clear, helpful way",
+                    "If no results are found, suggest the user try rephrasing their question",
+                    "This tool executes on SignalWire servers for optimal performance"
+                ]
+            }
+        ] 

signalwire_agents/skills/datetime/README.md

@@ -0,0 +1,132 @@
+# DateTime Skill
+
+The datetime skill provides current date and time information with timezone support. It allows agents to tell users the current time and date in any timezone around the world.
+
+## Features
+
+- Current time retrieval with timezone support
+- Current date retrieval with timezone support
+- Automatic timezone conversion using pytz
+- Human-readable time and date formatting
+- UTC default with custom timezone options
+
+## Requirements
+
+- **Packages**: `pytz`
+- **No external APIs required**
+
+## Parameters
+
+### Optional Parameters
+
+- `swaig_fields` (dict): Additional SWAIG function configuration
+  - `secure` (boolean): Override security settings for the time/date functions
+  - `fillers` (dict): Language-specific filler phrases while retrieving time/date
+  - 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
+
+- `get_current_time` - Get the current time, optionally in a specific timezone
+- `get_current_date` - Get the current date, optionally in a specific timezone
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+# No configuration needed - works immediately
+agent.add_skill("datetime")
+```
+
+### With Custom Fillers
+
+```python
+agent.add_skill("datetime", {
+    "swaig_fields": {
+        "fillers": {
+            "en-US": [
+                "Let me check the time...",
+                "Looking up the current date...",
+                "Getting the time for you..."
+            ],
+            "es-ES": [
+                "Déjame verificar la hora...",
+                "Consultando la fecha actual..."
+            ]
+        }
+    }
+})
+```
+
+### Disabling Security (if needed)
+
+```python
+agent.add_skill("datetime", {
+    "swaig_fields": {
+        "secure": False  # Allow unauthenticated time/date requests
+    }
+})
+```
+
+## How It Works
+
+### Time Function
+- **Input**: Optional timezone parameter (e.g., "America/New_York", "Europe/London")
+- **Default**: UTC timezone if no timezone specified
+- **Output**: Time in 12-hour format with AM/PM and timezone abbreviation
+- **Example**: "The current time is 02:30:45 PM EST"
+
+### Date Function
+- **Input**: Optional timezone parameter for date calculation
+- **Default**: UTC timezone if no timezone specified  
+- **Output**: Full date in readable format
+- **Example**: "Today's date is Friday, December 15, 2023"
+
+### Timezone Support
+- Uses the `pytz` library for accurate timezone handling
+- Supports all standard timezone names (e.g., "America/New_York", "Asia/Tokyo")
+- Handles daylight saving time automatically
+- Falls back to UTC for invalid timezone names
+
+## Function Parameters
+
+Both tools accept the same optional parameter:
+
+- `timezone` (string, optional): Timezone name for the time/date
+  - Examples: "America/New_York", "Europe/London", "Asia/Tokyo", "UTC"
+  - Default: "UTC" if not specified
+  - Invalid timezones will cause an error message to be returned
+
+## Error Handling
+
+- **Invalid Timezone**: Returns error message with the invalid timezone name
+- **System Issues**: Returns friendly error message for any datetime calculation problems
+- **Graceful Fallback**: Continues to work even if timezone data is corrupted
+
+## Common Timezone Examples
+
+- **US Timezones**: "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles"
+- **European Timezones**: "Europe/London", "Europe/Paris", "Europe/Berlin", "Europe/Rome"
+- **Asian Timezones**: "Asia/Tokyo", "Asia/Shanghai", "Asia/Kolkata", "Asia/Dubai"
+- **Other Regions**: "Australia/Sydney", "Africa/Cairo", "America/Sao_Paulo"
+
+## Best Practices
+
+1. **Default Behavior**: The skill works immediately without configuration
+2. **User Queries**: Handle questions like "What time is it?", "What's today's date?", "What time is it in Tokyo?"
+3. **Timezone Validation**: The skill gracefully handles invalid timezone names
+4. **Localization**: Use fillers in different languages for multilingual agents
+5. **Performance**: Very fast since no external API calls are required
+
+## Agent Integration
+
+When added to an agent, this skill automatically:
+
+- Adds speech recognition hints for time/date related words
+- Provides prompt guidance about time/date capabilities
+- Enables the agent to respond to time and date questions
+- Works with any timezone the user requests
+
+The skill is designed to be maintenance-free and always available, making it ideal for customer service and general-purpose agents that need to provide time and date information. 

signalwire_agents/skills/datetime/__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.
+"""
+
+"""DateTime Skill for SignalWire Agents""" 

signalwire_agents/skills/datetime/skill.py

@@ -0,0 +1,126 @@
+"""
+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 datetime import datetime, timezone
+import pytz
+from typing import List, Dict, Any
+
+from signalwire_agents.core.skill_base import SkillBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+class DateTimeSkill(SkillBase):
+    """Provides current date, time, and timezone information"""
+    
+    SKILL_NAME = "datetime"
+    SKILL_DESCRIPTION = "Get current date, time, and timezone information"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = ["pytz"]
+    REQUIRED_ENV_VARS = []
+    
+    def setup(self) -> bool:
+        """Setup the datetime skill"""
+        return self.validate_packages()
+        
+    def register_tools(self) -> None:
+        """Register datetime tools with the agent"""
+        
+        self.define_tool(
+            name="get_current_time",
+            description="Get the current time, optionally in a specific timezone",
+            parameters={
+                "timezone": {
+                    "type": "string",
+                    "description": "Timezone name (e.g., 'America/New_York', 'Europe/London'). Defaults to UTC."
+                }
+            },
+            handler=self._get_time_handler
+        )
+        
+        self.define_tool(
+            name="get_current_date",
+            description="Get the current date",
+            parameters={
+                "timezone": {
+                    "type": "string", 
+                    "description": "Timezone name for the date. Defaults to UTC."
+                }
+            },
+            handler=self._get_date_handler
+        )
+        
+    def _get_time_handler(self, args, raw_data):
+        """Handler for get_current_time tool"""
+        timezone_name = args.get("timezone", "UTC")
+        
+        try:
+            if timezone_name.upper() == "UTC":
+                tz = timezone.utc
+            else:
+                tz = pytz.timezone(timezone_name)
+                
+            now = datetime.now(tz)
+            time_str = now.strftime("%I:%M:%S %p %Z")
+            
+            return SwaigFunctionResult(f"The current time is {time_str}")
+            
+        except Exception as e:
+            return SwaigFunctionResult(f"Error getting time: {str(e)}")
+    
+    def _get_date_handler(self, args, raw_data):
+        """Handler for get_current_date tool"""
+        timezone_name = args.get("timezone", "UTC")
+        
+        try:
+            if timezone_name.upper() == "UTC":
+                tz = timezone.utc
+            else:
+                tz = pytz.timezone(timezone_name)
+                
+            now = datetime.now(tz)
+            date_str = now.strftime("%A, %B %d, %Y")
+            
+            return SwaigFunctionResult(f"Today's date is {date_str}")
+            
+        except Exception as e:
+            return SwaigFunctionResult(f"Error getting date: {str(e)}")
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        # Currently no hints provided, but you could add them like:
+        # return ["time", "date", "today", "now", "current", "timezone"]
+        return []
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return [
+            {
+                "title": "Date and Time Information", 
+                "body": "You can provide current date and time information.",
+                "bullets": [
+                    "Use get_current_time to tell users what time it is",
+                    "Use get_current_date to tell users today's date",
+                    "Both tools support different timezones"
+                ]
+            }
+        ]
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """
+        Get the parameter schema for the datetime skill
+        
+        The datetime 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 datetime skill
+        
+        return schema 

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

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