signalwire-agents 0.1.10__py3-none-any.whl → 0.1.12__py3-none-any.whl

signalwire_agents/skills/datasphere/skill.py

@@ -0,0 +1,229 @@
+"""
+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
+    
+    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.agent.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,
+            **self.swaig_fields
+        )
+        
+    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/__init__.py

@@ -0,0 +1 @@
+"""DataSphere Serverless Skill for SignalWire Agents using DataMap""" 

signalwire_agents/skills/datasphere_serverless/skill.py

@@ -0,0 +1,156 @@
+"""
+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
+    
+    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
+            "distance": self.distance,
+            "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/skill.py

@@ -30,7 +30,7 @@ class DateTimeSkill(SkillBase):
     def register_tools(self) -> None:
         """Register datetime tools with the agent"""
         
-        self.define_tool_with_swaig_fields(
+        self.agent.define_tool(
             name="get_current_time",
             description="Get the current time, optionally in a specific timezone",
             parameters={
@@ -39,10 +39,11 @@ class DateTimeSkill(SkillBase):
                     "description": "Timezone name (e.g., 'America/New_York', 'Europe/London'). Defaults to UTC."
                 }
             },
-            handler=self._get_time_handler
+            handler=self._get_time_handler,
+            **self.swaig_fields
         )
         
-        self.define_tool_with_swaig_fields(
+        self.agent.define_tool(
             name="get_current_date",
             description="Get the current date",
             parameters={
@@ -51,7 +52,8 @@ class DateTimeSkill(SkillBase):
                     "description": "Timezone name for the date. Defaults to UTC."
                 }
             },
-            handler=self._get_date_handler
+            handler=self._get_date_handler,
+            **self.swaig_fields
         )
         
     def _get_time_handler(self, args, raw_data):
@@ -92,7 +94,9 @@ class DateTimeSkill(SkillBase):
         
     def get_hints(self) -> List[str]:
         """Return speech recognition hints"""
-        return ["time", "date", "today", "now", "current", "timezone"]
+        # 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"""

signalwire_agents/skills/joke/__init__.py

@@ -0,0 +1 @@
+"""Joke Skill for SignalWire Agents using DataMap""" 

signalwire_agents/skills/joke/skill.py

@@ -0,0 +1,88 @@
+"""
+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 typing import 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 JokeSkill(SkillBase):
+    """Joke telling capability using API Ninjas with DataMap"""
+    
+    SKILL_NAME = "joke"
+    SKILL_DESCRIPTION = "Tell jokes using the API Ninjas joke API"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = []  # DataMap doesn't require local packages
+    REQUIRED_ENV_VARS = []  # API key comes from parameters
+    
+    def setup(self) -> bool:
+        """Setup the joke skill"""
+        # Validate required parameters
+        required_params = ['api_key']
+        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 parameters from config
+        self.api_key = self.params['api_key']
+        
+        # Optional parameters with defaults
+        self.tool_name = self.params.get('tool_name', 'get_joke')
+        
+        return True
+        
+    def register_tools(self) -> None:
+        """Register joke tool using DataMap"""
+        
+        # Create DataMap tool for jokes - uses required enum parameter
+        joke_tool = (DataMap(self.tool_name)
+            .description('Get a random joke from API Ninjas')
+            .parameter('type', 'string', 'Type of joke to get', 
+                      required=True, enum=['jokes', 'dadjokes'])
+            .webhook('GET', "https://api.api-ninjas.com/v1/${args.type}", 
+                     headers={'X-Api-Key': self.api_key})
+            .output(SwaigFunctionResult('Here\'s a joke: ${array[0].joke}'))
+            .error_keys(['error'])
+            .fallback_output(SwaigFunctionResult('Sorry, there is a problem with the joke service right now. Please try again later.'))
+        )
+        
+        # Register the DataMap tool with the agent
+        self.agent.register_swaig_function(joke_tool.to_swaig_function())
+        
+    def get_hints(self) -> List[str]:
+        """Return speech recognition hints"""
+        # Currently no hints are provided, but you could add them like:
+        # return [
+        #     "joke", "tell me a joke", "funny", "humor", "dad joke", 
+        #     "regular joke", "make me laugh", "comedy"
+        # ]
+        return []
+        
+    def get_global_data(self) -> Dict[str, Any]:
+        """Return global data to be available in DataMap variables"""
+        return {
+            "joke_skill_enabled": True
+        }
+        
+    def get_prompt_sections(self) -> List[Dict[str, Any]]:
+        """Return prompt sections to add to agent"""
+        return [
+            {
+                "title": "Joke Telling", 
+                "body": "You can tell jokes to entertain users.",
+                "bullets": [
+                    f"Use {self.tool_name} to tell jokes when users ask for humor",
+                    "You can tell regular jokes or dad jokes",
+                    "Be enthusiastic and fun when sharing jokes"
+                ]
+            }
+        ] 

signalwire_agents/skills/math/skill.py

@@ -29,7 +29,7 @@ class MathSkill(SkillBase):
     def register_tools(self) -> None:
         """Register math tools with the agent"""
         
-        self.define_tool_with_swaig_fields(
+        self.agent.define_tool(
             name="calculate",
             description="Perform a mathematical calculation with basic operations (+, -, *, /, %, **)",
             parameters={
@@ -38,7 +38,8 @@ class MathSkill(SkillBase):
                     "description": "Mathematical expression to evaluate (e.g., '2 + 3 * 4', '(10 + 5) / 3')"
                 }
             },
-            handler=self._calculate_handler
+            handler=self._calculate_handler,
+            **self.swaig_fields
         )
         
     def _calculate_handler(self, args, raw_data):
@@ -68,10 +69,12 @@ class MathSkill(SkillBase):
         
     def get_hints(self) -> List[str]:
         """Return speech recognition hints"""
-        return [
-            "calculate", "math", "plus", "minus", "times", "multiply", 
-            "divide", "equals", "percent", "power", "squared"
-        ]
+        # Currently no hints provided, but you could add them like:
+        # return [
+        #     "calculate", "math", "plus", "minus", "times", "multiply", 
+        #     "divide", "equals", "percent", "power", "squared"
+        # ]
+        return []
         
     def get_prompt_sections(self) -> List[Dict[str, Any]]:
         """Return prompt sections to add to agent"""

signalwire_agents/skills/native_vector_search/__init__.py

@@ -0,0 +1 @@
+# Native Vector Search Skill