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

signalwire_agents/prefabs/info_gatherer.py

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

@@ -1,387 +0,0 @@
-"""
-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)}")