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

signalwire_agents/skills/api_ninjas_trivia/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.
+"""
+
+"""
+API Ninjas Trivia Skill
+
+A configurable skill for getting trivia questions from API Ninjas with customizable
+categories and multiple tool instances.
+"""
+
+from typing import Dict, Any, List
+from signalwire_agents.core import SwaigFunctionResult
+from signalwire_agents.core.skill_base import SkillBase
+
+
+class ApiNinjasTriviaSkill(SkillBase):
+    """
+    Skill for getting trivia questions from API Ninjas with configurable categories.
+    
+    Supports multiple instances with different tool names and category combinations.
+    Uses DataMap for serverless execution with dynamic enum generation.
+    
+    Configuration:
+    - tool_name: Custom name for the generated SWAIG function
+    - api_key: API Ninjas API key
+    - categories: Array of category strings to enable
+    
+    Available categories:
+    - artliterature: Art and Literature
+    - language: Language  
+    - sciencenature: Science and Nature
+    - general: General Knowledge
+    - fooddrink: Food and Drink
+    - peopleplaces: People and Places
+    - geography: Geography
+    - historyholidays: History and Holidays
+    - entertainment: Entertainment
+    - toysgames: Toys and Games
+    - music: Music
+    - mathematics: Mathematics
+    - religionmythology: Religion and Mythology
+    - sportsleisure: Sports and Leisure
+    
+    Example:
+        agent.add_skill("api_ninjas_trivia", {
+            "tool_name": "get_science_trivia",
+            "api_key": "your_api_key",
+            "categories": ["sciencenature", "mathematics", "general"]
+        })
+    """
+    
+    SKILL_NAME = "api_ninjas_trivia"
+    SKILL_DESCRIPTION = "Get trivia questions from API Ninjas"
+    SUPPORTS_MULTIPLE_INSTANCES = True
+    REQUIRED_ENV_VARS = []  # API key can be passed via params
+    
+    # Valid API Ninjas trivia categories with human-readable descriptions
+    VALID_CATEGORIES = {
+        "artliterature": "Art and Literature",
+        "language": "Language",
+        "sciencenature": "Science and Nature", 
+        "general": "General Knowledge",
+        "fooddrink": "Food and Drink",
+        "peopleplaces": "People and Places",
+        "geography": "Geography",
+        "historyholidays": "History and Holidays",
+        "entertainment": "Entertainment",
+        "toysgames": "Toys and Games",
+        "music": "Music",
+        "mathematics": "Mathematics",
+        "religionmythology": "Religion and Mythology",
+        "sportsleisure": "Sports and Leisure"
+    }
+    
+    def __init__(self, agent, params: Dict[str, Any] = None):
+        """
+        Initialize the skill with configuration parameters.
+        
+        Args:
+            agent: The agent instance this skill belongs to
+            params: Configuration dictionary containing:
+                - tool_name: Custom tool name (default: "get_trivia")
+                - api_key: API Ninjas API key (required)
+                - categories: Array of category strings (default: all categories)
+        """
+        super().__init__(agent, params)
+        
+        # Extract configuration
+        self.tool_name = self.params.get('tool_name', 'get_trivia')
+        self.api_key = self.params.get('api_key')
+        self.categories = self.params.get('categories', list(self.VALID_CATEGORIES.keys()))
+        
+        # Validate configuration
+        self._validate_config()
+    
+    def _validate_config(self):
+        """Validate the skill configuration."""
+        # Validate API key
+        if not self.api_key or not isinstance(self.api_key, str):
+            raise ValueError("api_key parameter is required and must be a non-empty string")
+        
+        # Validate categories
+        if not isinstance(self.categories, list) or len(self.categories) == 0:
+            raise ValueError("categories parameter must be a non-empty list")
+        
+        # Validate each category
+        for i, category in enumerate(self.categories):
+            if not isinstance(category, str):
+                raise ValueError(f"Category {i} must be a string")
+            if category not in self.VALID_CATEGORIES:
+                valid_cats = ', '.join(self.VALID_CATEGORIES.keys())
+                raise ValueError(f"Category '{category}' is not valid. Valid categories: {valid_cats}")
+    
+    def setup(self) -> bool:
+        """
+        Setup the skill - validates API key is available.
+        
+        Returns:
+            True if setup successful
+        """
+        # API key validation already done in _validate_config
+        return True
+    
+    def register_tools(self) -> None:
+        """Register SWAIG tools with the agent"""
+        tools = self.get_tools()
+        for tool in tools:
+            # Merge any swaig_fields from params into the tool
+            if self.swaig_fields:
+                tool.update(self.swaig_fields)
+            self.agent.register_swaig_function(tool)
+    
+    def get_instance_key(self) -> str:
+        """
+        Generate a unique instance key for this skill configuration.
+        
+        Returns:
+            Unique key combining skill name and tool name
+        """
+        return f"{self.SKILL_NAME}_{self.tool_name}"
+    
+    def get_tools(self) -> List[Dict[str, Any]]:
+        """
+        Generate the SWAIG tool with DataMap webhook.
+        
+        Returns:
+            List containing the generated tool configuration
+        """
+        # Build enum values and descriptions
+        enum_values = []
+        descriptions = []
+        
+        for category in self.categories:
+            enum_values.append(category)
+            descriptions.append(f"{category}: {self.VALID_CATEGORIES[category]}")
+        
+        # Build parameter description
+        description = "Category for trivia question. Options: " + "; ".join(descriptions)
+        
+        # Create the tool configuration with DataMap webhook
+        tool = {
+            "function": self.tool_name,
+            "description": f"Get trivia questions for {self.tool_name.replace('_', ' ')}",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "category": {
+                        "type": "string",
+                        "description": description,
+                        "enum": enum_values
+                    }
+                },
+                "required": ["category"]
+            },
+            "data_map": {
+                "webhooks": [
+                    {
+                        "url": "https://api.api-ninjas.com/v1/trivia?category=%{args.category}",
+                        "method": "GET",
+                        "headers": {
+                            "X-Api-Key": self.api_key
+                        },
+                        "output": SwaigFunctionResult(
+                            "Category %{array[0].category} question: %{array[0].question} Answer: %{array[0].answer}, be sure to give the user time to answer before saying the answer."
+                        ).to_dict()
+                    }
+                ],
+                "error_keys": ["error"],
+                "output": SwaigFunctionResult(
+                    "Sorry, I cannot get trivia questions right now. Please try again later."
+                ).to_dict()
+            }
+        }
+        
+        return [tool]
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """
+        Get the parameter schema for the API Ninjas Trivia skill.
+        
+        Returns parameter definitions for GUI configuration.
+        """
+        schema = super().get_parameter_schema()
+        
+        # Build categories enum description
+        category_options = []
+        for key, desc in cls.VALID_CATEGORIES.items():
+            category_options.append(f"{key} ({desc})")
+        
+        schema.update({
+            "api_key": {
+                "type": "string",
+                "description": "API Ninjas API key",
+                "required": True,
+                "hidden": True,
+                "env_var": "API_NINJAS_KEY"
+            },
+            "categories": {
+                "type": "array",
+                "description": "List of trivia categories to enable. Available: " + ", ".join(category_options),
+                "default": list(cls.VALID_CATEGORIES.keys()),
+                "required": False,
+                "items": {
+                    "type": "string",
+                    "enum": list(cls.VALID_CATEGORIES.keys())
+                }
+            }
+        })
+        
+        return schema 

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

@@ -26,6 +26,88 @@ class DataSphereSkill(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 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
@@ -77,7 +159,7 @@ class DataSphereSkill(SkillBase):
         
     def register_tools(self) -> None:
         """Register knowledge search tool with the agent"""
-        self.agent.define_tool(
+        self.define_tool(
             name=self.tool_name,
             description="Search the knowledge base for information on any topic and return relevant results",
             parameters={
@@ -86,8 +168,7 @@ class DataSphereSkill(SkillBase):
                     "description": "The search query - what information you're looking for in the knowledge base"
                 }
             },
-            handler=self._search_knowledge_handler,
-            **self.swaig_fields
+            handler=self._search_knowledge_handler
         )
         
     def _search_knowledge_handler(self, args, raw_data):