@studious-lms/server 1.4.0 → 1.4.2

package/src/services/studentProgress.ts

@@ -0,0 +1,691 @@
+/**
+ * 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";
+
+type ProgressChatMessage = {
+  role: "user" | "assistant";
+  content: string;
+};
+
+type GradeSubmission = {
+  id: string;
+  gradeReceived: number | null;
+  submitted: boolean | null;
+  returned: boolean | null;
+  submittedAt: Date | null;
+  recommendationState: "NONE" | "OPEN" | "ASSIGNED" | "DISMISSED";
+  targetedAssignmentId: string | null;
+  assignment: {
+    id: string;
+    title: string;
+    dueDate: Date;
+    maxGrade: number | null;
+    weight: number;
+    type: AssignmentType;
+    section: { id: string; name: string } | null;
+  };
+};
+
+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) {
+    return null;
+  }
+
+  return (
+    Math.round(
+      (submission.gradeReceived / submission.assignment.maxGrade) * 1000,
+    ) / 10
+  );
+}
+
+function calculateTrend(submissions: GradeSubmission[]) {
+  const graded = submissions
+    .filter(
+      (submission) =>
+        submission.gradeReceived != null && submission.assignment.maxGrade,
+    )
+    .sort((a, b) => {
+      const aTime = a.submittedAt?.getTime() ?? a.assignment.dueDate.getTime();
+      const bTime = b.submittedAt?.getTime() ?? b.assignment.dueDate.getTime();
+      return aTime - bTime;
+    })
+    .map((submission) => calculatePercentage(submission))
+    .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;
+}
+
+function getOverallGrade(submissions: GradeSubmission[]) {
+  let totalWeighted = 0;
+  let totalWeight = 0;
+
+  for (const submission of submissions) {
+    if (
+      submission.gradeReceived != null &&
+      submission.assignment.maxGrade &&
+      submission.assignment.weight
+    ) {
+      totalWeighted +=
+        (submission.gradeReceived / submission.assignment.maxGrade) *
+        submission.assignment.weight;
+      totalWeight += submission.assignment.weight;
+    }
+  }
+
+  return totalWeight > 0
+    ? Math.round((totalWeighted / totalWeight) * 1000) / 10
+    : 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,
+  studentId: string,
+) {
+  const isTeacher = await isTeacherInClass(classId, viewerId);
+  if (viewerId !== studentId && !isTeacher) {
+    throw new TRPCError({
+      code: "UNAUTHORIZED",
+      message: "You can only view your own progress",
+    });
+  }
+
+  const [classData, student, submissions] = await Promise.all([
+    prisma.class.findUnique({
+      where: { id: classId },
+      select: { id: true, name: true, subject: true },
+    }),
+    prisma.user.findFirst({
+      where: {
+        id: studentId,
+        studentIn: { some: { id: classId } },
+      },
+      select: {
+        id: true,
+        username: true,
+        profile: { select: { displayName: true } },
+      },
+    }),
+    prisma.submission.findMany({
+      where: {
+        studentId,
+        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" });
+  }
+
+  if (!student) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Student not found in this class",
+    });
+  }
+
+  return { classData, student, submissions };
+}
+
+export async function getStudentProgressRecommendations(
+  viewerId: string,
+  classId: string,
+  studentId: string,
+) {
+  const { student, submissions } = await loadStudentProgressContext(
+    viewerId,
+    classId,
+    studentId,
+  );
+
+  const summary = await summarizeStudentRecommendationsWithCases(student, submissions);
+  const { recommendationCandidates: _recommendationCandidates, ...summaryResponse } =
+    summary;
+  return {
+    student: summaryResponse.student,
+    summary: summaryResponse.summary,
+    recommendations: summaryResponse.recommendations,
+    nextSteps: summaryResponse.nextSteps,
+  };
+}
+
+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 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 {
+    class: {
+      id: classData.id,
+      name: classData.name,
+      subject: classData.subject,
+    },
+    summary: {
+      studentsWithConcerns,
+      totalRecommendations,
+      totalMissingAssignments,
+      totalLowScoreAssignments,
+    },
+    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,
+    type: submission.assignment.type,
+    dueDate: submission.assignment.dueDate.toISOString(),
+    submitted: Boolean(submission.submitted),
+    returned: Boolean(submission.returned),
+    gradeReceived: submission.gradeReceived,
+    maxGrade: submission.assignment.maxGrade,
+    percentage: calculatePercentage(submission),
+    section: submission.assignment.section?.name ?? null,
+  }));
+}
+
+export async function chatAboutStudentProgress(
+  viewerId: string,
+  input: {
+    classId: string;
+    studentId: string;
+    message: string;
+    history?: ProgressChatMessage[];
+  },
+) {
+  const { classData, student, submissions } = await loadStudentProgressContext(
+    viewerId,
+    input.classId,
+    input.studentId,
+  );
+
+  const displayName = student.profile?.displayName ?? student.username;
+  const summary = {
+    overallGrade: getOverallGrade(submissions),
+    trend: calculateTrend(submissions),
+    assignments: buildProgressSummary(submissions),
+  };
+
+  const messages = [
+    {
+      role: "system" as const,
+      content:
+        "You are an educational progress assistant for teachers and students. Use only the provided class and grade context. Be concise, specific, supportive, and avoid fabricating grades or assignments.",
+    },
+    {
+      role: "user" as const,
+      content: JSON.stringify({
+        class: classData,
+        student: { id: student.id, username: student.username, displayName },
+        progress: summary,
+      }),
+    },
+    ...(input.history ?? []).slice(-8).map((message) => ({
+      role: message.role,
+      content: message.content,
+    })),
+    { role: "user" as const, content: input.message },
+  ];
+
+  try {
+    const response = await inference<string>(messages);
+    if (typeof response !== "string" || response.trim().length === 0) {
+      throw new Error("Student progress chat returned an empty response");
+    }
+    return { message: response, isFallback: false };
+  } catch (error) {
+    logger.error("Failed to generate student progress chat response", {
+      error,
+      classId: input.classId,
+      studentId: input.studentId,
+    });
+
+    const overall =
+      summary.overallGrade == null
+        ? "not enough graded work"
+        : `${summary.overallGrade}%`;
+    const missingItems = summary.assignments.filter(
+      (assignment) =>
+        !assignment.submitted &&
+        new Date(assignment.dueDate).getTime() < Date.now(),
+    ).length;
+    const lowScores = summary.assignments.filter(
+      (assignment) =>
+        assignment.percentage != null && assignment.percentage < 70,
+    ).length;
+    const awaitingFeedback = summary.assignments.filter(
+      (assignment) =>
+        assignment.submitted &&
+        assignment.gradeReceived == null &&
+        !assignment.returned,
+    ).length;
+
+    const fallbackParts = [
+      `${displayName}'s current overall grade is ${overall}.`,
+      missingItems > 0
+        ? `${missingItems} assignment${missingItems === 1 ? "" : "s"} ${missingItems === 1 ? "appears" : "appear"} overdue.`
+        : null,
+      lowScores > 0
+        ? `${lowScores} graded assignment${lowScores === 1 ? " is" : "s are"} below 70%.`
+        : null,
+      awaitingFeedback > 0
+        ? `${awaitingFeedback} assignment${awaitingFeedback === 1 ? " is" : "s are"} still awaiting feedback.`
+        : null,
+      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: fallbackParts.join(" "),
+      isFallback: true,
+    };
+  }
+}