@studious-lms/server 1.8.0 → 1.11.0

package/src/services/studentProgress.ts

@@ -3,6 +3,7 @@
  */
 import { TRPCError } from "@trpc/server";
 import type { AssignmentType } from "@prisma/client";
+import { z } from "zod";
 import { prisma } from "../lib/prisma.js";
 import { isTeacherInClass } from "../models/class.js";
 import { inference } from "../utils/inference.js";
@@ -38,10 +39,38 @@ type ProgressStudent = {
   profile: { displayName: string | null } | null;
 };
 
-type RecommendationType =
-  | "missing"
-  | "low_score"
-  | "awaiting_feedback";
+const insightItemSchema = z.object({
+  label: z.string(),
+  evidence: z.string(),
+});
+
+const studentProgressInsightsSchema = z.object({
+  summary: z.string(),
+  strengths: z.array(insightItemSchema).min(2).max(4),
+  growth: z.array(insightItemSchema).min(2).max(4),
+  talkingPoints: z.array(z.string()).min(3).max(5),
+});
+
+const studentProgressForecastSchema = z.object({
+  forecastLow: z.number().min(0).max(100),
+  forecastHigh: z.number().min(0).max(100),
+  risk: z.enum(["on_track", "watch", "at_risk"]),
+  reason: z.string(),
+});
+
+const studentProgressFocusSchema = z.object({
+  focusItems: z.array(z.string()).min(3).max(5),
+});
+
+export type StudentProgressInsights = z.infer<
+  typeof studentProgressInsightsSchema
+>;
+export type StudentProgressForecast = z.infer<
+  typeof studentProgressForecastSchema
+>;
+export type StudentProgressFocus = z.infer<typeof studentProgressFocusSchema>;
+
+type RecommendationType = "missing" | "low_score" | "awaiting_feedback";
 
 function calculatePercentage(submission: GradeSubmission) {
   if (submission.gradeReceived == null || !submission.assignment.maxGrade) {
@@ -131,8 +160,7 @@ function buildSuggestedAssignment(
       percentage != null
         ? `${displayName} scored ${percentage}% and needs targeted reinforcement on the underlying concepts.`
         : `${displayName} needs targeted reinforcement on the underlying concepts.`,
-    awaiting_feedback:
-      `${displayName} has work in progress here, so a short follow-up can keep momentum once feedback lands.`,
+    awaiting_feedback: `${displayName} has work in progress here, so a short follow-up can keep momentum once feedback lands.`,
   };
 
   return {
@@ -429,9 +457,14 @@ export async function getStudentProgressRecommendations(
     studentId,
   );
 
-  const summary = await summarizeStudentRecommendationsWithCases(student, submissions);
-  const { recommendationCandidates: _recommendationCandidates, ...summaryResponse } =
-    summary;
+  const summary = await summarizeStudentRecommendationsWithCases(
+    student,
+    submissions,
+  );
+  const {
+    recommendationCandidates: _recommendationCandidates,
+    ...summaryResponse
+  } = summary;
   return {
     student: summaryResponse.student,
     summary: summaryResponse.summary,
@@ -498,7 +531,10 @@ export async function getClassProgressRecommendations(
       ),
     )
   )
-    .map(({ recommendationCandidates: _recommendationCandidates, ...student }) => student)
+    .map(
+      ({ recommendationCandidates: _recommendationCandidates, ...student }) =>
+        student,
+    )
     .filter((student) => student.recommendations.length > 0)
     .sort((a, b) => b.priorityScore - a.priorityScore);
 
@@ -591,6 +627,152 @@ function buildProgressSummary(submissions: GradeSubmission[]) {
   }));
 }
 
