Add artifacts/models to HF Space repo and fix ignore rules

artifacts/models/answer_scorer/metrics.json

@@ -0,0 +1,45 @@
+{
+  "model_name": "answer_scorer",
+  "model_version": "answer_scorer_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "trained_at": "2026-05-22T05:33:11.363132+00:00",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 8371,
+    "validation": 1820,
+    "test": 1809
+  },
+  "metrics": {
+    "validation": {
+      "mae": 0.4787,
+      "rmse": 0.773,
+      "r_squared": 0.718,
+      "distribution": {
+        "predicted_mean": 1.8303,
+        "predicted_std": 0.9736,
+        "actual_mean": 2.0455,
+        "actual_std": 1.4557
+      },
+      "pct_above_review_threshold": 16.87
+    },
+    "test": {
+      "mae": 0.5256,
+      "rmse": 0.8385,
+      "r_squared": 0.6791,
+      "distribution": {
+        "predicted_mean": 1.8985,
+        "predicted_std": 0.9581,
+        "actual_mean": 2.174,
+        "actual_std": 1.4803
+      },
+      "pct_above_review_threshold": 19.68
+    }
+  },
+  "limitations": [
+    "Trained on synthetic data only.",
+    "TF-IDF features do not capture deep semantic similarity.",
+    "Predictions clipped to [0, max_marks] range.",
+    "teacher_review_required is always True in V2 baseline.",
+    "MAE is the primary metric; individual predictions may deviate significantly."
+  ]
+}

artifacts/models/answer_scorer/model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9f526fa2fd7fdd63a024d3c47d7259efbd85fd8133b0ea12cfc070dc0194109d
+size 8524

artifacts/models/answer_scorer/model_card.md

@@ -0,0 +1,51 @@
+# Model Card: Answer Scorer
+
+## Model Details
+
+- **Model Name:** answer_scorer
+- **Model Version:** answer_scorer_v2_baseline_001
+- **Algorithm:** TF-IDF + Ridge Regression
+- **Framework:** scikit-learn
+- **Trained At:** 2026-05-22T05:33:11.363132+00:00
+- **Seed:** 20260520
+
+## Intended Use
+
+Score subjective student answers against a rubric and model answer.
+Produces a predicted marks value clipped to [0, max_marks]. Always sets
+teacher_review_required=True in V2 baseline — predictions are advisory only.
+
+## Training Data
+
+- **Source:** training_answer_scoring.csv (synthetic dataset v2)
+- **Split Counts:** train=8371, validation=1820, test=1809
+- **Features:** student_answer (TF-IDF, max_features=5000, ngram_range=(1,2)) + rubric_match_score + concept_coverage_score
+- **Target:** teacher_marks (continuous)
+
+## Metrics
+
+### Validation Set
+- MAE: 0.4787
+- RMSE: 0.773
+- R-squared: 0.718
+- % Above Review Threshold (>1.0): 16.87%
+
+### Test Set
+- MAE: 0.5256
+- RMSE: 0.8385
+- R-squared: 0.6791
+- % Above Review Threshold (>1.0): 19.68%
+
+## Known Limitations
+
+- Trained on synthetic data only — performance on real student answers is unknown.
+- TF-IDF features do not capture deep semantic similarity or paraphrasing.
+- Predictions are clipped to [0, max_marks]; the model may predict outside this range before clipping.
+- teacher_review_required is always True in V2 baseline.
+- MAE is the primary metric; individual predictions may deviate significantly from teacher marks.
+
+## Fallback Behavior
+
+When the model is not loaded or confidence is below threshold,
+the system falls back to rubric keyword coverage + length heuristic,
+always setting teacher_review_required=True.

artifacts/models/answer_scorer/training_config.json

@@ -0,0 +1,26 @@
+{
+  "model_name": "answer_scorer",
+  "model_version": "answer_scorer_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 8371,
+    "validation": 1820,
+    "test": 1809
+  },
+  "hyperparameters": {
+    "tfidf_max_features": 5000,
+    "ngram_range": [
+      1,
+      2
+    ],
+    "ridge_alpha": 1.0
+  },
+  "feature_columns": [
+    "student_answer (TF-IDF)",
+    "rubric_match_score",
+    "concept_coverage_score"
+  ],
+  "target_column": "teacher_marks",
+  "algorithm": "TF-IDF + Ridge regression"
+}

artifacts/models/answer_scorer/vectorizer.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a8210b922548969cb609cb8e7c93590e064bfd2208b10647c993f51482bc0442
+size 26983

artifacts/models/bloom_classifier/label_encoder.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:49cd11f5861283c0d8da24d21a2f021791eb64ea0d971e21e6d76ce16c3f2b7f
+size 439

artifacts/models/bloom_classifier/metrics.json

