File size: 6,788 Bytes
b37b90f 29baa44 b37b90f d2f5b64 b37b90f 29baa44 c47ea86 29baa44 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 | ---
title: Adaptive Elearning Backend
emoji: ðŸ§
colorFrom: yellow
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
---
# Adaptive E-Learning System
Adaptive tutoring that models what each learner knows, teaches at their level, and brings topics
back just before they are forgotten.
> [!WARNING]
> **Portfolio project, not a production service.** The live demo exists to showcase the project.
>
> - **Limited AI in the live demo:** the demo's Gemini API quota has run out, so AI-written lessons,
> hints and tutor replies fall back to built-in content (quizzes, the learner model and
> recommendations work fully). For the full experience, clone this repo, add your own
> `GEMINI_API_KEY` (free at [Google AI Studio](https://aistudio.google.com/apikey)) and run or deploy it
> yourself (see [Running locally](#running-locally) and [Deployment](#deployment)).
> - **No persistent data:** the backend runs on Hugging Face's free tier, so accounts and progress may be
> reset whenever the Space restarts or goes to sleep after inactivity. The first request after a quiet
> period can take about 30 seconds while the server wakes up.
- **Frontend**: React + Vite + Tailwind (Vercel), at https://adaptive-e-learning-system.vercel.app
- **Backend**: Flask API on a Hugging Face Space (Docker)
- **Agents**: LangGraph multi-agent graph with LangChain structured outputs (Gemini)
- **Learner model**: Bayesian Knowledge Tracing (online) plus a transformer knowledge-tracing model
trained on GPU and served on CPU through ONNX Runtime
## Architecture
```
React (Vercel) ──Bearer token──► Flask API (HF Space, gunicorn gthread)
│
├── Coordinator = LangGraph StateGraph
│ START → KnowledgeAgent (learner profile)
│ ├─► TeachingAgent: strategy bandit → structured lesson (LLM / cache / offline)
│ ├─► AssessmentAgent: plan (target 70% success) → question bank
│ │ ↺ generate_questions (one LLM call, only when the bank runs short)
│ ├─► TutorAgent: hint ladder (socratic → conceptual → direct)
│ └─► RecommendationAgent: readiness, ZPD, spaced-repetition urgency
├── Tutor chat = LangGraph MessagesState + SQLite checkpointer (memory per user × topic)
├── Learner model = BKT (persisted) + forgetting curve + transformer KT (ONNX)
└── SQLite (WAL): users, attempts, question bank, lesson cache, bandit posteriors
```
| Agent | Decides | How |
|---|---|---|
| Knowledge | What does the learner know right now? | BKT posterior per topic, exponential forgetting, transformer KT predictions of P(correct) for every topic × difficulty |
| Teaching | How to teach this learner? | Expert rules provide the prior; a Thompson-sampling bandit learns from follow-up quiz results which strategy works per knowledge bucket |
| Assessment | Which questions, at what difficulty? | Difficulty mix chosen so predicted success ≈ 70%; unseen bank items preferred and calibrated by empirical p-correct; server-side grading |
| Tutor | How much help to give? | Hint level escalates with attempts; the LLM phrases it using the learner's code, output and mastery |
| Recommendation | What next? | Prerequisite readiness gate, learning potential, zone of proximal development, review urgency, goals |
## Knowledge-tracing results
Trained on an RTX 5090 (`training/`). Metric: test AUC for predicting the next answer.
**Real student data** (ASSISTments, standard DKVMN splits), used to validate the training harness:
| Model | ASSIST2009 | ASSIST2015 |
|---|---|---|
| BKT (per-skill, grid-search fit) | 0.711 | 0.702 |
| DKT (LSTM) | **0.819** | **0.731** |
| Transformer KT (best of a 16-config sweep) | 0.810 | 0.727 |
DKT matches published numbers. On these small datasets the transformer does not beat DKT, which is
consistent with public KT benchmarks.
**App curriculum** (20 topics, 3 difficulties, time gaps; 7.15M interactions from a learner simulator
with prerequisites, ZPD learning and forgetting):
| Model | Test AUC |
|---|---|
| Oracle (simulator's true probabilities, upper bound) | 0.719 |
| **Transformer KT, deployed (669k params, 2.7 MB ONNX)** | **0.693** |
| DKT (LSTM) | 0.689 |
| BKT | 0.654 |
| v1 heuristic tracker | 0.607 |
The deployed model captures about 88% of the achievable discrimination above chance; the v1 heuristic captured about 49%.
The simulator is not real learner data. Retrain on real logs with
`--app-db data/database.db` once the app has users; the pipeline appends them to the training set.
## Running locally
```bash
# one isolated env for the whole project (GPU wheels bundle their own CUDA runtime;
# the system driver/CUDA are untouched)
conda env create -f environment.yml && conda activate elearn
# backend (offline mode without a key: question bank + curriculum lessons)
cd backend && cp .env.example .env # add GEMINI_API_KEY and SECRET_KEY
SESSION_COOKIE_SECURE=false python app.py # http://localhost:7860
pytest tests -q
# frontend
cd frontend && npm install && npm run dev # http://localhost:3000
```
Retrain the models (GPU):
```bash
python training/train_kt.py --dataset assist2009 --model all # benchmark
python training/train_kt.py --dataset curriculum --model transformer \
--students 100000 --d 128 --layers 3 --heads 4 --dropout 0.1 --export # production model → backend/ml/artifacts
```
## Deployment
- **HF Space**: built from the root `Dockerfile`. Set the secrets `SECRET_KEY` and `GEMINI_API_KEY`
(optional: `LLM_MODEL`). Enable persistent storage to keep the database across restarts; it is used
automatically when `/data` is mounted.
- **Vercel**: root `frontend/`, env `VITE_API_URL=https://sawabedarain-adaptive-elearning-backend.hf.space`.
## API
`POST /api/register` · `POST /api/login` · `GET /api/current-user` · `PUT /api/profile`
`GET /api/topics` · `POST /api/generate-lesson` · `POST /api/generate-quiz` · `POST /api/submit-answer`
`GET /api/progress-summary` · `GET /api/knowledge-states` · `GET /api/recommendations` · `GET /api/next-topic`
`GET /api/learning-path/<id>` · `GET /api/review-queue` · `GET /api/study-tips`
`POST /api/check-code` (sandboxed subprocess) · `POST /api/ask-challenge-hint`
`POST /api/tutor/chat` · `GET|DELETE /api/tutor/history` · `GET /api/agent-status` · `GET /api/model-info` · `GET /api/health`
|