hf-space: deploy branch without frontend/data/results

.dockerignore

@@ -0,0 +1,31 @@
+# Python caches
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*.pyo
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Frontend app (deployed separately on Vercel)
+frontend/
+
+# Local/runtime cache
+.cache/
+
+# Explicit user-requested exclusions
+/EntireBookCleaned.txt
+/startup.txt
+
+# Git and editor noise
+.git/
+.gitignore
+.vscode/
+.idea/
+
+# OS artifacts
+.DS_Store
+Thumbs.db

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,32 @@
+# python specific ignores
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Environment and local secrets
+.env
+.env.*
+!.env.example
+
+# Build and packaging artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Caches and tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.ipynb_checkpoints/
+.cache/
+
+# IDE/editor
+.vscode/
+.idea/

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+# Minimal system packages for common Python builds.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt ./
+RUN pip install --upgrade pip && pip install -r requirements.txt
+
+COPY . .
+
+# Fail fast during build if critical runtime folders are missing from context.
+RUN test -d /app/backend && test -d /app/data && test -d /app/results
+
+# Hugging Face Spaces exposes apps on port 7860 by default.
+EXPOSE 7860
+
+CMD ["uvicorn", "backend.api:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,12 @@
+---
+title: NLP RAG
+emoji: 🏢
+colorFrom: gray
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
+short_description: NLP Spring 2026 Project 1
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

backend/api.py

@@ -0,0 +1,32 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from backend.routes.health import router as health_router
+from backend.routes.predict import router as predict_router
+from backend.routes.predict_stream import router as predict_stream_router
+from backend.routes.title import router as title_router
+from backend.services.startup import initialize_runtime_state
+from backend.state import state
+
+# fastapi configs defined here
+# all the router objects are imported here
+#--@Qamar
+
+app = FastAPI(title="RAG-AS3 API", version="0.1.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(health_router)
+app.include_router(title_router)
+app.include_router(predict_router)
+app.include_router(predict_stream_router)
+
+
+@app.on_event("startup")
+def startup_event() -> None:
+    initialize_runtime_state(state)

backend/routes/health.py

@@ -0,0 +1,11 @@
+from fastapi import APIRouter
+
+from backend.state import REQUIRED_STATE_KEYS, state
+
+router = APIRouter()
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    ready = all(k in state for k in REQUIRED_STATE_KEYS)
+    return {"status": "ok" if ready else "starting"}

backend/routes/predict.py

@@ -0,0 +1,88 @@
+import time
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+from backend.schemas import PredictRequest, PredictResponse
+from backend.services.chunks import build_retrieved_chunks
+from backend.services.models import resolve_model
+from backend.state import state
+from retriever.generator import RAGGenerator
+from retriever.retriever import HybridRetriever
+
+router = APIRouter()
+
+
+@router.post("/predict", response_model=PredictResponse)
+def predict(payload: PredictRequest) -> PredictResponse:
+    req_start = time.perf_counter()
+
+    precheck_start = time.perf_counter()
+    if not state:
+        raise HTTPException(status_code=503, detail="Service not initialized yet")
+
+    query = payload.query.strip()
+    if not query:
+        raise HTTPException(status_code=400, detail="Query cannot be empty")
+    precheck_time = time.perf_counter() - precheck_start
+
+    state_access_start = time.perf_counter()
+    retriever: HybridRetriever = state["retriever"]
+    index = state["index"]
+    rag_engine: RAGGenerator = state["rag_engine"]
+    models: dict[str, Any] = state["models"]
+    chunk_lookup: dict[str, dict[str, Any]] = state.get("chunk_lookup", {})
+    state_access_time = time.perf_counter() - state_access_start
+
+    model_resolve_start = time.perf_counter()
+    model_name, model_instance = resolve_model(payload.model, models)
+    model_resolve_time = time.perf_counter() - model_resolve_start
+
+    retrieval_start = time.perf_counter()
+    contexts = retriever.search(
+        query,
+        index,
+        chunking_technique=payload.chunking_technique,
+        mode=payload.mode,
+        rerank_strategy=payload.rerank_strategy,
+        use_mmr=payload.use_mmr,
+        lambda_param=payload.lambda_param,
+        top_k=payload.top_k,
+        final_k=payload.final_k,
+        verbose=False,
+    )
+    retrieval_time = time.perf_counter() - retrieval_start
+
+    if not contexts:
+        raise HTTPException(status_code=404, detail="No context chunks retrieved for this query")
+
+    inference_start = time.perf_counter()
+    answer = rag_engine.get_answer(model_instance, query, contexts, temperature=payload.temperature)
+    inference_time = time.perf_counter() - inference_start
+
+    mapping_start = time.perf_counter()
+    retrieved_chunks = build_retrieved_chunks(contexts=contexts, chunk_lookup=chunk_lookup)
+    mapping_time = time.perf_counter() - mapping_start
+
+    total_time = time.perf_counter() - req_start
+
+    print(
+        f"Predict timing | model={model_name} | mode={payload.mode} | "
+        f"rerank={payload.rerank_strategy} | use_mmr={payload.use_mmr} | "
+        f"lambda={payload.lambda_param:.2f} | temp={payload.temperature:.2f} | "
+        f"chunking={payload.chunking_technique} | "
+        f"top_k={payload.top_k} | final_k={payload.final_k} | returned={len(contexts)} | "
+        f"precheck={precheck_time:.3f}s | "
+        f"state_access={state_access_time:.3f}s | model_resolve={model_resolve_time:.3f}s | "
+        f"retrieval={retrieval_time:.3f}s | inference={inference_time:.3f}s | "
+        f"context_map={mapping_time:.3f}s | total={total_time:.3f}s"
+    )
+
+    return PredictResponse(
+        model=model_name,
+        answer=answer,
+        contexts=contexts,
+        retrieved_chunks=retrieved_chunks,
+    )
+
+

backend/routes/predict_stream.py

@@ -0,0 +1,151 @@
+import os
+import time
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+
+from backend.schemas import PredictRequest
+from backend.services.chunks import build_retrieved_chunks
+from backend.services.models import resolve_model
+from backend.services.streaming import to_ndjson
+from backend.state import state
+from retriever.generator import RAGGenerator
+from retriever.retriever import HybridRetriever
+
+router = APIRouter()
+
+
+# all paths define and API router object which is called
+# in the api.py
+
+
+@router.post("/predict/stream")
+def predict_stream(payload: PredictRequest) -> StreamingResponse:
+    req_start = time.perf_counter()
+    stream_max_tokens = int(os.getenv("STREAM_MAX_TOKENS", "400"))
+
+    precheck_start = time.perf_counter()
+    if not state:
+        raise HTTPException(status_code=503, detail="Service not initialized yet")
+
+    query = payload.query.strip()
+    if not query:
+        raise HTTPException(status_code=400, detail="Query cannot be empty")
+    precheck_time = time.perf_counter() - precheck_start
+
+    state_access_start = time.perf_counter()
+    retriever: HybridRetriever = state["retriever"]
+    index = state["index"]
+    rag_engine: RAGGenerator = state["rag_engine"]
+    models: dict[str, Any] = state["models"]
+    chunk_lookup: dict[str, dict[str, Any]] = state.get("chunk_lookup", {})
+    state_access_time = time.perf_counter() - state_access_start
+
+    model_resolve_start = time.perf_counter()
+    model_name, model_instance = resolve_model(payload.model, models)
+    model_resolve_time = time.perf_counter() - model_resolve_start
+
+    retrieval_start = time.perf_counter()
+    contexts = retriever.search(
+        query,
+        index,
+        chunking_technique=payload.chunking_technique,
+        mode=payload.mode,
+        rerank_strategy=payload.rerank_strategy,
+        use_mmr=payload.use_mmr,
+        lambda_param=payload.lambda_param,
+        top_k=payload.top_k,
+        final_k=payload.final_k,
+        verbose=False,
+    )
+    retrieval_time = time.perf_counter() - retrieval_start
+
+    if not contexts:
+        raise HTTPException(status_code=404, detail="No context chunks retrieved for this query")
+
+    def stream_events():
+        inference_start = time.perf_counter()
+        first_token_latency = None
+        answer_parts: list[str] = []
+        try:
+            yield to_ndjson(
+                {
+                    "type": "status",
+                    "stage": "inference_start",
+                    "model": model_name,
+                    "retrieval_s": round(retrieval_time, 3),
+                    "retrieval_debug": {
+                        "requested_chunking_technique": payload.chunking_technique,
+                        "requested_top_k": payload.top_k,
+                        "requested_final_k": payload.final_k,
+                        "returned_context_count": len(contexts),
+                        "use_mmr": payload.use_mmr,
+                        "lambda_param": payload.lambda_param,
+                    },
+                }
+            )
+
+            for token in rag_engine.get_answer_stream(
+                model_instance,
+                query,
+                contexts,
+                temperature=payload.temperature,
+                max_tokens=stream_max_tokens,
+            ):
+                if first_token_latency is None:
+                    first_token_latency = time.perf_counter() - inference_start
+                answer_parts.append(token)
+                yield to_ndjson({"type": "token", "token": token})
+
+            inference_time = time.perf_counter() - inference_start
+            answer = "".join(answer_parts)
+            retrieved_chunks = build_retrieved_chunks(contexts=contexts, chunk_lookup=chunk_lookup)
+
+            yield to_ndjson(
+                {
+                    "type": "done",
+                    "model": model_name,
+                    "answer": answer,
+                    "contexts": contexts,
+                    "retrieved_chunks": retrieved_chunks,
+                    "retrieval_debug": {
+                        "requested_chunking_technique": payload.chunking_technique,
+                        "requested_top_k": payload.top_k,
+                        "requested_final_k": payload.final_k,
+                        "returned_context_count": len(contexts),
+                        "use_mmr": payload.use_mmr,
+                        "lambda_param": payload.lambda_param,
+                    },
+                }
+            )
+
+            total_time = time.perf_counter() - req_start
+            print(
+                f"Predict stream timing | model={model_name} | mode={payload.mode} | "
+                f"rerank={payload.rerank_strategy} | use_mmr={payload.use_mmr} | "
+                f"lambda={payload.lambda_param:.2f} | temp={payload.temperature:.2f} | "
+                f"chunking={payload.chunking_technique} | "
+                f"top_k={payload.top_k} | final_k={payload.final_k} | returned={len(contexts)} | "
+                f"precheck={precheck_time:.3f}s | "
+                f"state_access={state_access_time:.3f}s | model_resolve={model_resolve_time:.3f}s | "
+                f"retrieval={retrieval_time:.3f}s | first_token={first_token_latency if first_token_latency is not None else -1:.3f}s | "
+                f"inference={inference_time:.3f}s | total={total_time:.3f}s | "
+                f"max_tokens={stream_max_tokens}"
+            )
+        except Exception as exc:
+            total_time = time.perf_counter() - req_start
+            print(
+                f"Predict stream error | model={model_name} | mode={payload.mode} | "
+                f"retrieval={retrieval_time:.3f}s | elapsed={total_time:.3f}s | error={exc}"
+            )
+            yield to_ndjson({"type": "error", "message": f"Streaming failed: {exc}"})
+
+    return StreamingResponse(
+        stream_events(),
+        media_type="application/x-ndjson",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )

backend/routes/title.py

@@ -0,0 +1,36 @@
+from fastapi import APIRouter, HTTPException
+from huggingface_hub import InferenceClient
+
+from backend.schemas import TitleRequest, TitleResponse
+from backend.services.title import parse_title_model_candidates, title_from_hf, title_from_query
+from backend.state import state
+
+router = APIRouter()
+
+
+@router.post("/predict/title", response_model=TitleResponse)
+def suggest_title(payload: TitleRequest) -> TitleResponse:
+    query = payload.query.strip()
+    if not query:
+        raise HTTPException(status_code=400, detail="Query cannot be empty")
+
+    fallback_title = title_from_query(query)
+
+    title_client: InferenceClient | None = state.get("title_client")
+    title_model_ids: list[str] = state.get("title_model_ids", parse_title_model_candidates())
+
+    if title_client is not None:
+        for title_model_id in title_model_ids:
+            try:
+                hf_title = title_from_hf(query, title_client, title_model_id)
+                if hf_title:
+                    return TitleResponse(title=hf_title, source=f"hf:{title_model_id}")
+            except Exception as exc:
+                err_text = str(exc)
+                if "model_not_supported" in err_text or "not supported by any provider" in err_text:
+                    continue
+                print(f"Title generation model failed ({title_model_id}): {exc}")
+                continue
+
+    print("Title generation fallback triggered: no title model available/successful")
+    return TitleResponse(title=fallback_title, source="rule-based")

backend/schemas.py

@@ -0,0 +1,35 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+# this defines the schemas for API endpoints
+#
+
+
+class PredictRequest(BaseModel):
+    query: str = Field(..., min_length=1, description="User query text")
+    model: str = Field(default="Llama-3-8B", description="Model name key")
+    top_k: int = Field(default=10, ge=1, le=20)
+    final_k: int = Field(default=3, ge=1, le=8)
+    chunking_technique: str = Field(default="all", description="all | fixed | sentence | paragraph | semantic | recursive | page | markdown")
+    mode: str = Field(default="hybrid", description="semantic | bm25 | hybrid")
+    rerank_strategy: str = Field(default="cross-encoder", description="cross-encoder | rrf | none")
+    use_mmr: bool = Field(default=True, description="Whether to apply MMR after reranking")
+    lambda_param: float = Field(default=0.5, ge=0.0, le=1.0, description="MMR relevance/diversity tradeoff")
+    temperature: float = Field(default=0.1, ge=0.0, le=2.0, description="Generation temperature")
+
+
+class PredictResponse(BaseModel):
+    model: str
+    answer: str
+    contexts: list[str]
+    retrieved_chunks: list[dict[str, Any]]
+
+
+class TitleRequest(BaseModel):
+    query: str = Field(..., min_length=1, description="First user message")
+
+
+class TitleResponse(BaseModel):
+    title: str
+    source: str

backend/services/cache.py

@@ -0,0 +1,30 @@
+import os
+from typing import Any
+
+from data.vector_db import load_chunks_with_local_cache
+
+# cacheing logic here
+# note cacheing just useful in dev environment
+# not really needed in hf, not even sure if hf memory is persistent
+
+def get_cache_settings() -> tuple[str, bool]:
+    project_root = os.path.dirname(os.path.abspath(__file__))
+    cache_dir = os.getenv("BM25_CACHE_DIR", os.path.join(project_root, "..", ".cache"))
+    force_cache_refresh = os.getenv("BM25_CACHE_REFRESH", "0").lower() in {"1", "true", "yes"}
+    return cache_dir, force_cache_refresh
+
+
+def load_cached_chunks(
+    index: Any,
+    index_name: str,
+    cache_dir: str,
+    force_cache_refresh: bool,
+    batch_size: int = 100,
+) -> tuple[list[dict[str, Any]], str]:
+    return load_chunks_with_local_cache(
+        index=index,
+        index_name=index_name,
+        cache_dir=cache_dir,
+        batch_size=batch_size,
+        force_refresh=force_cache_refresh,
+    )

backend/services/chunks.py

@@ -0,0 +1,52 @@
+from typing import Any
+
+
+# might need to touch this to get the additional metadata for retrieved chunks, like title and url
+# --@Qamar
+
+def build_retrieved_chunks(
+    contexts: list[str],
+    chunk_lookup: dict[str, dict[str, Any]],
+) -> list[dict[str, Any]]:
+    if not contexts:
+        return []
+
+    retrieved_chunks: list[dict[str, Any]] = []
+
+    for idx, text in enumerate(contexts, start=1):
+        meta = chunk_lookup.get(text, {})
+        title = meta.get("title") or "Untitled"
+        url = meta.get("url") or ""
+        chunk_index = meta.get("chunk_index")
+        page = meta.get("page")
+        section = meta.get("section")
+        source_type = meta.get("source_type") or meta.get("source")
+        image_url = (
+            meta.get("image_url")
+            or meta.get("image")
+            or meta.get("thumbnail_url")
+            or meta.get("media_url")
+        )
+
+        extra_metadata = {
+            k: v
+            for k, v in meta.items()
+            if k not in {"title", "url", "chunk_index", "text", "technique", "chunking_technique"}
+        }
+
+        retrieved_chunks.append(
+            {
+                "rank": idx,
+                "text": text,
+                "source_title": title,
+                "source_url": url,
+                "chunk_index": chunk_index,
+                "page": page,
+                "section": section,
+                "source_type": source_type,
+                "image_url": image_url,
+                "extra_metadata": extra_metadata,
+            }
+        )
+
+    return retrieved_chunks

backend/services/models.py

@@ -0,0 +1,37 @@
+from typing import Any
+
+from fastapi import HTTPException
+
+from models.llama_3_8b import Llama3_8B
+from models.mistral_7b import Mistral_7b
+from models.qwen_2_5 import Qwen2_5
+from models.deepseek_v3 import DeepSeek_V3
+from models.tiny_aya import TinyAya
+
+# model defination
+# copied from /models
+
+
+def build_models(hf_token: str) -> dict[str, Any]:
+    return {
+        "Llama-3-8B": Llama3_8B(token=hf_token),
+        "Mistral-7B": Mistral_7b(token=hf_token),
+        "Qwen-2.5": Qwen2_5(token=hf_token),
+        "DeepSeek-V3": DeepSeek_V3(token=hf_token),
+        "TinyAya": TinyAya(token=hf_token),
+    }
+
+
+def resolve_model(name: str, models: dict[str, Any]) -> tuple[str, Any]:
+    aliases = {
+        "llama": "Llama-3-8B",
+        "mistral": "Mistral-7B",
+        "qwen": "Qwen-2.5",
+        "deepseek": "DeepSeek-V3",
+        "tinyaya": "TinyAya",
+    }
+    model_key = aliases.get(name.lower(), name)
+    if model_key not in models:
+        allowed = ", ".join(models.keys())
+        raise HTTPException(status_code=400, detail=f"Unknown model '{name}'. Use one of: {allowed}")
+    return model_key, models[model_key]

backend/services/startup.py

@@ -0,0 +1,124 @@
+import os
+import time
+from typing import Any
+
+from dotenv import load_dotenv
+from huggingface_hub import InferenceClient
+
+from config_loader import cfg
+from data.vector_db import get_index_by_name
+from retriever.generator import RAGGenerator
+from retriever.processor import ChunkProcessor
+from retriever.retriever import HybridRetriever
+
+from backend.services.cache import get_cache_settings, load_cached_chunks
+from backend.services.models import build_models
+from backend.services.title import parse_title_model_candidates
+
+
+# main file for initializing the runtime. Actual defines the 
+# pipeline objects, like retriever, generator and models
+# i think i 
+
+def initialize_runtime_state(state: dict[str, Any]) -> None:
+    startup_start = time.perf_counter()
+
+    dotenv_start = time.perf_counter()
+    load_dotenv()
+    dotenv_time = time.perf_counter() - dotenv_start
+
+    env_start = time.perf_counter()
+    hf_token = os.getenv("HF_TOKEN")
+    pinecone_api_key = os.getenv("PINECONE_API_KEY")
+    env_time = time.perf_counter() - env_start
+
+    if not pinecone_api_key:
+        raise RuntimeError("PINECONE_API_KEY not found in environment variables")
+    if not hf_token:
+        raise RuntimeError("HF_TOKEN not found in environment variables")
+
+    index_name = "cbt-book-recursive"
+    embed_model_name = cfg.processing.get("embedding_model", "all-MiniLM-L6-v2")
+    rerank_model_name = os.getenv(
+        "RERANK_MODEL_NAME",
+        cfg.retrieval.get("rerank_model", "mixedbread-ai/mxbai-rerank-base-v1"),
+    )
+    cache_dir, force_cache_refresh = get_cache_settings()
+
+    index_start = time.perf_counter()
+    index = get_index_by_name(api_key=pinecone_api_key, index_name=index_name)
+    index_time = time.perf_counter() - index_start
+
+    chunks_start = time.perf_counter()
+    final_chunks, chunk_source = load_cached_chunks(
+        index=index,
+        index_name=index_name,
+        cache_dir=cache_dir,
+        force_cache_refresh=force_cache_refresh,
+    )
+    chunk_load_time = time.perf_counter() - chunks_start
+
+    if not final_chunks:
+        raise RuntimeError("No chunks found in Pinecone metadata. Run indexing once before API mode.")
+
+    processor_start = time.perf_counter()
+    proc = ChunkProcessor(model_name=embed_model_name, verbose=False, load_hf_embeddings=False)
+    processor_time = time.perf_counter() - processor_start
+
+    retriever_start = time.perf_counter()
+    retriever = HybridRetriever(
+        final_chunks,
+        proc.encoder,
+        rerank_model_name=rerank_model_name,
+        verbose=False,
+    )
+    retriever_time = time.perf_counter() - retriever_start
+
+    rag_start = time.perf_counter()
+    rag_engine = RAGGenerator()
+    rag_time = time.perf_counter() - rag_start
+
+    models_start = time.perf_counter()
+    models = build_models(hf_token)
+    models_time = time.perf_counter() - models_start
+
+    state_start = time.perf_counter()
+    chunk_lookup: dict[str, dict[str, Any]] = {}
+    for chunk in final_chunks:
+        metadata = chunk.get("metadata", {})
+        text = metadata.get("text")
+        if not text or text in chunk_lookup:
+            continue
+        meta_without_text = {k: v for k, v in metadata.items() if k != "text"}
+        meta_without_text["title"] = metadata.get("title", "Untitled")
+        meta_without_text["url"] = metadata.get("url", "")
+        meta_without_text["chunk_index"] = metadata.get("chunk_index")
+        chunk_lookup[text] = meta_without_text
+
+    state["index"] = index
+    state["retriever"] = retriever
+    state["rag_engine"] = rag_engine
+    state["models"] = models
+    state["chunk_lookup"] = chunk_lookup
+    state["title_model_ids"] = parse_title_model_candidates()
+    state["title_client"] = InferenceClient(token=hf_token)
+    state_time = time.perf_counter() - state_start
+
+    startup_time = time.perf_counter() - startup_start
+    print(
+        f"API startup complete | chunks={len(final_chunks)} | "
+        f"dotenv={dotenv_time:.3f}s | "
+        f"env={env_time:.3f}s | "
+        f"index={index_time:.3f}s | "
+        f"cache_dir={cache_dir} | "
+        f"force_cache_refresh={force_cache_refresh} | "
+        f"chunk_source={chunk_source} | "
+        f"chunk_load={chunk_load_time:.3f}s | "
+        f"processor={processor_time:.3f}s | "
+        f"rerank_model={rerank_model_name} | "
+        f"retriever={retriever_time:.3f}s | "
+        f"rag={rag_time:.3f}s | "
+        f"models={models_time:.3f}s | "
+        f"state={state_time:.3f}s | "
+        f"total={startup_time:.3f}s"
+    )

backend/services/streaming.py

@@ -0,0 +1,7 @@
+import json
+from typing import Any
+
+#need ndjson for streaming responses, this is a simple helper to convert dicts to ndjson format
+
+def to_ndjson(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=False) + "\n"

backend/services/title.py

@@ -0,0 +1,86 @@
+import os
+import re
+
+from huggingface_hub import InferenceClient
+
+# the functions for resolving and generating titles
+# it tries to query and hf model for title
+
+# some shitty fallback logic, if models fail
+# could improve candidate model defining code
+
+def title_from_query(query: str) -> str:
+    stop_words = {
+        "a", "an", "and", "are", "as", "at", "be", "by", "can", "do", "for", "from", "how",
+        "i", "in", "is", "it", "me", "my", "of", "on", "or", "please", "show", "tell", "that",
+        "the", "this", "to", "we", "what", "when", "where", "which", "why", "with", "you", "your",
+    }
+
+    words = re.findall(r"[A-Za-z0-9][A-Za-z0-9\-_/+]*", query)
+    if not words:
+        return "New Chat"
+
+    filtered: list[str] = []
+    for word in words:
+        cleaned = word.strip("-_/+")
+        if not cleaned:
+            continue
+        if cleaned.lower() in stop_words:
+            continue
+        filtered.append(cleaned)
+        if len(filtered) >= 6:
+            break
+
+    chosen = filtered if filtered else words[:6]
+    normalized = [w.capitalize() if w.islower() else w for w in chosen]
+    title = " ".join(normalized).strip()
+    return title[:80] if title else "New Chat"
+
+
+def clean_title_text(raw: str) -> str:
+    text = (raw or "").strip()
+    text = text.replace("\n", " ").replace("\r", " ")
+    text = re.sub(r"^[\"'`\s]+|[\"'`\s]+$", "", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    words = text.split()
+    if len(words) > 8:
+        text = " ".join(words[:8])
+    return text[:80]
+
+
+def title_from_hf(query: str, client: InferenceClient, model_id: str) -> str | None:
+    system_prompt = (
+        "You generate short chat titles. Return only a title, no punctuation at the end, no quotes."
+    )
+    user_prompt = (
+        "Create a concise 3-7 word title for this user request:\n"
+        f"{query}"
+    )
+
+    response = client.chat_completion(
+        model=model_id,
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+        max_tokens=24,
+        temperature=0.3,
+    )
+    if not response or not response.choices:
+        return None
+
+    raw_title = response.choices[0].message.content or ""
+    title = clean_title_text(raw_title)
+    if not title or title.lower() == "new chat":
+        return None
+    return title
+
+
+def parse_title_model_candidates() -> list[str]:
+    
+    raw = os.getenv(
+        "TITLE_MODEL_IDS",
+        "Qwen/Qwen2.5-1.5B-Instruct,CohereLabs/tiny-aya-global,meta-llama/Meta-Llama-3-8B-Instruct",
+    )
+    models = [m.strip() for m in raw.split(",") if m.strip()]
+    return models or ["meta-llama/Meta-Llama-3-8B-Instruct"]

backend/state.py

@@ -0,0 +1,7 @@
+from typing import Any
+
+state: dict[str, Any] = {}
+# this file defines the state dict
+# think of this as the runtime object created after startup
+
+REQUIRED_STATE_KEYS = ("index", "retriever", "rag_engine", "models")

config.yaml

@@ -0,0 +1,46 @@
+# ------------------------------------------------------------------
+# RAG CBT QUESTION-ANSWERING SYSTEM CONFIGURATION
+# ------------------------------------------------------------------
+
+project:
+  name: "cbt-rag-system"
+  category: "psychology"
+  doc_limit: null # Load all pages from the book
+
+processing:
+  # Embedding model used for both vector db and evaluator similarity
+  embedding_model: "jinaai/jina-embeddings-v2-small-en"
+  # Options: sentence, recursive, semantic, fixed
+  technique: "recursive"
+  # Jina supports 8192 tokens (~32k chars), using 1000 chars for better context
+  chunk_size: 1000
+  chunk_overlap: 100
+
+vector_db:
+  base_index_name: "cbt-book"
+  dimension: 512 # Jina outputs 512 dimensions
+  metric: "cosine"
+  batch_size: 50 # Reduced batch size for CPU processing
+
+retrieval:
+  # Options: hybrid, semantic, bm25
+  mode: "hybrid"
+  # Options: cross-encoder, rrf
+  rerank_strategy: "cross-encoder"
+  use_mmr: true
+  top_k: 10
+  final_k: 5
+
+generation:
+  temperature: 0.
+  max_new_tokens: 512
+  # The model used to Judge the others (OpenRouter)
+  judge_model: "stepfun/step-3.5-flash:free"
+
+# List of contestants in the tournament
+models:
+  - "Llama-3-8B"
+  - "Mistral-7B"
+  - "Qwen-2.5"
+  - "DeepSeek-V3"
+  - "TinyAya"

config_loader.py

@@ -0,0 +1,27 @@
+import yaml
+from pathlib import Path
+
+class RAGConfig:
+    def __init__(self, config_path="config.yaml"):
+        with open(config_path, 'r') as f:
+            self.data = yaml.safe_load(f)
+
+    @property
+    def project(self): return self.data['project']
+    
+    @property
+    def processing(self): return self.data['processing']
+    
+    @property
+    def db(self): return self.data['vector_db']
+    
+    @property
+    def retrieval(self): return self.data['retrieval']
+    
+    @property
+    def gen(self): return self.data['generation']
+    
+    @property
+    def model_list(self): return self.data['models']
+
+cfg = RAGConfig()

main.py

@@ -0,0 +1,659 @@
+import os
+import json
+import time
+from datetime import datetime
+from multiprocessing import Pool, cpu_count
+from functools import partial
+from dotenv import load_dotenv
+from config_loader import cfg
+
+from data.vector_db import get_pinecone_index, refresh_pinecone_index
+from retriever.retriever import HybridRetriever
+from retriever.generator import RAGGenerator
+from retriever.processor import ChunkProcessor
+from retriever.evaluator import RAGEvaluator
+from data.data_loader import load_cbt_book, get_book_stats
+from data.ingest import ingest_data, CHUNKING_TECHNIQUES
+
+# Import model fleet
+from models.llama_3_8b import Llama3_8B
+from models.mistral_7b import Mistral_7b
+from models.qwen_2_5 import Qwen2_5
+from models.deepseek_v3 import DeepSeek_V3
+from models.tiny_aya import TinyAya
+
+MODEL_MAP = {
+    "Llama-3-8B": Llama3_8B,
+    "Mistral-7B": Mistral_7b,
+    "Qwen-2.5": Qwen2_5,
+    "DeepSeek-V3": DeepSeek_V3,
+    "TinyAya": TinyAya
+}
+
+load_dotenv()
+
+
+def run_rag_for_technique(technique_name, query, index, encoder, models, evaluator, rag_engine):
+    """Run RAG pipeline for a specific chunking technique."""
+    
+    print(f"\n{'='*80}")
+    print(f"TECHNIQUE: {technique_name.upper()}")
+    print(f"{'='*80}")
+    
+    # Filter chunks by technique metadata
+    query_vector = encoder.encode(query).tolist()
+    
+    # Query with metadata filter for this technique - get more candidates for reranking
+    res = index.query(
+        vector=query_vector,
+        top_k=25,  
+        include_metadata=True,
+        filter={"technique": {"$eq": technique_name}}
+    )
+    
+    # Extract context chunks with URLs
+    all_candidates = []
+    chunk_urls = []
+    for match in res['matches']:
+        all_candidates.append(match['metadata']['text'])
+        chunk_urls.append(match['metadata'].get('url', ''))
+    
+    print(f"\nRetrieved {len(all_candidates)} candidate chunks for technique '{technique_name}'")
+    
+    if not all_candidates:
+        print(f"WARNING: No chunks found for technique '{technique_name}'")
+        return {}
+    
+    # Apply cross-encoder reranking to get top 5
+    # Use global reranker loaded once per worker
+    global _worker_reranker
+    pairs = [[query, chunk] for chunk in all_candidates]
+    scores = _worker_reranker.predict(pairs)
+    ranked = sorted(zip(all_candidates, chunk_urls, scores), key=lambda x: x[2], reverse=True)
+    context_chunks = [chunk for chunk, _, _ in ranked[:5]]
+    context_urls = [url for _, url, _ in ranked[:5]]
+    
+    print(f"After reranking: {len(context_chunks)} chunks (top 5)")
+    
+    # Print the final RAG context being passed to models (only once)
+    print(f"\n{'='*80}")
+    print(f"📚 FINAL RAG CONTEXT FOR TECHNIQUE '{technique_name.upper()}'")
+    print(f"{'='*80}")
+    for i, chunk in enumerate(context_chunks, 1):
+        print(f"\n[Chunk {i}] ({len(chunk)} chars):")
+        print(f"{'─'*60}")
+        print(chunk)
+        print(f"{'─'*60}")
+    print(f"\n{'='*80}")
+    
+    # Run model tournament for this technique
+    tournament_results = {}
+    
+    for name, model_inst in models.items():
+        print(f"\n{'-'*60}")
+        print(f"Model: {name}")
+        print(f"{'-'*60}")
+        try:
+            # Generation
+            answer = rag_engine.get_answer(
+                model_inst, query, context_chunks,
+                context_urls=context_urls,
+                temperature=cfg.gen['temperature']
+            )
+
+            print(f"\n{'─'*60}")
+            print(f"📝 FULL ANSWER from {name}:")
+            print(f"{'─'*60}")
+            print(answer)
+            print(f"{'─'*60}")
+
+            # Faithfulness Evaluation (strict=False reduces API calls from ~22 to ~3 per eval)
+            faith = evaluator.evaluate_faithfulness(answer, context_chunks, strict=False)
+            # Relevancy Evaluation
+            rel = evaluator.evaluate_relevancy(query, answer)
+
+            tournament_results[name] = {
+                "answer": answer,
+                "Faithfulness": faith['score'],
+                "Relevancy": rel['score'],
+                "Claims": faith['details'],
+                "context_chunks": context_chunks,
+                "context_urls": context_urls
+            }
+
+            print(f"\n📊 EVALUATION SCORES:")
+            print(f"  Faithfulness: {faith['score']:.1f}%")
+            print(f"  Relevancy: {rel['score']:.3f}")
+            print(f"  Combined: {faith['score'] + rel['score']:.3f}")
+
+        except Exception as e:
+            print(f"  Error evaluating {name}: {e}")
+            tournament_results[name] = {
+                "answer": "",
+                "Faithfulness": 0,
+                "Relevancy": 0,
+                "Claims": [],
+                "error": str(e),
+                "context_chunks": context_chunks,
+                "context_urls": context_urls
+            }
+    
+    return tournament_results
+
+
+def generate_findings_document(all_query_results, queries, output_file="rag_ablation_findings.md"):
+    """Generate detailed markdown document with findings from all techniques across all queries.
+    
+    Args:
+        all_query_results: Dict mapping query index to results dict
+        queries: List of all test queries
+        output_file: Path to output file
+    """
+    
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    
+    content = f"""# RAG Ablation Study Findings
+
+*Generated:* {timestamp}
+
+## Overview
+
+This document presents findings from a comparative analysis of 6 different chunking techniques 
+applied to a Cognitive Behavioral Therapy (CBT) book. Each technique was evaluated using 
+multiple LLM models with RAG (Retrieval-Augmented Generation) pipeline.
+
+## Test Queries
+
+"""
+    
+    for i, query in enumerate(queries, 1):
+        content += f"{i}. {query}\n"
+    
+    content += """
+## Chunking Techniques Evaluated
+
+1. *Fixed* - Fixed-size chunking (1000 chars, 100 overlap)
+2. *Sentence* - Sentence-level chunking (NLTK)
+3. *Paragraph* - Paragraph-level chunking (\\n\\n boundaries)
+4. *Semantic* - Semantic chunking (embedding similarity)
+5. *Recursive* - Recursive chunking (hierarchical separators)
+6. *Page* - Page-level chunking (--- Page markers)
+
+## Results by Technique (Aggregated Across All Queries)
+
+"""
+    
+    # Aggregate results across all queries
+    aggregated_results = {}
+    
+    for query_idx, query_results in all_query_results.items():
+        for technique_name, model_results in query_results.items():
+            if technique_name not in aggregated_results:
+                aggregated_results[technique_name] = {}
+            
+            for model_name, results in model_results.items():
+                if model_name not in aggregated_results[technique_name]:
+                    aggregated_results[technique_name][model_name] = {
+                        'Faithfulness': [],
+                        'Relevancy': [],
+                        'answers': [],
+                        'context_chunks': results.get('context_chunks', []),
+                        'context_urls': results.get('context_urls', [])
+                    }
+                
+                aggregated_results[technique_name][model_name]['Faithfulness'].append(results.get('Faithfulness', 0))
+                aggregated_results[technique_name][model_name]['Relevancy'].append(results.get('Relevancy', 0))
+                aggregated_results[technique_name][model_name]['answers'].append(results.get('answer', ''))
+    
+    # Add results for each technique
+    for technique_name, model_results in aggregated_results.items():
+        content += f"### {technique_name.upper()} Chunking\n\n"
+        
+        if not model_results:
+            content += "No results available for this technique.\n\n"
+            continue
+        
+        # Create results table with averaged scores
+        content += "| Model | Avg Faithfulness | Avg Relevancy | Avg Combined |\n"
+        content += "|-------|------------------|---------------|--------------|\n"
+        
+        for model_name, results in model_results.items():
+            avg_faith = sum(results['Faithfulness']) / len(results['Faithfulness']) if results['Faithfulness'] else 0
+            avg_rel = sum(results['Relevancy']) / len(results['Relevancy']) if results['Relevancy'] else 0
+            avg_combined = avg_faith + avg_rel
+            content += f"| {model_name} | {avg_faith:.1f}% | {avg_rel:.3f} | {avg_combined:.3f} |\n"
+        
+        # Find best model for this technique
+        if model_results:
+            best_model = max(
+                model_results.items(),
+                key=lambda x: (sum(x[1]['Faithfulness']) / len(x[1]['Faithfulness']) if x[1]['Faithfulness'] else 0) + 
+                              (sum(x[1]['Relevancy']) / len(x[1]['Relevancy']) if x[1]['Relevancy'] else 0)
+            )
+            best_name = best_model[0]
+            best_faith = sum(best_model[1]['Faithfulness']) / len(best_model[1]['Faithfulness']) if best_model[1]['Faithfulness'] else 0
+            best_rel = sum(best_model[1]['Relevancy']) / len(best_model[1]['Relevancy']) if best_model[1]['Relevancy'] else 0
+            
+            content += f"\n*Best Model:* {best_name} (Avg Faithfulness: {best_faith:.1f}%, Avg Relevancy: {best_rel:.3f})\n\n"
+        
+        # Show context chunks once per technique (not per model)
+        context_chunks = None
+        context_urls = None
+        for model_name, results in model_results.items():
+            if results.get('context_chunks'):
+                context_chunks = results['context_chunks']
+                context_urls = results.get('context_urls', [])
+                break
+        
+        if context_chunks:
+            content += "#### Context Chunks Used\n\n"
+            for i, chunk in enumerate(context_chunks, 1):
+                url = context_urls[i-1] if context_urls and i-1 < len(context_urls) else ""
+                if url:
+                    content += f"*Chunk {i}* ([Source]({url})):\n"
+                else:
+                    content += f"*Chunk {i}*:\n"
+                content += f"\n{chunk}\n\n\n"
+        
+        # Add detailed RAG results for each model
+        content += "#### Detailed RAG Results\n\n"
+        
+        for model_name, results in model_results.items():
+            answers = results.get('answers', [])
+            avg_faith = sum(results['Faithfulness']) / len(results['Faithfulness']) if results['Faithfulness'] else 0
+            avg_rel = sum(results['Relevancy']) / len(results['Relevancy']) if results['Relevancy'] else 0
+            
+            content += f"*{model_name}* (Avg Faithfulness: {avg_faith:.1f}%, Avg Relevancy: {avg_rel:.3f})\n\n"
+            
+            # Show answers from each query
+            for q_idx, answer in enumerate(answers):
+                content += f"📝 *Answer for Query {q_idx + 1}:*\n\n"
+                content += f"\n{answer}\n\n\n"
+            
+            content += "---\n\n"
+    
+    # Add comparative analysis
+    content += """## Comparative Analysis
+
+### Overall Performance Ranking (Across All Queries)
+
+| Rank | Technique | Avg Faithfulness | Avg Relevancy | Avg Combined |
+|------|-----------|------------------|---------------|--------------|
+"""
+    
+    # Calculate averages for each technique across all queries
+    technique_averages = {}
+    for technique_name, model_results in aggregated_results.items():
+        if model_results:
+            all_faith = []
+            all_rel = []
+            for model_name, results in model_results.items():
+                all_faith.extend(results['Faithfulness'])
+                all_rel.extend(results['Relevancy'])
+            
+            avg_faith = sum(all_faith) / len(all_faith) if all_faith else 0
+            avg_rel = sum(all_rel) / len(all_rel) if all_rel else 0
+            avg_combined = avg_faith + avg_rel
+            technique_averages[technique_name] = {
+                'faith': avg_faith,
+                'rel': avg_rel,
+                'combined': avg_combined
+            }
+    
+    # Sort by combined score
+    sorted_techniques = sorted(
+        technique_averages.items(),
+        key=lambda x: x[1]['combined'],
+        reverse=True
+    )
+    
+    for rank, (technique_name, averages) in enumerate(sorted_techniques, 1):
+        content += f"| {rank} | {technique_name} | {averages['faith']:.1f}% | {averages['rel']:.3f} | {averages['combined']:.3f} |\n"
+    
+    content += """
+### Key Findings
+
+"""
+    
+    if sorted_techniques:
+        best_technique = sorted_techniques[0][0]
+        worst_technique = sorted_techniques[-1][0]
+        
+        content += f"""
+1. *Best Performing Technique:* {best_technique}
+   - Achieved highest combined score across all models and queries
+   - Recommended for production RAG applications
+
+2. *Worst Performing Technique:* {worst_technique}
+   - Lower combined scores across models and queries
+   - May need optimization or different configuration
+
+3. *Model Consistency:* 
+   - Analyzed which models perform consistently across techniques
+   - Identified technique-specific model preferences
+
+"""
+    
+    content += """## Recommendations
+
+Based on the ablation study results:
+
+1. *Primary Recommendation:* Use the best-performing chunking technique for your specific use case
+2. *Hybrid Approach:* Consider combining techniques for different types of queries
+3. *Model Selection:* Choose models that perform well across multiple techniques
+4. *Parameter Tuning:* Optimize chunk sizes and overlaps based on document characteristics
+
+## Technical Details
+
+- *Embedding Model:* Jina embeddings (512 dimensions)
+- *Vector Database:* Pinecone (serverless, AWS us-east-1)
+- *Judge Model:* Openrouter Free models
+- *Retrieval:* Top 5 chunks per technique
+- *Evaluation Metrics:* Faithfulness (context grounding), Relevancy (query addressing)
+
+---
+
+This report was automatically generated by the RAG Ablation Study Pipeline.
+"""
+    
+    # Write to file
+    with open(output_file, 'w', encoding='utf-8') as f:
+        f.write(content)
+    
+    print(f"\nFindings document saved to: {output_file}")
+    return output_file
+
+
+# Global variables for worker processes
+_worker_proc = None
+_worker_evaluator = None
+_worker_models = None
+_worker_rag_engine = None
+_worker_reranker = None
+
+def init_worker(model_name, evaluator_config):
+    """Initialize models once per worker process."""
+    global _worker_proc, _worker_evaluator, _worker_models, _worker_rag_engine, _worker_reranker
+    
+    from retriever.processor import ChunkProcessor
+    from retriever.evaluator import RAGEvaluator
+    from retriever.generator import RAGGenerator
+    from sentence_transformers import CrossEncoder
+    from models.llama_3_8b import Llama3_8B
+    from models.mistral_7b import Mistral_7b
+    from models.qwen_2_5 import Qwen2_5
+    from models.deepseek_v3 import DeepSeek_V3
+    from models.tiny_aya import TinyAya
+    
+    MODEL_MAP = {
+        "Llama-3-8B": Llama3_8B,
+        "Mistral-7B": Mistral_7b,
+        "Qwen-2.5": Qwen2_5,
+        "DeepSeek-V3": DeepSeek_V3,
+        "TinyAya": TinyAya
+    }
+    
+    # Load embedding model once
+    _worker_proc = ChunkProcessor(model_name=model_name, verbose=False)
+    
+    # Initialize evaluator
+    _worker_evaluator = RAGEvaluator(
+        judge_model=evaluator_config['judge_model'],
+        embedding_model=_worker_proc.encoder,
+        api_key=evaluator_config['api_key']
+    )
+    
+    # Initialize models
+    hf_token = os.getenv("HF_TOKEN")
+    _worker_models = {name: MODEL_MAP[name](token=hf_token) for name in evaluator_config['model_list']}
+    
+    # Initialize RAG engine
+    _worker_rag_engine = RAGGenerator()
+    
+    # Load reranker once per worker
+    _worker_reranker = CrossEncoder('jinaai/jina-reranker-v1-tiny-en')
+
+
+def run_rag_for_technique_wrapper(args):
+    """Wrapper function for parallel execution."""
+    global _worker_proc, _worker_evaluator, _worker_models, _worker_rag_engine
+    
+    technique, query, index_name, pinecone_key = args
+    try:
+        # Create new connection in worker process
+        from data.vector_db import get_index_by_name
+        index = get_index_by_name(pinecone_key, index_name)
+        
+        return technique['name'], run_rag_for_technique(
+            technique_name=technique['name'],
+            query=query,
+            index=index,
+            encoder=_worker_proc.encoder,
+            models=_worker_models,
+            evaluator=_worker_evaluator,
+            rag_engine=_worker_rag_engine
+        )
+    except Exception as e:
+        import traceback
+        print(f"\n✗ Error processing technique {technique['name']}: {e}")
+        print(f"Full traceback:")
+        traceback.print_exc()
+        return technique['name'], {}
+
+
+def main():
+    """Main function to run RAG ablation study across all 6 chunking techniques."""
+    hf_token = os.getenv("HF_TOKEN")
+    pinecone_key = os.getenv("PINECONE_API_KEY")
+    openrouter_key = os.getenv("OPENROUTER_API_KEY")
+
+    # Verify environment variables
+    if not hf_token:
+        raise RuntimeError("HF_TOKEN not found in environment variables")
+    if not pinecone_key:
+        raise RuntimeError("PINECONE_API_KEY not found in environment variables")
+    if not openrouter_key:
+        raise RuntimeError("OPENROUTER_API_KEY not found in environment variables")
+
+    # Test queries
+    test_queries = [
+        "What is cognitive behavior therapy and how does it work?",
+        "What are the common cognitive distortions in CBT?",
+        "How does CBT help with anxiety and depression?"
+    ]
+
+    print("=" * 80)
+    print("RAG ABLATION STUDY - 6 CHUNKING TECHNIQUES")
+    print("=" * 80)
+    print(f"\nTest Queries:")
+    for i, q in enumerate(test_queries, 1):
+        print(f"  {i}. {q}")
+
+    # Step 1: Check if data already exists, skip ingestion if so
+    print("\n" + "=" * 80)
+    print("STEP 1: CHECKING/INGESTING DATA WITH ALL 6 TECHNIQUES")
+    print("=" * 80)
+
+    # Check if index already has data
+    from data.vector_db import get_index_by_name
+    index_name = f"{cfg.db['base_index_name']}-{cfg.processing['technique']}"
+    
+    print(f"\nChecking for existing index: {index_name}")
+    
+    try:
+        # Try to connect to existing index
+        print("Connecting to Pinecone...")
+        existing_index = get_index_by_name(pinecone_key, index_name)
+        print("Getting index stats...")
+        stats = existing_index.describe_index_stats()
+        existing_count = stats.get('total_vector_count', 0)
+        
+        if existing_count > 0:
+            print(f"\n✓ Found existing index with {existing_count} vectors")
+            print("Skipping ingestion - using existing data")
+            
+            # Initialize processor (this loads the embedding model)
+            print("Loading embedding model for retrieval...")
+            from retriever.processor import ChunkProcessor
+            proc = ChunkProcessor(model_name=cfg.processing['embedding_model'], verbose=False)
+            index = existing_index
+            all_chunks = []  # Empty since we're using existing data
+            final_chunks = []
+            print("✓ Processor initialized")
+        else:
+            print("\nIndex exists but is empty. Running full ingestion...")
+            all_chunks, final_chunks, proc, index = ingest_data()
+    except Exception as e:
+        print(f"\nIndex check failed: {e}")
+        print("Running full ingestion...")
+        all_chunks, final_chunks, proc, index = ingest_data()
+
+    print(f"\nTechniques to evaluate: {[tech['name'] for tech in CHUNKING_TECHNIQUES]}")
+
+    # Step 2: Initialize components
+    print("\n" + "=" * 80)
+    print("STEP 2: INITIALIZING COMPONENTS")
+    print("=" * 80)
+
+    # Initialize models
+    print("\nInitializing models...")
+    rag_engine = RAGGenerator()
+    models = {name: MODEL_MAP[name](token=hf_token) for name in cfg.model_list}
+
+    # Initialize evaluator
+    print("Initializing evaluator...")
+    if not openrouter_key:
+        raise RuntimeError("OPENROUTER_API_KEY not found in environment variables")
+    
+    evaluator = RAGEvaluator(
+        judge_model=cfg.gen['judge_model'],
+        embedding_model=proc.encoder,
+        api_key=openrouter_key
+    )
+
+    # Step 3: Run RAG for all techniques in parallel for all queries
+    print("\n" + "=" * 80)
+    print("STEP 3: RUNNING RAG FOR ALL 6 TECHNIQUES (IN PARALLEL)")
+    print("=" * 80)
+
+    # Prepare arguments for parallel execution
+    num_processes = min(cpu_count(), len(CHUNKING_TECHNIQUES))
+    print(f"\nUsing {num_processes} parallel processes for {len(CHUNKING_TECHNIQUES)} techniques")
+
+    # Run techniques in parallel for all queries
+    evaluator_config = {
+        'judge_model': cfg.gen['judge_model'],
+        'api_key': openrouter_key,
+        'model_list': cfg.model_list
+    }
+    
+    all_query_results = {}
+    
+    for query_idx, query in enumerate(test_queries):
+        print(f"\n{'='*80}")
+        print(f"PROCESSING QUERY {query_idx + 1}/{len(test_queries)}")
+        print(f"Query: {query}")
+        print(f"{'='*80}")
+        
+        with Pool(
+            processes=num_processes,
+            initializer=init_worker,
+            initargs=(cfg.processing['embedding_model'], evaluator_config)
+        ) as pool:
+            args_list = [
+                (technique, query, index_name, pinecone_key)
+                for technique in CHUNKING_TECHNIQUES
+            ]
+            results_list = pool.map(run_rag_for_technique_wrapper, args_list)
+
+        # Convert results to dictionary and store
+        query_results = {name: results for name, results in results_list}
+        all_query_results[query_idx] = query_results
+        
+        # Print quick summary for this query
+        print(f"\n{'='*80}")
+        print(f"QUERY {query_idx + 1} SUMMARY")
+        print(f"{'='*80}")
+        print(f"\n{'Technique':<15} {'Avg Faith':>12} {'Avg Rel':>12} {'Best Model':<20}")
+        print("-" * 60)
+
+        for technique_name, model_results in query_results.items():
+            if model_results:
+                avg_faith = sum(r.get('Faithfulness', 0) for r in model_results.values()) / len(model_results)
+                avg_rel = sum(r.get('Relevancy', 0) for r in model_results.values()) / len(model_results)
+                
+                # Find best model
+                best_model = max(
+                    model_results.items(),
+                    key=lambda x: x[1].get('Faithfulness', 0) + x[1].get('Relevancy', 0)
+                )
+                best_name = best_model[0]
+                
+                print(f"{technique_name:<15} {avg_faith:>11.1f}% {avg_rel:>12.3f} {best_name:<20}")
+            else:
+                print(f"{technique_name:<15} {'N/A':>12} {'N/A':>12} {'N/A':<20}")
+
+        print("-" * 60)
+
+    # Step 4: Generate findings document from all queries
+    print("\n" + "=" * 80)
+    print("STEP 4: GENERATING FINDINGS DOCUMENT")
+    print("=" * 80)
+
+    findings_file = generate_findings_document(all_query_results, test_queries)
+
+    # Step 5: Final summary
+    print("\n" + "=" * 80)
+    print("ABLATION STUDY COMPLETE - SUMMARY")
+    print("=" * 80)
+
+    print(f"\nQueries processed: {len(test_queries)}")
+    print(f"Techniques evaluated: {len(CHUNKING_TECHNIQUES)}")
+    print(f"Models tested: {len(cfg.model_list)}")
+    print(f"\nFindings document: {findings_file}")
+
+    # Print final summary across all queries
+    print("\n" + "-" * 60)
+    print(f"{'Technique':<15} {'Avg Faith':>12} {'Avg Rel':>12} {'Best Model':<20}")
+    print("-" * 60)
+
+    # Calculate averages across all queries
+    for tech_config in CHUNKING_TECHNIQUES:
+        tech_name = tech_config['name']
+        all_faith = []
+        all_rel = []
+        best_model_name = None
+        best_combined = 0
+        
+        for query_idx, query_results in all_query_results.items():
+            if tech_name in query_results and query_results[tech_name]:
+                model_results = query_results[tech_name]
+                for model_name, results in model_results.items():
+                    faith = results.get('Faithfulness', 0)
+                    rel = results.get('Relevancy', 0)
+                    combined = faith + rel
+                    all_faith.append(faith)
+                    all_rel.append(rel)
+                    
+                    if combined > best_combined:
+                        best_combined = combined
+                        best_model_name = model_name
+        
+        if all_faith:
+            avg_faith = sum(all_faith) / len(all_faith)
+            avg_rel = sum(all_rel) / len(all_rel)
+            print(f"{tech_name:<15} {avg_faith:>11.1f}% {avg_rel:>12.3f} {best_model_name or 'N/A':<20}")
+        else:
+            print(f"{tech_name:<15} {'N/A':>12} {'N/A':>12} {'N/A':<20}")
+
+    print("-" * 60)
+
+    print("\n✓ Ablation study complete!")
+    print(f"✓ Results saved to: {findings_file}")
+    print("\nYou can now analyze the findings document to compare chunking techniques.")
+
+    return all_query_results
+
+
+if __name__ == "__main__":
+    main()

main_easy.py

@@ -0,0 +1,104 @@
+import os
+import time
+from dotenv import load_dotenv
+from config_loader import cfg 
+
+# Optimized imports - only what we need for Retrieval and Generation
+from data.vector_db import get_index_by_name, load_chunks_from_pinecone # Using the new helper
+from retriever.retriever import HybridRetriever
+from retriever.generator import RAGGenerator
+from retriever.processor import ChunkProcessor
+from retriever.evaluator import RAGEvaluator
+
+# Model Fleet
+from models.llama_3_8b import Llama3_8B
+from models.mistral_7b import Mistral_7b
+from models.qwen_2_5 import Qwen2_5
+from models.deepseek_v3 import DeepSeek_V3
+from models.tiny_aya import TinyAya
+
+MODEL_MAP = {
+    "Llama-3-8B": Llama3_8B,
+    "Mistral-7B": Mistral_7b,
+    "Qwen-2.5": Qwen2_5,
+    "DeepSeek-V3": DeepSeek_V3,
+    "TinyAya": TinyAya
+}
+
+load_dotenv()
+
+def main():
+    hf_token = os.getenv("HF_TOKEN")
+    pinecone_key = os.getenv("PINECONE_API_KEY")
+    query = "How do transformers handle long sequences?"
+
+    # 1. Connect to Existing Index (No creation, no uploading)
+    # We use the slugified name directly or via config
+    index_name = f"{cfg.db['base_index_name']}-{cfg.processing['technique']}"
+    index = get_index_by_name(pinecone_key, index_name)
+
+    # 2. Setup Processor (Required for the Encoder/Embedding model)
+    proc = ChunkProcessor(model_name=cfg.processing['embedding_model'])
+
+    # 3. Load BM25 Corpus (The "Source of Truth")
+    # This replaces the entire data_loader/chunking block
+    # Note: On first run, this hits Pinecone. Use a pickle cache here for 0s delay.
+    print("🔄 Loading BM25 context from Pinecone metadata...")
+    final_chunks = load_chunks_from_pinecone(index) 
+
+    # 4. Retrieval Setup
+    retriever = HybridRetriever(final_chunks, proc.encoder)
+    
+    print(f"🔎 Searching via {cfg.retrieval['mode']} mode...")
+    context_chunks = retriever.search(
+        query, index,
+        mode=cfg.retrieval['mode'],
+        rerank_strategy=cfg.retrieval['rerank_strategy'],
+        use_mmr=cfg.retrieval['use_mmr'],
+        top_k=cfg.retrieval['top_k'],
+        final_k=cfg.retrieval['final_k']
+    )
+
+    # 5. Initialization of Contestants
+    rag_engine = RAGGenerator()
+    models = {name: MODEL_MAP[name](token=hf_token) for name in cfg.model_list}
+    
+    evaluator = RAGEvaluator(
+        judge_model=cfg.gen['judge_model'],
+        embedding_model=proc.encoder,
+        api_key=os.getenv("GROQ_API_KEY")
+    )
+
+    tournament_results = {}
+
+    # 6. Tournament Loop
+    for name, model_inst in models.items():
+        print(f"\n🏆 Tournament: {name} is generating...")
+        try:
+            # Generation
+            answer = rag_engine.get_answer(
+                model_inst, query, context_chunks, 
+                temperature=cfg.gen['temperature']
+            )
+            
+            # Faithfulness Evaluation
+            faith = evaluator.evaluate_faithfulness(answer, context_chunks)
+            # Relevancy Evaluation
+            rel = evaluator.evaluate_relevancy(query, answer)
+
+            tournament_results[name] = {
+                "Answer": answer[:100] + "...", # Preview
+                "Faithfulness": faith['score'],
+                "Relevancy": rel['score']
+            }
+            print(f"✅ {name} Score - Faith: {faith['score']} | Rel: {rel['score']}")
+            
+        except Exception as e:
+            print(f"❌ Error evaluating {name}: {e}")
+
+    print("\n--- Final Tournament Standings ---")
+    for name, scores in tournament_results.items():
+        print(f"{name}: F={scores['Faithfulness']}, R={scores['Relevancy']}")
+
+if __name__ == "__main__":
+    main()

models/deepseek_v3.py

@@ -0,0 +1,25 @@
+from huggingface_hub import InferenceClient
+
+class DeepSeek_V3:
+    def __init__(self, token):
+        self.client = InferenceClient(token=token)
+        self.model_id = "deepseek-ai/DeepSeek-V3"
+
+    def generate_stream(self, prompt, max_tokens=1500, temperature=0.1):
+        try:
+            for message in self.client.chat_completion(
+                model=self.model_id,
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=max_tokens,
+                temperature=temperature,
+                stream=True,
+            ):
+                if message.choices:
+                    content = message.choices[0].delta.content
+                    if content:
+                        yield content
+        except Exception as e:
+            yield f" DeepSeek API Busy: {e}"
+
+    def generate(self, prompt, max_tokens=500, temperature=0.1):
+        return "".join(self.generate_stream(prompt, max_tokens=max_tokens, temperature=temperature))

models/llama_3_8b.py

@@ -0,0 +1,22 @@
+from huggingface_hub import InferenceClient
+
+class Llama3_8B:
+    def __init__(self, token):
+        self.client = InferenceClient(token=token)
+        self.model_id = "meta-llama/Meta-Llama-3-8B-Instruct"
+
+    def generate_stream(self, prompt, max_tokens=1500, temperature=0.1):
+        for message in self.client.chat_completion(
+            model=self.model_id,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stream=True,
+        ):
+            if message.choices:
+                content = message.choices[0].delta.content
+                if content:
+                    yield content
+
+    def generate(self, prompt, max_tokens=500, temperature=0.1):
+        return "".join(self.generate_stream(prompt, max_tokens=max_tokens, temperature=temperature))

models/mistral_7b.py

@@ -0,0 +1,29 @@
+from huggingface_hub import InferenceClient
+import os
+
+class Mistral_7b:
+    def __init__(self, token):
+        self.client = InferenceClient(api_key=token)
+        # Provider-suffixed ids (e.g. :featherless-ai) are not valid HF repo ids.
+        # Keep a sane default and allow override via env for experimentation.
+        self.model_id = os.getenv("MISTRAL_MODEL_ID", "mistralai/Mistral-7B-Instruct-v0.2")
+
+    def generate_stream(self, prompt, max_tokens=1500, temperature=0.1):
+        try:
+            stream = self.client.chat.completions.create(
+                model=self.model_id,
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=max_tokens,
+                temperature=temperature,
+                stream=True,
+            )
+            for chunk in stream:
+                if chunk.choices and chunk.choices[0].delta.content:
+                    content = chunk.choices[0].delta.content
+                    yield content
+
+        except Exception as e:
+            yield f" Mistral Featherless Error: {e}"
+
+    def generate(self, prompt, max_tokens=500, temperature=0.1):
+        return "".join(self.generate_stream(prompt, max_tokens=max_tokens, temperature=temperature))

models/qwen_2_5.py

@@ -0,0 +1,22 @@
+from huggingface_hub import InferenceClient
+
+class Qwen2_5:
+    def __init__(self, token):
+        self.client = InferenceClient(token=token)
+        self.model_id = "Qwen/Qwen2.5-72B-Instruct"
+
+    def generate_stream(self, prompt, max_tokens=1500, temperature=0.1):
+        for message in self.client.chat_completion(
+            model=self.model_id,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stream=True,
+        ):
+            if message.choices:
+                content = message.choices[0].delta.content
+                if content:
+                    yield content
+
+    def generate(self, prompt, max_tokens=500, temperature=0.1):
+        return "".join(self.generate_stream(prompt, max_tokens=max_tokens, temperature=temperature))

models/tiny_aya.py

@@ -0,0 +1,25 @@
+from huggingface_hub import InferenceClient
+
+class TinyAya:
+    def __init__(self, token):
+        self.client = InferenceClient(token=token)
+        self.model_id = "CohereLabs/tiny-aya-global"
+
+    def generate_stream(self, prompt, max_tokens=1500, temperature=0.1):
+        try:
+            for message in self.client.chat_completion(
+                model=self.model_id,
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=max_tokens,
+                temperature=temperature,
+                stream=True,
+            ):
+                if message.choices:
+                    content = message.choices[0].delta.content
+                    if content:
+                        yield content
+        except Exception as e:
+            yield f" TinyAya Error: {e}"
+
+    def generate(self, prompt, max_tokens=500, temperature=0.1):
+        return "".join(self.generate_stream(prompt, max_tokens=max_tokens, temperature=temperature))

requirements.txt

@@ -0,0 +1,97 @@
+aiohappyeyeballs==2.6.1
+aiohttp==3.13.3
+aiosignal==1.4.0
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.12.1
+arxiv==2.4.1
+attrs==26.1.0
+certifi==2026.2.25
+charset-normalizer==3.4.6
+click==8.3.1
+colorama==0.4.6
+dataclasses-json==0.6.7
+feedparser==6.0.12
+fastapi==0.121.1
+filelock==3.25.2
+frozenlist==1.8.0
+fsspec==2026.2.0
+greenlet==3.3.2
+h11==0.16.0
+hf-xet==1.4.2
+httpcore==1.0.9
+httpx==0.28.1
+httpx-sse==0.4.3
+huggingface_hub==0.36.0
+idna==3.11
+Jinja2==3.1.6
+joblib==1.5.3
+jsonpatch==1.33
+jsonpointer==3.1.1
+langchain-classic==1.0.3
+langchain-community==0.4.1
+langchain-core==1.2.21
+langchain-experimental==0.4.1
+langchain-huggingface==1.2.1
+langchain-text-splitters==1.1.1
+langsmith==0.7.22
+markdown-it-py==4.0.0
+MarkupSafe==3.0.3
+marshmallow==3.26.2
+mdurl==0.1.2
+mpmath==1.3.0
+multidict==6.7.1
+mypy_extensions==1.1.0
+networkx==3.6.1
+nltk==3.9.4
+numpy==2.4.3
+orjson==3.11.7
+packaging==24.2
+pandas==3.0.1
+pinecone==8.1.0
+pinecone-plugin-assistant==3.0.2
+pinecone-plugin-interface==0.0.7
+propcache==0.4.1
+pydantic==2.12.5
+pydantic-settings==2.13.1
+pydantic_core==2.41.5
+Pygments==2.19.2
+PyMuPDF==1.27.2.2
+python-dateutil==2.9.0.post0
+python-dotenv==1.2.2
+PyYAML==6.0.3
+rank-bm25==0.2.2
+regex==2026.2.28
+requests==2.32.5
+requests-toolbelt==1.0.0
+rich==14.3.3
+safetensors==0.7.0
+scikit-learn==1.8.0
+scipy==1.17.1
+sentence-transformers==5.3.0
+setuptools==81.0.0
+sgmllib3k==1.0.0
+shellingham==1.5.4
+six==1.17.0
+SQLAlchemy==2.0.48
+sympy==1.14.0
+tenacity==9.1.4
+threadpoolctl==3.6.0
+tokenizers==0.22.2
+torch==2.11.0
+tqdm==4.67.3
+transformers==4.57.1
+typer==0.24.1
+typing-inspect==0.9.0
+typing-inspection==0.4.2
+typing_extensions==4.15.0
+tzdata==2025.3
+urllib3==2.6.3
+uvicorn==0.38.0
+uuid_utils==0.14.1
+xxhash==3.6.0
+yarl==1.23.0
+zstandard==0.25.0
+groq==1.1.2
+jiter==0.13.0
+openai==2.30.0

retriever/evaluator.py

@@ -0,0 +1,331 @@
+import re
+import numpy as np
+from sklearn.metrics.pairwise import cosine_similarity
+from openai import OpenAI
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+
+# ------------------------------------------------------------------
+# OpenRouter Judge Wrapper
+# ------------------------------------------------------------------
+
+class GroqJudge:
+    def __init__(self, api_key: str, model: str =    "deepseek/deepseek-v3.2",):
+        """
+        Wraps OpenRouter's chat completions to match the .generate(prompt) interface
+        expected by RAGEvaluator.
+
+        Args:
+            api_key: Your OpenRouter API key (https://openrouter.ai)
+            model:   OpenRouter model to use (primary model with fallback support)
+        """
+        self.client = OpenAI(
+            base_url="https://openrouter.ai/api/v1",
+            api_key=api_key,
+        )
+        self.model = model
+        
+        # Fallback models in order of preference (OpenRouter free models)
+        self.fallback_models = [
+            "deepseek/deepseek-v3.2",
+            "qwen/qwen3.6-plus-preview:free",
+            "stepfun/step-3.5-flash:free",
+            "nvidia/nemotron-3-super-120b-a12b:free",
+            "z-ai/glm-4.5-air:free",
+            "nvidia/nemotron-3-nano-30b-a3b:free",
+            "arcee-ai/trinity-mini:free",
+            "xiaomi/mimo-v2-flash"
+        ]
+
+    def generate(self, prompt: str) -> str:
+        """Generate response with fallback support for multiple models."""
+        last_error = None
+        
+        # Try primary model first, then fallbacks
+        models_to_try = [self.model] + [m for m in self.fallback_models if m != self.model]
+        
+        for model_name in models_to_try:
+               
+           
+            try:
+                response = self.client.chat.completions.create(
+                    model=model_name,
+                    messages=[{"role": "user", "content": prompt}],
+                )
+                content = response.choices[0].message.content
+                if content is None:
+                    raise ValueError(f"Model {model_name} returned None content")
+                return content.strip()
+            except Exception as e:
+                last_error = e
+                # If rate limited or model unavailable, try next model
+                if "429" in str(e) or "rate_limit" in str(e).lower() or "model" in str(e).lower():
+                    continue
+                # For other errors, raise immediately
+                raise
+        
+        # If all models fail, raise the last error
+        raise last_error
+
+
+# ------------------------------------------------------------------
+# RAG Evaluator
+# ------------------------------------------------------------------
+
+class RAGEvaluator:
+    def __init__(self, judge_model: str, embedding_model, api_key: str, verbose=True):
+        """
+        judge_model:     Model name string passed to OpenRouterJudge, must match cfg.gen['judge_model']
+                         e.g. "stepfun/step-3.5-flash:free", "nvidia/nemotron-3-super-120b-a12b:free"
+        embedding_model: The proc.encoder (SentenceTransformer) for similarity checks
+        api_key:         OpenRouter API key (https://openrouter.ai)
+        verbose:         If True, prints progress via internal helpers
+        """
+        self.judge = GroqJudge(api_key=api_key, model=judge_model)
+        self.encoder = embedding_model
+        self.verbose = verbose
+
+    # ------------------------------------------------------------------
+    # 1. FAITHFULNESS: Claim Extraction & Verification
+    # ------------------------------------------------------------------
+
+    def evaluate_faithfulness(self, answer: str, context_list: list[str], strict: bool = True) -> dict:
+        """
+        Args:
+            strict: If True, verifies each claim against chunks individually
+                    (more API calls but catches vague batch verdicts).
+                    If False, uses single batched verification call.
+        """
+        if self.verbose:
+            self._print_extraction_header(len(answer), strict=strict)
+
+        # --- Step A: Extraction ---
+        extraction_prompt = (
+            "Extract a list of independent factual claims from the following answer.\n"
+            "Rules:\n"
+            "- Each claim must be specific and verifiable — include numbers, names, or concrete details where present\n"
+            "- Vague claims like 'the model performs well' or 'this improves results' are NOT acceptable\n"
+            "- Do NOT include claims about what the context does or does not contain\n"
+            "- Do NOT include introductory text, numbering, or bullet points\n"
+            "- Do NOT rephrase or merge claims\n"
+            "- One claim per line only\n\n"
+            f"Answer: {answer}"
+        )
+        raw_claims = self.judge.generate(extraction_prompt)
+
+        # Filter out short lines, preamble, and lines ending with ':'
+        claims = [
+            c.strip() for c in raw_claims.split('\n')
+            if len(c.strip()) > 20 and not c.strip().endswith(':')
+        ]
+
+        if not claims:
+            return {"score": 0, "details": []}
+
+        # --- Step B: Verification ---
+        if strict:
+            # Per-chunk: claim must be explicitly supported by at least one chunk
+            # Parallelize across claims as well
+            def verify_claim_wrapper(args):
+                i, claim = args
+                return i, self._verify_claim_against_chunks(claim, context_list)
+            
+            with ThreadPoolExecutor(max_workers=min(len(claims), 5)) as executor:
+                futures = [executor.submit(verify_claim_wrapper, (i, claim)) for i, claim in enumerate(claims)]
+                verdicts = {i: result for future in as_completed(futures) for i, result in [future.result()]}
+        else:
+            # Batch: all chunks joined, strict burden-of-proof prompt
+            combined_context = "\n".join(context_list)
+            if len(combined_context) > 6000:
+                combined_context = combined_context[:6000]
+
+            claims_formatted = "\n".join([f"{i+1}. {c}" for i, c in enumerate(claims)])
+
+            batch_prompt = (
+                f"Context:\n{combined_context}\n\n"
+                f"For each claim, respond YES only if the claim is EXPLICITLY and DIRECTLY "
+                f"supported by the context above. Respond NO if the claim is inferred, assumed, "
+                f"or not clearly stated in the context.\n\n"
+                f"Format strictly as:\n"
+                f"1: YES\n"
+                f"2: NO\n\n"
+                f"Claims:\n{claims_formatted}"
+            )
+            raw_verdicts = self.judge.generate(batch_prompt)
+
+            verdicts = {}
+            for line in raw_verdicts.split('\n'):
+                match = re.match(r'(\d+)\s*:\s*(YES|NO)', line.strip().upper())
+                if match:
+                    verdicts[int(match.group(1)) - 1] = match.group(2) == "YES"
+
+        # --- Step C: Scoring & Details ---
+        verified_count = 0
+        details = []
+        for i, claim in enumerate(claims):
+            is_supported = verdicts.get(i, False)
+            if is_supported:
+                verified_count += 1
+            details.append({
+                "claim": claim,
+                "verdict": "Supported" if is_supported else "Not Supported"
+            })
+
+        score = (verified_count / len(claims)) * 100
+
+        if self.verbose:
+            self._print_faithfulness_results(claims, details, score)
+
+        return {"score": score, "details": details}
+
+    def _verify_claim_against_chunks(self, claim: str, context_list: list[str]) -> bool:
+        """Verify a single claim against each chunk individually. Returns True if any chunk supports it."""
+        def verify_single_chunk(chunk):
+            prompt = (
+                f"Context:\n{chunk}\n\n"
+                f"Claim: {claim}\n\n"
+                f"Is this claim EXPLICITLY and DIRECTLY stated in the context above? "
+                f"Do not infer or assume. Respond with YES or NO only."
+            )
+            result = self.judge.generate(prompt)
+            return "YES" in result.upper()
+        
+        # Use ThreadPoolExecutor for parallel verification
+        with ThreadPoolExecutor(max_workers=min(len(context_list), 5)) as executor:
+            futures = [executor.submit(verify_single_chunk, chunk) for chunk in context_list]
+            for future in as_completed(futures):
+                if future.result():
+                    return True
+        return False
+
+    # ------------------------------------------------------------------
+    # 2. RELEVANCY: Alternate Query Generation
+    # ------------------------------------------------------------------
+
+    def evaluate_relevancy(self, query: str, answer: str) -> dict:
+        if self.verbose:
+            self._print_relevancy_header()
+
+        # --- Step A: Generation ---
+        # Explicitly ask the judge NOT to rephrase the original query
+        gen_prompt = (
+            f"Generate 3 distinct questions that the following answer addresses.\n"
+            f"Rules:\n"
+            f"- Do NOT rephrase or repeat this question: '{query}'\n"
+            f"- Each question must end with a '?'\n"
+            f"- One question per line, no numbering or bullet points\n\n"
+            f"Answer: {answer}"
+        )
+        raw_gen = self.judge.generate(gen_prompt)
+
+        # Filter by length rather than just '?' presence
+        gen_queries = [
+            q.strip() for q in raw_gen.split('\n')
+            if len(q.strip()) > 10
+        ][:3]
+
+        if not gen_queries:
+            return {"score": 0, "queries": []}
+
+        # --- Step B: Similarity (single batched encode call) ---
+        all_vecs = self.encoder.encode([query] + gen_queries)
+        original_vec = all_vecs[0:1]
+        generated_vecs = all_vecs[1:]
+
+        similarities = cosine_similarity(original_vec, generated_vecs)[0]
+        avg_score = float(np.mean(similarities))
+
+        if self.verbose:
+            self._print_relevancy_results(query, gen_queries, similarities, avg_score)
+
+        return {"score": avg_score, "queries": gen_queries}
+
+    # ------------------------------------------------------------------
+    # 3. DATASET-LEVEL EVALUATION
+    # ------------------------------------------------------------------
+
+    def evaluate_dataset(self, test_cases: list[dict], strict: bool = False) -> dict:
+        """
+        Runs faithfulness + relevancy over a full test set and aggregates results.
+
+        Args:
+            test_cases: List of dicts, each with keys:
+                        - "query":    str
+                        - "answer":   str
+                        - "contexts": List[str]
+            strict:     If True, passes strict=True to evaluate_faithfulness
+                        (per-chunk verification, more API calls, harder to pass)
+
+        Returns:
+            {
+                "avg_faithfulness": float,
+                "avg_relevancy":    float,
+                "per_query":        List[dict]
+            }
+        """
+        faithfulness_scores = []
+        relevancy_scores = []
+        per_query = []
+
+        for i, case in enumerate(test_cases):
+            if self.verbose:
+                print(f"\n{'='*60}")
+                print(f"Query {i+1}/{len(test_cases)}: {case['query']}")
+                print('='*60)
+
+            f_result = self.evaluate_faithfulness(case['answer'], case['contexts'], strict=strict)
+            r_result = self.evaluate_relevancy(case['query'], case['answer'])
+
+            faithfulness_scores.append(f_result['score'])
+            relevancy_scores.append(r_result['score'])
+            per_query.append({
+                "query":       case['query'],
+                "faithfulness": f_result,
+                "relevancy":    r_result,
+            })
+
+        results = {
+            "avg_faithfulness": float(np.mean(faithfulness_scores)),
+            "avg_relevancy":    float(np.mean(relevancy_scores)),
+            "per_query":        per_query,
+        }
+
+        if self.verbose:
+            self._print_dataset_summary(results)
+
+        return results
+
+    # ------------------------------------------------------------------
+    # 4. PRINT HELPERS
+    # ------------------------------------------------------------------
+
+    def _print_extraction_header(self, length, strict=False):
+        mode = "strict per-chunk" if strict else "batch"
+        print(f"\n[EVAL] Analyzing Faithfulness ({mode})...")
+        print(f"      - Extracting claims from answer ({length} chars)")
+
+    def _print_faithfulness_results(self, claims, details, score):
+        print(f"      - Verifying {len(claims)} claims against context...")
+        for i, detail in enumerate(details):
+            status = "✅" if "Yes" in detail['verdict'] else "❌"
+            print(f"        {status} Claim {i+1}: {detail['claim'][:75]}...")
+        print(f"      🎯 Faithfulness Score: {score:.1f}%")
+
+    def _print_relevancy_header(self):
+        print(f"\n[EVAL] Analyzing Relevancy...")
+        print(f"      - Generating 3 distinct questions addressed by the answer")
+
+    def _print_relevancy_results(self, query, gen_queries, similarities, avg):
+        print(f"      - Comparing to original query: '{query}'")
+        for i, (q, sim) in enumerate(zip(gen_queries, similarities)):
+            print(f"        Q{i+1}: {q} (Sim: {sim:.2f})")
+        print(f"      🎯 Average Relevancy: {avg:.2f}")
+
+    def _print_dataset_summary(self, results):
+        print(f"\n{'='*60}")
+        print(f"  DATASET EVALUATION SUMMARY")
+        print(f"{'='*60}")
+        print(f"  Avg Faithfulness : {results['avg_faithfulness']:.1f}%")
+        print(f"  Avg Relevancy    : {results['avg_relevancy']:.2f}")
+        print(f"  Queries Evaluated: {len(results['per_query'])}")
+        print(f"{'='*60}")

retriever/generator.py

@@ -0,0 +1,45 @@
+#changed the prompt to output as markdown, plus some formating details
+#also added get answer stream for incremental token rendering on the frontend
+# --@Qamar
+class RAGGenerator:
+    def generate_prompt(self, query, retrieved_contexts, context_urls=None):
+        if context_urls:
+            context_text = "\n\n".join([f"[Source {i+1}] {url}: {c}" for i, (c, url) in enumerate(zip(retrieved_contexts, context_urls))])
+        else:
+            context_text = "\n\n".join([f"[Source {i+1}]: {c}" for i, c in enumerate(retrieved_contexts)])
+        
+        return f"""You are a specialized Cognitive Behavioral Therapy (CBT) assistant. Your task is to provide accurate, clinical, and structured answers based ONLY on the provided textbook excerpts.
+
+INSTRUCTIONS:
+1. Use the provided Sources to answer the question.
+2. CITATIONS: You must cite the sources used in your answer (e.g., "CBT is based on the cognitive model [Source 1]").
+3. FORMAT: Use clear headers and bullet points for complex explanations.
+4. GROUNDING: If the sources do not contain the answer, explicitly state: "The provided excerpts from the textbook do not contain information to answer this specific question." Do not use your own internal knowledge.
+5. TONE: Maintain a professional, empathetic, and academic tone.
+
+RETRIVED TEXTBOOK CONTEXT:
+{context_text}
+
+USER QUESTION: {query}
+
+ACADEMIC ANSWER (WITH CITATIONS):"""
+
+    def get_answer(self, model_instance, query, retrieved_contexts, context_urls=None, **kwargs):
+        """Uses a specific model instance to generate the final answer."""
+        prompt = self.generate_prompt(query, retrieved_contexts, context_urls)    
+        return model_instance.generate(prompt, **kwargs)
+
+    def get_answer_stream(self, model_instance, query, retrieved_contexts, context_urls=None, **kwargs):
+        """Streams model output token-by-token for incremental UI updates."""
+        prompt = self.generate_prompt(query, retrieved_contexts, context_urls)
+
+        if hasattr(model_instance, "generate_stream"):
+            for token in model_instance.generate_stream(prompt, **kwargs):
+                if token:
+                    yield token
+            return
+
+        # Fallback for model wrappers that only expose sync generation.
+        answer = model_instance.generate(prompt, **kwargs)
+        if answer:
+            yield answer

retriever/processor.py

@@ -0,0 +1,288 @@
+from langchain_text_splitters import (
+    RecursiveCharacterTextSplitter, 
+    CharacterTextSplitter,
+    SentenceTransformersTokenTextSplitter,
+    NLTKTextSplitter
+)
+from langchain_experimental.text_splitter import SemanticChunker
+from langchain_huggingface import HuggingFaceEmbeddings
+from sentence_transformers import SentenceTransformer
+from typing import List, Dict, Any, Optional
+import nltk
+nltk.download('punkt_tab', quiet=True)
+import pandas as pd
+import re
+
+
+class MarkdownTextSplitter:
+    """
+    Custom markdown header chunking strategy.
+    
+    Splits text by headers in a hierarchical manner:
+    - First checks h1 (#) headers
+    - If h1 content <= max_chars, accepts it as a chunk
+    - If h1 content > max_chars, splits into h2 headers
+    - If any h2 > max_chars, splits into h3, and so on
+    """
+    
+    def __init__(self, max_chars: int = 4000):
+        self.max_chars = max_chars
+        self.headers = ["\n# ", "\n## ", "\n### ", "\n#### "]
+    
+    def split_text(self, text: str) -> List[str]:
+        """Split text using markdown header hierarchy."""
+        return self._split_by_header(text, 0)
+    
+    def _split_by_header(self, content: str, header_level: int) -> List[str]:
+        """
+        Recursively split content by header levels.
+        
+        Args:
+            content: The text content to split
+            header_level: Current header level (0=h1, 1=h2, etc.)
+            
+        Returns:
+            List of text chunks
+        """
+        # If content is within limit, return it as is
+        if len(content) <= self.max_chars:
+            return [content]
+        
+        # If we've exhausted all header levels, return as single chunk
+        if header_level >= len(self.headers):
+            return [content]
+        
+        # Split by current header level
+        header = self.headers[header_level]
+        parts = re.split(f'(?={re.escape(header)})', content)
+        
+        # If no split occurred (no headers found at this level), try next level
+        if len(parts) == 1:
+            return self._split_by_header(content, header_level + 1)
+        
+        result = []
+        accumulated = ""
+        
+        for i, part in enumerate(parts):
+            # If this single part is too large, recursively split it with next header level
+            if len(part) > self.max_chars:
+                # First, flush any accumulated content
+                if accumulated:
+                    result.append(accumulated)
+                    accumulated = ""
+                # Then recursively split this large part with deeper headers
+                result.extend(self._split_by_header(part, header_level + 1))
+            # If adding this part would exceed limit, flush accumulated and start new
+            elif accumulated and len(accumulated) + len(part) > self.max_chars:
+                result.append(accumulated)
+                accumulated = part
+            # Accumulate parts that fit together
+            else:
+                accumulated += part
+        
+        # Don't forget the last accumulated part
+        if accumulated:
+            result.append(accumulated)
+        
+        return result
+
+
+class ChunkProcessor:
+    def __init__(self, model_name='all-MiniLM-L6-v2', verbose: bool = True, load_hf_embeddings: bool = False):
+        self.model_name = model_name
+        self._use_remote_code = self._requires_remote_code(model_name)
+        st_kwargs = {"trust_remote_code": True} if self._use_remote_code else {}
+        self.encoder = SentenceTransformer(model_name, **st_kwargs)
+        self.verbose = verbose
+        hf_kwargs = {"model_kwargs": {"trust_remote_code": True}} if self._use_remote_code else {}
+        self.hf_embeddings = HuggingFaceEmbeddings(model_name=model_name, **hf_kwargs) if load_hf_embeddings else None
+
+    def _requires_remote_code(self, model_name: str) -> bool:
+        normalized = (model_name or "").strip().lower()
+        return normalized.startswith("jinaai/")
+
+    def _get_hf_embeddings(self):
+        if self.hf_embeddings is None:
+            hf_kwargs = {"model_kwargs": {"trust_remote_code": True}} if self._use_remote_code else {}
+            self.hf_embeddings = HuggingFaceEmbeddings(model_name=self.model_name, **hf_kwargs)
+        return self.hf_embeddings
+
+    # ------------------------------------------------------------------
+    # Splitters
+    # ------------------------------------------------------------------
+
+    def get_splitter(self, technique: str, chunk_size: int = 500, chunk_overlap: int = 50, **kwargs):
+        """
+        Factory method to return different chunking strategies.
+
+        Strategies:
+        - "fixed":     Character-based, may split mid-sentence
+        - "recursive": Recursive character splitting with hierarchical separators
+        - "character": Character-based splitting on paragraph boundaries
+        - "paragraph": Paragraph-level splitting on \\n\\n boundaries
+        - "sentence":  Sliding window over NLTK sentences
+        - "semantic":  Embedding-based semantic chunking
+        - "page":      Page-level splitting on page markers
+        """
+        if technique == "fixed":
+            return CharacterTextSplitter(
+                separator=kwargs.get('separator', ""),
+                chunk_size=chunk_size,
+                chunk_overlap=chunk_overlap,
+                length_function=len,
+                is_separator_regex=False
+            )
+
+        elif technique == "recursive":
+            return RecursiveCharacterTextSplitter(
+                chunk_size=chunk_size,
+                chunk_overlap=chunk_overlap,
+                separators=kwargs.get('separators', ["\n\n", "\n", ". ", "! ", "? ", "; ", ", ", " ", ""]),
+                length_function=len,
+                keep_separator=kwargs.get('keep_separator', True)
+            )
+
+        elif technique == "character":
+            return CharacterTextSplitter(
+                separator=kwargs.get('separator', "\n\n"),
+                chunk_size=chunk_size,
+                chunk_overlap=chunk_overlap,
+                length_function=len,
+                is_separator_regex=False
+            )
+
+        elif technique == "paragraph":
+            # Paragraph-level chunking using paragraph breaks
+            return CharacterTextSplitter(
+                separator=kwargs.get('separator', "\n\n"),
+                chunk_size=chunk_size,
+                chunk_overlap=chunk_overlap,
+                length_function=len,
+                is_separator_regex=False
+            )
+
+        elif technique == "sentence":
+            # sentence-level chunking using NLTK
+            return NLTKTextSplitter(
+                chunk_size=chunk_size,
+                chunk_overlap=chunk_overlap,
+                separator="\n"
+            )  
+
+        elif technique == "semantic":
+            return SemanticChunker(
+                self._get_hf_embeddings(),
+                breakpoint_threshold_type=kwargs.get('breakpoint_threshold_type', "percentile"),
+                # Using 70 because 95 was giving way too big chunks
+                breakpoint_threshold_amount=kwargs.get('breakpoint_threshold_amount', 70)
+            )
+
+        elif technique == "page":
+            # Page-level chunking using page markers
+            return CharacterTextSplitter(
+                separator=kwargs.get('separator', "--- Page"),
+                chunk_size=chunk_size,
+                chunk_overlap=chunk_overlap,
+                length_function=len,
+                is_separator_regex=False
+            )
+
+        elif technique == "markdown":
+            # Markdown header chunking - splits by headers with max char limit
+            return MarkdownTextSplitter(max_chars=chunk_size)
+
+        else:
+            raise ValueError(f"Technique '{technique}' is not supported. Choose from: fixed, recursive, character, paragraph, sentence, semantic, page, markdown")
+
+    # ------------------------------------------------------------------
+    # Processing
+    # ------------------------------------------------------------------
+
+    def process(self, df: pd.DataFrame, technique: str = "recursive", chunk_size: int = 500,
+                chunk_overlap: int = 50, max_docs: Optional[int] = 5,
+                verbose: Optional[bool] = None, **kwargs) -> List[Dict[str, Any]]:
+        """
+        Processes a DataFrame into vector-ready chunks.
+
+        Args:
+            df:            DataFrame with columns: id, title, url, full_text
+            technique:     Chunking strategy to use
+            chunk_size:    Maximum size of each chunk in characters
+            chunk_overlap: Overlap between consecutive chunks
+            max_docs:      Number of documents to process (None for all)
+            verbose:       Override instance verbose setting
+            **kwargs:      Additional arguments passed to the splitter
+
+        Returns:
+            List of chunk dicts with embeddings and metadata
+        """
+        should_print = verbose if verbose is not None else self.verbose
+
+        required_cols = ['id', 'title', 'url', 'full_text']
+        missing_cols = [col for col in required_cols if col not in df.columns]
+        if missing_cols:
+            raise ValueError(f"DataFrame missing required columns: {missing_cols}")
+
+        splitter = self.get_splitter(technique, chunk_size, chunk_overlap, **kwargs)
+        subset_df = df.head(max_docs) if max_docs else df
+        processed_chunks = []
+
+        for _, row in subset_df.iterrows():
+            if should_print:
+                self._print_document_header(row['title'], row['url'], technique, chunk_size, chunk_overlap)
+
+            raw_chunks = splitter.split_text(row['full_text'])
+
+            for i, text in enumerate(raw_chunks):
+                content = text.page_content if hasattr(text, 'page_content') else text
+
+                if should_print:
+                    self._print_chunk(i, content)
+
+                processed_chunks.append({
+                    "id": f"{row['id']}-chunk-{i}",
+                    "values": self.encoder.encode(content).tolist(),
+                    "metadata": {
+                        "title": row['title'],
+                        "text": content,
+                        "url": row['url'],
+                        "chunk_index": i,
+                        "technique": technique,
+                        "chunk_size": len(content),
+                        "total_chunks": len(raw_chunks)
+                    }
+                })
+
+            if should_print:
+                self._print_document_summary(len(raw_chunks))
+
+        if should_print:
+            self._print_processing_summary(len(subset_df), processed_chunks)
+
+        return processed_chunks
+
+
+    # ------------------------------------------------------------------
+    # Printing
+    # ------------------------------------------------------------------
+
+    def _print_document_header(self, title, url, technique, chunk_size, chunk_overlap):
+        print("\n" + "="*80)
+        print(f"DOCUMENT: {title}")
+        print(f"URL: {url}")
+        print(f"Technique: {technique.upper()} | Chunk Size: {chunk_size} | Overlap: {chunk_overlap}")
+        print("-" * 80)
+
+    def _print_chunk(self, index, content):
+        print(f"\n[Chunk {index}] ({len(content)} chars):")
+        print(f"   {content}")
+
+    def _print_document_summary(self, num_chunks):
+        print(f"Total Chunks Generated: {num_chunks}")
+        print("="*80)
+
+    def _print_processing_summary(self, num_docs, processed_chunks):
+        print(f"\nFinished processing {num_docs} documents into {len(processed_chunks)} chunks.")
+        if processed_chunks:
+            avg = sum(c['metadata']['chunk_size'] for c in processed_chunks) / len(processed_chunks)
+            print(f"Average chunk size: {avg:.0f} chars")

retriever/retriever.py

@@ -0,0 +1,354 @@
+import numpy as np
+import time
+import re
+from rank_bm25 import BM25Okapi
+from sklearn.metrics.pairwise import cosine_similarity
+from typing import Optional, List
+
+# changed mmr to return final k, as a param, prev was hardcoded to 3
+# --@Qamare
+
+# Try to import FlashRank for CPU optimization, fallback to sentence-transformers
+try:
+    from flashrank import Ranker, RerankRequest
+    FLASHRANK_AVAILABLE = True
+except ImportError:
+    from sentence_transformers import CrossEncoder
+    FLASHRANK_AVAILABLE = False
+
+class HybridRetriever:
+    def __init__(self, final_chunks, embed_model, rerank_model_name='jinaai/jina-reranker-v1-tiny-en', verbose: bool = True):
+        self.final_chunks = final_chunks
+        self.embed_model = embed_model
+        self.verbose = verbose
+        self.rerank_model_name = self._normalize_rerank_model_name(rerank_model_name)
+        
+        # Use FlashRank if available (faster on CPU), otherwise fallback to sentence-transformers
+        if FLASHRANK_AVAILABLE:
+            try:
+                self.rerank_model = Ranker(model_name=self.rerank_model_name)
+                self.use_flashrank = True
+            except Exception:
+                from sentence_transformers import CrossEncoder as STCrossEncoder
+                self.rerank_model = STCrossEncoder(self.rerank_model_name)
+                self.use_flashrank = False
+        else:
+            self.rerank_model = CrossEncoder(self.rerank_model_name)
+            self.use_flashrank = False
+        
+        # Better tokenization for BM25 (strips punctuation)
+        self.tokenized_corpus = [self._tokenize(chunk['metadata']['text']) for chunk in final_chunks]
+        self.bm25 = BM25Okapi(self.tokenized_corpus)
+        self.technique_to_indices = self._build_chunking_index_map()
+
+    def _normalize_rerank_model_name(self, model_name: str) -> str:
+        normalized = (model_name or "").strip()
+        if not normalized:
+            return "cross-encoder/ms-marco-MiniLM-L-6-v2"
+        if "/" in normalized:
+            return normalized
+        return f"cross-encoder/{normalized}"
+
+    def _tokenize(self, text: str) -> List[str]:
+        """Tokenize text using regex to strip punctuation."""
+        return re.findall(r'\w+', text.lower())
+
+# added these two helper methods for chunking based on chunk_technique metadata, and normalization of chunking_technique param
+    def _build_chunking_index_map(self) -> dict[str, List[int]]:
+        mapping: dict[str, List[int]] = {}
+        for idx, chunk in enumerate(self.final_chunks):
+            metadata = chunk.get('metadata', {})
+            technique = (metadata.get('chunking_technique') or '').strip().lower()
+            if not technique:
+                continue
+            mapping.setdefault(technique, []).append(idx)
+        return mapping
+
+    def _normalize_chunking_technique(self, chunking_technique: Optional[str]) -> Optional[str]:
+        if not chunking_technique:
+            return None
+        normalized = str(chunking_technique).strip().lower()
+        if not normalized or normalized in {"all", "any", "*", "none"}:
+            return None
+        return normalized
+
+    # ------------------------------------------------------------------
+    # Retrieval
+    # ------------------------------------------------------------------
+
+    def _semantic_search(self, query, index, top_k, chunking_technique: Optional[str] = None) -> tuple[np.ndarray, List[str]]:
+        query_vector = self.embed_model.encode(query)
+        query_kwargs = {
+            "vector": query_vector.tolist(),
+            "top_k": top_k,
+            "include_metadata": True,
+        }
+        if chunking_technique:
+            query_kwargs["filter"] = {"chunking_technique": {"$eq": chunking_technique}}
+        res = index.query(**query_kwargs)
+        chunks = [match['metadata']['text'] for match in res['matches']]
+        return query_vector, chunks
+
+    def _bm25_search(self, query, top_k, chunking_technique: Optional[str] = None) -> List[str]:
+        tokenized_query = self._tokenize(query)
+        scores = self.bm25.get_scores(tokenized_query)
+
+        if chunking_technique:
+            candidate_indices = self.technique_to_indices.get(chunking_technique, [])
+            if not candidate_indices:
+                return []
+            top_indices = sorted(candidate_indices, key=lambda i: scores[i], reverse=True)[:top_k]
+        else:
+            top_indices = np.argsort(scores)[::-1][:top_k]
+
+        return [self.final_chunks[i]['metadata']['text'] for i in top_indices]
+
+    # ------------------------------------------------------------------
+    # Fusion
+    # ------------------------------------------------------------------
+
+    def _rrf_score(self, semantic_results, bm25_results, k=60) -> List[str]:
+        scores = {}
+        for rank, chunk in enumerate(semantic_results):
+            scores[chunk] = scores.get(chunk, 0) + 1 / (k + rank + 1)
+        for rank, chunk in enumerate(bm25_results):
+            scores[chunk] = scores.get(chunk, 0) + 1 / (k + rank + 1)
+        return [chunk for chunk, _ in sorted(scores.items(), key=lambda x: x[1], reverse=True)]
+
+    # ------------------------------------------------------------------
+    # Reranking
+    # ------------------------------------------------------------------
+
+    def _cross_encoder_rerank(self, query, chunks, final_k) -> List[str]:
+        if self.use_flashrank:
+            # Use FlashRank for CPU-optimized reranking
+            passages = [{"id": i, "text": chunk} for i, chunk in enumerate(chunks)]
+            rerank_request = RerankRequest(query=query, passages=passages)
+            results = self.rerank_model.rerank(rerank_request)
+            ranked_chunks = [res['text'] for res in results]
+            return ranked_chunks[:final_k]
+        else:
+            # Fallback to sentence-transformers CrossEncoder
+            pairs = [[query, chunk] for chunk in chunks]
+            scores = self.rerank_model.predict(pairs)
+            ranked = sorted(zip(chunks, scores), key=lambda x: x[1], reverse=True)
+            return [chunk for chunk, _ in ranked[:final_k]]
+
+    # ------------------------------------------------------------------
+    # MMR (applied after reranking as a diversity filter)
+    # ------------------------------------------------------------------
+
+    def _maximal_marginal_relevance(self, query_vector, chunks, lambda_param=0.5, top_k=10) -> List[str]:
+        """
+        Maximum Marginal Relevance (MMR) for diversity filtering.
+        
+        DIVISION BY ZERO DEBUGGING:
+        - This method can cause division by zero in cosine_similarity if vectors are zero
+        - We've added multiple safeguards to prevent this
+        """
+        print(f"    [MMR DEBUG] Starting MMR with {len(chunks)} chunks, top_k={top_k}")
+        
+        if not chunks:
+            print(f"    [MMR DEBUG] No chunks, returning empty list")
+            return []
+        
+        # STEP 1: Encode chunks to get embeddings
+        print(f"    [MMR DEBUG] Encoding {len(chunks)} chunks...")
+        try:
+            chunk_embeddings = self.embed_model.encode(chunks)
+            print(f"    [MMR DEBUG] Chunk embeddings shape: {chunk_embeddings.shape}")
+        except Exception as e:
+            print(f"    [MMR DEBUG] ERROR encoding chunks: {e}")
+            return chunks[:top_k]
+        
+        # STEP 2: Reshape query vector
+        query_embedding = query_vector.reshape(1, -1)
+        print(f"    [MMR DEBUG] Query embedding shape: {query_embedding.shape}")
+        
+        # STEP 3: Check for zero vectors (POTENTIAL DIVISION BY ZERO SOURCE)
+        print(f"    [MMR DEBUG] Checking for zero vectors...")
+        query_norm = np.linalg.norm(query_embedding)
+        chunk_norms = np.linalg.norm(chunk_embeddings, axis=1)
+        
+        print(f"    [MMR DEBUG] Query norm: {query_norm}")
+        print(f"    [MMR DEBUG] Chunk norms min: {chunk_norms.min()}, max: {chunk_norms.max()}")
+        
+        # Check for zero or near-zero vectors
+        if query_norm < 1e-10 or np.any(chunk_norms < 1e-10):
+            print(f"    [MMR DEBUG] WARNING: Zero or near-zero vectors detected!")
+            print(f"    [MMR DEBUG] Query norm < 1e-10: {query_norm < 1e-10}")
+            print(f"    [MMR DEBUG] Any chunk norm < 1e-10: {np.any(chunk_norms < 1e-10)}")
+            print(f"    [MMR DEBUG] Falling back to simple selection without MMR")
+            return chunks[:top_k]
+        
+        # STEP 4: Compute relevance scores (POTENTIAL DIVISION BY ZERO SOURCE)
+        print(f"    [MMR DEBUG] Computing relevance scores with cosine_similarity...")
+        try:
+            relevance_scores = cosine_similarity(query_embedding, chunk_embeddings)[0]
+            print(f"    [MMR DEBUG] Relevance scores computed successfully")
+            print(f"    [MMR DEBUG] Relevance scores shape: {relevance_scores.shape}")
+            print(f"    [MMR DEBUG] Relevance scores min: {relevance_scores.min()}, max: {relevance_scores.max()}")
+        except Exception as e:
+            print(f"    [MMR DEBUG] ERROR computing relevance scores: {e}")
+            print(f"    [MMR DEBUG] Falling back to simple selection")
+            return chunks[:top_k]
+        
+        # STEP 5: Initialize selection
+        selected, unselected = [], list(range(len(chunks)))
+        
+        first = int(np.argmax(relevance_scores))
+        selected.append(first)
+        unselected.remove(first)
+        print(f"    [MMR DEBUG] Selected first chunk: index {first}")
+        
+        # STEP 6: Iteratively select chunks using MMR
+        print(f"    [MMR DEBUG] Starting MMR iteration...")
+        iteration = 0
+        while len(selected) < min(top_k, len(chunks)):
+            iteration += 1
+            print(f"    [MMR DEBUG] Iteration {iteration}: selected={len(selected)}, unselected={len(unselected)}")
+            
+            # Calculate MMR scores
+            mmr_scores = []
+            for i in unselected:
+                # Compute max similarity to already selected items
+                max_sim = -1
+                for s in selected:
+                    try:
+                        # POTENTIAL DIVISION BY ZERO SOURCE: cosine_similarity
+                        sim = cosine_similarity(
+                            chunk_embeddings[i].reshape(1, -1),
+                            chunk_embeddings[s].reshape(1, -1)
+                        )[0][0]
+                        max_sim = max(max_sim, sim)
+                    except Exception as e:
+                        print(f"    [MMR DEBUG] ERROR computing similarity between chunk {i} and {s}: {e}")
+                        # If similarity computation fails, use 0
+                        max_sim = max(max_sim, 0)
+                
+                mmr_score = lambda_param * relevance_scores[i] - (1 - lambda_param) * max_sim
+                mmr_scores.append((i, mmr_score))
+            
+            # Select chunk with highest MMR score
+            if mmr_scores:
+                best, best_score = max(mmr_scores, key=lambda x: x[1])
+                selected.append(best)
+                unselected.remove(best)
+                print(f"    [MMR DEBUG] Selected chunk {best} with MMR score {best_score:.4f}")
+            else:
+                print(f"    [MMR DEBUG] No MMR scores computed, breaking")
+                break
+        
+        print(f"    [MMR DEBUG] MMR complete. Selected {len(selected)} chunks")
+        return [chunks[i] for i in selected]
+
+    # ------------------------------------------------------------------
+    # Main search
+    # ------------------------------------------------------------------
+
+    def search(self, query, index, top_k=25, final_k=5, mode="hybrid",
+               chunking_technique: Optional[str] = None,
+               rerank_strategy="cross-encoder", use_mmr=False, lambda_param=0.5,
+               verbose: Optional[bool] = None) -> List[str]:
+        """
+        :param mode:             "semantic", "bm25", or "hybrid"
+        :param rerank_strategy:  "cross-encoder", "rrf", or "none"
+        :param use_mmr:          Whether to apply MMR diversity filter after reranking
+        :param lambda_param:     MMR trade-off between relevance (1.0) and diversity (0.0)
+        """
+        should_print = verbose if verbose is not None else self.verbose
+        requested_technique = self._normalize_chunking_technique(chunking_technique)
+        total_start = time.perf_counter()
+        semantic_time = 0.0
+        bm25_time = 0.0
+        rerank_time = 0.0
+        mmr_time = 0.0
+        
+        if should_print:
+            self._print_search_header(query, mode, rerank_strategy, top_k, final_k)
+            if requested_technique:
+                print(f"Chunking Filter: {requested_technique}")
+
+        # 1. Retrieve candidates
+        query_vector = None
+        semantic_chunks, bm25_chunks = [], []
+
+        if mode in ["semantic", "hybrid"]:
+            semantic_start = time.perf_counter()
+            query_vector, semantic_chunks = self._semantic_search(query, index, top_k, requested_technique)
+            semantic_time = time.perf_counter() - semantic_start
+            if should_print:
+                self._print_candidates("Semantic Search", semantic_chunks)
+                print(f"Semantic time: {semantic_time:.3f}s")
+
+        if mode in ["bm25", "hybrid"]:
+            bm25_start = time.perf_counter()
+            bm25_chunks = self._bm25_search(query, top_k, requested_technique)
+            bm25_time = time.perf_counter() - bm25_start
+            if should_print:
+                self._print_candidates("BM25 Search", bm25_chunks)
+                print(f"BM25 time: {bm25_time:.3f}s")
+
+        # 2. Fuse / rerank
+        rerank_start = time.perf_counter()
+        if rerank_strategy == "rrf":
+            candidates = self._rrf_score(semantic_chunks, bm25_chunks)[:final_k]
+            label = "RRF"
+        elif rerank_strategy == "cross-encoder":
+            combined = list(dict.fromkeys(semantic_chunks + bm25_chunks))
+            candidates = self._cross_encoder_rerank(query, combined, final_k)
+            label = "Cross-Encoder"
+        else:  # "none"
+            candidates = list(dict.fromkeys(semantic_chunks + bm25_chunks))[:final_k]
+            label = "No Reranking"
+        rerank_time = time.perf_counter() - rerank_start
+
+        # 3. MMR diversity filter (applied after reranking)
+        if use_mmr and candidates:
+            mmr_start = time.perf_counter()
+            if query_vector is None:
+                query_vector = self.embed_model.encode(query)
+            candidates = self._maximal_marginal_relevance(query_vector, candidates,
+                                                          lambda_param=lambda_param, top_k=final_k)
+            label += " + MMR"
+            mmr_time = time.perf_counter() - mmr_start
+
+        total_time = time.perf_counter() - total_start
+
+        if should_print:
+            self._print_final_results(candidates, label)
+            self._print_timing_summary(semantic_time, bm25_time, rerank_time, mmr_time, total_time)
+
+        return candidates
+
+    # ------------------------------------------------------------------
+    # Printing
+    # ------------------------------------------------------------------
+
+    def _print_search_header(self, query, mode, rerank_strategy, top_k, final_k):
+        print("\n" + "="*80)
+        print(f" SEARCH QUERY: {query}")
+        print(f"Mode: {mode.upper()} | Rerank: {rerank_strategy.upper()}")
+        print(f"Top-K: {top_k} | Final-K: {final_k}")
+        print("-" * 80)
+
+    def _print_candidates(self, label, chunks, preview_n=3):
+        print(f"{label}: Retrieved {len(chunks)} candidates")
+        for i, chunk in enumerate(chunks[:preview_n]):
+            preview = chunk[:100] + "..." if len(chunk) > 100 else chunk
+            print(f"   [{i}] {preview}")
+
+    def _print_final_results(self, results, strategy_label):
+        print(f"\n Final {len(results)} Results ({strategy_label}):")
+        for i, chunk in enumerate(results):
+            preview = chunk[:150] + "..." if len(chunk) > 150 else chunk
+            print(f"   [{i+1}] {preview}")
+        print("="*80)
+
+    def _print_timing_summary(self, semantic_time, bm25_time, rerank_time, mmr_time, total_time):
+        print(" Retrieval Timing:")
+        print(f"   Semantic: {semantic_time:.3f}s")
+        print(f"   BM25: {bm25_time:.3f}s")
+        print(f"   Rerank/Fusion: {rerank_time:.3f}s")
+        print(f"   MMR: {mmr_time:.3f}s")
+        print(f"   Total Retrieval: {total_time:.3f}s")