EduRAG — AI Learning Companion

A production-grade personalized AI tutor powered by RAG (Retrieval-Augmented Generation), FastAPI, FAISS, and Google Gemini.

---

Features

Feature	Description
📁 Document Ingestion	Upload PDF, TXT, MD, DOCX — auto-chunked and embedded
💬 AI Tutor	Simple (ELI5) and Detailed explanations via RAG
🧠 Quiz Generation	MCQs auto-generated from your study materials
📊 Progress Tracking	Quiz history, topic performance, weak areas
💡 Personalization	Tailored study suggestions based on performance
🔄 Memory	Persistent student profiles across sessions
🌐 Dashboard	Beautiful dark-mode SPA with chat, upload, quiz, and progress tabs

---

Tech Stack

Layer	Technology
LLM	Google Gemini 1.5 Flash
Embeddings	sentence-transformers/all-MiniLM-L6-v2 (local)
Vector Store	FAISS (file-persisted)
Backend	FastAPI + Uvicorn
PDF Parsing	PyMuPDF
Memory	JSON file store
Frontend	Vanilla HTML/CSS/JS (ES modules)

---

Quick Start

1. Clone & Install

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux

# Install dependencies
pip install -r requirements.txt

2. Configure

# Copy the example env file
copy .env.example .env         # Windows
# cp .env.example .env         # macOS/Linux

# Edit .env and add your Gemini API key
GEMINI_API_KEY=your_key_here

Get a free Gemini API key at: https://makersuite.google.com/app/apikey

3. Run

# From the project root (eduRAG/)
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

4. Open Dashboard

Navigate to http://localhost:8000 in your browser.

The interactive API docs are available at http://localhost:8000/api/docs.

---

Project Structure

eduRAG/
├── backend/
│   ├── main.py              # FastAPI app, lifespan, routing
│   ├── config.py            # Pydantic-settings configuration
│   ├── core/
│   │   ├── chunker.py       # Recursive character text splitter
│   │   ├── embeddings.py    # SentenceTransformer wrapper
│   │   ├── vector_store.py  # FAISS index with JSON metadata
│   │   ├── retriever.py     # Top-k retrieval with quality filter
│   │   ├── llm.py           # Gemini LLM client with retry
│   │   ├── tutor.py         # Answer generation (simple/detailed)
│   │   ├── quiz.py          # MCQ generation & evaluation
│   │   ├── ingestion.py     # PDF/TXT/DOCX parsing pipeline
│   │   └── memory.py        # Student profile persistence
│   ├── api/
│   │   ├── ingest.py        # POST /api/ingest
│   │   ├── ask.py           # POST /api/ask
│   │   ├── quiz.py          # POST /api/quiz/generate, /evaluate
│   │   └── profile.py       # GET /api/profile/{id}
│   ├── models/
│   │   └── schemas.py       # Pydantic request/response models
│   └── data/                # Auto-created on first run
│       ├── vector_store/    # FAISS index files
│       ├── profiles/        # Student JSON profiles
│       └── uploads/         # Uploaded documents
├── frontend/
│   ├── index.html           # SPA shell
│   ├── css/style.css        # Complete design system
│   └── js/
│       ├── app.js           # Router, state, API client
│       ├── chat.js          # Chat UI
│       ├── upload.js        # Document upload UI
│       └── quiz.js          # Quiz UI
├── .env.example
├── requirements.txt
└── README.md

---

API Reference

Endpoint	Method	Description
/api/health	GET	System health + vector store stats
/api/ingest	POST	Upload a document (multipart/form-data)
/api/ask	POST	Ask the AI tutor a question
/api/quiz/generate	POST	Generate MCQs for a topic
/api/quiz/evaluate	POST	Grade submitted quiz answers
/api/profile/{id}	GET	Fetch student profile
/api/profile/{id}/suggestions	GET	Get personalized suggestions
/api/profile/{id}	DELETE	Reset student profile

Full interactive docs: http://localhost:8000/api/docs

---

Usage Examples

Upload a document

curl -X POST http://localhost:8000/api/ingest \
  -F "file=@lecture_notes.pdf"

Ask a question

curl -X POST http://localhost:8000/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "What is backpropagation?", "mode": "simple", "student_id": "alice"}'

Generate a quiz

curl -X POST http://localhost:8000/api/quiz/generate \
  -H "Content-Type: application/json" \
  -d '{"topic": "Neural Networks", "num_questions": 5, "student_id": "alice"}'

---

Configuration Reference

Variable	Default	Description
GEMINI_API_KEY	required	Google Gemini API key
GEMINI_MODEL	gemini-1.5-flash	Gemini model variant
CHUNK_SIZE	800	Characters per chunk
CHUNK_OVERLAP	100	Overlap between chunks
TOP_K_RETRIEVAL	5	Chunks retrieved per query
EMBEDDING_MODEL	all-MiniLM-L6-v2	SentenceTransformer model

---

License

MIT — free for personal and commercial use.