README.md

metadata

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

├── 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:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Environment Variables

Create a .env file in the root directory:

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:

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:

# Run all tests
pytest -v

# Run with output capture
pytest -s

All tests should pass in under 3 seconds!