sabrine-oueriech/-AILS-Adaptive-Immersive-Learning-System

AILS is an adaptive intelligent tutoring system that combines: - Cognitive Load Estimation - Explainable AI (SHAP) - Collaborative Filtering - LLM-based Exercise Generation - Real-Time Learning Analytics The system was evaluated with 34 Tunisian Baccalaureate students. # AILS — Adaptive Immersive Learning System Companion code for the paper: > **AILS: An Adaptive Immersive Learning System with Real-Time Cognitive Load Estimation, LLM Exercise Generation, and SHAP-Based Explainability** --- ## Repository structure ``` AILS.ipynb Main notebook (all pipeline cells) README.md This file .gitignore Excludes main.tex (article source, private) ``` --- ## Cell execution order | Cell | Role | Article section | |------|------|----------------| | 1–3 | Imports & API setup | — | | 4–6 | Google Sheets authentication | §4.3 | | 7–10 | CL model (Eq. 1–3), fusion weights (Eq. 3) | §3.1 | | 11–12 | CF recommender (cosine similarity) | §3.2.1 | | 13 | Constants, MODULES, POPULATION_CF/SYN, verify_exercise | §3.2.0.4 / §3.3 | | 14–16 | RAG context builder | §3.2.0.2 | | 17 | SHAP model (GBR + KernelExplainer, Table 4 mapping) | §3.2.2 | | 18 | SAFE_TEMPLATES fallback library | §3.3 | | 19 | *(empty — was duplicate of Cell 17, now removed)* | — | | 20 | Form 1 / Form 2 parsers | §4.2 | | 21 | Google Sheets live analysis (builds df_l) | §7 | | 22–23 | SHAP explainability plots | §3.2.2 | | 24 | Experiment configuration (EXP_STATE, constants) | §4.3 | | 25 | Full pipeline: generate_exercise_rag, _check_mastery, Gradio UI | §3–§4 | | 26 | Launch Gradio interface | §4.3 | | 27 | Statistical analysis (Wilcoxon, CL t-test, Pearson) | §7.2–§7.3 | | 28 | Wilcoxon signed-rank test — dynamic from real data | Table 17 / §7.2 | > **Run Cell 21 before Cells 27–28** to build `df_l` from the live Google Sheet. --- ## Dependencies ```bash pip install gradio mistralai google-auth google-auth-oauthlib \ gspread pandas numpy scipy scikit-learn shap matplotlib seaborn ``` Runtime: **Google Colab** (recommended) or local Python 3.10+. --- ## Credentials (required) Set the following Colab secrets before running: | Secret key | Value | |---|---| | `MISTRAL_API_KEY` | Your Mistral AI key | | `GOOGLE_SERVICE_ …