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`