ELUG — Explainable Learning Utility Graph

A knowledge-graph-based Explainable AI system for MOOC learning recommendations.

ELUG models learners, concepts, and resources as a tri-partite knowledge graph and recommends resources that maximise expected learning gain while providing transparent, graph-derived explanations.

---

Quick Start

# 1. Create a virtual-env (Python ≥ 3.11)
python -m venv venv && source venv/bin/activate

# 2. Install
pip install -e ".[dev]"

# 3. Run tests
pytest -v

# 4. Run the end-to-end example
python scripts/example_usage.py

# 5. Start the API server
uvicorn elug.api.app:app --reload

---

Project Structure

XAI_AdaptiveTutor/
├── config.yaml                     # Central configuration
├── requirements.txt
├── setup.py
├── data/
│   ├── raw/  processed/  synthetic/
├── notebooks/
│   ├── 01_graph_building.ipynb
│   ├── 02_utility_experiments.ipynb
│   └── 03_evaluation.ipynb
├── elug/
│   ├── config/settings.py          # Pydantic settings from config.yaml
│   ├── schemas/                    # Concept, Resource, Learner, Edges
│   ├── graph/                      # GraphBuilder, Store, Queries
│   ├── learner_model/              # Mastery, Readiness, Uncertainty
│   ├── utility/                    # UtilityCalculator, RankingEngine
│   ├── explainability/             # Concept, Counterfactual, Path Explainer
│   ├── simulation/                 # LearnerSimulator
│   ├── evaluation/                 # Metrics, Baselines
│   ├── api/app.py                  # FastAPI service
│   └── utils/helpers.py
├── tests/test_elug.py
└── scripts/example_usage.py

---

Core Idea

Utility Function

Utility(l, r) = Σ_c (1 − mastery(l,c)) × impact(r,c) × readiness(l,c)

Mastery gap × resource impact × prerequisite readiness produces a single scalar that quantifies expected learning gain.

Explainability

Mode	Description
Concept	Per-concept contribution breakdown, weak concepts, expected gains
Counterfactual	Delta analysis: recommended vs. alternative resource
Path	Prerequisite chains, unmastered prerequisites, shortest learning paths

Baselines

Baseline	Strategy
Random	Uniform random selection
Popularity	Most concepts covered
Mastery-Gap	Largest aggregate mastery gap

---

API Endpoints

Method	Path	Description
POST	/setup	Bulk-populate the knowledge graph
POST	/recommend	Top-k recommendations for a learner
POST	/explain	Generate concept / counterfactual / path explanation
POST	/update_progress	Record resource completion and update mastery
GET	/health	Health check

---

Evaluation Metrics

• Concept Gain — mean mastery increase
• Learning Efficiency — gain per minute
• Gain per Resource — gain per resource consumed
• Explanation Faithfulness — Pearson r between predicted and actual gains

---

License

See LICENSE.