signalwire-agents 0.1.13__py3-none-any.whl → 1.0.17.dev4__py3-none-any.whl

signalwire_agents/core/contexts.py

@@ -1,3 +1,12 @@
+"""
+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.
+"""
+
 """
 Contexts and Steps System for SignalWire Agents
 
@@ -18,9 +27,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 +124,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:
@@ -133,6 +214,7 @@ class Step:
     def to_dict(self) -> Dict[str, Any]:
         """Convert step to dictionary for SWML generation"""
         step_dict = {
+            "name": self.name,
             "text": self._render_text()
         }
         
@@ -145,6 +227,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 +255,23 @@ 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]] = []
+        
+        # Context fillers
+        self._enter_fillers: Optional[Dict[str, List[str]]] = None
+        self._exit_fillers: Optional[Dict[str, List[str]]] = None
     
     def add_step(self, name: str) -> Step:
         """
@@ -188,6 +304,273 @@ 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 set_enter_fillers(self, enter_fillers: Dict[str, List[str]]) -> 'Context':
+        """
+        Set fillers that the AI says when entering this context
+        
+        Args:
+            enter_fillers: Dictionary mapping language codes (or "default") to lists of filler phrases
+                          Example: {"en-US": ["Welcome...", "Hello..."], "default": ["Entering..."]}
+            
+        Returns:
+            Self for method chaining
+        """
+        if enter_fillers and isinstance(enter_fillers, dict):
+            self._enter_fillers = enter_fillers
+        return self
+    
+    def set_exit_fillers(self, exit_fillers: Dict[str, List[str]]) -> 'Context':
+        """
+        Set fillers that the AI says when exiting this context
+        
+        Args:
+            exit_fillers: Dictionary mapping language codes (or "default") to lists of filler phrases
+                         Example: {"en-US": ["Goodbye...", "Thank you..."], "default": ["Exiting..."]}
+            
+        Returns:
+            Self for method chaining
+        """
+        if exit_fillers and isinstance(exit_fillers, dict):
+            self._exit_fillers = exit_fillers
+        return self
+    
+    def add_enter_filler(self, language_code: str, fillers: List[str]) -> 'Context':
+        """
+        Add enter fillers for a specific language
+        
+        Args:
+            language_code: Language code (e.g., "en-US", "es") or "default" for catch-all
+            fillers: List of filler phrases for entering this context
+            
+        Returns:
+            Self for method chaining
+        """
+        if language_code and fillers and isinstance(fillers, list):
+            if self._enter_fillers is None:
+                self._enter_fillers = {}
+            self._enter_fillers[language_code] = fillers
+        return self
+    
+    def add_exit_filler(self, language_code: str, fillers: List[str]) -> 'Context':
+        """
+        Add exit fillers for a specific language
+        
+        Args:
+            language_code: Language code (e.g., "en-US", "es") or "default" for catch-all
+            fillers: List of filler phrases for exiting this context
+            
+        Returns:
+            Self for method chaining
+        """
+        if language_code and fillers and isinstance(fillers, list):
+            if self._exit_fillers is None:
+                self._exit_fillers = {}
+            self._exit_fillers[language_code] = fillers
+        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 +582,41 @@ 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
+        
+        # Add enter and exit fillers if defined
+        if self._enter_fillers is not None:
+            context_dict["enter_fillers"] = self._enter_fillers
+        
+        if self._exit_fillers is not None:
+            context_dict["exit_fillers"] = self._exit_fillers
             
         return context_dict
 

signalwire_agents/core/data_map.py

@@ -257,7 +257,6 @@ class DataMap:
         
         Args:
             foreach_config: Either:
-                - String: JSON path to array in response (deprecated, kept for compatibility)
                 - Dict: Foreach configuration with keys:
                     - input_key: Key in API response containing the array
                     - output_key: Name for the built string variable
@@ -278,20 +277,7 @@ class DataMap:
         if not self._webhooks:
             raise ValueError("Must add webhook before setting foreach")
             
-        if isinstance(foreach_config, str):
-            # Legacy support - convert string to basic foreach config
-            # Extract the key from "${response.key}" format if present
-            if foreach_config.startswith("${response.") and foreach_config.endswith("}"):
-                key = foreach_config[12:-1]  # Remove "${response." and "}"
-            else:
-                key = foreach_config
-            
-            foreach_data = {
-                "input_key": key,
-                "output_key": "foreach_output",
-                "append": "${this}"
-            }
-        else:
+        if isinstance(foreach_config, dict):
             # New format - validate required keys
             required_keys = ["input_key", "output_key", "append"]
             missing_keys = [key for key in required_keys if key not in foreach_config]
@@ -299,6 +285,8 @@ class DataMap:
                 raise ValueError(f"foreach config missing required keys: {missing_keys}")
             
             foreach_data = foreach_config
+        else:
+            raise ValueError("foreach_config must be a dictionary")
             
         self._webhooks[-1]["foreach"] = foreach_data
         return self