signalwire-agents 0.1.17__py3-none-any.whl → 0.1.19__py3-none-any.whl

signalwire_agents/core/contexts.py

@@ -18,9 +18,16 @@ class Step:
         self._step_criteria: Optional[str] = None
         self._functions: Optional[Union[str, List[str]]] = None
         self._valid_steps: Optional[List[str]] = None
+        self._valid_contexts: Optional[List[str]] = None
         
         # POM-style sections for rich prompts
         self._sections: List[Dict[str, Any]] = []
+        
+        # Reset object for context switching from steps
+        self._reset_system_prompt: Optional[str] = None
+        self._reset_user_prompt: Optional[str] = None
+        self._reset_consolidate: bool = False
+        self._reset_full_reset: bool = False
     
     def set_text(self, text: str) -> 'Step':
         """
@@ -108,6 +115,71 @@ class Step:
         self._valid_steps = steps
         return self
     
+    def set_valid_contexts(self, contexts: List[str]) -> 'Step':
+        """
+        Set which contexts can be navigated to from this step
+        
+        Args:
+            contexts: List of valid context names
+            
+        Returns:
+            Self for method chaining
+        """
+        self._valid_contexts = contexts
+        return self
+    
+    def set_reset_system_prompt(self, system_prompt: str) -> 'Step':
+        """
+        Set system prompt for context switching when this step navigates to a context
+        
+        Args:
+            system_prompt: New system prompt for context switching
+            
+        Returns:
+            Self for method chaining
+        """
+        self._reset_system_prompt = system_prompt
+        return self
+    
+    def set_reset_user_prompt(self, user_prompt: str) -> 'Step':
+        """
+        Set user prompt for context switching when this step navigates to a context
+        
+        Args:
+            user_prompt: User message to inject for context switching
+            
+        Returns:
+            Self for method chaining
+        """
+        self._reset_user_prompt = user_prompt
+        return self
+    
+    def set_reset_consolidate(self, consolidate: bool) -> 'Step':
+        """
+        Set whether to consolidate conversation when this step switches contexts
+        
+        Args:
+            consolidate: Whether to consolidate previous conversation
+            
+        Returns:
+            Self for method chaining
+        """
+        self._reset_consolidate = consolidate
+        return self
+    
+    def set_reset_full_reset(self, full_reset: bool) -> 'Step':
+        """
+        Set whether to do full reset when this step switches contexts
+        
+        Args:
+            full_reset: Whether to completely rewrite system prompt vs inject
+            
+        Returns:
+            Self for method chaining
+        """
+        self._reset_full_reset = full_reset
+        return self
+    
     def _render_text(self) -> str:
         """Render the step's prompt text"""
         if self._text is not None:
@@ -145,6 +217,23 @@ class Step:
         if self._valid_steps is not None:
             step_dict["valid_steps"] = self._valid_steps
             
+        if self._valid_contexts is not None:
+            step_dict["valid_contexts"] = self._valid_contexts
+        
+        # Add reset object if any reset parameters are set
+        reset_obj = {}
+        if self._reset_system_prompt is not None:
+            reset_obj["system_prompt"] = self._reset_system_prompt
+        if self._reset_user_prompt is not None:
+            reset_obj["user_prompt"] = self._reset_user_prompt
+        if self._reset_consolidate:
+            reset_obj["consolidate"] = self._reset_consolidate
+        if self._reset_full_reset:
+            reset_obj["full_reset"] = self._reset_full_reset
+            
+        if reset_obj:
+            step_dict["reset"] = reset_obj
+            
         return step_dict
 
 
@@ -156,6 +245,19 @@ class Context:
         self._steps: Dict[str, Step] = {}
         self._step_order: List[str] = []
         self._valid_contexts: Optional[List[str]] = None
