Educational RAG System

An AI‑powered educational assistant that turns documents (PDFs) into interactive learning material. Upload a document and the system will answer questions, summarize content, generate quizzes and learnable units, and adapt to the learner — with full support for Arabic (including Egyptian dialect) speech via built‑in Speech‑to‑Text and Text‑to‑Speech.

The project combines a RAG pipeline, a multi‑agent tutoring layer, OCR for scanned/Arabic documents, and a modern React frontend into a single FastAPI service.

---

Table of Contents

• Features
• Architecture
• Tech Stack
• Project Structure
• Getting Started
  • Prerequisites
  • Backend Setup
  • Frontend Setup
  • Docker
• Environment Variables
• API Reference
• Evaluation
• Testing
• License

---

Features

• 📄 Document processing — Upload PDFs; text is extracted, chunked, embedded, and stored in a PostgreSQL + pgvector database.
• 🔍 RAG question answering — Retrieval → relevance checking → reranking → context building → grounded answer generation.
• 📝 Summarization — Generates structured summaries (title, content, key points).
• 🧠 Tutor & Content Processor Agents — A multi‑agent layer that produces adaptive explanations, learnable units, and quizzes tailored to the learner.
• 🧭 Smart intent routing — Classifies each message as a query or an action and dispatches it to the correct handler (QA, summarize, tutor, etc.).
• 🗣️ Speech‑to‑Text (ASR) — Transcribes audio (Egyptian Arabic supported) using a SeamlessM4T‑v2 pipeline.
• 🔊 Text‑to‑Speech (TTS) — Streams spoken responses via ElevenLabs.
• 👁️ OCR module — Handles scanned and Arabic documents using Surya OCR plus Qwen2‑VL / Qari vision‑language models.
• 💬 Conversation persistence — Sessions, chat history, notes, summaries, and QA items are stored and retrievable.
• 📊 Evaluation suite — Notebook‑based RAG evaluation using BERTScore, ROUGE, and semantic similarity metrics.
• 🖥️ Modern frontend — React 18 + TypeScript + Vite + Tailwind UI with chat, voice recording, book visualization, and history.

---

Architecture

                         ┌──────────────────────────┐
                         │   React Frontend (Vite)   │
                         │  chat · voice · history   │
                         └────────────┬─────────────┘
                                      │ REST (JSON / multipart)
                         ┌────────────▼─────────────┐
                         │      FastAPI (main.py)    │
                         │   CORS · routers · nodes  │
                         └────────────┬─────────────┘
                                      │
        ┌───────────────┬────────────┼─────────────┬────────────────┐
        ▼               ▼            ▼              ▼                ▼
  Intent / Action    RAG Pipeline   Agents        ASR (STT)       TTS
   Router / Chains   ┌──────────┐  ┌──────────┐  SeamlessM4T‑v2   ElevenLabs
                     │ retrieve │  │ Content  │
                     │ relevance│  │ Processor│
                     │ rerank   │  │  Agent   │
                     │ context  │  │ Tutor    │
                     │ generate │  │  Agent   │
                     └────┬─────┘  └──────────┘
                          ▼
             PostgreSQL + pgvector (Neon)
        documents · chunks · sessions · QA · summaries · notes

The core RAG workflow is also expressed as a LangGraph state machine (backend/core/graph.py): loader → chunk_store → router → {qa | summarization | content_processor_agent} → END.

---

Tech Stack

Backend

• Python 3.10 (>=3.10,<3.11) — note the Docker image uses 3.11‑slim
• FastAPI + Uvicorn
• LangChain / LangGraph orchestration
• LLM providers: Groq (qwen/qwen3-32b) and Ollama (gpt-oss:120b-cloud)
• Embeddings: sentence-transformers/gtr-t5-base
• Reranker: BAAI/bge-reranker-v2-m3 (CrossEncoder)
• OCR: Surya OCR, Qwen2‑VL‑2B, Qari‑OCR
• ASR: SeamlessM4T‑v2 (via transformers / torchaudio)
• TTS: ElevenLabs
• PostgreSQL + pgvector (Neon), SQLAlchemy (async, asyncpg), Alembic

