Update README.md

README.md

@@ -1,116 +1,171 @@
-📄 Gemini RAG Assistant (FastAPI)
+📄 Gemini RAG Backend System (FastAPI)
 
-A production-style Retrieval-Augmented Generation (RAG) application built with FastAPI, Google Gemini, and FAISS, capable of answering questions and generating summaries from uploaded documents (PDF/TXT) with grounded responses, citations, and confidence scoring.
+Production-grade Retrieval-Augmented Generation (RAG) backend built with FastAPI, FAISS (ANN), and Google Gemini — featuring hybrid retrieval, HNSW indexing, cross-encoder reranking, evaluation logging, and analytics.
 
-This project evolved iteratively from a simple FastAPI API into a robust, end-to-end AI system, covering real-world challenges like PDF ingestion, vector search, LLM rate limits, and Git hygiene.
+This repository demonstrates how modern AI backend systems are actually built in industry, not toy demos.
 
-🚀 Features
+🚀 What This Project Is
 
-📤 Upload PDF and TXT documents
+This is a full RAG backend system that:
 
-🔍 Retrieval-Augmented Q&A using FAISS
+Ingests large PDF/TXT documents
 
-🧠 Grounded answers powered by Google Gemini
+Builds vector indexes with Approximate Nearest Neighbor (ANN) search
 
-📝 Document summarization using the same RAG pipeline
+Answers questions using grounded LLM responses
 
-📚 Page-level citations for transparency
+Tracks confidence, known/unknown answers, and usage analytics
 
-📊 Confidence scoring based on retrieval strength
+Supports production constraints (file limits, caching, logging)
 
-⚡ Async FastAPI backend (non-blocking I/O)
+The project evolved from RAG v1 → RAG v2, adding real-world scalability and observability.
 
-🧪 Mock mode for UI testing when API quota is exhausted
+✨ Key Features (RAG v2)
+📥 Document Ingestion
 
-🧹 Clean Git history with generated files ignored
+Upload PDF and TXT files
 
-🏗️ Architecture Overview
-Frontend (HTML + JS)
+Sentence-aware chunking with overlap
+
+Page-level metadata for citations
+
+🔍 Retrieval (Hybrid + ANN)
+
+FAISS HNSW ANN index for scalable similarity search
+
+Cosine similarity via normalized embeddings
+
+Keyword boosting for lexical relevance
+
+🧠 Reranking (Quality Boost)
+
+Cross-Encoder (ms-marco-MiniLM) reranking
+
+Improves relevance beyond raw vector similarity
+
+Mimics production search stacks (retrieve → rerank)
+
+🤖 LLM Generation
+
+Google Gemini 2.5 Flash
+
+Strict grounding: answers only from retrieved context
+
+Honest fallback: "I don't know" when unsupported
+
+📊 Evaluation & Monitoring
+
+Logs every query:
+
+retrieved chunk count
+
+confidence score
+
+known vs unknown answers
+
+JSONL logs for offline analysis
+
+Built-in analytics dashboard
+
+📈 Analytics Dashboard
+
+Total queries
+
+Knowledge rate
+
+Average confidence
+
+Unknown query tracking
+
+Recent query history
+
+Dark / Light mode UI
+
+🛡️ Production Safeguards
+
+File upload size limits (configurable)
+
+API quota handling
+
+Caching to reduce LLM calls
+
+Clean error handling
+
+Persistent vector store
+
+
+🏗️ System Architecture
+
+Frontend (HTML / JS)
         ↓
 FastAPI Backend
         ↓
 Document Ingestion (PDF / TXT)
         ↓
+Sentence Chunking + Metadata
+        ↓
 Embeddings (SentenceTransformers)
         ↓
-FAISS Vector Store
+FAISS ANN Index (HNSW)
         ↓
-Retriever (Top-K Similarity Search)
+Hybrid Retrieval (Vector + Keyword)
+        ↓
+Cross-Encoder Reranking
         ↓
 Prompt Assembly
         ↓
 Google Gemini LLM
         ↓
-Grounded Response + Citations + Confidence
-
-🧠 Key Concepts Learned
-1. FastAPI Fundamentals
-
-GET and POST endpoints
-
-Request/response lifecycle
-
-Input validation using Pydantic models
-
-Async endpoints for non-blocking LLM calls
-
-2. Real LLM Integration
-
-Secure API key handling via environment variables
-
-Structured prompts for strict input/output control
-
-Handling rate limits and safety-filtered responses
-
-Graceful error handling and fallbacks
-
-3. Retrieval-Augmented Generation (RAG)
+Answer + Confidence + Citations
+        ↓
+Evaluation Logging + Analytics
 