+        
+        # Context entry parameters
+        self._post_prompt: Optional[str] = None
+        self._system_prompt: Optional[str] = None
+        self._system_prompt_sections: List[Dict[str, Any]] = []  # For POM-style system prompts
+        self._consolidate: bool = False
+        self._full_reset: bool = False
+        self._user_prompt: Optional[str] = None
+        self._isolated: bool = False
+        
+        # Context prompt (separate from system_prompt)
+        self._prompt_text: Optional[str] = None
+        self._prompt_sections: List[Dict[str, Any]] = []
     
     def add_step(self, name: str) -> Step:
         """
@@ -188,6 +290,209 @@ class Context:
         self._valid_contexts = contexts
         return self
     
+    def set_post_prompt(self, post_prompt: str) -> 'Context':
+        """
+        Set post prompt override for this context
+        
+        Args:
+            post_prompt: Post prompt text to use when this context is active
+            
+        Returns:
+            Self for method chaining
+        """
+        self._post_prompt = post_prompt
+        return self
+    
+    def set_system_prompt(self, system_prompt: str) -> 'Context':
+        """
+        Set system prompt for context switching (triggers context reset)
+        
+        Args:
+            system_prompt: New system prompt for when this context is entered
+            
+        Returns:
+            Self for method chaining
+        """
+        if self._system_prompt_sections:
+            raise ValueError("Cannot use set_system_prompt() when POM sections have been added for system prompt. Use one approach or the other.")
+        self._system_prompt = system_prompt
+        return self
+    
+    def set_consolidate(self, consolidate: bool) -> 'Context':
+        """
+        Set whether to consolidate conversation history when entering this context
+        
+        Args:
+            consolidate: Whether to consolidate previous conversation
+            
+        Returns:
+            Self for method chaining
+        """
+        self._consolidate = consolidate
+        return self
+    
+    def set_full_reset(self, full_reset: bool) -> 'Context':
+        """
+        Set whether to do full reset when entering this context
+        
+        Args:
+            full_reset: Whether to completely rewrite system prompt vs inject
+            
+        Returns:
+            Self for method chaining
+        """
+        self._full_reset = full_reset
+        return self
+    
+    def set_user_prompt(self, user_prompt: str) -> 'Context':
+        """
+        Set user prompt to inject when entering this context
+        
+        Args:
+            user_prompt: User message to inject for context
+            
+        Returns:
+            Self for method chaining
+        """
+        self._user_prompt = user_prompt
+        return self
+    
+    def set_isolated(self, isolated: bool) -> 'Context':
+        """
+        Set whether to truncate conversation history when entering this context
+        
+        Args:
+            isolated: Whether to truncate conversation on context switch
+            
+        Returns:
+            Self for method chaining
+        """
+        self._isolated = isolated
+        return self
+    
+    def add_system_section(self, title: str, body: str) -> 'Context':
+        """
+        Add a POM section to the system prompt
+        
+        Args:
+            title: Section title
+            body: Section body text
+            
+        Returns:
+            Self for method chaining
+        """
+        if self._system_prompt is not None:
+            raise ValueError("Cannot add POM sections for system prompt when set_system_prompt() has been used. Use one approach or the other.")
+        self._system_prompt_sections.append({"title": title, "body": body})
+        return self
+    
+    def add_system_bullets(self, title: str, bullets: List[str]) -> 'Context':
+        """
+        Add a POM section with bullet points to the system prompt
+        
+        Args:
+            title: Section title
+            bullets: List of bullet points
+            
+        Returns:
+            Self for method chaining
+        """
+        if self._system_prompt is not None:
+            raise ValueError("Cannot add POM sections for system prompt when set_system_prompt() has been used. Use one approach or the other.")
+        self._system_prompt_sections.append({"title": title, "bullets": bullets})
+        return self
+    
+    def set_prompt(self, prompt: str) -> 'Context':
+        """
+        Set the context's prompt text directly
+        
+        Args:
+            prompt: The prompt text for this context
+            
+        Returns:
+            Self for method chaining
+        """
+        if self._prompt_sections:
+            raise ValueError("Cannot use set_prompt() when POM sections have been added. Use one approach or the other.")
+        self._prompt_text = prompt
+        return self
+    
+    def add_section(self, title: str, body: str) -> 'Context':
+        """
+        Add a POM section to the context prompt
+        
+        Args:
+            title: Section title
+            body: Section body text
+            
+        Returns:
+            Self for method chaining
+        """
+        if self._prompt_text is not None:
+            raise ValueError("Cannot add POM sections when set_prompt() has been used. Use one approach or the other.")
+        self._prompt_sections.append({"title": title, "body": body})
+        return self
+    
+    def add_bullets(self, title: str, bullets: List[str]) -> 'Context':
+        """
+        Add a POM section with bullet points to the context prompt
+        
+        Args:
+            title: Section title
+            bullets: List of bullet points
+            
+        Returns:
+            Self for method chaining
+        """
+        if self._prompt_text is not None:
+            raise ValueError("Cannot add POM sections when set_prompt() has been used. Use one approach or the other.")
+        self._prompt_sections.append({"title": title, "bullets": bullets})
+        return self
+    
+    def _render_prompt(self) -> Optional[str]:
+        """Render the context's prompt text"""
+        if self._prompt_text is not None:
+            return self._prompt_text
+        
+        if not self._prompt_sections:
+            return None
+        
+        # Convert POM sections to markdown
+        markdown_parts = []
+        for section in self._prompt_sections:
+            if "bullets" in section:
+                markdown_parts.append(f"## {section['title']}")
+                for bullet in section["bullets"]:
+                    markdown_parts.append(f"- {bullet}")
+            else:
+                markdown_parts.append(f"## {section['title']}")
+                markdown_parts.append(section["body"])
+            markdown_parts.append("")  # Add spacing
+        
+        return "\n".join(markdown_parts).strip()
+    
+    def _render_system_prompt(self) -> Optional[str]:
+        """Render the system prompt text"""
+        if self._system_prompt is not None:
+            return self._system_prompt
+        
+        if not self._system_prompt_sections:
+            return None
+        
+        # Convert POM sections to markdown
+        markdown_parts = []
+        for section in self._system_prompt_sections:
+            if "bullets" in section:
+                markdown_parts.append(f"## {section['title']}")
+                for bullet in section["bullets"]:
+                    markdown_parts.append(f"- {bullet}")
+            else:
+                markdown_parts.append(f"## {section['title']}")
+                markdown_parts.append(section["body"])
+            markdown_parts.append("")  # Add spacing
+        
+        return "\n".join(markdown_parts).strip()
+    
     def to_dict(self) -> Dict[str, Any]:
         """Convert context to dictionary for SWML generation"""
         if not self._steps:
@@ -199,6 +504,34 @@ class Context:
         
         if self._valid_contexts is not None:
             context_dict["valid_contexts"] = self._valid_contexts
+        
+        # Add context entry parameters
+        if self._post_prompt is not None:
+            context_dict["post_prompt"] = self._post_prompt
+        
+        rendered_system_prompt = self._render_system_prompt()
+        if rendered_system_prompt is not None:
+            context_dict["system_prompt"] = rendered_system_prompt
+            
+        if self._consolidate:
+            context_dict["consolidate"] = self._consolidate
+            
+        if self._full_reset:
+            context_dict["full_reset"] = self._full_reset
+            
+        if self._user_prompt is not None:
+            context_dict["user_prompt"] = self._user_prompt
+            
+        if self._isolated:
+            context_dict["isolated"] = self._isolated
+        
+        # Add context prompt - use POM structure if sections exist, otherwise use string
+        if self._prompt_sections:
+            # Use structured POM format
+            context_dict["pom"] = self._prompt_sections
+        elif self._prompt_text is not None:
+            # Use string format
+            context_dict["prompt"] = self._prompt_text
             
         return context_dict
 

signalwire_agents/core/swml_handler.py

@@ -103,19 +103,19 @@ class AIVerbHandler(SWMLVerbHandler):
             errors.append("'prompt' must be an object")
             return False, errors
         
-        # Check that prompt contains one of: text, pom, or contexts
+        # Check that prompt contains either text or pom (required)
         has_text = "text" in prompt
         has_pom = "pom" in prompt
         has_contexts = "contexts" in prompt
         
-        options_count = sum([has_text, has_pom, has_contexts])
+        # Require either text or pom (mutually exclusive)
+        base_prompt_count = sum([has_text, has_pom])
+        if base_prompt_count == 0:
+            errors.append("'prompt' must contain either 'text' or 'pom' as base prompt")
+        elif base_prompt_count > 1:
+            errors.append("'prompt' can only contain one of: 'text' or 'pom' (mutually exclusive)")
         