Frontend

• React 18 + TypeScript
• Vite 6
• Tailwind CSS 4 + Radix UI + MUI
• React Router 7, Recharts, Motion

---

Project Structure

educational_rag_system/
├── backend/
│   ├── api/
│   │   ├── main.py                 # FastAPI app & endpoints
│   │   └── routers/                # sessions, chat_history, tts
│   ├── core/
│   │   ├── graph.py                # LangGraph RAG workflow
│   │   ├── nodes/                  # loader, chunk_store, qa, summarizer, router
│   │   ├── rag/                    # retriever, relevance, context, generator, orchestrator
│   │   ├── agents/                 # ContentProcessorAgent, TutorAgent + handlers
│   │   ├── action_agent/           # intent classification, routing, dispatchers
│   │   ├── ocr_module/             # Surya / Qwen‑VL / Qari OCR
│   │   ├── ASR/                    # Speech‑to‑Text pipeline
│   │   └── TTS/                    # Text‑to‑Speech streaming
│   ├── database/
│   │   ├── db.py                   # Async engine (Neon / pgvector)
│   │   ├── models/                 # SQLAlchemy models
│   │   ├── repositories/           # Data access layer
│   │   └── migrations/             # Schema migrations
│   ├── models/                     # LLM, embedder & reranker wrappers
│   └── config.py                   # Device / cache / GLOBAL_K settings
├── frontend/                       # React + Vite app
├── evaluation/                     # RAG evaluation notebook & cache
├── tests/                          # pytest suite
├── Dockerfile
├── pyproject.toml / requirements.txt / uv.lock
└── example.env

---

Getting Started

Prerequisites

• Python 3.10 (backend) — Docker image builds on Python 3.11
• Node.js 18+ and npm (frontend)
• A PostgreSQL database with the pgvector extension (e.g. Neon)
• API keys: Groq, ElevenLabs, and optionally Ollama / LangSmith
• poppler (for pdf2image) if processing scanned PDFs

Backend Setup

This project uses uv (a uv.lock is committed), but plain pip works too.

# Clone
git clone <repo-url>
cd educational_rag_system

# Option A: uv (recommended)
uv sync

# Option B: pip + venv
python3.10 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Configure environment
cp example.env .env
# then edit .env with your keys & DATABASE_URL

# Run the API
uvicorn backend.api.main:app --host 0.0.0.0 --port 8000 --reload

The API will be available at http://localhost:8000 and interactive docs at http://localhost:8000/docs.

Frontend Setup

cd frontend
npm install
npm run dev      # start Vite dev server
npm run build    # production build

Point the frontend at your backend via its API service configuration (frontend/src/app/services/api.ts).

Docker

A multi‑stage Dockerfile builds a lean runtime image:

docker build -t educational-rag-backend:latest .
docker run -p 8000:8000 --env-file .env educational-rag-backend:latest

A /health healthcheck is included in the image.

---

Environment Variables

Copy example.env to .env and fill in the values:

Additional keys such as ELEVENLABS_API_KEY, OLLAMA_API_KEY, OLLAMA_BASE_URL, and MODEL_NAME (for the ASR model) may be required depending on which features you enable.

---

API Reference

Base URL: http://localhost:8000

Full interactive documentation (Swagger UI) is served at /docs.

Example — upload and ask a question:

# Upload a PDF
curl -F "[email protected]" http://localhost:8000/api/upload

# Ask a question about it
curl -F "query=What are the key concepts in chapter 2?" \
     http://localhost:8000/api/qa

---

Evaluation

The evaluation/ directory contains rag_evualuation.ipynb, which measures RAG answer quality using BERTScore, ROUGE, and semantic‑similarity metrics (embeddings cached under evaluation/cache/). Open it in Jupyter:

jupyter notebook evaluation/rag_evualuation.ipynb

---

Testing

Tests use pytest:

pytest                 # run all tests
pytest tests/test_repo.py
pytest tests/chunk_test.py

---

License

No license file is currently included in this repository. Add a LICENSE file to clarify usage terms before distribution.