+function buildStructuredProgressContext(
+  classData: { id: string; name: string; subject: string | null },
+  student: ProgressStudent,
+  submissions: GradeSubmission[],
+) {
+  const displayName = student.profile?.displayName ?? student.username;
+  const recommendationSummary = summarizeStudentRecommendations(
+    student,
+    submissions,
+  );
+
+  return {
+    class: classData,
+    student: { id: student.id, username: student.username, displayName },
+    progress: {
+      overallGrade: getOverallGrade(submissions),
+      trend: calculateTrend(submissions),
+      summary: recommendationSummary.summary,
+      assignments: buildProgressSummary(submissions),
+      recommendations: recommendationSummary.recommendations.map(
+        (recommendation) => ({
+          title: recommendation.title,
+          recommendationType: recommendation.recommendationType,
+          percentage: recommendation.percentage,
+          submitted: recommendation.submitted,
+          reasons: recommendation.reasons,
+          sectionName: recommendation.sectionName,
+        }),
+      ),
+    },
+  };
+}
+
+function buildStructuredInferenceMessages(
+  instruction: string,
+  context: ReturnType<typeof buildStructuredProgressContext>,
+) {
+  return [
+    {
+      role: "system" as const,
+      content:
+        "You are an educational progress analyst. Use only the provided class and grade context. Be specific, concise, supportive, and do not fabricate assignments, grades, or sections.",
+    },
+    {
+      role: "user" as const,
+      content: JSON.stringify(context),
+    },
+    {
+      role: "user" as const,
+      content: instruction,
+    },
+  ];
+}
+
+export async function getStudentProgressInsights(
+  viewerId: string,
+  classId: string,
+  studentId: string,
+) {
+  const { classData, student, submissions } = await loadStudentProgressContext(
+    viewerId,
+    classId,
+    studentId,
+  );
+  const context = buildStructuredProgressContext(
+    classData,
+    student,
+    submissions,
+  );
+
+  return inference<StudentProgressInsights>(
+    buildStructuredInferenceMessages(
+      [
+        "Generate an AI analytics summary for this one student's dashboard.",
+        "The summary must be 2-4 plain-prose sentences: lead with overall grade and trajectory, then call out one strength and one concern with assignment titles.",
+        "Strengths and growth items need 2-6 word labels and one-line evidence grounded in assignment titles or sections.",
+        "Talking points must be 3-5 specific teacher check-in prompts with no numbering.",
+      ].join(" "),
+      context,
+    ),
+    studentProgressInsightsSchema,
+    {
+      reason: "student_progress_insights",
+      metadata: { viewerId, classId, studentId },
+    },
+  );
+}
+
+export async function getStudentProgressForecast(
+  viewerId: string,
+  classId: string,
+  studentId: string,
+) {
+  const { classData, student, submissions } = await loadStudentProgressContext(
+    viewerId,
+    classId,
+    studentId,
+  );
+  const context = buildStructuredProgressContext(
+    classData,
+    student,
+    submissions,
+  );
+
+  return inference<StudentProgressForecast>(
+    buildStructuredInferenceMessages(
+      "Predict the student's next graded assignment percentage band and risk status. Base the forecast on trajectory, missing work, low scores, and assignment recency. Keep the reason to one sentence.",
+      context,
+    ),
+    studentProgressForecastSchema,
+    {
+      reason: "student_progress_forecast",
+      metadata: { viewerId, classId, studentId },
+    },
+  );
+}
+
+export async function getStudentProgressFocus(
+  viewerId: string,
+  classId: string,
+  studentId: string,
+) {
+  const { classData, student, submissions } = await loadStudentProgressContext(
+    viewerId,
+    classId,
+    studentId,
+  );
+  const context = buildStructuredProgressContext(
+    classData,
+    student,
+    submissions,
+  );
+
+  return inference<StudentProgressFocus>(
+    buildStructuredInferenceMessages(
+      "Generate 3-5 student-facing weekly focus items. Each item should be specific, actionable, and grounded in the student's grade pattern or assignment titles. No numbering in the strings.",
+      context,
+    ),
+    studentProgressFocusSchema,
+    {
+      reason: "student_progress_focus",
+      metadata: { viewerId, classId, studentId },
+    },
+  );
+}
+
 export async function chatAboutStudentProgress(
   viewerId: string,
   input: {
@@ -637,7 +819,11 @@ export async function chatAboutStudentProgress(
   try {
     const response = await inference<string>(messages, undefined, {
       reason: "student_progress_chat",
-      metadata: { viewerId, classId: input.classId, studentId: input.studentId },
+      metadata: {
+        viewerId,
+        classId: input.classId,
+        studentId: input.studentId,
+      },
     });
     if (typeof response !== "string" || response.trim().length === 0) {
       throw new Error("Student progress chat returned an empty response");