signalwire-agents 0.1.0__py3-none-any.whl

signalwire_agents/prefabs/info_gatherer.py

@@ -0,0 +1,253 @@
+"""
+InfoGathererAgent - Prefab agent for collecting structured information from users
+"""
+
+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 InfoGathererAgent(AgentBase):
+    """
+    A prefab agent designed to collect specific fields of information from a user.
+    
+    This agent will:
+    1. Ask for each requested field
+    2. Confirm the collected information
+    3. Return a structured JSON summary
+    
+    Example:
+        agent = InfoGathererAgent(
+            fields=[
+                {"name": "full_name", "prompt": "What is your full name?"},
+                {"name": "reason", "prompt": "How can I help you today?"}
+            ],
+            confirmation_template="Thanks {full_name}, I'll help you with {reason}."
+        )
+    """
+    
+    def __init__(
+        self,
+        fields: List[Dict[str, str]],
+        confirmation_template: Optional[str] = None,
+        summary_format: Optional[Dict[str, Any]] = None,
+        name: str = "info_gatherer", 
+        route: str = "/info_gatherer",
+        schema_path: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Initialize an information gathering agent
+        
+        Args:
+            fields: List of fields to collect, each with:
+                - name: Field name (for storage)
+                - prompt: Question to ask to collect the field
+                - validation: Optional regex or description of valid inputs
+            confirmation_template: Optional template string for confirming collected info
+                Format with field names in {brackets}, e.g. "Thanks {name}!"
+            summary_format: Optional JSON template for the post_prompt summary
+            name: Agent name for the route
+            route: HTTP route for this agent
+            schema_path: Optional path to a custom schema
+            **kwargs: Additional arguments for AgentBase
+        """
+        # Find schema.json if not provided
+        if not schema_path:
+            current_dir = os.path.dirname(os.path.abspath(__file__))
+            parent_dir = os.path.dirname(os.path.dirname(current_dir))
+            
+            schema_locations = [
+                os.path.join(current_dir, "schema.json"),
+                os.path.join(parent_dir, "schema.json")
+            ]
+            
+            for loc in schema_locations:
+                if os.path.exists(loc):
+                    schema_path = loc
+                    break
+                    
+        # Initialize the base agent
+        super().__init__(
+            name=name,
+            route=route,
+            use_pom=True,
+            schema_path=schema_path,
+            **kwargs
+        )
+        
+        self.fields = fields
+        self.confirmation_template = confirmation_template
+        self.summary_format = summary_format
+        
+        # Build the prompt
+        self._build_info_gatherer_prompt()
+        
+        # Set up the post-prompt template
+        self._setup_post_prompt()
+        
+        # Configure additional agent settings
+        self._configure_agent_settings()
+    
+    def _build_info_gatherer_prompt(self):
+        """Build the agent prompt for information gathering"""
+        # Create base instructions
+        instructions = [
+            "Ask for ONLY ONE piece of information at a time.",
+            "Confirm each answer before moving to the next question.",
+            "Do not ask for information not in your field list.",
+            "Be polite but direct with your questions."
+        ]
+        
+        # Add field-specific instructions
+        for i, field in enumerate(self.fields, 1):
+            field_name = field.get("name")
+            field_prompt = field.get("prompt")
+            validation = field.get("validation", "")
+            
+            field_text = f"{i}. {field_name}: \"{field_prompt}\""
+            if validation:
+                field_text += f" ({validation})"
+                
+            instructions.append(field_text)
+        
+        # Add confirmation instruction if a template is provided
+        if self.confirmation_template:
+            instructions.append(
+                f"After collecting all fields, confirm with: {self.confirmation_template}"
+            )
+            
+        # Create the prompt sections directly using prompt_add_section
+        self.prompt_add_section(
+            "Personality", 
+            body="You are a friendly and efficient virtual assistant."
+        )
+        
+        self.prompt_add_section(
+            "Goal", 
+            body="Your job is to collect specific information from the user."
+        )
+        
+        self.prompt_add_section(
+            "Instructions",
+            bullets=instructions
+        )
+    
+    def _setup_post_prompt(self):
+        """Set up the post-prompt for summary formatting"""
+        # Build a JSON template for the collected data
+        if not self.summary_format:
+            # Default format: a flat dictionary of field values
+            field_list = ", ".join([f'"{f["name"]}": "%{{{f["name"]}}}"' for f in self.fields])
+            post_prompt = f"""
+            Return a JSON object with all the information collected:
+            {{
+                {field_list}
+            }}
+            """
+        else:
+            # Format is provided as a template - just serialize it
+            post_prompt = f"""
+            Return the following JSON structure with the collected information:
+            {json.dumps(self.summary_format, indent=2)}
+            """
+            
+        self.set_post_prompt(post_prompt)
+    
+    def _configure_agent_settings(self):
+        """Configure additional agent settings"""
+        # Add field names as hints to help the AI recognize them
+        field_names = [field.get("name") for field in self.fields if "name" in field]
+        self.add_hints(field_names)
+        
+        # Set AI behavior parameters for better information collection
+        self.set_params({
+            "wait_for_user": False,
+            "end_of_speech_timeout": 1200,  # Slightly longer for thoughtful responses
+            "ai_volume": 5,
+            "digit_timeout": 3000,  # 3 seconds for DTMF input timeout
+            "energy_level": 50  # Medium energy threshold
+        })
+        
+        # Add global data with the fields structure
+        self.set_global_data({
+            "fields": [
+                {
+                    "name": field.get("name"),
+                    "prompt": field.get("prompt")
+                }
+                for field in self.fields
+            ]
+        })
+    
+    @AgentBase.tool(
+        name="validate_field",
+        description="Validate if the provided value is valid for a specific field",
+        parameters={
+            "field_name": {
+                "type": "string",
+                "description": "The name of the field to validate"
+            },
+            "value": {
+                "type": "string",
+                "description": "The value provided by the user"
+            }
+        }
+    )
+    def validate_field(self, args, raw_data):
+        """
+        Validate if a provided value is valid for a specific field
+        
+        This function checks if a user's input meets any validation criteria
+        specified for the field.
+        """
+        field_name = args.get("field_name", "")
+        value = args.get("value", "")
+        
+        # Find the field by name
+        field = None
+        for f in self.fields:
+            if f.get("name") == field_name:
+                field = f
+                break
+                
+        if not field:
+            return SwaigFunctionResult(f"Error: Field '{field_name}' not found in configuration.")
+        
+        # Check if the field has validation requirements
+        validation = field.get("validation", "")
+        
+        # Simple validation check (in a real implementation, you would perform
+        # more sophisticated validation based on the validation rules)
+        if validation and not value.strip():
+            return SwaigFunctionResult({
+                "response": f"The field '{field_name}' cannot be empty.",
+                "valid": False
+            })
+        
+        # For this simple example, we'll consider any non-empty value valid
+        return SwaigFunctionResult({
+            "response": f"The value for '{field_name}' is valid.",
+            "valid": True
+        })
+    
+    def on_summary(self, summary, raw_data=None):
+        """
+        Process the collected information summary
+        
+        Args:
+            summary: Dictionary of collected field values
+            raw_data: The complete raw POST data from the request
+            
+        Override this method in subclasses to use the collected data.
+        """
+        if summary:
+            if isinstance(summary, dict):
+                print(f"Information collected: {json.dumps(summary, indent=2)}")
+            else:
+                print(f"Information collected: {summary}")
+        
+        # Subclasses should override this to save or process the collected data

signalwire_agents/prefabs/survey.py

@@ -0,0 +1,387 @@
+"""
+SurveyAgent - Prefab agent for conducting automated surveys
+"""
+
+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 SurveyAgent(AgentBase):
+    """
+    A prefab agent designed to conduct automated surveys with users.
+    
+    This agent will:
+    1. Introduce the survey purpose and structure
+    2. Ask predefined questions in sequence
+    3. Collect and validate responses
+    4. Provide a summary of collected responses
+    
+    Example:
+        agent = SurveyAgent(
+            survey_name="Customer Satisfaction Survey",
+            introduction="We'd like to get your feedback on your recent experience.",
+            questions=[
+                {
+                    "id": "satisfaction",
+                    "text": "How satisfied were you with our service?",
+                    "type": "rating",
+                    "scale": 5,
+                    "required": True
+                },
+                {
+                    "id": "comments",
+                    "text": "Do you have any additional comments?",
+                    "type": "open_ended",
+                    "required": False
+                }
+            ]
+        )
+    """
+    
+    def __init__(
+        self,
+        survey_name: str,
+        questions: List[Dict[str, Any]],
+        introduction: Optional[str] = None,
+        conclusion: Optional[str] = None,
+        brand_name: Optional[str] = None,
+        max_retries: int = 2,
+        schema_path: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Initialize a survey agent
+        
+        Args:
+            survey_name: Name of the survey
+            questions: List of question objects with the following keys:
+                - id: Unique identifier for the question
+                - text: The question text to ask
+                - type: Type of question (rating, multiple_choice, yes_no, open_ended)
+                - options: List of options for multiple_choice questions
+                - scale: For rating questions, the scale (e.g., 1-5)
+                - required: Whether the question requires an answer
+            introduction: Optional custom introduction message
+            conclusion: Optional custom conclusion message
+            brand_name: Optional brand or company name
+            max_retries: Maximum number of times to retry invalid answers
+            schema_path: Optional path to a custom schema
+            **kwargs: Additional arguments for AgentBase
+        """
+        # Find schema.json if not provided
+        if not schema_path:
+            current_dir = os.path.dirname(os.path.abspath(__file__))
+            parent_dir = os.path.dirname(os.path.dirname(current_dir))
+            
+            schema_locations = [
+                os.path.join(current_dir, "schema.json"),
+                os.path.join(parent_dir, "schema.json")
+            ]
+            
+            for loc in schema_locations:
+                if os.path.exists(loc):
+                    schema_path = loc
+                    break
+        
+        # Initialize the base agent
+        super().__init__(
+            name="survey",
+            route="/survey",
+            use_pom=True,
+            schema_path=schema_path,
+            **kwargs
+        )
+        
+        # Store configuration
+        self.survey_name = survey_name
+        self.questions = questions
+        self.brand_name = brand_name or "Our Company"
+        self.max_retries = max_retries
+        
+        # Default messages if not provided
+        self.introduction = introduction or f"Welcome to our {survey_name}. We appreciate your participation."
+        self.conclusion = conclusion or "Thank you for completing our survey. Your feedback is valuable to us."
+        
+        # Validate questions
+        self._validate_questions()
+        
+        # Set up the agent's configuration
+        self._setup_survey_agent()
+    
+    def _validate_questions(self):
+        """Validate the question format and structure"""
+        valid_types = ["rating", "multiple_choice", "yes_no", "open_ended"]
+        
+        for i, question in enumerate(self.questions):
+            # Ensure required fields are present
+            if "id" not in question or not question["id"]:
+                question["id"] = f"question_{i+1}"
+                
+            if "text" not in question or not question["text"]:
+                raise ValueError(f"Question {i+1} is missing the 'text' field")
+                
+            if "type" not in question or question["type"] not in valid_types:
+                raise ValueError(f"Question {i+1} has an invalid type. Must be one of: {', '.join(valid_types)}")
+                
+            # Set defaults for optional fields
+            if "required" not in question:
+                question["required"] = True
+                
+            # Type-specific validation
+            if question["type"] == "multiple_choice" and ("options" not in question or not question["options"]):
+                raise ValueError(f"Multiple choice question '{question['id']}' must have options")
+                
+            if question["type"] == "rating" and "scale" not in question:
+                question["scale"] = 5  # Default to 5-point scale
+    
+    def _setup_survey_agent(self):
+        """Configure the survey agent with appropriate settings"""
+        # Basic personality and instructions
+        self.prompt_add_section("Personality", 
+            body=f"You are a friendly and professional survey agent representing {self.brand_name}."
+        )
+        
+        self.prompt_add_section("Goal", 
+            body=f"Conduct the '{self.survey_name}' survey by asking questions and collecting responses."
+        )
+        
+        # Build detailed instructions
+        instructions = [
+            "Guide the user through each survey question in sequence.",
+            "Ask only one question at a time and wait for a response.",
+            "For rating questions, explain the scale (e.g., 1-5, where 5 is best).",
+            "For multiple choice questions, list all the options.",
+            f"If a response is invalid, explain and retry up to {self.max_retries} times.",
+            "Be conversational but stay focused on collecting the survey data.",
+            "After all questions are answered, thank the user for their participation."
+        ]
+        
+        self.prompt_add_section("Instructions", bullets=instructions)
+        
+        # Add introduction section
+        self.prompt_add_section("Introduction", 
+            body=f"Begin with this introduction: {self.introduction}"
+        )
+        
+        # Questions section with all the survey questions
+        questions_subsections = []
+        for q in self.questions:
+            # Build a description based on question type
+            description = f"ID: {q['id']}\nType: {q['type']}\nRequired: {q['required']}"
+            
+            if q["type"] == "rating":
+                description += f"\nScale: 1-{q['scale']}"
+                
+            if q["type"] == "multiple_choice" and "options" in q:
+                options_list = ", ".join(q["options"])
+                description += f"\nOptions: {options_list}"
+                
+            questions_subsections.append({
+                "title": q["text"],
+                "body": description
+            })
+            
+        self.prompt_add_section("Survey Questions", 
+            body="Ask these questions in order:",
+            subsections=questions_subsections
+        )
+        
+        # Add conclusion section
+        self.prompt_add_section("Conclusion", 
+            body=f"End with this conclusion: {self.conclusion}"
+        )
+        
+        # Set up the post-prompt for summary
+        post_prompt = """
+        Return a JSON summary of the survey responses:
+        {
+            "survey_name": "SURVEY_NAME",
+            "responses": {
+                "QUESTION_ID_1": "RESPONSE_1",
+                "QUESTION_ID_2": "RESPONSE_2",
+                ...
+            },
+            "completion_status": "complete/incomplete",
+            "timestamp": "CURRENT_TIMESTAMP"
+        }
+        """
+        self.set_post_prompt(post_prompt)
+        
+        # Configure hints to help the AI understand survey terminology
+        type_terms = []
+        for q in self.questions:
+            if q["type"] == "rating":
+                type_terms.extend([str(i) for i in range(1, q["scale"]+1)])
+            elif q["type"] == "multiple_choice" and "options" in q:
+                type_terms.extend(q["options"])
+            elif q["type"] == "yes_no":
+                type_terms.extend(["yes", "no"])
+                
+        self.add_hints([
+            self.survey_name,
+            self.brand_name,
+            *type_terms
+        ])
+        
+        # Set AI behavior parameters
+        self.set_params({
+            "wait_for_user": False,
+            "end_of_speech_timeout": 1500,  # Longer timeout for thoughtful responses
+            "ai_volume": 5,
+            "static_greeting": self.introduction,
+            "static_greeting_no_barge": True
+        })
+        
+        # Add global data available to the AI
+        self.set_global_data({
+            "survey_name": self.survey_name,
+            "brand_name": self.brand_name,
+            "questions": self.questions,
+            "max_retries": self.max_retries
+        })
+        
+        # Configure native functions
+        self.set_native_functions(["check_time"])
+    
+    @AgentBase.tool(
+        name="validate_response",
+        description="Validate if a response meets the requirements for a specific question",
+        parameters={
+            "question_id": {
+                "type": "string",
+                "description": "The ID of the question"
+            },
+            "response": {
+                "type": "string",
+                "description": "The user's response to validate"
+            }
+        }
+    )
+    def validate_response(self, args, raw_data):
+        """
+        Validate if a response meets the requirements for a specific question
+        
+        This function checks if a user's response is valid for the specified question
+        based on the question type and constraints.
+        """
+        question_id = args.get("question_id", "")
+        response = args.get("response", "")
+        
+        # Find the question by ID
+        question = None
+        for q in self.questions:
+            if q["id"] == question_id:
+                question = q
+                break
+                
+        if not question:
+            return SwaigFunctionResult(f"Error: Question with ID '{question_id}' not found.")
+        
+        # Validate based on question type
+        valid = True
+        message = f"Response to '{question_id}' is valid."
+        
+        if question["type"] == "rating":
+            try:
+                rating = int(response.strip())
+                if rating < 1 or rating > question.get("scale", 5):
+                    valid = False
+                    message = f"Invalid rating. Please provide a number between 1 and {question.get('scale', 5)}."
+            except ValueError:
+                valid = False
+                message = f"Invalid rating. Please provide a number between 1 and {question.get('scale', 5)}."
+                
+        elif question["type"] == "multiple_choice":
+            options = question.get("options", [])
+            if not any(response.lower().strip() == option.lower() for option in options):
+                valid = False
+                message = f"Invalid choice. Please select one of: {', '.join(options)}."
+                
+        elif question["type"] == "yes_no":
+            response_lower = response.lower().strip()
+            if response_lower not in ["yes", "no", "y", "n"]:
+                valid = False
+                message = "Please answer with 'yes' or 'no'."
+        
+        # For open-ended, any non-empty response is valid
+        elif question["type"] == "open_ended":
+            if not response.strip() and question.get("required", True):
+                valid = False
+                message = "A response is required for this question."
+                
+        return SwaigFunctionResult({
+            "response": message,
+            "valid": valid,
+            "question_id": question_id
+        })
+    
+    @AgentBase.tool(
+        name="log_response",
+        description="Log a validated response to a survey question",
+        parameters={
+            "question_id": {
+                "type": "string",
+                "description": "The ID of the question"
+            },
+            "response": {
+                "type": "string",
+                "description": "The user's validated response"
+            }
+        }
+    )
+    def log_response(self, args, raw_data):
+        """
+        Log a validated response to a survey question
+        
+        This function would typically connect to a database or API to store the response.
+        In this example, it just acknowledges that the response was received.
+        """
+        question_id = args.get("question_id", "")
+        response = args.get("response", "")
+        
+        # Find the question by ID for a more informative message
+        question_text = ""
+        for q in self.questions:
+            if q["id"] == question_id:
+                question_text = q["text"]
+                break
+        
+        # In a real implementation, you would store this response in a database
+        # For this example, we just acknowledge it
+        message = f"Response to '{question_text}' has been recorded."
+        
+        return SwaigFunctionResult({
+            "response": message,
+            "question_id": question_id,
+            "success": True
+        })
+    
+    def on_summary(self, summary, raw_data=None):
+        """
+        Process the survey results summary
+        
+        Args:
+            summary: Summary data containing survey responses
+            raw_data: The complete raw POST data from the request
+        """
+        if summary:
+            try:
+                # Log survey completion
+                if isinstance(summary, dict):
+                    print(f"Survey completed: {json.dumps(summary, indent=2)}")
+                    
+                    # Here you would typically:
+                    # 1. Store the responses in a database
+                    # 2. Trigger any follow-up actions
+                    # 3. Send notifications if needed
+                    
+                else:
+                    print(f"Survey summary (unstructured): {summary}")
+                    
+            except Exception as e:
+                print(f"Error processing survey summary: {str(e)}")