sdca-rag 0.1.0__py3-none-any.whl

sdca/__init__.py

@@ -0,0 +1,60 @@
+"""SDCA: Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation (RAG) Systems.
+
+Developed by Subodh Butt & Ashish Dhillon.
+"""
+
+from src.baselines.models import Chunk
+from src.extraction.models import Document
+from src.extraction.pdf_parser import load_pdf
+from src.retrieval.hybrid import BM25, rrf, structure_guided_rrf
+from src.sdca.chunker import chunk_sdca
+from src.sdca.v2.chunker import chunk_sdca_v2
+from src.sdca.v3.chunker import V3Options, chunk_sdca_stair, chunk_sdca_v3
+
+__version__ = "0.1.0"
+__all__ = [
+    "chunk_document",
+    "load_pdf",
+    "chunk_sdca_stair",
+    "chunk_sdca_v2",
+    "chunk_sdca",
+    "structure_guided_rrf",
+    "SDCATextSplitter",
+    "Chunk",
+    "Document",
+    "V3Options",
+]
+
+
+def chunk_document(pdf_path: str, target_tokens: int = 300, **kwargs):
+    """High-level convenience API to load and chunk any PDF using the champion SDCA algorithm.
+    
+    Args:
+        pdf_path: Path to the target PDF document.
+        target_tokens: Desired target token size per chunk (default: 300).
+        
+    Returns:
+        List of layout-aware Chunk objects.
+    """
+    doc = load_pdf(pdf_path)
+    return chunk_sdca_stair(doc, target_tokens=target_tokens, **kwargs)
+
+
+class SDCATextSplitter:
+    """Drop-in LangChain-compatible Document Transformer for SDCA."""
+
+    def __init__(self, target_tokens: int = 300, min_tokens: int = 120, max_tokens: int = 420, **kwargs):
+        self.target_tokens = target_tokens
+        self.min_tokens = min_tokens
+        self.max_tokens = max_tokens
+        self.kwargs = kwargs
+
+    def split_pdf(self, pdf_path: str):
+        """Chunks a PDF document preserving section hierarchies and tables."""
+        return chunk_document(
+            pdf_path,
+            target_tokens=self.target_tokens,
+            min_tokens=self.min_tokens,
+            max_tokens=self.max_tokens,
+            **self.kwargs,
+        )

