# 🧪 VDoc-RAG Testing Guide

A step-by-step guide to test the VDoc-RAG document Q&A application.

---

## 📋 Table of Contents

1. [Access the Application](#1-access-the-application)
2. [Upload a Document](#2-upload-a-document)
3. [Ask Questions](#3-ask-questions)
4. [Review the Response](#4-review-the-response)
5. [Provide Feedback](#5-provide-feedback)
6. [Additional Features](#6-additional-features)
7. [Troubleshooting](#7-troubleshooting)

---

## 1. Access the Application

### Online (HuggingFace Spaces)
Open the live demo: **https://huggingface.co/spaces/adi9128/vdoc_rag**

### Local Development
```bash
# Start the server
uvicorn app.main:app --host 127.0.0.1 --port 8000

# Open in browser
http://127.0.0.1:8000
```

---

## 2. Upload a Document

### Step 2.1: Select a File
- Click the **"Choose File"** button
- Select a PDF file from your computer
- Supported formats: `.pdf`, `.png`, `.jpg`, `.jpeg`

### Step 2.2: Upload & Index
- Click **"Upload & Index"** button
- Wait for processing (usually 5-15 seconds)
- You'll see: `✅ Uploaded and indexed [filename] (X chunks)`

### Step 2.3: Confirmation
- A green box will appear: **"📎 Ready to query: [filename]"**
- The document is now indexed and ready for questions

---

## 3. Ask Questions

### Step 3.1: Enter Your Question
- Type your question in the text box
- Example questions:
  - "What is the user's name?"
  - "What skills are mentioned?"
  - "Summarize this document"
  - "What is the contact email?"
  - "List the work experience"

### Step 3.2: Submit
- Click **"Ask Question"** button
- Wait for the AI to process (2-5 seconds)

---

## 4. Review the Response

### The Answer Section Shows:

| Component | Description |
|-----------|-------------|
| **💡 Answer** | AI-generated response based on your document |
| **📚 Sources** | Which pages/sections were used |
| **🔍 Retrieved Chunks** | Raw text segments found in the document |
| **Confidence %** | How relevant each chunk is to your question |

### Example Response:
```
💡 Answer:
The user's name is Aditya, as mentioned in the resume header.

📚 Sources:
- Page 1 → Name: Aditya, Email: aditya@example.com...

🔍 Retrieved Chunks:
[1] Name: Aditya | Confidence: 95.2%
[2] Contact: aditya@example.com | Confidence: 87.1%
```

---

## 5. Provide Feedback

After receiving an answer, you can help improve the system:

| Button | When to Use |
|--------|-------------|
| **✅ Correct** | The answer is accurate and helpful |
| **❌ Incorrect** | The answer is wrong or irrelevant |

Your feedback helps improve future responses!

---

## 6. Additional Features

### Clear Cache
- Click **"🧹 Clear Cache"** to remove cached responses
- Use when you want fresh answers

### Clear Persistent Index
- Click **"🗑️ Clear Persistent Index"** to remove all indexed documents
- Use to start completely fresh

### Dashboards

| Dashboard | URL | Purpose |
|-----------|-----|---------|
| Feedback | `/feedback_dashboard` | View feedback statistics |
| Benchmark | `/benchmark_dashboard` | Evaluate embedding models |

---

## 7. Troubleshooting

### "No document found. Please upload a document first."
- **Cause**: No document is currently indexed
- **Solution**: Upload a PDF file first

### "Internal Server Error" after uploading
- **Cause**: Server state issue
- **Solution**: Refresh the page and try uploading again

### Document shows from another user
- **Note**: This is a shared demo instance
- **Solution**: Upload your own document - it will replace the previous one

### Slow response times
- **Cause**: First load downloads ML models (~500MB)
- **Solution**: Wait for initial setup, subsequent queries are faster

### OCR not extracting text properly
- **Cause**: Low quality PDF or scanned image
- **Solution**: Use higher resolution PDFs or clear text documents

---

## 📝 Test Scenarios

### Scenario 1: Resume Testing
1. Upload a resume PDF
2. Ask: "What is the candidate's name?"
3. Ask: "What are their skills?"
4. Ask: "List their work experience"

### Scenario 2: Report Testing
1. Upload a business report PDF
2. Ask: "What is the main topic?"
3. Ask: "Summarize the key findings"
4. Ask: "What recommendations are made?"

### Scenario 3: Invoice Testing
1. Upload an invoice PDF
2. Ask: "What is the total amount?"
3. Ask: "What items are listed?"
4. Ask: "What is the due date?"

---

## ✅ Success Criteria

The application is working correctly if:
- [x] Document uploads successfully with chunk count
- [x] Questions return relevant answers
- [x] Confidence scores are displayed
- [x] Source attribution shows page numbers
- [x] Feedback buttons work
- [x] New uploads replace old documents

---

## 🆘 Getting Help

If you encounter issues:
1. Check the browser console for errors (F12)
2. Try refreshing the page
3. Upload a different PDF to test
4. Clear the index and try again

---

**Made with ❤️ by Aditya**