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

signalwire_agents/skills/play_background_file/README.md

@@ -0,0 +1,218 @@
+# 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 with serverless DataMap execution.
+
+## Features
+
+- **Multiple Instances**: Create different tools with unique names and file sets
+- **Dynamic Enum Generation**: Function parameters built from your file configuration
+- **Audio & Video Support**: Works with any background file type
+- **DataMap Efficiency**: Serverless execution, no agent processing load
+- **Post-Processing**: AI speaks first, then executes the action
+- **Configurable Wait**: Control attention-getting behavior per file
+
+## Configuration
+
+### Basic Structure
+
+```python
+agent.add_skill("play_background_file", {
+    "tool_name": "your_custom_tool_name",
+    "files": [
+        {
+            "key": "unique_identifier",
+            "description": "Human readable description",
+            "url": "https://example.com/file.mp4",
+            "wait": True  # Optional, defaults to False
+        }
+    ]
+})
+```
+
+### Parameters
+
+- **tool_name** (string): Custom name for the generated SWAIG function (default: "play_background_file")
+- **files** (array): List of file objects to manage
+
+### File Object Properties
+
+- **key** (string, required): Unique identifier for the file (alphanumeric, underscores, hyphens only)
+- **description** (string, required): Human-readable description used in AI responses
+- **url** (string, required): URL to the audio/video file
+- **wait** (boolean, optional): Whether to suppress attention-getting behavior during playback (default: false)
+
+## Usage Examples
+
+### Single File Testimonial
+
+```python
+agent.add_skill("play_background_file", {
+    "tool_name": "play_testimonial",
+    "files": [
+        {
+            "key": "massey_success",
+            "description": "Customer success story from Massey Energy",
+            "url": "https://tatooine.cantina.cloud/vids/massey.mp4",
+            "wait": True
+        }
+    ]
+})
+```
+
+**Generated Tool**: `play_testimonial(action)`
+**Actions**: `["start_massey_success", "stop"]`
+
+### Multiple Demo Videos
+
+```python
+agent.add_skill("play_background_file", {
+    "tool_name": "play_demo",
+    "files": [
+        {
+            "key": "product_overview",
+            "description": "Product overview demonstration",
+            "url": "https://example.com/overview.mp4",
+            "wait": False
+        },
+        {
+            "key": "advanced_features",
+            "description": "Advanced features walkthrough", 
+            "url": "https://example.com/advanced.mp4",
+            "wait": True
+        }
+    ]
+})
+```
+
+**Generated Tool**: `play_demo(action)`
+**Actions**: `["start_product_overview", "start_advanced_features", "stop"]`
+
+### Music Playlist
+
+```python
+agent.add_skill("play_background_file", {
+    "tool_name": "play_music",
+    "files": [
+        {
+            "key": "jazz",
+            "description": "smooth jazz background music",
+            "url": "https://example.com/jazz.mp3"
+        },
+        {
+            "key": "classical",
+            "description": "classical piano background music",
+            "url": "https://example.com/classical.mp3"
+        }
+    ]
+})
+```
+
+## Generated SWAIG Function
+
+For the testimonial example above, the skill generates:
+
+```json
+{
+    "function": "play_testimonial",
+    "description": "Control background file playback for play testimonial",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "description": "Action to perform. Options: start_massey_success: Customer success story from Massey Energy; stop: Stop any currently playing background file",
+                "enum": ["start_massey_success", "stop"]
+            }
+        },
+        "required": ["action"]
+    },
+    "data_map": {
+        "expressions": [
+            {
+                "string": "${args.action}",
+                "pattern": "/start_massey_success/i",
+                "output": {
+                    "response": "Tell the user you are now going to play Customer success story from Massey Energy for them.",
+                    "action": [
+                        {
+                            "playback_bg": {
+                                "file": "https://tatooine.cantina.cloud/vids/massey.mp4",
+                                "wait": true
+                            }
+                        }
+                    ],
+                    "post_process": true
+                }
+            },
+            {
+                "string": "${args.action}",
+                "pattern": "/stop/i",
+                "output": {
+                    "response": "Tell the user you have stopped the background file playback.",
+                    "action": [
+                        {
+                            "stop_playback_bg": true
+                        }
+                    ],
+                    "post_process": true
+                }
+            }
+        ]
+    }
+}
+```
+
+## Execution Flow
+
+1. **AI calls function**: `play_testimonial(action: "start_massey_success")`
+2. **DataMap matches pattern**: `/start_massey_success/i`
+3. **AI receives instruction**: "Tell the user you are now going to play Customer success story from Massey Energy for them."
+4. **AI responds naturally**: The AI interprets this and responds in its own voice
+5. **Action executes**: Background video starts playing
+6. **User experience**: Natural AI announcement before action
+
+## Multiple Instances
+
+You can add multiple instances of this skill with different tool names:
+
+```python
+# Testimonials
+agent.add_skill("play_background_file", {
+    "tool_name": "play_testimonial",
+    "files": [{"key": "massey", "description": "Massey Energy success story", "url": "..."}]
+})
+
+# Demos  
+agent.add_skill("play_background_file", {
+    "tool_name": "play_demo",
+    "files": [
+        {"key": "overview", "description": "Product overview", "url": "..."},
+        {"key": "features", "description": "Advanced features", "url": "..."}
+    ]
+})
+
+# Music
+agent.add_skill("play_background_file", {
+    "tool_name": "play_music", 
+    "files": [{"key": "jazz", "description": "Jazz music", "url": "..."}]
+})
+```
+
+This creates three separate tools: `play_testimonial`, `play_demo`, and `play_music`.
+
+## Benefits
+
+- **Reusable**: Same skill manages different file collections
+- **Configurable**: Easy to add/remove files without code changes  
+- **Efficient**: DataMap serverless execution
+- **Type Safe**: Enum parameters prevent invalid file references
+- **Natural**: AI speaks before actions with post-processing
+- **Maintainable**: Centralized file management logic
+
+## Implementation Notes
+
+- File keys are converted to `start_{key}` enum values
+- All tools include a "stop" action to halt playback
+- Post-processing is enabled by default for natural conversation flow
+- The skill validates all configuration parameters at initialization
+- Instance keys combine skill name and tool name for uniqueness 

signalwire_agents/skills/play_background_file/__init__.py

@@ -0,0 +1,12 @@
+"""
+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 .skill import PlayBackgroundFileSkill
+
+__all__ = ['PlayBackgroundFileSkill'] 

signalwire_agents/skills/play_background_file/skill.py

@@ -0,0 +1,242 @@
+"""
+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.
+"""
+
+"""
+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
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """Get parameter schema for Play Background File skill"""
+        schema = super().get_parameter_schema()
+        schema.update({
+            "files": {
+                "type": "array",
+                "description": "Array of file configurations to make available for playback",
+                "required": True,
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "key": {
+                            "type": "string",
+                            "description": "Unique identifier for the file"
+                        },
+                        "description": {
+                            "type": "string",
+                            "description": "Human-readable description of the file"
+                        },
+                        "url": {
+                            "type": "string",
+                            "description": "URL of the audio/video file to play"
+                        },
+                        "wait": {
+                            "type": "boolean",
+                            "description": "Whether to wait for file to finish playing",
+                            "default": False
+                        }
+                    },
+                    "required": ["key", "description", "url"]
+                }
+            }
+        })
+        return schema
+    
+    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