Upload 40 files

.env.example

@@ -0,0 +1,18 @@
+# Copy this file to .env and fill in your values
+# .env is gitignored — never commit secrets
+
+# For Groq API (free trial available)
+GROQ_API_KEY=gsk_your_key_here
+
+# Embedding model (runs locally, no token needed)
+EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
+
+# Vector store
+CHROMA_PERSIST_DIR=./chroma_db
+COLLECTION_NAME=rag_documents
+
+# App settings
+LOG_LEVEL=INFO
+CHUNK_SIZE=500
+CHUNK_OVERLAP=50
+TOP_K_RESULTS=5

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* 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
+data/raw/attention_is_all_you_need.pdf filter=lfs diff=lfs merge=lfs -text
+data/raw/rag_for_knowledge_intesive_NLP_tasks.pdf filter=lfs diff=lfs merge=lfs -text

app.py

@@ -0,0 +1,124 @@
+"""
+Gradio UI — RAG Document Q&A
+Deployed on HuggingFace Spaces.
+
+Pre-ingested documents:
+  - Attention Is All You Need (Vaswani et al., 2017)
+  - RAG for Knowledge-Intensive NLP Tasks (Lewis et al., 2020)
+"""
+
+import os
+from pathlib import Path
+import gradio as gr
+from src.generation.rag_chain import RAGChain
+from src.retrieval.vector_store import VectorStore
+from src.ingestion.pdf_loader import load_pdfs_from_dir
+from src.ingestion.chunker import chunk_pages
+from src.retrieval.embedder import Embedder
+from src.utils.logger import logger
+
+
+def ensure_ingested():
+    """
+    Auto-ingest PDFs on first startup if vector store is empty.
+    On HuggingFace Spaces, the chroma_db doesn't persist between restarts
+    so we re-ingest from data/raw/ every cold start.
+    """
+    store = VectorStore()
+    if store.collection.count() > 0:
+        logger.info(f"Vector store already has {store.collection.count()} chunks — skipping ingestion")
+        return
+
+    logger.info("Vector store empty — ingesting PDFs from data/raw/...")
+    pages = load_pdfs_from_dir("data/raw")
+    if not pages:
+        logger.error("No PDFs found in data/raw/ — app will not work correctly")
+        return
+
+    chunks = chunk_pages(pages)
+    embedder = Embedder()
+    texts = [c["text"] for c in chunks]
+    embeddings = embedder.embed_texts(texts)
+    store.add_chunks(chunks, embeddings)
+    logger.info(f"Ingestion complete — {len(chunks)} chunks stored")
+
+
+# Run ingestion on startup
+ensure_ingested()
+
+# Initialise RAG chain
+chain = RAGChain()
+
+
+def answer_question(question: str) -> tuple[str, str]:
+    """Gradio callback: takes question, returns (answer, sources_markdown)."""
+    if not question.strip():
+        return "Please enter a question.", ""
+
+    result = chain.query(question)
+    answer = result["answer"]
+
+    sources_lines = ["**Sources retrieved:**\n"]
+    for i, s in enumerate(result["sources"], start=1):
+        sources_lines.append(
+            f"{i}. `{s['source']}` — Page {s['page']} (similarity: {s['score']})"
+        )
+    sources_md = "\n".join(sources_lines)
+    return answer, sources_md
+
+
+# ------------------------------------------------------------
+# Gradio UI
+# ------------------------------------------------------------
+
+with gr.Blocks(
+    title="RAG Document Q&A",
+    theme=gr.themes.Soft(),
+) as demo:
+    gr.Markdown("""
+    # RAG Document Q&A
+    Ask questions about the **Attention Is All You Need** and **RAG** papers.
+    Answers are grounded only in the retrieved document passages — no hallucination from training data.
+    """)
+
+    with gr.Row():
+        question_box = gr.Textbox(
+            label="Your question",
+            placeholder="e.g. What is the attention mechanism? How does RAG work?",
+            lines=2,
+        )
+
+    submit_btn = gr.Button("Ask", variant="primary", size="lg")
+
+    with gr.Row():
+        answer_box = gr.Textbox(
+            label="Answer",
+            lines=8,
+            interactive=False,
+        )
+        sources_box = gr.Markdown(label="Sources")
+
+    gr.Examples(
+        examples=[
+            "What is the attention mechanism in transformers?",
+            "What is multi-head attention?",
+            "How does RAG combine retrieval and generation?",
+            "What datasets were used to evaluate RAG?",
+            "What is the encoder-decoder architecture?",
+        ],
+        inputs=question_box,
+    )
+
+    submit_btn.click(
+        fn=answer_question,
+        inputs=[question_box],
+        outputs=[answer_box, sources_box],
+    )
+
+    gr.Markdown(
+        "_Built with sentence-transformers, ChromaDB, and Groq (Llama 3.1 8B). "
+        "[View source on GitHub](https://github.com/OmUniyal/rag-document-qa)_"
+    )
+
+if __name__ == "__main__":
+    demo.launch()

