@studious-lms/server 1.4.1 → 1.4.3

package/tests/utils/inference.test.ts

@@ -0,0 +1,218 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { z } from 'zod';
+
+const {
+  chatCreateMock,
+  responseParseMock,
+  modelsListMock,
+  prismaMocks,
+  logger,
+} = vi.hoisted(() => ({
+  chatCreateMock: vi.fn(),
+  responseParseMock: vi.fn(),
+  modelsListMock: vi.fn(),
+  prismaMocks: {
+    aiUsageLog: {
+      create: vi.fn(),
+    },
+    message: {
+      create: vi.fn(),
+    },
+  },
+  logger: {
+    info: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+vi.mock('openai', () => ({
+  default: class OpenAI {
+    chat = {
+      completions: {
+        create: chatCreateMock,
+      },
+    };
+
+    responses = {
+      parse: responseParseMock,
+    };
+
+    models = {
+      list: modelsListMock,
+    };
+  },
+}));
+
+vi.mock('openai/helpers/zod', () => ({
+  zodTextFormat: vi.fn((schema, name) => ({ schema, name })),
+}));
+
+vi.mock('../../src/lib/prisma.js', () => ({
+  prisma: prismaMocks,
+}));
+
+vi.mock('../../src/utils/logger.js', () => ({
+  logger,
+}));
+
+vi.mock('../../src/lib/pusher.js', () => ({
+  chatChannel: vi.fn(),
+  pusher: {
+    trigger: vi.fn(),
+  },
+}));
+
+vi.mock('../../src/utils/aiUser.js', () => ({
+  ensureAIUserExists: vi.fn(),
+  getAIUserId: vi.fn(() => 'AI_ASSISTANT'),
+}));
+
+vi.mock('../../src/lib/config/env.js', () => ({
+  env: {
+    INFERENCE_API_KEY: 'test-key',
+    INFERENCE_API_BASE_URL: 'http://localhost:11434/v1',
+    OPENAI_API_KEY: 'test-openai-key',
+  },
+}));
+
+import { estimateTokenCount, inference } from '../../src/utils/inference.js';
+
+describe('inference', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    prismaMocks.aiUsageLog.create.mockResolvedValue({ id: 'log-1' });
+  });
+
+  test('logs chat completion usage with the provided reason', async () => {
+    chatCreateMock.mockResolvedValue({
+      choices: [{ message: { content: 'Hello back' } }],
+      usage: {
+        prompt_tokens: 12,
+        completion_tokens: 8,
+        total_tokens: 20,
+      },
+    });
+
+    const result = await inference<string>('Hello there', undefined, {
+      reason: 'student_progress_chat',
+      metadata: { classId: 'class-1', studentId: 'student-1' },
+    });
+
+    expect(result).toBe('Hello back');
+    expect(prismaMocks.aiUsageLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        reason: 'student_progress_chat',
+        operation: 'chat.completions',
+        success: true,
+        promptTokens: 12,
+        completionTokens: 8,
+        totalTokens: 20,
+        estimatedInputTokens: estimateTokenCount('Hello there'),
+        metadata: { classId: 'class-1', studentId: 'student-1' },
+      }),
+    });
+    expect(logger.info).toHaveBeenCalledWith(
+      'AI usage logged',
+      expect.objectContaining({
+        reason: 'student_progress_chat',
+        totalTokens: 20,
+      }),
+    );
+    expect(chatCreateMock).toHaveBeenCalledWith({
+      model: 'gpt-5-nano',
+      messages: [{ role: 'user', content: 'Hello there' }],
+    });
+  });
+
+  test('passes optional chat completion settings through the helper', async () => {
+    chatCreateMock.mockResolvedValue({
+      choices: [{ message: { content: 'Configured response' } }],
+      usage: {
+        prompt_tokens: 10,
+        completion_tokens: 5,
+        total_tokens: 15,
+      },
+    });
+
+    const result = await inference<string>('Introduce yourself', undefined, {
+      reason: 'newton_chat_introduction',
+      metadata: { conversationId: 'conversation-1' },
+      model: 'command-a-03-2025',
+      maxTokens: 300,
+      temperature: 0.8,
+    });
+
+    expect(result).toBe('Configured response');
+    expect(chatCreateMock).toHaveBeenCalledWith({
+      model: 'command-a-03-2025',
+      messages: [{ role: 'user', content: 'Introduce yourself' }],
+      max_tokens: 300,
+      temperature: 0.8,
+    });
+    expect(prismaMocks.aiUsageLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        reason: 'newton_chat_introduction',
+        model: 'command-a-03-2025',
+        metadata: { conversationId: 'conversation-1' },
+      }),
+    });
+  });
+
+  test('logs structured response usage for parsed responses', async () => {
+    responseParseMock.mockResolvedValue({
+      output_parsed: { score: 4 },
+      usage: {
+        input_tokens: 30,
+        output_tokens: 10,
+        total_tokens: 40,
+      },
+    });
+
+    const schema = z.object({ score: z.number() });
+    const result = await inference<{ score: number }>('Grade this', schema, {
+      reason: 'worksheet_autograde',
+      metadata: { worksheetResponseId: 'response-1' },
+    });
+
+    expect(result).toEqual({ score: 4 });
+    expect(prismaMocks.aiUsageLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        reason: 'worksheet_autograde',
+        operation: 'responses.parse',
+        success: true,
+        promptTokens: 30,
+        completionTokens: 10,
+        totalTokens: 40,
+        metadata: { worksheetResponseId: 'response-1' },
+      }),
+    });
+  });
+
+  test('logs failed attempts before rethrowing', async () => {
+    chatCreateMock.mockRejectedValue(new Error('OpenAI unavailable'));
+
+    await expect(
+      inference<string>('Hello there', undefined, {
+        reason: 'newton_chat_response',
+        metadata: { conversationId: 'conversation-1' },
+      }),
+    ).rejects.toThrow('OpenAI unavailable');
+
+    expect(prismaMocks.aiUsageLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        reason: 'newton_chat_response',
+        operation: 'chat.completions',
+        success: false,
+        estimatedInputTokens: estimateTokenCount('Hello there'),
+        error: 'OpenAI unavailable',
+        metadata: { conversationId: 'conversation-1' },
+      }),
+    });
+    expect(logger.error).toHaveBeenCalledWith(
+      'Failed to generate inference response',
+      expect.objectContaining({
+        reason: 'newton_chat_response',
+      }),
+    );
+  });
+});

