Initial commit: Explainable RAG system

.gitignore

@@ -0,0 +1,7 @@
+myenv/
+__pycache__/
+*.pyc
+.env
+data/
+processed/
+embeddings/

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 5000
+
+CMD ["bash", "-c", "\
+if [ ! -d embeddings ]; then \
+  echo 'Running setup...'; \
+  python src/ingestion/fetch_docs.py && \
+  python src/ingestion/chunk.py && \
+  python src/retrieval/embed_store.py; \
+fi && \
+python app.py"]

app.py

@@ -0,0 +1,210 @@
+import os
+import sys
+
+DEBUG = False  # ← set False to hide ALL noise
+
+os.environ["TRANSFORMERS_VERBOSITY"] = "error"
+os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+os.environ["HF_HUB_DISABLE_TELEMETRY"] = "1"
+
+import time
+import numpy as np
+from flask import Flask, render_template, request, jsonify
+from transformers import AutoTokenizer
+from sklearn.decomposition import PCA
+
+from src.retrieval.query import (
+    retrieve, embed_query, bm25_index, docs_all, metas_all,
+    mmr_from_embs, _session
+)
+from src.generation.generate import generate_answer, build_prompt, build_context
+
+class SuppressOutput:
+    def __enter__(self):
+        if not DEBUG:
+            self._stdout = sys.stdout
+            self._stderr = sys.stderr
+            sys.stdout = open(os.devnull, "w")
+            sys.stderr = open(os.devnull, "w")
+
+    def __exit__(self, *args):
+        if not DEBUG:
+            sys.stdout.close()
+            sys.stderr.close()
+            sys.stdout = self._stdout
+            sys.stderr = self._stderr
+
+app = Flask(__name__)
+
+with SuppressOutput():
+    _tokenizer = AutoTokenizer.from_pretrained("BAAI/bge-small-en-v1.5")
+
+
+# -----------------------------
+# BM25 IDF
+# -----------------------------
+def _build_idf(bm25):
+    return {term: max(0.0, float(val)) for term, val in bm25.idf.items()}
+
+_idf_map = _build_idf(bm25_index)
+_max_idf = max(_idf_map.values()) if _idf_map else 1.0
+
+
+# -----------------------------
+# PCA FIT
+# -----------------------------
+def _fit_pca(n_components=128):
+    import random
+    from sentence_transformers import SentenceTransformer
+
+    sample = random.sample(docs_all, min(200, len(docs_all)))
+
+    with SuppressOutput():
+        model = SentenceTransformer("BAAI/bge-small-en-v1.5")
+        embs = model.encode(sample, normalize_embeddings=True)
+
+    n_comp = min(n_components, embs.shape[0], embs.shape[1])
+    pca = PCA(n_components=n_comp)
+    pca.fit(embs)
+    return pca
+
+
+_pca = _fit_pca(128)
+
+
+# -----------------------------
+# ROUTES
+# -----------------------------
+@app.route("/")
+def home():
+    return render_template("index.html")
+
+
+@app.route("/analyze_query", methods=["POST"])
+def analyze_query():
+    data = request.json
+    query = data.get("query", "")
+
+    enc = _tokenizer(query, return_offsets_mapping=True)
+    input_ids = enc["input_ids"]
+    tokens_raw = _tokenizer.convert_ids_to_tokens(input_ids)
+
+    special = set(_tokenizer.all_special_tokens)
+    tokens = [
+        {"token": t, "id": int(i)}
+        for t, i in zip(tokens_raw, input_ids)
+        if t not in special
+    ]
+
+    for tok in tokens:
+        word = tok["token"].lstrip("##").lower()
+        raw_idf = _idf_map.get(word, 0.0)
+        tok["idf"] = round(raw_idf, 4)
+        tok["idf_normalized"] = round(raw_idf / _max_idf, 4) if _max_idf else 0.0
+
+    idf_vals = [t["idf"] for t in tokens]
+    avg_idf = round(sum(idf_vals) / len(idf_vals), 4) if idf_vals else 0.0
+    unique_toks = len({t["token"] for t in tokens})
+    complexity = round(min(1.0, (len(tokens) / 20) * 0.4 + (avg_idf / _max_idf) * 0.6), 3)
+
+    q_emb = embed_query(query)
+    projected = _pca.transform(q_emb.reshape(1, -1))[0]
+    p_min, p_max = projected.min(), projected.max()
+
+    normed = (
+        ((projected - p_min) / (p_max - p_min) * 2 - 1).tolist()
+        if p_max != p_min else [0.0] * len(projected)
+    )
+
+    return jsonify({
+        "tokens": tokens,
+        "embedding": [round(v, 4) for v in normed],
+        "stats": {
+            "token_count": len(tokens),
+            "unique_tokens": unique_toks,
+            "avg_idf": avg_idf,
+            "complexity": complexity,
+        }
+    })
+
+
+@app.route("/mmr_rerun", methods=["POST"])
+def mmr_rerun():
+    if _session["query_emb"] is None:
+        return jsonify({"error": "No active session. Run a query first."}), 400
+
+    data = request.json
+    lambda_param = float(data.get("lambda", 0.7))
+    lambda_param = max(0.0, min(1.0, lambda_param))
+
+    selected = mmr_from_embs(
+        _session["query_emb"],
+        _session["doc_indices"],
+        _session["embs"],
+        k=10,
+        lambda_param=lambda_param
+    )
+
+    return jsonify({
+        "selected_indices": selected,
+        "selected_local": [
+            _session["doc_indices"].index(s) for s in selected
+        ],
+        "lambda": lambda_param,
+    })
+
+
+@app.route("/ask", methods=["POST"])
+def ask():
+    data = request.json
+    query = data.get("query")
+
+    if DEBUG:
+        print(f"\n[API QUERY]: {query}\n")
+
+    t0 = time.perf_counter()
+    results, debug = retrieve(query)
+    t_retrieve = time.perf_counter() - t0
+
+    results = sorted(results, key=lambda x: (
+        x["meta"].get("chunk_id", 0),
+        x["meta"].get("global_chunk_id", 0)
+    ))
+
+    docs = [r["text"] for r in results]
+    metas = [r["meta"] for r in results]
+    raw_scores = [float(r["rerank_score"]) for r in results]
+
+    context = build_context(docs, metas, raw_scores)
+
+    t1 = time.perf_counter()
+    prompt = build_prompt(query, context)
+    answer = generate_answer(prompt)
+    t_llm = time.perf_counter() - t1
+
+    sources = [
+        {"title": meta.get("title", "Source"), "url": meta.get("url", "")}
+        for meta in metas
+    ]
+
+    stage_timings = debug.get("timings", {})
+    stage_timings["llm"] = round(t_llm * 1000)
+    stage_timings["total"] = round((t_retrieve + t_llm) * 1000)
+
+    return jsonify({
+        "answer": answer,
+        "sources": sources,
+        "chunks": docs,
+        "scores": raw_scores,
+        "raw_scores": raw_scores,
+        "debug": debug,
+        "timings": stage_timings
+    })
+
+
+# -----------------------------
+# RUN
+# -----------------------------
+if __name__ == "__main__":
+    app.run(debug=DEBUG)

requirements.txt

@@ -0,0 +1,11 @@
+flask
+numpy
+scikit-learn
+transformers
+sentence-transformers
+chromadb
+rank-bm25
+umap-learn
+requests
+beautifulsoup4
+tqdm

src/generation/generate.py

@@ -0,0 +1,115 @@
+import requests
+from src.retrieval.query import retrieve
+
+def build_prompt(query, context):
+    return f"""You are a helpful assistant. Answer using ONLY the context below. Do NOT use outside knowledge.
+
+### Context
+{context}
+
+### Question
+{query}
+
+### Instructions
+
+- Start directly with the answer. No introduction.
+- Use only information from the context.
+- Do NOT invent or modify commands beyond fixing formatting.
+
+---
+
+### Structure
+
+- If the question is conceptual or descriptive (e.g. "what is X", "explain X") → 
+  explain fully using all relevant information from the context. Cover features, 
+  use cases, and design principles if present. Do NOT use methods or numbered steps.
+
+- If there is ONE clear workflow → use numbered steps.
+
+- Only treat something as a separate method if the context explicitly presents it as a distinct approach to solving the same task.
+- Do NOT create methods from examples, helper classes, or unrelated concepts.
+- If the context describes only ONE workflow or approach, DO NOT create multiple methods.
+- In that case, use numbered steps instead.
+
+- If there are MULTIPLE valid ways to perform the task:
+  → group them into separate sections using:
+
+### Method 1 - Name
+### Method 2 - Name
+
+- Each method must be self-contained.
+- Do NOT mix commands from different methods.
+- Do NOT merge all methods into one numbered list.
+
+---
+
+### Code Rules
+
+- All commands MUST be inside fenced code blocks.
+- Use:
+  - ```bash for shell commands
+  - ```python for Python code
+
+- Commands must be valid and executable.
+
+- Fix formatting issues:
+  - Merge broken tokens (". env" → ".env")
+  - Fix paths ("source . env /bin/activate" → "source .env/bin/activate")
+  - Split combined commands into separate lines
+
+- NEVER:
+  - put multiple commands on the same line
+  - leave commands outside code blocks
+  - use inline code blocks like ```bash command```
+
+---
+
+### Output Requirements
+
+- Output must be clean, valid markdown.
+- Code blocks must render correctly.
+
+### Answer
+"""
+
+import requests
+import os
+
+def generate_answer(prompt, model="llama-3.1-8b-instant"):
+    response = requests.post(
+        "https://api.groq.com/openai/v1/chat/completions",
+        headers={
+            "Authorization": f"Bearer {"API_KEY"}",
+            "Content-Type": "application/json"
+        },
+        json={
+            "model": model,
+            "max_tokens": 2048,
+            "messages": [
+                {"role": "user", "content": prompt}
+            ],
+            "temperature": 0
+        }
+    )
+    data = response.json()
+    print("GROQ RESPONSE:", data) 
+
+    return response.json()["choices"][0]["message"]["content"]
+
+def build_context(docs, metas, scores):
+    context = ""
+
+    for i, (doc, meta, score) in enumerate(zip(docs, metas, scores)):
+        context += f"""
+                [Source {i+1} | Score: {round(score, 3)} | {meta.get('url', 'N/A')}]
+                Title: {meta.get("title", "N/A")}
+
+                {doc}
+
+                {"-"*50}
+                """
+    return context
+
+
+
+

