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

signalwire_agents/skills/datasphere/skill.py

@@ -0,0 +1,310 @@
+"""
+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 requests
+import json
+from typing import Optional, List, Dict, Any
+
+from signalwire_agents.core.skill_base import SkillBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+class DataSphereSkill(SkillBase):
+    """SignalWire DataSphere knowledge search capability"""
+    
+    SKILL_NAME = "datasphere"
+    SKILL_DESCRIPTION = "Search knowledge using SignalWire DataSphere RAG stack"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = ["requests"]
+    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 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, we use 'search_knowledge' as the default tool name instead of 'datasphere'
+        """
+        tool_name = self.params.get('tool_name', 'search_knowledge')
+        return f"{self.SKILL_NAME}_{tool_name}"
+    
+    def setup(self) -> bool:
+        """Setup the datasphere 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)  # None means don't include in request
+        self.language = self.params.get('language', None)  # None means don't include in request
+        self.pos_to_expand = self.params.get('pos_to_expand', None)  # None means don't include in request
+        self.max_synonyms = self.params.get('max_synonyms', None)  # None means don't include in request
+        
+        # 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"
+        
+        # Setup session for requests
+        self.session = requests.Session()
+        
+        return True
+        
+    def register_tools(self) -> None:
+        """Register knowledge search tool with the agent"""
+        self.define_tool(
+            name=self.tool_name,
+            description="Search the knowledge base for information on any topic and return relevant results",
+            parameters={
+                "query": {
+                    "type": "string",
+                    "description": "The search query - what information you're looking for in the knowledge base"
+                }
+            },
+            handler=self._search_knowledge_handler
+        )
+        
+    def _search_knowledge_handler(self, args, raw_data):
+        """Handler for knowledge search tool"""
+        query = args.get("query", "").strip()
+        
+        if not query:
+            return SwaigFunctionResult(
+                "Please provide a search query. What would you like me to search for in the knowledge base?"
+            )
+        
+        self.logger.info(f"DataSphere search requested: '{query}' (document: {self.document_id})")
+        
+        # Build request payload
+        payload = {
+            "document_id": self.document_id,
+            "query_string": query,
+            "distance": self.distance,
+            "count": self.count
+        }
+        
+        # Add optional parameters only if they were provided
+        if self.tags is not None:
+            payload["tags"] = self.tags
+        if self.language is not None:
+            payload["language"] = self.language
+        if self.pos_to_expand is not None:
+            payload["pos_to_expand"] = self.pos_to_expand
+        if self.max_synonyms is not None:
+            payload["max_synonyms"] = self.max_synonyms
+        
+        try:
+            # Make API request
+            response = self.session.post(
+                self.api_url,
+                auth=(self.project_id, self.token),
+                headers={
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json'
+                },
+                json=payload,
+                timeout=30
+            )
+            
+            response.raise_for_status()
+            data = response.json()
+            
+            # Check if we have valid response data
+            if not data or not isinstance(data, dict):
+                self.logger.warning(f"DataSphere API returned invalid data: {data}")
+                formatted_message = self.no_results_message.format(query=query) if '{query}' in self.no_results_message else self.no_results_message
+                return SwaigFunctionResult(formatted_message)
+            
+            # Extract results - DataSphere API returns 'chunks', not 'results'
+            chunks = data.get('chunks', [])
+            
+            if not chunks:
+                formatted_message = self.no_results_message.format(query=query) if '{query}' in self.no_results_message else self.no_results_message
+                return SwaigFunctionResult(formatted_message)
+            
+            # Format the results
+            formatted_results = self._format_search_results(query, chunks)
+            return SwaigFunctionResult(formatted_results)
+            
+        except requests.exceptions.Timeout:
+            self.logger.error("DataSphere API request timed out")
+            return SwaigFunctionResult(
+                "Sorry, the knowledge search timed out. Please try again."
+            )
+        except requests.exceptions.HTTPError as e:
+            self.logger.error(f"DataSphere API HTTP error: {e}")
+            return SwaigFunctionResult(
+                "Sorry, there was an error accessing the knowledge base. Please try again later."
+            )
+        except Exception as e:
+            self.logger.error(f"Error performing DataSphere search: {e}")
+            return SwaigFunctionResult(
+                "Sorry, I encountered an error while searching the knowledge base. Please try again later."
+            )
+    
+    def _format_search_results(self, query: str, chunks: List[Dict[str, Any]]) -> str:
+        """Format search results for display"""
+        if len(chunks) == 1:
+            result_text = f"I found 1 result for '{query}':\n\n"
+        else:
+            result_text = f"I found {len(chunks)} results for '{query}':\n\n"
+        
+        formatted_results = []
+        
+        for i, chunk in enumerate(chunks, 1):
+            result_content = f"=== RESULT {i} ===\n"
+            
+            # DataSphere API returns chunks with 'text' field
+            if 'text' in chunk:
+                result_content += chunk['text']
+            elif 'content' in chunk:
+                result_content += chunk['content']
+            elif 'chunk' in chunk:
+                result_content += chunk['chunk']
+            else:
+                # Fallback to the entire result as JSON if we don't recognize the format
+                result_content += json.dumps(chunk, indent=2)
+            
+            result_content += f"\n{'='*50}\n\n"
+            formatted_results.append(result_content)
+        
+        return result_text + '\n'.join(formatted_results)
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        # Currently no hints provided, but you could add them like:
+        # return [
+        #     "knowledge", "search", "information", "database", "find",
+        #     "look up", "research", "query", "datasphere", "document"
+        # ]
+        return []
+        
+    def get_global_data(self) -> Dict[str, Any]:
+        """Return global data for agent context"""
+        return {
+            "datasphere_enabled": True,
+            "document_id": self.document_id,
+            "knowledge_provider": "SignalWire DataSphere"
+        }
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return [
+            {
+                "title": "Knowledge Search Capability",
+                "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"
+                ]
+            }
+        ] 

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

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