Hotel Search Query Tuning - Elasticsearch Hybrid Search

This project provides a web-based interface for performing hybrid searches across hotel data in Elasticsearch, combining semantic search with traditional text matching.

Features

• Hybrid search across hotel data with:

  • E5 Semantic Search (dense embeddings)
  • ELSER Semantic Search (sparse embeddings)
  • Text Match across multiple fields

• Adjustable search component weights:

  • E5 Semantic Search
  • ELSER Semantic Search
  • Text Match

• AI Summary Chat: Intelligent explanations of search results with:

  • 🤖 "Query Advisor" button for each result with explain data
  • Resizable chat pane for follow-up questions
  • UI-aware recommendations for improving search performance
  • Context-aware guidance based on your search query

• Visual Score Breakdown: AI-generated visual explanations with:

  • 📊 "Visual Score Breakdown" button for each result with explain data
  • Interactive charts and progress bars showing score contributions
  • Color-coded field breakdowns and semantic model identification
  • Visual suggestions for improving search performance
  • Responsive HTML visualizations generated by AI

• Real-time search results with highlighting

• Modern, responsive UI built with Bootstrap

• Query visualization for debugging

• Optional semantic reranking

Prerequisites

• Python 3.11 or higher (for local development)
• Docker and Docker Compose (for containerized deployment)
• Elasticsearch cluster with the hotels index containing:
  • Hotel information (name, description, address, etc.)
  • Semantic embeddings (semantic_description_e5, semantic_description_elser)
  • Combined fields for reranking
• Azure OpenAI account (for AI Summary Chat feature):
  • OpenAI endpoint URL
  • API key
  • Model deployment (e.g., gpt-4o-global)

Quick Start with Docker (Recommended)

The easiest way to run this application is using Docker:

1. Clone the repository:

git clone https://github.com/yourusername/hotel-finder-query-constructor.git
cd hotel-finder-query-constructor

2. Set up environment variables:

cp variables.env.template variables.env

Edit variables.env with your Elasticsearch and OpenAI configuration:

ES_URL=https://your-cluster.region.elastic.co:9243
ES_API_KEY=your-api-key-here
ELSER_INFERENCE_ID=.elser-2-elasticsearch

# OpenAI/Azure Configuration for AI Summary Chat
OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
OPENAI_API_KEY=your-azure-openai-api-key-here
OPENAI_MODEL=gpt-4o-global
OPENAI_API_VERSION=2025-01-01-preview

3. Run the containerized application:

./run-container.sh

4. Access the application: Open your browser and go to http://localhost:8080

For detailed Docker instructions, see README-Docker.md.

Local Development Setup

If you prefer to run the application locally without Docker:

1. Clone the repository:

git clone https://github.com/yourusername/hotel-finder-query-constructor.git
cd hotel-finder-query-constructor

2. Create a variables.env file with your Elasticsearch and OpenAI configuration:

cat > variables.env << EOL
ES_URL=your_elasticsearch_url
ES_API_KEY=your_elasticsearch_api_key
ELSER_INFERENCE_ID=.elser-2-elasticsearch

# OpenAI/Azure Configuration for AI Summary Chat
OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
OPENAI_API_KEY=your-azure-openai-api-key-here
OPENAI_MODEL=gpt-4o-global
OPENAI_API_VERSION=2025-01-01-preview
EOL

Replace the placeholder values with your actual credentials.

Note: The variables.env file contains sensitive information and should not be committed to version control. It is automatically added to .gitignore.

3. Set up and activate the environment:

Run the following command to set up the Python virtual environment, install dependencies, validate your configuration, and activate the environment in your current shell:

source setup_env.sh

Important: You must use source setup_env.sh (not ./setup_env.sh) so that the virtual environment is activated in your current shell session.

When setup completes, your shell prompt should show (venv) indicating the environment is active.

Deactivate the Virtual Environment

When you're done, you can deactivate the virtual environment by running:

deactivate

Data Ingestion

Before using the UI, you must ingest hotel data into your Elasticsearch hotels index. Use your preferred ingestion method or script to populate the index as needed.

Note: The previous ingestion scripts (ingest.py, elasticsearch_ingest.py) have been removed. Please use your own ingestion process or contact the project maintainer for guidance.

Running the Application

With Docker (Recommended)

./run-container.sh

Access at: http://localhost:8080

Local Development

1. Start the Flask application:

python search_ui.py

2. Open your browser and navigate to http://127.0.0.1:5001

Usage

1. Enter your search query (hotel name, description, location, amenities, etc.)
2. Adjust the weights for different search components using the sliders:
   • E5 Semantic Search (default: 2.0)
   • ELSER Semantic Search (default: 1.5)
   • Text Match (default: 1.0)
3. Optionally enable semantic reranking with configurable parameters
4. Click "Search" or press Enter
5. View the results with highlighted matches
6. Click "Show Generated Query" to see the Elasticsearch query structure

AI Summary Chat Feature

For results with explain data enabled:

1. Click "🤖 Query Advisor" next to any result to open the AI chat pane
2. Read the AI summary explaining which document fields contributed most to the score
3. Ask follow-up questions like:
   • "How can I make the title field more important?"
   • "What weights should I adjust to improve this result?"
   • "Why did this result score higher than others?"
4. Get UI-specific recommendations based on the available tuning controls
5. Resize the chat pane by dragging the handle on the left edge
6. Close the chat when done to clear the session

The AI assistant understands all UI capabilities and provides actionable recommendations for:

• Weight adjustments (E5, ELSER, Text Match)
• Field boosts (title, description, features, etc.)
• Retriever type selection (Linear vs RRF)
• Location and price filtering
• Multi-match type configuration

Visual Score Breakdown Feature

For results with explain data enabled:

1. Click "📊 Visual Score Breakdown" next to any result to generate an AI-powered visual explanation
2. View interactive charts and progress bars showing how each field contributed to the score
3. See color-coded breakdowns for different types of matches (semantic vs keyword)
4. Get visual suggestions for improving search performance with specific UI adjustments
5. Identify which semantic models were used (E5, ELSER, or both)
6. Toggle between different explanation views (Summary, Visual, Raw JSON)

The visual breakdown includes:

• Overall score visualization with contributing factors
• Field-specific progress bars showing relative importance
• Semantic model identification and explanation
• Interactive suggestions for UI parameter adjustments
• Responsive design that works on all screen sizes

Search Fields

The search covers the following hotel fields:

• HotelName
• Description
• Address
• cityName
• HotelFacilities
• Attractions

Development

The project consists of two main components:

1. search_ui.py: Flask application handling the backend logic and AI chat integration
2. templates/index.html: Frontend interface with Bootstrap styling and resizable chat pane

Containerization

This project includes Docker support for easy deployment:

• Dockerfile: Multi-stage build for production-ready container
• docker-compose.yml: Easy orchestration with environment variables
• run-container.sh: Helper script for building and running
• README-Docker.md: Detailed Docker documentation