Skip to main content

Search Interface Quickstart

Get up and running with the Advanced Search Interface in just a few minutes. This guide will walk you through the essential setup and basic usage patterns.

Installation​

Prerequisites​

  • Python 3.8 or higher
  • pip package manager

Install the Package​

pip install search-interface

Install Optional Dependencies​

For voice search capabilities:

pip install speech-recognition pydub

For advanced analytics:

pip install scikit-learn pandas

Basic Setup​

1. Import Required Modules​

from search_interface import SearchInterface, SearchConfig
from search_interface.autocomplete import AutoCompleteEngine, AutoCompleteConfig
from search_interface.suggestions import SearchSuggestionsEngine, SuggestionConfig
from search_interface.analytics import SearchAnalytics, SearchAnalyticsConfig

2. Create Configuration​

# Main search interface configuration
config = SearchConfig(
    autocomplete_enabled=True,
    suggestions_enabled=True,
    voice_search_enabled=True,
    personalization_enabled=True,
    analytics_enabled=True,
    max_results=20,
    enable_highlighting=True,
    enable_snippets=True
)

# Auto-complete configuration
autocomplete_config = AutoCompleteConfig(
    use_query_history=True,
    use_popular_queries=True,
    use_domain_terms=True,
    max_suggestions=10,
    min_query_length=2
)

# Search suggestions configuration
suggestions_config = SuggestionConfig(
    use_related_queries=True,
    use_spelling_corrections=True,
    use_synonyms=True,
    max_suggestions=8
)

# Analytics configuration
analytics_config = SearchAnalyticsConfig(
    track_queries=True,
    track_clicks=True,
    track_suggestions=True,
    data_retention_days=90
)

3. Initialize Components​

# Create engine instances
autocomplete_engine = AutoCompleteEngine(autocomplete_config)
suggestions_engine = SearchSuggestionsEngine(suggestions_config)
analytics = SearchAnalytics(analytics_config)

# Create main search interface
search_interface = SearchInterface(
    config=config,
    autocomplete_engine=autocomplete_engine,
    suggestions_engine=suggestions_engine,
    analytics=analytics
)

Basic Usage​

1. Start a Search Session​

# Start a new search session
session_id = await search_interface.start_session("user123")
print(f"Started session: {session_id}")

2. Get Auto-Complete Suggestions​

# Get auto-complete suggestions as user types
partial_query = "python"
suggestions = await search_interface.get_autocomplete_suggestions(
    partial_query, session_id
)

print("Auto-complete suggestions:")
for suggestion in suggestions:
    print(f"- {suggestion.text} (confidence: {suggestion.confidence:.2f})")

3. Get Search Suggestions​

# Get contextual search suggestions
query = "python tutorial"
suggestions = await search_interface.get_search_suggestions(query, session_id)

print("Search suggestions:")
for suggestion in suggestions:
    print(f"- {suggestion.text} ({suggestion.suggestion_type})")
# Perform a search query
results = await search_interface.search(query, session_id)

print(f"Found {len(results)} results:")
for i, result in enumerate(results, 1):
    print(f"{i}. {result.title}")
    print(f"   Score: {result.score:.2f}")
    print(f"   Snippet: {result.snippet}")
    print()

5. Track User Interactions​

# Track result clicks for analytics
result_id = results[0].id
await search_interface.click_result(result_id, session_id)

# Track suggestion selections
if suggestions:
    await search_interface.select_suggestion(suggestions[0], session_id)

6. End the Session​

# End the search session
await search_interface.end_session(session_id)
print("Session ended")

Complete Example​

Here's a complete working example that demonstrates all the basic functionality:

import asyncio
from search_interface import SearchInterface, SearchConfig
from search_interface.autocomplete import AutoCompleteEngine, AutoCompleteConfig
from search_interface.suggestions import SearchSuggestionsEngine, SuggestionConfig
from search_interface.analytics import SearchAnalytics, SearchAnalyticsConfig

