https://github.com/soheil-mp/event-assistant-llm
A RAG chatbot to assist event attendees by providing accurate information exclusively from event documentation.
https://github.com/soheil-mp/event-assistant-llm
Last synced: 24 days ago
JSON representation
A RAG chatbot to assist event attendees by providing accurate information exclusively from event documentation.
- Host: GitHub
- URL: https://github.com/soheil-mp/event-assistant-llm
- Owner: soheil-mp
- Created: 2025-07-21T18:48:12.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2025-07-21T19:14:24.000Z (3 months ago)
- Last Synced: 2025-09-12T07:49:29.241Z (26 days ago)
- Language: Python
- Homepage:
- Size: 8.32 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Marbet AI Event Assistant
[](https://python.org)
[](https://langchain.com)
[](https://reactjs.org)
[](LICENSE)
### A Retrieval-Augmented Generation (RAG) chatbot for intelligent event assistance
*Combining document retrieval with large language models to deliver accurate, source-grounded responses*
## Table of Contents
Navigation
1. [Overview](#overview)
2. [Key Features](#key-features)
3. [System Architecture](#system-architecture)
4. [Technology Stack](#technology-stack)
5. [Quick Start](#quick-start)
6. [Installation](#installation)
7. [Configuration](#configuration)
8. [Usage](#usage)
9. [API Reference](#api-reference)
10. [Development](#development)
11. [Contributing](#contributing)
12. [License](#license)
## Overview
The Marbet AI Event Assistant is a **Retrieval-Augmented Generation (RAG)** system that provides accurate, context-aware responses to user queries by leveraging a curated collection of event documents. The system ensures factual accuracy by grounding all responses in the provided source material, eliminating hallucinations commonly found in standalone language models.
Built with modularity and flexibility in mind, the system supports both local and cloud-based language models, making it suitable for various deployment scenarios and security requirements.
## System Architecture
```mermaid
graph TB
subgraph "Client Layer"
UI[React Frontend]
CLI[Command Line Interface]
end
subgraph "API Layer"
API[Flask REST API]
CORS[CORS Handler]
end
subgraph "Processing Layer"
RAG[RAG Orchestrator]
RET[Document Retriever]
LLM[Language Model]
end
subgraph "Storage Layer"
VDB[(ChromaDB Vector Store)]
DOCS[PDF Documents]
end
subgraph "External Services"
OLLAMA[Ollama Server]
GEMINI[Google Gemini API]
end
UI --> API
CLI --> RAG
API --> RAG
RAG --> RET
RAG --> LLM
RET --> VDB
LLM --> OLLAMA
LLM --> GEMINI
DOCS --> VDB
style UI fill:#e1f5fe
style API fill:#f3e5f5
style RAG fill:#e8f5e8
style VDB fill:#fff3e0
```
### Data Flow
1. **Document Ingestion**: PDF files are processed, chunked, and converted to vector embeddings
2. **Query Processing**: User queries are received via web UI or CLI
3. **Context Retrieval**: Relevant document chunks are retrieved from the vector store
4. **Response Generation**: LLM generates contextual responses using retrieved information
5. **Result Delivery**: Answers with source citations are returned to the user
## Quick Start
**Get up and running in under 5 minutes**
### Prerequisites Check
```bash
# Verify Python version (3.9+ required)
python --version
# Verify Node.js version (16+ required)
node --version
# Check if Tesseract is installed
tesseract --version
```
### Installation & Setup
Step 1: Clone Repository
```bash
git clone https://github.com/soheil-mp/event-assistant-llm.git
cd event-assistant-llm
```
Step 2: Backend Setup
```bash
# Create and activate virtual environment
python -m venv venv
# Windows
.\venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
```
Step 3: Frontend Setup
```bash
cd frontend
npm install
cd ..
```
Step 4: Environment Configuration
Create `.env` file in project root:
```env
# LLM Provider Selection
LLM_SOURCE="gemini" # or "ollama"
# Google Gemini Configuration (if using cloud)
GEMINI_API_KEY="your_api_key_here"
GEMINI_LLM_MODEL="gemini-1.5-flash-latest"
# Ollama Configuration (if using local)
OLLAMA_BASE_URL="http://localhost:11434"
OLLAMA_LLM_MODEL="deepseek-r1:32b"
```
Step 5: Add Documents & Launch
```bash
# Add your PDF documents
cp your-documents/*.pdf data/documents/
# Start backend (processes documents on first run)
python api.py
# Start frontend (in new terminal)
cd frontend && npm run dev
```
**Access at:** `http://localhost:5173`
## Installation
### System Requirements
Platform
Windows 10+, macOS 10.15+, Ubuntu 18.04+
Python
3.9.0 or higher
Node.js
16.0.0 or higher
Memory
4GB RAM minimum, 8GB recommended
Storage
2GB free space for dependencies and vector store
### Tesseract OCR Installation
Windows Installation
1. Download installer from [Tesseract at UB Mannheim](https://github.com/UB-Mannheim/tesseract/wiki)
2. Run installer with default settings
3. Add installation path to system PATH: `C:\Program Files\Tesseract-OCR`
4. Verify installation: `tesseract --version`
macOS Installation
```bash
# Using Homebrew (recommended)
brew install tesseract
# Verify installation
tesseract --version
```
Linux Installation
```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install tesseract-ocr tesseract-ocr-eng
# CentOS/RHEL/Fedora
sudo yum install tesseract tesseract-langpack-eng
# Verify installation
tesseract --version
```
## Configuration
### Environment Setup
The application uses environment variables for configuration. Create a `.env` file in the project root:
Google Gemini Configuration (Cloud)
```env
# LLM Provider
LLM_SOURCE="gemini"
# Gemini API Settings
GEMINI_API_KEY="your_api_key_here"
GEMINI_LLM_MODEL="gemini-1.5-flash-latest"
GEMINI_EMBEDDING_MODEL="models/embedding-001"
# General Settings
LLM_TEMPERATURE="0.0"
CHUNK_SIZE="128"
CHUNK_OVERLAP="20"
RETRIEVER_K="100"
FORCE_REBUILD_VECTOR_STORE="False"
```
**Setup Instructions:**
1. Visit [Google AI Studio](https://makersuite.google.com/app/apikey)
2. Create a new API key
3. Add the key to your `.env` file
Ollama Configuration (Local)
```env
# LLM Provider
LLM_SOURCE="ollama"
# Ollama Settings
OLLAMA_BASE_URL="http://localhost:11434"
OLLAMA_LLM_MODEL="deepseek-r1:32b"
EMBEDDING_MODEL="mxbai-embed-large:latest"
# General Settings
LLM_TEMPERATURE="0.0"
CHUNK_SIZE="128"
CHUNK_OVERLAP="20"
RETRIEVER_K="100"
FORCE_REBUILD_VECTOR_STORE="False"
```
**Setup Instructions:**
1. Install [Ollama](https://ollama.ai)
2. Pull required models:
```bash
ollama pull deepseek-r1:32b
ollama pull mxbai-embed-large:latest
```
3. Start Ollama server: `ollama serve`
### Configuration Parameters
| Parameter | Description | Default | Options |
|:----------|:------------|:--------|:--------|
| `LLM_SOURCE` | Language model provider | `gemini` | `gemini`, `ollama` |
| `GEMINI_API_KEY` | Google Gemini API key | - | Your API key |
| `OLLAMA_BASE_URL` | Ollama server endpoint | `http://localhost:11434` | Valid URL |
| `CHUNK_SIZE` | Document chunk size | `128` | 64-512 tokens |
| `CHUNK_OVERLAP` | Overlap between chunks | `20` | 10-50 tokens |
| `RETRIEVER_K` | Documents to retrieve | `100` | 10-200 |
| `FORCE_REBUILD_VECTOR_STORE` | Force vector store rebuild | `False` | `True`, `False` |
### Document Management
Add your PDF documents to the `data/documents/` directory. The system will automatically:
- Process new documents on startup
- Extract text using OCR when needed
- Create vector embeddings
- Store them in the local ChromaDB instance
## Usage
### Web Interface
**Starting the Application**
```bash
# Terminal 1: Start backend API
python api.py
# Terminal 2: Start frontend
cd frontend
npm run dev
```
**First Run Notes:**
- Document processing occurs automatically
- Vector store creation may take several minutes
- Monitor console output for progress
**Using the Interface**
1. **Access**: Navigate to `http://localhost:5173`
2. **Chat**: Type questions about your event documents
3. **Sources**: View document citations in responses
4. **History**: Previous conversations are maintained
**Example Queries:**
- "What time does registration start?"
- "Where is the welcome reception?"
- "What should I bring to the event?"
### Command Line Interface
For development and testing purposes:
```bash
python main.py
```
**Interactive Session:**
```
--- Marbet Event Assistant CLI Ready ---
Ask questions about the event (type 'quit' to exit).
Assistant: Parking is available in the adjacent parking structure.
Level B1 is reserved for event attendees with validation.
Retrieved Sources:
- Event_Logistics.pdf, Page 3: "Parking structure - Level B1 reserved"
```
## API Reference
### Chat Endpoint
**`POST /api/chat`**
Send a message to the chatbot and receive an AI-generated response with source attribution.
Request Format
```http
POST /api/chat
Content-Type: application/json
{
"message": "string",
"history": [
{
"sender": "user|ai",
"text": "string"
}
]
}
```
**Parameters:**
- `message` (required): The user's question or query
- `history` (optional): Array of previous conversation messages
Response Format
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"answer": "string",
"retrieved_context": [
{
"metadata": {
"source": "document.pdf",
"page": 1
}
}
],
"has_citations": true
}
```
**Response Fields:**
- `answer`: The generated response text
- `retrieved_context`: Metadata for documents used in the response
- `has_citations`: Boolean indicating if sources were found and cited
Error Responses
```http
HTTP/1.1 400 Bad Request
{
"error": "Missing 'message' in request body"
}
HTTP/1.1 500 Internal Server Error
{
"error": "Chatbot is not initialized. Please check server logs."
}
```
### Example Usage
Python Example
```python
import requests
# Basic chat request
response = requests.post('http://localhost:5000/api/chat', json={
'message': 'What time does the event start?',
'history': []
})
if response.status_code == 200:
data = response.json()
print(f"Answer: {data['answer']}")
print(f"Has citations: {data['has_citations']}")
else:
print(f"Error: {response.status_code}")
```
JavaScript Example
```javascript
const response = await fetch('http://localhost:5000/api/chat', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
message: 'What time does the event start?',
history: []
})
});
const data = await response.json();
console.log('Answer:', data.answer);
```
## API Reference
### `POST /api/chat`
Handles chat requests.
**Request Body:**
```json
{
"message": "string",
"history": [
{"sender": "user", "text": "string"},
{"sender": "ai", "text": "string"}
]
}
```
**Success Response (200 OK):**
```json
{
"answer": "string",
"retrieved_context": [
{
"metadata": {
"source": "string",
"page": "number"
}
}
],
"has_citations": "boolean"
}
```
**Error Responses:**
- `400 Bad Request`: If the `message` field is missing.
- `500 Internal Server Error`: If the chatbot fails to initialize or an error occurs during processing.
## Development
## Development
### Project Structure
```
event-assistant-llm/
├── 📁 src/marbet_rag/ # Core RAG implementation
│ ├── __init__.py # Package initialization
│ ├── data_processing.py # Document loading and chunking
│ ├── retrieval.py # Vector store and RAG chain setup
│ ├── prompts.py # System prompts and templates
│ └── utils.py # Helper functions and utilities
├── 📁 frontend/ # React web interface
│ ├── 📁 src/ # React source code
│ │ ├── 📁 components/ # UI components
│ │ ├── App.jsx # Main application component
│ │ └── main.jsx # Application entry point
│ ├── 📁 public/ # Static assets
│ ├── package.json # Frontend dependencies
│ └── vite.config.js # Vite configuration
├── 📁 data/ # Data directory
│ ├── 📁 documents/ # Source PDF documents
│ └── 📁 vector_store/ # Generated ChromaDB storage
├── 📁 assets/ # Demo images and documentation assets
├── 📁 notebooks/ # Jupyter notebooks for experimentation
├── api.py # Flask API server
├── main.py # CLI interface
├── config.py # Configuration management
├── requirements.txt # Python dependencies
└── README.md # Project documentation
```
### Development Workflow
**Setup Development Environment**
```bash
# Clone repository
git clone
cd event-assistant-llm
# Setup Python environment
python -m venv venv
source venv/bin/activate # Windows: .\venv\Scripts\activate
pip install -r requirements.txt
# Setup frontend
cd frontend
npm install
cd ..
```
**Development Commands**
```bash
# Start backend in development mode
python api.py
# Start frontend with hot reload
cd frontend && npm run dev
# Run CLI for testing
python main.py
# Build frontend for production
cd frontend && npm run build
```
### Testing
Running Tests
```bash
# Install test dependencies
pip install pytest pytest-cov
# Run all tests
python -m pytest
# Run with coverage
python -m pytest --cov=src
# Run specific test file
python -m pytest tests/test_rag.py -v
```
### Code Quality
Linting and Formatting
```bash
# Python code formatting
pip install black flake8
black src/ --line-length 88
flake8 src/ --max-line-length 88
# JavaScript/React linting
cd frontend
npm run lint
npm run lint:fix
```
## Technology Stack
### Backend Technologies
| Component | Technology | Purpose |
|:---------:|:----------:|:--------|
| **Runtime** |  | Core application runtime |
| **Framework** |  | RAG pipeline orchestration |
| **API Server** |  | RESTful web services |
| **Vector DB** |  | Document embeddings storage |
| **OCR Engine** |  | Text extraction from PDFs |
### Frontend Technologies
| Component | Technology | Purpose |
|:---------:|:----------:|:--------|
| **UI Library** |  | User interface components |
| **Build Tool** |  | Development and build system |
| **HTTP Client** |  | API communication |
### AI/ML Services
| Service | Provider | Integration |
|:-------:|:--------:|:-----------:|
| **Local LLM** |  | Self-hosted language models |
| **Cloud LLM** |  | Google Generative AI API |