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

signalwire_agents/__init__.py

@@ -18,7 +18,7 @@ A package for building AI agents using SignalWire's AI and SWML capabilities.
 from .core.logging_config import configure_logging
 configure_logging()
 
-__version__ = "0.1.17"
+__version__ = "0.1.18"
 
 # Import core classes for easier access
 from .core.agent_base import AgentBase

signalwire_agents/cli/build_search.py

@@ -85,6 +85,10 @@ Examples:
   sw-search search ./docs.swsearch "how to create an agent"
   sw-search search ./docs.swsearch "API reference" --count 3 --verbose
   sw-search search ./docs.swsearch "configuration" --tags documentation --json
+
+  # Search via remote API
+  sw-search remote http://localhost:8001 "how to create an agent" --index-name docs
+  sw-search remote localhost:8001 "API reference" --index-name docs --count 3 --verbose
         """
     )
     
@@ -263,7 +267,7 @@ Examples:
     
     try:
         # Create index builder - import only when actually needed
-        from ..search.index_builder import IndexBuilder
+        from signalwire_agents.search.index_builder import IndexBuilder
         builder = IndexBuilder(
             model_name=args.model,
             chunking_strategy=args.chunking_strategy,
@@ -328,7 +332,7 @@ def validate_command():
         sys.exit(1)
     
     try:
-        from ..search.index_builder import IndexBuilder
+        from signalwire_agents.search.index_builder import IndexBuilder
         builder = IndexBuilder()
         
         validation = builder.validate_index(args.index_file)
@@ -376,8 +380,8 @@ def search_command():
     try:
         # Import search dependencies
         try:
-            from ..search.search_engine import SearchEngine
-            from ..search.query_processor import preprocess_query
+            from signalwire_agents.search.search_engine import SearchEngine
+            from signalwire_agents.search.query_processor import preprocess_query
         except ImportError as e:
             print(f"Error: Search functionality not available. Install with: pip install signalwire-agents[search]")
             print(f"Details: {e}")
@@ -478,6 +482,141 @@ def search_command():
             traceback.print_exc()
         sys.exit(1)
 
+def remote_command():
+    """Search via remote API endpoint"""
+    parser = argparse.ArgumentParser(description='Search via remote API endpoint')
+    parser.add_argument('endpoint', help='Remote API endpoint URL (e.g., http://localhost:8001)')
+    parser.add_argument('query', help='Search query')
+    parser.add_argument('--index-name', required=True, help='Name of the index to search')
+    parser.add_argument('--count', type=int, default=5, help='Number of results to return (default: 5)')
+    parser.add_argument('--distance-threshold', type=float, default=0.0, help='Minimum similarity score (default: 0.0)')
+    parser.add_argument('--tags', help='Comma-separated tags to filter by')
+    parser.add_argument('--verbose', action='store_true', help='Show detailed information')
+    parser.add_argument('--json', action='store_true', help='Output results as JSON')
+    parser.add_argument('--no-content', action='store_true', help='Hide content in results (show only metadata)')
+    parser.add_argument('--timeout', type=int, default=30, help='Request timeout in seconds (default: 30)')
+    
+    args = parser.parse_args()
+    
+    # Ensure endpoint starts with http:// or https://
+    endpoint = args.endpoint
+    if not endpoint.startswith(('http://', 'https://')):
+        endpoint = f"http://{endpoint}"
+    
+    # Ensure endpoint ends with /search
+    if not endpoint.endswith('/search'):
+        if endpoint.endswith('/'):
+            endpoint += 'search'
+        else:
+            endpoint += '/search'
+    
+    try:
+        import requests
+    except ImportError:
+        print("Error: requests library not available. Install with: pip install requests")
+        sys.exit(1)
+    
+    # Prepare request payload
+    payload = {
+        'query': args.query,
+        'index_name': args.index_name,
+        'count': args.count,
+        'distance_threshold': args.distance_threshold
+    }
+    
+    if args.tags:
+        payload['tags'] = [tag.strip() for tag in args.tags.split(',')]
+    
+    if args.verbose:
+        print(f"Searching remote endpoint: {endpoint}")
+        print(f"Payload: {payload}")
+        print()
+    
+    try:
+        # Make the API request
+        response = requests.post(
+            endpoint,
+            json=payload,
+            headers={'Content-Type': 'application/json'},
+            timeout=args.timeout
+        )
+        
+        if response.status_code == 200:
+            result = response.json()
+            
+            if args.json:
+                # Output raw JSON response
+                import json
+                print(json.dumps(result, indent=2))
+            else:
+                # Human-readable output
+                results = result.get('results', [])
+                if not results:
+                    print(f"No results found for '{args.query}' in index '{args.index_name}'")
+                    sys.exit(0)
+                
+                print(f"Found {len(results)} result(s) for '{args.query}' in index '{args.index_name}':")
+                if result.get('enhanced_query') and result.get('enhanced_query') != args.query:
+                    print(f"Enhanced query: '{result.get('enhanced_query')}'")
+                print("=" * 80)
+                
+                for i, search_result in enumerate(results):
+                    print(f"\n[{i+1}] Score: {search_result.get('score', 0):.4f}")
+                    
+                    # Show metadata
+                    metadata = search_result.get('metadata', {})
+                    print(f"File: {metadata.get('filename', 'Unknown')}")
+                    if metadata.get('section'):
+                        print(f"Section: {metadata['section']}")
+                    if metadata.get('line_start'):
+                        print(f"Lines: {metadata['line_start']}-{metadata.get('line_end', metadata['line_start'])}")
+                    if metadata.get('tags'):
+                        print(f"Tags: {', '.join(metadata['tags'])}")
+                    
+                    # Show content unless suppressed
+                    if not args.no_content and 'content' in search_result:
+                        content = search_result['content']
+                        if len(content) > 500 and not args.verbose:
+                            content = content[:500] + "..."
+                        print(f"\nContent:\n{content}")
+                    
+                    if i < len(results) - 1:
+                        print("-" * 80)
+        
+        elif response.status_code == 404:
+            try:
+                error_detail = response.json()
+                error_msg = error_detail.get('detail', 'Index not found')
+            except:
+                error_msg = 'Index not found'
+            print(f"Error: {error_msg}")
+            sys.exit(1)
+        else:
+            try:
+                error_detail = response.json()
+                error_msg = error_detail.get('detail', f'HTTP {response.status_code}')
+            except:
+                error_msg = f'HTTP {response.status_code}: {response.text}'
+            print(f"Error: {error_msg}")
+            sys.exit(1)
+            
+    except requests.ConnectionError:
+        print(f"Error: Could not connect to {endpoint}")
+        print("Make sure the search server is running")
+        sys.exit(1)
+    except requests.Timeout:
+        print(f"Error: Request timed out after {args.timeout} seconds")
+        sys.exit(1)
+    except requests.RequestException as e:
+        print(f"Error making request: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}")
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
 def console_entry_point():
     """Console script entry point for pip installation"""
     import sys
@@ -594,6 +733,10 @@ Examples:
   sw-search search ./docs.swsearch "how to create an agent"
   sw-search search ./docs.swsearch "API reference" --count 3 --verbose
   sw-search search ./docs.swsearch "configuration" --tags documentation --json
+
+  # Search via remote API
+  sw-search remote http://localhost:8001 "how to create an agent" --index-name docs
+  sw-search remote localhost:8001 "API reference" --index-name docs --count 3 --verbose
 """)
         return
     