async def main():
    # Configuration
    config = SearchConfig(
        autocomplete_enabled=True,
        suggestions_enabled=True,
        analytics_enabled=True
    )
    
    autocomplete_config = AutoCompleteConfig()
    suggestions_config = SuggestionConfig()
    analytics_config = SearchAnalyticsConfig()
    
    # Initialize components
    autocomplete_engine = AutoCompleteEngine(autocomplete_config)
    suggestions_engine = SearchSuggestionsEngine(suggestions_config)
    analytics = SearchAnalytics(analytics_config)
    
    search_interface = SearchInterface(
        config=config,
        autocomplete_engine=autocomplete_engine,
        suggestions_engine=suggestions_engine,
        analytics=analytics
    )
    
    # Start session
    session_id = await search_interface.start_session("demo_user")
    print(f"Started session: {session_id}")
    
    # Simulate user typing and searching
    queries = ["python", "python tutorial", "python programming"]
    
    for query in queries:
        print(f"\n--- Searching for: {query} ---")
        
        # Get auto-complete suggestions
        suggestions = await search_interface.get_autocomplete_suggestions(
            query, session_id
        )
        print(f"Auto-complete suggestions: {[s.text for s in suggestions]}")
        
        # Get search suggestions
        search_suggestions = await search_interface.get_search_suggestions(
            query, session_id
        )
        print(f"Search suggestions: {[s.text for s in search_suggestions]}")
        
        # Perform search
        results = await search_interface.search(query, session_id)
        print(f"Found {len(results)} results")
        
        # Track interactions
        if results:
            await search_interface.click_result(results[0].id, session_id)
    
    # End session
    await search_interface.end_session(session_id)
    print("\nSession ended")

# Run the example
if __name__ == "__main__":
    asyncio.run(main())

Advanced Features​

# Start voice search
voice_result = await search_interface.start_voice_search(session_id)
print(f"Voice search started: {voice_result}")

# Process audio (in a real app, you'd get this from microphone)
# audio_data = get_audio_from_microphone()

# Stop voice search and get transcribed text
transcribed_text = await search_interface.stop_voice_search(session_id)
print(f"Transcribed: {transcribed_text}")

# Use transcribed text for search
if transcribed_text:
    results = await search_interface.search(transcribed_text, session_id)
from search_interface.guided_search import GuidedSearchAssistant, GuidedSearchConfig

# Initialize guided search
guided_config = GuidedSearchConfig(
    enable_intent_detection=True,
    enable_complexity_analysis=True
)
guided_search = GuidedSearchAssistant(guided_config)

# Get search assistance
assistance = await search_interface.get_guided_search_assistance(
    "how to learn python", session_id
)

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']]}")

Personalization​

from search_interface.personalization import SearchPersonalizationEngine, PersonalizationConfig

# Initialize personalization
personalization_config = PersonalizationConfig(
    learning_enabled=True,
    enable_result_reranking=True
)
personalization_engine = SearchPersonalizationEngine(personalization_config)

# Update user behavior
await personalization_engine.update_user_behavior(
    user_id="demo_user",
    query="python tutorial",
    clicked_results=["result1", "result2"]
)

# Get personalized suggestions
personalized_suggestions = await personalization_engine.get_personalized_suggestions(
    "python", session_id
)

Configuration Options​

SearchConfig​

config = SearchConfig(
    # Auto-complete settings
    autocomplete_enabled=True,
    autocomplete_min_length=2,
    autocomplete_max_suggestions=10,
    autocomplete_delay_ms=300,
    
    # Search suggestions
    suggestions_enabled=True,
    suggestions_max_count=8,
    suggestions_include_recent=True,
    suggestions_include_popular=True,
    
    # Search results
    max_results=20,
    enable_highlighting=True,
    enable_snippets=True,
    snippet_max_length=200,
    
    # Voice search
    voice_search_enabled=True,
    voice_language="en-US",
    voice_timeout_seconds=30,
    
    # Personalization
    personalization_enabled=True,
    learning_rate=0.1,
    history_retention_days=90,
    
    # Performance
    cache_enabled=True,
    cache_ttl_seconds=300,
    debounce_delay_ms=200,
    
    # Analytics
    analytics_enabled=True,
    track_clicks=True,
    track_queries=True,
    track_sessions=True
)

Error Handling​

import logging

# Set up logging
logging.basicConfig(level=logging.INFO)

async def safe_search(search_interface, query, session_id):
    """Safely perform search with error handling."""
    try:
        results = await search_interface.search(query, session_id)
        return results
    except Exception as e:
        logging.error(f"Search failed: {e}")
        return []

# Use safe search
results = await safe_search(search_interface, "python tutorial", session_id)

Next Steps​

Now that you have the basics working, explore these advanced topics:

  1. Auto-Complete Guide - Learn about intelligent auto-complete features
  2. Search Suggestions - Discover contextual suggestion capabilities
  3. Voice Search - Implement voice search functionality
  4. Personalization - Create personalized search experiences
  5. Analytics - Track and analyze search behavior
  6. A/B Testing - Test interface improvements
  7. Customization - Customize themes and layouts
  8. API Reference - Complete API documentation

Troubleshooting​

Common Issues​

  1. Import Errors: Make sure all dependencies are installed
  2. Database Errors: Check database connection and permissions
  3. Performance Issues: Review the Optimization Guide
  4. Voice Search Not Working: Install speech recognition dependencies

Getting Help​