src/ingestion/chunk.py

@@ -0,0 +1,177 @@
+import re
+import json
+from tqdm import tqdm
+
+
+CHUNK_SIZE = 300   
+OVERLAP = 50    
+MIN_CHUNK_WORDS = 30 
+
+def split_by_headings(text: str) -> list[str]:
+
+    heading_re = re.compile(r'(?:^|\n)(?=\n?[A-Z][^\n]{2,80}\n)')
+
+    candidate_positions = [m.start() for m in heading_re.finditer(text)]
+
+    safe_positions = [0]
+    in_fence = False
+    fence_re = re.compile(r'```')
+    fence_positions = [m.start() for m in fence_re.finditer(text)]
+    fence_idx = 0
+
+    for pos in candidate_positions:
+        if pos == 0:
+            continue
+        while fence_idx < len(fence_positions) and fence_positions[fence_idx] < pos:
+            in_fence = not in_fence
+            fence_idx += 1
+        if not in_fence:
+            safe_positions.append(pos)
+
+    safe_positions.append(len(text))
+    sections = []
+    for i in range(len(safe_positions) - 1):
+        chunk = text[safe_positions[i]:safe_positions[i + 1]].strip()
+        if chunk:
+            sections.append(chunk)
+
+    return sections if sections else [text.strip()]
+
+def split_section_into_parts(section: str) -> list[dict]:
+   
+    parts = []
+    segments = re.split(r'(```[\s\S]*?```)', section)
+
+    for seg in segments:
+        seg = seg.strip()
+        if not seg:
+            continue
+        if seg.startswith("```"):
+            parts.append({'type': 'code', 'content': seg})
+        else:
+            sentences = re.split(r'(?<=[.!?])\s+', seg)
+            for sent in sentences:
+                sent = sent.strip()
+                if sent:
+                    parts.append({'type': 'text', 'content': sent})
+    return parts
+
+
+def chunk_section(section: str, chunk_size: int = CHUNK_SIZE, overlap: int = OVERLAP) -> list[str]:
+    parts = split_section_into_parts(section)
+
+    chunks: list[str] = []
+    current_parts: list[dict] = []   
+    current_words = 0
+
+    def flush(current_parts: list[dict]) -> list[str]:
+        text = "\n\n".join(p['content'] for p in current_parts).strip()
+        return text
+
+    def word_count(s: str) -> int:
+        return len(s.split())
+
+    for part in parts:
+        wc = word_count(part['content'])
+        if part['type'] == 'code':
+            if current_words + wc > chunk_size and current_parts:
+                chunks.append(flush(current_parts))
+                current_parts = []
+                current_words = 0
+
+            current_parts.append(part)
+            current_words += wc
+
+            if current_words >= chunk_size:
+                chunks.append(flush(current_parts))
+                current_parts = []
+                current_words = 0
+
+            continue
+
+        if current_words + wc > chunk_size and current_parts:
+            chunks.append(flush(current_parts))
+
+            overlap_parts: list[dict] = []
+            overlap_words = 0
+            for prev in reversed(current_parts):
+                if prev['type'] == 'code':
+                    pw = word_count(prev['content'])
+                if overlap_words + pw > overlap:
+                    break
+                overlap_parts.insert(0, prev)
+                overlap_words += pw
+
+            current_parts = overlap_parts
+            current_words = overlap_words
+
+        current_parts.append(part)
+        current_words += wc
+
+    if current_parts:
+        chunks.append(flush(current_parts))
+
+    return chunks
+
+def hybrid_chunk(doc: dict) -> list[str]:
+    sections = split_by_headings(doc["text"])
+    final_chunks: list[str] = []
+
+    for section in sections:
+        chunks = chunk_section(section)
+        final_chunks.extend(chunks)
+
+    return final_chunks
+
+def chunk_documents(input_path="data/docs.json", output_path="processed/chunks.json"):
+    print("[INFO] Loading documents...\n")
+
+    with open(input_path, "r") as f:
+        docs = json.load(f)
+
+    print(f"[INFO] Loaded {len(docs)} documents\n")
+
+    all_chunks = []
+    global_id = 0
+
+    for doc in tqdm(docs, desc="Chunking documents"):
+        chunks = hybrid_chunk(doc)
+
+        chunks = [c for c in chunks if len(c.split()) >= MIN_CHUNK_WORDS]
+
+        print(f"[DEBUG] {doc['metadata']['title']} → {len(chunks)} chunks")
+
+        for local_id, chunk in enumerate(chunks):
+            text = chunk.strip()
+            if not text:
+                continue
+
+            if text.count("```") % 2 != 0:
+                text += "\n```"
+
+            all_chunks.append({
+                "text": text,
+                "metadata": {
+                    **doc["metadata"],
+                    "chunk_id": local_id,
+                    "global_chunk_id": global_id
+                }
+            })
+
+            global_id += 1
+
+    wc_list = [len(c["text"].split()) for c in all_chunks]
+    print(f"\n[INFO] Total chunks created: {len(all_chunks)}")
+    if wc_list:
+        print(f"[INFO] Word count — min: {min(wc_list)}, max: {max(wc_list)}, "
+              f"mean: {sum(wc_list)//len(wc_list)}, "
+              f"median: {sorted(wc_list)[len(wc_list)//2]}")
+
+    with open(output_path, "w") as f:
+        json.dump(all_chunks, f, indent=2)
+
+    print(f"[SUCCESS] Saved to {output_path}")
+
+
+if __name__ == "__main__":
+    chunk_documents()

src/ingestion/clean.py

@@ -0,0 +1,21 @@
+import re
+
+
+def normalize_text(text: str) -> str:
+    text = re.sub(r'\r\n?', '\n', text)
+    text = re.sub(r'\.\s+([a-zA-Z0-9])', r'.\1', text)
+    text = re.sub(r'(\w)\s*/\s*(\w)', r'\1/\2', text)
+    text = re.sub(r'[ \t]+', ' ', text)
+    text = re.sub(r'\s*```\s*', '\n```\n', text)
+    text = re.sub(r'(?<!\n)(uv pip install)', r'\n\1', text)
+    text = re.sub(r'\n{3,}', '\n\n', text)
+    return text.strip()
+
+
+def clean_text(text: str) -> str:
+    text = re.sub(r'[ \t]+', ' ', text)
+    text = re.sub(r'\n\s*\n+', '\n\n', text)
+    text = text.replace('\xa0', ' ')
+    text = re.sub(r'\n{3,}', '\n\n', text)
+    text = normalize_text(text)   
+    return text.strip()

src/ingestion/fetch_docs.py

@@ -0,0 +1,178 @@
+import sys
+import os
+from pathlib import Path
+
+sys.path.insert(0, os.path.dirname(__file__))
+
+import requests
+from bs4 import BeautifulSoup
+import json
+import time
+from tqdm import tqdm
+from clean import clean_text
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+DOCS_OUTPUT  = PROJECT_ROOT / "data" / "docs.json"
+
+URLS = [
+    "https://huggingface.co/docs/transformers/index/",
+    "https://huggingface.co/docs/transformers/installation/",
+    "https://huggingface.co/docs/transformers/quicktour/",
+    "https://huggingface.co/docs/transformers/weightconverter",
+    "https://huggingface.co/docs/transformers/models",
+    "https://huggingface.co/docs/transformers/custom_models",
+    "https://huggingface.co/docs/transformers/monkey_patching",
+    "https://huggingface.co/docs/transformers/fusion_mapping",
+    "https://huggingface.co/docs/transformers/how_to_hack_models",
+    "https://huggingface.co/docs/transformers/model_sharing",
+    "https://huggingface.co/docs/transformers/serialization"
+]
+
+
+def normalize_code_block(code: str) -> str:
+    lines = code.split("\n")
+    stripped = [l.rstrip() for l in lines]
+
+    # Drop leading/trailing blank lines
+    while stripped and not stripped[0]:
+        stripped.pop(0)
+    while stripped and not stripped[-1]:
+        stripped.pop()
+
+    if not stripped:
+        return ""
+
+    def fix_python_spacing(s: str) -> str:
+        import re
+        s = re.sub(r'\s*\(\s*', '(', s)
+        s = re.sub(r'\s*\)\s*', ')', s)
+        s = re.sub(r'\s*\[\s*', '[', s)
+        s = re.sub(r'\s*\]\s*', ']', s)
+        s = re.sub(r'\s*,\s*', ', ', s)
+        s = re.sub(r'\s*:\s*', ': ', s)
+        s = re.sub(r'\s*=\s*', '=', s)
+        s = re.sub(r'([^=!<>])=([^=])', r'\1 = \2', s)
+        s = re.sub(r'==', ' == ', s)
+        s = re.sub(r'!=', ' != ', s)
+        s = re.sub(r'  +', ' ', s)
+        return s.strip()
+
+    if len(stripped) <= 4 and all(len(l.split()) <= 4 for l in stripped if l):
+        joined = " ".join(l for l in stripped if l)
+        return joined
+
+    fixed = []
+    for line in stripped:
+        fixed.append(fix_python_spacing(line))
+    return "\n".join(fixed)
+
+
+def extract_main_text(soup):
+    main = soup.find("main")
+    if not main:
+        return ""
+
+    for tag in main.find_all(["nav", "footer", "aside", "script", "style"]):
+        tag.decompose()
+
+    for tag in main.find_all(True):
+        if tag.get_text(" ", strip=True).startswith("and get access to the augmented"):
+            tag.decompose()
+            break
+
+    texts = []
+
+    for tag in main.find_all(["h1", "h2", "h3", "p", "li", "pre"]):
+
+        if tag.name == "pre":
+            code_tag = tag.find("code")
+            raw = (code_tag or tag).get_text("\n")  
+
+            lang = ""
+            cls = (code_tag or tag).get("class", [])
+            for c in cls:
+                if c.startswith("language-"):
+                    lang = c.replace("language-", "")
+                    break
+
+            normalized = normalize_code_block(raw)
+            if not normalized or len(normalized.strip()) < 3:
+                continue
+
+            texts.append(f"\n```{lang}\n{normalized}\n```\n")
+            continue
+
+        content = tag.get_text(" ", strip=True)
+
+        if len(content) < 30:
+            continue
+
+        if tag.name in ["h1", "h2", "h3"]:
+            texts.append(f"\n{content}\n")
+        elif tag.name == "li":
+            texts.append(f"- {content}")
+        else:
+            texts.append(content)
+
+    return "\n\n".join(texts)
+
+
+def process_url(url, retries=3):
+    headers = {"User-Agent": "Mozilla/5.0 (compatible; RAG-doc-fetcher/1.0)"}
+
+    for attempt in range(retries):
+        try:
+            response = requests.get(url, timeout=10, headers=headers)
+            response.raise_for_status()
+
+            print(f"[SUCCESS] Fetched: {url} (Attempt {attempt+1})\n")
+
+            soup = BeautifulSoup(response.text, "html.parser")
+
+            text = extract_main_text(soup)
+            cleaned = clean_text(text)
+
+            title = soup.title.string if soup.title else "No Title"
+
+            return {
+                "text": cleaned,
+                "metadata": {
+                    "source": "huggingface",
+                    "url": url,
+                    "title": title
+                }
+            }
+
+        except requests.RequestException as e:
+            print(f"[Attempt {attempt+1}/{retries}] Failed: {url}")
+            print(f"Error: {e}")
+
+            if attempt < retries - 1:
+                print("Waiting 5 seconds before retry...\n")
+                time.sleep(5)
+            else:
+                print(f"[FAILED] All retries failed for: {url}\n")
+                return None
+
+
+def main():
+    docs = []
+
+    for i, url in enumerate(tqdm(URLS, desc="Processing URLs")):
+        doc = process_url(url)
+
+        if doc and doc["text"].strip():   
+            docs.append(doc)
+
+        if i < len(URLS) - 1:
+            time.sleep(0.75)
+
+    DOCS_OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    with open(DOCS_OUTPUT, "w") as f:
+        json.dump(docs, f, indent=2)
+
+    print(f"Saved {len(docs)} docs to {DOCS_OUTPUT}")
+
+
+if __name__ == "__main__":
+    main()

