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

signalwire_agents/skills/api_ninjas_trivia/skill.py

@@ -0,0 +1,192 @@
+"""
+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] 

signalwire_agents/skills/play_background_file/__init__.py

@@ -0,0 +1,3 @@
+from .skill import PlayBackgroundFileSkill
+
+__all__ = ['PlayBackgroundFileSkill'] 

signalwire_agents/skills/play_background_file/skill.py

@@ -0,0 +1,197 @@
+"""
+Play Background File Skill
+
+A configurable skill for managing background file playback with custom tool names
+and multiple file collections. Supports both audio and video files.
+"""
+
+from typing import Dict, Any, List
+from signalwire_agents.core import SwaigFunctionResult
+from signalwire_agents.core.skill_base import SkillBase
+
+
+class PlayBackgroundFileSkill(SkillBase):
+    """
+    Skill for playing background files (audio/video) with configurable tool names.
+    
+    Supports multiple instances with different tool names and file collections.
+    Uses DataMap for serverless execution with dynamic enum generation.
+    
+    Configuration:
+    - tool_name: Custom name for the generated SWAIG function
+    - files: Array of file objects with key, description, url, and optional wait
+    
+    Example:
+        agent.add_skill("play_background_file", {
+            "tool_name": "play_testimonial",
+            "files": [
+                {
+                    "key": "massey",
+                    "description": "Customer success story from Massey Energy",
+                    "url": "https://example.com/massey.mp4",
+                    "wait": True
+                }
+            ]
+        })
+    """
+    
+    SKILL_NAME = "play_background_file"
+    SKILL_DESCRIPTION = "Control background file playback"
+    SUPPORTS_MULTIPLE_INSTANCES = True
+    
+    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: "play_background_file")
+                - files: Array of file objects with key, description, url, wait
+        """
+        super().__init__(agent, params)
+        
+        # Extract configuration
+        self.tool_name = self.params.get('tool_name', 'play_background_file')
+        self.files = self.params.get('files', [])
+        
+        # Validate configuration
+        self._validate_config()
+    
+    def _validate_config(self):
+        """Validate the skill configuration."""
+        if not isinstance(self.files, list) or len(self.files) == 0:
+            raise ValueError("files parameter must be a non-empty list")
+        
+        for i, file_obj in enumerate(self.files):
+            if not isinstance(file_obj, dict):
+                raise ValueError(f"File {i} must be a dictionary")
+            
+            required_fields = ['key', 'description', 'url']
+            for field in required_fields:
+                if field not in file_obj:
+                    raise ValueError(f"File {i} missing required field: {field}")
+                if not isinstance(file_obj[field], str) or not file_obj[field].strip():
+                    raise ValueError(f"File {i} field '{field}' must be a non-empty string")
+            
+            # Validate optional wait field
+            if 'wait' in file_obj and not isinstance(file_obj['wait'], bool):
+                raise ValueError(f"File {i} field 'wait' must be a boolean")
+            
+            # Validate key format (alphanumeric, underscores, hyphens)
+            key = file_obj['key']
+            if not key.replace('_', '').replace('-', '').isalnum():
+                raise ValueError(f"File {i} key '{key}' must contain only alphanumeric characters, underscores, and hyphens")
+    
+    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 setup(self) -> bool:
+        """
+        Setup the skill - no external dependencies needed.
+        
+        Returns:
+            True if setup successful
+        """
+        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_tools(self) -> List[Dict[str, Any]]:
+        """
+        Generate the SWAIG tool with DataMap expressions.
+        
+        Returns:
+            List containing the generated tool configuration
+        """
+        # Build enum values and descriptions
+        enum_values = []
+        descriptions = []
+        
+        for file_obj in self.files:
+            enum_values.append(f"start_{file_obj['key']}")
+            descriptions.append(f"start_{file_obj['key']}: {file_obj['description']}")
+        
+        enum_values.append("stop")
+        descriptions.append("stop: Stop any currently playing background file")
+        
+        # Build parameter description
+        description = "Action to perform. Options: " + "; ".join(descriptions)
+        
+        # Create the tool configuration
+        tool = {
+            "function": self.tool_name,
+            "description": f"Control background file playback for {self.tool_name.replace('_', ' ')}",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "action": {
+                        "type": "string",
+                        "description": description,
+                        "enum": enum_values
+                    }
+                },
+                "required": ["action"]
+            },
+            "wait_for_fillers": True,
+            "skip_fillers": True,
+            "data_map": {
+                "expressions": self._build_expressions()
+            }
+        }
+        
+        return [tool]
+    
+    def _build_expressions(self) -> List[Dict[str, Any]]:
+        """
+        Build DataMap expressions for file playback and stop actions.
+        
+        Returns:
+            List of expression configurations
+        """
+        expressions = []
+        
+        # Add expressions for each file
+        for file_obj in self.files:
+            key = file_obj['key']
+            url = file_obj['url']
+            wait = file_obj.get('wait', False)
+            description = file_obj['description']
+            
+            # Create the result with appropriate response
+            result = SwaigFunctionResult(
+                f"Tell the user you are now going to play {description} for them.",
+                post_process=True
+            ).play_background_file(url, wait=wait)
+            
+            expressions.append({
+                "string": "${args.action}",
+                "pattern": f"/start_{key}/i",
+                "output": result.to_dict()
+            })
+        
+        # Add stop expression
+        stop_result = SwaigFunctionResult(
+            "Tell the user you have stopped the background file playback."
+        ).stop_background_file()
+        
+        expressions.append({
+            "string": "${args.action}",
+            "pattern": "/stop/i",
+            "output": stop_result.to_dict()
+        })
+        
+        return expressions 

