Watch Teaser Video | View Presentation
A sophisticated helpdesk chatbot application built with a Retrieval-Augmented Generation (RAG) architecture, combining FastAPI backend with React frontend, powered by AI models for intelligent document retrieval and response generation.
** Documentation Latex: https://www.overleaf.com **
This helpdesk chatbot leverages advanced RAG (Retrieval-Augmented Generation) technology to provide accurate, context-aware responses by:
- Hybrid Retrieval: Combining semantic search (Vector Embeddings) with keyword search (BM25) for optimal results.
- Query Expansion: Generating multiple search queries and hypothetical answers (HyDE) to capture user intent.
- Course-Specific Knowledge: Dynamically managing separate knowledge bases for different courses.
- Intelligent Generation: Using OpenAI's GPT models to synthesize answers from retrieved context.
- 🤖 Advanced RAG System: Implements Hybrid Search (BM25 + Vector) and Query Expansion.
- 📚 Course-Specific Knowledge Bases: Automatically organizes documents into separate collections per course.
- ⚡ Real-time Streaming: Provides instant feedback with streaming status updates and responses.
- 🧠 Smart Query Processing: Uses LLM to generate multiple search queries and hypothetical answers (HyDE).
- ⚖️ Answer Evaluation: Includes mechanisms for answer judging and keypoint extraction.
- 🎨 Modern UI: React-based frontend with Tailwind CSS and Markdown support.
- 🚀 Fast API: High-performance backend with FastAPI.
- 🐳 Docker Support: Fully containerized deployment.
- 📊 ChromaDB Integration: Efficient vector storage and retrieval.
- 🔐 CORS Enabled: Secure cross-origin resource sharing
The platform goes beyond simple Q&A by offering interactive study tools generated dynamically from course content:
- Auto-Generation: Creates flashcards focusing on key concepts and definitions from the selected course.
- Interactive UI: Smooth flip animations and navigation.
- Self-Paced: Students can review material at their own speed.
- Dynamic Assessment: Generates multiple-choice questions to test understanding.
- Instant Feedback: Immediate validation of answers with detailed explanations.
- AI Integration: Seamlessly ask the AI for further clarification on any quiz question.
- Gamification: Score tracking and celebratory effects for correct answers.
The system supports distinct roles with specific permissions to manage the educational process:
- Course Access: View available courses and request enrollment.
- Learning Tools: Access chat, flashcards, and quizzes for enrolled courses.
- Progress Tracking: View personal enrollment status.
- Course Management: Update course details (name, description, color).
- Student Management: Review, approve, or reject student enrollment requests.
- Oversight: Monitor course popularity and student interest.
graph TB
subgraph "Client Layer"
USER[👤 User Browser]
FRONTEND[🎨 Frontend React + Vite<br/>Port 80]
end
subgraph "API Layer"
FASTAPI[⚡ FastAPI Backend<br/>Port 8000]
CORS[🔒 CORS Middleware]
end
subgraph "Business Logic Layer"
RAG[🧠 RAG Model]
LLM[💭 LLM Model<br/>GPT-3.5/4]
EMBED[📊 Embedding Model]
RETRIEVER[🔍 Document Retriever]
CHUNKING[📄 Chunking Module]
end
subgraph "Data Processing"
HYBRID[🔀 Hybrid Search<br/>BM25 + Vector]
QUERY_GEN[🔎 Query Generation]
JUDGE[⚖️ Answer Judging]
KEYPOINT[🎯 Keypoint Extraction]
end
subgraph "Storage Layer"
CHROMADB[(🗄️ ChromaDB<br/>Vector Store)]
JSON_DB[📁 JSON Database]
DOCS[📚 Course Documents<br/>.ppsx, .pdf, .txt]
end
subgraph "External Services"
OPENAI[🤖 OpenAI API<br/>Embeddings + Chat]
end
USER --> FRONTEND
FRONTEND -->|HTTP REST API| FASTAPI
FASTAPI --> CORS
CORS --> RAG
RAG --> LLM
RAG --> RETRIEVER
RETRIEVER --> EMBED
RETRIEVER --> HYBRID
RETRIEVER --> CHROMADB
LLM --> QUERY_GEN
LLM --> JUDGE
LLM --> KEYPOINT
LLM -->|API Calls| OPENAI
EMBED -->|API Calls| OPENAI
EMBED --> CHUNKING
CHUNKING --> DOCS
FASTAPI --> JSON_DB
JSON_DB -.->|users.json| FASTAPI
JSON_DB -.->|courses.json| FASTAPI
JSON_DB -.->|enrollments.json| FASTAPI
style USER fill:#e1f5ff
style FRONTEND fill:#4fc3f7
style FASTAPI fill:#81c784
style RAG fill:#ffb74d
style CHROMADB fill:#ba68c8
style OPENAI fill:#ff8a65
sequenceDiagram
participant U as 👤 User
participant F as Frontend
participant API as FastAPI
participant RAG as RAG Model
participant LLM as LLM Model
participant RET as Retriever
participant CHR as ChromaDB
participant OAI as OpenAI API
U->>F: Ask question about course
F->>API: POST /api/chat/stream
API->>RAG: queryBank(query, course_name, top_k)
Note over RAG,LLM: Step 1: Query Expansion
RAG->>LLM: generateQueries(query)
LLM->>OAI: Generate 3-5 variations
OAI-->>LLM: Query variations
LLM-->>RAG: queries[]
RAG-->>F: Stream: "Generating queries..."
Note over RAG,CHR: Step 2: Hybrid Retrieval (Parallel)
par For each query
RAG->>RET: retrieve_hybrid(query, course)
RET->>RET: Semantic Search (Embeddings)
RET->>OAI: Embed query
OAI-->>RET: Query embedding
RET->>CHR: Query with embedding
CHR-->>RET: Vector results
RET->>RET: Keyword Search (BM25)
RET->>CHR: Get all docs
CHR-->>RET: All documents
RET->>RET: BM25 ranking
RET->>RET: Hybrid merge (RRF)
RET-->>RAG: Combined results
end
RAG-->>F: Stream: "Retrieving documents..."
Note over RAG,OAI: Step 3: Answer Generation (Parallel)
par For each query + context
RAG->>LLM: generateResponse(context, query)
LLM->>OAI: Generate answer
OAI-->>LLM: Answer candidate
LLM-->>RAG: answer
end
RAG-->>F: Stream: "Generating candidates..."
Note over RAG,LLM: Step 4: Answer Judging
par For each answer
RAG->>LLM: judgeAnswer(query, answer, context)
LLM->>OAI: Judge quality
OAI-->>LLM: Score + reasoning
LLM-->>RAG: judgment
end
RAG-->>F: Stream: "Judging answers..."
Note over RAG,LLM: Step 5: Best Answer Selection
RAG->>RAG: Select highest scored answer
RAG->>LLM: extractKeypoints(answer, context)
LLM->>OAI: Extract key concepts
OAI-->>LLM: Keypoints
LLM-->>RAG: keypoints[]
Note over RAG,F: Step 6: Stream Response
RAG-->>F: Stream: best_answer (chunked)
RAG-->>F: Stream: keypoints
RAG-->>F: Stream: sources
F-->>U: Display answer with sources
graph LR
subgraph "Frontend Components"
APP[App.tsx]
CHAT[Chat Component]
LOGIN[Login Component]
COURSES[Courses List]
FLASH[Flashcards]
QUIZ[Quiz Generator]
API_CLIENT[api.ts]
end
APP --> LOGIN
APP --> COURSES
APP --> CHAT
APP --> FLASH
APP --> QUIZ
CHAT --> API_CLIENT
FLASH --> API_CLIENT
QUIZ --> API_CLIENT
API_CLIENT -->|axios| BACKEND[Backend API]
Tehnologii:
- React 18
- TypeScript
- Vite (Build Tool)
- Tailwind CSS
- Axios (HTTP Client)
- Markdown Rendering
graph TB
subgraph "Backend Structure"
MAIN[main.py<br/>FastAPI App]
RAG_M[RAGModel.py<br/>Orchestrator]
subgraph "LLM Module"
LLM_M[LlmModel.py]
PROMPTS[Prompts<br/>Templates]
end
subgraph "Embedding Module"
DOC_RET[documentRetriever.py]
CHUNK[chunking.py]
end
subgraph "Scripts"
EMBED_ALL[embed_all_courses.py]
EMBED_SINGLE[embed_single_course.py]
end
subgraph "Database"
USERS[users.json]
COURSES_DB[courses.json]
ENROLL[enrollments.json]
end
end
MAIN --> RAG_M
RAG_M --> LLM_M
RAG_M --> DOC_RET
LLM_M --> PROMPTS
DOC_RET --> CHUNK
MAIN --> USERS
MAIN --> COURSES_DB
MAIN --> ENROLL
EMBED_ALL --> DOC_RET
EMBED_SINGLE --> DOC_RET
Tehnologii:
- FastAPI
- Pydantic
- OpenAI SDK
- ChromaDB Client
- Rank-BM25
- Python-dotenv
flowchart TD
START([User Query + Course]) --> QUERY_GEN[Query Generation<br/>LLM expands query into 3-5 variations]
QUERY_GEN --> PARALLEL_RET{Parallel Retrieval}
PARALLEL_RET --> RET1[Retrieve Q1]
PARALLEL_RET --> RET2[Retrieve Q2]
PARALLEL_RET --> RET3[Retrieve Q3]
RET1 --> HYBRID1[Hybrid Search<br/>Vector + BM25]
RET2 --> HYBRID2[Hybrid Search<br/>Vector + BM25]
RET3 --> HYBRID3[Hybrid Search<br/>Vector + BM25]
HYBRID1 --> EMBED1[Vector Search<br/>OpenAI Embeddings]
HYBRID1 --> BM25_1[BM25 Keyword<br/>Search]
EMBED1 --> CHROMA1[(ChromaDB)]
BM25_1 --> CHROMA1
CHROMA1 --> RRF1[Reciprocal Rank<br/>Fusion RRF]
RRF1 --> CTX1[Context 1]
HYBRID2 --> CTX2[Context 2]
HYBRID3 --> CTX3[Context 3]
CTX1 --> GEN{Parallel Generation}
CTX2 --> GEN
CTX3 --> GEN
GEN --> ANS1[Answer 1]
GEN --> ANS2[Answer 2]
GEN --> ANS3[Answer 3]
ANS1 --> JUDGE{Judge Answers<br/>Parallel}
ANS2 --> JUDGE
ANS3 --> JUDGE
JUDGE --> SCORE1[Score: 8/10]
JUDGE --> SCORE2[Score: 9/10]
JUDGE --> SCORE3[Score: 7/10]
SCORE1 --> SELECT[Select Best<br/>Answer]
SCORE2 --> SELECT
SCORE3 --> SELECT
SELECT --> BEST[Best Answer<br/>Score: 9/10]
BEST --> ENHANCE{Enhance Answer}
ENHANCE --> KEYPOINTS[Extract Keypoints]
ENHANCE --> SOURCES[Add Sources]
KEYPOINTS --> FINAL[Final Response]
SOURCES --> FINAL
FINAL --> END([Stream to User])
style START fill:#e1f5ff
style QUERY_GEN fill:#fff3e0
style PARALLEL_RET fill:#f3e5f5
style HYBRID1 fill:#e8f5e9
style JUDGE fill:#fff9c4
style SELECT fill:#ffccbc
style FINAL fill:#c8e6c9
style END fill:#b2dfdb
flowchart LR
subgraph "Hybrid Search Algorithm"
QUERY[Query String] --> SPLIT{Split Search}
SPLIT --> VECTOR[Vector Search Path]
SPLIT --> KEYWORD[Keyword Search Path]
VECTOR --> EMBED_Q[Embed Query<br/>OpenAI text-embedding-3-small]
EMBED_Q --> CHROMA_V[(ChromaDB<br/>Cosine Similarity)]
CHROMA_V --> VEC_RESULTS[Top-K Vector Results<br/>with scores]
KEYWORD --> BM25[BM25 Algorithm<br/>TF-IDF variant]
BM25 --> CHROMA_K[(ChromaDB<br/>All documents)]
CHROMA_K --> TOKENIZE[Tokenize & Rank]
TOKENIZE --> KEY_RESULTS[Top-K Keyword Results<br/>with scores]
VEC_RESULTS --> MERGE[Reciprocal Rank Fusion<br/>RRF]
KEY_RESULTS --> MERGE
MERGE --> FORMULA["score = 1/(k + rank)<br/>k=60"]
FORMULA --> DEDUPE[Deduplicate & Re-rank]
DEDUPE --> FINAL_RESULTS[Final Top-K Results]
end
style EMBED_Q fill:#bbdefb
style BM25 fill:#c5e1a5
style MERGE fill:#ffccbc
style FINAL_RESULTS fill:#b2dfdb
Formula RRF:
RRF_score(doc) = Σ [ 1 / (k + rank_i) ]
unde:
k = 60(parametru de netezire)rank_i= poziția documentului în lista i- Suma se face pentru toate listele (vector + keyword)
erDiagram
USERS ||--o{ ENROLLMENTS : requests
COURSES ||--o{ ENROLLMENTS : has
COURSES ||--o{ CHROMADB_COLLECTIONS : stored_in
USERS {
string username PK
string password
string role "student|teacher"
}
COURSES {
string id PK
string name
string description
string color
string folder_path
}
ENROLLMENTS {
string id PK
string username FK
string course_id FK
string status "pending|approved|rejected"
timestamp created_at
}
CHROMADB_COLLECTIONS {
string collection_name PK
string course_id FK
int document_count
json embeddings
json metadata
}
graph TB
subgraph "Authentication"
LOGIN[POST /api/login]
end
subgraph "Chat & RAG"
CHAT_STREAM[POST /api/chat/stream<br/>Streaming RAG responses]
CHAT_SIMPLE[POST /api/chat<br/>Simple chat]
end
subgraph "Courses Management"
GET_COURSES[GET /api/courses<br/>List all courses]
UPDATE_COURSE[PUT /api/courses/:id<br/>Update course]
UPLOAD_COURSE[POST /api/courses/upload<br/>Upload course files]
EMBED_COURSE[POST /api/courses/embed<br/>Embed course documents]
end
subgraph "Enrollments"
ENROLL[POST /api/enrollments/request<br/>Student enrolls]
MY_ENROLL[GET /api/enrollments/my<br/>Get user enrollments]
PENDING[GET /api/enrollments/pending<br/>Teacher view]
APPROVE[POST /api/enrollments/approve<br/>Teacher approves]
REJECT[POST /api/enrollments/reject<br/>Teacher rejects]
end
subgraph "Learning Tools"
FLASHCARDS[POST /api/flashcards<br/>Generate flashcards]
QUIZ[POST /api/quiz<br/>Generate quiz]
end
subgraph "Static Files"
DOCS[GET /docs/**<br/>Course documents]
end
style CHAT_STREAM fill:#ffb74d
style LOGIN fill:#81c784
style FLASHCARDS fill:#64b5f6
style QUIZ fill:#4db6ac
sequenceDiagram
actor S as Student
participant F as Frontend
participant API as Backend API
participant DB as JSON DB
participant RAG as RAG System
S->>F: Login with credentials
F->>API: POST /api/login
API->>DB: Verify user
DB-->>API: User data (role: student)
API-->>F: Login success
S->>F: Browse courses
F->>API: GET /api/courses
API->>DB: Read courses.json
DB-->>API: Courses list
API-->>F: Courses data
S->>F: Request enrollment
F->>API: POST /api/enrollments/request
API->>DB: Save enrollment (status: pending)
DB-->>API: Success
API-->>F: Enrollment requested
Note over S,RAG: After teacher approval
S->>F: Select enrolled course
S->>F: Ask question in chat
F->>API: POST /api/chat/stream
API->>RAG: Process query
RAG-->>API: Stream response
API-->>F: Stream chunks
F-->>S: Display answer with sources
S->>F: Generate flashcards
F->>API: POST /api/flashcards
API->>RAG: Generate cards
RAG-->>API: Flashcards
API-->>F: Cards data
F-->>S: Display flashcards
S->>F: Take quiz
F->>API: POST /api/quiz
API->>RAG: Generate quiz
RAG-->>API: Questions
API-->>F: Quiz data
F-->>S: Display quiz
sequenceDiagram
actor T as Teacher
participant F as Frontend
participant API as Backend API
participant DB as JSON DB
participant FS as File System
T->>F: Login with credentials
F->>API: POST /api/login
API->>DB: Verify user
DB-->>API: User data (role: teacher)
API-->>F: Login success
T->>F: View pending enrollments
F->>API: GET /api/enrollments/pending
API->>DB: Read enrollments.json
DB-->>API: Pending enrollments
API-->>F: Enrollments list
T->>F: Approve enrollment
F->>API: POST /api/enrollments/approve
API->>DB: Update status to approved
DB-->>API: Success
API-->>F: Enrollment approved
T->>F: Update course info
F->>API: PUT /api/courses/:id
API->>DB: Update courses.json
DB-->>API: Success
API-->>F: Course updated
T->>F: Upload course materials
F->>API: POST /api/courses/upload
API->>FS: Save files to docs/
FS-->>API: Files saved
T->>F: Embed course documents
F->>API: POST /api/courses/embed
API->>API: Run embed_single_course.py
API->>FS: Read documents
FS-->>API: Document content
API->>API: Chunk & embed
API->>DB: Store in ChromaDB
DB-->>API: Success
API-->>F: Embedding complete
| Tehnologie | Versiune | Rol |
|---|---|---|
| React | 18.x | UI Framework |
| TypeScript | 5.x | Type Safety |
| Vite | 5.x | Build Tool & Dev Server |
| Tailwind CSS | 3.x | Styling |
| Axios | 1.x | HTTP Client |
| React Markdown | 9.x | Markdown Rendering |
| Tehnologie | Versiune | Rol |
|---|---|---|
| Python | 3.11+ | Programming Language |
| FastAPI | 0.100+ | Web Framework |
| Uvicorn | 0.23+ | ASGI Server |
| Pydantic | 2.x | Data Validation |
| OpenAI SDK | 1.x | LLM & Embeddings API |
| ChromaDB | 0.4+ | Vector Database |
| Rank-BM25 | 0.2+ | Keyword Search |
| Tehnologie | Rol |
|---|---|
| Docker | Containerization |
| Docker Compose | Multi-container orchestration |
| Nginx | Static file serving (Frontend) |
| Model | Provider | Uso |
|---|---|---|
| GPT-3.5-turbo / GPT-4 | OpenAI | Answer generation, query expansion, judging |
| text-embedding-3-small | OpenAI | Document & query embeddings |
# OpenAI Configuration
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-3.5-turbo
# Database Paths
PATH_TO_CHROMADB=/path/to/chromaDB
# Server Configuration
BACKEND_PORT=8000
FRONTEND_PORT=80
# RAG Parameters
TOP_K_RESULTS=3
TEMPERATURE=0.7
MAX_TOKENS=2000| Parameter | Default | Description |
|---|---|---|
| top_k | 3 | Number of documents to retrieve per query |
| num_queries | 3-5 | Number of query variations to generate |
| rrf_k | 60 | RRF smoothing parameter |
| temperature | 0.7 | LLM generation temperature |
| chunk_size | 512 | Document chunk size (tokens) |
| chunk_overlap | 50 | Overlap between chunks (tokens) |
- Containerizare cu Docker permite deployment facil
- Separare frontend/backend permite scaling independent
- ChromaDB poate stoca milioane de vectori
- Componente independente (RAG, LLM, Retriever)
- Ușor de extins cu noi cursuri
- Prompts externalizate în fișiere separate
- Retrieval paralel pentru toate query-urile
- Generation paralel pentru toate răspunsurile
- Streaming responses pentru feedback instant
- Cache BM25 pentru keyword search rapid
- Hybrid search combină semantic + keyword
- Query expansion captează intențiile utilizatorului
- Answer judging selectează cel mai bun răspuns
- Source attribution pentru verificare
- Streaming responses pentru feedback în timp real
- Multi-modal learning (chat + flashcards + quiz)
- Role-based access control
- Course-specific knowledge bases
- API calls la OpenAI (embeddings + completions)
- Storage pentru vectori în ChromaDB
- Multiple LLM calls (query gen, generation, judging)
- Mitigat prin paralelizare
- Require OpenAI API availability
- Require internet connection
- Pipeline RAG sofisticat (mai greu de debug)
- Multiple componente de menținut
-
Clone the repository
git clone https://github.com/LauraDiosan-CS/projects-helpdesk-bt.git cd projects-helpdesk-bt -
Set up environment variables
cp .env.example .env
Edit
.envand add your API keys(example):OPENAI_API_KEY=your_openai_api_key_here
-
Build and run with Docker Compose
docker-compose up --build
-
Navigate to backend directory
cd backend -
Create virtual environment
python -m venv venv
-
Activate virtual environment
- Windows (PowerShell):
.\venv\Scripts\Activate.ps1
- Linux/Mac:
source venv/bin/activate
- Windows (PowerShell):
-
Install dependencies
pip install -r requirements.txt
-
Set environment variables
# Windows PowerShell $env:OPENAI_API_KEY="your_key_here" # Linux/Mac export OPENAI_API_KEY="your_key_here"
-
Navigate to frontend directory
cd frontend -
Install dependencies
npm install
-
Run development server
npm run dev
-
Access frontend
- Development: http://localhost:5173
- Open the application in your browser
- Type your question in the chat interface
- The system will:
- Retrieve relevant documents from the vector database
- Generate a contextual response using the LLM
- Display the answer with source references
GET /api/model
Query Parameters:
prompt(string, required): The user's question
Example:
curl "http://localhost:8000/api/model?prompt=How%20do%20I%20reset%20my%20password?"Response:
{
"role": "assistant",
"content": "To reset your password..."
}projects-helpdesk-bt/
├── backend/
│ ├── main.py # FastAPI application entry point
│ ├── RAGModel.py # RAG orchestration
│ ├── requirements.txt # Python dependencies
│ ├── Dockerfile # Backend container config
│ ├── .dockerignore # Docker ignore rules
│ ├── embeddingModel/
│ │ └── documentRetriever.py # Vector search & retrieval
│ └── llmModel/
│ └── LlmModel.py # OpenAI LLM integration
├── frontend/
│ ├── src/
│ │ ├── main.tsx # React entry point
│ │ ├── App.tsx # Main app component
│ │ ├── api.ts # API client
│ │ └── components/ # React components
│ │ ├── Chat.tsx
│ │ ├── Header.tsx
│ │ ├── Footer.tsx
│ │ └── Logo.tsx
│ ├── package.json # Node dependencies
│ ├── Dockerfile # Frontend container config
│ ├── .dockerignore # Docker ignore rules
│ ├── vite.config.ts # Vite configuration
│ └── tsconfig.json # TypeScript config
├── docker-compose.yml # Multi-container orchestration
├── .env.example # Environment template
└── README.md # This file