Cleanup

src/app.py

@@ -14,13 +14,6 @@ from src.search.vector_search import (
     search_vector_with_reranking,
 )
 from src.data_prep.data_prep import load_clean_amazon_product_data
-from src.constants.code_snippets import (
-    CODE_STAGE_1,
-    CODE_STAGE_2,
-    CODE_STAGE_3,
-    CODE_STAGE_4,
-)
-
 
 _FILE_PATH = Path(__file__).parents[1]
 
@@ -268,11 +261,37 @@ def generate_comparison_table(all_metrics: List[Dict]) -> str:
 
     html += "\n---\n\n"
     html += "## Key Insights\n\n"
-    html += f"- **Top-1 Score** improves by **{top1_improvement:.0f}%** from baseline to final stage\n"
-    html += f"- **Top-5 Average** improves by **{top5_improvement:.0f}%** from baseline to final stage\n"
-    html += f"- **Latency** stays under **{max(m['latency_ms'] for m in all_metrics)}ms** maintaining fast performance\n"
-    html += "- Each stage progressively enhances search relevance while keeping response times low\n"
-    html += "- Vector embeddings provide the biggest jump in semantic understanding\n"
+    html += f"- **Relevance Improvement**: Top-1 score increases by **{top1_improvement:.0f}%**, Top-5 average by **{top5_improvement:.0f}%**\n"
+    html += f"- **Production-Ready Performance**: All stages complete in under **{max(m['latency_ms'] for m in all_metrics)}ms**\n"
+    html += "- **Semantic Understanding**: Vector embeddings provide the largest single improvement in search quality\n"
+    html += "- **Progressive Enhancement**: Each stage builds upon the previous, creating a robust pipeline\n"
+    html += "- **Real-World Applicability**: This architecture scales to millions of documents with proper infrastructure\n"
+
+    html += "\n\n---\n\n"
+    html += """
+<div style="background: #FFF7ED; border-left: 4px solid #F97316; padding: 20px; border-radius: 8px; margin-top: 24px;">
+    <h3 style="color: #C2410C; margin-top: 0; font-size: 1.2em;">
+        💡 Understanding Reranker Scores
+    </h3>
+    <p style="color: #7C2D12; font-size: 1.0em; line-height: 1.6; margin-bottom: 12px;">
+        <strong>Note:</strong> You may notice that reranking shows the <em>same cosine similarity scores</em> from Stage 2
+        despite improved result ordering. This is intentional and highlights an important concept:
+    </p>
+    <ul style="color: #7C2D12; font-size: 0.95em; line-height: 1.7; margin-left: 20px;">
+        <li><strong>Different ranking mechanisms:</strong> Cosine similarity measures vector distance in embedding space,
+        while rerankers use cross-encoder models that analyze query-document pairs directly for deeper semantic understanding.</li>
+        <li><strong>Why reranking works better:</strong> Cross-encoders examine token-level interactions between the query
+        and each document, capturing nuances that simple vector distance misses.</li>
+        <li><strong>The scores displayed:</strong> We preserve cosine scores to show that reranking <em>reorders</em> results
+        based on relevance, not similarity. A document with slightly lower cosine similarity might be more contextually relevant.</li>
+        <li><strong>Production best practice:</strong> Use fast vector search to retrieve candidates (~100-1000 results),
+        then apply computationally expensive reranking to the top results for maximum accuracy.</li>
+    </ul>
+    <p style="color: #7C2D12; font-size: 0.9em; margin-top: 12px; font-style: italic;">
+        This two-stage approach (retrieve + rerank) is the industry standard for building high-quality search systems at scale.
+    </p>
+</div>
+"""
 
     return html
 
@@ -376,6 +395,10 @@ with gr.Blocks(
                 """
             <h1 class="header-title" style="font-size: 2.5em; text-align: left;">Search Alchemy</h1>
             <p style="color: #64748B; font-size: 1.1em; margin-top: 0; text-align: left;">Building Production Search Pipelines with Fireworks AI</p>
+            <p style="color: #475569; font-size: 1.0em; line-height: 1.6; margin: 0;">
+            Four progressive stages demonstrating production-grade semantic search:
+            <strong>BM25</strong> → <strong>Vector Embeddings</strong> → <strong>Query Expansion</strong> → <strong>Reranking</strong>
+            </p>
             """
             )
         with gr.Row(elem_classes="compact-header"):
