A Retrieval-Augmented Generation (RAG) system for answering questions about the Harry Potter books using semantic retrieval, vector search, query routing, and grounded answer generation.
The deployed frontend is available at:
(https://harry-potter-rag.vercel.app/)
The frontend communicates with the FastAPI backend through the /query endpoint.
The overall workflow is:
┌──────────────────────┐
│ Harry Potter PDF │
│ harrypotter.pdf │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Text Extraction │
│ + Cleaning │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Semantic Chunking │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Chunk JSON Payloads │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ E5 Embeddings │
│ multilingual-e5-large│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Qdrant Cloud │
│ Vector Database │
└──────────┬───────────┘
│
│
┌─────────────────────┴─────────────────────┐
│ │
▼ ▼
┌────────────────┐ ┌────────────────┐
│ Vercel Frontend│ │ FastAPI API │
│ │ │ /query │
└────────────────┘ └───────┬────────┘
│
▼
┌─────────────────┐
│ Groq Router │
└────────┬────────┘
│
┌──────────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
retrieve chitchat off-topic
│ │ │
▼ ▼ ▼
E5 Embedding Groq Response Fixed Response
│
▼
Qdrant Search
│
▼
Top-K Chunks
│
▼
Gemini Generation
│
▼
Grounded Answer
│
▼
Source Metadata
For each user question, the backend follows these steps:
The user's question is first sent to a Groq-powered router.
The router classifies the message into exactly one of:
retrieve
chitchat
off-topic
Used for questions about the Harry Potter books, including:
Used for casual interaction such as:
Hello
How are you?
These requests receive a short conversational response.
Used for questions unrelated to the Harry Potter books.
These requests are rejected without performing retrieval.
For retrieve queries, the backend generates an embedding using Sentence Transformers.
Current model:
intfloat/multilingual-e5-large
Embeddings are normalized before retrieval.
-
The generated query vector is sent to Qdrant Cloud.
-
The system retrieves the top-K most relevant semantic chunks.
-
Each retrieved chunk contains metadata such as:
- Chunk ID
- Book name
- Page start
- Page end
- Chunk text
- Similarity score
The retrieved chunks are formatted into a context passed to the generation model.
The context includes the relevant book text and metadata, for example:
[Source 1]
Chunk ID: ...
Book: ...
Pages: ...
Text:
...
The retrieved context and the user's question are sent to Gemini.
The Harry Potter books were processed from the source PDF:
The processed dataset contains approximately:
Total pages: 3,623
Total characters: 6,273,981
Total words: 1,121,939
Empty pages: 19
Low-text pages: 17
The processing pipeline is:
PDF
↓
Text Extraction (markdown file)
↓
Cleaning
↓
Semantic Chunking
↓
Chunk JSON
↓
Embeddings
↓
Qdrant
Harry_Potter_RAG/
│
├── backend/
│ ├── rag_api.py
│ └── requirements.txt
│
├── frontend/
│ ├── index.html
│ ├── script.js
│ └── style.css
│
├── notebooks/
│ └── RAG_Final_Project.ipynb
│
├── Testing_Screens/
│ ├── Chitchat example.png
│ ├── Off-topic example.png
│ └── Retrieve example.png
│
├── .env.example
│
├── .gitignore
│
└── README.md
Create a .env file for local development.
Follow the structure of .env.example
Create and activate a virtual environment:
python -m venv .venv
.\.venv\Scripts\Activate.ps1Install the required dependencies:
pip install -r requirements.txtStart the FastAPI application with Uvicorn:
uvicorn rag_api:app --reload --host 0.0.0.0 --port 8000The API exposes:
GET /
GET /health
POST /query
Interactive API documentation (Swagger UI):
http://localhost:8000/docs
Returns basic API information and status.
Example:
{
"name": "Harry Potter RAG API",
"version": "1.0.0",
"status": "running",
"docs": "/docs"
}Checks API health and Qdrant connectivity.
Main RAG endpoint.
Request:
{
"query": "Who gave Harry the Marauder's Map?"
}The endpoint returns:
{
"query": "Who gave Harry the Marauder's Map?",
"route": "retrieve",
"answer": "...",
"sources": [
{
"chunk_id": "...",
"book_name": "...",
"page_start": 0,
"page_end": 0,
"score": 0.0
}
]
}curl -X POST "http://localhost:8000/query" \
-H "Content-Type: application/json" \
-d "{\"query\":\"Who gave Harry the Marauder's Map?\"}"The development notebook is:
notebooks/RAG_Final_Project.ipynb
The main workflow is:
- Load and inspect the Harry Potter PDF.
- Extract and clean the text.
- Perform semantic chunking.
- Create chunk payloads.
- Generate embeddings.
- Upload vectors and metadata to Qdrant.
- Test retrieval.
- Test answer generation.
- Evaluate sample questions.
- Persist and reuse the vector database.
The API then uses the already-created Qdrant collection for real-time retrieval.
The frontend is deployed separately using Vercel.
Live application:
https://harry-potter-rag.vercel.app/
The frontend sends user questions to the FastAPI backend through:
POST /query
The backend performs:
User Question
↓
Groq Router
↓
Route
│
├── chitchat → Groq
│
├── off-topic → Fixed response
│
└── retrieve
↓
E5 Embedding
↓
Qdrant
↓
Top-K Chunks
↓
Gemini
↓
Answer
Do not commit .env files or API keys.
Add .env to .gitignore:
.env
.venv/
__pycache__/
API keys should be configured through environment variables or the deployment platform's secret/environment-variable system.
The original Harry Potter PDF contains copyrighted material. Avoid committing or distributing the complete copyrighted book text unnecessarily.
Check:
EMBEDDING_MODEL
and make sure the deployment environment can download the model.
The current model is:
intfloat/multilingual-e5-large
For deployment environments with limited RAM, a smaller E5 model may be considered.
Verify:
QDRANT_URL
QDRANT_API_KEY
QDRANT_COLLECTION
Also make sure that the configured collection exists.
Check:
GEMINI_MODEL
GEMINI_API_KEY
If the selected Gemini model is unavailable or temporarily unavailable, configure another supported model.
Check:
GROQ_MODEL
GROQ_API_KEY
The Groq model is responsible for routing queries and handling chitchat.
| Component | Technology |
|---|---|
| Language | Python |
| API | FastAPI |
| API Server | Uvicorn |
| Query Router | Groq |
| Generation | Google Gemini |
| Embeddings | Sentence Transformers |
| Embedding Model | intfloat/multilingual-e5-large |
| Vector Database | Qdrant Cloud |
| Frontend | HTML / CSS / JavaScript |
| Frontend Deployment | Vercel |
| Development | VS Code / Jupyter Notebook |