signalwire-agents 0.1.23__py3-none-any.whl → 0.1.24__py3-none-any.whl

signalwire_agents/skills/datasphere/README.md

@@ -0,0 +1,210 @@
+# DataSphere Skill
+
+The datasphere skill provides knowledge search capabilities using SignalWire DataSphere's RAG (Retrieval-Augmented Generation) stack. It allows agents to search through uploaded documents and knowledge bases to find relevant information.
+
+## Features
+
+- SignalWire DataSphere integration for knowledge search
+- Vector-based similarity search with configurable distance thresholds
+- Multi-language support and synonym expansion
+- Tag-based filtering for targeted searches
+- Custom no-results messages with query placeholders
+- **Multiple instance support** - search different knowledge bases with different configurations
+
+## Requirements
+
+- **Packages**: `requests`
+- **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
+agent.add_skill("datasphere", {
+    "space_name": "my-space",
+    "project_id": "my-project-id",
+    "token": "my-token",
+    "document_id": "my-document-id"
+})
+```
+
+### Advanced Configuration
+
+```python
+# Comprehensive search with filtering
+agent.add_skill("datasphere", {
+    "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", {
+    "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", {
+    "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
+})
+
+# Policy and procedure search
+agent.add_skill("datasphere", {
+    "space_name": "my-space",
+    "project_id": "my-project-id",
+    "token": "my-token",
+    "document_id": "policies-id",
+    "tool_name": "search_policies",
+    "tags": ["Policy", "Compliance"],
+    "count": 1,
+    "distance": 2.0
+})
+```
+
+### With Custom Fillers
+
+```python
+agent.add_skill("datasphere", {
+    "space_name": "my-space",
+    "project_id": "my-project-id",
+    "token": "my-token", 
+    "document_id": "my-document-id",
+    "swaig_fields": {
+        "fillers": {
+            "en-US": [
+                "Searching our knowledge base...",
+                "Looking through our documentation...",
+                "Checking our information database..."
+            ],
+            "es-ES": [
+                "Buscando en nuestra base de conocimientos...",
+                "Revisando nuestra documentación..."
+            ]
+        }
+    }
+})
+```
+
+## How It Works
+
+1. **Vector Search**: Uses semantic similarity to find relevant content chunks
+2. **Distance Filtering**: Only returns results within the specified distance threshold
+3. **Tag Filtering**: Optionally filters results by document tags
+4. **Language Processing**: Supports synonym expansion and language-specific search
+5. **Format Results**: Presents found content with metadata and relevance scores
+
+## Multiple Instance Support
+
+The datasphere skill supports multiple instances, allowing you to:
+
+- Search different knowledge bases/documents with one agent
+- Use different search parameters per knowledge domain
+- Create specialized search tools (`search_products`, `search_support`, etc.)
+- Apply different tag filtering per instance
+- Customize distance thresholds based on content type
+
+Each instance is uniquely identified by its `search_engine_id` (derived from space/project/document) and `tool_name` combination.
+
+## Parameters Explained
+
+### Distance Threshold
+- **Lower values** (1.0-2.0): Very strict matching, only highly similar content
+- **Medium values** (3.0-4.0): Balanced matching, good for most use cases
+- **Higher values** (5.0+): More permissive matching, broader results
+
+### Count vs Distance
+- Use higher `count` with lower `distance` for precise, multiple results
+- Use lower `count` with higher `distance` for broader, fewer results
+
+### Tags Usage
+- Pre-tag your documents in DataSphere with categories
+- Use tags to create domain-specific searches (e.g., ["FAQ"], ["Legal"], ["Technical"])
+
+### Language Support
+- Specify language codes for multilingual knowledge bases
+- Helps improve search accuracy for non-English content
+
+## Error Handling
+
+- **No Results**: Returns custom `no_results_message` with query placeholder
+- **API Issues**: Returns friendly error message for authentication/connectivity issues
+- **Invalid Documents**: Gracefully handles missing or inaccessible documents
+- **Timeout Protection**: Built-in 30-second timeout for API requests
+
+## Best Practices
+
+1. **Document Organization**: Use meaningful tags when uploading to DataSphere
+2. **Distance Tuning**: Start with default 3.0, adjust based on result quality
+3. **Multiple Instances**: Separate different knowledge domains for better results
+4. **Language Consistency**: Specify language when dealing with multilingual content
+5. **Result Count**: Balance between comprehensive answers (higher count) and response speed (lower count)
+
+## Setting Up DataSphere
+
+1. Access your SignalWire space
+2. Enable DataSphere in your space settings
+3. Upload documents through the DataSphere interface
+4. Note the document IDs for use in skill configuration
+5. Apply appropriate tags during document upload
+6. Get your project ID and token from SignalWire console 

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/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.