@studious-lms/server 1.4.1 → 1.4.3

package/src/services/studentProgress.ts

@@ -2,11 +2,11 @@
  * Student progress service - assignment recommendations and progress chat.
  */
 import { TRPCError } from "@trpc/server";
+import type { AssignmentType } from "@prisma/client";
 import { prisma } from "../lib/prisma.js";
+import { isTeacherInClass } from "../models/class.js";
 import { inference } from "../utils/inference.js";
 import { logger } from "../utils/logger.js";
-import { isTeacherInClass } from "../models/class.js";
-import type { AssignmentType } from "@prisma/client";
 
 type ProgressChatMessage = {
   role: "user" | "assistant";
@@ -19,6 +19,8 @@ type GradeSubmission = {
   submitted: boolean | null;
   returned: boolean | null;
   submittedAt: Date | null;
+  recommendationState: "NONE" | "OPEN" | "ASSIGNED" | "DISMISSED";
+  targetedAssignmentId: string | null;
   assignment: {
     id: string;
     title: string;
@@ -30,9 +32,22 @@ type GradeSubmission = {
   };
 };
 
+type ProgressStudent = {
+  id: string;
+  username: string;
+  profile: { displayName: string | null } | null;
+};
+
+type RecommendationType =
+  | "missing"
+  | "low_score"
+  | "awaiting_feedback";
+
 function calculatePercentage(submission: GradeSubmission) {
-  if (submission.gradeReceived == null || !submission.assignment.maxGrade)
+  if (submission.gradeReceived == null || !submission.assignment.maxGrade) {
     return null;
+  }
+
   return (
     Math.round(
       (submission.gradeReceived / submission.assignment.maxGrade) * 1000,
@@ -55,11 +70,13 @@ function calculateTrend(submissions: GradeSubmission[]) {
     .filter((value): value is number => value != null);
 
   if (graded.length < 2) return 0;
+
   const midpoint = Math.floor(graded.length / 2);
   const first = graded.slice(0, midpoint);
   const second = graded.slice(midpoint);
   const average = (values: number[]) =>
     values.reduce((sum, value) => sum + value, 0) / values.length;
+
   return Math.round((average(second) - average(first)) * 10) / 10;
 }
 
@@ -85,6 +102,257 @@ function getOverallGrade(submissions: GradeSubmission[]) {
     : null;
 }
 
+function normalizeAssignmentType(
+  assignmentType: AssignmentType,
+): AssignmentType {
+  if (assignmentType === "TEST" || assignmentType === "QUIZ") {
+    return "HOMEWORK";
+  }
+
+  return assignmentType;
+}
+
+function buildSuggestedAssignment(
+  recommendationType: RecommendationType,
+  submission: GradeSubmission,
+  displayName: string,
+  percentage: number | null,
+) {
+  const sourceTitle = submission.assignment.title;
+  const section = submission.assignment.section?.name;
+  const titleByType: Record<RecommendationType, string> = {
+    missing: `Make-up: ${sourceTitle}`,
+    low_score: `Targeted practice: ${sourceTitle}`,
+    awaiting_feedback: `Revision follow-up: ${sourceTitle}`,
+  };
+  const leadByType: Record<RecommendationType, string> = {
+    missing: `${displayName} missed the original assignment and needs a focused make-up task on the same material.`,
+    low_score:
+      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.`,
+  };
+
+  return {
+    title: titleByType[recommendationType],
+    instructions: [
+      leadByType[recommendationType],
+      `Source assignment: ${sourceTitle}.`,
+      section ? `Section: ${section}.` : null,
+      "Keep the work concise and focused on the specific area of concern.",
+    ]
+      .filter((line): line is string => Boolean(line))
+      .join("\n\n"),
+    type: normalizeAssignmentType(submission.assignment.type),
+    maxGrade: submission.assignment.maxGrade ?? 100,
+    weight: submission.assignment.weight || 1,
+    graded: true,
+    sectionId: submission.assignment.section?.id ?? null,
+    sourceAssignmentId: submission.assignment.id,
+  };
+}
+
+function buildRecommendationCandidate(
+  submission: GradeSubmission,
+  displayName: string,
+  now: Date,
+) {
+  if (
+    submission.recommendationState === "ASSIGNED" ||
+    submission.recommendationState === "DISMISSED"
+  ) {
+    return null;
+  }
+
+  const percentage = calculatePercentage(submission);
+  const isMissing =
+    !submission.submitted &&
+    submission.assignment.dueDate.getTime() < now.getTime();
+  const isLowScore = percentage != null && percentage < 70;
+  const isUnreturned =
+    Boolean(submission.submitted) &&
+    submission.gradeReceived == null &&
+    !submission.returned;
+  const reasons: string[] = [];
+  let priorityScore = 0;
+  let recommendationType: RecommendationType | null = null;
+
+  if (isMissing) {
+    reasons.push("Missing past-due work");
+    priorityScore += 100;
+    recommendationType = "missing";
+  }
+  if (isLowScore) {
+    reasons.push(`Scored ${percentage}%`);
+    priorityScore += 85 - (percentage ?? 0);
+    recommendationType ??= "low_score";
+  }
+  if (isUnreturned) {
+    reasons.push("Awaiting grade or feedback");
+    priorityScore += 15;
+    recommendationType ??= "awaiting_feedback";
+  }
+
+  if (priorityScore <= 0 || !recommendationType) {
+    return null;
+  }
+
+  return {
+    assignmentId: submission.assignment.id,
+    submissionId: submission.id,
+    title: submission.assignment.title,
+    type: submission.assignment.type,
+    sectionId: submission.assignment.section?.id ?? null,
+    sectionName: submission.assignment.section?.name ?? null,
+    dueDate: submission.assignment.dueDate,
+    gradeReceived: submission.gradeReceived,
+    maxGrade: submission.assignment.maxGrade,
+    percentage,
+    submitted: Boolean(submission.submitted),
+    returned: Boolean(submission.returned),
+    recommendationType,
+    reasons,
+    priorityScore,
+    suggestedAssignment: buildSuggestedAssignment(
+      recommendationType,
+      submission,
+      displayName,
+      percentage,
+    ),
+  };
+}
+
+function summarizeStudentRecommendations(
+  student: ProgressStudent,
+  submissions: GradeSubmission[],
+) {
+  const now = new Date();
+  const displayName = student.profile?.displayName ?? student.username;
+  const recommendationCandidates = submissions
+    .map((submission) =>
+      buildRecommendationCandidate(submission, displayName, now),
+    )
+    .filter(
+      (
+        candidate,
+      ): candidate is NonNullable<
+        ReturnType<typeof buildRecommendationCandidate>
+      > => candidate != null,
+    )
+    .sort((a, b) => b.priorityScore - a.priorityScore);
+
+  const recommendations = recommendationCandidates
+    .slice(0, 5)
+    .map(({ priorityScore, ...candidate }) => candidate);
+
+  const gradedPercentages = submissions
+    .map(calculatePercentage)
+    .filter((value): value is number => value != null);
+  const lowScoreCount = gradedPercentages.filter(
+    (percentage) => percentage < 70,
+  ).length;
+  const missingCount = submissions.filter(
+    (submission) =>
+      !submission.submitted &&
+      submission.assignment.dueDate.getTime() < now.getTime(),
+  ).length;
+  const trend = calculateTrend(submissions);
+  const overallGrade = getOverallGrade(submissions);
+
+  const nextSteps = [
+    missingCount > 0
+      ? `Prioritize ${missingCount} missing assignment${missingCount === 1 ? "" : "s"}.`
+      : null,
+    lowScoreCount > 0
+      ? `Review ${lowScoreCount} low-scoring assignment${lowScoreCount === 1 ? "" : "s"} before introducing new material.`
+      : null,
+    trend < -5
+      ? "Schedule a check-in because recent performance is trending down."
+      : null,
+    recommendationCandidates.length === 0
+      ? "No urgent assignment issues detected from the available grades."
+      : null,
+  ].filter((step): step is string => Boolean(step));
+
+  return {
+    student: {
+      id: student.id,
+      username: student.username,
+      displayName,
+    },
+    summary: {
+      overallGrade,
+      trend,
+      completedAssignments: submissions.filter((submission) =>
+        Boolean(submission.submitted),
+      ).length,
+      totalAssignments: submissions.length,
+      missingCount,
+      lowScoreCount,
+    },
+    recommendations,
+    recommendationCandidates,
+    nextSteps,
+    priorityScore: recommendationCandidates[0]?.priorityScore ?? 0,
+  };
+}
+
+async function syncRecommendationStates(
+  submissions: GradeSubmission[],
+  recommendationCandidates: Array<
+    NonNullable<ReturnType<typeof buildRecommendationCandidate>>
+  >,
+) {
+  const candidateSubmissionIds = new Set(
+    recommendationCandidates.map((candidate) => candidate.submissionId),
+  );
+  const updates: Promise<unknown>[] = [];
+
+  for (const submission of submissions) {
+    const shouldBeOpen = candidateSubmissionIds.has(submission.id);
+
+    if (shouldBeOpen && submission.recommendationState === "NONE") {
+      updates.push(
+        prisma.submission.update({
+          where: { id: submission.id },
+          data: {
+            recommendationState: "OPEN",
+            recommendationUpdatedAt: new Date(),
+          },
+        }),
+      );
+      continue;
+    }
+
+    if (!shouldBeOpen && submission.recommendationState === "OPEN") {
+      updates.push(
+        prisma.submission.update({
+          where: { id: submission.id },
+          data: {
+            recommendationState: "NONE",
+            recommendationUpdatedAt: new Date(),
+          },
+        }),
+      );
+    }
+  }
+
+  if (updates.length) {
+    await Promise.all(updates);
+  }
+}
+
+async function summarizeStudentRecommendationsWithCases(
+  student: ProgressStudent,
+  submissions: GradeSubmission[],
+) {
+  const summary = summarizeStudentRecommendations(student, submissions);
+  await syncRecommendationStates(submissions, summary.recommendationCandidates);
+  return summary;
+}
+
 async function loadStudentProgressContext(
   viewerId: string,
   classId: string,
@@ -161,116 +429,154 @@ export async function getStudentProgressRecommendations(
     studentId,
   );
 
-  const now = new Date();
-  const recommendationCandidates = submissions
-    .map((submission) => {
-      const percentage = calculatePercentage(submission);
-      const isMissing =
-        !submission.submitted &&
-        submission.assignment.dueDate.getTime() < now.getTime();
-      const isLowScore = percentage != null && percentage < 70;
-      const isUnreturned =
-        Boolean(submission.submitted) &&
-        submission.gradeReceived == null &&
-        !submission.returned;
-      const isUpcoming =
-        !Boolean(submission.submitted) &&
-        !submission.submittedAt &&
-        !submission.returned &&
-        submission.gradeReceived == null &&
-        submission.assignment.dueDate.getTime() >= now.getTime();
-      const reasons: string[] = [];
-      let priorityScore = 0;
-
-      if (isMissing) {
-        reasons.push("Missing past-due work");
-        priorityScore += 100;
-      }
-      if (isLowScore) {
-        reasons.push(`Scored ${percentage}%`);
-        priorityScore += 85 - (percentage ?? 0);
-      }
-      if (isUnreturned) {
-        reasons.push("Awaiting grade or feedback");
-        priorityScore += 15;
-      }
-      if (isUpcoming) {
-        reasons.push("Upcoming graded assignment");
-        priorityScore += 5;
-      }
-
-      return {
-        assignmentId: submission.assignment.id,
-        submissionId: submission.id,
-        title: submission.assignment.title,
-        type: submission.assignment.type,
-        sectionName: submission.assignment.section?.name ?? null,
-        dueDate: submission.assignment.dueDate,
-        gradeReceived: submission.gradeReceived,
-        maxGrade: submission.assignment.maxGrade,
-        percentage,
-        submitted: Boolean(submission.submitted),
-        returned: Boolean(submission.returned),
-        reasons,
-        priorityScore,
-      };
-    })
-    .filter((candidate) => candidate.priorityScore > 0)
-    .sort((a, b) => b.priorityScore - a.priorityScore)
-    .slice(0, 5);
+  const summary = await summarizeStudentRecommendationsWithCases(student, submissions);
+  const { recommendationCandidates: _recommendationCandidates, ...summaryResponse } =
+    summary;
+  return {
+    student: summaryResponse.student,
+    summary: summaryResponse.summary,
+    recommendations: summaryResponse.recommendations,
+    nextSteps: summaryResponse.nextSteps,
+  };
+}
 
-  const gradedPercentages = submissions
-    .map(calculatePercentage)
-    .filter((value): value is number => value != null);
-  const lowScoreCount = gradedPercentages.filter(
-    (percentage) => percentage < 70,
-  ).length;
-  const missingCount = submissions.filter(
-    (submission) =>
-      !submission.submitted &&
-      submission.assignment.dueDate.getTime() < now.getTime(),
-  ).length;
-  const trend = calculateTrend(submissions);
-  const overallGrade = getOverallGrade(submissions);
+export async function getClassProgressRecommendations(
+  viewerId: string,
+  classId: string,
+) {
+  const teacherInClass = await isTeacherInClass(classId, viewerId);
+  if (!teacherInClass) {
+    throw new TRPCError({
+      code: "UNAUTHORIZED",
+      message: "Only teachers can view class-wide recommendations",
+    });
+  }
 
-  const nextSteps = [
-    missingCount > 0
-      ? `Prioritize ${missingCount} missing assignment${missingCount === 1 ? "" : "s"}.`
-      : null,
-    lowScoreCount > 0
-      ? `Review ${lowScoreCount} low-scoring assignment${lowScoreCount === 1 ? "" : "s"} before introducing new material.`
-      : null,
-    trend < -5
-      ? "Schedule a check-in because recent performance is trending down."
-      : null,
-    recommendationCandidates.length === 0
-      ? "No urgent assignment issues detected from the available grades."
-      : null,
-  ].filter((step): step is string => Boolean(step));
+  const classData = await prisma.class.findUnique({
+    where: { id: classId },
+    select: {
+      id: true,
+      name: true,
+      subject: true,
+      students: {
+        select: {
+          id: true,
+          username: true,
+          profile: { select: { displayName: true } },
+          submissions: {
+            where: {
+              assignment: { classId, graded: true },
+            },
+            include: {
+              assignment: {
+                select: {
+                  id: true,
+                  title: true,
+                  dueDate: true,
+                  maxGrade: true,
+                  weight: true,
+                  type: true,
+                  section: { select: { id: true, name: true } },
+                },
+              },
+            },
+            orderBy: { assignment: { dueDate: "asc" } },
+          },
+        },
+      },
+    },
+  });
+
+  if (!classData) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Class not found" });
+  }
+
+  const students = (
+    await Promise.all(
+      classData.students.map((student) =>
+        summarizeStudentRecommendationsWithCases(student, student.submissions),
+      ),
+    )
+  )
+    .map(({ recommendationCandidates: _recommendationCandidates, ...student }) => student)
+    .filter((student) => student.recommendations.length > 0)
+    .sort((a, b) => b.priorityScore - a.priorityScore);
+
+  const totalRecommendations = students.reduce(
+    (sum, student) => sum + student.recommendations.length,
+    0,
+  );
+  const studentsWithConcerns = students.length;
+  const totalMissingAssignments = students.reduce(
+    (sum, student) => sum + student.summary.missingCount,
+    0,
+  );
+  const totalLowScoreAssignments = students.reduce(
+    (sum, student) => sum + student.summary.lowScoreCount,
+    0,
+  );
 
   return {
-    student: {
-      id: student.id,
-      username: student.username,
-      displayName: student.profile?.displayName ?? student.username,
+    class: {
+      id: classData.id,
+      name: classData.name,
+      subject: classData.subject,
     },
     summary: {
-      overallGrade,
-      trend,
-      completedAssignments: submissions.filter((submission) =>
-        Boolean(submission.submitted),
-      ).length,
-      totalAssignments: submissions.length,
-      missingCount,
-      lowScoreCount,
+      studentsWithConcerns,
+      totalRecommendations,
+      totalMissingAssignments,
+      totalLowScoreAssignments,
     },
-    recommendations: recommendationCandidates.map(
-      ({ priorityScore, ...candidate }) => candidate,
-    ),
-    nextSteps,
+    students: students.map(({ priorityScore, ...student }) => student),
   };
 }
 
+export async function dismissStudentRecommendation(
+  viewerId: string,
+  input: {
+    classId: string;
+    studentId: string;
+    submissionId: string;
+  },
+) {
+  const teacherInClass = await isTeacherInClass(input.classId, viewerId);
+  if (!teacherInClass) {
+    throw new TRPCError({
+      code: "UNAUTHORIZED",
+      message: "Only teachers can dismiss recommendations",
+    });
+  }
+
+  const submission = await prisma.submission.findFirst({
+    where: {
+      id: input.submissionId,
+      studentId: input.studentId,
+      assignment: {
+        classId: input.classId,
+      },
+    },
+    select: { id: true },
+  });
+
+  if (!submission) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Submission not found for this student in this class",
+    });
+  }
+
+  await prisma.submission.update({
+    where: { id: input.submissionId },
+    data: {
+      recommendationState: "DISMISSED",
+      recommendationUpdatedAt: new Date(),
+    },
+  });
+
+  return { success: true };
+}
+
 function buildProgressSummary(submissions: GradeSubmission[]) {
   return submissions.map((submission) => ({
     title: submission.assignment.title,
@@ -329,7 +635,10 @@ export async function chatAboutStudentProgress(
   ];
 
   try {
-    const response = await inference<string>(messages);
+    const response = await inference<string>(messages, undefined, {
+      reason: "student_progress_chat",
+      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");
     }
@@ -360,30 +669,25 @@ export async function chatAboutStudentProgress(
         assignment.gradeReceived == null &&
         !assignment.returned,
     ).length;
-    const trendLabel =
-      summary.overallGrade == null
-        ? "not enough graded work to determine a recent trend"
-        : summary.trend > 5
-        ? "improving"
-        : summary.trend < -5
-          ? "declining"
-          : "stable";
-    const advice = [
+
+    const fallbackParts = [
+      `${displayName}'s current overall grade is ${overall}.`,
       missingItems > 0
-        ? `Review ${missingItems} missing assignment${missingItems === 1 ? "" : "s"}.`
+        ? `${missingItems} assignment${missingItems === 1 ? "" : "s"} ${missingItems === 1 ? "appears" : "appear"} overdue.`
         : null,
       lowScores > 0
-        ? `Use targeted practice for ${lowScores} low-scoring assignment${lowScores === 1 ? "" : "s"}.`
+        ? `${lowScores} graded assignment${lowScores === 1 ? " is" : "s are"} below 70%.`
         : null,
       awaitingFeedback > 0
-        ? `Check back after feedback is returned for ${awaitingFeedback} submitted assignment${awaitingFeedback === 1 ? "" : "s"}.`
-        : null,
-      missingItems === 0 && lowScores === 0 && awaitingFeedback === 0
-        ? "Check upcoming work and ask for feedback as new grades are returned."
+        ? `${awaitingFeedback} assignment${awaitingFeedback === 1 ? " is" : "s are"} still awaiting feedback.`
         : null,
-    ].filter((item): item is string => Boolean(item));
+      summary.trend < -5
+        ? "Recent performance is trending down, so a check-in would be reasonable."
+        : "Performance looks relatively steady from the available data.",
+    ].filter((part): part is string => Boolean(part));
+
     return {
-      message: `${displayName}'s current overall progress is ${overall}, with ${trendLabel}. ${advice.join(" ")}`,
+      message: fallbackParts.join(" "),
       isFallback: true,
     };
   }