feat: add per-student SHAP explainability and fine-tuning feasibility report

Add SHAP TreeExplainer integration to the ML pipeline (Step 10b) that
computes per-student feature attributions for retention, gateway math,
gateway English, and low GPA models. SHAP values are stored as a JSON
column alongside predictions, surfaced through the student detail API,
and consumed by the LLM enrichment path for grounded explanations.

- compute_shap_explanations() handles both XGBoost and RandomForest
- enrich_with_llm() now accepts SHAP data for attribution-aware prompts
- Student API returns parsed shap_explanations to frontend
- Add shap>=0.44.0 dependency
- Add model-client.ts Ollama/OpenAI dual-backend adapter
- Add fine-tuning feasibility report with explainability analysis

Author: William-Hill

ai_model/complete_ml_pipeline.py

@@ -1046,6 +1046,119 @@ 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)
+
+import shap
+import json as _json
+
+def compute_shap_explanations(model, X_data, feature_names, model_label, 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 plus the full
+    SHAP vector for downstream use by the fine-tuned explainer.
+    """
+    explainer = shap.TreeExplainer(model)
+    shap_values = explainer.shap_values(X_data)
+
+    # Binary classifiers: shap_values may be a list [class_0, class_1] (RandomForest),
+    # a 3D array (samples, features, classes), or a 2D array (XGBoost default).
+    if isinstance(shap_values, list):
+        sv = shap_values[1]
+    elif shap_values.ndim == 3:
+        sv = shap_values[:, :, 1]
+    else:
+        sv = shap_values
+
+    # Base value — expected model output before any feature contributions
+    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)
+
+    explanations = []
+    for i in range(len(X_data)):
+        row_shap = sv[i]
+        row_values = X_data.iloc[i] if hasattr(X_data, 'iloc') else X_data[i]
+
+        # Build (feature_name, shap_value, feature_value) tuples
+        feature_contribs = []
+        for j, fname in enumerate(feature_names):
+            fval = row_values.iloc[j] if hasattr(row_values, 'iloc') else row_values[j]
+            feature_contribs.append({
+                "feature": fname,
+                "shap_value": round(float(row_shap[j]), 4),
+                "value": float(fval) if isinstance(fval, (int, float, np.integer, np.floating)) else str(fval),
+            })
+
+        sorted_pos = sorted(
+            [f for f in feature_contribs if f["shap_value"] > 0],
+            key=lambda x: x["shap_value"], reverse=True
+        )[:top_n]
+
+        sorted_neg = sorted(
+            [f for f in feature_contribs if f["shap_value"] < 0],
+            key=lambda x: x["shap_value"]
+        )[:top_n]
+
+        explanations.append({
+            "base_value": round(base_value, 4),
+            "top_positive": sorted_pos,
+            "top_negative": sorted_neg,
+            "all_contributions": feature_contribs,
+        })
+
+    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),
+}
+
+shap_results = {}
+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, label)
+    shap_results[label] = explanations
+    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']}")
+
+# Attach SHAP explanations as JSON column on the main dataframe
+# Stores only top contributors per model to keep DB size manageable
+print("\nAttaching SHAP explanations to student dataframe...")
+shap_json_col = []
+for i in range(len(df)):
+    student_shap = {}
+    for label, explanations in shap_results.items():
+        if i < len(explanations):
+            ex = explanations[i]
+            student_shap[label] = {
+                "base_value": ex["base_value"],
+                "top_positive": ex["top_positive"],
+                "top_negative": ex["top_negative"],
+            }
+    shap_json_col.append(_json.dumps(student_shap))
+
+df['shap_explanations'] = shap_json_col
+print(f"✓ SHAP explanations attached as JSON column ({len(shap_json_col):,} students)")
+
 # ============================================================================
 # STEP 11: SAVE PREDICTIONS TO STUDENT-LEVEL FILE
 # ============================================================================
@@ -1063,7 +1176,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

@@ -29,6 +29,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,
@@ -51,10 +52,21 @@ export async function GET(
     }
 
     const row = result.rows[0]
+    // Parse JSON string columns into objects for the frontend
+    let shap = null
+    if (row.shap_explanations) {
+      try {
+        shap = typeof row.shap_explanations === "string"
+          ? JSON.parse(row.shap_explanations)
+          : row.shap_explanations
+      } catch { shap = null }
+    }
+
     return NextResponse.json({
       ...row,
       risk_factors:      row.risk_factors      ? JSON.parse(row.risk_factors)      : [],
       suggested_actions: row.suggested_actions ? JSON.parse(row.suggested_actions) : [],
+      shap_explanations: shap,
     })
   } catch (error) {
     console.error("Student detail fetch error:", error)

codebenders-dashboard/lib/model-client.ts

@@ -0,0 +1,81 @@
+/**
+ * Model client adapter — routes inference to Ollama (fine-tuned) or
+ * OpenAI (fallback) based on MODEL_BACKEND env var.
+ */
+
+import { generateText } from "ai"
+import { createOpenAI } from "@ai-sdk/openai"
+
+const MODEL_BACKEND = process.env.MODEL_BACKEND || "openai"
+const SCHOOL_CODE = process.env.SCHOOL_CODE || "bishop-state"
+const OLLAMA_BASE_URL = process.env.OLLAMA_BASE_URL || "http://localhost:11434"
+const MODEL_SIZE = process.env.MODEL_SIZE || "9b"
+
+let _openai: ReturnType<typeof createOpenAI> | null = null
+
+function getOpenAI() {
+  if (!_openai) {
+    _openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY || "" })
+  }
+  return _openai
+}
+
+async function callOllama(model: string, prompt: string, maxTokens: number): Promise<string> {
+  const response = await fetch(`${OLLAMA_BASE_URL}/api/generate`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model,
+      prompt,
+      stream: false,
+      options: {
+        temperature: 0.3,
+        num_predict: maxTokens,
+      },
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Ollama error: ${response.status} ${response.statusText}`)
+  }
+
+  const data = await response.json()
+  return data.response
+}
+
+async function generate(
+  task: "explainer" | "summarizer",
+  prompt: string,
+  maxTokens: number,
+): Promise<string> {
+  if (MODEL_BACKEND === "ollama") {
+    const model = `${SCHOOL_CODE}-${task}:${MODEL_SIZE}`
+    return callOllama(model, prompt, maxTokens)
+  }
+  const result = await generateText({
+    model: getOpenAI()("gpt-4o-mini"),
+    prompt,
+    maxOutputTokens: maxTokens,
+  })
+  return result.text
+}
+
+/**
+ * Generate a course pairing explanation.
+ */
+export async function generateExplanation(
+  prompt: string,
+  maxTokens: number = 320,
+): Promise<string> {
+  return generate("explainer", prompt, maxTokens)
+}
+
+/**
+ * Generate a query result summary.
+ */
+export async function generateSummary(
+  prompt: string,
+  maxTokens: number = 200,
+): Promise<string> {
+  return generate("summarizer", prompt, maxTokens)
+}