---
title: VDoc-RAG
emoji: 📄
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
---

# 📄 VDoc-RAG (Visually-Rich Document Retrieval-Augmented Generation)

VDoc-RAG is an intelligent document Q&A system that answers questions from PDFs, resumes, reports, and other visually-rich documents using RAG (Retrieval-Augmented Generation) technology.

🔗 **Live Demo**: [https://huggingface.co/spaces/adi9128/vdoc_rag](https://huggingface.co/spaces/adi9128/vdoc_rag)

---

## ✨ Key Features

| Feature | Description |
|---------|-------------|
| 📤 **Document Upload** | Upload PDF files for instant processing |
| 🔍 **Smart Q&A** | Ask natural language questions about your documents |
| 🧠 **RAG Pipeline** | Retrieval-Augmented Generation with ChromaDB vector store |
| 📊 **OCR + Table/Chart Extraction** | Tesseract OCR with visual element detection |
| 💯 **Confidence Scoring** | Cosine similarity scores for retrieved chunks |
| 📝 **Feedback System** | Mark answers as correct/incorrect for improvement |
| 🔄 **Document Isolation** | Each upload clears previous data for privacy |
| 🎨 **Modern UI** | Clean gradient design with responsive layout |

---

## 🚀 Live Deployment

The app is deployed on **HuggingFace Spaces** using Docker:
- **URL**: https://huggingface.co/spaces/adi9128/vdoc_rag
- **SDK**: Docker (Python 3.11)
- **Port**: 7860

---

## 💻 Local Development

### Prerequisites

Install these tools and add them to PATH:
- **Python 3.11+**
- **Tesseract OCR** → [Download](https://github.com/UB-Mannheim/tesseract/wiki)
- **Poppler** → [Download](https://github.com/oschwartz10612/poppler-windows/releases)

### Setup

```bash
# Clone the repository
git clone https://github.com/YOUR_USERNAME/vdoc-rag.git
cd vdoc-rag

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Set environment variables
# Create .env file with:
GEMINI_API_KEY=your_gemini_api_key_here

# Run the server
uvicorn app.main:app --host 127.0.0.1 --port 8000
```

Open → [http://127.0.0.1:8000](http://127.0.0.1:8000)

---

## 🖥️ Web Interface

| Route | Description |
|-------|-------------|
| `/` | Main interface - Upload documents & ask questions |
| `/feedback_dashboard` | View feedback statistics |
| `/benchmark_dashboard` | Embedding model evaluation metrics |

---

## 📁 Project Structure

```
vdoc-rag/
├── app/
│   ├── main.py              # FastAPI server & routes
│   ├── indexer.py           # ChromaDB vector store wrapper
│   ├── embeddings.py        # Sentence-transformer embeddings
│   ├── ingest.py            # PDF processing & OCR
│   ├── reader.py            # LLM (Gemini) integration
│   ├── chart_reasoner.py    # Chart/graph understanding
│   ├── feedback_manager.py  # User feedback collection
│   ├── visual_highlight.py  # PDF region highlighting
│   ├── cache_manager.py     # Response caching
│   └── templates/           # HTML templates
│       ├── index.html
│       ├── feedback_dashboard.html
│       └── benchmark_dashboard.html
├── Dockerfile               # HuggingFace Spaces deployment
├── requirements.txt         # Python dependencies
├── TESTING_GUIDE.md         # Step-by-step testing guide
└── README.md
```

---

## 🧠 Technology Stack

| Component | Technology |
|-----------|------------|
| **Backend** | FastAPI + Uvicorn |
| **Vector Database** | ChromaDB (persistent) |
| **Embeddings** | Sentence-Transformers (all-MiniLM-L6-v2) |
| **LLM** | Google Gemini API |
| **OCR** | Tesseract + Poppler |
| **PDF Processing** | pdf2image + PyMuPDF |
| **Frontend** | Jinja2 + TailwindCSS |
| **Deployment** | Docker on HuggingFace Spaces |

---

## 🔒 Privacy & Document Isolation

- **Stateless Design**: Each page refresh shows a clean interface
- **Document Isolation**: Uploading a new document clears all previous data
- **No Persistent User Tracking**: Documents are processed in-memory per session
- **Shared Instance Note**: HuggingFace free tier uses a single server instance

---

## 📈 How It Works

1. **Upload**: PDF is processed with OCR and chunked into text segments
2. **Embed**: Chunks are converted to vectors using Sentence-Transformers
3. **Index**: Vectors are stored in ChromaDB for semantic search
4. **Query**: User questions are embedded and matched against stored chunks
5. **Generate**: Top matching chunks are sent to Gemini LLM for answer generation
6. **Display**: Answer with confidence scores and source attribution

---

## 🧪 Testing

See [TESTING_GUIDE.md](TESTING_GUIDE.md) for step-by-step instructions.

---

## 👨‍💻 Author

**Made with ❤️ by Aditya**

---

## 📄 License

This project is open source and available for educational and research purposes.