---
title: Docs QA Backend
sdk: gradio
sdk_version: 5.49.1
python_version: "3.12"
app_file: app.py
pinned: false
app_port: 7860
---

# RAG Backend (v0.3)

## Setup
```bash
python -m venv venv
venv\Scripts\Activate.ps1          # Mac/Linux: source venv/bin/activate
pip install -r requirements.txt
copy .env.example .env             # add your free GROQ_API_KEY (https://console.groq.com/keys)
uvicorn app.main:app --reload
```
Docs UI: http://127.0.0.1:8000/docs

First start downloads two small models once (embedding ~90 MB, re-ranker ~90 MB). Data is stored in `./data`.
Upgrading from v0.2? Delete the old `qdrant_data` folder and upload your files again (chunking changed).

## What it does
1. **Upload** (`POST /documents`) returns immediately; parsing, chunking and embedding run in the background with progress (`GET /documents`). Duplicate files are detected by hash. Pages with no text (scans) are reported.
2. **Understands the question** before searching: finds page numbers ("page 20", "20 no ke page"), document names, and rewrites the question into a clean English search query (Groq) so Hinglish and typos work.
3. **Page questions** ("what is on page 20?") read that page directly instead of guessing by similarity.
4. **Other questions** use hybrid search: vector search + BM25 keywords, fused with RRF, then a cross-encoder re-ranker. With several documents, each is searched separately so one large PDF cannot crowd out the others.
5. **Answers** come from Groq using only the retrieved context, with numbered citations.

## Endpoints
- `GET /health`
- `GET /documents`, `POST /documents`, `DELETE /documents/{doc_id}`
- `POST /ask` with `{"question": "...", "doc_ids": ["..."] | null, "history": [{"role": "user", "content": "..."}]}`

## Tests (no models or API key needed)
```bash
pip install pytest httpx reportlab
python -m pytest -q
```

## Notes
- Page numbers are the position in the PDF file (1 = first page), which can differ from the number printed on the page.
- Scanned PDFs (images) have no text and need OCR first.
- Settings you can change in `.env`: `LLM_MODEL`, `USE_RERANKER`, `USE_QUERY_REWRITE` (see `app/config.py` for chunk size, top_k, etc.).