@@ -0,0 +1,204 @@
+{
+  "model_name": "bloom_classifier",
+  "model_version": "bloom_classifier_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "trained_at": "2026-05-22T05:33:07.050037+00:00",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 3912,
+    "validation": 1033,
+    "test": 875
+  },
+  "metrics": {
+    "validation": {
+      "macro_f1": 0.6434,
+      "weighted_f1": 0.6634,
+      "per_class": {
+        "Analyze": {
+          "precision": 0.614,
+          "recall": 0.6774,
+          "f1": 0.6442,
+          "support": 155
+        },
+        "Apply": {
+          "precision": 0.65,
+          "recall": 0.5778,
+          "f1": 0.6118,
+          "support": 270
+        },
+        "Create": {
+          "precision": 0.8947,
+          "recall": 1.0,
+          "f1": 0.9444,
+          "support": 17
+        },
+        "Evaluate": {
+          "precision": 1.0,
+          "recall": 0.1522,
+          "f1": 0.2642,
+          "support": 46
+        },
+        "Remember": {
+          "precision": 0.7438,
+          "recall": 0.5732,
+          "f1": 0.6475,
+          "support": 157
+        },
+        "Understand": {
+          "precision": 0.68,
+          "recall": 0.8325,
+          "f1": 0.7486,
+          "support": 388
+        }
+      },
+      "confusion_matrix": [
+        [
+          105,
+          50,
+          0,
+          0,
+          0,
+          0
+        ],
+        [
+          27,
+          156,
+          0,
+          0,
+          0,
+          87
+        ],
+        [
+          0,
+          0,
+          17,
+          0,
+          0,
+          0
+        ],
+        [
+          37,
+          0,
+          2,
+          7,
+          0,
+          0
+        ],
+        [
+          0,
+          2,
+          0,
+          0,
+          90,
+          65
+        ],
+        [
+          2,
+          32,
+          0,
+          0,
+          31,
+          323
+        ]
+      ]
+    },
+    "test": {
+      "macro_f1": 0.6178,
+      "weighted_f1": 0.6654,
+      "per_class": {
+        "Analyze": {
+          "precision": 0.7,
+          "recall": 0.6853,
+          "f1": 0.6926,
+          "support": 143
+        },
+        "Apply": {
+          "precision": 0.6411,
+          "recall": 0.5678,
+          "f1": 0.6022,
+          "support": 236
+        },
+        "Create": {
+          "precision": 0.8333,
+          "recall": 0.9375,
+          "f1": 0.8824,
+          "support": 16
+        },
+        "Evaluate": {
+          "precision": 0.6667,
+          "recall": 0.0588,
+          "f1": 0.1081,
+          "support": 34
+        },
+        "Remember": {
+          "precision": 0.7677,
+          "recall": 0.608,
+          "f1": 0.6786,
+          "support": 125
+        },
+        "Understand": {
+          "precision": 0.665,
+          "recall": 0.8411,
+          "f1": 0.7428,
+          "support": 321
+        }
+      },
+      "confusion_matrix": [
+        [
+          98,
+          45,
+          0,
+          0,
+          0,
+          0
+        ],
+        [
+          13,
+          134,
+          0,
+          0,
+          0,
+          89
+        ],
+        [
+          0,
+          0,
+          15,
+          1,
+          0,
+          0
+        ],
+        [
+          29,
+          0,
+          3,
+          2,
+          0,
+          0
+        ],
+        [
+          0,
+          2,
+          0,
+          0,
+          76,
+          47
+        ],
+        [
+          0,
+          28,
+          0,
+          0,
+          23,
+          270
+        ]
+      ]
+    }
+  },
+  "limitations": [
+    "Trained on synthetic data only.",
+    "6 classes with imbalanced distribution \u2014 Create (~2%) and Evaluate (~4%) are rare.",
+    "Macro F1 is the primary metric; per-class recall may be low for rare classes.",
+    "TF-IDF features do not capture semantic similarity beyond n-gram overlap."
+  ]
+}

artifacts/models/bloom_classifier/model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c536885f0c45c7cb0318e5a65db523761d0e02b1ce5798e82b1764e4f4dd2d3d
+size 76782

artifacts/models/bloom_classifier/model_card.md

