feat: update methodology page — remove impl refs, add worked examples (#60)

* fix: quote Retention column in KPIs query and coerce pg string counts to numbers for Recharts

* fix: use exact case-sensitive column names in LLM schema prompt to prevent Postgres quoting errors

* feat: update methodology page — remove impl refs, add worked examples

- Remove Script and Table header badges (internal details)
- Remove 'Data Source' section (table names, script paths not user-facing)
- Replace raw db field names in sub-score tables with plain English labels
- Remove input_features column reference from Transparency card
- Add 'Worked Examples' section with Maria T. (High, 0.699) and Jordan M. (Low, 0.386)
- Each example: inputs table, step-by-step sub-score math, color-coded final score

Closes #59

Author: William-Hill

codebenders-dashboard/app/api/analyze/route.ts

@@ -18,50 +18,55 @@ const queryPlanSchema = z.object({
 })
 
 // Database schema configuration
+// IMPORTANT: Column names listed here are the EXACT case-sensitive names in PostgreSQL.
+// Mixed-case columns (e.g. "Cohort", "Retention") must be double-quoted in generated SQL.
+// All-lowercase columns (e.g. retention_probability) do not require quoting.
 const SCHEMA_INFO = {
   bscc: {
     database: "postgres",
     mainTable: "student_level_with_predictions",
     description: "Bishop State Community College student cohort data with retention, persistence, and completion metrics",
     columns: {
-      // Key dimensions
-      cohort: "Cohort year (numeric: 2019, 2020, etc.)",
-      cohort_term: "Term of cohort entry (Fall, Spring, Summer)",
-      student_guid: "Unique student identifier",
-      institution_id: "Institution identifier (102030 for Bishop State)",
-
-      // Demographics
-      gender: "Student gender",
-      race: "Student race/ethnicity",
-      student_age: "Age of student",
-      first_gen: "First generation status",
-
-      // Academic info
-      enrollment_type: "Type of enrollment",
-      enrollment_intensity_first_term: "Enrollment intensity in first term (Full-Time, Part-Time)",
-      program_of_study_year_1: "Program of study in year 1 (CIP code)",
-      credential_type_sought_year_1: "Credential type being pursued",
-
-      // Performance metrics
-      retention: "Retention indicator (0 or 1)",
-      persistence: "Persistence indicator (0 or 1)",
-      gpa_group_year_1: "GPA in year 1",
-      gpa_group_term_1: "GPA in term 1",
-
-      // Credits
-      number_of_credits_attempted_year_1: "Credits attempted in year 1",
-      number_of_credits_earned_year_1: "Credits earned in year 1",
-      number_of_credits_attempted_year_2: "Credits attempted in year 2",
-      number_of_credits_earned_year_2: "Credits earned in year 2",
-
-      // Completion metrics
-      time_to_credential: "Time to any credential",
-
-      // ML predictions
+      // Key dimensions — MIXED CASE: must be double-quoted in SQL
+      Cohort: "Cohort year (numeric: 2019, 2020, etc.) — write as \"Cohort\"",
+      Cohort_Term: "Term of cohort entry (Fall, Spring, Summer) — write as \"Cohort_Term\"",
+      Student_GUID: "Unique student identifier — write as \"Student_GUID\"",
+      Institution_ID: "Institution identifier (102030 for Bishop State) — write as \"Institution_ID\"",
+
+      // Demographics — MIXED CASE: must be double-quoted in SQL
+      Gender: "Student gender — write as \"Gender\"",
+      Race: "Student race/ethnicity — write as \"Race\"",
+      Student_Age: "Age of student (integer) — write as \"Student_Age\"",
+      First_Gen: "First generation status — write as \"First_Gen\"",
+
+      // Academic info — MIXED CASE: must be double-quoted in SQL
+      Enrollment_Type: "Type of enrollment — write as \"Enrollment_Type\"",
+      Enrollment_Intensity_First_Term: "Enrollment intensity in first term (Full-Time, Part-Time) — write as \"Enrollment_Intensity_First_Term\"",
+      Program_of_Study_Year_1: "Program of study in year 1 (CIP code) — write as \"Program_of_Study_Year_1\"",
+      Credential_Type_Sought_Year_1: "Credential type being pursued — write as \"Credential_Type_Sought_Year_1\"",
+      Math_Placement: "Math placement level (C=college-level, R=remedial, N=none) — write as \"Math_Placement\"",
+
+      // Performance metrics — MIXED CASE: must be double-quoted in SQL
+      Retention: "Retention indicator (0 or 1) — write as \"Retention\"",
+      Persistence: "Persistence indicator (0 or 1) — write as \"Persistence\"",
+      GPA_Group_Year_1: "GPA in year 1 — write as \"GPA_Group_Year_1\"",
+      GPA_Group_Term_1: "GPA in term 1 — write as \"GPA_Group_Term_1\"",
+
+      // Credits — MIXED CASE: must be double-quoted in SQL
+      Number_of_Credits_Attempted_Year_1: "Credits attempted in year 1 — write as \"Number_of_Credits_Attempted_Year_1\"",
+      Number_of_Credits_Earned_Year_1: "Credits earned in year 1 — write as \"Number_of_Credits_Earned_Year_1\"",
+      Number_of_Credits_Attempted_Year_2: "Credits attempted in year 2 — write as \"Number_of_Credits_Attempted_Year_2\"",
+      Number_of_Credits_Earned_Year_2: "Credits earned in year 2 — write as \"Number_of_Credits_Earned_Year_2\"",
+
+      // Completion metrics — MIXED CASE: must be double-quoted in SQL
+      Time_to_Credential: "Time to any credential — write as \"Time_to_Credential\"",
+
+      // ML predictions — all lowercase: no quoting needed
       retention_probability: "Predicted probability of retention (0-1)",
       retention_risk_category: "Risk category (Low Risk, Moderate Risk, High Risk, Critical Risk)",
       at_risk_alert: "Early warning alert level (LOW, MODERATE, HIGH, URGENT)",
-      predicted_gpa: "ML-predicted GPA",
+      course_completion_rate: "Course completion rate (0-1)",
+      passing_rate: "Course passing rate (0-1)",
     },
   },
   akron: {
@@ -107,39 +112,43 @@ KEY COLUMNS:
 ${Object.entries(schemaInfo.columns).map(([col, desc]) => `- ${col}: ${desc}`).join("\n")}
 
 CRITICAL SCHEMA NOTES:
-- cohort: NUMERIC year only (e.g., 2019, 2020) — NOT a string like "2024-Fall"
-- cohort_term: Term name (e.g., "Fall", "Spring", "Summer")
-- To filter by "Fall 2023", use: WHERE cohort = 2023 AND cohort_term = 'Fall'
-- student_age: INTEGER field — use direct numeric comparisons (e.g., student_age >= 25)
+- Column names with uppercase letters MUST be double-quoted in PostgreSQL SQL or the query will fail.
+  CORRECT:   WHERE "Cohort" = 2023 AND "Cohort_Term" = 'Fall'
+  INCORRECT: WHERE cohort = 2023 AND cohort_term = 'Fall'
+- "Cohort": NUMERIC year only (e.g., 2019, 2020) — NOT a string like "2024-Fall"
+- "Cohort_Term": Term name (e.g., "Fall", "Spring", "Summer")
+- To filter by "Fall 2023", use: WHERE "Cohort" = 2023 AND "Cohort_Term" = 'Fall'
+- "Student_Age": INTEGER field — use direct numeric comparisons (e.g., "Student_Age" >= 25)
+- Lowercase ML columns (retention_probability, at_risk_alert, etc.) do NOT need quoting.
 - Use standard PostgreSQL syntax — no backtick quoting, no cross-database references
 
 IMPORTANT QUERY INTERPRETATION RULES:
 
 1. METRIC SELECTION:
    - ONLY include a metric if the user explicitly asks for retention, persistence, GPA, credits, etc.
    - If user asks to "segment", "compare", "show", "count", or "list" students → use COUNT(*) and NO specific metric
-   - "retention" → AVG(retention) as retention_rate
-   - "persistence" or "completion" → AVG(persistence) as completion_rate
-   - "GPA" → AVG(gpa_group_year_1) as gpa
-   - "credits" → AVG(number_of_credits_earned_year_1) as credits_earned
+   - "retention" → AVG("Retention") as retention_rate
+   - "persistence" or "completion" → AVG("Persistence") as completion_rate
+   - "GPA" → AVG("GPA_Group_Year_1") as gpa
+   - "credits" → AVG("Number_of_Credits_Earned_Year_1") as credits_earned
    - Otherwise → COUNT(*) as count
 
 2. GROUPING & SEGMENTATION:
    - "segment by X" or "compare X" → GROUP BY X column
    - "by age", "age groups", "segment by age" → Use CASE statement to create age groups:
      CASE
-       WHEN student_age < 25 THEN 'Under 25'
-       WHEN student_age >= 25 THEN '25 and Over'
+       WHEN "Student_Age" < 25 THEN 'Under 25'
+       WHEN "Student_Age" >= 25 THEN '25 and Over'
      END AS age_group
-   - "by gender" → GROUP BY gender
-   - "by race" → GROUP BY race
-   - "by cohort" → GROUP BY cohort
-   - "by term" → GROUP BY cohort_term
+   - "by gender" → GROUP BY "Gender"
+   - "by race" → GROUP BY "Race"
+   - "by cohort" → GROUP BY "Cohort"
+   - "by term" → GROUP BY "Cohort_Term"
 
 3. FILTERS:
-   - "2023 cohort" → WHERE cohort = 2023
-   - "Fall 2023" or "2023 Fall" → WHERE cohort = 2023 AND cohort_term = 'Fall'
-   - Age filters: use numeric comparisons directly (e.g., student_age >= 25)
+   - "2023 cohort" → WHERE "Cohort" = 2023
+   - "Fall 2023" or "2023 Fall" → WHERE "Cohort" = 2023 AND "Cohort_Term" = 'Fall'
+   - Age filters: use numeric comparisons directly (e.g., "Student_Age" >= 25)
 
 4. VISUALIZATION:
    - Comparing groups (age, gender, race) → "bar"
@@ -163,7 +172,7 @@ Generate a query plan with:
 EXAMPLE for "segment students over 25 and under 25 in 2023 cohort":
 {
   "vizType": "bar",
-  "sql": "SELECT CASE WHEN student_age < 25 THEN 'Under 25' ELSE '25 and Over' END AS age_group, COUNT(*) as count FROM student_level_with_predictions WHERE cohort = 2023 GROUP BY age_group ORDER BY age_group",
+  "sql": "SELECT CASE WHEN \"Student_Age\" < 25 THEN 'Under 25' ELSE '25 and Over' END AS age_group, COUNT(*) as count FROM student_level_with_predictions WHERE \"Cohort\" = 2023 GROUP BY age_group ORDER BY age_group",
   "queryString": ""
 }
 

codebenders-dashboard/app/api/dashboard/kpis/route.ts

@@ -7,7 +7,7 @@ export async function GET(request: NextRequest) {
 
     const sql = `
       SELECT
-        AVG(retention) * 100 as overall_retention_rate,
+        AVG("Retention") * 100 as overall_retention_rate,
         AVG(retention_probability) * 100 as avg_predicted_retention,
         SUM(CASE WHEN at_risk_alert IN ('HIGH', 'URGENT') THEN 1 ELSE 0 END) as high_critical_risk_count,
         AVG(course_completion_rate) * 100 as avg_course_completion_rate,