Merge branch 'feature/shap-explainability' into fine-tuning/student-explainability

Author: William-Hill

ai_model/complete_ml_pipeline.py

@@ -22,6 +22,8 @@
 )
 from sklearn.ensemble import RandomForestClassifier, RandomForestRegressor
 import xgboost as xgb
+import shap
+import json
 from datetime import datetime
 import warnings
 warnings.filterwarnings('ignore')
@@ -1046,6 +1048,98 @@ def assign_alert_level(risk_score):
 
 print(f"Low GPA predictions generated")
 
+# ============================================================================
+# STEP 10b: PER-STUDENT SHAP EXPLANATIONS
+# ============================================================================
+print("\n" + "=" * 80)
+print("STEP 10b: COMPUTING PER-STUDENT SHAP EXPLANATIONS")
+print("=" * 80)
+
+
+def compute_shap_explanations(model, X_data, feature_names, top_n=5):
+    """
+    Compute per-student SHAP values using TreeExplainer.
+
+    For binary classifiers, uses class-1 (positive outcome) SHAP values.
+    Returns top N positive/negative contributors per student.
+    """
+    explainer = shap.TreeExplainer(model)
+    shap_values = explainer.shap_values(X_data)
+
+    # Binary classifiers: RandomForest returns list [class_0, class_1],
+    # some models return 3D (samples, features, classes), XGBoost returns 2D.
+    if isinstance(shap_values, list):
+        sv = shap_values[1]
+    elif shap_values.ndim == 3:
+        sv = shap_values[:, :, 1]
+    else:
+        sv = shap_values
+
+    base = explainer.expected_value
+    if isinstance(base, (list, np.ndarray)):
+        base_value = float(base[1]) if len(base) > 1 else float(base[0])
+    else:
+        base_value = float(base)
+
+    base_rounded = round(base_value, 4)
+
+    def _make_entry(row_shap, row_values, j):
+        fval = row_values.iloc[j]
+        return {
+            "feature": feature_names[j],
+            "shap_value": round(float(row_shap[j]), 4),
+            "value": float(fval) if isinstance(fval, (int, float, np.integer, np.floating)) else str(fval),
+        }
+
+    explanations = []
+    for i in range(len(X_data)):
+        row_shap = sv[i]
+        row_values = X_data.iloc[i]
+
+        # Use argsort to find top contributors without building a full list
+        pos_indices = np.argsort(-row_shap)[:top_n]
+        pos_indices = pos_indices[row_shap[pos_indices] > 0]
+
+        neg_indices = np.argsort(row_shap)[:top_n]
+        neg_indices = neg_indices[row_shap[neg_indices] < 0]
+
+        explanations.append({
+            "base_value": base_rounded,
+            "top_positive": [_make_entry(row_shap, row_values, j) for j in pos_indices],
+            "top_negative": [_make_entry(row_shap, row_values, j) for j in neg_indices],
+        })
+
+    return explanations
+
+
+# Models to explain with SHAP (all 4 XGBoost/RF classifiers)
+shap_targets = {
+    "retention": (retention_model, X_full_retention, retention_features),
+    "gateway_math": (gateway_math_model, X_full_gateway_math, gateway_math_features),
+    "gateway_english": (gateway_english_model, X_full_gateway_english, gateway_english_features),
+    "low_gpa": (low_gpa_model, X_gpa_clean, gpa_features),
+}
+
+# Build per-student dicts in a single pass, discarding each model's list promptly
+student_shap_dicts = [{} for _ in range(len(df))]
+
+for label, (model, X_data, features) in shap_targets.items():
+    print(f"\nComputing SHAP explanations for {label} model...")
+    explanations = compute_shap_explanations(model, X_data, features)
+    for i, ex in enumerate(explanations):
+        student_shap_dicts[i][label] = ex
+    print(f"  ✓ {len(explanations)} student explanations generated")
+    if explanations:
+        ex = explanations[0]
+        print(f"  Sample (student 0): base_value={ex['base_value']}")
+        for f in ex['top_positive'][:3]:
+            print(f"    ↑ {f['feature']}: +{f['shap_value']}")
+        for f in ex['top_negative'][:3]:
+            print(f"    ↓ {f['feature']}: {f['shap_value']}")
+
+df['shap_explanations'] = [json.dumps(d) for d in student_shap_dicts]
+print(f"✓ SHAP explanations attached as JSON column ({len(df):,} students)")
+
 # ============================================================================
 # STEP 11: SAVE PREDICTIONS TO STUDENT-LEVEL FILE
 # ============================================================================
@@ -1063,7 +1157,8 @@ def assign_alert_level(risk_score):
     'prob_no_credential', 'prob_certificate', 'prob_associate', 'prob_bachelor',
     'gateway_math_probability', 'gateway_math_prediction', 'gateway_math_risk',
     'gateway_english_probability', 'gateway_english_prediction', 'gateway_english_risk',
-    'low_gpa_probability', 'low_gpa_prediction', 'academic_risk_level'
+    'low_gpa_probability', 'low_gpa_prediction', 'academic_risk_level',
+    'shap_explanations'
 ]
 
 predictions_df = df[prediction_columns].copy()

ai_model/generate_readiness_scores.py

@@ -447,13 +447,17 @@ def score_student(row) -> dict:
 # LLM Enrichment (optional)
 # ============================================================================
 