@@ -0,0 +1,47 @@
+# Model Card: Bloom Classifier
+
+## Model Details
+
+- **Model Name:** bloom_classifier
+- **Model Version:** bloom_classifier_v2_baseline_001
+- **Algorithm:** TF-IDF + LogisticRegression (multinomial)
+- **Framework:** scikit-learn
+- **Trained At:** 2026-05-22T05:33:07.050037+00:00
+- **Seed:** 20260520
+
+## Intended Use
+
+Automatically classify questions by Bloom's taxonomy cognitive level.
+Used in the Bloom classification endpoint to predict one of 6 levels:
+Remember, Understand, Apply, Analyze, Evaluate, Create.
+
+## Training Data
+
+- **Source:** training_bloom_classification.csv (synthetic dataset v2)
+- **Split Counts:** train=3912, validation=1033, test=875
+- **Feature:** question_text (TF-IDF vectorized, max_features=8000, ngram_range=(1,2))
+- **Target:** bloom_level (6 classes)
+
+## Metrics
+
+### Validation Set
+- Macro F1: 0.6434
+- Weighted F1: 0.6634
+
+### Test Set
+- Macro F1: 0.6178
+- Weighted F1: 0.6654
+
+## Known Limitations
+
+- Trained on synthetic data only — performance on real classroom questions is unknown.
+- Class imbalance: Create (~2%) and Evaluate (~4%) are rare; recall on these classes may be low.
+- TF-IDF features do not capture semantic similarity beyond n-gram overlap.
+- Macro F1 is the primary metric; accuracy alone would mask poor performance on rare classes.
+
+## Fallback Behavior
+
+When the model is not loaded or confidence is below the threshold (0.55),
+the system falls back to keyword heuristic classification:
+define/list → Remember; explain → Understand; calculate/use → Apply;
+compare/contrast → Analyze; justify → Evaluate; design → Create.

artifacts/models/bloom_classifier/training_config.json

@@ -0,0 +1,28 @@
+{
+  "model_name": "bloom_classifier",
+  "model_version": "bloom_classifier_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 3912,
+    "validation": 1033,
+    "test": 875
+  },
+  "hyperparameters": {
+    "tfidf_max_features": 8000,
+    "ngram_range": [
+      1,
+      2
+    ],
+    "sublinear_tf": true,
+    "logreg_C": 1.0,
+    "logreg_solver": "lbfgs",
+    "logreg_max_iter": 1000,
+    "logreg_multi_class": "multinomial"
+  },
+  "feature_columns": [
+    "question_text"
+  ],
+  "target_column": "bloom_level",
+  "algorithm": "LogisticRegression(multinomial)"
+}

artifacts/models/bloom_classifier/vectorizer.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a1aef70da6176b150f33ce072efdda54115a07b9e1dacc2b2bf25daad5670b49
+size 31067

artifacts/models/difficulty_model/encoder.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:781bac207e91e216ba726703b113d6646eabe3f46567205b10088621e6404f47
+size 704

artifacts/models/difficulty_model/feature_columns.json

@@ -0,0 +1,6 @@
+[
+  "bloom_score",
+  "grade",
+  "subject",
+  "question_type"
+]

artifacts/models/difficulty_model/metrics.json

@@ -0,0 +1,38 @@
+{
+  "model_name": "difficulty_model",
+  "model_version": "difficulty_model_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "trained_at": "2026-05-22T05:33:07.506348+00:00",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 3912,
+    "validation": 1033,
+    "test": 875
+  },
+  "metrics": {
+    "validation": {
+      "mae": 0.3477,
+      "r_squared": 0.5007,
+      "per_bucket_mae": {
+        "easy": 0.3051,
+        "medium": 0.2958,
+        "hard": 0.6525
+      }
+    },
+    "test": {
+      "mae": 0.3514,
+      "r_squared": 0.4693,
+      "per_bucket_mae": {
+        "easy": 0.3241,
+        "medium": 0.2903,
+        "hard": 0.6728
+      }
+    }
+  },
+  "limitations": [
+    "Trained on synthetic data only.",
+    "difficulty_score distribution may not reflect real-world difficulty.",
+    "OrdinalEncoder assumes an ordering that may not be meaningful for subject/question_type.",
+    "Per-bucket MAE depends on the quality of the difficulty string labels."
+  ]
+}

artifacts/models/difficulty_model/model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:87924be76fe290bfce10dec3bbbe137fd942314538029843c12798f3da975e98
+size 735477

artifacts/models/difficulty_model/model_card.md

@@ -0,0 +1,50 @@
+# Model Card: Difficulty Model
+
+## Model Details
+
+- **Model Name:** difficulty_model
+- **Model Version:** difficulty_model_v2_baseline_001
+- **Algorithm:** RandomForestRegressor
+- **Framework:** scikit-learn
+- **Trained At:** 2026-05-22T05:33:07.506348+00:00
+- **Seed:** 20260520
+
+## Intended Use
+
+Estimate question difficulty as a continuous score in [0, 1] based on
+question features (bloom_score, grade, subject, question_type). Used in
+the difficulty estimation endpoint to predict how hard a question is for
+a given grade level.
+
+## Training Data
+
+- **Source:** training_lo_tagging.csv + questions.csv (for question_type)
+- **Split Counts:** train=3912, validation=1033, test=875
+- **Features:** bloom_score (numeric), grade (numeric), subject (OrdinalEncoded), question_type (OrdinalEncoded)
+- **Target:** difficulty_score (continuous [0, 1])
+
+## Metrics
+
+### Validation Set
+- MAE: 0.3477
+- R-squared: 0.5007
+- Per-bucket MAE: {'easy': 0.3051, 'medium': 0.2958, 'hard': 0.6525}
+
+### Test Set
+- MAE: 0.3514
+- R-squared: 0.4693
+- Per-bucket MAE: {'easy': 0.3241, 'medium': 0.2903, 'hard': 0.6728}
+
+## Known Limitations
+
+- Trained on synthetic data only — performance on real questions is unknown.
+- difficulty_score distribution may not reflect real-world difficulty.
+- OrdinalEncoder assumes an ordering that may not be meaningful for subject/question_type.
+- Per-bucket MAE depends on the quality of the difficulty string labels.
+- Limited feature set (4 features); text-based features could improve performance.
+
+## Fallback Behavior
+
+When the model is not loaded or confidence is below threshold, the system
+falls back to a rule-based difficulty estimation using bloom_score and
+grade-level heuristics.