@@ -609,6 +752,11 @@ Examples:
             sys.argv.pop(1)
             search_command()
             return
+        elif sys.argv[1] == 'remote':
+            # Remove 'remote' from argv and call remote_command
+            sys.argv.pop(1)
+            remote_command()
+            return
     
     # Regular build command
     main()

signalwire_agents/core/agent_base.py

@@ -1496,6 +1496,10 @@ class AgentBase(SWMLService):
         if self._function_includes:
             swaig_obj["includes"] = self._function_includes
         
+        # Add internal_fillers if any are defined
+        if hasattr(self, '_internal_fillers') and self._internal_fillers:
+            swaig_obj["internal_fillers"] = self._internal_fillers
+        
         # Create functions array
         functions = []
         
@@ -1577,13 +1581,25 @@ class AgentBase(SWMLService):
             try:
                 # Check if we're in contexts mode
                 if self._contexts_defined and self._contexts_builder:
-                    # Generate contexts instead of prompt
+                    # Generate contexts and combine with base prompt
                     contexts_dict = self._contexts_builder.to_dict()
                     
-                    # Build AI config with contexts
+                    # Determine base prompt (required when using contexts)
+                    base_prompt_text = None
+                    base_prompt_pom = None
+                    
+                    if prompt_is_pom:
+                        base_prompt_pom = prompt
+                    elif prompt:
+                        base_prompt_text = prompt
+                    else:
+                        # Provide default base prompt if none exists
+                        base_prompt_text = f"You are {self.name}, a helpful AI assistant that follows structured workflows."
+                    
+                    # Build AI config with base prompt + contexts
                     ai_config = ai_handler.build_config(
-                        prompt_text=None,
-                        prompt_pom=None,
+                        prompt_text=base_prompt_text,
+                        prompt_pom=base_prompt_pom,
                         contexts=contexts_dict,
                         post_prompt=post_prompt,
                         post_prompt_url=post_prompt_url,
@@ -2613,6 +2629,63 @@ class AgentBase(SWMLService):
             self.native_functions = [name for name in function_names if isinstance(name, str)]
         return self
 
+    def set_internal_fillers(self, internal_fillers: Dict[str, Dict[str, List[str]]]) -> 'AgentBase':
+        """
+        Set internal fillers for native SWAIG functions
+        
+        Internal fillers provide custom phrases the AI says while executing
+        internal/native functions like check_time, wait_for_user, next_step, etc.
+        
+        Args:
+            internal_fillers: Dictionary mapping function names to language-specific filler phrases
+                            Format: {"function_name": {"language_code": ["phrase1", "phrase2"]}}
+                            Example: {"next_step": {"en-US": ["Moving to the next step...", "Great, let's continue..."]}}
+            
+        Returns:
+            Self for method chaining
+            
+        Example:
+            agent.set_internal_fillers({
+                "next_step": {
+                    "en-US": ["Moving to the next step...", "Great, let's continue..."],
+                    "es": ["Pasando al siguiente paso...", "Excelente, continuemos..."]
+                },
+                "check_time": {
+                    "en-US": ["Let me check the time...", "Getting the current time..."]
+                }
+            })
+        """
+        if internal_fillers and isinstance(internal_fillers, dict):
+            if not hasattr(self, '_internal_fillers'):
+                self._internal_fillers = {}
+            self._internal_fillers.update(internal_fillers)
+        return self
+
+    def add_internal_filler(self, function_name: str, language_code: str, fillers: List[str]) -> 'AgentBase':
+        """
+        Add internal fillers for a specific function and language
+        
+        Args:
+            function_name: Name of the internal function (e.g., 'next_step', 'check_time')
+            language_code: Language code (e.g., 'en-US', 'es', 'fr')
+            fillers: List of filler phrases for this function and language
+            
+        Returns:
+            Self for method chaining
+            
+        Example:
+            agent.add_internal_filler("next_step", "en-US", ["Moving to the next step...", "Great, let's continue..."])
+        """
+        if function_name and language_code and fillers and isinstance(fillers, list):
+            if not hasattr(self, '_internal_fillers'):
+                self._internal_fillers = {}
+            
+            if function_name not in self._internal_fillers:
+                self._internal_fillers[function_name] = {}
+                
+            self._internal_fillers[function_name][language_code] = fillers
+        return self
+
     def add_function_include(self, url: str, functions: List[str], meta_data: Optional[Dict[str, Any]] = None) -> 'AgentBase':
         """
         Add a remote function include to the SWAIG configuration

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/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.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.17
+Version: 0.1.18
 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") \

{signalwire_agents-0.1.17.dist-info → signalwire_agents-0.1.18.dist-info}/RECORD

@@ -1,12 +1,12 @@
-signalwire_agents/__init__.py,sha256=j6hnK4qmHpUrq0dX_QthipymxXUEMLW14ZkW7kq-F2Q,2707
+signalwire_agents/__init__.py,sha256=3YN2p2ynw-LH_LXSsuM52E0U5fCBzjAoxlOaQ7H1bvA,2707
 signalwire_agents/agent_server.py,sha256=3Or8rIMAqW750V-XitBUMgOpW9BAIXmKXoGq7LkejAA,24988
 signalwire_agents/schema.json,sha256=M8Mn6pQda2P9jhbmkALrLr1wt-fRuhYRqdmEi9Rbhqk,178075
 signalwire_agents/cli/__init__.py,sha256=Iy2BfWDWBEZoA1cyHTDsooBSVMx4vH5Ddhr3sEuFe8c,197
-signalwire_agents/cli/build_search.py,sha256=PnGoIZVfIbSF21rb0m0_ceIL-8lJx59_qXrrl8l2yBE,22340
+signalwire_agents/cli/build_search.py,sha256=KLQJBqVSADFyGcKAi0KLwU_UoUd5rtRoKAdfcH91u70,28652
 signalwire_agents/cli/test_swaig.py,sha256=CqfdBWE8_fiFnFWHbv9ouU1eUA_rGUUHwyOf_iUaZFU,101851
 signalwire_agents/core/__init__.py,sha256=mVDLbpq1pg_WwiqsQR28NNZwJ6-VUXFIfg-vN7pk0ew,806
-signalwire_agents/core/agent_base.py,sha256=0MA1i6honMKfyEIyCrVgS7WAR-iL3v3n8u0ZI8B-hHA,155944
-signalwire_agents/core/contexts.py,sha256=h7hra4xoiKAUdVyJhcKggl8X9EoqwTVWBmNMp-sEsuc,9598
+signalwire_agents/core/agent_base.py,sha256=O-sQ9k6L8_qE94Xzpds3bSS52onxqVs8rYU9_1B0LV8,159349
+signalwire_agents/core/contexts.py,sha256=RQGIZGR92AC90nv8_hGa8S4YGY-SmMa1giR4g7jLgQI,21283
 signalwire_agents/core/data_map.py,sha256=U-HLEZQomWf-UI0-nLAE8g1oyRdE5bU_WxQpboI2YI4,17695
 signalwire_agents/core/function_result.py,sha256=GGmd2gAB9uJFFyldrhC86LCmpCnccU1bb-3gZVW2rxE,45360
 signalwire_agents/core/logging_config.py,sha256=x4d_RAjBjVpJOFA2vXnPP2dNr13BZHz091J5rGpC77Y,13142
@@ -15,7 +15,7 @@ signalwire_agents/core/skill_base.py,sha256=lOpVTLhD9NjStF7Lxh6bAQUGa3DpNYV4agXJ
 signalwire_agents/core/skill_manager.py,sha256=XWq4MeDQ3kmM4Th8qI-Gx5klokDHNZ-K9cChJPW-zmQ,8113
 signalwire_agents/core/swaig_function.py,sha256=3xJrrQVxCZX-DssLkdjaui_psTUzahkzAsQ1EyRVMFk,6837
 signalwire_agents/core/swml_builder.py,sha256=Q1ikU9pedgjW888mjbqDFv-jMDvDZ-tZgfyMfu4qQN0,6719
-signalwire_agents/core/swml_handler.py,sha256=C8NvMpNdFg9UiEzPwMmMXMn8X6w10IShKjBJ8VSITBk,8189
+signalwire_agents/core/swml_handler.py,sha256=hFDq41dQWL3EdFbq6h0hizE1dIqdVeiTeCrujbZsPzo,8397
 signalwire_agents/core/swml_renderer.py,sha256=u6HnbOC0NUnPpr6uz0FkXNEqcTF2OjWDui6gceD1Bhs,14773
 signalwire_agents/core/swml_service.py,sha256=oLdVYRYDyucgBVDAuhiOWVTN6p21SvPvddkPIMMd5kw,48346
 signalwire_agents/core/security/__init__.py,sha256=4Mr7baQ_xR_hfJ72YxQRAT_GFa663YjFX_PumJ35Xds,191
@@ -50,7 +50,7 @@ signalwire_agents/skills/math/skill.py,sha256=5sErd5x1rFHJg2GlmdJB3LvrmvTNOrZsA2
 signalwire_agents/skills/native_vector_search/__init__.py,sha256=buvncVoH5u8MJA0SLlz1JQgIuyBTQW5aql-ydnc7Wh8,29
 signalwire_agents/skills/native_vector_search/skill.py,sha256=da-3eM1NT7Tcju1GiQipxOrYhP7OIry68l2dLKpDV4I,15859
 signalwire_agents/skills/web_search/__init__.py,sha256=wJlptYDExYw-nxZJVzlTLOgkKkDOLUUt1ZdoLt44ixs,45
-signalwire_agents/skills/web_search/skill.py,sha256=GkfhG3Vz2HxOv91TvVuA4e_4b5cuswUpnJDLdaZW37k,10304
+signalwire_agents/skills/web_search/skill.py,sha256=6EwoNABxEH5UkEdXsPT72PQzoVlFUbWsFJR6NuyhglI,10363
 signalwire_agents/skills/wikipedia_search/__init__.py,sha256=8Db_aE0ly7QoXg7n2RDvCqKupkyR-UYlK9uFUnGNCE8,184
 signalwire_agents/skills/wikipedia_search/skill.py,sha256=Q_HWJoG2RkQuZMgWxD9czuzEor79Gy1tjo6ywVzec84,6877
 signalwire_agents/utils/__init__.py,sha256=1KVsHzwgfktSXHe3vqSRGImjtIE58szwD2FHHoFBtvY,601
@@ -58,10 +58,10 @@ signalwire_agents/utils/pom_utils.py,sha256=4Mr7baQ_xR_hfJ72YxQRAT_GFa663YjFX_Pu
 signalwire_agents/utils/schema_utils.py,sha256=i4okv_O9bUApwT_jJf4Yoij3bLCrGrW3DC-vzSy2RuY,16392
 signalwire_agents/utils/token_generators.py,sha256=4Mr7baQ_xR_hfJ72YxQRAT_GFa663YjFX_PumJ35Xds,191
 signalwire_agents/utils/validators.py,sha256=4Mr7baQ_xR_hfJ72YxQRAT_GFa663YjFX_PumJ35Xds,191
-signalwire_agents-0.1.17.data/data/schema.json,sha256=M8Mn6pQda2P9jhbmkALrLr1wt-fRuhYRqdmEi9Rbhqk,178075
-signalwire_agents-0.1.17.dist-info/licenses/LICENSE,sha256=NYvAsB-rTcSvG9cqHt9EUHAWLiA9YzM4Qfz-mPdvDR0,1067
-signalwire_agents-0.1.17.dist-info/METADATA,sha256=MercvoiEgCNae7kxsMyXtALOtzwJXux7-1WKe8XGHsQ,34572
-signalwire_agents-0.1.17.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-signalwire_agents-0.1.17.dist-info/entry_points.txt,sha256=LRwltbVfaKUFMYmQoMxJGTT_-iQm0ftzXK0xPfD64Is,138
-signalwire_agents-0.1.17.dist-info/top_level.txt,sha256=kDGS6ZYv84K9P5Kyg9_S8P_pbUXoHkso0On_DB5bbWc,18
-signalwire_agents-0.1.17.dist-info/RECORD,,
+signalwire_agents-0.1.18.data/data/schema.json,sha256=M8Mn6pQda2P9jhbmkALrLr1wt-fRuhYRqdmEi9Rbhqk,178075
+signalwire_agents-0.1.18.dist-info/licenses/LICENSE,sha256=NYvAsB-rTcSvG9cqHt9EUHAWLiA9YzM4Qfz-mPdvDR0,1067
+signalwire_agents-0.1.18.dist-info/METADATA,sha256=OdI3xK6tg17jbWrZkWhAN4hsK2G67oG4VYSQ5BVTIMA,35364
+signalwire_agents-0.1.18.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+signalwire_agents-0.1.18.dist-info/entry_points.txt,sha256=LRwltbVfaKUFMYmQoMxJGTT_-iQm0ftzXK0xPfD64Is,138
+signalwire_agents-0.1.18.dist-info/top_level.txt,sha256=kDGS6ZYv84K9P5Kyg9_S8P_pbUXoHkso0On_DB5bbWc,18
+signalwire_agents-0.1.18.dist-info/RECORD,,