package/tests/utils/studentProgress.test.ts

@@ -0,0 +1,361 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+const { prismaMocks, isTeacherInClass, inference, logger } = vi.hoisted(() => ({
+  prismaMocks: {
+    class: { findUnique: vi.fn() },
+    user: { findFirst: vi.fn() },
+    submission: { findMany: vi.fn(), update: vi.fn(), findFirst: vi.fn() },
+  },
+  isTeacherInClass: vi.fn(),
+  inference: vi.fn(),
+  logger: { error: vi.fn() },
+}));
+
+vi.mock("../../src/lib/prisma.js", () => ({
+  prisma: prismaMocks,
+}));
+
+vi.mock("../../src/models/class.js", () => ({
+  isTeacherInClass,
+}));
+
+vi.mock("../../src/utils/inference.js", () => ({
+  inference,
+}));
+
+vi.mock("../../src/utils/logger.js", () => ({
+  logger,
+}));
+
+import {
+  chatAboutStudentProgress,
+  dismissStudentRecommendation,
+  getClassProgressRecommendations,
+  getStudentProgressRecommendations,
+} from "../../src/services/studentProgress.js";
+
+function createSubmission(overrides: Partial<any> = {}) {
+  return {
+    id: overrides.id ?? "submission-1",
+    gradeReceived: overrides.gradeReceived ?? null,
+    submitted: overrides.submitted ?? false,
+    returned: overrides.returned ?? false,
+    submittedAt: overrides.submittedAt ?? null,
+    recommendationState: overrides.recommendationState ?? "NONE",
+    targetedAssignmentId: overrides.targetedAssignmentId ?? null,
+    assignment: {
+      id: overrides.assignment?.id ?? "assignment-1",
+      title: overrides.assignment?.title ?? "Assignment",
+      dueDate: overrides.assignment?.dueDate ?? daysFromNow(-2),
+      maxGrade: overrides.assignment?.maxGrade ?? 100,
+      weight: overrides.assignment?.weight ?? 1,
+      type: overrides.assignment?.type ?? "HOMEWORK",
+      section: overrides.assignment?.section ?? null,
+    },
+  };
+}
+
+function daysFromNow(days: number) {
+  return new Date(Date.now() + days * 24 * 60 * 60 * 1000);
+}
+
+describe("studentProgress service", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    prismaMocks.submission.update.mockResolvedValue({});
+    prismaMocks.submission.findFirst.mockResolvedValue({ id: "submission-1" });
+  });
+
+  test("returns prioritized student recommendations with normalized assignment types", async () => {
+    isTeacherInClass.mockResolvedValue(false);
+    prismaMocks.class.findUnique.mockResolvedValue({
+      id: "class-1",
+      name: "Algebra",
+      subject: "Math",
+    });
+    prismaMocks.user.findFirst.mockResolvedValue({
+      id: "student-1",
+      username: "student1",
+      profile: { displayName: "Student One" },
+    });
+    prismaMocks.submission.findMany.mockResolvedValue([
+      createSubmission({
+        id: "missing-submission",
+        assignment: {
+          id: "missing-assignment",
+          title: "Missing Quiz",
+          dueDate: daysFromNow(-2),
+          type: "QUIZ",
+          section: { id: "section-1", name: "Fractions" },
+        },
+      }),
+      createSubmission({
+        id: "low-score-submission",
+        gradeReceived: 60,
+        submitted: true,
+        submittedAt: daysFromNow(-4),
+        assignment: {
+          id: "low-score-assignment",
+          title: "Fractions Test",
+          dueDate: daysFromNow(-3),
+          type: "TEST",
+        },
+      }),
+    ]);
+
+    const result = await getStudentProgressRecommendations(
+      "student-1",
+      "class-1",
+      "student-1",
+    );
+
+    expect(result.student).toMatchObject({
+      id: "student-1",
+      displayName: "Student One",
+    });
+    expect(result.summary).toMatchObject({
+      overallGrade: 60,
+      completedAssignments: 1,
+      totalAssignments: 2,
+      missingCount: 1,
+      lowScoreCount: 1,
+    });
+    expect(result.recommendations).toHaveLength(2);
+    expect(result.recommendations[0]).toMatchObject({
+      assignmentId: "missing-assignment",
+      recommendationType: "missing",
+    });
+    expect(result.recommendations[0]?.suggestedAssignment).toMatchObject({
+      title: "Make-up: Missing Quiz",
+      type: "HOMEWORK",
+      sectionId: "section-1",
+      sourceAssignmentId: "missing-assignment",
+    });
+    expect(result.recommendations[1]).toMatchObject({
+      assignmentId: "low-score-assignment",
+      recommendationType: "low_score",
+      percentage: 60,
+    });
+    expect(result.recommendations[1]?.suggestedAssignment?.type).toBe(
+      "HOMEWORK",
+    );
+    expect(result.nextSteps).toContain("Prioritize 1 missing assignment.");
+    expect(result.nextSteps).toContain(
+      "Review 1 low-scoring assignment before introducing new material.",
+    );
+  });
+
+  test("aggregates class-wide recommendation counts for teachers", async () => {
+    isTeacherInClass.mockResolvedValue(true);
+    prismaMocks.class.findUnique.mockResolvedValue({
+      id: "class-1",
+      name: "Algebra",
+      subject: "Math",
+      students: [
+        {
+          id: "student-1",
+          username: "student1",
+          profile: { displayName: "Student One" },
+          submissions: [
+            createSubmission({
+              id: "student-1-missing",
+              assignment: {
+                id: "missing-assignment",
+                title: "Missed Homework",
+                dueDate: daysFromNow(-2),
+                type: "HOMEWORK",
+              },
+            }),
+            createSubmission({
+              id: "student-1-low",
+              gradeReceived: 62,
+              submitted: true,
+              submittedAt: daysFromNow(-4),
+              assignment: {
+                id: "student-1-low-assignment",
+                title: "Student 1 Test",
+                dueDate: daysFromNow(-3),
+                type: "TEST",
+              },
+            }),
+          ],
+        },
+        {
+          id: "student-2",
+          username: "student2",
+          profile: { displayName: "Student Two" },
+          submissions: [
+            createSubmission({
+              id: "student-2-low",
+              gradeReceived: 40,
+              submitted: true,
+              submittedAt: daysFromNow(-3),
+              assignment: {
+                id: "student-2-low-assignment",
+                title: "Student 2 Quiz",
+                dueDate: daysFromNow(-3),
+                type: "QUIZ",
+              },
+            }),
+          ],
+        },
+        {
+          id: "student-3",
+          username: "student3",
+          profile: { displayName: "Student Three" },
+          submissions: [
+            createSubmission({
+              id: "student-3-ok",
+              gradeReceived: 95,
+              submitted: true,
+              submittedAt: daysFromNow(-3),
+              assignment: {
+                id: "student-3-ok-assignment",
+                title: "Completed Work",
+                dueDate: daysFromNow(-3),
+                type: "HOMEWORK",
+              },
+            }),
+          ],
+        },
+      ],
+    });
+
+    const result = await getClassProgressRecommendations("teacher-1", "class-1");
+
+    expect(result.class).toMatchObject({
+      id: "class-1",
+      name: "Algebra",
+      subject: "Math",
+    });
+    expect(result.summary).toMatchObject({
+      studentsWithConcerns: 2,
+      totalRecommendations: 3,
+      totalMissingAssignments: 1,
+      totalLowScoreAssignments: 2,
+    });
+    expect(result.students).toHaveLength(2);
+    expect(result.students[0]?.student.id).toBe("student-1");
+    expect(result.students[0]?.recommendations[0]).toMatchObject({
+      assignmentId: "missing-assignment",
+      recommendationType: "missing",
+    });
+    expect(result.students[1]?.student.id).toBe("student-2");
+  });
+
+  test("rejects class-wide recommendations for non-teachers", async () => {
+    isTeacherInClass.mockResolvedValue(false);
+
+    await expect(
+      getClassProgressRecommendations("student-1", "class-1"),
+    ).rejects.toMatchObject({
+      code: "UNAUTHORIZED",
+    });
+  });
+
+  test("falls back to a deterministic chat summary when inference fails", async () => {
+    isTeacherInClass.mockResolvedValue(false);
+    inference.mockRejectedValue(new Error("upstream failure"));
+    prismaMocks.class.findUnique.mockResolvedValue({
+      id: "class-1",
+      name: "Algebra",
+      subject: "Math",
+    });
+    prismaMocks.user.findFirst.mockResolvedValue({
+      id: "student-1",
+      username: "student1",
+      profile: { displayName: "Student One" },
+    });
+    prismaMocks.submission.findMany.mockResolvedValue([
+      createSubmission({
+        id: "missing-submission",
+        assignment: {
+          id: "missing-assignment",
+          title: "Missing Quiz",
+          dueDate: daysFromNow(-2),
+          type: "QUIZ",
+        },
+      }),
+      createSubmission({
+        id: "low-score-submission",
+        gradeReceived: 60,
+        submitted: true,
+        submittedAt: daysFromNow(-4),
+        assignment: {
+          id: "low-score-assignment",
+          title: "Fractions Test",
+          dueDate: daysFromNow(-3),
+          type: "TEST",
+        },
+      }),
+    ]);
+
+    const result = await chatAboutStudentProgress("student-1", {
+      classId: "class-1",
+      studentId: "student-1",
+      message: "How is this student doing?",
+    });
+
+    expect(result.isFallback).toBe(true);
+    expect(result.message).toContain("Student One's current overall grade is 60%.");
+    expect(result.message).toContain("1 assignment appears overdue.");
+    expect(result.message).toContain("1 graded assignment is below 70%.");
+    expect(logger.error).toHaveBeenCalled();
+  });
+
+  test("suppresses recommendations for submissions marked ASSIGNED", async () => {
+    isTeacherInClass.mockResolvedValue(false);
+    prismaMocks.class.findUnique.mockResolvedValue({
+      id: "class-1",
+      name: "Algebra",
+      subject: "Math",
+    });
+    prismaMocks.user.findFirst.mockResolvedValue({
+      id: "student-1",
+      username: "student1",
+      profile: { displayName: "Student One" },
+    });
+    prismaMocks.submission.findMany.mockResolvedValue([
+      createSubmission({
+        id: "low-score-submission",
+        gradeReceived: 52,
+        submitted: true,
+        submittedAt: daysFromNow(-4),
+        recommendationState: "ASSIGNED",
+        assignment: {
+          id: "low-score-assignment",
+          title: "Fractions Test",
+          dueDate: daysFromNow(-3),
+          type: "TEST",
+        },
+      }),
+    ]);
+
+    const result = await getStudentProgressRecommendations(
+      "student-1",
+      "class-1",
+      "student-1",
+    );
+
+    expect(result.recommendations).toHaveLength(0);
+  });
+
+  test("allows teachers to dismiss a recommendation", async () => {
+    isTeacherInClass.mockResolvedValue(true);
+    prismaMocks.submission.findFirst.mockResolvedValue({ id: "submission-1" });
+
+    const result = await dismissStudentRecommendation("teacher-1", {
+      classId: "class-1",
+      studentId: "student-1",
+      submissionId: "submission-1",
+    });
+
+    expect(result).toEqual({ success: true });
+    expect(prismaMocks.submission.update).toHaveBeenCalledWith({
+      where: { id: "submission-1" },
+      data: expect.objectContaining({
+        recommendationState: "DISMISSED",
+      }),
+    });
+  });
+});

package/vitest.unit.config.ts

@@ -19,6 +19,7 @@ export default defineConfig({
       'tests/middleware/**/*.test.ts',
       'tests/lib/**/*.test.ts',
       'tests/pipelines/**/*.test.ts',
+      'tests/routers/**/*.test.ts',
     ],
     env: {
       NODE_ENV: 'test',