signalwire-agents 0.1.16__tar.gz → 0.1.18__tar.gz

{signalwire_agents-0.1.16/signalwire_agents.egg-info → signalwire_agents-0.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.16
+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.16 → signalwire_agents-0.1.18}/README.md

@@ -221,7 +221,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?
 
@@ -230,7 +230,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
 
@@ -241,30 +241,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
@@ -280,22 +284,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 \
@@ -303,8 +312,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") \
@@ -314,7 +323,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
@@ -340,41 +349,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.16 → signalwire_agents-0.1.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire_agents"
-version = "0.1.16"
+version = "0.1.18"
 description = "SignalWire AI Agents SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}
@@ -93,7 +93,7 @@ swaig-test = "signalwire_agents.cli.test_swaig:console_entry_point"
 sw-search = "signalwire_agents.cli.sw_search_fast:main"
 
 [tool.setuptools]
-packages = ["signalwire_agents", "signalwire_agents.prefabs", "signalwire_agents.utils", "signalwire_agents.core", "signalwire_agents.core.state", "signalwire_agents.core.security", "signalwire_agents.skills", "signalwire_agents.skills.web_search", "signalwire_agents.skills.datetime", "signalwire_agents.skills.math", "signalwire_agents.skills.joke", "signalwire_agents.skills.datasphere", "signalwire_agents.skills.datasphere_serverless", "signalwire_agents.skills.wikipedia", "signalwire_agents.skills.native_vector_search", "signalwire_agents.cli", "signalwire_agents.search"]
+packages = ["signalwire_agents", "signalwire_agents.prefabs", "signalwire_agents.utils", "signalwire_agents.core", "signalwire_agents.core.state", "signalwire_agents.core.security", "signalwire_agents.skills", "signalwire_agents.skills.web_search", "signalwire_agents.skills.datetime", "signalwire_agents.skills.math", "signalwire_agents.skills.joke", "signalwire_agents.skills.datasphere", "signalwire_agents.skills.datasphere_serverless", "signalwire_agents.skills.wikipedia_search", "signalwire_agents.skills.native_vector_search", "signalwire_agents.cli", "signalwire_agents.search"]
 include-package-data = true
 
 [tool.setuptools.package-data]

{signalwire_agents-0.1.16 → signalwire_agents-0.1.18}/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.16"
+__version__ = "0.1.18"
 
 # Import core classes for easier access
 from .core.agent_base import AgentBase

{signalwire_agents-0.1.16 → signalwire_agents-0.1.18}/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()