fix: NQL rate formatting and course_enrollments routing (#90)

- Add isRateColumn helper and formatCellValue to render 0–1 probabilities
  as percentages in table cells, chart axes, tooltips, and KPI display
- Fix KPI suffix to only append % when value is actually in 0–1 range
- Add course_enrollments table to LLM prompt with schema, routing rules,
  DFWI/pass rate SQL patterns, FERPA guardrails, and worked example
- Add SchemaEntry interface; remove as-any cast on courseColumns
- SQL patterns return 0–1 scale; display layer handles multiplication

Author: William-Hill

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

@@ -21,7 +21,17 @@ const queryPlanSchema = z.object({
 // 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 = {
+interface SchemaEntry {
+  database: string
+  mainTable: string
+  description?: string
+  columns: Record<string, string>
+  courseTable?: string
+  courseColumns?: Record<string, string>
+  ferpaExcluded?: string[]
+}
+
+const SCHEMA_INFO: Record<string, SchemaEntry> = {
   bscc: {
     database: "postgres",
     mainTable: "student_level_with_predictions",
@@ -68,6 +78,22 @@ const SCHEMA_INFO = {
       course_completion_rate: "Course completion rate (0-1)",
       passing_rate: "Course passing rate (0-1)",
     },
+    courseTable: "course_enrollments",
+    courseColumns: {
+      course_prefix:     "Course dept code ('MAT','ENG','NUR','CIS', etc.) — lowercase, no quoting",
+      course_number:     "Course number ('100','201', etc.) — lowercase, no quoting",
+      course_name:       "Full course name — lowercase, no quoting",
+      grade:             "Student grade: 'A','B','C','D','F','W','I','AU','P' — lowercase, no quoting",
+      delivery_method:   "Delivery: 'F'=face-to-face, 'O'=online, 'H'=hybrid — lowercase, no quoting",
+      instructor_status: "Instructor type: 'FT'=full-time, 'PT'=part-time — lowercase, no quoting",
+      gateway_type:      "Gateway: 'M'=math gateway, 'E'=English gateway, 'N'=not a gateway — lowercase",
+      credits_attempted: "Credits attempted (numeric)",
+      credits_earned:    "Credits earned (numeric)",
+      cohort:            "Cohort year as text — lowercase, no quoting",
+      academic_year:     "Academic year e.g. '2021-22' — lowercase, no quoting",
+      academic_term:     "Term e.g. 'FALL','SPRING','SUMMER' — lowercase, no quoting",
+    },
+    ferpaExcluded: ["Student_GUID", "student_guid"],
   },
   akron: {
     database: "University_of_Akron",
@@ -104,14 +130,21 @@ export async function POST(request: NextRequest) {
       schema: queryPlanSchema,
       prompt: `You are a SQL query generator for student success analytics using PostgreSQL.
 
-DATABASE SCHEMA:
-- Main Table: ${schemaInfo.mainTable}
-- Description: ${schemaInfo.description}
+AVAILABLE TABLES:
+
+1. ${schemaInfo.mainTable} — student-level analytics
+   USE FOR: retention rates, persistence, GPA, demographics, risk scores, credential predictions, enrollment counts
+   COLUMNS:
+${Object.entries(schemaInfo.columns).map(([col, desc]) => `   - ${col}: ${desc}`).join("\n")}
 
-KEY COLUMNS:
-${Object.entries(schemaInfo.columns).map(([col, desc]) => `- ${col}: ${desc}`).join("\n")}
+2. ${schemaInfo.courseTable ?? "course_enrollments"} — individual course enrollment records
+   USE FOR: DFW/DFWI rates by course, pass rates by course, gateway course outcomes, delivery method analysis, instructor type analysis
+   COLUMNS:
+${Object.entries(schemaInfo.courseColumns ?? {}).map(([col, desc]) => `   - ${col}: ${desc}`).join("\n")}
 
-CRITICAL SCHEMA NOTES:
+TABLE SELECTION RULE: If the question mentions "courses", "DFW", "DFWI", "withdrawal rate", "pass rate by course", "gateway course", "failing courses", "course outcomes" → use ${schemaInfo.courseTable ?? "course_enrollments"}. Otherwise use ${schemaInfo.mainTable}.
+
+CRITICAL SCHEMA NOTES (for ${schemaInfo.mainTable}):
 - 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'
@@ -122,6 +155,16 @@ CRITICAL SCHEMA NOTES:
 - Lowercase ML columns (retention_probability, at_risk_alert, etc.) do NOT need quoting.
 - Use standard PostgreSQL syntax — no backtick quoting, no cross-database references
 
+COMPUTING DFWI RATE from course_enrollments (returns 0–1, display layer multiplies by 100):
+  ROUND(COUNT(*) FILTER (WHERE grade IN ('D','F','W','I'))::numeric / NULLIF(COUNT(*), 0), 4) AS dfwi_rate
+
+COMPUTING PASS RATE from course_enrollments (returns 0–1, display layer multiplies by 100):
+  ROUND(COUNT(*) FILTER (WHERE grade NOT IN ('D','F','W','I') AND grade IS NOT NULL AND grade != '')::numeric / NULLIF(COUNT(*), 0), 4) AS pass_rate
+
+FERPA COMPLIANCE — NEVER include these in SELECT output:
+  Student_GUID, student_guid
+Do not expose individual student identifiers in query results.
+
 IMPORTANT QUERY INTERPRETATION RULES:
 
 1. METRIC SELECTION:
@@ -151,7 +194,7 @@ IMPORTANT QUERY INTERPRETATION RULES:
    - Age filters: use numeric comparisons directly (e.g., "Student_Age" >= 25)
 
 4. VISUALIZATION:
-   - Comparing groups (age, gender, race) → "bar"
+   - Comparing groups (age, gender, race, courses) → "bar"
    - Time series (cohort, term over time) → "line"
    - Single number → "kpi"
    - Percentages/shares → "pie"
@@ -166,7 +209,7 @@ Generate a query plan with:
 - filters: any filters to apply [OPTIONAL]
 - timeHint: human-readable time description [OPTIONAL]
 - vizType: appropriate visualization [REQUIRED]
-- sql: VALID executable PostgreSQL query against table "${schemaInfo.mainTable}" [REQUIRED]
+- sql: VALID executable PostgreSQL query against the appropriate table (${schemaInfo.mainTable} or course_enrollments) [REQUIRED]
 - queryString: empty string [OPTIONAL]
 
 EXAMPLE for "segment students over 25 and under 25 in 2023 cohort":
@@ -176,6 +219,13 @@ EXAMPLE for "segment students over 25 and under 25 in 2023 cohort":
   "queryString": ""
 }
 
+EXAMPLE for "top 5 courses with highest DFW rates":
+{
+  "vizType": "bar",
+  "sql": "SELECT course_prefix || ' ' || course_number AS course, MAX(course_name) AS course_name, COUNT(*) AS enrollments, ROUND(COUNT(*) FILTER (WHERE grade IN ('D','F','W','I'))::numeric / NULLIF(COUNT(*), 0), 4) AS dfwi_rate FROM course_enrollments GROUP BY course_prefix, course_number HAVING COUNT(*) >= 10 ORDER BY dfwi_rate DESC LIMIT 5",
+  "queryString": ""
+}
+
 Make sure the SQL is valid PostgreSQL and addresses exactly what the user asked for!`,
     })
 

codebenders-dashboard/components/analysis-result.tsx

@@ -37,6 +37,23 @@ const TOOLTIP_STYLE = {
   color: "var(--popover-foreground)",
 }
 
+function isRateColumn(col: string): boolean {
+  const lower = col.toLowerCase()
+  return (
+    lower.endsWith("_rate") ||
+    lower.endsWith("_probability") ||
+    lower.endsWith("_pct") ||
+    lower.endsWith("_percent") ||
+    lower.endsWith("_percentage")
+  )
+}
+
+function formatCellValue(col: string, val: unknown): string {
+  if (typeof val !== "number") return val == null ? "" : String(val)
+  if (isRateColumn(col) && val >= 0 && val <= 1) return (val * 100).toFixed(1) + "%"
+  return Number.isInteger(val) ? String(val) : val.toFixed(2)
+}
+
 export function AnalysisResult({ result, plan }: AnalysisResultProps) {
   const renderDataTable = () => {
     if (!result.data || result.data.length === 0) return null
@@ -56,7 +73,7 @@ export function AnalysisResult({ result, plan }: AnalysisResultProps) {
           {result.data.map((row, idx) => (
             <TableRow key={idx}>
               {columns.map((col) => (
-                <TableCell key={col}>{typeof row[col] === "number" ? row[col].toFixed(2) : row[col]}</TableCell>
+                <TableCell key={col}>{formatCellValue(col, row[col])}</TableCell>
               ))}
             </TableRow>
           ))}
@@ -89,10 +106,22 @@ export function AnalysisResult({ result, plan }: AnalysisResultProps) {
               <LineChart data={result.data}>
                 <CartesianGrid strokeDasharray="3 3" stroke="var(--border)" />
                 <XAxis dataKey={groupByKey} stroke="var(--muted-foreground)" />
-                <YAxis stroke="var(--muted-foreground)" />
+                <YAxis
+                  stroke="var(--muted-foreground)"
+                  // No upper-bound guard: axis ticks may slightly exceed 1.0 (chart padding),
+                  // and should still render as % to stay visually consistent with data labels.
+                  tickFormatter={(v: number) =>
+                    isRateColumn(metricKey) && v >= 0 ? `${(v * 100).toFixed(0)}%` : String(v)
+                  }
+                />
                 <Tooltip
                   wrapperStyle={{ zIndex: 10, overflow: 'visible' as const }}
                   contentStyle={TOOLTIP_STYLE}
+                  formatter={(v: number) =>
+                    isRateColumn(metricKey) && v >= 0 && v <= 1
+                      ? [`${(v * 100).toFixed(1)}%`, metricKey.replace(/_/g, " ")]
+                      : [v, metricKey.replace(/_/g, " ")]
+                  }
                 />
                 <Legend />
                 <Line
@@ -115,11 +144,23 @@ export function AnalysisResult({ result, plan }: AnalysisResultProps) {
               <BarChart data={result.data}>
                 <CartesianGrid strokeDasharray="3 3" stroke="var(--border)" />
                 <XAxis dataKey={groupByKey} stroke="var(--muted-foreground)" />
-                <YAxis stroke="var(--muted-foreground)" />
+                <YAxis
+                  stroke="var(--muted-foreground)"
+                  // No upper-bound guard: axis ticks may slightly exceed 1.0 (chart padding),
+                  // and should still render as % to stay visually consistent with data labels.
+                  tickFormatter={(v: number) =>
+                    isRateColumn(metricKey) && v >= 0 ? `${(v * 100).toFixed(0)}%` : String(v)
+                  }
+                />
                 <Tooltip
                   cursor={false}
                   wrapperStyle={{ zIndex: 10, overflow: 'visible' as const }}
                   contentStyle={TOOLTIP_STYLE}
+                  formatter={(v: number) =>
+                    isRateColumn(metricKey) && v >= 0 && v <= 1
+                      ? [`${(v * 100).toFixed(1)}%`, metricKey.replace(/_/g, " ")]
+                      : [v, metricKey.replace(/_/g, " ")]
+                  }
                 />
                 <Legend />
                 <Bar
@@ -155,6 +196,11 @@ export function AnalysisResult({ result, plan }: AnalysisResultProps) {
                 <Tooltip
                   wrapperStyle={{ zIndex: 10, overflow: 'visible' as const }}
                   contentStyle={TOOLTIP_STYLE}
+                  formatter={(v: number) =>
+                    isRateColumn(metricKey) && v >= 0 && v <= 1
+                      ? [`${(v * 100).toFixed(1)}%`, metricKey.replace(/_/g, " ")]
+                      : [v, metricKey.replace(/_/g, " ")]
+                  }
                 />
                 <Legend
                   verticalAlign="bottom"
@@ -166,19 +212,30 @@ export function AnalysisResult({ result, plan }: AnalysisResultProps) {
           </div>
         )
 
-      case "kpi":
-        const kpiValue = result.data[0]?.[metricKey] ?? 0
+      case "kpi": {
+        const kpiRaw = result.data[0]?.[metricKey] ?? 0
+        const isRate = isRateColumn(metricKey)
+        const shouldScale = isRate && typeof kpiRaw === "number" && kpiRaw >= 0 && kpiRaw <= 1
+        const kpiDisplay =
+          typeof kpiRaw === "number"
+            ? shouldScale
+              ? (kpiRaw * 100).toFixed(1)
+              : kpiRaw.toFixed(1)
+            : String(kpiRaw)
+        const kpiSuffix = shouldScale ? "%" : ""
         return (
           <div className="flex items-center justify-center h-48">
             <div className="text-center space-y-4">
               <div className="text-6xl font-bold text-foreground">
-                {typeof kpiValue === "number" ? kpiValue.toFixed(1) : kpiValue}
-                {metricKey.includes("rate") || metricKey.includes("percentage") ? "%" : ""}
+                {kpiDisplay}{kpiSuffix}
+              </div>
+              <div className="text-xl text-muted-foreground capitalize">
+                {metricKey.replace(/_/g, " ")}
               </div>
-              <div className="text-xl text-muted-foreground capitalize">{metricKey.replace(/_/g, " ")}</div>
             </div>
           </div>
         )
+      }
 
       case "table":
         return (