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

signalwire_agents/prefabs/info_gatherer.py

@@ -1,10 +1,18 @@
 """
-InfoGathererAgent - Prefab agent for collecting structured information from users
+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.
+"""
+
+"""
+InfoGathererAgent - Prefab agent for collecting answers to a series of 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
@@ -12,242 +20,244 @@ from signalwire_agents.core.function_result import SwaigFunctionResult
 
 class InfoGathererAgent(AgentBase):
     """
-    A prefab agent designed to collect specific fields of information from a user.
+    A prefab agent designed to collect answers to a series of questions.
     
     This agent will:
-    1. Ask for each requested field
-    2. Confirm the collected information
-    3. Return a structured JSON summary
+    1. Ask if the user is ready to begin
+    2. Ask each question in sequence
+    3. Store the answers for later use
     
     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}."
+            questions=[
+                {"key_name": "full_name", "question_text": "What is your full name?"},
+                {"key_name": "email", "question_text": "What is your email address?", "confirm": True},
+                {"key_name": "reason", "question_text": "How can I help you today?"}
+            ]
         )
     """
     
     def __init__(
         self,
-        fields: List[Dict[str, str]],
-        confirmation_template: Optional[str] = None,
-        summary_format: Optional[Dict[str, Any]] = None,
+        questions: List[Dict[str, str]],
         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
+            questions: List of questions to ask, each with:
+                - key_name: Identifier for storing the answer
+                - question_text: The actual question to ask the user
+                - confirm: (Optional) If set to True, the agent will confirm the answer before submitting
             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
+        # Validate questions format
+        self._validate_questions(questions)
         
-        # Build the prompt
-        self._build_info_gatherer_prompt()
+        # Set up global data with questions and initial state
+        self.set_global_data({
+            "questions": questions,
+            "question_index": 0,
+            "answers": []
+        })
         
-        # Set up the post-prompt template
-        self._setup_post_prompt()
+        # Build a minimal prompt
+        self._build_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", "")
+    def _validate_questions(self, questions):
+        """Validate that questions are in the correct format"""
+        if not questions:
+            raise ValueError("At least one question is required")
             
-            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
+        for i, question in enumerate(questions):
+            if "key_name" not in question:
+                raise ValueError(f"Question {i+1} is missing 'key_name' field")
+            if "question_text" not in question:
+                raise ValueError(f"Question {i+1} is missing 'question_text' field")
+    
+    def _build_prompt(self):
+        """Build a minimal prompt with just the objective"""
         self.prompt_add_section(
-            "Personality", 
-            body="You are a friendly and efficient virtual assistant."
+            "Objective", 
+            body="Your role is to get answers to a series of questions. Begin by asking the user if they are ready to answer some questions. If they confirm they are ready, call the start_questions function to begin the process."
         )
+    
+    def _configure_agent_settings(self):
+        """Configure additional agent settings"""
+        # Set AI behavior parameters
+        self.set_params({
+            "end_of_speech_timeout": 800,
+            "speech_event_timeout": 1000  # Slightly longer for thoughtful responses
+        })
+    
+    def _generate_question_instruction(self, question_text: str, needs_confirmation: bool, is_first_question: bool = False) -> str:
+        """
+        Generate the instruction text for asking a question
         
-        self.prompt_add_section(
-            "Goal", 
-            body="Your job is to collect specific information from the user."
-        )
+        Args:
+            question_text: The question to ask
+            needs_confirmation: Whether confirmation is required
+            is_first_question: Whether this is the first question or a subsequent one
+            
+        Returns:
+            Formatted instruction text
+        """
+        # Start with the appropriate prefix based on whether this is the first question
+        if is_first_question:
+            instruction = f"Ask the user to answer the following question: {question_text}\n\n"
+        else:
+            instruction = f"Previous Answer recorded. Now ask the user to answer the following question: {question_text}\n\n"
         
-        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}
-            }}
-            """
+        # Add the common part
+        instruction += "Make sure the answer fits the scope and context of the question before submitting it. "
+        
+        # Add confirmation guidance if needed
+        if needs_confirmation:
+            instruction += "Insist that the user confirms the answer as many times as needed until they say it is correct."
         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)}