configs/config.yaml

@@ -0,0 +1,27 @@
+# Central config — all tuneable parameters live here
+# Code reads this via src/utils/config.py — no magic strings in source files
+
+ingestion:
+  chunk_size: 500
+  chunk_overlap: 50
+  supported_formats: [".pdf"]
+
+retrieval:
+  embedding_model: "sentence-transformers/all-MiniLM-L6-v2"
+  top_k: 5
+  collection_name: "rag_documents"
+  chroma_persist_dir: "./chroma_db"
+
+generation:
+  backend: "groq"
+  groq_model: "llama-3.1-8b-instant"
+  max_new_tokens: 512
+  temperature: 0.1   # Low temp = more factual, less creative
+
+evaluation:
+  ragas_metrics: ["faithfulness", "answer_relevancy", "context_precision", "context_recall"]
+  faithfulness_threshold: 0.7
+
+logging:
+  level: "INFO"
+  file: "logs/app.log"

data/raw/attention_is_all_you_need.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bdfaa68d8984f0dc02beaca527b76f207d99b666d31d1da728ee0728182df697
+size 2215244

data/raw/rag_for_knowledge_intesive_NLP_tasks.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:23e3249e9a1e75418d82efecab0ea8c4d033b89c93742f63208d47ce01f21233
+size 885323

src/evaluation/ragas_eval.py