-Why LLMs alone are unreliable for factual answers
+🧠 Core Concepts Demonstrated
+Retrieval-Augmented Generation (RAG)
 
-Converting documents into embeddings
+Why pure LLMs hallucinate
 
-Similarity search using FAISS
+How grounding fixes factual accuracy
 
-Injecting retrieved context into prompts for grounded answers
+Vector search vs keyword search
 
-4. Document Ingestion Reality
+Hybrid retrieval strategies
 
-Not all PDFs are text-based
+Approximate Nearest Neighbor (ANN)
 
-Scanned/screenshot PDFs require OCR
+Why brute-force search fails at scale
 
-RAG quality depends on data quality
+HNSW indexing for fast similarity search
 
-Silent failures often come from missing extractable text
+efConstruction vs efSearch trade-offs
 
-5. Summarization vs Q&A
+Reranking
 
-Summarization is not the same as question answering
+Why top-K vectors ≠ best answers
 
-Naive summarization can fail due to token limits
+Cross-encoder reranking for relevance
 
-Simpler pipelines are often more stable for small documents
+Industry-standard retrieval pipelines
 
-6. Confidence & Trust
+Evaluation & Observability
 
-Confidence score reflects retrieval strength, not “truth”
+Measuring known vs unknown
 
-Honest responses (“I don’t know”) improve trust
+Confidence as a heuristic, not truth
 
-Citations are critical for verification
+Logging for iterative improvement
 
-7. Engineering Best Practices
+Analytics-driven RAG tuning
 
-Start with a stable baseline before adding complexity
+Real Backend Engineering
 
-Mock LLM responses during development
+API limits & retries
 
-Handle API quotas and rate limits explicitly
+Persistent storage
 
-Keep generated files out of Git (.gitignore)
+Clean Git hygiene
 
-Resolve Git branch divergence safely using rebase
+Incremental system evolution
 
 🛠️ Tech Stack
 Backend
@@ -119,10 +174,12 @@ Python
 
 FastAPI
 
-FAISS
+FAISS (HNSW ANN)
 
 SentenceTransformers
 
+Cross-Encoder (MS MARCO)
+
 Google Gemini API
 
 PyPDF
@@ -137,73 +194,49 @@ CSS
 
 Vanilla JavaScript (Fetch API)
 
-Platform & Tooling
+Tooling & Platform
 
 VS Code
 
 Git & GitHub
 
+Docker
+
 Hugging Face Spaces (deployment)
 
 Virtual Environments (venv)
 
-⚙️ Setup Instructions
-1️⃣ Clone the repository
-git clone https://github.com/your-username/your-repo-name.git
-cd your-repo-name
+⚙️ Setup & Run Locally
 
-2️⃣ Create & activate virtual environment
+1️⃣ Clone Repository
+git clone https://github.com/LVVignesh/gemini-rag-fastapi.git
+cd gemini-rag-fastapi
 python -m venv venv
-source venv/bin/activate  # Linux/Mac
-venv\Scripts\activate     # Windows
-
-3️⃣ Install dependencies
+venv\Scripts\activate
 pip install -r requirements.txt
-
-4️⃣ Set environment variables
-
-Create a .env file:
-
 GEMINI_API_KEY=your_api_key_here
-
-5️⃣ Run the server
 uvicorn main:app --reload
 
-
-Open in browser:
-
-http://127.0.0.1:8000
-
-Test and use my RAG project on Hugging face : https://huggingface.co/spaces/lvvignesh2122/Gemini-Rag-Fastapi-Pro
-
-🧪 Mock Mode (Development)
-
-To test the UI without consuming Gemini API quota:
-
-Enable mock responses in main.py
-
-Allows frontend and flow testing without LLM calls
-
-This mirrors real production workflows.
-
 ⚠️ Known Limitations
 
-Scanned/image-based PDFs are not supported (OCR required)
+Scanned/image-only PDFs require OCR (not included)
+
+Confidence score is heuristic
 
-Confidence score is heuristic, not a guarantee of correctness
+Very large corpora may require:
 
-Large documents may require map-reduce summarization (future work)
+batch ingestion
 
-🔮 Future Improvements
+sharding
 
-OCR integration for scanned PDFs
+background workers
 
-Chunk-based retrieval for large documents
+🚀 Live Demo
 
-Streaming LLM responses
+👉 Hugging Face Spaces
+https://huggingface.co/spaces/lvvignesh2122/Gemini-Rag-Fastapi-Pro
 
-Evaluation metrics for answer quality
+📜 License
 
-Multi-document cross-referencing
+MIT License
 
-Auth & user-specific document stores