signalwire-agents 0.1.1__py3-none-any.whl → 0.1.5__py3-none-any.whl

signalwire_agents/prefabs/__init__.py

@@ -0,0 +1,26 @@
+"""
+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.
+"""
+
+"""
+Prefab agents with specific functionality that can be used out-of-the-box
+"""
+
+from signalwire_agents.prefabs.info_gatherer import InfoGathererAgent
+from signalwire_agents.prefabs.faq_bot import FAQBotAgent
+from signalwire_agents.prefabs.concierge import ConciergeAgent
+from signalwire_agents.prefabs.survey import SurveyAgent
+from signalwire_agents.prefabs.receptionist import ReceptionistAgent
+
+__all__ = [
+    "InfoGathererAgent",
+    "FAQBotAgent",
+    "ConciergeAgent",
+    "SurveyAgent",
+    "ReceptionistAgent"
+]

signalwire_agents/prefabs/concierge.py

@@ -0,0 +1,267 @@
+"""
+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.
+"""
+
+"""
+ConciergeAgent - Prefab agent for providing virtual concierge services
+"""
+
+from typing import List, Dict, Any, Optional, Union
+import json
+import os
+from datetime import datetime
+
+from signalwire_agents.core.agent_base import AgentBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+
+class ConciergeAgent(AgentBase):
+    """
+    A prefab agent designed to act as a virtual concierge, providing information
+    and services to users.
+    
+    This agent will:
+    1. Welcome users and explain available services
+    2. Answer questions about amenities, hours, and directions
+    3. Help with bookings and reservations
+    4. Provide personalized recommendations
+    
+    Example:
+        agent = ConciergeAgent(
+            venue_name="Grand Hotel",
+            services=["room service", "spa bookings", "restaurant reservations"],
+            amenities={
+                "pool": {"hours": "7 AM - 10 PM", "location": "2nd Floor"},
+                "gym": {"hours": "24 hours", "location": "3rd Floor"}
+            }
+        )
+    """
+    
+    def __init__(
+        self,
+        venue_name: str,
+        services: List[str],
+        amenities: Dict[str, Dict[str, str]],
+        hours_of_operation: Optional[Dict[str, str]] = None,
+        special_instructions: Optional[List[str]] = None,
+        welcome_message: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Initialize a concierge agent
+        
+        Args:
+            venue_name: Name of the venue or business
+            services: List of services offered
+            amenities: Dictionary of amenities with details
+            hours_of_operation: Optional dictionary of operating hours
+            special_instructions: Optional list of special instructions
+            welcome_message: Optional custom welcome message
+            **kwargs: Additional arguments for AgentBase
+        """
+        # Initialize the base agent
+        super().__init__(
+            name="concierge",
+            route="/concierge",
+            use_pom=True,
+            **kwargs
+        )
+        
+        # Store configuration
+        self.venue_name = venue_name
+        self.services = services
+        self.amenities = amenities
+        self.hours_of_operation = hours_of_operation or {"default": "9 AM - 5 PM"}
+        self.special_instructions = special_instructions or []
+        
+        # Set up the agent's configuration
+        self._setup_concierge_agent(welcome_message)
+        
+    def _setup_concierge_agent(self, welcome_message: Optional[str] = None):
+        """Configure the concierge agent with appropriate settings"""
+        # Basic personality and instructions
+        self.prompt_add_section("Personality", 
+            body=f"You are a professional and helpful virtual concierge for {self.venue_name}."
+        )
+        
+        self.prompt_add_section("Goal", 
+            body="Provide exceptional service by helping users with information, recommendations, and booking assistance."
+        )
+        
+        # Build detailed instructions
+        instructions = [
+            "Be warm and welcoming but professional at all times.",
+            "Provide accurate information about amenities, services, and operating hours.",
+            "Offer to help with reservations and bookings when appropriate.",
+            "Answer questions concisely with specific, relevant details."
+        ]
+        
+        # Add any special instructions
+        instructions.extend(self.special_instructions)
+        
+        self.prompt_add_section("Instructions", bullets=instructions)
+        
+        # Services section
+        services_list = ", ".join(self.services)
+        self.prompt_add_section("Available Services", 
+            body=f"The following services are available: {services_list}"
+        )
+        
+        # Amenities section with details
+        amenities_subsections = []
+        for name, details in self.amenities.items():
+            subsection = {
+                "title": name.title(),
+                "body": "\n".join([f"{k.title()}: {v}" for k, v in details.items()])
+            }
+            amenities_subsections.append(subsection)
+            
+        self.prompt_add_section("Amenities", 
+            body="Information about available amenities:",
+            subsections=amenities_subsections
+        )
+        
+        # Hours of operation
+        hours_list = "\n".join([f"{k.title()}: {v}" for k, v in self.hours_of_operation.items()])
+        self.prompt_add_section("Hours of Operation", body=hours_list)
+        
+        # Set up the post-prompt for summary
+        self.set_post_prompt("""
+        Return a JSON summary of this interaction:
+        {
+            "topic": "MAIN_TOPIC",
+            "service_requested": "SPECIFIC_SERVICE_REQUESTED_OR_null",
+            "questions_answered": ["QUESTION_1", "QUESTION_2"],
+            "follow_up_needed": true/false
+        }
+        """)
+        
+        # Configure hints for better understanding
+        self.add_hints([
+            self.venue_name,
+            *self.services,
+            *self.amenities.keys()
+        ])
+        
+        # Set up parameters
+        self.set_params({
+            "wait_for_user": False,
+            "end_of_speech_timeout": 1000,
+            "ai_volume": 5,
+            "local_tz": "America/New_York"
+        })
+        
+        # Add global data
+        self.set_global_data({
+            "venue_name": self.venue_name,
+            "services": self.services,
+            "amenities": self.amenities,
+            "hours": self.hours_of_operation
+        })
+        
+        # Configure native functions
+        self.set_native_functions(["check_time"])
+        
+        # Set custom welcome message if provided
+        if welcome_message:
+            self.set_params({
+                "static_greeting": welcome_message,
+                "static_greeting_no_barge": True
+            })
+        
+        # Register tool methods
+        # These methods are already decorated with @AgentBase.tool in the class definition
+        
+    @AgentBase.tool(
+        name="check_availability",
+        description="Check availability for a service on a specific date and time",
+        parameters={
+            "service": {
+                "type": "string",
+                "description": "The service to check (e.g., spa, restaurant)"
+            },
+            "date": {
+                "type": "string",
+                "description": "The date to check (YYYY-MM-DD format)"
+            },
+            "time": {
+                "type": "string",
+                "description": "The time to check (HH:MM format, 24-hour)"
+            }
+        }
+    )
+    def check_availability(self, args, raw_data):
+        """
+        Check availability for a service on a specific date and time
+        
+        This is a simulated function that would typically connect to a real booking system.
+        In this example, it returns a mock availability response.
+        """
+        service = args.get("service", "").lower()
+        date = args.get("date", "")
+        time = args.get("time", "")
+        
+        # Simple availability simulation - in a real application, this would
+        # connect to your actual booking system
+        if service in self.services:
+            # Generate a simple availability response
+            return SwaigFunctionResult(
+                f"Yes, {service} is available on {date} at {time}. Would you like to make a reservation?"
+            )
+        else:
+            return SwaigFunctionResult(
+                f"I'm sorry, we don't offer {service} at {self.venue_name}. "
+                f"Our available services are: {', '.join(self.services)}."
+            )
+    
+    @AgentBase.tool(
+        name="get_directions",
+        description="Get directions to a specific location or amenity",
+        parameters={
+            "location": {
+                "type": "string",
+                "description": "The location or amenity to get directions to"
+            }
+        }
+    )
+    def get_directions(self, args, raw_data):
+        """Provide directions to a specific location or amenity"""
+        location = args.get("location", "").lower()
+        
+        # Check if the location is an amenity
+        if location in self.amenities and "location" in self.amenities[location]:
+            amenity_location = self.amenities[location]["location"]
+            return SwaigFunctionResult(
+                f"The {location} is located at {amenity_location}. "
+                f"From the main entrance, follow the signs to {amenity_location}."
+            )
+        else:
+            return SwaigFunctionResult(
+                f"I don't have specific directions to {location}. "
+                f"You can ask our staff at the front desk for assistance."
+            )
+    
+    def on_summary(self, summary, raw_data=None):
+        """
+        Process the interaction summary
+        
+        Args:
+            summary: Summary data from the conversation
+            raw_data: The complete raw POST data from the request
+        """
+        if summary:
+            try:
+                # For structured summary
+                if isinstance(summary, dict):
+                    print(f"Concierge interaction summary: {json.dumps(summary, indent=2)}")
+                else:
+                    print(f"Concierge interaction summary: {summary}")
+                    
+                # Subclasses can override this to log or process the interaction
+            except Exception as e:
+                print(f"Error processing summary: {str(e)}")

signalwire_agents/prefabs/faq_bot.py

@@ -0,0 +1,305 @@
+"""
+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.
+"""
+
+"""
+FAQBotAgent - Prefab agent for answering frequently asked questions
+"""
+
+from typing import List, Dict, Any, Optional, Union
+import json
+import os
+
+from signalwire_agents.core.agent_base import AgentBase
+from signalwire_agents.core.function_result import SwaigFunctionResult
+
+
+class FAQBotAgent(AgentBase):
+    """
+    A prefab agent designed to answer frequently asked questions based on
+    a provided list of question/answer pairs.
+    
+    This agent will:
+    1. Match user questions against the FAQ database
+    2. Provide the most relevant answer
+    3. Suggest other relevant questions when appropriate
+    
+    Example:
+        agent = FAQBotAgent(
+            faqs=[
+                {
+                    "question": "What is SignalWire?",
+                    "answer": "SignalWire is a developer-friendly cloud communications platform."
+                },
+                {
+                    "question": "How much does it cost?",
+                    "answer": "SignalWire offers pay-as-you-go pricing with no monthly fees."
+                }
+            ]
+        )
+    """
+    
+    def __init__(
+        self,
+        faqs: List[Dict[str, str]],
+        suggest_related: bool = True,
+        persona: Optional[str] = None,
+        name: str = "faq_bot",
+        route: str = "/faq",
+        **kwargs
+    ):
+        """
+        Initialize an FAQ bot agent
+        
+        Args:
+            faqs: List of FAQ items, each with:
+                - question: The question text
+                - answer: The answer text
+                - categories: Optional list of category tags
+            suggest_related: Whether to suggest related questions
+            persona: Optional custom personality description
+            name: Agent name for the route
+            route: HTTP route for this agent
+            **kwargs: Additional arguments for AgentBase
+        """
+        # Initialize the base agent
+        super().__init__(
+            name=name,
+            route=route,
+            use_pom=True,
+            **kwargs
+        )
+        
+        self.faqs = faqs
+        self.suggest_related = suggest_related
+        self.persona = persona or "You are a helpful FAQ bot that provides accurate answers to common questions."
+        
+        # Build the prompt
+        self._build_faq_bot_prompt()
+        
+        # Set up the post-prompt template
+        self._setup_post_prompt()
+        
+        # Configure additional agent settings
+        self._configure_agent_settings()
+    
+    def _build_faq_bot_prompt(self):
+        """Build the agent prompt for the FAQ bot"""
+        # Set up the personality
+        self.prompt_add_section(
+            "Personality", 
+            body=self.persona
+        )
+        
+        # Set up the goal
+        self.prompt_add_section(
+            "Goal", 
+            body="Answer user questions by matching them to the most similar FAQ in your database."
+        )
+        
+        # Set up the instructions
+        instructions = [
+            "Compare user questions to your FAQ database and find the best match.",
+            "Provide the answer from the FAQ database for the matching question.",
+            "If no close match exists, politely say you don't have that information.",
+            "Be concise and factual in your responses."
+        ]
+        
+        # Add instruction about suggesting related questions if enabled
+        if self.suggest_related:
+            instructions.append(
+                "When appropriate, suggest other related questions from the FAQ database that might be helpful."
+            )
+            
+        self.prompt_add_section(
+            "Instructions",
+            bullets=instructions
+        )
+        
+        # Add FAQ Database section with subsections for each FAQ
+        faq_subsections = []
+        for faq in self.faqs:
+            question = faq.get("question", "")
+            answer = faq.get("answer", "")
+            categories = faq.get("categories", [])
+            
+            # Skip invalid entries
+            if not question or not answer:
+                continue
+                
+            # Build the body text with answer and optional categories
+            body_text = answer
+            if categories:
+                category_str = "Categories: " + ", ".join(categories)
+                body_text = f"{body_text}\n\n{category_str}"
+                
+            faq_subsections.append({
+                "title": question,
+                "body": body_text
+            })
+            
+        # Add the FAQ Database section with all FAQ subsections
+        self.prompt_add_section(
+            "FAQ Database",
+            body="Here is your database of frequently asked questions and answers:",
+            subsections=faq_subsections
+        )
+        
+        # Add section about suggesting related questions if enabled
+        if self.suggest_related:
+            self.prompt_add_section(
+                "Related Questions",
+                body="When appropriate, suggest other related questions from the FAQ database that might be helpful."
+            )
+    
+    def _setup_post_prompt(self):
+        """Set up the post-prompt for summary"""
+        post_prompt = """
+        Return a JSON summary of this interaction:
+        {
+            "question": "MAIN_QUESTION_ASKED",
+            "matched_faq": "MATCHED_FAQ_QUESTION_OR_null",
+            "answered_successfully": true/false,
+            "suggested_related": []
+        }
+        """
+        self.set_post_prompt(post_prompt)
+    
+    def _configure_agent_settings(self):
+        """Configure additional agent settings"""
+        # Add hints for better recognition of FAQ-related terms
+        hints = []
+        
+        # Add questions and categories as hints
+        for faq in self.faqs:
+            # Extract key terms from questions
+            question = faq.get("question", "")
+            if question:
+                # Split question into words and add words with 4+ characters
+                words = [word.strip(".,?!") for word in question.split() if len(word.strip(".,?!")) >= 4]
+                hints.extend(words)
+                
+            # Add categories as hints
+            categories = faq.get("categories", [])
+            hints.extend(categories)
+        
+        # Remove duplicates and add as hints
+        unique_hints = list(set(hints))
+        if unique_hints:
+            self.add_hints(unique_hints)
+        
+        # Set AI behavior parameters
+        self.set_params({
+            "wait_for_user": False,
+            "end_of_speech_timeout": 1000,
+            "ai_volume": 5
+        })
+        
+        # Add global data
+        self.set_global_data({
+            "faq_count": len(self.faqs),
+            "categories": list(set(
+                category 
+                for faq in self.faqs 
+                for category in faq.get("categories", [])
+            ))
+        })
+        
+        # Configure native functions
+        self.set_native_functions(["check_time"])
+    
+    @AgentBase.tool(
+        name="search_faqs",
+        description="Search for FAQs matching a specific query or category",
+        parameters={
+            "query": {
+                "type": "string",
+                "description": "The search query"
+            },
+            "category": {
+                "type": "string",
+                "description": "Optional category to filter by"
+            }
+        }
+    )
+    def search_faqs(self, args, raw_data):
+        """
+        Search for FAQs matching a specific query or category
+        
+        This function helps find relevant FAQs based on a search query or category.
+        It returns matching FAQs in order of relevance.
+        """
+        query = args.get("query", "").lower()
+        category = args.get("category", "").lower()
+        
+        # Simple search logic (in a real implementation, you would use more
+        # sophisticated search algorithms such as vector embeddings)
+        results = []
+        
+        for faq in self.faqs:
+            question = faq.get("question", "").lower()
+            categories = [c.lower() for c in faq.get("categories", [])]
+            match_score = 0
+            
+            # Match on query
+            if query and query in question:
+                # Simple substring matching - higher score for exact matches
+                if query == question:
+                    match_score += 100
+                else:
+                    match_score += 50
+                    
+                # Boost score for matches at the beginning of the question
+                if question.startswith(query):
+                    match_score += 25
+                    
+            # Match on category
+            if category and category in categories:
+                match_score += 30
+                
+            # Only include results with a positive match score
+            if match_score > 0:
+                results.append({
+                    "question": faq.get("question"),
+                    "score": match_score
+                })
+                
+        # Sort results by score (highest first)
+        results.sort(key=lambda x: x["score"], reverse=True)
+        
+        # Limit to top 3 results
+        top_results = results[:3]
+        
+        if top_results:
+            result_text = "Here are the most relevant FAQs:\n\n"
+            for i, result in enumerate(top_results, 1):
+                result_text += f"{i}. {result['question']}\n"
+                
+            return SwaigFunctionResult(result_text)
+        else:
+            return SwaigFunctionResult("No matching FAQs found.")
+    
+    def on_summary(self, summary, raw_data=None):
+        """
+        Process the interaction summary
+        
+        Args:
+            summary: Summary data from the conversation
+            raw_data: The complete raw POST data from the request
+        """
+        if summary:
+            try:
+                # For structured summary
+                if isinstance(summary, dict):
+                    print(f"FAQ interaction summary: {json.dumps(summary, indent=2)}")
+                else:
+                    print(f"FAQ interaction summary: {summary}")
+                    
+                # Subclasses can override this to log or save the interaction
+            except Exception as e:
+                print(f"Error processing summary: {str(e)}")