@@ -0,0 +1,281 @@
+"""
+RAG Evaluation — lightweight implementation of RAGAS-style metrics.
+
+Why not use the ragas library directly:
+  ragas has unstable langchain_community dependencies that break frequently.
+  This module implements the same four core metrics from first principles
+  using only sentence-transformers and the Groq LLM we already have.
+
+Metrics implemented:
+  1. Faithfulness      — are answer claims supported by context?
+  2. Answer Relevancy  — does the answer address the question?
+  3. Context Precision — are retrieved chunks relevant to the question?
+  4. Context Recall    — were all needed chunks retrieved?
+"""
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+from src.utils.logger import logger
+
+# Use the same embedding model as the retrieval pipeline
+_embedder = None
+
+
+def _get_embedder():
+    global _embedder
+    if _embedder is None:
+        _embedder = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
+    return _embedder
+
+
+def _cosine_similarity(a, b):
+    a, b = np.array(a), np.array(b)
+    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))
+
+
+# ------------------------------------------------------------
+# Metric 1: Faithfulness
+# "Is every claim in the answer supported by the retrieved context?"
+# Score 0-1. Low score = hallucination.
+# ------------------------------------------------------------
+
+def faithfulness(answer: str, context_chunks: list[str], threshold: float = 0.5) -> dict:
+    """
+    Checks if each sentence in the answer has semantic support
+    in at least one retrieved chunk.
+
+    Args:
+        answer:         The LLM-generated answer string.
+        context_chunks: List of retrieved chunk texts.
+        threshold:      Minimum cosine similarity to consider a sentence supported.
+
+    Returns:
+        {
+            "score": float,           # 0-1, fraction of sentences supported
+            "supported": int,         # number of supported sentences
+            "total": int,             # total sentences checked
+            "details": list[dict]     # per-sentence breakdown
+        }
+
+    Note: Production RAGAS uses an LLM to decompose answers into atomic claims.
+    This implementation uses embedding similarity as a faster approximation.
+    """
+    model = _get_embedder()
+
+    sentences = [s.strip() for s in answer.split(".") if s.strip()]
+    if not sentences:
+        return {"score": 0.0, "supported": 0, "total": 0, "details": []}
+
+    chunk_embeddings = model.encode(context_chunks)
+    details = []
+    supported = 0
+
+    for sentence in sentences:
+        sentence_embedding = model.encode(sentence)
+        max_similarity = max(
+            _cosine_similarity(sentence_embedding, chunk_emb)
+            for chunk_emb in chunk_embeddings
+        )
+        is_supported = max_similarity >= threshold
+        if is_supported:
+            supported += 1
+        details.append({
+            "sentence": sentence,
+            "max_similarity": round(max_similarity, 4),
+            "supported": is_supported,
+        })
+
+    score = supported / len(sentences)
+    logger.debug(f"Faithfulness: {score:.2f} ({supported}/{len(sentences)} sentences supported)")
+    return {
+        "score": round(score, 4),
+        "supported": supported,
+        "total": len(sentences),
+        "details": details,
+    }
+
+
+# ------------------------------------------------------------
+# Metric 2: Answer Relevancy
+# "Does the answer actually address the question asked?"
+# Score 0-1. Low score = answer is off-topic or evasive.
+# ------------------------------------------------------------
+
+def answer_relevancy(question: str, answer: str) -> dict:
+    """
+    Measures semantic similarity between the question and answer.
+    High similarity = answer directly addresses the question.
+
+    Note: Production RAGAS generates multiple questions from the answer
+    and measures how well they reconstruct the original question.
+    This is a simpler direct similarity approximation.
+    """
+    model = _get_embedder()
+
+    question_embedding = model.encode(question)
+    answer_embedding = model.encode(answer)
+    score = _cosine_similarity(question_embedding, answer_embedding)
+
+    # Clamp to [0, 1] — cosine can be slightly negative
+    score = max(0.0, min(1.0, score))
+
+    logger.debug(f"Answer relevancy: {score:.2f}")
+    return {
+        "score": round(score, 4),
+        "question": question,
+        "answer_preview": answer[:100] + "..." if len(answer) > 100 else answer,
+    }
+
+
+# ------------------------------------------------------------
+# Metric 3: Context Precision
+# "Are the retrieved chunks actually relevant to the question?"
+# Score 0-1. Low score = too many irrelevant chunks retrieved.
+# ------------------------------------------------------------
+
+def context_precision(question: str, context_chunks: list[str], threshold: float = 0.4) -> dict:
+    """
+    Measures what fraction of retrieved chunks are relevant to the question.
+    Signal-to-noise ratio of retrieval.
+
+    Args:
+        question:       The user's question.
+        context_chunks: Retrieved chunk texts.
+        threshold:      Minimum similarity to consider a chunk relevant.
+    """
+    if not context_chunks:
+        return {"score": 0.0, "relevant": 0, "total": 0, "details": []}
+
+    model = _get_embedder()
+    question_embedding = model.encode(question)
+
+    details = []
+    relevant = 0
+
+    for i, chunk in enumerate(context_chunks):
+        chunk_embedding = model.encode(chunk)
+        similarity = _cosine_similarity(question_embedding, chunk_embedding)
+        is_relevant = similarity >= threshold
+        if is_relevant:
+            relevant += 1
+        details.append({
+            "chunk_index": i,
+            "similarity": round(similarity, 4),
+            "relevant": is_relevant,
+            "preview": chunk[:80] + "..." if len(chunk) > 80 else chunk,
+        })
+
+    score = relevant / len(context_chunks)
+    logger.debug(f"Context precision: {score:.2f} ({relevant}/{len(context_chunks)} chunks relevant)")
+    return {
+        "score": round(score, 4),
+        "relevant": relevant,
+        "total": len(context_chunks),
+        "details": details,
+    }
+
+
+# ------------------------------------------------------------
+# Metric 4: Context Recall
+# "Did we retrieve all the chunks needed to answer fully?"
+# Score 0-1. Low score = answer is incomplete due to missing context.
+# ------------------------------------------------------------
+
+def context_recall(answer: str, context_chunks: list[str], threshold: float = 0.5) -> dict:
+    """
+    Measures what fraction of the answer's content is attributable
+    to the retrieved context. Inverse of faithfulness framing —
+    here we measure coverage rather than support.
+
+    Note: Production RAGAS uses ground truth answers for recall.
+    Without ground truth, we approximate by checking how much of
+    the answer is semantically covered by the context.
+    """
+    model = _get_embedder()
+
+    sentences = [s.strip() for s in answer.split(".") if s.strip()]
+    if not sentences or not context_chunks:
+        return {"score": 0.0, "covered": 0, "total": 0}
+
+    chunk_embeddings = model.encode(context_chunks)
+    covered = 0
+
+    for sentence in sentences:
+        sentence_embedding = model.encode(sentence)
+        max_similarity = max(
+            _cosine_similarity(sentence_embedding, chunk_emb)
+            for chunk_emb in chunk_embeddings
+        )
+        if max_similarity >= threshold:
+            covered += 1
+
+    score = covered / len(sentences)
+    logger.debug(f"Context recall: {score:.2f} ({covered}/{len(sentences)} sentences covered)")
+    return {
+        "score": round(score, 4),
+        "covered": covered,
+        "total": len(sentences),
+    }
+
+
+# ------------------------------------------------------------
+# Combined evaluation — run all four metrics at once
+# ------------------------------------------------------------
+
+def evaluate(
+    question: str,
+    answer: str,
+    context_chunks: list[str],
+    faithfulness_threshold: float = 0.5,
+    precision_threshold: float = 0.4,
+) -> dict:
+    """
+    Run all four metrics and return a combined evaluation report.
+
+    Args:
+        question:        The user's question.
+        answer:          The LLM-generated answer.
+        context_chunks:  List of retrieved chunk texts.
+
+    Returns:
+        Dict with all four metric results and an overall summary.
+    """
+    logger.info("Running RAG evaluation...")
+
+    faith = faithfulness(answer, context_chunks, faithfulness_threshold)
+    relevancy = answer_relevancy(question, answer)
+    precision = context_precision(question, context_chunks, precision_threshold)
+    recall = context_recall(answer, context_chunks, faithfulness_threshold)
+
+    # Overall score — average of four metrics
+    overall = np.mean([
+        faith["score"],
+        relevancy["score"],
+        precision["score"],
+        recall["score"],
+    ])
+
+    report = {
+        "overall": round(float(overall), 4),
+        "faithfulness": faith["score"],
+        "answer_relevancy": relevancy["score"],
+        "context_precision": precision["score"],
+        "context_recall": recall["score"],
+        "details": {
+            "faithfulness": faith,
+            "answer_relevancy": relevancy,
+            "context_precision": precision,
+            "context_recall": recall,
+        }
+    }
+
+    logger.info(
+        f"Evaluation complete — "
+        f"overall={report['overall']:.2f} | "
+        f"faithfulness={faith['score']:.2f} | "
+        f"relevancy={relevancy['score']:.2f} | "
+        f"precision={precision['score']:.2f} | "
+        f"recall={recall['score']:.2f}"
+    )
+
+    return report

