@studious-lms/server 1.3.0 → 1.4.1

package/src/services/studentProgress.ts

@@ -0,0 +1,390 @@
+/**
+ * Student progress service - assignment recommendations and progress chat.
+ */
+import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.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";
+  content: string;
+};
+
+type GradeSubmission = {
+  id: string;
+  gradeReceived: number | null;
+  submitted: boolean | null;
+  returned: boolean | null;
+  submittedAt: Date | null;
+  assignment: {
+    id: string;
+    title: string;
+    dueDate: Date;
+    maxGrade: number | null;
+    weight: number;
+    type: AssignmentType;
+    section: { id: string; name: string } | null;
+  };
+};
+
+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;
+}
+
+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 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 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: student.profile?.displayName ?? student.username,
+    },
+    summary: {
+      overallGrade,
+      trend,
+      completedAssignments: submissions.filter((submission) =>
+        Boolean(submission.submitted),
+      ).length,
+      totalAssignments: submissions.length,
+      missingCount,
+      lowScoreCount,
+    },
+    recommendations: recommendationCandidates.map(
+      ({ priorityScore, ...candidate }) => candidate,
+    ),
+    nextSteps,
+  };
+}
+
+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 trendLabel =
+      summary.overallGrade == null
+        ? "not enough graded work to determine a recent trend"
+        : summary.trend > 5
+        ? "improving"
+        : summary.trend < -5
+          ? "declining"
+          : "stable";
+    const advice = [
+      missingItems > 0
+        ? `Review ${missingItems} missing assignment${missingItems === 1 ? "" : "s"}.`
+        : null,
+      lowScores > 0
+        ? `Use targeted practice for ${lowScores} low-scoring assignment${lowScores === 1 ? "" : "s"}.`
+        : 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."
+        : null,
+    ].filter((item): item is string => Boolean(item));
+    return {
+      message: `${displayName}'s current overall progress is ${overall}, with ${trendLabel}. ${advice.join(" ")}`,
+      isFallback: true,
+    };
+  }
+}

package/tests/lib/aiLabChatContract.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "vitest";
+import { labChatArrayFieldInstructions, labChatResponseFormat, labChatResponseSchema } from "../../src/pipelines/aiLabChatContract.js";
+
+describe("aiLabChat contract", () => {
+  test("defaults worksheet and section collections to empty arrays", () => {
+    const parsed = labChatResponseSchema.parse({
+      text: "Summary",
+      docs: null,
+      assignmentsToCreate: null,
+    });
+
+    expect(parsed.worksheetsToCreate).toEqual([]);
+    expect(parsed.sectionsToCreate).toEqual([]);
+  });
+
+  test("rejects null worksheet and section collections", () => {
+    expect(() => labChatResponseSchema.parse({
+      text: "Summary",
+      docs: null,
+      worksheetsToCreate: null,
+      sectionsToCreate: null,
+      assignmentsToCreate: null,
+    })).toThrow();
+  });
+
+  test("prompt instructions require arrays for worksheet and section fields", () => {
+    expect(labChatResponseFormat).toContain(`"worksheetsToCreate": array`);
+    expect(labChatResponseFormat).toContain(`"sectionsToCreate": array`);
+    expect(labChatArrayFieldInstructions).toContain(`Use [] when there are no worksheets to create.`);
+    expect(labChatArrayFieldInstructions).toContain(`Use [] when there are no sections to create.`);
+  });
+});

package/tests/pipelines/aiLabChat.test.ts

@@ -0,0 +1,95 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const prismaMock = {
+  labChat: {
+    findUnique: vi.fn(),
+  },
+  message: {
+    update: vi.fn(),
+  },
+};
+
+const pusherTriggerMock = vi.fn();
+const teacherChannelMock = vi.fn((classId: string) => `teacher-${classId}`);
+const loggerErrorMock = vi.fn();
+const consoleErrorMock = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+vi.mock('../../src/lib/prisma.js', () => ({
+  prisma: prismaMock,
+}));
+
+vi.mock('../../src/lib/pusher.js', () => ({
+  pusher: {
+    trigger: pusherTriggerMock,
+  },
+  teacherChannel: teacherChannelMock,
+}));
+
+vi.mock('../../src/utils/logger.js', () => ({
+  logger: {
+    error: loggerErrorMock,
+    info: vi.fn(),
+  },
+}));
+
+vi.mock('../../src/utils/aiUser.js', () => ({
+  getAIUserId: vi.fn(),
+  isAIUser: vi.fn(() => false),
+}));
+
+vi.mock('../../src/utils/inference.js', () => ({
+  inference: vi.fn(),
+  inferenceClient: {},
+  sendAIMessage: vi.fn(),
+}));
+
+vi.mock('../../src/lib/jsonConversion.js', () => ({
+  createPdf: vi.fn(),
+}));
+
+vi.mock('../../src/lib/googleCloudStorage.js', () => ({
+  bucket: {
+    file: vi.fn(),
+  },
+}));
+
+const { generateAndSendLabResponse } = await import('../../src/pipelines/aiLabChat.js');
+
+describe('generateAndSendLabResponse', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    consoleErrorMock.mockClear();
+  });
+
+  it('broadcasts lab-response-failed even if marking the message as FAILED throws', async () => {
+    const generationError = new Error('boom');
+    const statusError = new Error('message missing');
+
+    prismaMock.labChat.findUnique.mockRejectedValueOnce(generationError);
+    prismaMock.message.update.mockRejectedValueOnce(statusError);
+    pusherTriggerMock.mockResolvedValueOnce(undefined);
+
+    await expect(
+      generateAndSendLabResponse('lab-chat-1', 'teacher prompt', {
+        classId: 'class-1',
+        messageId: 'message-1',
+      }),
+    ).rejects.toThrow(generationError);
+
+    expect(prismaMock.message.update).toHaveBeenCalledWith({
+      where: { id: 'message-1' },
+      data: { status: 'FAILED' },
+    });
+    expect(teacherChannelMock).toHaveBeenCalledWith('class-1');
+    expect(pusherTriggerMock).toHaveBeenCalledWith('teacher-class-1', 'lab-response-failed', {
+      labChatId: 'lab-chat-1',
+      messageId: 'message-1',
+      error: 'AI response generation failed',
+    });
+    expect(loggerErrorMock).toHaveBeenCalledWith('Failed to set message status FAILED:', {
+      error: statusError,
+      labChatId: 'lab-chat-1',
+      messageId: 'message-1',
+    });
+  });
+});