artifacts/models/difficulty_model/training_config.json

@@ -0,0 +1,33 @@
+{
+  "model_name": "difficulty_model",
+  "model_version": "difficulty_model_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 3912,
+    "validation": 1033,
+    "test": 875
+  },
+  "hyperparameters": {
+    "n_estimators": 100,
+    "random_state": 20260520,
+    "algorithm": "RandomForestRegressor",
+    "encoder": "OrdinalEncoder"
+  },
+  "feature_columns": [
+    "bloom_score",
+    "grade",
+    "subject",
+    "question_type"
+  ],
+  "categorical_columns": [
+    "subject",
+    "question_type"
+  ],
+  "numeric_columns": [
+    "bloom_score",
+    "grade"
+  ],
+  "target_column": "difficulty_score",
+  "algorithm": "RandomForestRegressor"
+}

artifacts/models/lo_tagger/label_encoder.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:42e9faea136d20cf19963170fc609d0f3a02b28b6d2e3e376b79739b3f043e43
+size 1147

artifacts/models/lo_tagger/model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1178f614787d62a4f6a96764052381a23df9018505e1f8979110d22ea6db925a
+size 7427598

artifacts/models/lo_tagger/model_card.md

@@ -0,0 +1,50 @@
+# Model Card: LO Tagger
+
+## Model Details
+
+- **Model Name:** lo_tagger
+- **Model Version:** lo_tagger_v2_baseline_001
+- **Algorithm:** TF-IDF + CalibratedClassifierCV(LinearSVC)
+- **Framework:** scikit-learn
+- **Trained At:** 2026-05-22T05:33:05.850313+00:00
+- **Seed:** 20260520
+
+## Intended Use
+
+Automatically tag questions to their most relevant Learning Outcome (LO).
+Used in the LO tagging endpoint to classify question text into one of 194
+learning outcome categories.
+
+## Training Data
+
+- **Source:** training_lo_tagging.csv (synthetic dataset v2)
+- **Split Counts:** train=3912, validation=1033, test=875
+- **Feature:** question_text (TF-IDF vectorized, max_features=10000, ngram_range=(1,2))
+- **Target:** lo_id (194 classes)
+
+## Metrics
+
+### Validation Set
+- Top-1 Accuracy: 0.9245
+- Top-3 Accuracy: 1.0
+- Macro F1: 0.9042
+- Weighted F1: 0.9249
+
+### Test Set
+- Top-1 Accuracy: 0.9097
+- Top-3 Accuracy: 1.0
+- Macro F1: 0.8861
+- Weighted F1: 0.9115
+
+## Known Limitations
+
+- Trained on synthetic data only — performance on real classroom questions is unknown.
+- 194 classes with imbalanced distribution; rare LOs may have low recall.
+- TF-IDF features do not capture semantic similarity beyond n-gram overlap.
+- Top-3 accuracy is the primary metric; top-1 may be low for ambiguous questions.
+
+## Fallback Behavior
+
+When the model is not loaded or confidence is below the threshold (0.55),
+the system falls back to keyword/embedding match against learning_outcomes.embedding_text
+filtered by grade and subject, returning top-3 with rule-based confidence.

artifacts/models/lo_tagger/training_config.json

@@ -0,0 +1,27 @@
+{
+  "model_name": "lo_tagger",
+  "model_version": "lo_tagger_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 3912,
+    "validation": 1033,
+    "test": 875
+  },
+  "hyperparameters": {
+    "tfidf_max_features": 10000,
+    "ngram_range": [
+      1,
+      2
+    ],
+    "sublinear_tf": true,
+    "svc_max_iter": 5000,
+    "calibration_cv": 3,
+    "calibration_method": "sigmoid"
+  },
+  "feature_columns": [
+    "question_text"
+  ],
+  "target_column": "lo_id",
+  "algorithm": "CalibratedClassifierCV(LinearSVC)"
+}

artifacts/models/lo_tagger/vectorizer.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f40dd0d2353b0d608565093d96e288a624498f2acbfcd007dc993e5f47422606
+size 31068