src/generation/llm_client.py

@@ -0,0 +1,39 @@
+"""
+LLM backend — Groq API.
+Fast, free tier, reliable. Uses llama-3.1-8b-instant.
+
+Why Groq over HuggingFace inference API:
+- More stable free tier
+- Lower latency
+- No provider routing issues
+"""
+
+import os
+from groq import Groq
+from src.utils.config import config
+from src.utils.logger import logger
+
+
+class LLMClient:
+
+    def __init__(self):
+        api_key = os.getenv("GROQ_API_KEY")
+        if not api_key:
+            raise ValueError("GROQ_API_KEY not set in .env")
+        self.client = Groq(api_key=api_key)
+        self.model = config.groq_model
+        logger.info(f"LLM client ready: Groq ({self.model})")
+
+    def generate(self, prompt: str) -> str:
+        """Send prompt, get response string back."""
+        try:
+            completion = self.client.chat.completions.create(
+                model=self.model,
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=config.max_new_tokens,
+                temperature=config.temperature,
+            )
+            return completion.choices[0].message.content.strip()
+        except Exception as e:
+            logger.error(f"Groq error: {e}")
+            raise

src/generation/prompt_builder.py

@@ -0,0 +1,83 @@
+"""
+Constructs the prompt sent to the LLM.
+
+This is where grounding happens — the system prompt explicitly instructs the
+model to only use the provided context. Understanding this module deeply is
+what separates RAG engineers from people who just call LangChain.
+
+Key concepts:
+- System prompt:  Sets behaviour for the entire conversation.
+- Context block:  The retrieved chunks, formatted clearly with source info.
+- User question:  The original query.
+
+Interview question: "How do you prevent hallucination in RAG?"
+Answer lives here: the system prompt + the fallback behaviour when context is weak.
+"""
+
+
+SYSTEM_PROMPT = """You are a precise document assistant. Your job is to answer questions
+using ONLY the context passages provided below. 
+
+Rules you must follow:
+1. If the answer is clearly in the context, answer directly and cite the source.
+2. If the context is partially relevant, use what is there and acknowledge limits.
+3. If the context contains no relevant information, say exactly:
+   "I could not find relevant information in the provided documents."
+   Do NOT guess, infer beyond the text, or use prior knowledge.
+4. Always mention which document and page your answer comes from.
+"""
+
+
+def build_prompt(query: str, chunks: list[dict]) -> str:
+    """
+    Assemble the full prompt from retrieved chunks + user query.
+
+    Args:
+        query:  The user's question.
+        chunks: Retrieved chunks from Retriever.retrieve()
+
+    Returns:
+        A single formatted string ready to send to the LLM.
+    """
+    if not chunks:
+        context_block = "No relevant context was retrieved."
+    else:
+        context_parts = []
+        for i, chunk in enumerate(chunks, start=1):
+            context_parts.append(
+                f"[Source {i}: {chunk['source']}, Page {chunk['page']} | Similarity: {chunk['score']}]\n"
+                f"{chunk['text']}"
+            )
+        context_block = "\n\n---\n\n".join(context_parts)
+
+    prompt = (
+        f"{SYSTEM_PROMPT}\n\n"
+        f"=== CONTEXT ===\n{context_block}\n\n"
+        f"=== QUESTION ===\n{query}\n\n"
+        f"=== ANSWER ==="
+    )
+    return prompt
+
+
+def build_messages(query: str, chunks: list[dict]) -> list[dict]:
+    """
+    Build chat-style messages (system/user) for models that use message format.
+    Used with HuggingFace chat-template models.
+    """
+    context_block = _format_context(chunks)
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {
+            "role": "user",
+            "content": f"Context:\n{context_block}\n\nQuestion: {query}",
+        },
+    ]
+
+
+def _format_context(chunks: list[dict]) -> str:
+    if not chunks:
+        return "No relevant context was retrieved."
+    parts = []
+    for i, chunk in enumerate(chunks, start=1):
+        parts.append(f"[{chunk['source']} | p{chunk['page']}]\n{chunk['text']}")
+    return "\n\n".join(parts)

