Merge branch 'main' of https://github.com/EduChatbot/chatbot-backend

Author: JanOpala

README.md

@@ -1,130 +1,59 @@
-# Chatbot Backend
+# Learning module with conversational educational system - Backend Module
 
-Educational chatbot with Moodle integration and RAG capabilities.
+This repository contains the Backend Module developed as the primary functional layer for the Bachelor's Engineering Thesis: **"Learning module with conversational educational system"**.
 
-## Project Structure
+---
 
-```
-chatbot-backend/
-├── app/                      # Main application
-│   ├── __init__.py
-│   ├── main.py              # FastAPI app setup
-│   ├── api/
-│   │   └── routes/          # API endpoints
-│   │       ├── chat.py      # Chat endpoints
-│   │       ├── moodle.py    # Moodle integration
-│   │       ├── embeddings.py # Embedding generation
-│   │       └── health.py    # Health checks
-│   ├── services/            # Business logic
-│   │   ├── llm_service.py   # LLM integration (Ollama)
-│   │   ├── moodle_service.py
-│   │   ├── embedding_service.py # Embedding generation
-│   │   └── rag_service.py   # RAG
-│   ├── models/              # Data models
-│   │   ├── schemas.py       # Pydantic schemas
-│   │   └── database.py      # SQLAlchemy models
-│   ├── core/
-│   │   └── database.py      # DB connection
-│   └── config/              # Configuration
-│       └── settings.py
-├── docker-compose.yaml
-├── Dockerfile               # Backend container
-├── Dockerfile.ollama        # Ollama container
-├── requirements.txt
-└── README.md
-```
+## Academic Context
+* **University:** Warsaw University of Technology (Politechnika Warszawska)
+* **Faculty:** Faculty of Mathematics and Information Science (MiNI)
+* **Supervisor:** dr inż. Anna Wróblewska
+* **Authors:** Anna Ostrowska, Gabriela Majstrak, Jan Opala
 
-## Setup
+---
 
-### Prerequisites
+## Technical Stack & Architecture
+The backend is built as a high-performance REST API using **FastAPI**, designed to utilize the RAG (Retrieval-Augmented Generation) pipeline.
 
-- Docker Desktop
-- Python 3.10+ (for local development)
-- 8GB+ RAM recommended
+### Core Technologies:
+* **Vector Database:** ChromaDB for efficient semantic search and context retrieval.
+* **OCR & Parsing:** Adaptive document processing.
+* **LLM Orchestration:** Integration with **OpenAI (GPT-4o-mini)** and **Google Gemini** for generation, and **Voyage AI** for embeddings.
+* **Task Scheduling:** **APScheduler** automatically synchronizes course materials from Moodle.
 
-### Environment Variables
+---
 
-Create a `.env` file:
+## Key Features
 
-```env
-# LLM Settings
-LLM_BASE_URL=http://ollama:11434
-CHAT_MODEL=
-EMBED_MODEL=
-LLM_TIMEOUT=
-MAX_TOKENS=
-TEMPERATURE=
+### 1. Advanced Document Ingestion
+The system features a custom-built ingestion pipeline (`parser_utils.py`) that includes:
+* **Adaptive OCR**
+* **Context-Aware Chunking**
+* **Math Normalization**
 
-# Moodle Settings
-MOODLE_BASE_URL=
+### 2. Intelligent Services
+* **RAG Pipeline:**  Uses vector search to provide factually grounded answers strictly based on course content.
+* **Quiz Generation:** Automated assessment creation based on Bloom's Taxonomy to evaluate student understanding.
+* **Smart Sync:** Periodic background jobs that check for new course materials without manual teacher intervention.
 
-# Database
-DATABASE_URL=
+---
 
-# CORS
-CORS_ORIGINS=["http://localhost:3000","https://moodle-edu-chatbot.vercel.app"]
-```
+## Repository Structure
+* **`app/api/routes/`**: Define API endpoints for chat, quiz, and dashboard features.
+* **`app/services/`**: Core business logic, including the RAG engine and embedding management.
+* **`app/core/parser_utils.py`**: Technical implementation of the parsing and OCR logic.
+* **`Dockerfile` & `docker-compose.yaml`**: Full containerization setup for easy deployment and scalability.
 
-### Docker Deployment
+---
 
-```powershell
-# Build and start all services
+## Deployment (Docker)
+1. Ensure your `.env` file is configured with the necessary API keys.
+2. Build and start the system:
+```bash
 docker compose up -d --build
-
-# Check logs
-docker compose logs -f
-
-# Stop services
-docker compose down
-```
-
-## API Endpoints
-
-### Chat
-
-**POST** `/chat`
-
-```json
-{
-  "message": "Hello!",
-  "history": [
-    {"role": "user", "content": "Previous message"},
-    {"role": "assistant", "content": "Previous response"}
-  ],
-  "stream": false
-}
 ```
+The API will be available at http://localhost:8000 with interactive Swagger documentation at /docs.
 
-### Embeddings
-
-**POST** `/api/embeddings?text=your_text`
-
-Returns vector embedding with dimensions.
-
-### Moodle
-
-**POST** `/api/moodle/login`
-
-```json
-{
-  "username": "user",
-  "password": "pass"
-}
-```
-
-**GET** `/api/moodle/courses?token=YOUR_TOKEN`
-
-**GET** `/api/moodle/assignments?token=YOUR_TOKEN&course_id=1`
-
-### Health
-
-**GET** `/health` - Returns `{"status": "ok"}`
-
-
-## Configuration
-
-All configuration is in `app/config/settings.py`. Override via:
+---
 
-1. `.env` file
-2. Environment variables
-3. Defaults in Settings class
+*Developed as the primary technical part of the diploma process at Warsaw University of Technology.*