artifacts/models/mastery_model/feature_columns.json

@@ -0,0 +1,11 @@
+[
+  "attempt_count",
+  "accuracy",
+  "average_marks_ratio",
+  "average_time_seconds",
+  "hint_usage_rate",
+  "attendance_percentage",
+  "assignment_completion_rate",
+  "average_login_per_week",
+  "inactive_days_last_14"
+]

artifacts/models/mastery_model/metrics.json

@@ -0,0 +1,132 @@
+{
+  "model_name": "mastery_model",
+  "model_version": "mastery_model_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "trained_at": "2026-05-22T05:33:10.125086+00:00",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 24515,
+    "validation": 5218,
+    "test": 5187
+  },
+  "metrics": {
+    "validation": {
+      "macro_f1": 0.8661,
+      "weighted_f1": 0.8967,
+      "per_class": {
+        "weak": {
+          "precision": 0.9678,
+          "recall": 0.964,
+          "f1": 0.9659,
+          "support": 2247
+        },
+        "developing": {
+          "precision": 0.8908,
+          "recall": 0.9095,
+          "f1": 0.9001,
+          "support": 1337
+        },
+        "proficient": {
+          "precision": 0.7819,
+          "recall": 0.7421,
+          "f1": 0.7615,
+          "support": 826
+        },
+        "mastered": {
+          "precision": 0.8255,
+          "recall": 0.849,
+          "f1": 0.8371,
+          "support": 808
+        }
+      },
+      "confusion_matrix": [
+        [
+          2166,
+          81,
+          0,
+          0
+        ],
+        [
+          72,
+          1216,
+          49,
+          0
+        ],
+        [
+          0,
+          68,
+          613,
+          145
+        ],
+        [
+          0,
+          0,
+          122,
+          686
+        ]
+      ]
+    },
+    "test": {
+      "macro_f1": 0.8763,
+      "weighted_f1": 0.9034,
+      "per_class": {
+        "weak": {
+          "precision": 0.9653,
+          "recall": 0.9722,
+          "f1": 0.9687,
+          "support": 2120
+        },
+        "developing": {
+          "precision": 0.9179,
+          "recall": 0.9067,
+          "f1": 0.9123,
+          "support": 1394
+        },
+        "proficient": {
+          "precision": 0.7887,
+          "recall": 0.7518,
+          "f1": 0.7698,
+          "support": 814
+        },
+        "mastered": {
+          "precision": 0.8354,
+          "recall": 0.8743,
+          "f1": 0.8544,
+          "support": 859
+        }
+      },
+      "confusion_matrix": [
+        [
+          2061,
+          59,
+          0,
+          0
+        ],
+        [
+          74,
+          1264,
+          56,
+          0
+        ],
+        [
+          0,
+          54,
+          612,
+          148
+        ],
+        [
+          0,
+          0,
+          108,
+          751
+        ]
+      ]
+    }
+  },
+  "limitations": [
+    "Trained on synthetic data only.",
+    "4-class mastery labels derived from synthetic mastery_score thresholds.",
+    "All features are numeric; no text or contextual features used.",
+    "Class distribution may not reflect real-world mastery patterns."
+  ]
+}

artifacts/models/mastery_model/model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:36c2dffc14d2708ee128a0859f3f13453a61400f725ce0b56dcbb488043e1090
+size 6881288

artifacts/models/mastery_model/model_card.md

@@ -0,0 +1,56 @@
+# Model Card: Mastery Model
+
+## Model Details
+
+- **Model Name:** mastery_model
+- **Model Version:** mastery_model_v2_baseline_001
+- **Algorithm:** RandomForestClassifier
+- **Framework:** scikit-learn
+- **Trained At:** 2026-05-22T05:33:10.125086+00:00
+- **Seed:** 20260520
+
+## Intended Use
+
+Predict per-student per-LO mastery label (weak, developing, proficient, mastered)
+based on behavioral and performance features. Used in the mastery prediction
+endpoint to classify student mastery level for a given learning outcome.
+
+## Training Data
+
+- **Source:** training_mastery_prediction.csv (synthetic dataset v2)
+- **Split Counts:** train=24515, validation=5218, test=5187
+- **Features:** attempt_count, accuracy, average_marks_ratio, average_time_seconds, hint_usage_rate, attendance_percentage, assignment_completion_rate, average_login_per_week, inactive_days_last_14 (all numeric)
+- **Target:** mastery_label (integer 0-3, mapped to weak/developing/proficient/mastered)
+
+## Metrics
+
+### Validation Set
+- Macro F1: 0.8661
+- Weighted F1: 0.8967
+
+### Test Set
+- Macro F1: 0.8763
+- Weighted F1: 0.9034
+
+## Per-Class Performance (Test Set)
+
+| Class | Precision | Recall | F1 | Support |
+|-------|-----------|--------|-----|---------|
+| weak | 0.9653 | 0.9722 | 0.9687 | 2120 |
+| developing | 0.9179 | 0.9067 | 0.9123 | 1394 |
+| proficient | 0.7887 | 0.7518 | 0.7698 | 814 |
+| mastered | 0.8354 | 0.8743 | 0.8544 | 859 |
+
+## Known Limitations
+
+- Trained on synthetic data only — performance on real student data is unknown.
+- 4-class mastery labels derived from synthetic mastery_score thresholds.
+- All features are numeric; no text or contextual features used.
+- Class distribution may not reflect real-world mastery patterns.
+- No encoding needed since all features are already numeric.
+
+## Fallback Behavior
+
+When the model is not loaded or confidence is below the threshold (0.55),
+the system falls back to rule-based mastery estimation using mastery_score
+thresholds: <0.4 weak, <0.6 developing, <0.8 proficient, else mastered.