src/generation/rag_chain.py

@@ -0,0 +1,61 @@
+"""
+The complete RAG pipeline in one place.
+
+RAGChain.query() is the single entrypoint for the app and API.
+It orchestrates: retrieve → build prompt → generate → return with sources.
+
+This is the class you demo in interviews.
+"""
+
+from src.retrieval.retriever import Retriever
+from src.generation.prompt_builder import build_prompt
+from src.generation.llm_client import LLMClient
+from src.utils.config import config
+from src.utils.logger import logger
+
+
+class RAGChain:
+
+    def __init__(self):
+        self.retriever = Retriever()
+        self.llm = LLMClient()
+
+    def query(self, question: str, top_k: int = None) -> dict:
+        """
+        Full RAG pipeline: question in, answer + sources out.
+
+        Returns:
+            {
+                "question": str,
+                "answer":   str,
+                "sources":  [{"source": str, "page": int, "score": float}],
+                "chunks_used": int,
+            }
+        """
+        logger.info(f"Query received: '{question}'")
+
+        # Step 1: Retrieve relevant chunks
+        chunks = self.retriever.retrieve(question, top_k=top_k or config.top_k)
+
+        # Step 2: Build the grounded prompt
+        prompt = build_prompt(question, chunks)
+
+        # Step 3: Generate answer
+        logger.info("Sending to LLM...")
+        answer = self.llm.generate(prompt)
+
+        # Step 4: Package sources for attribution
+        sources = [
+            {"source": c["source"], "page": c["page"], "score": c["score"]}
+            for c in chunks
+        ]
+
+        result = {
+            "question": question,
+            "answer": answer,
+            "sources": sources,
+            "chunks_used": len(chunks),
+        }
+
+        logger.info(f"Answer generated. Sources: {[s['source'] for s in sources]}")
+        return result

src/ingestion/chunker.py

