@studious-lms/server 1.4.0 → 1.4.1

package/dist/services/studentProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"studentProgress.js","sources":["services/studentProgress.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Student progress service - assignment recommendations and progress chat.\n */\nimport { TRPCError } from \"@trpc/server\";\nimport { prisma } from \"../lib/prisma.js\";\nimport { inference } from \"../utils/inference.js\";\nimport { logger } from \"../utils/logger.js\";\nimport { isTeacherInClass } from \"../models/class.js\";\nimport type { AssignmentType } from \"@prisma/client\";\n\ntype ProgressChatMessage = {\n  role: \"user\" | \"assistant\";\n  content: string;\n};\n\ntype GradeSubmission = {\n  id: string;\n  gradeReceived: number | null;\n  submitted: boolean | null;\n  returned: boolean | null;\n  submittedAt: Date | null;\n  assignment: {\n    id: string;\n    title: string;\n    dueDate: Date;\n    maxGrade: number | null;\n    weight: number;\n    type: AssignmentType;\n    section: { id: string; name: string } | null;\n  };\n};\n\nfunction calculatePercentage(submission: GradeSubmission) {\n  if (submission.gradeReceived == null || !submission.assignment.maxGrade)\n    return null;\n  return (\n    Math.round(\n      (submission.gradeReceived / submission.assignment.maxGrade) * 1000,\n    ) / 10\n  );\n}\n\nfunction calculateTrend(submissions: GradeSubmission[]) {\n  const graded = submissions\n    .filter(\n      (submission) =>\n        submission.gradeReceived != null && submission.assignment.maxGrade,\n    )\n    .sort((a, b) => {\n      const aTime = a.submittedAt?.getTime() ?? a.assignment.dueDate.getTime();\n      const bTime = b.submittedAt?.getTime() ?? b.assignment.dueDate.getTime();\n      return aTime - bTime;\n    })\n    .map((submission) => calculatePercentage(submission))\n    .filter((value): value is number => value != null);\n\n  if (graded.length < 2) return 0;\n  const midpoint = Math.floor(graded.length / 2);\n  const first = graded.slice(0, midpoint);\n  const second = graded.slice(midpoint);\n  const average = (values: number[]) =>\n    values.reduce((sum, value) => sum + value, 0) / values.length;\n  return Math.round((average(second) - average(first)) * 10) / 10;\n}\n\nfunction getOverallGrade(submissions: GradeSubmission[]) {\n  let totalWeighted = 0;\n  let totalWeight = 0;\n\n  for (const submission of submissions) {\n    if (\n      submission.gradeReceived != null &&\n      submission.assignment.maxGrade &&\n      submission.assignment.weight\n    ) {\n      totalWeighted +=\n        (submission.gradeReceived / submission.assignment.maxGrade) *\n        submission.assignment.weight;\n      totalWeight += submission.assignment.weight;\n    }\n  }\n\n  return totalWeight > 0\n    ? Math.round((totalWeighted / totalWeight) * 1000) / 10\n    : null;\n}\n\nasync function loadStudentProgressContext(\n  viewerId: string,\n  classId: string,\n  studentId: string,\n) {\n  const isTeacher = await isTeacherInClass(classId, viewerId);\n  if (viewerId !== studentId && !isTeacher) {\n    throw new TRPCError({\n      code: \"UNAUTHORIZED\",\n      message: \"You can only view your own progress\",\n    });\n  }\n\n  const [classData, student, submissions] = await Promise.all([\n    prisma.class.findUnique({\n      where: { id: classId },\n      select: { id: true, name: true, subject: true },\n    }),\n    prisma.user.findFirst({\n      where: {\n        id: studentId,\n        studentIn: { some: { id: classId } },\n      },\n      select: {\n        id: true,\n        username: true,\n        profile: { select: { displayName: true } },\n      },\n    }),\n    prisma.submission.findMany({\n      where: {\n        studentId,\n        assignment: { classId, graded: true },\n      },\n      include: {\n        assignment: {\n          select: {\n            id: true,\n            title: true,\n            dueDate: true,\n            maxGrade: true,\n            weight: true,\n            type: true,\n            section: { select: { id: true, name: true } },\n          },\n        },\n      },\n      orderBy: { assignment: { dueDate: \"asc\" } },\n    }),\n  ]);\n\n  if (!classData) {\n    throw new TRPCError({ code: \"NOT_FOUND\", message: \"Class not found\" });\n  }\n\n  if (!student) {\n    throw new TRPCError({\n      code: \"NOT_FOUND\",\n      message: \"Student not found in this class\",\n    });\n  }\n\n  return { classData, student, submissions };\n}\n\nexport async function getStudentProgressRecommendations(\n  viewerId: string,\n  classId: string,\n  studentId: string,\n) {\n  const { student, submissions } = await loadStudentProgressContext(\n    viewerId,\n    classId,\n    studentId,\n  );\n\n  const now = new Date();\n  const recommendationCandidates = submissions\n    .map((submission) => {\n      const percentage = calculatePercentage(submission);\n      const isMissing =\n        !submission.submitted &&\n        submission.assignment.dueDate.getTime() < now.getTime();\n      const isLowScore = percentage != null && percentage < 70;\n      const isUnreturned =\n        Boolean(submission.submitted) &&\n        submission.gradeReceived == null &&\n        !submission.returned;\n      const isUpcoming =\n        !Boolean(submission.submitted) &&\n        !submission.submittedAt &&\n        !submission.returned &&\n        submission.gradeReceived == null &&\n        submission.assignment.dueDate.getTime() >= now.getTime();\n      const reasons: string[] = [];\n      let priorityScore = 0;\n\n      if (isMissing) {\n        reasons.push(\"Missing past-due work\");\n        priorityScore += 100;\n      }\n      if (isLowScore) {\n        reasons.push(`Scored ${percentage}%`);\n        priorityScore += 85 - (percentage ?? 0);\n      }\n      if (isUnreturned) {\n        reasons.push(\"Awaiting grade or feedback\");\n        priorityScore += 15;\n      }\n      if (isUpcoming) {\n        reasons.push(\"Upcoming graded assignment\");\n        priorityScore += 5;\n      }\n\n      return {\n        assignmentId: submission.assignment.id,\n        submissionId: submission.id,\n        title: submission.assignment.title,\n        type: submission.assignment.type,\n        sectionName: submission.assignment.section?.name ?? null,\n        dueDate: submission.assignment.dueDate,\n        gradeReceived: submission.gradeReceived,\n        maxGrade: submission.assignment.maxGrade,\n        percentage,\n        submitted: Boolean(submission.submitted),\n        returned: Boolean(submission.returned),\n        reasons,\n        priorityScore,\n      };\n    })\n    .filter((candidate) => candidate.priorityScore > 0)\n    .sort((a, b) => b.priorityScore - a.priorityScore)\n    .slice(0, 5);\n\n  const gradedPercentages = submissions\n    .map(calculatePercentage)\n    .filter((value): value is number => value != null);\n  const lowScoreCount = gradedPercentages.filter(\n    (percentage) => percentage < 70,\n  ).length;\n  const missingCount = submissions.filter(\n    (submission) =>\n      !submission.submitted &&\n      submission.assignment.dueDate.getTime() < now.getTime(),\n  ).length;\n  const trend = calculateTrend(submissions);\n  const overallGrade = getOverallGrade(submissions);\n\n  const nextSteps = [\n    missingCount > 0\n      ? `Prioritize ${missingCount} missing assignment${missingCount === 1 ? \"\" : \"s\"}.`\n      : null,\n    lowScoreCount > 0\n      ? `Review ${lowScoreCount} low-scoring assignment${lowScoreCount === 1 ? \"\" : \"s\"} before introducing new material.`\n      : null,\n    trend < -5\n      ? \"Schedule a check-in because recent performance is trending down.\"\n      : null,\n    recommendationCandidates.length === 0\n      ? \"No urgent assignment issues detected from the available grades.\"\n      : null,\n  ].filter((step): step is string => Boolean(step));\n\n  return {\n    student: {\n      id: student.id,\n      username: student.username,\n      displayName: student.profile?.displayName ?? student.username,\n    },\n    summary: {\n      overallGrade,\n      trend,\n      completedAssignments: submissions.filter((submission) =>\n        Boolean(submission.submitted),\n      ).length,\n      totalAssignments: submissions.length,\n      missingCount,\n      lowScoreCount,\n    },\n    recommendations: recommendationCandidates.map(\n      ({ priorityScore, ...candidate }) => candidate,\n    ),\n    nextSteps,\n  };\n}\n\nfunction buildProgressSummary(submissions: GradeSubmission[]) {\n  return submissions.map((submission) => ({\n    title: submission.assignment.title,\n    type: submission.assignment.type,\n    dueDate: submission.assignment.dueDate.toISOString(),\n    submitted: Boolean(submission.submitted),\n    returned: Boolean(submission.returned),\n    gradeReceived: submission.gradeReceived,\n    maxGrade: submission.assignment.maxGrade,\n    percentage: calculatePercentage(submission),\n    section: submission.assignment.section?.name ?? null,\n  }));\n}\n\nexport async function chatAboutStudentProgress(\n  viewerId: string,\n  input: {\n    classId: string;\n    studentId: string;\n    message: string;\n    history?: ProgressChatMessage[];\n  },\n) {\n  const { classData, student, submissions } = await loadStudentProgressContext(\n    viewerId,\n    input.classId,\n    input.studentId,\n  );\n\n  const displayName = student.profile?.displayName ?? student.username;\n  const summary = {\n    overallGrade: getOverallGrade(submissions),\n    trend: calculateTrend(submissions),\n    assignments: buildProgressSummary(submissions),\n  };\n\n  const messages = [\n    {\n      role: \"system\" as const,\n      content:\n        \"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.\",\n    },\n    {\n      role: \"user\" as const,\n      content: JSON.stringify({\n        class: classData,\n        student: { id: student.id, username: student.username, displayName },\n        progress: summary,\n      }),\n    },\n    ...(input.history ?? []).slice(-8).map((message) => ({\n      role: message.role,\n      content: message.content,\n    })),\n    { role: \"user\" as const, content: input.message },\n  ];\n\n  try {\n    const response = await inference<string>(messages);\n    if (typeof response !== \"string\" || response.trim().length === 0) {\n      throw new Error(\"Student progress chat returned an empty response\");\n    }\n    return { message: response, isFallback: false };\n  } catch (error) {\n    logger.error(\"Failed to generate student progress chat response\", {\n      error,\n      classId: input.classId,\n      studentId: input.studentId,\n    });\n\n    const overall =\n      summary.overallGrade == null\n        ? \"not enough graded work\"\n        : `${summary.overallGrade}%`;\n    const missingItems = summary.assignments.filter(\n      (assignment) =>\n        !assignment.submitted &&\n        new Date(assignment.dueDate).getTime() < Date.now(),\n    ).length;\n    const lowScores = summary.assignments.filter(\n      (assignment) =>\n        assignment.percentage != null && assignment.percentage < 70,\n    ).length;\n    const awaitingFeedback = summary.assignments.filter(\n      (assignment) =>\n        assignment.submitted &&\n        assignment.gradeReceived == null &&\n        !assignment.returned,\n    ).length;\n    const trendLabel =\n      summary.overallGrade == null\n        ? \"not enough graded work to determine a recent trend\"\n        : summary.trend > 5\n        ? \"improving\"\n        : summary.trend < -5\n          ? \"declining\"\n          : \"stable\";\n    const advice = [\n      missingItems > 0\n        ? `Review ${missingItems} missing assignment${missingItems === 1 ? \"\" : \"s\"}.`\n        : null,\n      lowScores > 0\n        ? `Use targeted practice for ${lowScores} low-scoring assignment${lowScores === 1 ? \"\" : \"s\"}.`\n        : null,\n      awaitingFeedback > 0\n        ? `Check back after feedback is returned for ${awaitingFeedback} submitted assignment${awaitingFeedback === 1 ? \"\" : \"s\"}.`\n        : null,\n      missingItems === 0 && lowScores === 0 && awaitingFeedback === 0\n        ? \"Check upcoming work and ask for feedback as new grades are returned.\"\n        : null,\n    ].filter((item): item is string => Boolean(item));\n    return {\n      message: `${displayName}'s current overall progress is ${overall}, with ${trendLabel}. ${advice.join(\" \")}`,\n      isFallback: true,\n    };\n  }\n}\n"],"names":[],"mappings":"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","debug_id":"e4b426af-1ccd-5152-a996-9a03a09b6503"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studious-lms/server",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Backend server for Studious application",
   "main": "dist/exportType.js",
   "types": "dist/exportType.d.ts",
