AI-Powered Learning System

Personalized study app with a React + Vite frontend and a FastAPI backend.

The current production path uses an LLM-guided live scheduler for topic ordering and rescheduling, plus RAG for syllabus analysis and study chat. The old supervised reschedule benchmark is no longer the product path; rescheduling is now evaluated as a live planner with operational signals.

What It Does

• Upload syllabi and study material, then extract subject -> unit -> topic hierarchies.
• Build a live daily study plan from study hours, topic difficulty, and user actions.
• Mark topics as complete, missed, skip tomorrow, or do later.
• Keep a daily plan history so the user can see what changed and why.
• Track progress, motivation, analytics, profile state, and community features.
• Answer questions from uploaded study material using local Ollama-powered RAG.

Current Scheduling Path

The adaptive scheduler now works like this:

1. Syllabus analysis and current topic state are loaded from the database.
2. Ollama ranks topics by urgency, difficulty, importance, and user behavior.
3. Missed topics move to the next planning day.
4. Skip tomorrow pushes the topic one day later.
5. Do later lets the LLM place the topic further out based on load and difficulty.
6. The deterministic packer fits the result into the user's study hours.
7. The final study plan is saved in study_plans, with an AgentDecision and schedule history record.

This repo does not use a true reinforcement-learning pipeline for rescheduling.

Tech Stack

Frontend:

• React 18
• Vite
• React Router 6
• Recharts
• Framer Motion
• Lucide React

Backend:

• FastAPI
• SQLAlchemy async ORM
• SQLite by default, PostgreSQL when configured
• Redis
• Celery
• JWT auth with bcrypt
• httpx for Ollama calls
• scikit-learn, LightGBM, XGBoost, pandas, NumPy
• PyMuPDF, python-pptx, pytesseract, Pillow

Local AI:

• Ollama
• mistral:latest for generation in the current local setup
• nomic-embed-text for embeddings

Baseline Metrics

The latest saved historical supervised baselines are in backend/app/evaluation_plots/summary/metrics.json.

Agent	Baseline metric
Progress	AUC 0.8249, accuracy 0.7616
Motivation	Accuracy 0.8773, weighted F1 0.8772
Profiling	Silhouette 0.2941, 4 clusters

Progress-agent top features in backend/app/evaluation_plots/progress/top_features.json are led by diff_gap, attempt_n, difficulty, log_time_since_q, and u_cum_acc.

The rescheduler no longer has a supervised ML baseline in the product path. It is now measured with live planner signals instead of an old regression score.

Live Scheduler Metrics

Fresh operational metrics for the new scheduler are saved in backend/app/evaluation_plots/summary/llm_scheduler_metrics.json and were generated by backend/ml/evaluate_llm_scheduler.py.

Current local run:

Signal	Value
Planner mode	rag-llm
LLM used	false in this local run because the current Ollama model did not return in time
Subject count	11
Topics evaluated	2180
Topics scheduled	2180
Coverage ratio	1.0
Topic guidance count	545
Schedule days	2138
Average difficulty	4.0
Forced-topic offset mean	186.0714 days

The live scheduler is still the right evaluation target. This report measures how the planner behaves with real uploaded-syllabus data, not a deleted reschedule model.

Evaluation Artifacts

Checked-in artifacts currently include:

• backend/app/evaluation_plots/summary/metrics.json
• backend/app/evaluation_plots/summary/llm_scheduler_metrics.json
• backend/app/evaluation_plots/summary/llm_scheduler_summary.png
• backend/app/evaluation_plots/summary/llm_scheduler_timeline.png
• backend/app/evaluation_plots/summary/model_summary.png
• backend/app/evaluation_plots/summary/new_summary.jpeg
• backend/app/evaluation_plots/progress/roc_curve.png
• backend/app/evaluation_plots/progress/perm_importance.png
• backend/app/evaluation_plots/motivation/confusion_matrix.png

The historical supervised evaluation script at backend/ml/evaluate_all.py still covers the ML baselines. The live scheduler report is now generated separately by backend/ml/evaluate_llm_scheduler.py.

Data Sources Present in the Repo

Raw datasets currently present under backend/data/raw/ include:

• Riiid Answer Correctness Prediction (riiid-test-answer-prediction)
• ASSISTments 2015 skill builder data (2015_100_skill_builders_main_problems.csv)
• Open University Learning Analytics Dataset (OULAD/)
• University Student Stress Dataset (University Student Stress Dataset/)
• Student Performance datasets (StudentPerformance/, student+performance.zip, student_performance.csv)
• Additional cleaned or merged CSVs used to build the current training sets

These sources feed the current progress, motivation, profiling, and reschedule training flows.

Local Development

Frontend:

npm install
npm run dev

Backend:

pip install -r backend/requirements.txt
uvicorn backend.api:app --reload --port 8000

If POSTGRES_URL or DATABASE_URL is not set, the backend uses SQLite at backend/ai_learning.db.

Docker Deployment

The container stack is in backend/docker/docker-compose.yml.

docker compose -f backend/docker/docker-compose.yml up --build

That stack starts backend, db, redis, celery-worker, celery-beat, and ollama.

Configuration

Variable	Purpose	Default
POSTGRES_URL	PostgreSQL connection string	Falls back to SQLite
DATABASE_URL	Alternate database URL	Falls back to SQLite
REDIS_URL	Redis connection string	redis://localhost:6379/0
CELERY_BROKER_URL	Celery broker URL	redis://localhost:6379/1
SECRET_KEY	JWT signing secret	change-me-in-production-32-chars!
OLLAMA_URL	Ollama base URL	http://ollama:11434 in Docker
OLLAMA_EMBED_MODEL	Embedding model	nomic-embed-text
OLLAMA_GEN_MODEL	Generation model used by the live planner	Set to the Ollama model installed in your environment

Notes For a Resume or Paper

The current story is:

• baseline ML agents still exist for progress, motivation, and profiling,
• rescheduling is now a live Ollama-guided planner with operational evaluation,
• the old supervised reschedule benchmark is no longer the product path,
• plan history and user actions are used to measure how the scheduler behaves over time.

That is the version the README should describe. It should not claim true RL if the code is not training one.

License

MIT. See LICENSE.