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

signalwire_agents/skills/datasphere_serverless/README.md

@@ -0,0 +1,258 @@
+# DataSphere Serverless Skill
+
+The datasphere_serverless skill provides knowledge search capabilities using SignalWire DataSphere's RAG (Retrieval-Augmented Generation) stack with serverless execution via DataMap. This skill offers the same functionality as the standard datasphere skill but executes on SignalWire servers rather than your agent server.
+
+## Features
+
+- **Serverless Execution**: Runs on SignalWire infrastructure via DataMap
+- **SignalWire DataSphere Integration**: Vector-based knowledge search
+- **Identical API**: Same parameters and functionality as the standard datasphere skill
+- **Multi-language Support**: Synonym expansion and language-specific search
+- **Tag-based Filtering**: Targeted searches using document tags
+- **Custom No-results Messages**: Configurable response templates
+- **Multiple Instance Support**: Search different knowledge bases with different configurations
+- **No Webhook Infrastructure**: No need to expose HTTP endpoints
+
+## Requirements
+
+- **Packages**: None (DataMap handles API calls serverlessly)
+- **SignalWire Account**: DataSphere-enabled space with uploaded documents
+
+## Parameters
+
+### Required Parameters
+
+- `space_name` (string): SignalWire space name
+- `project_id` (string): SignalWire project ID  
+- `token` (string): SignalWire authentication token
+- `document_id` (string): DataSphere document ID to search
+
+### Optional Parameters
+
+- `count` (integer, default: 1): Number of search results to return
+- `distance` (float, default: 3.0): Distance threshold for search matching (lower = more similar)
+- `tags` (list): List of tags to filter search results
+- `language` (string): Language code to limit search (e.g., "en", "es")
+- `pos_to_expand` (list): Parts of speech for synonym expansion (e.g., ["NOUN", "VERB"])
+- `max_synonyms` (integer): Maximum number of synonyms to use for each word
+- `tool_name` (string, default: "search_knowledge"): Custom name for the search tool (enables multiple instances)
+- `no_results_message` (string): Custom message 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."
+  - Use `{query}` as placeholder for the search query
+
+### Advanced Parameters
+
+- `swaig_fields` (dict): Additional SWAIG function configuration
+  - `secure` (boolean): Override security settings
+  - `fillers` (dict): Language-specific filler phrases during search
+  - Any other SWAIG function parameters
+
+## Tools Created
+
+- **Default**: `search_knowledge` - Search the knowledge base for information
+- **Custom**: Uses the `tool_name` parameter value
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+# Minimal configuration - same as standard datasphere skill
+agent.add_skill("datasphere_serverless", {
+    "space_name": "my-space",
+    "project_id": "my-project-id",
+    "token": "my-token",
+    "document_id": "my-document-id"
+})
+```
+
+### Advanced Configuration
+
+```python
+# Comprehensive search with filtering - identical to standard skill
+agent.add_skill("datasphere_serverless", {
+    "space_name": "my-space",
+    "project_id": "my-project-id",
+    "token": "my-token",
+    "document_id": "my-document-id",
+    "count": 3,
+    "distance": 5.0,
+    "tags": ["FAQ", "Support"],
+    "language": "en",
+    "pos_to_expand": ["NOUN", "VERB"],
+    "max_synonyms": 3,
+    "no_results_message": "I couldn't find information about '{query}' in our support documentation."
+})
+```
+
+### Multiple Instances
+
+```python
+# Product documentation search
+agent.add_skill("datasphere_serverless", {
+    "space_name": "my-space",
+    "project_id": "my-project-id",
+    "token": "my-token",
+    "document_id": "product-docs-id",
+    "tool_name": "search_product_docs",
+    "tags": ["Products", "Features"],
+    "count": 2
+})
+
+# Support knowledge base search
+agent.add_skill("datasphere_serverless", {
+    "space_name": "my-space",
+    "project_id": "my-project-id",
+    "token": "my-token",
+    "document_id": "support-kb-id",
+    "tool_name": "search_support",
+    "tags": ["Support", "Troubleshooting"],
+    "count": 3,
+    "distance": 4.0
+})
+```
+
+## DataMap Implementation Details
+
+This skill demonstrates advanced DataMap usage patterns:
+
+### 1. **Serverless API Integration**
+- API calls execute on SignalWire servers, not your agent server
+- No webhook endpoints required
+- Built-in authentication and error handling
+
+### 2. **Dynamic Request Building**
+```python
+webhook_body = {
+    "document_id": self.document_id,
+    "query_string": "${args.query}",  # Dynamic from user input
+    "distance": self.distance,         # Static from configuration
+    "count": self.count               # Static from configuration
+}
+
+# Optional parameters added conditionally
+if self.tags is not None:
+    webhook_body["tags"] = self.tags
+```
+
+### 3. **Response Processing with Foreach**
+```python
+.foreach({
+    "input_key": "results",           # API response key containing array
+    "output_key": "formatted_results", # Name for built string
+    "max": self.count,                # Limit processing
+    "append": "=== RESULT ${this.index} ===\n${this.content}\n========\n\n"
+})
+```
+
+The `foreach` mechanism:
+- Iterates over the `results` array from DataSphere API response
+- For each result, expands `${this.content}` with the result's content field
+- Builds a concatenated string stored as `formatted_results`
+- Limits processing to `max` items
+
+### 4. **Variable Expansion in Output**
+```python
+.output(SwaigFunctionResult('I found ${results.length} result(s) for "${args.query}":\n\n${formatted_results}'))
+```
+
+References:
+- `${results.length}`: Number of results from API
+- `${args.query}`: User's search query
+- `${formatted_results}`: String built by foreach
+
+### 5. **Error Handling**
+```python
+.error_keys(['error', 'message'])
+.fallback_output(SwaigFunctionResult(self.no_results_message.replace('{query}', '${args.query}')))
+```
+
+## Comparison: Standard vs Serverless
+
+| Feature | Standard DataSphere | DataSphere Serverless |
+|---------|-------------------|---------------------|
+| **Execution** | Agent server | SignalWire servers |
+| **Parameters** | Identical | Identical |
+| **Functionality** | Full Python logic | DataMap templates |
+| **Performance** | Agent server load | No agent server load |
+| **Deployment** | Webhook infrastructure | No infrastructure needed |
+| **Response Formatting** | Custom Python code | DataMap foreach/templates |
+| **Error Handling** | Granular Python exceptions | DataMap error keys |
+| **Use Case** | Complex custom logic | Standard API integration |
+
+## When to Use Serverless vs Standard
+
+### **Use DataSphere Serverless When:**
+- You want simple deployment without webhook infrastructure
+- Performance on agent server is a concern
+- Standard response formatting is sufficient
+- You prefer serverless execution model
+
+### **Use Standard DataSphere When:**
+- You need complex custom response formatting
+- You want granular error handling with different messages per error type
+- You need runtime decision-making logic
+- You want full control over the search process
+
+## Benefits of DataMap Implementation
+
+1. **Simplified Deployment**: No HTTP endpoints to expose or manage
+2. **Better Performance**: Executes on SignalWire infrastructure
+3. **Reduced Complexity**: Declarative configuration vs imperative code
+4. **Automatic Scaling**: SignalWire handles execution scaling
+5. **Built-in Reliability**: Server-side execution with built-in retry logic
+
+## How It Works
+
+1. **Configuration**: Skill parameters are validated and stored during setup
+2. **Tool Registration**: DataMap configuration is built with static values from setup
+3. **Execution**: When called, DataMap executes on SignalWire servers:
+   - Makes POST request to DataSphere API with user's query
+   - Processes response array using foreach mechanism
+   - Formats results using template expansion
+   - Returns formatted response to agent
+4. **Response**: Agent receives formatted results without any local processing
+
+## Multiple Instance Support
+
+Like the standard datasphere skill, this supports multiple instances:
+
+- Each instance creates a tool with a unique name (`tool_name` parameter)
+- Different configurations per instance (different documents, tags, etc.)
+- Instance tracking via `get_instance_key()` method
+- Same agent can search multiple knowledge bases
+
+## Error Handling
+
+- **API Errors**: Handled by `error_keys` configuration
+- **No Results**: Uses `fallback_output` with custom message
+- **Invalid Parameters**: Validated during skill setup
+- **Timeout/Network**: Handled by SignalWire infrastructure
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Missing required parameters"**
+   - Ensure all required parameters are provided
+   - Check parameter names match exactly
+
+2. **"No results found"**
+   - Verify document_id exists and is accessible
+   - Check distance threshold isn't too restrictive
+   - Ensure tags match document tags if specified
+
+3. **"Authentication failed"**
+   - Verify project_id and token are correct
+   - Ensure token has DataSphere permissions
+
+### Debugging
+
+Enable debug logging to see DataMap execution:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+DataMap execution details are logged by the SignalWire server infrastructure. 

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

signalwire_agents/skills/datasphere_serverless/skill.py

@@ -26,6 +26,88 @@ class DataSphereServerlessSkill(SkillBase):
     # 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
@@ -83,7 +165,6 @@ class DataSphereServerlessSkill(SkillBase):
         webhook_params = {
             "document_id": self.document_id,
             "query_string": "${args.query}",  # Only this is dynamic from user input
-            "distance": self.distance,
             "count": self.count
         }
         

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

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

signalwire_agents/skills/datetime/skill.py

@@ -30,7 +30,7 @@ class DateTimeSkill(SkillBase):
     def register_tools(self) -> None:
         """Register datetime tools with the agent"""
         
-        self.agent.define_tool(
+        self.define_tool(
             name="get_current_time",
             description="Get the current time, optionally in a specific timezone",
             parameters={
@@ -39,11 +39,10 @@ class DateTimeSkill(SkillBase):
                     "description": "Timezone name (e.g., 'America/New_York', 'Europe/London'). Defaults to UTC."
                 }
             },
-            handler=self._get_time_handler,
-            **self.swaig_fields
+            handler=self._get_time_handler
         )
         
-        self.agent.define_tool(
+        self.define_tool(
             name="get_current_date",
             description="Get the current date",
             parameters={
@@ -52,8 +51,7 @@ class DateTimeSkill(SkillBase):
                     "description": "Timezone name for the date. Defaults to UTC."
                 }
             },
-            handler=self._get_date_handler,
-            **self.swaig_fields
+            handler=self._get_date_handler
         )
         
     def _get_time_handler(self, args, raw_data):
@@ -110,4 +108,19 @@ class DateTimeSkill(SkillBase):
                     "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