-        if options_count == 0:
-            errors.append("'prompt' must contain one of: 'text', 'pom', or 'contexts'")
-        elif options_count > 1:
-            errors.append("'prompt' can only contain one of: 'text', 'pom', or 'contexts'")
-        
-        # Validate contexts structure if present
+        # Contexts are optional and can be combined with text or pom
         if has_contexts:
             contexts = prompt["contexts"]
             if not isinstance(contexts, dict):
@@ -141,9 +141,9 @@ class AIVerbHandler(SWMLVerbHandler):
         Build a configuration for the AI verb
         
         Args:
-            prompt_text: Text prompt for the AI (mutually exclusive with prompt_pom and contexts)
-            prompt_pom: POM structure for the AI prompt (mutually exclusive with prompt_text and contexts)
-            contexts: Contexts and steps configuration (mutually exclusive with prompt_text and prompt_pom)
+            prompt_text: Text prompt for the AI (mutually exclusive with prompt_pom)
+            prompt_pom: POM structure for the AI prompt (mutually exclusive with prompt_text)
+            contexts: Optional contexts and steps configuration (can be combined with text or pom)
             post_prompt: Optional post-prompt text
             post_prompt_url: Optional URL for post-prompt processing
             swaig: Optional SWAIG configuration
@@ -154,19 +154,25 @@ class AIVerbHandler(SWMLVerbHandler):
         """
         config = {}
         
-        # Add prompt (either text, POM, or contexts - mutually exclusive)
-        prompt_options_count = sum(x is not None for x in [prompt_text, prompt_pom, contexts])
-        if prompt_options_count == 0:
-            raise ValueError("One of prompt_text, prompt_pom, or contexts must be provided")
-        elif prompt_options_count > 1:
-            raise ValueError("prompt_text, prompt_pom, and contexts are mutually exclusive")
+        # Require either text or pom as base prompt (mutually exclusive)
+        base_prompt_count = sum(x is not None for x in [prompt_text, prompt_pom])
+        if base_prompt_count == 0:
+            raise ValueError("Either prompt_text or prompt_pom must be provided as base prompt")
+        elif base_prompt_count > 1:
+            raise ValueError("prompt_text and prompt_pom are mutually exclusive")
         
+        # Build prompt object with base prompt
+        prompt_config = {}
         if prompt_text is not None:
-            config["prompt"] = {"text": prompt_text}
+            prompt_config["text"] = prompt_text
         elif prompt_pom is not None:
-            config["prompt"] = {"pom": prompt_pom}
-        elif contexts is not None:
-            config["prompt"] = {"contexts": contexts}
+            prompt_config["pom"] = prompt_pom
+            
+        # Add contexts if provided (optional, activates steps feature)
+        if contexts is not None:
+            prompt_config["contexts"] = contexts
+            
+        config["prompt"] = prompt_config
         
         # Add post-prompt if provided
         if post_prompt is not None:

signalwire_agents/skills/datasphere_serverless/skill.py

@@ -83,7 +83,6 @@ class DataSphereServerlessSkill(SkillBase):
         webhook_params = {
             "document_id": self.document_id,
             "query_string": "${args.query}",  # Only this is dynamic from user input
-            "distance": self.distance,
             "count": self.count
         }
         

signalwire_agents/skills/web_search/skill.py

@@ -224,7 +224,7 @@ class WebSearchSkill(SkillBase):
                 formatted_message = self.no_results_message.format(query=query) if '{query}' in self.no_results_message else self.no_results_message
                 return SwaigFunctionResult(formatted_message)
             
-            response = f"I found {num_results} results for '{query}':\n\n{search_results}"
+            response = f"Here are {num_results} results for '{query}':\n\nReiterate them to the user in a concise summary format\n\n{search_results}"
             return SwaigFunctionResult(response)
             
         except Exception as e:

{signalwire_agents-0.1.17.dist-info → signalwire_agents-0.1.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.17
+Version: 0.1.19
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
 Project-URL: Homepage, https://github.com/signalwire/signalwire-ai-agents
@@ -287,7 +287,7 @@ For detailed documentation, see [DataMap Guide](docs/datamap_guide.md).
 
 ## Contexts and Steps
 
-The SignalWire Agents SDK provides a powerful alternative to traditional Prompt Object Model (POM) prompts through the **Contexts and Steps** system. This feature allows you to create structured, workflow-driven AI interactions with explicit navigation control and step-by-step guidance.
+The SignalWire Agents SDK provides a powerful enhancement to traditional prompts through the **Contexts and Steps** system. This feature allows you to add structured, workflow-driven AI interactions on top of your base prompt, with explicit navigation control and step-by-step guidance.
 
 ### Why Use Contexts and Steps?
 
@@ -296,7 +296,7 @@ The SignalWire Agents SDK provides a powerful alternative to traditional Prompt
 - **Completion Criteria**: Set specific criteria for step completion and progression  
 - **Function Restrictions**: Limit which AI tools are available in each step
 - **Workflow Isolation**: Create separate contexts for different conversation flows
-- **Backward Compatibility**: Works alongside traditional prompts and all existing AgentBase features
+- **Enhanced Base Prompts**: Adds structured workflows on top of your existing prompt foundation
 
 ### Basic Usage
 
@@ -307,30 +307,34 @@ class WorkflowAgent(AgentBase):
     def __init__(self):
         super().__init__(name="Workflow Assistant", route="/workflow")
         
-        # Define contexts and steps (alternative to traditional prompts)
+        # Set base prompt (required even when using contexts)
+        self.prompt_add_section("Role", "You are a helpful workflow assistant.")
+        self.prompt_add_section("Instructions", "Guide users through structured processes step by step.")
+        
+        # Define contexts and steps (adds structured workflow to base prompt)
         contexts = self.define_contexts()
         
         # Create a single context named "default" (required for single context)
-        context = contexts.create_context("default")
+        context = contexts.add_context("default")
         
         # Add step-by-step workflow
-        context.create_step("greeting") \
+        context.add_step("greeting") \
             .set_text("Welcome! I'm here to help you complete your application. Let's start with your personal information.") \
             .set_step_criteria("User has provided their name and confirmed they want to continue") \
             .set_valid_steps(["personal_info"])  # Can only go to personal_info step
         
-        context.create_step("personal_info") \
+        context.add_step("personal_info") \
             .add_section("Instructions", "Collect the user's personal information") \
             .add_bullets(["Ask for full name", "Ask for email address", "Ask for phone number"]) \
             .set_step_criteria("All personal information has been collected and confirmed") \
             .set_valid_steps(["review", "personal_info"])  # Can stay or move to review
         
-        context.create_step("review") \
+        context.add_step("review") \
             .set_text("Let me review the information you've provided. Please confirm if everything is correct.") \
             .set_step_criteria("User has confirmed or requested changes") \
             .set_valid_steps(["personal_info", "complete"])  # Can go back or complete
         
-        context.create_step("complete") \
+        context.add_step("complete") \
             .set_text("Thank you! Your application has been submitted successfully.") \
             .set_step_criteria("Application processing is complete")
             # No valid_steps = end of workflow
@@ -346,22 +350,27 @@ class MultiContextAgent(AgentBase):
     def __init__(self):
         super().__init__(name="Multi-Context Agent", route="/multi-context")
         
-        # Add skills first
+        # Set base prompt (required)
+        self.prompt_add_section("Role", "You are a versatile AI assistant.")
+        self.prompt_add_section("Capabilities", "You can help with calculations and provide time information.")
+        
+        # Add skills
         self.add_skill("datetime")
         self.add_skill("math")
         
+        # Define contexts for different service modes
         contexts = self.define_contexts()
         
         # Main conversation context
-        main_context = contexts.create_context("main")
-        main_context.create_step("welcome") \
+        main_context = contexts.add_context("main")
+        main_context.add_step("welcome") \
             .set_text("Welcome! I can help with calculations or provide date/time info. What would you like to do?") \
             .set_step_criteria("User has chosen a service type") \
             .set_valid_contexts(["calculator", "datetime_info"])  # Can switch contexts
         
         # Calculator context with function restrictions
-        calc_context = contexts.create_context("calculator")
-        calc_context.create_step("math_mode") \
+        calc_context = contexts.add_context("calculator")
+        calc_context.add_step("math_mode") \
             .add_section("Role", "You are a mathematical assistant") \
             .add_section("Instructions", "Help users with calculations") \
             .set_functions(["math"])  # Only math function available \
@@ -369,8 +378,8 @@ class MultiContextAgent(AgentBase):
             .set_valid_contexts(["main"])  # Can return to main
         
         # DateTime context
-        datetime_context = contexts.create_context("datetime_info")
-        datetime_context.create_step("time_mode") \
+        datetime_context = contexts.add_context("datetime_info")
+        datetime_context.add_step("time_mode") \
             .set_text("I can provide current date and time information. What would you like to know?") \
             .set_functions(["datetime"])  # Only datetime function available \
             .set_step_criteria("Date/time information has been provided") \
@@ -380,7 +389,7 @@ class MultiContextAgent(AgentBase):
 ### Context and Step Methods
 
 #### Context Methods
-- `create_step(name)`: Create a new step in this context
+- `add_step(name)`: Create a new step in this context
 - `set_valid_contexts(contexts)`: Control which contexts can be accessed from this context
 
 #### Step Methods
@@ -406,41 +415,45 @@ class SupportAgent(AgentBase):
     def __init__(self):
         super().__init__(name="Customer Support", route="/support")
         
+        # Set base prompt (required)
+        self.prompt_add_section("Role", "You are a professional customer support representative.")
+        self.prompt_add_section("Goal", "Provide excellent customer service using structured workflows.")
+        
         # Add skills for enhanced capabilities
         self.add_skill("datetime")
         self.add_skill("web_search", {"api_key": "your-key", "search_engine_id": "your-id"})
         
+        # Define support workflow contexts
         contexts = self.define_contexts()
         
         # Triage context
-        triage = contexts.create_context("triage")
-        triage.create_step("initial_greeting") \
-            .add_section("Role", "You are a helpful customer support agent") \
-            .add_section("Goal", "Understand the customer's issue and route them appropriately") \
-            .add_bullets(["Be empathetic and professional", "Ask clarifying questions", "Categorize the issue"]) \
+        triage = contexts.add_context("triage")
+        triage.add_step("initial_greeting") \
+            .add_section("Current Task", "Understand the customer's issue and route them appropriately") \
+            .add_bullets("Questions to Ask", ["What problem are you experiencing?", "How urgent is this issue?", "Have you tried any troubleshooting steps?"]) \
             .set_step_criteria("Issue type has been identified") \
             .set_valid_contexts(["technical_support", "billing_support", "general_inquiry"])
         
         # Technical support context
-        tech = contexts.create_context("technical_support")
-        tech.create_step("technical_diagnosis") \
-            .add_section("Role", "You are a technical support specialist") \
-            .add_section("Instructions", "Help diagnose and resolve technical issues") \
+        tech = contexts.add_context("technical_support")
+        tech.add_step("technical_diagnosis") \
+            .add_section("Current Task", "Help diagnose and resolve technical issues") \
+            .add_section("Available Tools", "Use web search to find solutions and datetime to check service windows") \
             .set_functions(["web_search", "datetime"])  # Can search for solutions and check times \
             .set_step_criteria("Technical issue is resolved or escalated") \
             .set_valid_contexts(["triage"])  # Can return to triage
         
         # Billing support context  
-        billing = contexts.create_context("billing_support")
-        billing.create_step("billing_assistance") \
+        billing = contexts.add_context("billing_support")
+        billing.add_step("billing_assistance") \
             .set_text("I'll help you with your billing inquiry. Please provide your account details.") \
             .set_functions("none")  # No external tools for sensitive billing info \
             .set_step_criteria("Billing issue is addressed") \
             .set_valid_contexts(["triage"])
         
         # General inquiry context
-        general = contexts.create_context("general_inquiry")
-        general.create_step("general_help") \
+        general = contexts.add_context("general_inquiry")
+        general.add_step("general_help") \
             .set_text("I'm here to help with general questions. What can I assist you with?") \
             .set_functions(["web_search", "datetime"])  # Full access to search and time \
             .set_step_criteria("Inquiry has been answered") \