@@ -24,7 +24,7 @@
     "test:watch": "NODE_ENV=test vitest watch",
     "test:coverage": "NODE_ENV=test vitest run --coverage",
     "db:seed": "tsx src/seedDatabase.ts",
-    "sentry:sourcemaps": "sentry-cli sourcemaps inject --org studious-fp --project server ./dist && sentry-cli sourcemaps upload --org studious-fp --project server ./dist"
+    "sentry:sourcemaps": "sentry-cli sourcemaps inject ./dist && sentry-cli sourcemaps upload --org \"${SENTRY_ORG:-studious-lms}\" --project \"${SENTRY_PROJECT:-server}\" ./dist"
   },
   "dependencies": {
     "@google-cloud/storage": "^7.16.0",

package/sentry.properties

@@ -0,0 +1,3 @@
+# Sentry CLI API host. Required for EU data residency (DSN host ingest.de.sentry.io).
+# Override anytime: SENTRY_URL=https://sentry.io
+defaults.url=https://de.sentry.io

package/src/pipelines/aiLabChat.ts

@@ -8,80 +8,14 @@ import { GenerationStatus } from "@prisma/client";
 import { pusher, teacherChannel } from "../lib/pusher.js";
 import type { Assignment, Class, File, Section, User } from "@prisma/client";
 import { inference, inferenceClient, sendAIMessage } from "../utils/inference.js";
-import z from "zod";
 import { logger } from "../utils/logger.js";
 import { createPdf } from "../lib/jsonConversion.js";
 import { v4 } from "uuid";
 import { bucket } from "../lib/googleCloudStorage.js";
 import OpenAI from "openai";
 import { DocumentBlock } from "../lib/jsonStyles.js";
-
-// Schema for lab chat response with PDF document generation
-const labChatResponseSchema = z.object({
-    text: z.string(),
-    worksheetsToCreate: z.array(z.object({
-      title: z.string(),
-      questions: z.array(z.object({
-          type: z.enum(['MULTIPLE_CHOICE', 'TRUE_FALSE', 'SHORT_ANSWER', 'LONG_ANSWER', 'MATH_EXPRESSION', 'ESSAY']),
-          question: z.string(),
-          answer: z.string(),
-          options: z.array(z.object({
-              id: z.string(),
-              text: z.string(),
-              isCorrect: z.boolean(),
-          })).optional().default([]),
-          markScheme: z.array(z.object({
-              id: z.string(),
-              points: z.number(),
-              description: z.string(),
-          })).optional().default([]),
-          points: z.number().optional().default(0),
-          order: z.number(),
-      })),
-  })),
-  sectionsToCreate: z.array(z.object({
-      name: z.string(),
-      color: z.string().regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/).nullable().optional(),
-  })),
-    assignmentsToCreate: z.array(z.object({
-        title: z.string(),
-        instructions: z.string(),
-        dueDate: z.string().datetime(),
-        acceptFiles: z.boolean(),
-        acceptExtendedResponse: z.boolean(),
-        acceptWorksheet: z.boolean(),
-        maxGrade: z.number(),
-        gradingBoundaryId: z.string().nullable().optional(),
-        markschemeId: z.string().nullable().optional(),
-        worksheetIds: z.array(z.string()),
-        studentIds: z.array(z.string()),
-        sectionId: z.string().nullable().optional(),
-        type: z.enum(['HOMEWORK', 'QUIZ', 'TEST', 'PROJECT', 'ESSAY', 'DISCUSSION', 'PRESENTATION', 'LAB', 'OTHER']),
-        attachments: z.array(z.object({
-            id: z.string(),
-        })),
-    })).nullable().optional(),
-    docs: z.array(z.object({
-        title: z.string(),
-        blocks: z.array(z.object({
-            format: z.number().int().min(0).max(12),
-            content: z.union([z.string(), z.array(z.string())]),
-            metadata: z.object({
-                fontSize: z.number().min(6).nullable().optional(),
-                lineHeight: z.number().min(0.6).nullable().optional(),
-                paragraphSpacing: z.number().min(0).nullable().optional(),
-                indentWidth: z.number().min(0).nullable().optional(),
-                paddingX: z.number().min(0).nullable().optional(),
-                paddingY: z.number().min(0).nullable().optional(),
-                font: z.number().int().min(0).max(5).nullable().optional(),
-                color: z.string().regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/).nullable().optional(),
-                background: z.string().regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/).nullable().optional(),
-                align: z.enum(["left", "center", "right"]).nullable().optional(),
-            }).nullable().optional(),
-        })),
-    })).nullable().optional(),
-});
-
+import { type LabChatResponse, labChatArrayFieldInstructions, labChatResponseFormat, labChatResponseSchema } from "./aiLabChatContract.js";
+import { buildLabChatSystemPrompt } from "./labChatPrompt.js";
 
 /** Extended class data for AI context (schema-aware) */
 type ClassContextData = {
@@ -91,8 +25,8 @@ type ClassContextData = {
   gradingBoundaries: { id: string; structured: string }[];
   worksheets: { id: string; name: string; questionCount: number }[];
   files: File[];
-  students: (User & { profile?: { displayName: string | null } | null })[];
-  teachers: (User & { profile?: { displayName: string | null } | null })[];
+  students: { id: string; username: string; profile?: { displayName: string | null } | null }[];
+  teachers: { id: string; username: string; profile?: { displayName: string | null } | null }[];
   assignments: (Assignment & {
     section?: { id: string; name: string; order?: number | null } | null;
     markScheme?: { id: string } | null;
@@ -169,8 +103,8 @@ Syllabus: ${cls.syllabus ? cls.syllabus.slice(0, 200) + (cls.syllabus.length > 2
 SECTIONS (use sectionId when creating assignments):
 ${sectionList || "  (none - suggest sectionsToCreate first)"}
 
-MARK SCHEMES (use markschemeId when creating assignments):
-${markSchemeList || "  (none - suggest creating one or omit markschemeId)"}
+MARK SCHEMES (use markSchemeId when creating assignments):
+${markSchemeList || "  (none - suggest creating one or omit markSchemeId)"}
 
 GRADING BOUNDARIES (use gradingBoundaryId when creating assignments):
 ${gradingBoundaryList || "  (none - suggest creating one or omit gradingBoundaryId)"}
@@ -322,12 +256,10 @@ export const generateAndSendLabIntroduction = async (
   export const generateAndSendLabResponse = async (
     labChatId: string,
     teacherMessage: string,
-    conversationId: string,
     emitOptions?: { classId: string; messageId: string }
   ): Promise<void> => {
     try {
       // Get lab context from database
-      
       const fullLabChat = await prisma.labChat.findUnique({
         where: { id: labChatId },
         include: {
@@ -344,6 +276,8 @@ export const generateAndSendLabIntroduction = async (
         throw new Error('Lab chat not found');
       }
   
+      const conversationId = fullLabChat.conversationId;
+  
       // Get recent conversation history
       const recentMessages = await prisma.message.findMany({
         where: {
@@ -370,67 +304,7 @@ export const generateAndSendLabIntroduction = async (
   
       // Build conversation history as proper message objects
       // Enhance the stored context with schema-aware instructions
-      const enhancedSystemPrompt = `${fullLabChat.context}
-
-IMPORTANT INSTRUCTIONS:
-- Use the context information above (subject, topic, difficulty, objectives, etc.) as your foundation
-- A separate CLASS CONTEXT message lists this class's sections, mark schemes, grading boundaries, worksheets, files, and students with their database IDs
-- Do NOT ask teachers about technical details (hex codes, format numbers, IDs, schema fields). Use sensible defaults yourself.
-- Only ask clarifying questions about content or pedagogy (e.g., topic scope, difficulty, number of questions). Never ask "what hex color?" or "which format?"
-- When creating content, make reasonable choices: pick nice default colors, use standard formatting. Teachers care about the content, not implementation.
-- Only output final course materials when you have sufficient details about the content itself
-- Do not use markdown in your responses - use plain text only
-- You are primarily a chatbot - only provide docs/assignments when the teacher explicitly requests them
-- If the request is vague, ask 1-2 high-level clarifying questions (topic, scope, style) - never technical ones
-
-CRITICAL: REFERENCING OBJECTS - NAMES vs IDs:
-- In "text": Refer to objects by NAME (e.g., "Unit 1", "Biology Rubric", "Cell_Structure_Worksheet")
-- In "assignmentsToCreate", "worksheetsToCreate", "sectionsToCreate": Use DATABASE IDs from the CLASS CONTEXT
-  * sectionId, gradingBoundaryId, markschemeId, worksheetIds, studentIds, attachments[].id must be real IDs from the context
-  * If the class has no sections/mark schemes/grading boundaries, use sectionsToCreate first, or omit optional IDs
-
-RESPONSE FORMAT (JSON):
-{ "text": string, "docs": null | array, "worksheetsToCreate": null | array, "sectionsToCreate": null | array, "assignmentsToCreate": null | array }
-
-CRITICAL - "text" field rules:
-- "text" must be a SHORT conversational summary (2-4 sentences). Plain text, no markdown.
-- NEVER list assignment/worksheet fields in text (no "Type:", "dueDate:", "worksheetIds:", "sectionId:", etc.)
-- NEVER dump schema or JSON-like output in text. The teacher sees the actual content in UI cards below.
-- Good example: "I've created 4 assignments for Unit 1: Week 1 homework on the worksheet, Week 2 quiz, Week 3 lab activity, and Week 4 review test. You can create them below."
-- Bad example: "Week 1 - Homework. Type: HOMEWORK. dueDate: 2026-03-10. worksheetIds: [...]" — NEVER do this.
-
-- "docs": PDF documents when creating course materials (worksheets, handouts, answer keys)
-- "worksheetsToCreate": Worksheets with questions when teacher wants structured assessments
-- "sectionsToCreate": New sections when the class has none or teacher wants new units
-- "assignmentsToCreate": Assignments when teacher explicitly requests them. Use IDs from CLASS CONTEXT. The structured data goes HERE only, not in text.
-
-WHEN CREATING DOCUMENTS (docs):
-- docs: [ { "title": string, "blocks": [ { "format": 0-12, "content": string | string[], "metadata"?: {...} } ] } ]
-- Format: 0=H1, 1=H2, 2=H3, 3=H4, 4=H5, 5=H6, 6=PARAGRAPH, 7=BULLET, 8=NUMBERED, 9=TABLE, 10=IMAGE, 11=CODE_BLOCK, 12=QUOTE
-- Bullets (7) and Numbered (8): content is array of strings; do NOT include * or 1. 2. 3. - renderer adds them
-- Table (9) and Image (10) not supported - do not emit
-- Colors: use sensible defaults (e.g. "#3B82F6" blue, "#10B981" green) - never ask the teacher
-
-WHEN CREATING WORKSHEETS (worksheetsToCreate):
-- Question types: MULTIPLE_CHOICE, TRUE_FALSE, SHORT_ANSWER, LONG_ANSWER, MATH_EXPRESSION, ESSAY
-- For MULTIPLE_CHOICE/TRUE_FALSE: options array with { id, text, isCorrect }
-- For others: options can be empty; answer holds the key
-- markScheme: array of { id, points, description } for rubric items
-- points: total points per question; order: display order
-
-WHEN CREATING SECTIONS (sectionsToCreate):
-- Use when class has no sections or teacher wants new units (e.g., "Unit 1", "Chapter 3")
-- color: pick a nice default (e.g. "#3B82F6") - do not ask
-
-WHEN CREATING ASSIGNMENTS (assignmentsToCreate):
-- Put ALL assignment data (title, type, dueDate, instructions, worksheetIds, etc.) ONLY in assignmentsToCreate. The "text" field gets a brief friendly summary only.
-- Use IDs from CLASS CONTEXT. If class has no sections, suggest sectionsToCreate first.
-- type: HOMEWORK | QUIZ | TEST | PROJECT | ESSAY | DISCUSSION | PRESENTATION | LAB | OTHER
-- sectionId, gradingBoundaryId, markschemeId: use from context; omit if class has none (suggest creating first)
-- studentIds: empty array = assign to all; otherwise list specific student IDs
-- worksheetIds: IDs of existing worksheets; empty if using docs-only or new worksheets
-- attachments[].id: file IDs from CLASS CONTEXT (PDFs, documents)
-- acceptFiles, acceptExtendedResponse, acceptWorksheet: set based on assignment type`;
+      const enhancedSystemPrompt = buildLabChatSystemPrompt(fullLabChat.context);
   
       const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
         { role: 'system', content: enhancedSystemPrompt },
@@ -471,10 +345,18 @@ WHEN CREATING ASSIGNMENTS (assignmentsToCreate):
             },
           },
           students: {
-            include: { profile: { select: { displayName: true } } },
+            select: {
+              id: true,
+              username: true,
+              profile: { select: { displayName: true } },
+            },
           },
           teachers: {
-            include: { profile: { select: { displayName: true } } },
+            select: {
+              id: true,
+              username: true,
+              profile: { select: { displayName: true } },
+            },
           },
           classFiles: {
             include: {
@@ -529,7 +411,7 @@ REMINDER: Your "text" response must be a short, friendly summary (2-4 sentences)
     //     response_format: zodTextFormat(labChatResponseSchema, "lab_chat_response_format"),
     //   });
 
-    const response = await inference<z.infer<typeof labChatResponseSchema>>(messages, labChatResponseSchema);
+    const response = await inference<LabChatResponse>(messages, labChatResponseSchema);
         
       if (!response) {
         throw new Error('No response generated from inference API');
@@ -635,6 +517,10 @@ REMINDER: Your "text" response must be a short, friendly summary (2-4 sentences)
       }
 
       if (emitOptions) {
+        await prisma.message.update({
+          where: { id: emitOptions.messageId },
+          data: { status: GenerationStatus.COMPLETED },
+        });
         try {
           await pusher.trigger(teacherChannel(emitOptions.classId), "lab-response-completed", {
             labChatId,
@@ -643,10 +529,6 @@ REMINDER: Your "text" response must be a short, friendly summary (2-4 sentences)
         } catch (broadcastError) {
           logger.error("Failed to broadcast lab response completed:", { error: broadcastError });
         }
-        await prisma.message.update({
-          where: { id: emitOptions.messageId },
-          data: { status: GenerationStatus.COMPLETED },
-        });
       }
 
       logger.info('AI response sent', { labChatId, conversationId });
@@ -663,20 +545,27 @@ REMINDER: Your "text" response must be a short, friendly summary (2-4 sentences)
       });
 
       if (emitOptions) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
+        try {
+          await prisma.message.update({
+            where: { id: emitOptions.messageId },
+            data: { status: GenerationStatus.FAILED },
+          });
+        } catch (statusError) {
+          logger.error("Failed to set message status FAILED:", {
+            error: statusError,
+            labChatId,
+            messageId: emitOptions.messageId,
+          });
+        }
         try {
           await pusher.trigger(teacherChannel(emitOptions.classId), "lab-response-failed", {
             labChatId,
             messageId: emitOptions.messageId,
-            error: errorMessage,
+            error: "AI response generation failed",
           });
         } catch (broadcastError) {
           logger.error("Failed to broadcast lab response failed:", { error: broadcastError });
         }
-        await prisma.message.update({
-          where: { id: emitOptions.messageId },
-          data: { status: GenerationStatus.FAILED },
-        });
       }
 
       throw error; // Re-throw to see the full error in the calling function

package/src/pipelines/aiLabChatContract.ts

@@ -0,0 +1,75 @@
+import z from "zod";
+
+export const labChatResponseSchema = z.object({
+  text: z.string(),
+  worksheetsToCreate: z.array(z.object({
+    title: z.string(),
+    questions: z.array(z.object({
+      type: z.enum(["MULTIPLE_CHOICE", "TRUE_FALSE", "SHORT_ANSWER", "LONG_ANSWER", "MATH_EXPRESSION", "ESSAY"]),
+      question: z.string(),
+      answer: z.string(),
+      options: z.array(z.object({
+        id: z.string(),
+        text: z.string(),
+        isCorrect: z.boolean(),
+      })).optional().default([]),
+      markScheme: z.array(z.object({
+        id: z.string(),
+        points: z.number(),
+        description: z.string(),
+      })).optional().default([]),
+      points: z.number().optional().default(0),
+      order: z.number(),
+    })),
+  })).default([]),
+  sectionsToCreate: z.array(z.object({
+    name: z.string(),
+    color: z.string().regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/).nullable().optional(),
+  })).default([]),
+  assignmentsToCreate: z.array(z.object({
+    title: z.string(),
+    instructions: z.string(),
+    dueDate: z.string().datetime(),
+    acceptFiles: z.boolean(),
+    acceptExtendedResponse: z.boolean(),
+    acceptWorksheet: z.boolean(),
+    maxGrade: z.number(),
+    gradingBoundaryId: z.string().nullable().optional(),
+    markSchemeId: z.string().nullable().optional(),
+    worksheetIds: z.array(z.string()),
+    studentIds: z.array(z.string()),
+    sectionId: z.string().nullable().optional(),
+    type: z.enum(["HOMEWORK", "QUIZ", "TEST", "PROJECT", "ESSAY", "DISCUSSION", "PRESENTATION", "LAB", "OTHER"]),
+    attachments: z.array(z.object({
+      id: z.string(),
+    })),
+  })).nullable().optional(),
+  docs: z.array(z.object({
+    title: z.string(),
+    blocks: z.array(z.object({
+      format: z.number().int().min(0).max(12),
+      content: z.union([z.string(), z.array(z.string())]),
+      metadata: z.object({
+        fontSize: z.number().min(6).nullable().optional(),
+        lineHeight: z.number().min(0.6).nullable().optional(),
+        paragraphSpacing: z.number().min(0).nullable().optional(),
+        indentWidth: z.number().min(0).nullable().optional(),
+        paddingX: z.number().min(0).nullable().optional(),
+        paddingY: z.number().min(0).nullable().optional(),
+        font: z.number().int().min(0).max(5).nullable().optional(),
+        color: z.string().regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/).nullable().optional(),
+        background: z.string().regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/).nullable().optional(),
+        align: z.enum(["left", "center", "right"]).nullable().optional(),
+      }).nullable().optional(),
+    })),
+  })).nullable().optional(),
+});
+
+export type LabChatResponse = z.infer<typeof labChatResponseSchema>;
+
+export const labChatResponseFormat = `{ "text": string, "docs": null | array, "worksheetsToCreate": array, "sectionsToCreate": array, "assignmentsToCreate": null | array }`;
+
+export const labChatArrayFieldInstructions = [
+  `- "worksheetsToCreate": always output an array. Use [] when there are no worksheets to create.`,
+  `- "sectionsToCreate": always output an array. Use [] when there are no sections to create.`,
+].join("\n");

package/src/pipelines/labChatPrompt.ts

@@ -0,0 +1,68 @@
+export const buildLabChatSystemPrompt = (context: string): string => `${context}
+
+IMPORTANT INSTRUCTIONS:
+- Use the context information above (subject, topic, difficulty, objectives, etc.) as your foundation
+- A separate CLASS CONTEXT message lists this class's sections, mark schemes, grading boundaries, worksheets, files, and students with their database IDs
+- Do NOT ask teachers about technical details (hex codes, format numbers, IDs, schema fields). Use sensible defaults yourself.
+- Only ask clarifying questions about content or pedagogy (e.g., topic scope, difficulty, number of questions). Never ask "what hex color?" or "which format?"
+- When creating content, make reasonable choices: pick nice default colors, use standard formatting. Teachers care about the content, not implementation.
+- Only output final course materials when you have sufficient details about the content itself
+- Do not use markdown in your responses - use plain text only
+- You are primarily a chatbot - only provide docs/assignments when the teacher explicitly requests them
+- If the request is vague, ask 1-2 high-level clarifying questions (topic, scope, style) - never technical ones
+
+CRITICAL: REFERENCING OBJECTS - NAMES vs IDs:
+- In "text": Refer to objects by NAME (e.g., "Unit 1", "Biology Rubric", "Cell_Structure_Worksheet")
+- In "assignmentsToCreate", "worksheetsToCreate", "sectionsToCreate": Use DATABASE IDs from the CLASS CONTEXT
+  * sectionId, gradingBoundaryId, markSchemeId, worksheetIds, studentIds, attachments[].id must be real IDs from the context
+  * If the class has no sections/mark schemes/grading boundaries, use sectionsToCreate first, or omit optional IDs
+
+RESPONSE FORMAT (JSON):
+{ "text": string, "docs": null | array, "worksheetsToCreate": array, "sectionsToCreate": array, "assignmentsToCreate": null | array }
+
+CRITICAL ARRAY RULES:
+- "worksheetsToCreate" must always be an array. Use [] when there are no worksheets to create.
+- "sectionsToCreate" must always be an array. Use [] when there are no sections to create.
+- Do not return null for "worksheetsToCreate" or "sectionsToCreate".
+
+CRITICAL - "text" field rules:
+- "text" must be a SHORT conversational summary (2-4 sentences). Plain text, no markdown.
+- NEVER list assignment/worksheet fields in text (no "Type:", "dueDate:", "worksheetIds:", "sectionId:", etc.)
+- NEVER dump schema or JSON-like output in text. The teacher sees the actual content in UI cards below.
+- Good example: "I've created 4 assignments for Unit 1: Week 1 homework on the worksheet, Week 2 quiz, Week 3 lab activity, and Week 4 review test. You can create them below."
+- Bad example: "Week 1 - Homework. Type: HOMEWORK. dueDate: 2026-03-10. worksheetIds: [...]" - NEVER do this.
+
+- "docs": PDF documents when creating course materials (worksheets, handouts, answer keys)
+- "worksheetsToCreate": Worksheets with questions when teacher wants structured assessments. Always return an array.
+- "sectionsToCreate": New sections when the class has none or teacher wants new units. Always return an array.
+- "assignmentsToCreate": Assignments when teacher explicitly requests them. Use IDs from CLASS CONTEXT. The structured data goes HERE only, not in text.
+
+WHEN CREATING DOCUMENTS (docs):
+- docs: [ { "title": string, "blocks": [ { "format": 0-12, "content": string | string[], "metadata"?: {...} } ] } ]
+- Format: 0=H1, 1=H2, 2=H3, 3=H4, 4=H5, 5=H6, 6=PARAGRAPH, 7=BULLET, 8=NUMBERED, 9=TABLE, 10=IMAGE, 11=CODE_BLOCK, 12=QUOTE
+- Bullets (7) and Numbered (8): content is array of strings; do NOT include * or 1. 2. 3. - renderer adds them
+- Table (9) and Image (10) not supported - do not emit
+- Colors: use sensible defaults (e.g. "#3B82F6" blue, "#10B981" green) - never ask the teacher
+
+WHEN CREATING WORKSHEETS (worksheetsToCreate):
+- Return an array every time, even when empty.
+- Question types: MULTIPLE_CHOICE, TRUE_FALSE, SHORT_ANSWER, LONG_ANSWER, MATH_EXPRESSION, ESSAY
+- For MULTIPLE_CHOICE/TRUE_FALSE: options array with { id, text, isCorrect }
+- For others: options can be empty; answer holds the key
+- markScheme: array of { id, points, description } for rubric items
+- points: total points per question; order: display order
+
+WHEN CREATING SECTIONS (sectionsToCreate):
+- Return an array every time, even when empty.
+- Use when class has no sections or teacher wants new units (e.g., "Unit 1", "Chapter 3")
+- color: pick a nice default (e.g. "#3B82F6") - do not ask
+
+WHEN CREATING ASSIGNMENTS (assignmentsToCreate):
+- Put ALL assignment data (title, type, dueDate, instructions, worksheetIds, etc.) ONLY in assignmentsToCreate. The "text" field gets a brief friendly summary only.
+- Use IDs from CLASS CONTEXT. If class has no sections, suggest sectionsToCreate first.
+- type: HOMEWORK | QUIZ | TEST | PROJECT | ESSAY | DISCUSSION | PRESENTATION | LAB | OTHER
+- sectionId, gradingBoundaryId, markSchemeId: use from context; omit if class has none (suggest creating first)
+- studentIds: empty array = assign to all; otherwise list specific student IDs
+- worksheetIds: IDs of existing worksheets; empty if using docs-only or new worksheets
+- attachments[].id: file IDs from CLASS CONTEXT (PDFs, documents)
+- acceptFiles, acceptExtendedResponse, acceptWorksheet: set based on assignment type`;

package/src/routers/_app.ts

@@ -20,6 +20,7 @@ import { newtonChatRouter } from "./newtonChat.js";
 import { marketingRouter } from "./marketing.js";
 import { worksheetRouter } from "./worksheet.js";
 import { commentRouter } from "./comment.js";
+import { studentProgressRouter } from "./studentProgress.js";
 
 export const appRouter = createTRPCRouter({
   class: classRouter,
@@ -41,7 +42,8 @@ export const appRouter = createTRPCRouter({
   marketing: marketingRouter,
   worksheet: worksheetRouter,
   comment: commentRouter,
-}); 
+  studentProgress: studentProgressRouter,
+});
 
 // Export type router type definition
 export type AppRouter = typeof appRouter;
@@ -49,4 +51,4 @@ export type RouterInputs = inferRouterInputs<AppRouter>;
 export type RouterOutputs = inferRouterOutputs<AppRouter>;
 
 // Export caller
-export const createCaller = createCallerFactory(appRouter); 
+export const createCaller = createCallerFactory(appRouter);

package/src/routers/studentProgress.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { createTRPCRouter, protectedClassMemberProcedure } from "../trpc.js";
+import {
+  chatAboutStudentProgress,
+  getStudentProgressRecommendations,
+} from "../services/studentProgress.js";
+
+const progressInputSchema = z.object({
+  classId: z.string(),
+  studentId: z.string(),
+});
+
+export const studentProgressRouter = createTRPCRouter({
+  getRecommendations: protectedClassMemberProcedure
+    .input(progressInputSchema)
+    .query(({ ctx, input }) =>
+      getStudentProgressRecommendations(
+        ctx.user!.id,
+        input.classId,
+        input.studentId,
+      ),
+    ),
+
+  chat: protectedClassMemberProcedure
+    .input(
+      progressInputSchema.extend({
+        message: z.string().min(1).max(4000),
+        history: z
+          .array(
+            z.object({
+              role: z.enum(["user", "assistant"]),
+              content: z.string().min(1).max(4000),
+            }),
+          )
+          .max(8)
+          .optional(),
+      }),
+    )
+    .mutation(({ ctx, input }) =>
+      chatAboutStudentProgress(ctx.user!.id, {
+        classId: input.classId,
+        studentId: input.studentId,
+        message: input.message,
+        history: input.history,
+      }),
+    ),
+});