src/retrieval/embed_store.py

@@ -0,0 +1,42 @@
+import json
+from tqdm import tqdm
+from sentence_transformers import SentenceTransformer
+from chromadb import PersistentClient
+
+model = SentenceTransformer("BAAI/bge-small-en-v1.5")
+
+client = PersistentClient(path="embeddings/")
+collection = client.get_or_create_collection(name="rag_docs")
+
+
+def embed_and_store(input_path="processed/chunks.json"):
+    with open(input_path, "r") as f:
+        chunks = json.load(f)
+
+    documents, metadatas, ids = [], [], []
+
+    for i, chunk in enumerate(tqdm(chunks)):
+        documents.append("passage: " + chunk["text"])
+        metadatas.append(chunk["metadata"])
+        ids.append(f"chunk_{i}")
+
+    client.delete_collection(name="rag_docs")
+    collection = client.get_or_create_collection(name="rag_docs")       
+
+    embeddings = model.encode(
+        documents,
+        batch_size=32,
+        normalize_embeddings=True,
+        show_progress_bar=True
+    )
+
+    collection.add(
+        documents=documents,
+        metadatas=metadatas,
+        ids=ids,
+        embeddings=embeddings.tolist()
+    )
+
+
+if __name__ == "__main__":
+    embed_and_store()

src/retrieval/preprocess.py

@@ -0,0 +1,8 @@
+from nltk.stem import WordNetLemmatizer
+from nltk.tokenize import word_tokenize
+
+lemmatizer = WordNetLemmatizer()
+
+def preprocess(text):
+    tokens = word_tokenize(text.lower())
+    return [lemmatizer.lemmatize(t) for t in tokens]

src/retrieval/query.py

@@ -0,0 +1,264 @@
+import re
+import time
+import numpy as np
+from sentence_transformers import SentenceTransformer, CrossEncoder
+from chromadb import PersistentClient
+from functools import lru_cache
+from rank_bm25 import BM25Okapi
+
+# ------------------ MODELS ------------------
+embed_model = SentenceTransformer("BAAI/bge-small-en-v1.5")
+reranker    = CrossEncoder("cross-encoder/ms-marco-MiniLM-L-6-v2")
+
+# ------------------ DB ------------------
+client     = PersistentClient(path="embeddings/")
+collection = client.get_collection(name="rag_docs")
+
+data      = collection.get(include=["documents", "metadatas"])
+docs_all  = data["documents"]
+metas_all = data["metadatas"]
+ids_all   = data["ids"]
+
+# ------------------ BM25 INDEX ------------------
+def tokenize(text: str) -> list[str]:
+    return re.findall(r"\w+", text.lower())
+
+bm25_corpus = [tokenize(doc) for doc in docs_all]
+bm25_index  = BM25Okapi(bm25_corpus)
+
+def bm25_search(query: str, top_n: int = 25) -> list[tuple[int, float]]:
+    tokens     = tokenize(query)
+    raw_scores = bm25_index.get_scores(tokens)
+    max_s, min_s = raw_scores.max(), raw_scores.min()
+    norm = (raw_scores - min_s) / (max_s - min_s) if max_s != min_s else np.zeros_like(raw_scores)
+    top_indices = np.argsort(norm)[::-1][:top_n]
+    return [(int(i), float(norm[i])) for i in top_indices]
+
+# ------------------ EMBEDDING ------------------
+@lru_cache(maxsize=128)
+def embed_query(query: str):
+    return embed_model.encode("query: " + query, normalize_embeddings=True)
+
+# ------------------ HYBRID FUSION ------------------
+def hybrid_fusion(vector_indices, vector_scores, bm25_results, alpha=0.5, top_n=25):
+    vec_map  = dict(zip(vector_indices, vector_scores))
+    bm25_map = dict(bm25_results)
+    fused = [
+        (idx, vec_map.get(idx, 0.0), bm25_map.get(idx, 0.0),
+         alpha * vec_map.get(idx, 0.0) + (1 - alpha) * bm25_map.get(idx, 0.0))
+        for idx in set(vec_map) | set(bm25_map)
+    ]
+    fused.sort(key=lambda x: x[3], reverse=True)
+    return fused[:top_n]
+
+# ------------------ MMR ------------------
+def mmr(query_emb, doc_indices, k=10, lambda_param=0.7):
+    embs = [
+        np.array(collection.get(ids=[ids_all[i]], include=["embeddings"])["embeddings"][0])
+        for i in doc_indices
+    ]
+    embs      = [e / np.linalg.norm(e) for e in embs]
+    query_emb = query_emb / np.linalg.norm(query_emb)
+    sims      = [np.dot(query_emb, e) for e in embs]
+
+    best_idx = int(np.argmax(sims))
+    selected = [doc_indices[best_idx]]
+    sel_idx  = [best_idx]
+    mmr_debug = []
+
+    while len(selected) < min(k, len(doc_indices)):
+        scores = [
+            (lambda_param * sims[i] - (1 - lambda_param) * max(np.dot(embs[i], embs[j]) for j in sel_idx),
+             i, sims[i], max(np.dot(embs[i], embs[j]) for j in sel_idx))
+            for i in range(len(doc_indices)) if i not in sel_idx
+        ]
+        if not scores:
+            break
+        _, idx, rel, div = max(scores)
+        selected.append(doc_indices[idx])
+        sel_idx.append(idx)
+        mmr_debug.append({
+            "doc_index":         doc_indices[idx],
+            "relevance":         float(rel),
+            "diversity_penalty": float(div),
+        })
+
+    return selected, mmr_debug
+
+# ------------------ MMR (rerun with cached embs) ------------------
+def mmr_from_embs(query_emb, doc_indices, embs, k=10, lambda_param=0.7):
+    """Same as mmr() but uses pre-fetched embeddings — for fast lambda slider reruns."""
+    embs_n    = [e / np.linalg.norm(e) for e in embs]
+    query_emb = query_emb / np.linalg.norm(query_emb)
+    sims      = [np.dot(query_emb, e) for e in embs_n]
+
+    best_idx = int(np.argmax(sims))
+    selected = [doc_indices[best_idx]]
+    sel_idx  = [best_idx]
+
+    while len(selected) < min(k, len(doc_indices)):
+        scores = [
+            (lambda_param * sims[i] - (1 - lambda_param) * max(np.dot(embs_n[i], embs_n[j]) for j in sel_idx),
+             i, sims[i], max(np.dot(embs_n[i], embs_n[j]) for j in sel_idx))
+            for i in range(len(doc_indices)) if i not in sel_idx
+        ]
+        if not scores:
+            break
+        _, idx, rel, div = max(scores)
+        selected.append(doc_indices[idx])
+        sel_idx.append(idx)
+
+    return selected
+
+# ------------------ RERANK ------------------
+def rerank(query, doc_indices, top_k=7):
+    docs   = [docs_all[i] for i in doc_indices]
+    pairs  = [[query, doc] for doc in docs]
+    scores = reranker.predict(pairs)
+    s_arr  = np.array(scores, dtype=float)
+    if s_arr.max() != s_arr.min():
+        s_arr = (s_arr - s_arr.min()) / (s_arr.max() - s_arr.min())
+    else:
+        s_arr = np.ones_like(s_arr)
+    scored = sorted(zip(doc_indices, s_arr.tolist()), key=lambda x: x[1], reverse=True)
+    return scored[:top_k], scored
+
+_session = {
+    "query_emb":    None,   # np.ndarray
+    "doc_indices":  None,   # list[int]
+    "embs":         None,   # list[np.ndarray]  — raw (not normalized)
+    "sims":         None,   # list[float] query-doc cosine sims
+    "umap_coords":  None,   # list[[x,y]] — computed once per query
+    "sim_matrix":   None,   # NxN similarity matrix between candidates
+}
+
+def _compute_umap(embs_norm):
+    try:
+        import umap
+        n = len(embs_norm)
+        n_neighbors = min(5, n - 1)
+        reducer = umap.UMAP(n_components=2, n_neighbors=n_neighbors,
+                            min_dist=0.1, random_state=42, verbose=False)
+        coords = reducer.fit_transform(np.array(embs_norm))
+        for dim in range(2):
+            mn, mx = coords[:, dim].min(), coords[:, dim].max()
+            if mx != mn:
+                coords[:, dim] = (coords[:, dim] - mn) / (mx - mn)
+        return coords.tolist()
+    except Exception as e:
+        print(f"[UMAP] Failed: {e}")
+        return None
+
+def _compute_sim_matrix(embs_norm):
+    mat = np.array(embs_norm)
+    sim = mat @ mat.T
+    return np.clip(sim, -1, 1).tolist()
+
+RERANK_THRESHOLD = 0.3
+HYBRID_ALPHA     = 0.7
+
+def retrieve(query, top_k=7):
+    print(f"\n🔍 Query: {query}")
+    timings = {}
+
+    # --- EMBED ---
+    t = time.perf_counter()
+    query_emb = embed_query(query)
+    timings["embed"] = round((time.perf_counter() - t) * 1000)
+
+    # --- VECTOR SEARCH ---
+    t = time.perf_counter()
+    results        = collection.query(query_embeddings=[query_emb.tolist()], n_results=25)
+    vector_ids     = results["ids"][0]
+    vector_dists   = results["distances"][0]
+    vector_scores  = [1 - d for d in vector_dists]
+    vector_indices = [ids_all.index(i) for i in vector_ids]
+    timings["vector"] = round((time.perf_counter() - t) * 1000)
+    print(f"[Vector Search] Retrieved: {len(vector_indices)} chunks")
+
+    # --- BM25 ---
+    t = time.perf_counter()
+    bm25_results = bm25_search(query, top_n=25)
+    timings["bm25"] = round((time.perf_counter() - t) * 1000)
+    print(f"[BM25] Retrieved: {len(bm25_results)} chunks")
+
+    # --- HYBRID FUSION ---
+    t = time.perf_counter()
+    fused          = hybrid_fusion(vector_indices, vector_scores, bm25_results, alpha=HYBRID_ALPHA)
+    hybrid_indices = [idx for idx, _, _, _ in fused]
+    score_lookup   = {idx: (vs, bs, hs) for idx, vs, bs, hs in fused}
+    timings["hybrid"] = round((time.perf_counter() - t) * 1000)
+    print(f"[Hybrid] Fused: {len(hybrid_indices)} chunks")
+
+    # --- FETCH EMBEDDINGS for MMR + cache  ---
+    t = time.perf_counter()
+    raw_embs = [
+        np.array(collection.get(ids=[ids_all[i]], include=["embeddings"])["embeddings"][0])
+        for i in hybrid_indices
+    ]
+    embs_norm = [e / np.linalg.norm(e) for e in raw_embs]
+    query_emb_n = query_emb / np.linalg.norm(query_emb)
+    sims = [float(np.dot(query_emb_n, e)) for e in embs_norm]
+
+    # --- MMR ---
+    mmr_selected = mmr_from_embs(query_emb, hybrid_indices, raw_embs, k=10)
+    mmr_debug = []
+    timings["mmr"] = round((time.perf_counter() - t) * 1000)
+    print(f"[MMR] Selected: {len(mmr_selected)} chunks")
+
+    # --- CACHE session  ---
+    umap_coords = _compute_umap(embs_norm)
+    sim_matrix  = _compute_sim_matrix(embs_norm)
+
+    _session["query_emb"]   = query_emb
+    _session["doc_indices"] = hybrid_indices
+    _session["embs"]        = raw_embs
+    _session["sims"]        = sims
+    _session["umap_coords"] = umap_coords
+    _session["sim_matrix"]  = sim_matrix
+
+    # --- RERANK ---
+    t = time.perf_counter()
+    top_final, full_rerank = rerank(query, mmr_selected, top_k)
+    top_final = [(i, score) for i, score in top_final if score >= RERANK_THRESHOLD]
+    timings["rerank"] = round((time.perf_counter() - t) * 1000)
+    print(f"[Reranker] Selected: {len(top_final)} chunks (threshold: {RERANK_THRESHOLD})")
+
+    # --- OUTPUT ---
+    final = [
+        {
+            "text":         docs_all[i].replace("passage: ", ""),
+            "meta":         metas_all[i],
+            "rerank_score": float(score),
+            "vector_score": score_lookup.get(i, (0, 0, 0))[0],
+            "bm25_score":   score_lookup.get(i, (0, 0, 0))[1],
+            "hybrid_score": score_lookup.get(i, (0, 0, 0))[2],
+        }
+        for i, score in top_final
+    ]
+
+    # --- MMR without diversity (pure relevance) ---
+    no_mmr_selected = [
+        hybrid_indices[i] for i in np.argsort(sims)[::-1][:10]
+    ]
+
+    debug_info = {
+        "vector_count":    len(vector_indices),
+        "bm25_count":      len(bm25_results),
+        "hybrid_count":    len(hybrid_indices),
+        "mmr_count":       len(mmr_selected),
+        "rerank_count":    len(top_final),
+        "mmr_details":     mmr_debug,
+        "mmr_selected":    mmr_selected,
+        "no_mmr_selected": no_mmr_selected,
+        "rerank_full":     full_rerank,
+        "score_lookup":    {str(k): v for k, v in score_lookup.items()},
+        "timings":         timings,
+        "umap_coords":     umap_coords,
+        "sim_matrix":      sim_matrix,
+        "doc_indices":     hybrid_indices,
+        "sims":            sims,
+        "doc_previews":    [docs_all[i][:80].replace("passage: ", "") for i in hybrid_indices],
+    }
+
+    return final, debug_info