sdca_rag-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: sdca-rag
+Version: 0.1.0
+Summary: Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation (RAG) Systems
+Author: Subodh Butt, Ashish Dhillon
+License-Expression: MIT
+Keywords: rag,chunking,llm,information-retrieval,document-ai,pdf-parsing,stair
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pymupdf>=1.24.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: faiss-cpu>=1.7.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+
+# Structure-Aware Document Chunking Algorithm for Retrieval-Augmented Generation Systems (SDCA)
+
+## Overview
+This repository implements **SDCA (Structure-Aware Document Chunking Algorithm)**, an M.Tech research project addressing chunk boundary degradation in PDF-based Retrieval-Augmented Generation (RAG) pipelines.
+
+Standard naive chunking strategies (fixed-size windowing, simple character recursive splitting) often cleave paragraphs mid-sentence, ignore section hierarchies, and fragment semantic context, leading to degraded retrieval precision. SDCA provides a deterministic, layout-aware chunking pipeline that leverages PDF typography and document structure extracted via PyMuPDF.
+
+---
+
+## 5-Phase Implementation Plan
+
+1. **Phase 1: PDF Extraction Foundation** (**COMPLETED**)
+   - Extract structured text blocks, bounding boxes, font sizes, flags, and page metadata via PyMuPDF (`fitz`).
+2. **Phase 2: Baseline Chunking** (**COMPLETED**)
+   - Implement three standard RAG chunking baselines: Fixed-Size, Recursive, and Sentence-based Chunking.
+3. **Phase 3: SDCA Proposed Algorithm** (**COMPLETED**)
+   - Implement the deterministic structure-aware chunking algorithm targeting ~400 tokens (range 200–600 tokens) with heading detection, paragraph preservation, and sentence-bounded splitting.
+4. **Phase 4: Retrieval and Controlled Experiments** (**COMPLETED**)
+   - Generate embeddings using Sentence Transformers (`all-MiniLM-L6-v2`) and build FAISS vector indexes (`IndexFlatIP`) under strict *Ceteris Paribus* conditions.
+5. **Phase 5 & 5.1: Evaluation Dashboard & Interactive Research Laboratory** (**COMPLETED**)
+   - Interactive viva research laboratory for visual inspection, multi-algorithm side-by-side chunking, multi-strategy live FAISS retrieval, and frozen official benchmark presentation.
+6. **Phase V2: SDCA V2 Hierarchical Evolution & Controlled 5-Way Benchmark** (**COMPLETED**)
+   - Hierarchical section context (`section_path`), heading-content binding, structure-aware retrieval text (`chunk.retrieval_text`), small-chunk merging, and 5-strategy comparative benchmark.
+
+---
+
+## Running the SDCA Research Laboratory
+
+Launch the interactive Streamlit research laboratory:
+
+```bash
+# Direct run via virtual environment
+.venv/bin/streamlit run src/app/streamlit_app.py
+```
+
+The application opens at `http://localhost:8501` featuring 5 dedicated research views:
+1. **Overview:** Executive product landing page with capability cards and aggregate dataset metrics.
+2. **SDCA Explorer:** Deep visual inspection of both SDCA V1 and SDCA V2 (modal body font inference, hierarchical breadcrumbs, heading binding, and structure-aware retrieval text).
+3. **Algorithm Comparison:** Side-by-side multi-algorithm execution (`Fixed`, `Recursive`, `Sentence`, `SDCA V1`, `SDCA V2`) on the same PDF with token statistics, distribution charts, and sequential position chunk inspection.
+4. **Live Retrieval Lab:** Multi-algorithm semantic search under identical embedding and FAISS conditions with side-by-side cosine similarity scoring and vector text inspection.
+5. **Official Benchmark:** Tabbed evaluation featuring the full 5-way V2 benchmark, the frozen Phase 4 baseline, and direct head-to-head SDCA V1 vs SDCA V2 evolution analysis.
+6. **About SDCA:** Algorithmic pipeline, typography heuristics, and viva examination defense notes.
+
+---
+
+## Running the Automated Test Suite
+
+Execute the full 100-test automated test suite across all project phases:
+
+```bash
+.venv/bin/pytest -v tests/
+```
+
+Expected result: `100 passed, 0 failures` (100% pass rate).
+
+
+---
+
+## Research Controls (*Ceteris Paribus*)
+To ensure scientific validity, all retrieval benchmarks hold constant:
+- Document corpus (3 landmark academic papers: Attention, RAG, BERT; 50 pages total)
+- Benchmark query set & ground truth (15 verified technical queries)
+- Embedding model (`sentence-transformers/all-MiniLM-L6-v2`, 384 dimensions)
+- Subword tokenizer (injected model tokenizer across all 4 chunkers)
+- Vector index algorithm (FAISS `IndexFlatIP`)
+- Similarity metric (Exact Cosine Similarity via unit $L_2$-normalized inner product)
+- Retrieval depth ($K = 5$)
+- Evaluation metrics (Precision@5, Recall@5, Hit Rate@5, MRR, NDCG@5)
+
+*The only independent variable is the chunking algorithm.*
+
+---
+
+## Technical Documentation
+- [docs/SDCA_ALGORITHM.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/SDCA_ALGORITHM.md): Algorithmic specification, pseudocode, and typography heuristics.
+- [docs/EXPERIMENT_PROTOCOL.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/EXPERIMENT_PROTOCOL.md): 19-point formal controlled retrieval experiment protocol.
+- [docs/PHASE5_DASHBOARD.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/docs/PHASE5_DASHBOARD.md): Demonstration dashboard architecture and viva defense guide.
+
+---
+
+## Governance Documents
+- [RULES.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/RULES.md): Research rules, algorithmic boundaries, and coding standards.
+- [PROJECT_STATE.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/PROJECT_STATE.md): Current phase, deliverable tracker, and experiment states.
+- [DECISIONS.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/DECISIONS.md): Architectural Decision Records (ADRs).
+- [ERROR_CHANGE_LOG.md](file:///Users/ashishdhillon/DPG/Coordinator/Mtech%20Synopsis/SDCA%20PRoject/Project/ERROR_CHANGE_LOG.md): Historical log of errors, refactorings, and changes.

sdca_rag-0.1.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+sdca/__init__.py,sha256=LwBzfm-iAO_e0a-em4LHabjODqVjaAyMd_jXNDx0l78,1912
+src/__init__.py,sha256=-Ku49JrDjfoEjl4TAzSYGjbf1jfvi3UNYZ3rWjMk0w0,181
+src/app/__init__.py,sha256=BrSE6pqmBlMYeoKKUX-_HXTAXEAF_b5aaEFv3mkwOhg,73
+src/app/comparison.py,sha256=w5oY1ZeCvSCdnHJVuJ217s4-5uOq8Sd1IkxglXtSYiI,9753
+src/app/streamlit_app.py,sha256=31qGuoRrvyeq8l4NZBoeIVrNj1_KM2bS7dJpIM3Dm4A,86884
+src/baselines/__init__.py,sha256=Rp8lUdoblfKfQCPeRH_1tLQTqpqD2cGhQa3lu8ONAf4,853
+src/baselines/fixed.py,sha256=pUcYnwLG6CLW7jCbOMdq2YHrN6CPCsdnNZW3U6XBmjc,3498
+src/baselines/models.py,sha256=zuofdm8Du-o-6d0TrrGxbSQs8Ch_KunajsDc1QcacQM,1446
+src/baselines/recursive.py,sha256=TNGkOLD100YO4khCzYFGNADMhIEqpUe-LlFGTHaRFnU,8906
+src/baselines/sentence.py,sha256=Bis0lXbXB13aEjagb_GVcVD-kL3mYbyD9OlJfSvbhtM,5409
+src/baselines/tokenization.py,sha256=akowdcyF0IdZdPmGzDaBGAAghScQi9_w7OYCZh8xT8w,4993
+src/evaluation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/experiments/__init__.py,sha256=I-UeScjb1aKPIRMTPfE_dOFqgMiZdpEcAwvZw4BM6x4,779
+src/experiments/metrics.py,sha256=pu5nplIQt95JpWXMJLr2PwHu9D1AhiW_8gxN2eXZrdk,5347
+src/experiments/runner.py,sha256=8qUO_HYHaw3Nw6CWb4wze-1dJTOzQoj9B2OnW1O65V4,14617
+src/experiments/runner_v2.py,sha256=YXyoCidgo7HqB-bdPAduxPrUS1ClLYUGbScoCZ1e6-g,12282
+src/extraction/__init__.py,sha256=bxa9XpuWOpV7UQpuBg6RwdsgNWSWHHI2lJwvuhOOPWI,426
+src/extraction/models.py,sha256=BCYSqrjHgcM5WVUmtvPb519myxzuM4M-Yb-jcx9jfkc,3193
+src/extraction/pdf_parser.py,sha256=N5tH0XRLCipOxekRmQjK--JSvglTXBE-nMDyRlS5YAA,4944
+src/retrieval/__init__.py,sha256=9NHLzqnrpQoHixPVbPeKZlkw20EX4RjSNMXae8tdWmI,388
+src/retrieval/embeddings.py,sha256=gsHBuDmmpt4lqWM8T3WP7teczw_Yp7UajXx5Y6JjaFw,4839
+src/retrieval/faiss_store.py,sha256=6HMTdTMCuRlzqTbgYF4EAAWdwF5ia1v9L35jd7MyZiI,3795
+src/retrieval/hybrid.py,sha256=nZ-H9k0J-EAmvVCgURyeKgFMSTTzC-EQlv0kUhZyACU,2363
+src/sdca/__init__.py,sha256=TBldAdw67mn0yFBDk52ys8rGuC3UuwMVIiRCdFyhdrE,477
+src/sdca/chunker.py,sha256=K4aoGQM90SvO0s9H-QLKJUu_whKCi2F1LRu-RZeyiKg,13300
+src/sdca/structure.py,sha256=ItjQURIDVIeMH54RbM_EMYN2lZ9b-Lc7mwPd547dUQA,9680
+src/sdca/v2/__init__.py,sha256=tS4kxe1l8p4CB5jrL29JCniWF7z95ciYI-e4wg6tNJQ,579
+src/sdca/v2/chunker.py,sha256=MNI-zp-V3L3O_hvyjBG5pEYqTrEHJxBTqtuJihlHM-M,11878
+src/sdca/v2/structure.py,sha256=8q79SyeswSRqIEU6m_U2LR4uK7njMx0TlRB9g3jXF8c,10876
+src/sdca/v3/__init__.py,sha256=0NR5jznB6iqctUJ4s9W5WSiMRBIEFkh_OXcab_vXpuI,375
+src/sdca/v3/chunker.py,sha256=owiMBbqep-w5Gp2ERZNfJWZw3DlGHoDhMtAV5MBfZgM,7314
+sdca_rag-0.1.0.dist-info/METADATA,sha256=KYzpcz4bdmjfIoWDsDw6_e4Hs7rwEYDGURNwHuho-KA,6624
+sdca_rag-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sdca_rag-0.1.0.dist-info/top_level.txt,sha256=mvEol6p69DleC67l_uPVDipm2RSaP4Rao9PR7Tq2mHQ,9
+sdca_rag-0.1.0.dist-info/RECORD,,

sdca_rag-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sdca_rag-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+sdca
+src

src/__init__.py

@@ -0,0 +1,6 @@
+"""SDCA Research Project Source Package."""
+
+import os
+
+# Prevent OpenMP runtime conflict between faiss-cpu and torch on macOS
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")

src/app/__init__.py

@@ -0,0 +1 @@
+"""Streamlit Demonstration and Evaluation Dashboard Package for SDCA."""

src/app/comparison.py

@@ -0,0 +1,271 @@
+"""Comparison and orchestration logic for the SDCA Research Laboratory (Phase 5.1).
+
+Coordinates side-by-side chunking and live retrieval across Fixed, Recursive,
+Sentence, and SDCA under strict Ceteris Paribus experimental controls.
+"""
+
+from pathlib import Path
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+# Ensure project root is in sys.path
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from src.baselines.fixed import chunk_fixed
+from src.baselines.models import Chunk
+from src.baselines.recursive import chunk_recursive
+from src.baselines.sentence import chunk_sentence
+from src.extraction.models import Document
+from src.retrieval.embeddings import EmbeddingManager
+from src.retrieval.faiss_store import FAISSVectorStore
+from src.retrieval.hybrid import BM25, structure_guided_rrf
+from src.sdca.chunker import chunk_sdca
+from src.sdca.v2.chunker import chunk_sdca_v2
+from src.sdca.v3 import chunk_sdca_stair
+
+AVAILABLE_STRATEGIES: List[str] = ["Fixed", "Recursive", "Sentence", "SDCA"]
+ALL_AVAILABLE_STRATEGIES: List[str] = [
+    "Fixed",
+    "Recursive",
+    "Sentence",
+    "SDCA",
+    "SDCA V2",
+    "SDCA (STAIR)",
+]
+
+
+def run_chunking_strategy(
+    strategy: str,
+    doc: Document,
+    tokenizer: Any,
+    target_tokens: int = 400,
+) -> List[Chunk]:
+    """Executes a single chunking strategy on the provided document.
+
+    Args:
+        strategy: One of 'Fixed', 'Recursive', 'Sentence', 'SDCA (V1)', 'SDCA (V2)', 'SDCA (STAIR)'.
+        doc: The extracted Document instance.
+        tokenizer: Tokenizer instance or callable.
+        target_tokens: Desired target token size (default 400).
+
+    Returns:
+        List of generated Chunk objects.
+    """
+    if strategy in ("Fixed", "fixed"):
+        return chunk_fixed(doc, target_tokens=target_tokens, overlap_tokens=50, tokenizer=tokenizer)
+    elif strategy in ("Recursive", "recursive"):
+        return chunk_recursive(doc, target_tokens=target_tokens, tokenizer=tokenizer)
+    elif strategy in ("Sentence", "sentence"):
+        return chunk_sentence(doc, target_tokens=target_tokens, tokenizer=tokenizer)
+    elif strategy in ("SDCA", "sdca", "SDCA V1", "sdca_v1", "SDCA (V1)"):
+        return chunk_sdca(doc, target_tokens=target_tokens, min_tokens=200, max_tokens=600, tokenizer=tokenizer)
+    elif strategy in ("SDCA V2", "sdca_v2", "SDCA (V2)"):
+        return chunk_sdca_v2(doc, target_tokens=target_tokens, min_tokens=200, max_tokens=600, tokenizer=tokenizer)
+    elif strategy in ("SDCA (STAIR)", "SDCA STAIR", "sdca_stair", "STAIR"):
+        return chunk_sdca_stair(doc, target_tokens=300, min_tokens=120, max_tokens=420, tokenizer=tokenizer)
+    else:
+        raise ValueError(
+            f"Unknown chunking strategy '{strategy}'. Must be one of {ALL_AVAILABLE_STRATEGIES}"
+        )
+
+
+
+def run_comparison(
+    doc: Document,
+    selected_strategies: List[str],
+    tokenizer: Any,
+    target_tokens: int = 400,
+) -> Dict[str, List[Chunk]]:
+    """Runs the selected chunking algorithms side-by-side on the same document.
+
+    Args:
+        doc: Document to chunk.
+        selected_strategies: Subset of ['Fixed', 'Recursive', 'Sentence', 'SDCA'].
+        tokenizer: Tokenizer to use across all chunkers for token measurement invariance.
+        target_tokens: Target chunk size (default 400).
+
+    Returns:
+        Mapping of strategy name to its generated list of Chunk objects.
+    """
+    results: Dict[str, List[Chunk]] = {}
+    for strat in selected_strategies:
+        results[strat] = run_chunking_strategy(
+            strategy=strat,
+            doc=doc,
+            tokenizer=tokenizer,
+            target_tokens=target_tokens,
+        )
+    return results
+
+
+def calculate_extended_stats(chunks: List[Chunk]) -> Dict[str, Any]:
+    """Calculates comprehensive token and character statistics for a list of chunks.
+
+    Args:
+        chunks: List of Chunk objects.
+
+    Returns:
+        Dictionary containing Chunk Count, Mean Tokens, Median Tokens,
+        Min Tokens, Max Tokens, Std Dev, and Mean Characters.
+    """
+    if not chunks:
+        return {
+            "Chunk Count": 0,
+            "Mean Tokens": 0.0,
+            "Median Tokens": 0.0,
+            "Min Tokens": 0,
+            "Max Tokens": 0,
+            "Std Dev": 0.0,
+            "Mean Characters": 0.0,
+        }
+
+    tokens = [c.token_count for c in chunks]
+    chars = [len(c.text) for c in chunks]
+
+    return {
+        "Chunk Count": len(chunks),
+        "Mean Tokens": round(float(np.mean(tokens)), 2),
+        "Median Tokens": round(float(np.median(tokens)), 2),
+        "Min Tokens": int(np.min(tokens)),
+        "Max Tokens": int(np.max(tokens)),
+        "Std Dev": round(float(np.std(tokens)), 2),
+        "Mean Characters": round(float(np.mean(chars)), 2),
+    }
+
+
+def run_retrieval_comparison(
+    doc: Document,
+    selected_strategies: List[str],
+    query: str,
+    top_k: int,
+    embedding_mgr: EmbeddingManager,
+    target_tokens: int = 400,
+) -> Dict[str, List[Tuple[Chunk, float, int]]]:
+    """Runs live dense retrieval across all selected chunking strategies.
+
+    Follows strict Ceteris Paribus:
+    - Same Document
+    - Same Tokenizer
+    - Same Embedding Model (MiniLM-L6-v2, 384 dimensions)
+    - Same FAISS IndexFlatIP (Cosine similarity via L2 normalization)
+    - Same Query
+    - Same Top-K
+
+    Args:
+        doc: Document instance.
+        selected_strategies: List of strategies to evaluate.
+        query: User search query.
+        top_k: Number of chunks to retrieve per strategy.
+        embedding_mgr: Cached EmbeddingManager instance.
+        target_tokens: Target chunk tokens.
+
+    Returns:
+        Mapping of strategy name to list of (chunk, cosine_similarity, rank) tuples.
+    """
+    if not query.strip() or not selected_strategies:
+        return {}
+
+    query_vec = embedding_mgr.encode([query], normalize_embeddings=True)[0]
+    results: Dict[str, List[Tuple[Chunk, float, int]]] = {}
+
+    for strat in selected_strategies:
+        chunks = run_chunking_strategy(
+            strategy=strat,
+            doc=doc,
+            tokenizer=embedding_mgr.tokenizer,
+            target_tokens=target_tokens,
+        )
+
+        if not chunks:
+            results[strat] = []
+            continue
+
+        chunk_texts = [
+            getattr(c, "retrieval_text", None) or c.metadata.get("retrieval_text") or c.text
+            for c in chunks
+        ]
+        embeddings = embedding_mgr.encode(chunk_texts, normalize_embeddings=True)
+
+        if strat in ("SDCA (STAIR)", "SDCA STAIR", "sdca_stair"):
+            # Structure-Guided Hybrid Retrieval
+            bm = BM25(chunk_texts)
+            sb = bm.scores(query)
+            sd = list(embeddings @ query_vec)
+            sec_paths = [c.metadata.get("section_path_str") or c.section or "" for c in chunks]
+            sec_emb = embedding_mgr.encode(sec_paths, normalize_embeddings=True)
+            sec_sim = list(sec_emb @ query_vec)
+            fused = structure_guided_rrf(sd, sb, sec_sim, alpha_sec=0.003)
+            order = sorted(range(len(chunks)), key=lambda i: -fused[i])
+            results[strat] = [(chunks[i], float(fused[i]), rank + 1) for rank, i in enumerate(order[:top_k])]
+        else:
+            store = FAISSVectorStore(dimension=embedding_mgr.dimension)
+            store.add_chunks(chunks, embeddings)
+            hits = store.search(query_vec, top_k=top_k)
+            results[strat] = hits
+
+    return results
+
+
+def generate_llm_answer(
+    query: str,
+    chunks: List[Chunk],
+    api_key: Optional[str] = None,
+    model_name: str = "gemini-2.5-flash",
+) -> Dict[str, Any]:
+    """Generates an answer to the query grounded exclusively on the retrieved chunks.
+
+    Args:
+        query: User search query.
+        chunks: List of retrieved Chunk objects.
+        api_key: Optional Google Gemini API key. Defaults to GEMINI_API_KEY environment variable.
+        model_name: Gemini model name (default: gemini-2.5-flash).
+
+    Returns:
+        Dict with 'answer', 'model', and 'error'.
+    """
+    import os
+    resolved_key = api_key or os.environ.get("GEMINI_API_KEY")
+
+    if not chunks:
+        return {"answer": "No context chunks were retrieved to answer this query.", "model": None, "error": None}
+
+    if not resolved_key:
+        return {
+            "answer": "To generate live answers with Google Gemini, provide an API key in the sidebar or set the GEMINI_API_KEY environment variable.",
+            "model": None,
+            "error": "MISSING_API_KEY",
+        }
+
+    try:
+        from google import genai
+        client = genai.Client(api_key=resolved_key)
+        context_parts = []
+        for i, c in enumerate(chunks):
+            sec = c.metadata.get("section_path_str") or c.section or "General"
+            context_parts.append(f"--- [Passage {i+1} | Section: {sec} | Page: {c.page_start}] ---\n{c.text}")
+        context_str = "\n\n".join(context_parts)
+
+        prompt = f"""You are a precise technical research assistant.
+Answer the following question based STRICTLY and ONLY on the provided context passages below.
+If the answer cannot be determined directly from the context, state: "The provided context does not contain sufficient information to answer this question."
+Do not extrapolate or assume facts not explicitly stated.
+
+Context:
+{context_str}
+
+Question:
+{query}
+
+Answer:"""
+        response = client.models.generate_content(
+            model=model_name,
+            contents=prompt,
+        )
+        return {"answer": response.text, "model": model_name, "error": None}
+    except Exception as e:
+        return {"answer": f"Error generating answer: {str(e)}", "model": model_name, "error": str(e)}
+