signalwire_agents/skills/weather_api/__init__.py

@@ -0,0 +1,3 @@
+from .skill import WeatherApiSkill
+
+__all__ = ['WeatherApiSkill'] 

signalwire_agents/skills/weather_api/skill.py

@@ -0,0 +1,154 @@
+"""
+Weather API Skill
+
+A configurable skill for getting weather information from WeatherAPI.com with customizable
+temperature units and TTS-friendly responses.
+"""
+
+from typing import Dict, Any, List
+from signalwire_agents.core import SwaigFunctionResult
+from signalwire_agents.core.skill_base import SkillBase
+
+
+class WeatherApiSkill(SkillBase):
+    """
+    Skill for getting weather information from WeatherAPI.com.
+    
+    Provides current weather data with configurable temperature units and
+    TTS-optimized natural language responses.
+    
+    Configuration:
+    - tool_name: Custom name for the generated SWAIG function
+    - api_key: WeatherAPI.com API key
+    - temperature_unit: "fahrenheit" or "celsius" for temperature display
+    
+    Example:
+        agent.add_skill("weather_api", {
+            "tool_name": "get_weather",
+            "api_key": "your_weatherapi_key",
+            "temperature_unit": "fahrenheit"
+        })
+    """
+    
+    SKILL_NAME = "weather_api"
+    SKILL_DESCRIPTION = "Get current weather information from WeatherAPI.com"
+    SUPPORTS_MULTIPLE_INSTANCES = False
+    REQUIRED_ENV_VARS = []  # API key can be passed via params
+    
+    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_weather")
+                - api_key: WeatherAPI.com API key (required)
+                - temperature_unit: "fahrenheit" or "celsius" (default: "fahrenheit")
+        """
+        super().__init__(agent, params)
+        
+        # Extract configuration
+        self.tool_name = self.params.get('tool_name', 'get_weather')
+        self.api_key = self.params.get('api_key')
+        self.temperature_unit = self.params.get('temperature_unit', 'fahrenheit')
+        
+        # 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 temperature unit
+        if self.temperature_unit not in ['fahrenheit', 'celsius']:
+            raise ValueError("temperature_unit must be either 'fahrenheit' or 'celsius'")
+    
+    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_tools(self) -> List[Dict[str, Any]]:
+        """
+        Generate the SWAIG tool with DataMap webhook.
+        
+        Returns:
+            List containing the generated tool configuration
+        """
+        # Determine temperature fields based on unit
+        if self.temperature_unit == 'fahrenheit':
+            temp_field = 'temp_f'
+            feels_like_field = 'feelslike_f'
+            unit_name = 'Fahrenheit'
+        else:
+            temp_field = 'temp_c'
+            feels_like_field = 'feelslike_c'
+            unit_name = 'Celsius'
+        
+        # Create TTS-friendly response instruction
+        response_instruction = (
+            f"Tell the user the current weather conditions. "
+            f"Express all temperatures in {unit_name} using natural language numbers "
+            f"without abbreviations or symbols for clear text-to-speech pronunciation. "
+            f"For example, say 'seventy two degrees {unit_name}' instead of '72F' or '72°F'. "
+            f"Include the condition, current temperature, wind direction and speed, "
+            f"cloud coverage percentage, and what the temperature feels like."
+        )
+        
+        # Build the weather data template
+        weather_template = (
+            f"{response_instruction} "
+            f"Current conditions: ${{current.condition.text}}. "
+            f"Temperature: ${{current.{temp_field}}} degrees {unit_name}. "
+            f"Wind: ${{current.wind_dir}} at ${{current.wind_mph}} miles per hour. "
+            f"Cloud coverage: ${{current.cloud}} percent. "
+            f"Feels like: ${{current.{feels_like_field}}} degrees {unit_name}."
+        )
+        
+        # Create the tool configuration with DataMap webhook
+        tool = {
+            "function": self.tool_name,
+            "description": f"Get current weather information for any location",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "location": {
+                        "type": "string",
+                        "description": "The city, state, country, or location to get weather for"
+                    }
+                },
+                "required": ["location"]
+            },
+            "data_map": {
+                "webhooks": [
+                    {
+                        "url": f"https://api.weatherapi.com/v1/current.json?key={self.api_key}&q=%{{args.location}}&aqi=no",
+                        "method": "GET",
+                        "output": SwaigFunctionResult(weather_template).to_dict()
+                    }
+                ],
+                "error_keys": ["error"],
+                "output": SwaigFunctionResult(
+                    "Sorry, I cannot get weather information right now. Please try again later or check if the location name is correct."
+                ).to_dict()
+            }
+        }
+        
+        return [tool] 

{signalwire_agents-0.1.20.dist-info → signalwire_agents-0.1.23.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.20
+Version: 0.1.23
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
-Project-URL: Homepage, https://github.com/signalwire/signalwire-ai-agents
-Classifier: Development Status :: 3 - Alpha
+Project-URL: Homepage, https://github.com/signalwire/signalwire-agents
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -176,7 +176,7 @@ agent.serve()
 - **Dependency validation**: Clear error messages for missing requirements
 - **Modular architecture**: Skills are self-contained and reusable
 
-For detailed documentation, see [Skills System README](docs/SKILLS_SYSTEM_README.md).
+For detailed documentation, see [Skills System README](docs/skills_system.md).
 
 ## DataMap Tools
 
@@ -572,10 +572,7 @@ class SimpleAgent(AgentBase):
         self.prompt_add_section("Goal", body="Help users with basic questions.")
         self.prompt_add_section("Instructions", bullets=["Be concise and clear."])
         
-        # Alternative using convenience methods:
-        # self.setPersonality("You are a helpful assistant.")
-        # self.setGoal("Help users with basic questions.")
-        # self.setInstructions(["Be concise and clear."])
+        # Note: Use prompt_add_section() for all prompt configuration
     
     @AgentBase.tool(
         name="get_time",