Guided Search Guide

The Guided Search Assistant helps users build better queries by providing intelligent assistance, query analysis, and search tips. This guide covers configuration, usage, and advanced features.

Overview

The Guided Search Assistant offers several types of assistance:

• Query Analysis: Intent detection, complexity assessment, and query structure analysis
• Query Building: Step-by-step assistance in constructing effective queries
• Search Tips: Contextual advice on improving search effectiveness
• Query Suggestions: Alternative formulations and refinements
• Error Detection: Identification of common query problems and solutions

Basic Usage

1. Initialize the Assistant

from search_interface.guided_search import GuidedSearchAssistant, GuidedSearchConfig

# Create configuration
config = GuidedSearchConfig(
    enable_intent_detection=True,
    enable_complexity_analysis=True,
    enable_query_building=True,
    max_tips=5
)

# Initialize assistant
assistant = GuidedSearchAssistant(config)

2. Get Search Assistance

# Get assistance for a query
query = "how to learn python"
assistance = await assistant.get_assistance(query, user_id="user123")

print("Guided search assistance:")
print(f"Intent: {assistance['query_analysis']['intent']}")
print(f"Complexity: {assistance['query_analysis']['complexity']}")
print(f"Tips: {[tip['title'] for tip in assistance['search_tips']]}")

3. Build Query Step by Step

# Start query building process
builder = await assistant.start_query_building(user_id="user123")

# Add components to query
await builder.add_topic("python")
await builder.add_intent("learn")
await builder.add_context("beginner")

# Get current query
current_query = await builder.get_current_query()
print(f"Current query: {current_query}")

# Complete query building
final_query = await builder.complete()
print(f"Final query: {final_query}")

Configuration Options

GuidedSearchConfig

config = GuidedSearchConfig(
    # Analysis features
    enable_intent_detection=True,        # Enable intent detection
    enable_complexity_analysis=True,     # Enable complexity analysis
    enable_query_building=True,          # Enable query building
    enable_error_detection=True,         # Enable error detection
    
    # Query building
    max_query_components=10,             # Maximum query components
    enable_auto_completion=True,         # Enable auto-completion
    enable_validation=True,              # Enable query validation
    
    # Search tips
    max_tips=5,                          # Maximum number of tips
    tip_categories=["general", "advanced", "specific"],  # Tip categories
    enable_contextual_tips=True,         # Enable contextual tips
    
    # Performance settings
    cache_enabled=True,                  # Enable caching
    cache_ttl_seconds=300,               # Cache time-to-live
    debounce_delay_ms=200,               # Delay before processing
    
    # Personalization
    personalization_enabled=True,        # Enable personalized assistance
    learning_rate=0.1,                   # Learning rate for personalization
    history_retention_days=90,           # Days to retain query history
)

Advanced Features

1. Intent Detection

# Configure intent detection
config = GuidedSearchConfig(
    enable_intent_detection=True,
    intent_categories=[
        "learn", "find", "compare", "buy", "troubleshoot", "explore"
    ]
)

assistant = GuidedSearchAssistant(config)

# Get intent analysis
intent_analysis = await assistant.analyze_intent("python tutorial", user_id="user123")

print("Intent analysis:")
print(f"Primary intent: {intent_analysis['primary_intent']}")
print(f"Confidence: {intent_analysis['confidence']:.2f}")
print(f"Secondary intents: {intent_analysis['secondary_intents']}")

2. Complexity Analysis

# Configure complexity analysis
config = GuidedSearchConfig(
    enable_complexity_analysis=True,
    complexity_levels=["beginner", "intermediate", "advanced", "expert"]
)

assistant = GuidedSearchAssistant(config)

# Get complexity analysis
complexity_analysis = await assistant.analyze_complexity("python tutorial", user_id="user123")

print("Complexity analysis:")
print(f"Level: {complexity_analysis['level']}")
print(f"Score: {complexity_analysis['score']:.2f}")
print(f"Factors: {complexity_analysis['factors']}")

3. Query Building

# Configure query building
config = GuidedSearchConfig(
    enable_query_building=True,
    max_query_components=10,
    enable_auto_completion=True
)

assistant = GuidedSearchAssistant(config)

# Start query building
builder = await assistant.start_query_building(user_id="user123")

# Add components with auto-completion
await builder.add_topic("python", auto_complete=True)
await builder.add_intent("learn", auto_complete=True)
await builder.add_context("beginner", auto_complete=True)

# Get suggestions for next component
suggestions = await builder.get_suggestions("difficulty")
print(f"Suggestions: {suggestions}")

4. Error Detection

# Configure error detection
config = GuidedSearchConfig(
    enable_error_detection=True,
    error_types=["typos", "ambiguity", "vagueness", "complexity"]
)

assistant = GuidedSearchAssistant(config)

# Detect errors in query
error_analysis = await assistant.detect_errors("pythn tutoral", user_id="user123")

print("Error analysis:")
for error in error_analysis['errors']:
    print(f"- {error['type']}: {error['message']}")
    print(f"  Suggestion: {error['suggestion']}")

Integration Examples

1. Search Interface Integration

