How rohityadav483/swiggy-rag works
1. What this repo is
- This is a fully local Retrieval-Augmented Generation system for a single document: data/swiggy_report.pdf.
- The architecture is split into two clear phases: offline ingestion/index building and online question answering.
2. Entry points
- ingest.py builds the retrieval indexes from the PDF.
- app.py is the user-facing Streamlit app that handles questions and displays answers.
- The rest of the logic lives under src/ as reusable pipeline components.
3. Document acquisition and extraction boundary
- src/pdf_loader.py is the first processing layer for the report.
- It uses PyMuPDF for standard text pages and hands scanned pages off to src/ocr_extractor.py, which uses pytesseract + Pillow.
- This creates a unified text stream from mixed PDF content types, which is important because the report likely contains both digital and scanned pages.
4. Text normalization
- src/text_cleaner.py cleans extracted text before indexing.
- This layer removes PDF/OCR noise such as whitespace issues, headers, and encoding artifacts so downstream chunking and retrieval operate on cleaner text.
5. Chunking and document units
- src/chunking.py splits cleaned text into retrieval-sized chunks.
- The README indicates chunking around 800 characters with overlap, so each chunk becomes the atomic unit for both vector search and lexical search.
- Chunk metadata includes page references, which later support citations in answers.
6. Offline indexing storage
- src/embeddings.py provides a local embedding model: BAAI/bge-small-en.
- src/vector_store.py persists semantic embeddings in ChromaDB as the vector index.
- The same chunk set is also used for keyword retrieval, likely stored as a BM25-ready corpus artifact for fast lexical lookup.
7. Hybrid retrieval boundary
- src/hybrid_retriever.py combines two retrieval modes:
- semantic search from ChromaDB
- keyword search via BM25
- The two result sets are merged and deduplicated, which improves recall on both paraphrased questions and exact-term queries.
8. Relevance ranking
- src/reranker.py applies a cross-encoder reranker, specifically cross-encoder/ms-marco-MiniLM-L-6-v2.
- This is the quality-control layer between retrieval and generation: it scores candidate chunks more precisely than embedding similarity or BM25 alone.
- The output is a small top-k set of highly relevant context chunks.
9. Answer generation pipeline
- src/rag_pipeline.py orchestrates the end-to-end query flow.
- It compresses the retrieved context by deduplicating and trimming it, then sends it to a local LLM through Ollama.
- The model named in the README is gemma2:2b, used with a strict prompt so responses stay grounded in the report.
10. User-facing behavior
- app.py exposes the system as a Streamlit UI.
- The app receives a question, calls the RAG pipeline, and returns an answer with page citations.
- This means the UI is thin; most architectural complexity lives in the ingestion, retrieval, reranking, and generation layers.
11. Runtime and infrastructure characteristics
- The whole system is intentionally local: no cloud vector DB, no hosted embeddings API, and no external LLM API.
- The only operational dependency outside Python is Ollama, which must be running to serve the local model.
- This makes the deployment model simple: one offline build step, then a local interactive app.
12. Main data flow to diagram
- PDF → extraction/OCR → cleaning → chunking → embeddings + ChromaDB / BM25 artifact creation.
- User question → hybrid retrieval → reranking → context compression → local LLM → cited answer.
- The key boundaries to show are: ingestion vs serving, semantic vs lexical retrieval, and retrieval vs generation.
Main entry points: hybrid_retriever.py Hybrid retriever · pdf_loader.py PDF loader · chunking.py Chunking · rag_pipeline.py RAG pipeline
Components 16
Offline ingestion
Builds cleaned chunks and local retrieval indexes from the PDF.
- PDF report · Single local report used as the knowledge base.
data/swiggy_report.pdf - Ingest entry · Offline entry point that builds indexes from the report.
ingest.py - PDF loader · Reads the report and routes page content into text extraction.
src/pdf_loader.py - OCR extractor · Uses OCR for scanned pages to produce text from images.
src/ocr_extractor.py - Text cleaner · Removes PDF and OCR noise before indexing.
src/text_cleaner.py - Chunking · Splits cleaned text into retrieval-sized chunks with page metadata.
src/chunking.py - Embeddings · Local BAAI/bge-small-en model for semantic vectors.
src/embeddings.py - Vector store · Persists semantic chunk embeddings in ChromaDB.
src/vector_store.py - BM25 corpus · Keyword-searchable chunk corpus used for lexical retrieval.
Online Q&A
Handles user questions, retrieval, reranking, and answer generation.
- Streamlit app · User-facing interface for asking questions and viewing cited answers.
app.py - RAG pipeline · Coordinates retrieval, context preparation, and answer generation.
src/rag_pipeline.py - Hybrid retriever · Merges semantic vector search with BM25 keyword search.
src/hybrid_retriever.py - Reranker · Re-scores retrieved chunks with cross-encoder/ms-marco-MiniLM-L-6-v2.
src/reranker.py - Context compress · Deduplicates and trims evidence before it is sent to the model.
src/rag_pipeline.py - Ollama LLM · Serves the local Gemma 2B model used for grounded answering.
- Cited answer · Final answer with page citations returned to the UI.
Connections 19
- PDF report → PDF loader: source · The report is the only knowledge source.
- Ingest entry → PDF loader: loads · Offline build starts document ingestion.
- PDF loader → OCR extractor: scanned pages · Image-based pages are routed through OCR.
- PDF loader → Text cleaner: text pages · Extracted text flows into normalization.
- OCR extractor → Text cleaner: raw OCR text · OCR output is normalized with the rest of the document text.
- Text cleaner → Chunking: clean text · Normalized text is split into chunks.
- Chunking → Embeddings: chunk text · Chunks are encoded into semantic vectors.
- Chunking → BM25 corpus: chunk corpus · The same chunks form the lexical retrieval corpus.
- Embeddings → Vector store: vectors · Embedding outputs are persisted in ChromaDB.
- Streamlit app → RAG pipeline: question · The UI forwards user queries to the RAG pipeline.
- RAG pipeline → Hybrid retriever: retrieve · The pipeline first gathers candidate evidence.
- Hybrid retriever → Vector store: semantic search · Retrieves by vector similarity from ChromaDB.
- Hybrid retriever → BM25 corpus: keyword search · Retrieves exact-term matches from the lexical corpus.
- Hybrid retriever → Reranker: candidates · Merged retrieval candidates are sent for re-scoring.
- Reranker → Context compress: top chunks · Highest-scoring chunks become the working context.
- Context compress → Ollama LLM: prompt · Compressed context is passed to the local model.
- Ollama LLM → Cited answer: generation · The model produces the grounded response.
- RAG pipeline → Cited answer: returns · Pipeline returns the final cited answer to the UI.
- Cited answer → Streamlit app: display · The app renders the answer and citations.