artifacts/models/mastery_model/training_config.json

@@ -0,0 +1,35 @@
+{
+  "model_name": "mastery_model",
+  "model_version": "mastery_model_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 24515,
+    "validation": 5218,
+    "test": 5187
+  },
+  "hyperparameters": {
+    "n_estimators": 100,
+    "random_state": 20260520,
+    "algorithm": "RandomForestClassifier"
+  },
+  "feature_columns": [
+    "attempt_count",
+    "accuracy",
+    "average_marks_ratio",
+    "average_time_seconds",
+    "hint_usage_rate",
+    "attendance_percentage",
+    "assignment_completion_rate",
+    "average_login_per_week",
+    "inactive_days_last_14"
+  ],
+  "target_column": "mastery_label",
+  "label_map": {
+    "0": "weak",
+    "1": "developing",
+    "2": "proficient",
+    "3": "mastered"
+  },
+  "algorithm": "RandomForestClassifier"
+}

artifacts/models/recommender/encoder.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:417a9e093b8090b171f8383bc3772bfca90127b02d17a5b543ec3f5517200d2d
+size 699

artifacts/models/recommender/feature_columns.json

@@ -0,0 +1,7 @@
+[
+  "priority",
+  "ai_confidence",
+  "recommendation_type",
+  "grade",
+  "subject"
+]

artifacts/models/recommender/metrics.json

@@ -0,0 +1,33 @@
+{
+  "model_name": "recommender",
+  "model_version": "recommender_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "trained_at": "2026-05-22T05:33:12.270778+00:00",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 5671,
+    "validation": 1214,
+    "test": 1215
+  },
+  "metrics": {
+    "validation": {
+      "roc_auc_clicked": 0.544,
+      "lift_at_10_clicked": 1.1392,
+      "roc_auc_is_completed": 0.5299,
+      "lift_at_10_is_completed": 1.1056
+    },
+    "test": {
+      "roc_auc_clicked": 0.5486,
+      "lift_at_10_clicked": 1.0471,
+      "roc_auc_is_completed": 0.5424,
+      "lift_at_10_is_completed": 1.0366
+    }
+  },
+  "limitations": [
+    "Trained on synthetic data only.",
+    "Two separate GBC models \u2014 no joint optimization of clicked + is_completed.",
+    "OrdinalEncoder assumes an ordering for priority/recommendation_type/subject.",
+    "Lift@10 depends on the distribution of positive labels in the dataset.",
+    "No user-level features (e.g., engagement history) included in baseline."
+  ]
+}

artifacts/models/recommender/model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:27c6e41ce34d625c1fd10f05537051daf7f4ae871ecf147746eeff7203e83d3d
+size 201527

artifacts/models/recommender/model_card.md

@@ -0,0 +1,53 @@
+# Model Card: Recommender
+
+## Model Details
+
+- **Model Name:** recommender
+- **Model Version:** recommender_v2_baseline_001
+- **Algorithm:** GradientBoostingClassifier (two models: clicked, is_completed)
+- **Framework:** scikit-learn
+- **Trained At:** 2026-05-22T05:33:12.270778+00:00
+- **Seed:** 20260520
+
+## Intended Use
+
+Predict whether a student will click on a recommendation and whether they will
+complete the recommended content. Used in the recommendation engine to rank
+content by predicted engagement. Two separate binary classifiers are trained:
+one for `clicked` and one for `is_completed`.
+
+## Training Data
+
+- **Source:** training_recommendation_outcomes.csv (synthetic dataset v2)
+- **Split Counts:** train=5671, validation=1214, test=1215
+- **Features:** priority (OrdinalEncoded), ai_confidence (numeric), recommendation_type (OrdinalEncoded), grade (numeric), subject (OrdinalEncoded)
+- **Targets:** clicked (binary), is_completed (binary)
+
+## Metrics
+
+### Validation Set
+- ROC-AUC (clicked): 0.544
+- ROC-AUC (is_completed): 0.5299
+- Lift@10 (clicked): 1.1392
+- Lift@10 (is_completed): 1.1056
+
+### Test Set
+- ROC-AUC (clicked): 0.5486
+- ROC-AUC (is_completed): 0.5424
+- Lift@10 (clicked): 1.0471
+- Lift@10 (is_completed): 1.0366
+
+## Known Limitations
+
+- Trained on synthetic data only — performance on real recommendation data is unknown.
+- Two separate GBC models — no joint optimization of clicked + is_completed.
+- OrdinalEncoder assumes an ordering for priority/recommendation_type/subject.
+- Lift@10 depends on the distribution of positive labels in the dataset.
+- No user-level features (e.g., engagement history) included in baseline.
+- Limited feature set (5 features); adding student history could improve performance.
+
+## Fallback Behavior
+
+When the model is not loaded or confidence is below threshold, the system
+falls back to knowledge-graph weakest-prerequisite + content_catalog filtered
+by LO + difficulty, ranked by estimated_mastery_gain.