class SearchInterface:
    def __init__(self):
        self.guided_search = GuidedSearchAssistant(GuidedSearchConfig())
        self.query_builder = None
    
    async def on_query_change(self, query: str, user_id: str):
        """Handle query changes with guided assistance."""
        # Get assistance for current query
        assistance = await self.guided_search.get_assistance(query, user_id)
        
        # Show tips and suggestions
        return {
            "query": query,
            "assistance": assistance,
            "tips": assistance['search_tips'],
            "suggestions": assistance['query_suggestions']
        }
    
    async def start_query_building(self, user_id: str):
        """Start guided query building."""
        self.query_builder = await self.guided_search.start_query_building(user_id)
        return self.query_builder
    
    async def add_query_component(self, component: str, value: str):
        """Add component to query building."""
        if self.query_builder:
            await self.query_builder.add_component(component, value)
            return await self.query_builder.get_current_query()
        return None

2. Mobile App Integration

class MobileSearchInterface:
    def __init__(self):
        self.guided_search = GuidedSearchAssistant(GuidedSearchConfig())
        self.cache = {}
    
    async def get_assistance(self, query: str, user_id: str):
        """Get assistance optimized for mobile."""
        # Check cache first
        cache_key = f"{user_id}:{query}"
        if cache_key in self.cache:
            return self.cache[cache_key]
        
        # Get assistance
        assistance = await self.guided_search.get_assistance(query, user_id)
        
        # Limit tips for mobile
        mobile_assistance = {
            **assistance,
            'search_tips': assistance['search_tips'][:3]  # Limit to 3 tips
        }
        
        # Cache for performance
        self.cache[cache_key] = mobile_assistance
        return mobile_assistance

3. Voice Search Integration

class VoiceSearchInterface:
    def __init__(self):
        self.guided_search = GuidedSearchAssistant(GuidedSearchConfig())
    
    async def process_voice_input(self, transcribed_text: str, user_id: str):
        """Process voice input with guided assistance."""
        # Get assistance for transcribed text
        assistance = await self.guided_search.get_assistance(transcribed_text, user_id)
        
        # If query needs improvement, provide guidance
        if assistance['query_analysis']['needs_improvement']:
            return {
                "original": transcribed_text,
                "assistance": assistance,
                "needs_guidance": True,
                "suggestions": assistance['query_suggestions']
            }
        
        return {
            "original": transcribed_text,
            "assistance": assistance,
            "needs_guidance": False
        }

Performance Optimization

1. Caching

# Enable caching for better performance
config = GuidedSearchConfig(
    cache_enabled=True,
    cache_ttl_seconds=300,  # 5 minutes
    cache_max_size=1000     # Maximum cached entries
)

assistant = GuidedSearchAssistant(config)

2. Batch Processing

# Process multiple queries in batch
queries = ["python tutorial", "java course", "javascript guide"]
batch_assistance = await assistant.get_batch_assistance(queries, user_id="user123")

for query, assistance in batch_assistance.items():
    print(f"Query: {query}")
    print(f"Intent: {assistance['query_analysis']['intent']}")
    print(f"Tips: {[tip['title'] for tip in assistance['search_tips']]}")

3. Async Processing

# Process assistance asynchronously
async def process_assistance_async(queries: List[str], user_id: str):
    """Process multiple queries asynchronously."""
    tasks = [
        assistant.get_assistance(query, user_id) 
        for query in queries
    ]
    
    results = await asyncio.gather(*tasks)
    return dict(zip(queries, results))

Analytics and Monitoring

1. Track Assistance Performance

# Track assistance metrics
await assistant.track_assistance_metrics(
    query="python tutorial",
    assistance_provided=True,
    tips_shown=5,
    user_id="user123"
)

2. Monitor Performance

# Get performance metrics
metrics = await assistant.get_performance_metrics()

print("Guided search performance:")
print(f"Average response time: {metrics['avg_response_time_ms']}ms")
print(f"Cache hit rate: {metrics['cache_hit_rate']:.2%}")
print(f"Total assistance requests: {metrics['total_requests']}")
print(f"User satisfaction: {metrics['user_satisfaction']:.2f}")

3. A/B Testing

# Test different configurations
config_a = GuidedSearchConfig(max_tips=3)
config_b = GuidedSearchConfig(max_tips=5)

# Run A/B test
test_results = await assistant.run_ab_test(
    config_a, config_b, 
    test_duration_days=7
)

print("A/B test results:")
print(f"Config A satisfaction: {test_results['config_a']['satisfaction']:.2f}")
print(f"Config B satisfaction: {test_results['config_b']['satisfaction']:.2f}")

Troubleshooting

Common Issues

1. Slow Response Times

   • Enable caching
   • Reduce max_tips
   • Increase debounce_delay_ms

2. Irrelevant Assistance

   • Adjust scoring weights
   • Improve query analysis models
   • Add more contextual tips

3. Memory Usage

   • Reduce cache_max_size
   • Decrease history_retention_days
   • Use batch processing

Debug Mode

# Enable debug mode for troubleshooting
config = GuidedSearchConfig(debug=True)
assistant = GuidedSearchAssistant(config)

# Get detailed debug information
assistance = await assistant.get_assistance("python tutorial", user_id="user123")
print(f"Debug info: {assistance['debug_info']}")

Best Practices

1. Start Simple: Begin with basic configuration and add features gradually
2. Monitor Performance: Track response times and user satisfaction
3. Test Regularly: Use A/B testing to optimize assistance
4. Update Tips: Keep search tips current and relevant
5. Handle Errors: Implement proper error handling and fallbacks
6. Cache Strategically: Use caching to improve performance
7. Personalize Gradually: Start with basic personalization and enhance over time

Next Steps

• Learn about Auto-Complete
• Explore Search Suggestions
• Discover Voice Search
• Check out Analytics