@@ -0,0 +1,77 @@
+"""
+Phase 2: split page text into overlapping chunks.
+
+Key design questions this module answers (study these for interviews):
+- Why chunk at all? LLMs have token limits; we can't feed a 100-page PDF.
+- Why overlap? A sentence split across chunk boundaries would be missed
+  by retrieval. Overlap ensures boundary context appears in at least one chunk.
+- Why not just use token count? Characters are simpler; tokens vary by model.
+  In production you'd switch to tiktoken-based splitting for precision.
+"""
+
+from src.utils.config import config
+from src.utils.logger import logger
+
+
+def chunk_text(text: str, chunk_size: int = None, overlap: int = None) -> list[str]:
+    """
+    Split a single string into overlapping chunks by character count.
+
+    Args:
+        text:       Raw text from one PDF page.
+        chunk_size: Max characters per chunk. Defaults to config value.
+        overlap:    Characters shared between consecutive chunks.
+
+    Returns:
+        List of chunk strings.
+
+    Interview note: This is a naive fixed-size chunker.
+    A smarter approach splits at sentence boundaries (semantic chunking).
+    We build this first to understand WHY the smarter approach matters.
+    """
+    chunk_size = chunk_size or config.chunk_size
+    overlap = overlap or config.chunk_overlap
+
+    if not text.strip():
+        return []
+
+    chunks = []
+    start = 0
+
+    while start < len(text):
+        end = start + chunk_size
+        chunk = text[start:end].strip()
+        if chunk:
+            chunks.append(chunk)
+        # Move start forward by (chunk_size - overlap) to create the overlap window
+        start += chunk_size - overlap
+
+    return chunks
+
+
+def chunk_pages(pages: list[dict]) -> list[dict]:
+    """
+    Chunk all pages from a document, preserving metadata.
+
+    Returns:
+        List of chunk dicts:
+        [{"chunk_id": str, "text": str, "source": str, "page": int}, ...]
+
+    The chunk_id is critical for deduplication and tracing answers back to source.
+    """
+    all_chunks = []
+    chunk_index = 0
+
+    for page in pages:
+        page_chunks = chunk_text(page["text"])
+        for chunk in page_chunks:
+            all_chunks.append({
+                "chunk_id": f"{page['source']}_p{page['page']}_c{chunk_index}",
+                "text": chunk,
+                "source": page["source"],
+                "page": page["page"],
+            })
+            chunk_index += 1
+
+    logger.info(f"Created {len(all_chunks)} chunks from {len(pages)} pages")
+    return all_chunks

src/ingestion/pdf_loader.py

