project2-advanced-rag

🔍 Advanced RAG Research Assistant

Production-grade Retrieval-Augmented Generation with hybrid retrieval, graph-based reasoning, and rigorous evaluation

🔬 What This Project Does

A 3-tier RAG system that goes far beyond basic "vector search → LLM" tutorials:

All three tiers are evaluated with RAGAS metrics to prove the improvements aren't just theoretical.

📊 Results (RAGAS Evaluation)

(Fill in after running evaluation — these numbers go in your resume!)

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────┐
│                    Advanced RAG Pipeline                          │
│                                                                   │
│  📄 Documents                                                     │
│   │                                                               │
│   ├──▶ 🔤 Chunking (recursive, 512 tokens, 50 overlap)          │
│   │                                                               │
│   ├──▶ 📊 TIER 1: Dense Retrieval                                │
│   │    └── BGE-small embeddings → FAISS index → Top-K            │
│   │                                                               │
│   ├──▶ 📊 TIER 2: Hybrid Retrieval                               │
│   │    ├── BM25 (sparse) ──┐                                     │
│   │    ├── BGE (dense) ────┤── RRF Fusion → Cross-encoder → Top-K│
│   │    └── Reciprocal Rank Fusion                                 │
│   │                                                               │
│   └──▶ 📊 TIER 3: Graph Retrieval (LightRAG)                    │
│        ├── Entity Extraction → Knowledge Graph                    │
│        ├── Local queries (specific entities)                      │
│        ├── Global queries (abstract themes)                       │
│        └── Hybrid mode (best of both)                             │
│                                                                   │
│  ❓ Query                                                         │
│   │                                                               │
│   ├──▶ Retrieve relevant contexts (any tier)                     │
│   ├──▶ Rerank with cross-encoder                                 │
│   ├──▶ Generate answer with LLM (Groq API / HF Inference)       │
│   └──▶ Evaluate with RAGAS (faithfulness, relevancy, recall)     │
│                                                                   │
│  🖥️ Gradio Interface                                             │
│   ├── Chat tab (ask questions)                                    │
│   ├── Upload tab (add documents)                                  │
│   ├── Compare tab (side-by-side tier comparison)                  │
│   └── Eval tab (RAGAS scores)                                    │
└──────────────────────────────────────────────────────────────────┘

🛠️ Tech Stack

📁 Project Structure

project2_advanced_rag/
├── README.md                  # This file
├── requirements.txt           # Dependencies  
├── rag_engine.py             # Core RAG engine (all 3 tiers)
├── evaluation.py              # RAGAS evaluation pipeline
├── app.py                     # Gradio web interface
├── ingest_sample_data.py      # Download & index sample documents
├── config.py                  # Configuration (API keys, model names)
└── sample_data/               # Sample documents for demo
    └── README.md

🚀 How to Run

Quick Start (5 minutes)

# 1. Install dependencies
pip install -r requirements.txt

# 2. Set up API key (free!)
#    Go to https://console.groq.com → Get API key
export GROQ_API_KEY="your-key-here"

# 3. Index sample documents
python ingest_sample_data.py

# 4. Launch the app
python app.py
# Opens at http://localhost:7860

Deploy on HF Spaces (Free)

# 1. Create a new Space on huggingface.co
# 2. Upload all files
# 3. Add GROQ_API_KEY to Space secrets
# 4. It deploys automatically!

💡 Key Concepts You'll Learn

• Dense vs Sparse Retrieval: Why you need both
• Reciprocal Rank Fusion: How to combine multiple retrievers
• Cross-encoder Reranking: Why bi-encoders aren't enough
• Knowledge Graphs: Entity extraction and relationship mapping
• Multi-hop Reasoning: Answering questions that span multiple documents
• RAGAS Evaluation: Measuring RAG quality scientifically

📄 Based On

• LightRAG Paper — Graph-based retrieval
• RAGAS Paper — RAG evaluation framework
• Blended RAG — Hybrid retrieval (IBM Research)
• RRF Paper — Reciprocal Rank Fusion

🔑 Getting Free API Keys