artifacts/models/recommender/training_config.json

@@ -0,0 +1,39 @@
+{
+  "model_name": "recommender",
+  "model_version": "recommender_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 5671,
+    "validation": 1214,
+    "test": 1215
+  },
+  "hyperparameters": {
+    "n_estimators": 100,
+    "max_depth": 4,
+    "random_state": 20260520,
+    "algorithm": "GradientBoostingClassifier",
+    "encoder": "OrdinalEncoder"
+  },
+  "feature_columns": [
+    "priority",
+    "ai_confidence",
+    "recommendation_type",
+    "grade",
+    "subject"
+  ],
+  "categorical_columns": [
+    "priority",
+    "recommendation_type",
+    "subject"
+  ],
+  "numeric_columns": [
+    "ai_confidence",
+    "grade"
+  ],
+  "target_columns": [
+    "clicked",
+    "is_completed"
+  ],
+  "algorithm": "GradientBoostingClassifier"
+}

artifacts/models/risk_model/feature_columns.json

@@ -0,0 +1,21 @@
+[
+  "avg_mastery_score",
+  "weak_lo_count",
+  "developing_lo_count",
+  "mastered_lo_count",
+  "avg_confidence",
+  "avg_accuracy",
+  "avg_marks_ratio",
+  "avg_time_seconds",
+  "hint_usage_rate",
+  "total_attempts",
+  "attendance_percentage",
+  "assignment_completion_rate",
+  "average_login_per_week",
+  "inactive_days_last_14",
+  "avg_active_minutes",
+  "total_logins",
+  "avg_video_watch_ratio",
+  "total_content_completed",
+  "total_quiz_attempts"
+]

artifacts/models/risk_model/metrics.json

@@ -0,0 +1,101 @@
+{
+  "model_name": "risk_model",
+  "model_version": "risk_model_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "trained_at": "2026-05-22T05:33:10.882126+00:00",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 1133,
+    "validation": 243,
+    "test": 244
+  },
+  "metrics": {
+    "validation": {
+      "recall_positive": 0.8571,
+      "precision_positive": 0.9231,
+      "f1_positive": 0.8889,
+      "roc_auc": 0.9915,
+      "per_class": {
+        "not_at_risk": {
+          "precision": 0.9706,
+          "recall": 0.9851,
+          "f1": 0.9778,
+          "support": 201
+        },
+        "at_risk": {
+          "precision": 0.9231,
+          "recall": 0.8571,
+          "f1": 0.8889,
+          "support": 42
+        }
+      },
+      "confusion_matrix": [
+        [
+          198,
+          3
+        ],
+        [
+          6,
+          36
+        ]
+      ],
+      "risk_level_recall": {
+        "high": {
+          "recall": 0.8421,
+          "support": 38
+        },
+        "critical": {
+          "recall": 1.0,
+          "support": 4
+        }
+      }
+    },
+    "test": {
+      "recall_positive": 0.8125,
+      "precision_positive": 0.8966,
+      "f1_positive": 0.8525,
+      "roc_auc": 0.9899,
+      "per_class": {
+        "not_at_risk": {
+          "precision": 0.9721,
+          "recall": 0.9858,
+          "f1": 0.9789,
+          "support": 212
+        },
+        "at_risk": {
+          "precision": 0.8966,
+          "recall": 0.8125,
+          "f1": 0.8525,
+          "support": 32
+        }
+      },
+      "confusion_matrix": [
+        [
+          209,
+          3
+        ],
+        [
+          6,
+          26
+        ]
+      ],
+      "risk_level_recall": {
+        "high": {
+          "recall": 0.7778,
+          "support": 27
+        },
+        "critical": {
+          "recall": 1.0,
+          "support": 5
+        }
+      }
+    }
+  },
+  "limitations": [
+    "Trained on synthetic data only.",
+    "Binary risk_label derived from synthetic risk_score thresholds.",
+    "All features are numeric; no text or contextual features used.",
+    "Class imbalance (~16% positive) addressed via class_weight='balanced'.",
+    "Critical class (~2%) recall should be monitored separately."
+  ]
+}

