RAG Bot

RAG Bot uses generative AI to provide an interactive QUIZ based on a supplied PDF.

Installation

This project requires Python 3.12 for development and uses pipenv to manage dependencies.

pip install --user pipenv
pipenv shell
pipenv install

Alternatively, you can run the frontend using Docker. In that case, installing dependencies with pipenv locally is not necessary (the Dockerfile will handle it).

Running

There are two ways to run the project. Before running, create a .env file as described in the "Environment variables" section.

1. Using your local Python environment (inside the pipenv shell):

   • To run the chat-like interface: pipenv run chat
   • To run the end-to-end integration test from the command line: pipenv run test-integration

2. Using docker-compose to emulate production:

   # Build image and run project
   docker compose up --build
   
   # Run in detached mode
   docker compose up --build -d
   
   # Stop
   docker compose down

   If you prefer Docker without docker-compose, you can use:

   # Build the image
   docker build -t rag-bot .
   
   # Run the container
   docker run -p 8501:8501 --env-file .env rag-bot

   Dockerfiles that use pipenv to install machine-learning packages may take some time to build (on my machine it took ~12 minutes). Optimizing this is a potential future improvement. Source.

When run via the chat script or docker-compose, the app is available by default at http://localhost:8501.

Environment variables

The application uses environment variables for configuration. The .env.template file contains detailed explanations for each variable and suggested values for required variables. Copy the template to .env and fill in the values as instructed.

Required

These variables are required for the project to run:

Variable	Description	Example
EMBEDDING_MODEL	Embedding model used for indexing	sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_PROVIDER	Embedding provider to use	huggingface, openai
LLM_API_KEY	API key for the LLM provider	gsk_xxxxx
LLM_MODEL	LLM model used to generate questions	qwen/qwen3-32b
LLM_PROVIDER	LLM provider in use	Supported: groq, openai
DOCUMENT_URL	URL of the PDF regulation document	https://bugs.python.org/file47781/Tutorial_EDIT.pdf

Optional

These variables adjust application behavior and have defaults:

Variable	Description	Default
DB_PATH	Directory for FAISS index and question cache	db
DATA_PATH	Local directory for data files	data
EMBEDDING_API_KEY	API key for the embedding provider	None
LLM_TEMPERATURE	Temperature controlling LLM creativity	0.3
QUIZ_GENERATION_MODE	Generation strategy (balanced or random)	balanced
REGENERATE_QUESTIONS_ON_START	Ignore cache and regenerate questions on start	False

Available scripts

Command	Description
pipenv run chat	Starts the quiz web interface using Streamlit (app.py).
pipenv run setup	Prepares the runtime environment: clears db/ and (re)creates the FAISS index.
pipenv run test-integration	Runs the full RAG pipeline integration test: ingestion, FAISS, semantic retrieval and LLM question generation.
pipenv run clean-faiss	Removes only FAISS index files (.faiss and .pkl) from db/.
pipenv run clean-questions	Removes only the question cache (questions.json) produced by QuizManager.
pipenv run clean-db	Completely clears the db/ folder, removing both FAISS index and question cache.

System architecture

The system follows the RAG (Retrieval-Augmented Generation) pattern to produce context-aware questions from a PDF document (regulation).

System Flow

                            +-----------------------+
                            |        PDF URL        |
                            +-----------+-----------+
                                        |
                                        v
                        +---------------+----------------+
                        | document_manager               |
                        | downloads the PDF if needed    |
                        +---------------+----------------+
                                        |
                                        v
                            +-----------+-----------+
                            |   regulation.pdf      |
                            +-----------+-----------+
                                        |
                                        v
                        +----------------+-----------------+
                        | ingestor.ingest_pdf_to_faiss      |
                        | - splits into chunks              |
                        | - generates embeddings            |
                        | - creates FAISS index             |
                        +----------------+-----------------+
                                        |
                                        v
                            +-----------+-----------+
                            |     FAISS Index       |
                            +-----------+-----------+
                                        |
                                        v
+-------------------+       +------------------------+       +------------------------+
|                   |       | retriever              |       | generator              |
| quiz_manager      +------>+ retrieves context from +------>+ generates questions    |
|                   |       | FAISS index            |       | from the context (LLM) |
+---------+---------+       +-----------+------------+       +-----------+------------+
            |                           |                                |
            +------------------------------------------------------------+
                                        |
                                        v
                        +---------------+---------------+
                        | Contextualized questions      |
                        +-------------------------------+

Downloading the PDF and creating the FAISS index can be performed independently from running the frontend using the setup script (see the scripts table). If the PDF and/or FAISS index already exist when the frontend starts, those steps are skipped and the application proceeds with the quiz manager flow (fetch context, generate question, show to user).

Main components

1. document_manager.py

• Responsibility: Ensure the regulation PDF is available locally.
• If the file is missing from data/, it downloads the PDF from the URL configured in .env.

2. ingestor.py

• Responsibility: Process the PDF and create the vector index.
• Loads the PDF and splits content into chunks.
• Converts each chunk into semantic vectors using embeddings.
• Creates a FAISS index in the db/ folder.

3. retriever.py

• Responsibility: Retrieve relevant passages from the document using FAISS.
• Loads the FAISS index and provides methods to fetch similar texts.
• Can use standard semantic search or MMR for diversity.

4. generator.py

• Responsibility: Generate questions based on the document context.
• Receives context passages from the Retriever.
• Uses an LLM to generate questions and answer options.

5. quiz_manager.py

• Responsibility: Orchestrate the full quiz generation flow.
• Calls the retriever to fetch context from FAISS.
• Uses the generator to create questions based on that context.