@@ -430,23 +453,15 @@ with gr.Blocks(
 
         with gr.Tab("Stage 1: BM25 Baseline"):
             stage1_output = gr.Markdown(label="Results")
-            with gr.Accordion("Show Code", open=False):
-                gr.Markdown(CODE_STAGE_1)
 
         with gr.Tab("Stage 2: + Vector Embeddings"):
             stage2_output = gr.Markdown(label="Results")
-            with gr.Accordion("Show Code", open=False):
-                gr.Markdown(CODE_STAGE_2)
 
         with gr.Tab("Stage 3: + Query Expansion"):
             stage3_output = gr.Markdown(label="Results")
-            with gr.Accordion("Show Code", open=False):
-                gr.Markdown(CODE_STAGE_3)
 
         with gr.Tab("Stage 4: + LLM Reranking"):
             stage4_output = gr.Markdown(label="Results")
-            with gr.Accordion("Show Code", open=False):
-                gr.Markdown(CODE_STAGE_4)
 
         with gr.Tab("Compare All Stages"):
             comparison_output = gr.Markdown(label="Comparison")

src/config.py

@@ -69,33 +69,35 @@ CUSTOM_CSS = """
 .result-card {
     background: white;
     border-radius: 12px;
-    padding: 16px;
-    margin: 8px 0;
-    box-shadow: 0 2px 4px rgba(103, 32, 255, 0.08);
+    padding: 18px;
+    margin: 10px 0;
+    box-shadow: 0 2px 6px rgba(103, 32, 255, 0.08);
     border: 1px solid #E6EAF4;
-    transition: all 0.2s ease;
+    transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
 }
 
 .result-card:hover {
-    box-shadow: 0 4px 12px rgba(103, 32, 255, 0.12);
+    transform: translateY(-2px);
+    box-shadow: 0 6px 16px rgba(103, 32, 255, 0.15);
     border-color: #C4B5FD;
 }
 
 .metric-box {
-    background: linear-gradient(to right, #F3F0FF, #FFFFFF);
-    border-left: 3px solid #6720FF;
-    padding: 12px;
+    background: linear-gradient(135deg, #F3F0FF 0%, #FFFFFF 100%);
+    border-left: 4px solid #6720FF;
+    padding: 16px;
     margin: 8px 0;
-    border-radius: 8px;
+    border-radius: 10px;
     font-size: 0.9em;
+    box-shadow: 0 2px 4px rgba(103, 32, 255, 0.05);
 }
 
 .code-section {
-    background: linear-gradient(to right, #F3F0FF, #FFFFFF);
-    border-left: 3px solid #6720FF;
-    padding: 16px;
+    background: linear-gradient(135deg, #F3F0FF 0%, #FFFFFF 100%);
+    border-left: 4px solid #6720FF;
+    padding: 18px;
     margin: 12px 0;
-    border-radius: 8px;
+    border-radius: 10px;
     font-family: 'JetBrains Mono', monospace;
     font-size: 0.9em;
 }
@@ -104,62 +106,76 @@ CUSTOM_CSS = """
     width: 100%;
     border-collapse: collapse;
     margin: 20px 0;
+    box-shadow: 0 2px 8px rgba(103, 32, 255, 0.08);
+    border-radius: 10px;
+    overflow: hidden;
 }
 
 .comparison-table th {
-    background: #6720FF;
+    background: linear-gradient(135deg, #6720FF 0%, #7B2FFF 100%);
     color: white;
-    padding: 12px;
+    padding: 14px;
     text-align: left;
     font-weight: 600;
+    text-transform: uppercase;
+    font-size: 0.85em;
+    letter-spacing: 0.5px;
 }
 
 .comparison-table td {
-    padding: 12px;
+    padding: 14px;
     border-bottom: 1px solid #E6EAF4;
+    background: white;
 }
 
-.comparison-table tr:hover {
-    background: #F3F0FF;
+.comparison-table tr:hover td {
+    background: #F8F7FF;
+}
+
+.comparison-table tr:last-child td {
+    border-bottom: none;
 }
 
 ::-webkit-scrollbar {
-    width: 8px;
-    height: 8px;
+    width: 10px;
+    height: 10px;
 }
 
 ::-webkit-scrollbar-track {
     background: #F3F0FF;
-    border-radius: 4px;
+    border-radius: 5px;
 }
 
 ::-webkit-scrollbar-thumb {
-    background: #C4B5FD;
-    border-radius: 4px;
+    background: linear-gradient(135deg, #C4B5FD 0%, #A78BFA 100%);
+    border-radius: 5px;
 }
 
 ::-webkit-scrollbar-thumb:hover {
-    background: #A78BFA;
+    background: linear-gradient(135deg, #A78BFA 0%, #8B5CF6 100%);
 }
 
 details {
     border: 1px solid #E6EAF4;
-    border-radius: 10px;
-    padding: 12px;
-    margin: 10px 0;
+    border-radius: 12px;
+    padding: 14px;
+    margin: 12px 0;
     background: white;
+    transition: all 0.3s ease;
 }
 
 details[open] {
-    border-color: #6720FF;
-    box-shadow: 0 4px 12px rgba(103, 32, 255, 0.15);
+    border-color: #C4B5FD;
+    box-shadow: 0 4px 16px rgba(103, 32, 255, 0.12);
 }
 
 summary {
     font-weight: 600;
     color: #6720FF;
     cursor: pointer;
-    padding: 4px;
+    padding: 6px;
+    user-select: none;
+    transition: color 0.2s ease;
 }
 
 summary:hover {
@@ -181,6 +197,26 @@ summary:hover {
     font-size: 0.85em;
     padding: 8px 12px;
 }
+
+/* Tab styling */
+.tabs button {
+    transition: all 0.2s ease;
+}
+
+.tabs button[aria-selected="true"] {
+    border-bottom: 3px solid #6720FF !important;
+}
+
+/* Button enhancements */
+button.primary {
+    background: linear-gradient(135deg, #6720FF 0%, #7B2FFF 100%) !important;
+    transition: all 0.3s ease !important;
+}
+
+button.primary:hover {
+    transform: translateY(-1px);
+    box-shadow: 0 4px 12px rgba(103, 32, 255, 0.25) !important;
+}
 """
 
 

src/constants/code_snippets.py

@@ -1,120 +0,0 @@
-"""
-Code snippets for displaying implementation examples in the Gradio UI.
-Each snippet shows the actual implementation approach for each search stage.
-"""
-
-CODE_STAGE_1 = """
-```python
-import bm25s
-import pandas as pd
-
-# Step 1: Create BM25 index (one-time setup)
-df = pd.read_parquet("data/amazon_products.parquet")
-corpus = df["FullText"].tolist()
-corpus_tokens = bm25s.tokenize(corpus, stopwords="en")
-
-retriever = bm25s.BM25()
-retriever.index(corpus_tokens)
-retriever.save("data/bm25_index")
-
-# Step 2: Load index and search
-bm25_index = bm25s.BM25.load("data/bm25_index", load_corpus=False)
-query_tokens = bm25s.tokenize(query, stopwords="en")
-results, scores = bm25_index.retrieve(query_tokens, k=5)
-
-# Extract top results
-top_products = [df.iloc[idx] for idx in results[0]]
-```
-"""
-
-CODE_STAGE_2 = """
-```python
-from openai import OpenAI
-import faiss
-import numpy as np
-
-# Initialize Fireworks AI client
-client = OpenAI(
-    api_key="your_fireworks_api_key",
-    base_url="https://api.fireworks.ai/inference/v1"
-)
-
-# Generate query embedding
-response = client.embeddings.create(
-    model="accounts/fireworks/models/qwen3-embedding-8b",
-    input=query
-)
-query_embedding = np.array(response.data[0].embedding, dtype=np.float32)
-query_vector = query_embedding.reshape(1, -1)
-
-# Normalize for cosine similarity using L2 distance
-faiss.normalize_L2(query_vector)
-
-# Load pre-built FAISS index
-index = faiss.read_index("data/faiss_index.bin")
-
-# Search for top-k similar documents
-distances, indices = index.search(query_vector, k=10)
-
-# Convert L2 distances to cosine similarity scores
-# After normalization: L2_distance = 2 * (1 - cosine_similarity)
-# So: cosine_similarity = 1 - (L2_distance / 2)
-similarity_scores = 1 - (distances[0] / 2)
-
-# Get top results
-top_results = [
-    {
-        "product": df.iloc[idx],
-        "score": float(score)
-    }
-    for idx, score in zip(indices[0], similarity_scores)
-]
-```
-"""
-
-CODE_STAGE_3 = """
-```python
-# Query expansion with LLM
-response = client.chat.completions.create(
-    model="accounts/fireworks/models/llama-v3p1-8b-instruct",
-    messages=[{
-        "role": "user",
-        "content": f"Extract 2-3 key search concepts from: {query}"
-    }]
-)
-
-expanded_query = response.choices[0].message.content
-
-# Search with expanded query
-response = client.embeddings.create(
-    model="accounts/fireworks/models/qwen3-embedding-8b",
-    input=[expanded_query] + documents
-)
-
-# Continue with embedding search...
-```
-"""
-
-CODE_STAGE_4 = """
-```python
-# First get top 20 candidates from Stage 3
-top_20_results = get_stage_3_results(query, k=20)
-
-# Rerank with Fireworks reranker
-rerank_response = client.post(
-    "https://api.fireworks.ai/inference/v1/rerank",
-    json={
-        "model": "fireworks/qwen3-reranker-8b",
-        "query": query,
-        "documents": [r["text"] for r in top_20_results],
-        "top_n": 5
-    }
-)
-
-# Get final ranked results
-final_results = [
-    top_20_results[r["index"]]
-    for r in rerank_response.json()["results"]
-]
-```
-"""