artifacts/models/risk_model/model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d10e1aed1d17c9b2973771c900a258d13393df793c0b766667546904a0af505a
+size 151205

artifacts/models/risk_model/model_card.md

@@ -0,0 +1,71 @@
+# Model Card: Risk Model
+
+## Model Details
+
+- **Model Name:** risk_model
+- **Model Version:** risk_model_v2_baseline_001
+- **Algorithm:** RandomForestClassifier (class_weight="balanced")
+- **Framework:** scikit-learn
+- **Trained At:** 2026-05-22T05:33:10.882126+00:00
+- **Seed:** 20260520
+
+## Intended Use
+
+Predict whether a student is at-risk (binary: 0=not at-risk, 1=at-risk) based on
+mastery, performance, and engagement features. Used in the risk prediction endpoint
+to identify students who may need intervention. Primary optimization target is
+recall on the positive class to minimize missed at-risk students.
+
+## Training Data
+
+- **Source:** training_risk_prediction.csv (synthetic dataset v2)
+- **Split Counts:** train=1133, validation=243, test=244
+- **Features:** avg_mastery_score, weak_lo_count, developing_lo_count, mastered_lo_count, avg_confidence, avg_accuracy, avg_marks_ratio, avg_time_seconds, hint_usage_rate, total_attempts, attendance_percentage, assignment_completion_rate, average_login_per_week, inactive_days_last_14, avg_active_minutes, total_logins, avg_video_watch_ratio, total_content_completed, total_quiz_attempts (all numeric, 19 features)
+- **Target:** risk_label (binary 0/1)
+- **Class Imbalance:** ~16% positive class, addressed via class_weight="balanced"
+
+## Metrics
+
+### Validation Set
+- Recall (positive): 0.8571
+- Precision (positive): 0.9231
+- F1 (positive): 0.8889
+- ROC-AUC: 0.9915
+
+### Test Set
+- Recall (positive): 0.8125
+- Precision (positive): 0.8966
+- F1 (positive): 0.8525
+- ROC-AUC: 0.9899
+
+## Per-Class Performance (Test Set)
+
+| Class | Precision | Recall | F1 | Support |
+|-------|-----------|--------|-----|---------|
+| not_at_risk | 0.9721 | 0.9858 | 0.9789 | 212 |
+| at_risk | 0.8966 | 0.8125 | 0.8525 | 32 |
+
+## Risk Level Recall (Test Set)
+
+| Risk Level | Recall | Support |
+|------------|--------|---------|
+| high | 0.7778 | 27 |
+| critical | 1.0 | 5 |
+
+## Known Limitations
+
+- Trained on synthetic data only — performance on real student data is unknown.
+- Binary risk_label derived from synthetic risk_score thresholds.
+- All features are numeric; no text or contextual features used.
+- Class imbalance (~16% positive) addressed via class_weight="balanced".
+- Critical class (~2%) is very rare; recall on critical should be monitored.
+- No temporal features (trend over time) included in this baseline.
+
+## Fallback Behavior
+
+When the model is not loaded or confidence is below the threshold (0.55),
+the system falls back to rule-based risk estimation using:
+- inactive_days_last_14 > 7 → high risk
+- attendance_percentage < 60% → high risk
+- avg_mastery_score < 0.4 → medium risk
+- Otherwise → low risk

artifacts/models/risk_model/training_config.json

@@ -0,0 +1,44 @@
+{
+  "model_name": "risk_model",
+  "model_version": "risk_model_v2_baseline_001",
+  "dataset_version": "2.0.0",
+  "seed": 20260520,
+  "split_counts": {
+    "train": 1133,
+    "validation": 243,
+    "test": 244
+  },
+  "hyperparameters": {
+    "n_estimators": 100,
+    "class_weight": "balanced",
+    "random_state": 20260520,
+    "algorithm": "RandomForestClassifier"
+  },
+  "feature_columns": [
+    "avg_mastery_score",
+    "weak_lo_count",
+    "developing_lo_count",
+    "mastered_lo_count",
+    "avg_confidence",
+    "avg_accuracy",
+    "avg_marks_ratio",
+    "avg_time_seconds",
+    "hint_usage_rate",
+    "total_attempts",
+    "attendance_percentage",
+    "assignment_completion_rate",
+    "average_login_per_week",
+    "inactive_days_last_14",
+    "avg_active_minutes",
+    "total_logins",
+    "avg_video_watch_ratio",
+    "total_content_completed",
+    "total_quiz_attempts"
+  ],
+  "target_column": "risk_label",
+  "label_map": {
+    "0": "not_at_risk",
+    "1": "at_risk"
+  },
+  "algorithm": "RandomForestClassifier"
+}