@@ -0,0 +1,59 @@
+"""
+PDF loader using pdfplumber — pure Python, no native DLLs.
+Extracts text page by page, preserving page number metadata
+for source attribution in answers.
+"""
+
+from pathlib import Path
+import pdfplumber
+from src.utils.logger import logger
+
+
+def load_pdf(file_path: str) -> list[dict]:
+    """
+    Extract text from each page of a PDF.
+
+    Returns:
+        List of dicts: [{"page": int, "text": str, "source": str}, ...]
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"PDF not found: {path}")
+    if path.suffix.lower() != ".pdf":
+        raise ValueError(f"Expected a .pdf file, got: {path.suffix}")
+
+    logger.info(f"Loading PDF: {path.name}")
+    pages = []
+
+    with pdfplumber.open(str(path)) as pdf:
+        for page_num, page in enumerate(pdf.pages, start=1):
+            text = page.extract_text()
+            if not text or not text.strip():
+                logger.debug(f"  Page {page_num}: empty, skipping")
+                continue
+            pages.append({
+                "page": page_num,
+                "text": text.strip(),
+                "source": path.name,
+            })
+
+    logger.info(f"  Extracted {len(pages)} pages from {path.name}")
+    return pages
+
+
+def load_pdfs_from_dir(dir_path: str) -> list[dict]:
+    """Load all PDFs from a directory."""
+    dir_path = Path(dir_path)
+    all_pages = []
+    pdf_files = list(dir_path.glob("*.pdf"))
+
+    if not pdf_files:
+        logger.warning(f"No PDFs found in {dir_path}")
+        return []
+
+    for pdf_file in pdf_files:
+        pages = load_pdf(pdf_file)
+        all_pages.extend(pages)
+
+    logger.info(f"Total pages loaded: {len(all_pages)} from {len(pdf_files)} file(s)")
+    return all_pages

src/retrieval/embedder.py

@@ -0,0 +1,52 @@
+"""
+Converts text (chunks or queries) into dense vector embeddings.
+
+Why sentence-transformers and not the OpenAI embeddings API?
+- Runs fully locally — no cost, no rate limits, no data leaving your machine.
+- You understand what the model IS: a fine-tuned BERT encoder.
+- In interviews: "I used sentence-transformers because I wanted full control
+  over the embedding layer and to avoid vendor lock-in."
+
+Model choice:
+- all-MiniLM-L6-v2: fast, small (80MB), good general quality. Good for dev.
+- bge-large-en-v1.5: slower, larger, better retrieval quality. Good for prod.
+"""
+
+from sentence_transformers import SentenceTransformer
+from src.utils.config import config
+from src.utils.logger import logger
+
+
+class Embedder:
+    """Wraps a sentence-transformer model with a consistent interface."""
+
+    def __init__(self, model_name: str = None):
+        model_name = model_name or config.embedding_model
+        logger.info(f"Loading embedding model: {model_name}")
+        self.model = SentenceTransformer(model_name)
+        self.model_name = model_name
+        self.embedding_dim = self.model.get_embedding_dimension()
+        logger.info(f"  Embedding dimension: {self.embedding_dim}")
+
+    def embed_texts(self, texts: list[str]) -> list[list[float]]:
+        """
+        Embed a batch of strings.
+
+        Returns list of float vectors (one per input string).
+        Batching is important: embedding 1000 texts one-by-one is ~10x slower
+        than batching them together.
+        """
+        if not texts:
+            return []
+        logger.debug(f"Embedding {len(texts)} texts...")
+        embeddings = self.model.encode(texts, batch_size=32, show_progress_bar=False)
+        return embeddings.tolist()
+
+    def embed_query(self, query: str) -> list[float]:
+        """
+        Embed a single query string.
+
+        Kept separate from embed_texts because some models use different
+        pooling for queries vs documents (asymmetric embedding models).
+        """
+        return self.model.encode(query).tolist()

src/retrieval/retriever.py

@@ -0,0 +1,39 @@
+"""
+Ties embedder + vector store into a single retrieve() call.
+
+This is the interface the rest of the app uses.
+Neither app.py nor rag_chain.py should talk to Embedder or VectorStore directly.
+"""
+
+from src.retrieval.embedder import Embedder
+from src.retrieval.vector_store import VectorStore
+from src.utils.config import config
+from src.utils.logger import logger
+
+
+class Retriever:
+
+    def __init__(self):
+        self.embedder = Embedder()
+        self.store = VectorStore()
+
+    def retrieve(self, query: str, top_k: int = None) -> list[dict]:
+        """
+        Given a natural language query, return the top-k relevant chunks.
+
+        Steps:
+          1. Embed the query using the same model used for documents.
+             (Critical: query and document embeddings MUST use the same model.)
+          2. Search the vector store for nearest neighbours.
+          3. Return ranked chunks with source metadata.
+        """
+        top_k = top_k or config.top_k
+        logger.info(f"Retrieving top-{top_k} chunks for: '{query[:60]}...'")
+
+        query_embedding = self.embedder.embed_query(query)
+        chunks = self.store.query(query_embedding, top_k=top_k)
+
+        for i, chunk in enumerate(chunks):
+            logger.debug(f"  [{i+1}] score={chunk['score']} | {chunk['source']} p{chunk['page']}")
+
+        return chunks

src/retrieval/vector_store.py

@@ -0,0 +1,95 @@
+"""
+ChromaDB vector store wrapper.
+
+ChromaDB stores: the raw text, the embedding vector, and metadata (source, page).
+On disk so the vector store survives between runs — you don't re-embed on every restart.
+
+Interview concept to own:
+  Chroma uses HNSW (Hierarchical Navigable Small World) indexing under the hood.
+  HNSW is an approximate nearest neighbour algorithm — it trades a tiny bit of
+  recall for massive speed gains at scale. At 10M vectors, brute-force cosine
+  search is unusable; HNSW is O(log n).
+"""
+
+import chromadb
+from chromadb.config import Settings
+from src.utils.config import config
+from src.utils.logger import logger
+
+
+class VectorStore:
+
+    def __init__(self, collection_name: str = None, persist_dir: str = None):
+        collection_name = collection_name or config.collection_name
+        persist_dir = persist_dir or config.chroma_persist_dir
+
+        self.client = chromadb.PersistentClient(
+            path=persist_dir,
+            settings=Settings(anonymized_telemetry=False),
+        )
+        self.collection = self.client.get_or_create_collection(
+            name=collection_name,
+            metadata={"hnsw:space": "cosine"},  # Use cosine distance, not L2
+        )
+        logger.info(f"Vector store ready: '{collection_name}' at {persist_dir}")
+        logger.info(f"  Current document count: {self.collection.count()}")
+
+    def add_chunks(self, chunks: list[dict], embeddings: list[list[float]]) -> None:
+        """
+        Store chunks + their embeddings in Chroma.
+
+        Args:
+            chunks:     Output from chunker.chunk_pages()
+            embeddings: Parallel list of embedding vectors from Embedder.embed_texts()
+        """
+        if not chunks:
+            logger.warning("No chunks to add.")
+            return
+
+        self.collection.add(
+            ids=[c["chunk_id"] for c in chunks],
+            embeddings=embeddings,
+            documents=[c["text"] for c in chunks],
+            metadatas=[{"source": c["source"], "page": c["page"]} for c in chunks],
+        )
+        logger.info(f"Added {len(chunks)} chunks. Total in store: {self.collection.count()}")
+
+    def query(self, query_embedding: list[float], top_k: int = None) -> list[dict]:
+        """
+        Find the top-k most similar chunks to a query embedding.
+
+        Returns:
+            List of dicts: [{"text": str, "source": str, "page": int, "score": float}]
+            Ordered by similarity (most similar first).
+        """
+        top_k = top_k or config.top_k
+        results = self.collection.query(
+            query_embeddings=[query_embedding],
+            n_results=top_k,
+            include=["documents", "metadatas", "distances"],
+        )
+
+        chunks = []
+        for doc, meta, dist in zip(
+            results["documents"][0],
+            results["metadatas"][0],
+            results["distances"][0],
+        ):
+            chunks.append({
+                "text": doc,
+                "source": meta["source"],
+                "page": meta["page"],
+                "score": round(1 - dist, 4),  # Convert cosine distance → similarity
+            })
+
+        return chunks
+
+    def reset(self) -> None:
+        """Delete and recreate the collection. Use during development to re-ingest."""
+        name = self.collection.name
+        self.client.delete_collection(name)
+        self.collection = self.client.get_or_create_collection(
+            name=name,
+            metadata={"hnsw:space": "cosine"},
+        )
+        logger.warning(f"Collection '{name}' has been reset.")

src/utils/config.py

@@ -0,0 +1,60 @@
+"""
+Loads config.yaml and .env into a single typed config object.
+Everything in the codebase imports from here — no hardcoded values elsewhere.
+"""
+
+import os
+from pathlib import Path
+import yaml
+from dotenv import load_dotenv
+
+load_dotenv()
+
+_CONFIG_PATH = Path(__file__).parent.parent.parent / "configs" / "config.yaml"
+
+
+def _load_yaml() -> dict:
+    with open(_CONFIG_PATH, "r") as f:
+        return yaml.safe_load(f)
+
+
+class Config:
+    """Single source of truth for all runtime settings."""
+
+    def __init__(self):
+        cfg = _load_yaml()
+
+        # Ingestion
+        self.chunk_size: int = cfg["ingestion"]["chunk_size"]
+        self.chunk_overlap: int = cfg["ingestion"]["chunk_overlap"]
+
+        # Retrieval
+        self.embedding_model: str = cfg["retrieval"]["embedding_model"]
+        self.top_k: int = cfg["retrieval"]["top_k"]
+        self.collection_name: str = cfg["retrieval"]["collection_name"]
+        self.chroma_persist_dir: str = cfg["retrieval"]["chroma_persist_dir"]
+
+        # Generation
+        self.llm_backend: str = cfg["generation"]["backend"]
+        self.groq_model: str = cfg["generation"]["groq_model"]
+        self.max_new_tokens: int = cfg["generation"]["max_new_tokens"]
+        self.temperature: float = cfg["generation"]["temperature"]
+        self.groq_model: str = cfg["generation"]["groq_model"]
+
+        # Secrets from .env (never from yaml)
+        self.hf_api_token: str = os.getenv("HF_API_TOKEN", "")
+        self.ollama_base_url: str = os.getenv("OLLAMA_BASE_URL", "http://localhost:11434")
+
+        # Evaluation
+        self.faithfulness_threshold: float = cfg["evaluation"]["faithfulness_threshold"]
+
+    def __repr__(self):
+        return (
+            f"Config(backend={self.llm_backend}, "
+            f"embedding={self.embedding_model}, "
+            f"chunk_size={self.chunk_size})"
+        )
+
+
+# Module-level singleton — import this everywhere
+config = Config()

src/utils/logger.py

@@ -0,0 +1,31 @@
+"""
+Centralised logger using loguru.
+Import `logger` from here everywhere — don't use print() in production code.
+"""
+
+import sys
+from loguru import logger
+from pathlib import Path
+
+LOG_DIR = Path("logs")
+LOG_DIR.mkdir(exist_ok=True)
+
+# Remove default handler, set our format
+logger.remove()
+
+logger.add(
+    sys.stdout,
+    format="<green>{time:HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{line}</cyan> - {message}",
+    level="INFO",
+    colorize=True,
+)
+
+logger.add(
+    LOG_DIR / "app.log",
+    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {name}:{line} - {message}",
+    level="DEBUG",
+    rotation="10 MB",
+    retention="7 days",
+)
+
+__all__ = ["logger"]