README.md

---
title: RAG Knowledge Assistant
emoji: 🐨
colorFrom: indigo
colorTo: yellow
sdk: gradio
sdk_version: 6.15.2
python_version: '3.13'
app_file: app.py
pinned: false
license: mit
---

# 🤖 RAG Knowledge Assistant

Welcome to the **RAG Knowledge Assistant**—a high-performance, modular Retrieval-Augmented Generation (RAG) system tailored for the Playmobil Toy Shop. It utilizes vector search in **Qdrant** and inference with the **Groq LLM API** to answer user queries with precise store policies and product descriptions, now enhanced with full conversation history and interactive session state.

---

## 🌟 Key Features

1. **Modular Clean Architecture**: Complete separation of the presentation layer (Gradio UI), data orchestration, vector databases, and modular RAG services.
2. **Conversational Session State & History**: Automatically retains preceding user and assistant messages so the virtual toy assistant (Maya) can understand and answer context-aware follow-up queries.
3. **Dynamic AI Query Routing**: Automatically routes questions to the correct context category (`policy`, `product`, or `none`) using high-speed classification.
4. **Optimized RAG Pipeline**: Skips expensive database query retrievals for general conversational questions (`none` classification) to improve latency and reduce cost.
5. **Metadata Filtered Retrieval**: Restricts vector search using Qdrant index payload checks for precise target matching.
6. **Semantic Document Chunking**: Implements a robust text splitting algorithm using recursive character chunking with overlap to preserve semantic context across chunk lines.
7. **100% Offline Testing Suite**: Includes **29 fast unit tests** that fully mock external database connections and model downloads.

---

## 📂 Project Structure

```bash
├── app.py                      # Declarative entrypoint establishing the Gradio interface
├── config.py                   # Central configuration & env variable loader
├── requirements.txt            # Python package dependencies
├── data/                       # Raw dataset files
│   ├── policies.json           # Playmobil shop return, safety, and shipping policies
│   └── products.json           # Catalog of toy packages, contents, and pricing
├── db/                         # Database connection & provisioning
│   ├── bootstrap.py            # Entry for schema setups on startup
│   ├── qdrant_client.py        # Connection setup & index creations
│   └── vectorstore.py          # HuggingFace Embeddings & LangChain vector wrappers
├── rag/                        # Core retrieval and prompt structures
│   ├── prompts.py              # LLM system/context templates
│   ├── retriever.py            # Similarity search & metadata filtering
│   └── router.py               # AI Query categorization prompt & logic
├── services/                   # High-level business logic coordinators
│   ├── chat_service.py         # Coordinating Chat RAG pipeline flow
│   ├── ingestion_service.py    # Document loading, tagging, chunking, and ingesting
│   ├── ui_handlers.py          # Gradio callback handlers keeping app.py completely declarative
│   └── llm.py                  # Groq API client provisioning
└── tests/                      # Automated test suite
    ├── conftest.py             # 100% Offline mocking layer intercepting API clients
    ├── test_chat_service.py    # Unit tests for the main Chat service & history flow
    ├── test_ingestion_service.py # Unit tests for parsing, chunking, and db loader
    ├── test_retriever.py       # Unit tests for vector similarities search
    └── test_router.py          # Unit tests for query routing classifications
```

---

## ⚙️ Setup Instructions

### 1. Prerequisites
- Python 3.13 or newer installed.
- A Qdrant Cluster (Cloud or Local instance).
- A Groq Cloud API Key.

### 2. Install Dependencies
Create a virtual environment and install the required modules:
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 3. Environment Variables
Create a `.env` file in the root directory:
```env
GROQ_API_KEY=your_groq_api_key_here
QDRANT_URL=https://your-qdrant-endpoint-here.aws.cloud.qdrant.io
QDRANT_API_KEY=your_qdrant_api_key_here
STORE_NAME="Playmobil Toy Shop"
STORE_DESCRIPTION="A premium online store selling high-quality Playmobil toys."
```

---

## 🚀 Running the Application

To run the application locally:
```bash
python app.py
```
This will:
1. Bootstrap the Qdrant collections and payload keyword indices.
2. Launch the **Gradio Chat UI** on `http://localhost:7860`.

### Redesigned Chat Interface
* **Interactive Chat Column**: Embeds a native `gr.Chatbot` utilizing active session state. Clear your text input field and post updates instantly. Supports both hitting **Enter** and clicking **Send 🚀**.
* **Sidebar Controls & Utilities**: Allows toggling filter modes, checking background document indexing triggers via real-time status updates, or clicking **🗑️ Clear History** to start a new chat session.

---

## 🧪 Testing Suite

The testing suite contains **29 unit tests** covering every functional capability of the assistant.

### Offline Testing Architecture
To guarantee fast, deterministic execution and eliminate API cost:
* Tests run **100% offline** and do not require internet access, model downloads, or API keys.
* A custom mocking layer (`tests/conftest.py`) intercepts imports of `groq`, `qdrant_client`, and `langchain` modules using dynamic Python `sys.modules` patching.
* No raw Hugging Face embedding model is ever loaded or downloaded.

### Running the Tests
To run the test suite, run `pytest` from the root directory:
```bash
# Run all tests
pytest -v

# Run with output capture
pytest -s
```
All tests should pass in under 3 seconds!