-            """
+            instruction += "You don't need the user to confirm the answer to this question."
             
-        self.set_post_prompt(post_prompt)
+        return instruction
     
-    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)
+    @AgentBase.tool(
+        name="start_questions",
+        description="Start the question sequence with the first question",
+        parameters={}
+    )
+    def start_questions(self, args, raw_data):
+        """
+        Start the question sequence by retrieving the first question
         
-        # 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
-        })
+        This function gets the current question index from global_data
+        and returns the corresponding question.
+        """
+        # Get global data
+        global_data = raw_data.get("global_data", {})
+        questions = global_data.get("questions", [])
+        question_index = global_data.get("question_index", 0)
         
-        # 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
-            ]
-        })
+        # Check if we have questions
+        if not questions or question_index >= len(questions):
+            return SwaigFunctionResult("I don't have any questions to ask.")
+        
+        # Get the current question
+        current_question = questions[question_index]
+        question_text = current_question.get("question_text", "")
+        needs_confirmation = current_question.get("confirm", False)
+        
+        # Generate instruction using the helper method
+        instruction = self._generate_question_instruction(
+            question_text=question_text,
+            needs_confirmation=needs_confirmation,
+            is_first_question=True
+        )
+        
+        # Return a prompt to ask the question
+        return SwaigFunctionResult(instruction)
     
     @AgentBase.tool(
-        name="validate_field",
-        description="Validate if the provided value is valid for a specific field",
+        name="submit_answer",
+        description="Submit an answer to the current question and move to the next one",
         parameters={
-            "field_name": {
-                "type": "string",
-                "description": "The name of the field to validate"
-            },
-            "value": {
+            "answer": {
                 "type": "string",
-                "description": "The value provided by the user"
+                "description": "The user's answer to the current question"
             }
         }
     )
-    def validate_field(self, args, raw_data):
+    def submit_answer(self, args, raw_data):
         """
-        Validate if a provided value is valid for a specific field
+        Submit an answer to the current question and move to the next one
         
-        This function checks if a user's input meets any validation criteria
-        specified for the field.
+        This function:
+        1. Stores the answer in global_data
+        2. Increments the question index
+        3. Returns the next question or completion message
         """
-        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
+        # Get the answer
+        answer = args.get("answer", "")
         
-        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}")
+        # Get global data
+        global_data = raw_data.get("global_data", {})
+        questions = global_data.get("questions", [])
+        question_index = global_data.get("question_index", 0)
+        answers = global_data.get("answers", [])
         
-        # Subclasses should override this to save or process the collected data
+        # Check if we're within bounds
+        if question_index >= len(questions):
+            return SwaigFunctionResult("All questions have already been answered.")
+        
+        # Get the current question
+        current_question = questions[question_index]
+        key_name = current_question.get("key_name", "")
+        
+        # Store the answer
+        new_answer = {"key_name": key_name, "answer": answer}
+        new_answers = answers + [new_answer]
+        
+        # Increment question index
+        new_question_index = question_index + 1
+        
+        print(f"new_question_index: {new_question_index} len(questions): {len(questions)}")
+        
+        # Check if we have more questions
+        if new_question_index < len(questions):
+
+            print(f"Asking next question: {new_question_index} question: {questions[new_question_index]}")
+            
+            # Get the next question
+            next_question = questions[new_question_index]
+            next_question_text = next_question.get("question_text", "")
+            needs_confirmation = next_question.get("confirm", False)
+            
+            # Generate instruction using the helper method
+            instruction = self._generate_question_instruction(
+                question_text=next_question_text,
+                needs_confirmation=needs_confirmation,
+                is_first_question=False
+            )
+            
+            # Create response with the global data update and next question
+            result = SwaigFunctionResult(instruction)
+            
+            # Add actions to update global data
+            result.add_actions([
+                {"set_global_data": {
+                    "answers": new_answers,
+                    "question_index": new_question_index
+                }}
+            ])
+            
+            return result
+        else:
+            # No more questions - create response with global data update and completion message
+            result = SwaigFunctionResult(
+                "Thank you! All questions have been answered. You can now summarize the information collected or ask if there's anything else the user would like to discuss."
+            )
+            
+            # Add actions to update global data
+            result.add_actions([
+                {"set_global_data": {
+                    "answers": new_answers,
+                    "question_index": new_question_index
+                }}
+            ])
+            
+            return result
+