src/retrieval/test.py

@@ -0,0 +1,13 @@
+from query import retrieve
+
+if __name__ == "__main__":
+    q = "how to install transformers"
+    results, debug = retrieve(q)
+
+    for i, r in enumerate(results):
+        print(f"\n--- Result {i+1} ---")
+        print("Score:", r["rerank_score"])
+        print(r["text"][:300])
+
+    print("\n--- DEBUG INFO ---")
+    print(debug)

static/main.js

@@ -0,0 +1,240 @@
+function idfColor(n) {
+    const stops = [
+        { t: 0.0, r: 148, g: 163, b: 184 }, { t: 0.3, r: 99, g: 102, b: 241 },
+        { t: 0.7, r: 139, g: 92, b: 246 }, { t: 1.0, r: 236, g: 72, b: 153 }
+    ];
+    const v = Math.max(0, Math.min(1, n));
+    let lo = stops[0], hi = stops[stops.length - 1];
+    for (let i = 0; i < stops.length - 1; i++) {
+        if (v >= stops[i].t && v <= stops[i + 1].t) { lo = stops[i]; hi = stops[i + 1]; break; }
+    }
+    const t2 = lo.t === hi.t ? 0 : (v - lo.t) / (hi.t - lo.t);
+    return `rgb(${Math.round(lo.r + (hi.r - lo.r) * t2)},${Math.round(lo.g + (hi.g - lo.g) * t2)},${Math.round(lo.b + (hi.b - lo.b) * t2)})`;
+}
+
+function heatmapColor(v) {
+    if (v >= 0) { const i = Math.round(v * 255); return `rgb(255,${255 - i},${255 - i})`; }
+    const i = Math.round(-v * 255); return `rgb(${255 - i},${255 - i},255)`;
+}
+
+function escHtml(s) {
+    return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function renderQueryPanel(d) {
+    const container = document.getElementById("query-panel");
+    if (!d) { container.innerHTML = ""; return; }
+
+    const maxIdfTok = d.tokens.reduce((best, t) => t.idf > best.idf ? t : best, d.tokens[0]);
+
+    const pills = d.tokens.map(tok => {
+        const bg = idfColor(tok.idf_normalized);
+        const alpha = (0.15 + tok.idf_normalized * 0.85).toFixed(2);
+        return `<div class="token-pill">
+            <div class="pill-text" style="background:${bg};opacity:${alpha};min-width:32px;text-align:center">${escHtml(tok.token.replace('##', '·'))}</div>
+            <div class="pill-id">#${tok.id}</div>
+            <div class="pill-idf">idf ${tok.idf.toFixed(2)}</div>
+        </div>`;
+    }).join("");
+
+    const cells = d.embedding.map((v, i) =>
+        `<div class="heatmap-cell" style="background:${heatmapColor(v)}" title="dim ${i}: ${v.toFixed(3)}"></div>`
+    ).join("");
+
+    const cpx = d.stats.complexity, cpxPct = (cpx * 100).toFixed(0);
+    const cpxLabel = cpx < 0.33 ? "Simple" : cpx < 0.66 ? "Moderate" : "Complex";
+
+    const embNote = maxIdfTok
+        ? `<div class="embed-note"> <b>"${escHtml(maxIdfTok.token)}"</b> has the highest IDF (${maxIdfTok.idf.toFixed(2)}) — it pulls the embedding vector the most and takes maximum retrieval weight.</div>`
+        : "";
+
+    container.innerHTML = `
+        <div class="query-panel">
+            <div class="panel-title">🔍 Query Analysis</div>
+            <div class="token-row">${pills}</div>
+            <div class="heatmap-label">Query Embedding — ${d.embedding.length}-dim PCA projection
+                <span style="color:#94a3b8;margin-left:8px">■ <span style="color:#ef4444">positive</span> &nbsp;■ <span style="color:#6366f1">negative</span></span>
+            </div>
+            <div class="heatmap-strip">${cells}</div>
+            ${embNote}
+            <div class="stats-row">
+                <div class="stat-chip"><div class="stat-label">Tokens</div><div class="stat-value">${d.stats.token_count}</div></div>
+                <div class="stat-chip"><div class="stat-label">Unique</div><div class="stat-value">${d.stats.unique_tokens}</div></div>
+                <div class="stat-chip"><div class="stat-label">Avg IDF</div><div class="stat-value">${d.stats.avg_idf}</div></div>
+                <div class="complexity-wrap">
+                    <div class="stat-label">Complexity — ${cpxLabel} (${cpxPct}%)</div>
+                    <div class="complexity-bar-bg"><div class="complexity-bar-fill" style="width:${cpxPct}%"></div></div>
+                </div>
+            </div>
+        </div>`;
+}
+
+
+const STAGES = [
+    { key: "embed", label: "Embed", cls: "seg-embed" },
+    { key: "vector", label: "Vector", cls: "seg-vector" },
+    { key: "bm25", label: "BM25", cls: "seg-bm25" },
+    { key: "hybrid", label: "Hybrid", cls: "seg-hybrid" },
+    { key: "mmr", label: "MMR", cls: "seg-mmr" },
+    { key: "rerank", label: "Rerank", cls: "seg-rerank" },
+    { key: "llm", label: "LLM", cls: "seg-llm" },
+];
+const SEG_COLORS = {
+    "seg-embed": "#6366f1", "seg-vector": "#0ea5e9", "seg-bm25": "#10b981",
+    "seg-hybrid": "#f59e0b", "seg-mmr": "#8b5cf6", "seg-rerank": "#ef4444", "seg-llm": "#64748b"
+};
+
+function renderLatencyPanel(timings) {
+    const container = document.getElementById("latency-panel");
+    if (!timings) { container.innerHTML = ""; return; }
+    const total = timings.total || STAGES.reduce((s, st) => s + (timings[st.key] || 0), 0);
+
+    const segments = STAGES.map((s, idx) => {
+        const ms = timings[s.key] || 0, pct = total > 0 ? (ms / total) * 100 : 0;
+        const isLast = idx === STAGES.length - 1;
+        const inner = pct > 5 ? ms + "ms" : "";
+        return `<div class="latency-segment ${s.cls}" style="${isLast ? 'flex:1' : 'width:' + pct.toFixed(2) + '%'}"
+            title="${s.label}: ${ms}ms (${pct.toFixed(1)}%)">${inner}</div>`;
+    }).join("");
+
+    const smallLabels = STAGES.map(s => {
+        const ms = timings[s.key] || 0, pct = total > 0 ? (ms / total) * 100 : 0;
+        if (ms === 0 || pct > 5) return "";
+        return `<span class="latency-small-label" style="color:${SEG_COLORS[s.cls]}">${s.label} ${ms}ms</span>`;
+    }).filter(Boolean).join("");
+    const smallRow = smallLabels ? `<div class="latency-small-row">${smallLabels}</div>` : "";
+
+    const chips = STAGES.map(s => {
+        const ms = timings[s.key] || 0, pct = total > 0 ? ((ms / total) * 100).toFixed(1) : "0.0";
+        return `<div class="latency-chip">
+            <div class="chip-dot" style="background:${SEG_COLORS[s.cls]}"></div>
+            ${s.label} <span class="chip-time">${ms}ms</span>
+            <span style="color:#94a3b8">${pct}%</span></div>`;
+    }).join("");
+
+    const slowest = STAGES.reduce((b, s) => (timings[s.key] || 0) > (timings[b.key] || 0) ? s : b, STAGES[0]);
+    const slowestMs = timings[slowest.key] || 0;
+    const slowestPct = total > 0 ? Math.round((slowestMs / total) * 100) : 0;
+    const slowestCallout = slowestMs > 0
+        ? `<div class="slowest-callout"> <b>${slowest.label}</b> is taking the most time — <b>${slowestMs}ms</b> (${slowestPct}% of total)</div>`
+        : "";
+
+    const retrieval = STAGES.filter(s => s.key !== "llm");
+    const bottleneck = retrieval.reduce((b, s) => (timings[s.key] || 0) > (timings[b.key] || 0) ? s : b, retrieval[0]);
+    const bPct = total > 0 ? Math.round((timings[bottleneck.key] / total) * 100) : 0;
+    const retrievalCallout = bPct > 15 && slowest.key !== "llm"
+        ? `<div class="bottleneck-callout">⚠ Retrieval bottleneck: <b>${bottleneck.label}</b> taking <b>${bPct}%</b> of total (${timings[bottleneck.key]}ms)</div>`
+        : "";
+    const llmPct = total > 0 ? Math.round(((timings.llm || 0) / total) * 100) : 0;
+    const llmCallout = llmPct > 50
+        ? `<div class="llm-callout">💬 LLM generation is <b>${llmPct}%</b> of total time (${timings.llm}ms) — retrieval is fast ✅</div>`
+        : "";
+
+    container.innerHTML = `
+        <div class="latency-panel">
+            <div class="panel-title">⏱ Latency Timeline</div>
+            <div class="latency-bar">${segments}</div>
+            ${smallRow}
+            <div class="latency-meta">${chips}<div class="latency-total">Total: ${total}ms</div></div>
+            ${slowestCallout}${retrievalCallout}${llmCallout}
+        </div>`;
+}
+
+
+function scoreColor(s) {
+    if (s >= 0.7) return { bg: "#dcfce7", color: "#166534" };
+    if (s >= 0.4) return { bg: "#fef9c3", color: "#854d0e" };
+    return { bg: "#fee2e2", color: "#991b1b" };
+}
+
+function renderChunksPanel(chunks, scores, raw_scores, sources) {
+    const container = document.getElementById("chunks-panel");
+    let html = `<h4 style="margin-top:28px;margin-bottom:12px;color:#1e293b">📄 Context Chunks</h4>`;
+
+    const order = scores
+        .map((s, i) => ({ i, s }))
+        .sort((a, b) => b.s - a.s)
+        .map(x => x.i);
+
+    order.forEach(i => {
+        const score = scores[i];
+        const sc = scoreColor(score);
+        const src = sources[i] || {};
+        const url = src.url || "";
+        const title = src.title || url;
+
+        let displayUrl = url;
+        try {
+            const u = new URL(url);
+            displayUrl = u.hostname + u.pathname.replace(/\/$/, "");
+        } catch (_) { }
+
+        const sourceTag = url
+            ? `<a class="chunk-source-link" href="${escHtml(url)}" target="_blank" title="${escHtml(title)}">
+                   <span class="chunk-source-icon">🔗</span>${escHtml(displayUrl)}
+               </a>`
+            : "";
+
+        html += `
+            <div class="chunk-card">
+                <div class="chunk-card-header">
+                    <span class="chunk-card-title">Chunk ${i + 1}</span>
+                    <span class="chunk-score-badge" style="background:${sc.bg};color:${sc.color}">
+                        score ${score.toFixed(3)}
+                    </span>
+                    ${sourceTag}
+                </div>
+                <div class="chunk-card-body">
+                    <div class="chunk-content">${marked.parse(chunks[i])}</div>
+                </div>
+            </div>`;
+    });
+
+    container.innerHTML = html;
+    hljs.highlightAll();
+}
+
+
+async function ask() {
+    const query = document.getElementById("query").value.trim();
+    if (!query) return;
+
+    document.getElementById("answer").innerHTML = "<p style='color:#94a3b8'>Thinking...</p>";
+    document.getElementById("latency-panel").innerHTML = "";
+    document.getElementById("query-panel").innerHTML = "<p style='font-size:12px;color:#94a3b8;padding:12px 0'>Analyzing query...</p>";
+    document.getElementById("retrieval-panel").innerHTML = "";
+    document.getElementById("mmr-panel").innerHTML = "";
+    document.getElementById("chunks-panel").innerHTML = "";
+
+    const [askRes, analyzeRes] = await Promise.all([
+        fetch("/ask", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query }) }),
+        fetch("/analyze_query", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query }) })
+    ]);
+    const [data, analysis] = await Promise.all([askRes.json(), analyzeRes.json()]);
+
+    // 1. Answer
+    document.getElementById("answer").innerHTML =
+        `<h3>Answer:</h3><div class="answer-box">${marked.parse(data.answer)}</div>`;
+    hljs.highlightAll();
+
+    // 2. Latency
+    renderLatencyPanel(data.timings);
+
+    // 3. Query Analysis
+    renderQueryPanel(analysis);
+
+    // 4. Retrieval Comparison
+    renderRetrievalTable(data.comparison_rows);
+
+    // 5. MMR
+    renderMMRPanel(data.mmr_data);
+
+    // 6. Chunks
+    renderChunksPanel(data.chunks, data.scores, data.raw_scores, data.sources);
+}
+
+document.addEventListener("DOMContentLoaded", () => {
+    document.getElementById("query").addEventListener("keydown", e => {
+        if (e.key === "Enter") ask();
+    });
+});