-def enrich_with_llm(record: dict, model: str) -> dict:
+def enrich_with_llm(record: dict, model: str, shap_data: dict = None) -> dict:
     """
     Replace rationale and suggested_actions with LLM-generated content.
     Only called for medium/low readiness students.
     Input is the FERPA-safe profile — no PII sent to any external service.
     Returns the record with enriched text fields (score unchanged).
 
+    When shap_data is provided (from the ML pipeline's SHAP step), the prompt
+    includes per-model feature attribution so the LLM can ground its
+    explanation in what the models actually learned.
+
     Provider is determined by the model string:
       "gpt-4o-mini"               -> OpenAI (requires OPENAI_API_KEY)
       "ollama/llama3.2:3b"        -> local Ollama (no key needed)
@@ -469,6 +473,25 @@ def enrich_with_llm(record: dict, model: str) -> dict:
     profile = json.loads(record["input_features"]) if isinstance(record["input_features"], str) else record["input_features"]
     risk_factors = json.loads(record["risk_factors"]) if isinstance(record["risk_factors"], str) else []
 
+    # Build SHAP context section if available
+    shap_section = ""
+    if shap_data:
+        shap_lines = []
+        for model_name, attrs in shap_data.items():
+            shap_lines.append(f"\n  {model_name} model (base prediction: {attrs.get('base_value', 'N/A')}):")
+            for f in attrs.get("top_positive", []):
+                shap_lines.append(f"    ↑ {f['feature']} = {f['value']} (pushes prediction UP by {f['shap_value']})")
+            for f in attrs.get("top_negative", []):
+                shap_lines.append(f"    ↓ {f['feature']} = {f['value']} (pushes prediction DOWN by {abs(f['shap_value'])})")
+        shap_section = f"""
+
+ML Model Feature Attribution (SHAP — shows which features drive each prediction):
+{''.join(shap_lines)}
+
+IMPORTANT: Use these SHAP values to ground your explanation. Tell the advisor
+which specific factors are most responsible for this student's risk level,
+citing the magnitude. Do not speculate beyond what the models show."""
+
     prompt = f"""You are an academic advisor assistant at Bishop State Community College.
 A student has a readiness score of {record['readiness_score']:.2f} ({record['readiness_level']} readiness).
 
@@ -484,10 +507,10 @@ def enrich_with_llm(record: dict, model: str) -> dict:
 - Retention probability: {profile.get('retention_probability')}
 
 Identified risk factors:
-{chr(10).join(f'- {f}' for f in risk_factors)}
+{chr(10).join(f'- {f}' for f in risk_factors)}{shap_section}
 
 Write two things:
-1. RATIONALE: A 2-sentence explanation of this student's readiness score for an advisor.
+1. RATIONALE: A 2-3 sentence explanation of this student's readiness score for an advisor. If SHAP data is available, cite the top contributing factors by name and magnitude.
 2. ACTIONS: A JSON array of 3-5 specific, actionable intervention recommendations (strings only).
 
 Format your response exactly as:
@@ -588,7 +611,15 @@ def main():
             record["generation_ms"] = elapsed_ms
             record["run_id"] = run_id
             if args.enrich_with_llm and record["readiness_level"] in ("medium", "low"):
-                record = enrich_with_llm(record, args.llm_model)
+                # Pass SHAP data if the shap_explanations column exists
+                shap_data = None
+                shap_raw = row.get("shap_explanations")
+                if shap_raw and str(shap_raw) not in ("", "nan", "None"):
+                    try:
+                        shap_data = json.loads(shap_raw) if isinstance(shap_raw, str) else shap_raw
+                    except (json.JSONDecodeError, TypeError):
+                        pass
+                record = enrich_with_llm(record, args.llm_model, shap_data=shap_data)
             records.append(record)
         except Exception as e:
             errors += 1

codebenders-dashboard/app/api/students/[guid]/route.ts

@@ -2,6 +2,15 @@ import { type NextRequest, NextResponse } from "next/server"
 import { getPool } from "@/lib/db"
 import { canAccess, type Role } from "@/lib/roles"
 
+function safeParse<T>(raw: unknown, fallback: T): T {
+  if (!raw) return fallback
+  try {
+    return typeof raw === "string" ? JSON.parse(raw) : (raw as T)
+  } catch {
+    return fallback
+  }
+}
+
 export async function GET(
   request: NextRequest,
   { params }: { params: Promise<{ guid: string }> }
@@ -29,6 +38,7 @@ export async function GET(
       ROUND((s.low_gpa_probability * 100)::numeric, 1)          AS gpa_risk_pct,
       ROUND(s.predicted_time_to_credential::numeric, 1)         AS time_to_credential,
       s.predicted_credential_label                              AS credential_type,
+      s.shap_explanations,
       ROUND((r.readiness_score * 100)::numeric, 1)             AS readiness_pct,
       r.readiness_level,
       r.rationale,
@@ -53,8 +63,9 @@ export async function GET(
     const row = result.rows[0]
     return NextResponse.json({
       ...row,
-      risk_factors:      row.risk_factors      ? JSON.parse(row.risk_factors)      : [],
-      suggested_actions: row.suggested_actions ? JSON.parse(row.suggested_actions) : [],
+      risk_factors:      safeParse(row.risk_factors, []),
+      suggested_actions: safeParse(row.suggested_actions, []),
+      shap_explanations: safeParse(row.shap_explanations, null),
     })
   } catch (error) {
     console.error("Student detail fetch error:", error)