static/mmr.js

@@ -0,0 +1,245 @@
+let _p3 = {
+    coords: null,   // [[x,y], ...]  UMAP coords, local index
+    sims: null,   // [float, ...]  query-doc similarities
+    previews: null,   // [str, ...]    chunk previews
+    docIndices: null,   // [int, ...]    global doc indices
+    mmrSelected: null,   // set of global doc indices — current MMR selection
+    noMmrSelected: null,   // set — pure relevance top-10
+    lambda: 0.7,
+    sliderTimeout: null,
+};
+
+function renderMMRPanel(mmrData) {
+    const container = document.getElementById("mmr-panel");
+    if (!mmrData || !mmrData.umap_coords) {
+        container.innerHTML = `<div class="p3-panel"><div class="panel-title">🔵 MMR Visualization</div><p style="color:#94a3b8;font-size:13px">UMAP unavailable — install umap-learn</p></div>`;
+        return;
+    }
+
+    _p3.coords = mmrData.umap_coords;
+    _p3.sims = mmrData.sims;
+    _p3.previews = mmrData.doc_previews;
+    _p3.docIndices = mmrData.doc_indices;
+    _p3.mmrSelected = new Set(mmrData.mmr_selected);
+    _p3.noMmrSelected = new Set(mmrData.no_mmr_selected);
+    _p3.lambda = 0.7;
+
+    container.innerHTML = `
+        <div class="p3-panel">
+            <div class="panel-title">🔵 MMR Visualization</div>
+
+            <!-- Lambda slider -->
+            <div class="p3-slider-row">
+                <span class="p3-slider-label">λ = <b id="p3-lambda-val">0.70</b></span>
+                <input id="p3-lambda" type="range" min="0" max="1" step="0.05" value="0.7" class="p3-slider">
+                <span class="p3-slider-hint">← diversity &nbsp;&nbsp; relevance →</span>
+            </div>
+
+            <!-- UMAP + side-by-side row -->
+            <div class="p3-top-row">
+
+                <!-- UMAP scatter -->
+                <div class="p3-scatter-wrap">
+                    <div class="p3-section-label">UMAP Scatter — candidate chunks</div>
+                    <canvas id="p3-umap" width="340" height="280" class="p3-canvas"></canvas>
+                    <div class="p3-scatter-legend">
+                        <span><span class="p3-dot-lg" style="background:#10b981"></span> MMR selected</span>
+                        <span><span class="p3-dot-lg" style="background:#ef4444"></span> Rejected</span>
+                    </div>
+                    <div id="p3-tooltip" class="p3-scatter-tooltip"></div>
+                </div>
+
+                <!-- Side by side: No MMR vs MMR -->
+                <div class="p3-side-wrap">
+                    <div class="p3-side-col">
+                        <div class="p3-section-label" style="color:#f59e0b">Without MMR (top relevance)</div>
+                        <div id="p3-no-mmr-list" class="p3-chunk-list"></div>
+                    </div>
+                    <div class="p3-side-col">
+                        <div class="p3-section-label" style="color:#10b981">With MMR (λ=<span id="p3-side-lambda">0.70</span>)</div>
+                        <div id="p3-mmr-list" class="p3-chunk-list"></div>
+                    </div>
+                </div>
+
+            </div>
+
+            <!-- Similarity matrix -->
+            <div class="p3-section-label" style="margin-top:18px">Similarity Matrix — top 10 MMR candidates</div>
+            <div class="p3-matrix-wrap">
+                <canvas id="p3-simmatrix" class="p3-canvas"></canvas>
+            </div>
+
+        </div>`;
+
+    _drawAll();
+    _drawSideBySide();
+    _drawSimMatrix(mmrData.sim_matrix);
+
+
+    document.getElementById("p3-lambda").addEventListener("input", function () {
+        _p3.lambda = parseFloat(this.value);
+        document.getElementById("p3-lambda-val").textContent = _p3.lambda.toFixed(2);
+        document.getElementById("p3-side-lambda").textContent = _p3.lambda.toFixed(2);
+        clearTimeout(_p3.sliderTimeout);
+        _p3.sliderTimeout = setTimeout(_rerrunMMR, 300);
+    });
+}
+
+function _drawAll() {
+    const canvas = document.getElementById("p3-umap");
+    if (!canvas) return;
+    const ctx = canvas.getContext("2d");
+    const W = canvas.width, H = canvas.height;
+    const PAD = 24;
+
+    ctx.clearRect(0, 0, W, H);
+
+
+    _p3.coords.forEach(([x, y], i) => {
+        const cx = PAD + x * (W - PAD * 2);
+        const cy = PAD + y * (H - PAD * 2);
+        const isSelected = _p3.mmrSelected.has(_p3.docIndices[i]);
+        const sim = _p3.sims[i] || 0;
+
+        if (isSelected) {
+            ctx.beginPath();
+            ctx.arc(cx, cy, 11, 0, Math.PI * 2);
+            ctx.fillStyle = "rgba(16,185,129,0.18)";
+            ctx.fill();
+        }
+
+        ctx.beginPath();
+        ctx.arc(cx, cy, isSelected ? 8 : 5, 0, Math.PI * 2);
+        ctx.fillStyle = isSelected ? "#10b981" : "#ef4444";
+        ctx.globalAlpha = isSelected ? 1 : 0.55 + sim * 0.45;
+        ctx.fill();
+        ctx.globalAlpha = 1;
+
+        if (isSelected) {
+            ctx.font = "bold 9px Arial";
+            ctx.fillStyle = "#065f46";
+            ctx.fillText(i, cx + 10, cy + 4);
+        }
+    });
+
+    canvas.onmousemove = (e) => {
+        const rect = canvas.getBoundingClientRect();
+        const mx = e.clientX - rect.left;
+        const my = e.clientY - rect.top;
+        const PAD = 24;
+
+        let hit = null;
+        _p3.coords.forEach(([x, y], i) => {
+            const cx = PAD + x * (W - PAD * 2);
+            const cy = PAD + y * (H - PAD * 2);
+            if (Math.hypot(mx - cx, my - cy) < 10) hit = i;
+        });
+
+        const tip = document.getElementById("p3-tooltip");
+        if (hit !== null) {
+            const isSelected = _p3.mmrSelected.has(_p3.docIndices[hit]);
+            tip.innerHTML = `
+                <b>${isSelected ? "✅ Selected" : "❌ Rejected"}</b> — chunk ${hit}<br>
+                sim: ${(_p3.sims[hit] || 0).toFixed(3)}<br>
+                <span style="color:#cbd5e1">${escP3(_p3.previews[hit] || "")}</span>`;
+            tip.style.display = "block";
+            tip.style.left = (mx + 12) + "px";
+            tip.style.top = (my + 12) + "px";
+        } else {
+            tip.style.display = "none";
+        }
+    };
+    canvas.onmouseleave = () => {
+        const tip = document.getElementById("p3-tooltip");
+        if (tip) tip.style.display = "none";
+    };
+}
+
+function _drawSideBySide() {
+    const noMmrEl = document.getElementById("p3-no-mmr-list");
+    const mmrEl = document.getElementById("p3-mmr-list");
+    if (!noMmrEl || !mmrEl) return;
+
+    function makeList(selectedSet) {
+        return _p3.docIndices
+            .map((docIdx, i) => ({ docIdx, i, sim: _p3.sims[i] || 0, preview: _p3.previews[i] || "" }))
+            .filter(({ docIdx }) => selectedSet.has(docIdx))
+            .sort((a, b) => b.sim - a.sim)
+            .map(({ i, sim, preview }) => `
+                <div class="p3-side-item">
+                    <div class="p3-side-sim">${sim.toFixed(3)}</div>
+                    <div class="p3-side-text">${escP3(preview)}…</div>
+                </div>`)
+            .join("");
+    }
+
+    noMmrEl.innerHTML = makeList(_p3.noMmrSelected);
+    mmrEl.innerHTML = makeList(_p3.mmrSelected);
+}
+
+function _drawSimMatrix(simMatrix) {
+    if (!simMatrix) return;
+    const localSelected = _p3.docIndices
+        .map((d, i) => ({ d, i }))
+        .filter(({ d }) => _p3.mmrSelected.has(d))
+        .map(({ i }) => i)
+        .slice(0, 10);
+
+    const N = localSelected.length;
+    const CELL = 32;
+    const canvas = document.getElementById("p3-simmatrix");
+    if (!canvas || N === 0) return;
+
+    canvas.width = N * CELL;
+    canvas.height = N * CELL;
+    const ctx = canvas.getContext("2d");
+
+    for (let r = 0; r < N; r++) {
+        for (let c = 0; c < N; c++) {
+            const ri = localSelected[r];
+            const ci = localSelected[c];
+            const val = (simMatrix[ri] && simMatrix[ri][ci] != null) ? simMatrix[ri][ci] : 0;
+            ctx.fillStyle = simHeatColor(val);
+            ctx.fillRect(c * CELL, r * CELL, CELL, CELL);
+
+            ctx.font = "9px Arial";
+            ctx.fillStyle = val > 0.6 ? "#fff" : "#334155";
+            ctx.textAlign = "center";
+            ctx.fillText(val.toFixed(2), c * CELL + CELL / 2, r * CELL + CELL / 2 + 3);
+        }
+    }
+
+    ctx.font = "bold 9px Arial";
+    ctx.fillStyle = "#64748b";
+    ctx.textAlign = "center";
+    for (let i = 0; i < N; i++) {
+        ctx.fillText(localSelected[i], i * CELL + CELL / 2, N * CELL + 12);
+        ctx.fillText(localSelected[i], -6, i * CELL + CELL / 2 + 3);
+    }
+}
+
+function simHeatColor(v) {
+    const t = Math.max(0, Math.min(1, v));
+    const r = Math.round(255 - t * (255 - 99));
+    const g = Math.round(255 - t * (255 - 102));
+    const b = Math.round(255 - t * (255 - 241));
+    return `rgb(${r},${g},${b})`;
+}
+
+async function _rerrunMMR() {
+    const res = await fetch("/mmr_rerun", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ lambda: _p3.lambda })
+    });
+    const data = await res.json();
+    if (data.error) { console.warn("MMR rerun:", data.error); return; }
+
+    _p3.mmrSelected = new Set(data.selected_indices);
+    _drawAll();
+    _drawSideBySide();
+}
+
+function escP3(s) {
+    return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

static/rerank.js

@@ -0,0 +1,126 @@
+// Store full texts in a module-level array — avoids HTML attribute escaping bugs
+let _p2FullTexts = [];
+
+function scoreBar(val, color) {
+    const pct = (val * 100).toFixed(0);
+    return `
+        <div class="p2-score-wrap" title="${val.toFixed(4)}">
+            <div class="p2-bar-bg">
+                <div class="p2-bar-fill" style="width:${pct}%;background:${color}"></div>
+            </div>
+            <span class="p2-score-num">${val.toFixed(3)}</span>
+        </div>`;
+}
+
+function rankArrow(delta) {
+    if (delta > 0) return `<span class="p2-arrow up"   title="Moved up ${delta}">▲${delta}</span>`;
+    if (delta < 0) return `<span class="p2-arrow down" title="Moved down ${Math.abs(delta)}">▼${Math.abs(delta)}</span>`;
+    return `<span class="p2-arrow flat" title="No change">—</span>`;
+}
+
+function rowColor(rerank, passed) {
+    if (!passed) return "rgba(239,68,68,0.06)";
+    if (rerank >= 0.7) return "rgba(16,185,129,0.08)";
+    if (rerank >= 0.4) return "rgba(245,158,11,0.07)";
+    return "rgba(99,102,241,0.05)";
+}
+
+function borderColor(rerank, passed) {
+    if (!passed) return "#fca5a5";
+    if (rerank >= 0.7) return "#6ee7b7";
+    if (rerank >= 0.4) return "#fcd34d";
+    return "#c7d2fe";
+}
+
+function escHtml(s) {
+    return String(s)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+
+function renderRetrievalTable(rows) {
+    const container = document.getElementById("retrieval-panel");
+    if (!rows || !rows.length) { container.innerHTML = ""; return; }
+
+    _p2FullTexts = rows.map(r => r.text_full || "");
+
+    const topRow = [...rows].sort((a, b) => b.rerank_score - a.rerank_score)[0];
+
+    const tableRows = rows.map((r, i) => {
+        const isTop = r.idx === topRow.idx;
+        const bg = rowColor(r.rerank_score, r.passed_threshold);
+        const border = borderColor(r.rerank_score, r.passed_threshold);
+        const dropped = !r.passed_threshold ? `<span class="p2-dropped">DROPPED</span>` : "";
+        const winner = isTop ? `<span class="p2-winner" title="Highest combined rerank score">★ top</span>` : "";
+        const preview = escHtml((r.text_preview || "").trim());
+
+        return `
+            <tr class="p2-row" style="background:${bg};border-left:3px solid ${border}">
+                <td class="p2-td p2-rank">#${r.pre_rank + 1}</td>
+                <td class="p2-td p2-rank">#${r.post_rank + 1} ${winner}${dropped}</td>
+                <td class="p2-td p2-preview-cell" data-idx="${i}">
+                    <div class="p2-preview">${preview}</div>
+                    <div class="p2-tooltip"></div>
+                </td>
+                <td class="p2-td">${scoreBar(r.vector_score, "#0ea5e9")}</td>
+                <td class="p2-td">${scoreBar(r.bm25_score, "#10b981")}</td>
+                <td class="p2-td">${scoreBar(r.hybrid_score, "#f59e0b")}</td>
+                <td class="p2-td">${scoreBar(r.rerank_score, r.passed_threshold ? "#6366f1" : "#ef4444")}</td>
+                <td class="p2-td p2-delta">${rankArrow(r.rank_delta)}</td>
+            </tr>`;
+    }).join("");
+
+    container.innerHTML = `
+        <div class="p2-panel">
+            <div class="panel-title">📊 Retrieval Comparison</div>
+            <div class="p2-legend">
+                <span><span class="p2-dot" style="background:#0ea5e9"></span>Vector</span>
+                <span><span class="p2-dot" style="background:#10b981"></span>BM25</span>
+                <span><span class="p2-dot" style="background:#f59e0b"></span>Hybrid</span>
+                <span><span class="p2-dot" style="background:#6366f1"></span>Reranker</span>
+                <span class="p2-legend-sep">|</span>
+                <span><span class="p2-dot" style="background:#6ee7b7;border:1px solid #10b981"></span>passed</span>
+                <span><span class="p2-dot" style="background:#fca5a5;border:1px solid #ef4444"></span>dropped</span>
+            </div>
+            <div class="p2-table-wrap">
+                <table class="p2-table">
+                    <thead>
+                        <tr>
+                            <th class="p2-th">Original Rank</th>
+                            <th class="p2-th">Rerank</th>
+                            <th class="p2-th">Chunk</th>
+                            <th class="p2-th">Vector</th>
+                            <th class="p2-th">BM25</th>
+                            <th class="p2-th">Hybrid</th>
+                            <th class="p2-th">Reranker</th>
+                            <th class="p2-th">Δ</th>
+                        </tr>
+                    </thead>
+                    <tbody>${tableRows}</tbody>
+                </table>
+            </div>
+        </div>`;
+
+    container.querySelectorAll(".p2-preview-cell").forEach(cell => {
+        const tooltip = cell.querySelector(".p2-tooltip");
+        const idx = parseInt(cell.dataset.idx);
+        tooltip.textContent = _p2FullTexts[idx] || "";
+
+        cell.addEventListener("mouseenter", () => tooltip.classList.add("visible"));
+        cell.addEventListener("mouseleave", () => tooltip.classList.remove("visible"));
+        cell.addEventListener("mousemove", e => {
+            const spaceBelow = window.innerHeight - e.clientY;
+            tooltip.style.left = "0px";
+            if (spaceBelow < 220) {
+                tooltip.style.bottom = "100%";
+                tooltip.style.top = "auto";
+            } else {
+                tooltip.style.top = "100%";
+                tooltip.style.bottom = "auto";
+            }
+        });
+    });
+}

static/style.css

@@ -0,0 +1,845 @@
+/* ══════════════════════════════════════════════════════
+   Reset & Base
+══════════════════════════════════════════════════════ */
+* {
+    box-sizing: border-box;
+}
+
+body {
+    font-family: Arial, sans-serif;
+    background: #f5f7fa;
+    margin: 0;
+}
+
+p {
+    line-height: 1.5;
+}
+
+/* ══════════════════════════════════════════════════════
+   Layout
+══════════════════════════════════════════════════════ */
+.container {
+    max-width: 900px;
+    margin: 50px auto;
+    padding: 25px;
+    text-align: center;
+}
+
+h1 {
+    margin-bottom: 25px;
+}
+
+.input-container {
+    display: flex;
+    gap: 10px;
+    justify-content: center;
+    margin-bottom: 20px;
+}
+
+input {
+    padding: 12px;
+    font-size: 16px;
+    flex: 1;
+    border-radius: 8px;
+    border: 1px solid #ccc;
+    max-width: 600px;
+}
+
+button {
+    padding: 12px 16px;
+    font-size: 16px;
+    border-radius: 8px;
+    border: none;
+    background: #007bff;
+    color: white;
+    cursor: pointer;
+}
+
+button:hover {
+    background: #0056b3;
+}
+
+/* ══════════════════════════════════════════════════════
+   Answer box
+══════════════════════════════════════════════════════ */
+#answer {
+    margin-top: 20px;
+    width: 100%;
+    text-align: left;
+}
+
+.answer-box pre {
+    background: #807d7d;
+    padding: 14px;
+    border-radius: 10px;
+    overflow-x: auto;
+    margin: 10px 0;
+}
+
+.answer-box pre code {
+    background: transparent !important;
+    color: #f8f8f2 !important;
+    font-family: "Courier New", monospace;
+    font-size: 14px;
+    display: block;
+    white-space: pre;
+}
+
+.answer-box code:not(pre code) {
+    background: #eee;
+    color: #333;
+    padding: 2px 6px;
+    border-radius: 4px;
+}
+
+.answer-box ul,
+.answer-box ol {
+    text-align: left;
+    padding-left: 20px;
+}
+
+.query-panel,
+.latency-panel,
+.p2-panel,
+.p3-panel {
+    margin-top: 28px;
+    border: 1px solid #e2e8f0;
+    border-radius: 10px;
+    padding: 20px 24px;
+    background: #f8fafc;
+    font-family: 'JetBrains Mono', 'Fira Code', monospace;
+}
+
+.panel-title {
+    margin: 0 0 16px;
+    font-size: 13px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: #64748b;
+}
+
+.bottleneck-callout,
+.llm-callout,
+.slowest-callout {
+    margin-top: 8px;
+    padding: 8px 12px;
+    border-left-width: 3px;
+    border-left-style: solid;
+    border-radius: 4px;
+    font-size: 12px;
+}
+
+.bottleneck-callout {
+    background: #fff7ed;
+    border-left-color: #ef4444;
+    color: #7c2d12;
+    margin-top: 12px;
+}
+
+.bottleneck-callout b {
+    color: #dc2626;
+}
+
+.llm-callout {
+    background: #f0f9ff;
+    border-left-color: #64748b;
+    color: #1e3a5f;
+}
+
+.llm-callout b {
+    color: #334155;
+}
+
+.slowest-callout {
+    background: #fdf4ff;
+    border-left-color: #a855f7;
+    color: #581c87;
+    font-family: 'JetBrains Mono', 'Fira Code', monospace;
+}
+
+.slowest-callout b {
+    color: #7e22ce;
+}
+
+.p2-dot,
+.p3-dot-lg {
+    display: inline-block;
+    width: 10px;
+    height: 10px;
+    margin-right: 4px;
+    vertical-align: middle;
+}
+
+.p2-dot {
+    border-radius: 3px;
+}
+
+.p3-dot-lg {
+    border-radius: 50%;
+}
+
+
+.p2-winner,
+.p2-dropped {
+    display: inline-block;
+    margin-left: 5px;
+    font-size: 10px;
+    border-radius: 4px;
+    padding: 1px 5px;
+    font-weight: 600;
+    border-width: 1px;
+    border-style: solid;
+}
+
+.p2-winner {
+    background: #fef9c3;
+    color: #854d0e;
+    border-color: #fde047;
+}
+
+.p2-dropped {
+    background: #fee2e2;
+    color: #991b1b;
+    border-color: #fca5a5;
+}
+
+
+.p2-tooltip,
+.p3-scatter-tooltip {
+    display: none;
+    position: absolute;
+    pointer-events: none;
+    background: #1e293b;
+    color: #e2e8f0;
+    border-radius: 6px;
+    font-family: Arial, sans-serif;
+}
+
+.p2-tooltip {
+    top: 100%;
+    left: 0;
+    z-index: 100;
+    width: 380px;
+    max-height: 200px;
+    overflow-y: auto;
+    font-size: 12px;
+    line-height: 1.6;
+    padding: 12px 14px;
+    border-radius: 8px;
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.25);
+    white-space: pre-wrap;
+    word-break: break-word;
+}
+
+.p3-scatter-tooltip {
+    font-size: 11px;
+    line-height: 1.5;
+    padding: 8px 10px;
+    max-width: 220px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+    z-index: 50;
+}
+
+.p2-tooltip.visible,
+.p3-scatter-tooltip.visible {
+    display: block;
+}
+
+.p2-legend,
+.p3-scatter-legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 14px;
+    align-items: center;
+    font-size: 12px;
+    color: #475569;
+}
+
+.p2-legend {
+    margin-bottom: 14px;
+}
+
+.p3-scatter-legend {
+    margin-top: 8px;
+}
+
+.p2-legend-sep {
+    color: #cbd5e1;
+}
+
+.p2-bar-bg,
+.complexity-bar-bg {
+    height: 6px;
+    background: #e2e8f0;
+    border-radius: 3px;
+    overflow: hidden;
+}
+
+.p2-bar-fill,
+.complexity-bar-fill {
+    height: 100%;
+    border-radius: 3px;
+}
+
+.p2-bar-fill {
+    transition: width 0.4s ease;
+}
+
+.complexity-bar-fill {
+    background: linear-gradient(90deg, #10b981, #f59e0b, #ef4444);
+    transition: width 0.5s ease;
+}
+
+/* ══════════════════════════════════════════════════════
+Query Analysis
+══════════════════════════════════════════════════════ */
+.token-row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin-bottom: 20px;
+}
+
+.token-pill {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 3px;
+}
+
+.pill-text {
+    padding: 4px 10px;
+    border-radius: 20px;
+    font-size: 13px;
+    font-weight: 600;
+    color: #fff;
+    letter-spacing: 0.02em;
+    white-space: nowrap;
+}
+
+.pill-id {
+    font-size: 9px;
+    color: #94a3b8;
+}
+
+.pill-idf {
+    font-size: 9px;
+    color: #64748b;
+    font-weight: 500;
+}
+
+.heatmap-label {
+    font-size: 11px;
+    color: #64748b;
+    margin-bottom: 6px;
+    font-weight: 500;
+}
+
+.heatmap-strip {
+    display: flex;
+    height: 22px;
+    border-radius: 4px;
+    overflow: hidden;
+    width: 100%;
+    gap: 1px;
+    margin-bottom: 10px;
+}
+
+.heatmap-cell {
+    flex: 1;
+    border-radius: 1px;
+    transition: opacity 0.15s;
+    cursor: default;
+}
+
+.heatmap-cell:hover {
+    opacity: 0.7;
+}
+
+.embed-note {
+    font-size: 12px;
+    color: #475569;
+    background: #eff6ff;
+    border-left: 3px solid #6366f1;
+    border-radius: 4px;
+    padding: 7px 12px;
+    margin-bottom: 14px;
+    font-family: Arial, sans-serif;
+}
+
+.stats-row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 16px;
+}
+
+.stat-chip {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+
+.stat-label {
+    font-size: 10px;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: #94a3b8;
+}
+
+.stat-value {
+    font-size: 15px;
+    font-weight: 700;
+    color: #0f172a;
+}
+
+.complexity-wrap {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    flex: 1;
+    min-width: 140px;
+}
+
+/* ══════════════════════════════════════════════════════
+  Retrieval Comparison Table
+══════════════════════════════════════════════════════ */
+.p2-panel {
+    width: 100vw;
+    max-width: 100vw;
+    margin-left: calc(50% - 50vw);
+    margin-right: calc(50% - 50vw);
+}
+
+.p2-table-wrap {
+    overflow-x: auto;
+    border-radius: 8px;
+    border: 1px solid #e2e8f0;
+}
+
+.p2-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 12px;
+}
+
+.p2-th {
+    padding: 8px 12px;
+    text-align: left;
+    font-size: 11px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: #64748b;
+    background: #f1f5f9;
+    border-bottom: 1px solid #e2e8f0;
+    white-space: nowrap;
+}
+
+.p2-row {
+    border-bottom: 1px solid #e2e8f0;
+}
+
+.p2-row:last-child {
+    border-bottom: none;
+}
+
+.p2-td {
+    padding: 10px 12px;
+    vertical-align: middle;
+    color: #1e293b;
+}
+
+.p2-rank {
+    font-weight: 700;
+    font-size: 13px;
+    white-space: nowrap;
+    min-width: 80px;
+}
+
+.p2-preview-cell {
+    position: relative;
+    max-width: 260px;
+    min-width: 160px;
+}
+
+.p2-preview {
+    font-size: 12px;
+    color: #334155;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 240px;
+    cursor: default;
+    font-family: Arial, sans-serif;
+}
+
+.p2-score-wrap {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    min-width: 90px;
+}
+
+.p2-bar-bg {
+    flex: 1;
+}
+
+.p2-score-num {
+    font-size: 11px;
+    font-weight: 600;
+    color: #475569;
+    min-width: 36px;
+}
+
+.p2-delta {
+    text-align: center;
+    min-width: 40px;
+}
+
+.p2-arrow {
+    font-size: 12px;
+    font-weight: 700;
+    padding: 2px 5px;
+    border-radius: 4px;
+}
+
+.p2-arrow.up {
+    color: #059669;
+    background: #d1fae5;
+}
+
+.p2-arrow.down {
+    color: #dc2626;
+    background: #fee2e2;
+}
+
+.p2-arrow.flat {
+    color: #94a3b8;
+    background: #f1f5f9;
+}
+
+/* ════════════════════���═════════════════════════════════
+MMR Visualization
+══════════════════════════════════════════════════════ */
+.p3-section-label {
+    font-size: 11px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.07em;
+    color: #64748b;
+    margin-bottom: 8px;
+}
+
+.p3-slider-row {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    margin-bottom: 18px;
+    flex-wrap: wrap;
+}
+
+.p3-slider-label {
+    font-size: 13px;
+    color: #334155;
+    min-width: 70px;
+}
+
+.p3-slider {
+    flex: 1;
+    max-width: 260px;
+    accent-color: #6366f1;
+    cursor: pointer;
+}
+
+.p3-slider-hint {
+    font-size: 11px;
+    color: #94a3b8;
+}
+
+.p3-top-row {
+    display: flex;
+    gap: 20px;
+    flex-wrap: wrap;
+    align-items: flex-start;
+}
+
+.p3-scatter-wrap {
+    position: relative;
+    flex-shrink: 0;
+}
+
+.p3-canvas {
+    display: block;
+    border-radius: 8px;
+    border: 1px solid #e2e8f0;
+    background: #fff;
+}
+
+.p3-side-wrap {
+    display: flex;
+    gap: 14px;
+    flex: 1;
+    min-width: 280px;
+}
+
+.p3-side-col {
+    flex: 1;
+    min-width: 120px;
+}
+
+.p3-chunk-list {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    max-height: 280px;
+    overflow-y: auto;
+}
+
+.p3-side-item {
+    display: flex;
+    gap: 8px;
+    padding: 6px 8px;
+    background: #fff;
+    border: 1px solid #e2e8f0;
+    border-radius: 6px;
+    font-size: 11px;
+    align-items: flex-start;
+    font-family: Arial, sans-serif;
+}
+
+.p3-side-sim {
+    font-weight: 700;
+    color: #6366f1;
+    white-space: nowrap;
+    flex-shrink: 0;
+    font-family: 'JetBrains Mono', monospace;
+}
+
+.p3-side-text {
+    color: #475569;
+    overflow: hidden;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+}
+
+.p3-matrix-wrap {
+    overflow-x: auto;
+    margin-top: 6px;
+    padding-bottom: 16px;
+}
+
+/* ══════════════════════════════════════════════════════
+  Latency Timeline
+══════════════════════════════════════════════════════ */
+.latency-bar {
+    display: flex;
+    height: 28px;
+    border-radius: 6px;
+    overflow: hidden;
+    width: 100%;
+}
+
+.latency-segment {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 11px;
+    font-weight: 600;
+    color: #fff;
+    white-space: nowrap;
+    overflow: hidden;
+    transition: opacity 0.2s;
+    cursor: default;
+}
+
+.latency-segment:last-child {
+    flex: 1;
+}
+
+.latency-segment:hover {
+    opacity: 0.85;
+}
+
+.seg-embed {
+    background: #6366f1;
+}
+
+.seg-vector {
+    background: #0ea5e9;
+}
+
+.seg-bm25 {
+    background: #10b981;
+}
+
+.seg-hybrid {
+    background: #f59e0b;
+}
+
+.seg-mmr {
+    background: #8b5cf6;
+}
+
+.seg-rerank {
+    background: #ef4444;
+}
+
+.seg-llm {
+    background: #64748b;
+}
+
+.latency-small-row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin-top: 6px;
+    margin-bottom: 2px;
+}
+
+.latency-small-label {
+    font-size: 10px;
+    font-weight: 700;
+    background: #f1f5f9;
+    border-radius: 4px;
+    padding: 2px 6px;
+    white-space: nowrap;
+}
+
+.latency-meta {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 12px;
+    margin-top: 14px;
+    align-items: center;
+}
+
+.latency-chip {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 12px;
+    color: #334155;
+}
+
+.chip-dot {
+    width: 10px;
+    height: 10px;
+    border-radius: 3px;
+    flex-shrink: 0;
+}
+
+.chip-time {
+    font-weight: 700;
+    color: #0f172a;
+}
+
+.latency-total {
+    margin-left: auto;
+    font-size: 13px;
+    font-weight: 700;
+    color: #0f172a;
+}
+
+/* ══════════════════════════════════════════════════════
+   Chunk cards
+══════════════════════════════════════════════════════ */
+.chunk-card {
+    border: 1px solid #e2e8f0;
+    border-radius: 10px;
+    background: #fff;
+    margin-bottom: 14px;
+    overflow: hidden;
+}
+
+.chunk-card-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 10px 14px;
+    background: #f8fafc;
+    border-bottom: 1px solid #e2e8f0;
+    gap: 10px;
+    flex-wrap: wrap;
+}
+
+.chunk-card-title {
+    font-size: 14px;
+    font-weight: 700;
+    color: #1e293b;
+}
+
+.chunk-score-badge {
+    font-size: 12px;
+    font-weight: 700;
+    padding: 3px 8px;
+    border-radius: 20px;
+    white-space: nowrap;
+}
+
+.chunk-source-link {
+    font-size: 14px;
+    color: #6366f1;
+    text-decoration: none;
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    max-width: 380px;
+}
+
+.chunk-source-link:hover {
+    text-decoration: underline;
+}
+
+.chunk-source-icon {
+    font-size: 12px;
+    flex-shrink: 0;
+}
+
+.chunk-card-body {
+    padding: 14px;
+}
+
+.chunk-content {
+    font-size: 14px;
+    color: #334155;
+    line-height: 1.6;
+    text-align: left;
+}
+
+.chunk-content pre,
+.chunk-content code {
+    background: none !important;
+    color: inherit !important;
+    padding: 0 !important;
+    border-radius: 0 !important;
+    font-family: inherit !important;
+    white-space: normal !important;
+}
+
+.chunk {
+    border: 1px solid #ddd;
+    padding: 12px;
+    margin-bottom: 12px;
+    border-radius: 10px;
+    background: white;
+    text-align: left;
+}
+
+.chunk pre,
+.chunk code {
+    background: none !important;
+    color: inherit !important;
+    padding: 0 !important;
+    border-radius: 0 !important;
+    font-family: inherit !important;
+    white-space: normal !important;
+}
+
+.source {
+    margin-top: 8px;
+}

templates/index.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>RAG Assistant</title>
+    <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
+    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+</head>
+
+<body>
+
+    <div class="container">
+
+        <h1>📚 RAG Assistant</h1>
+
+        <div class="input-container">
+            <input id="query" placeholder="Ask something about Transformers...">
+            <button onclick="ask()">Ask</button>
+        </div>
+
+        <div id="answer"></div>
+        <div id="latency-panel"></div>
+        <div id="query-panel"></div>
+        <div id="retrieval-panel"></div>
+        <div id="mmr-panel"></div>
+        <div id="chunks-panel"></div>
+
+    </div>
+
+    <script src="{{ url_for('static', filename='rerank.js') }}"></script>
+    <script src="{{ url_for('static', filename='mmr.js') }}"></script>
+    <script src="{{ url_for('static', filename='main.js') }}"></script>
+
+</body>
+
+</html>