@studious-lms/server 1.5.0 → 1.6.0

package/src/utils/inference.ts

@@ -8,7 +8,7 @@ import { prisma } from '../lib/prisma.js';
 import { chatChannel, pusher } from '../lib/pusher.js';
 import { ensureAIUserExists, getAIUserId } from './aiUser.js';
 import { env } from '../lib/config/env.js';
-import { Prisma } from '@prisma/client';
+import { JobStatus, Prisma } from '@prisma/client';
 import { ZodSchema } from 'zod';
 import { zodTextFormat } from 'openai/helpers/zod';
 
@@ -276,6 +276,214 @@ export async function sendAIMessage(
   };
 }
 
+interface AIMessageSenderInfo {
+  displayName?: string;
+  profilePicture?: string | null;
+}
+
+function buildAISenderInfo(customSender?: AIMessageSenderInfo) {
+  return {
+    id: getAIUserId(),
+    username: 'Newton_AI',
+    profile: {
+      displayName: customSender?.displayName ?? 'Newton AI',
+      profilePicture: customSender?.profilePicture ?? null,
+    },
+  };
+}
+
+/**
+ * Create an AI message placeholder in PENDING state and broadcast it.
+ *
+ * The AI message lifecycle == job lifecycle: this row is the bubble the
+ * client renders for "AI is thinking..." and is later flipped by
+ * {@link completePendingAIMessage} / {@link failPendingAIMessage}.
+ */
+export async function createPendingAIMessage(
+  conversationId: string,
+  options: {
+    customSender?: AIMessageSenderInfo;
+  } = {},
+): Promise<{
+  id: string;
+  conversationId: string;
+  createdAt: Date;
+  senderId: string;
+  status: JobStatus;
+}> {
+  await ensureAIUserExists();
+
+  const aiMessage = await prisma.message.create({
+    data: {
+      content: '',
+      senderId: getAIUserId(),
+      conversationId,
+      status: JobStatus.PENDING,
+    },
+  });
+
+  logger.info('AI placeholder message created', {
+    messageId: aiMessage.id,
+    conversationId,
+  });
+
+  const senderInfo = buildAISenderInfo(options.customSender);
+
+  try {
+    await pusher.trigger(chatChannel(conversationId), 'new-message', {
+      id: aiMessage.id,
+      content: '',
+      senderId: getAIUserId(),
+      conversationId: aiMessage.conversationId,
+      status: JobStatus.PENDING,
+      createdAt: aiMessage.createdAt,
+      sender: senderInfo,
+      mentionedUserIds: [],
+      meta: {},
+      attachments: [],
+    });
+  } catch (error) {
+    logger.error('Failed to broadcast pending AI message:', {
+      error,
+      messageId: aiMessage.id,
+    });
+  }
+
+  return {
+    id: aiMessage.id,
+    conversationId: aiMessage.conversationId,
+    createdAt: aiMessage.createdAt,
+    senderId: aiMessage.senderId,
+    status: JobStatus.PENDING,
+  };
+}
+
+/**
+ * Fill a PENDING AI message with its generated content and flip it to
+ * COMPLETED. Broadcasts a `message-updated` event so clients that already
+ * rendered the placeholder can patch it in place.
+ */
+export async function completePendingAIMessage(
+  messageId: string,
+  content: string,
+  options: {
+    attachments?: { connect: { id: string }[] };
+    meta?: Record<string, any>;
+    customSender?: AIMessageSenderInfo;
+  } = {},
+): Promise<{
+  id: string;
+  content: string;
+  conversationId: string;
+  createdAt: Date;
+  status: JobStatus;
+}> {
+  const updated = await prisma.message.update({
+    where: { id: messageId },
+    data: {
+      content,
+      status: JobStatus.COMPLETED,
+      ...(options.attachments && {
+        attachments: {
+          connect: options.attachments.connect,
+        },
+      }),
+      ...(options.meta !== undefined && {
+        meta: options.meta as Prisma.InputJsonValue,
+      }),
+    },
+    include: {
+      attachments: true,
+    },
+  });
+
+  logger.info('AI message completed', {
+    messageId: updated.id,
+    conversationId: updated.conversationId,
+    contentLength: content.length,
+  });
+
+  const senderInfo = buildAISenderInfo(options.customSender);
+
+  try {
+    await pusher.trigger(chatChannel(updated.conversationId), 'message-updated', {
+      id: updated.id,
+      content: updated.content,
+      senderId: updated.senderId,
+      conversationId: updated.conversationId,
+      status: updated.status,
+      createdAt: updated.createdAt,
+      sender: senderInfo,
+      mentionedUserIds: [],
+      meta: updated.meta ?? {},
+      attachments: updated.attachments.map((attachment) => ({
+        id: attachment.id,
+        attachmentId: attachment.id,
+        name: attachment.name,
+        type: attachment.type,
+        size: attachment.size,
+        path: attachment.path,
+      })),
+    });
+  } catch (error) {
+    logger.error('Failed to broadcast completed AI message:', {
+      error,
+      messageId,
+    });
+  }
+
+  return {
+    id: updated.id,
+    content: updated.content,
+    conversationId: updated.conversationId,
+    createdAt: updated.createdAt,
+    status: (updated.status ?? JobStatus.COMPLETED) as JobStatus,
+  };
+}
+
+/**
+ * Flip a PENDING AI message to FAILED and broadcast the status change.
+ * Does NOT throw — failure paths in the pipelines call this in catch blocks
+ * and we do not want broadcast/DB errors to mask the original error.
+ */
+export async function failPendingAIMessage(
+  messageId: string,
+  options: { reason?: string } = {},
+): Promise<void> {
+  try {
+    const updated = await prisma.message.update({
+      where: { id: messageId },
+      data: { status: JobStatus.FAILED },
+      select: { id: true, conversationId: true, status: true },
+    });
+
+    logger.info('AI message marked as failed', {
+      messageId: updated.id,
+      conversationId: updated.conversationId,
+      reason: options.reason,
+    });
+
+    try {
+      await pusher.trigger(chatChannel(updated.conversationId), 'message-updated', {
+        id: updated.id,
+        conversationId: updated.conversationId,
+        status: updated.status,
+      });
+    } catch (broadcastError) {
+      logger.error('Failed to broadcast failed AI message:', {
+        error: broadcastError,
+        messageId,
+      });
+    }
+  } catch (error) {
+    logger.error('Failed to mark AI message as failed:', {
+      error,
+      messageId,
+      reason: options.reason,
+    });
+  }
+}
+
 /** Responses API user parts use `type: "input_*"`; chat completions use `text` / `image_url` / etc. */
 function isResponseInputWithInputParts(
   content: OpenAI.Chat.Completions.ChatCompletionMessageParam[] | ResponseInput

package/src/workers/index.ts

@@ -12,9 +12,19 @@ import { Worker } from 'bullmq';
 import { prisma } from '../lib/prisma.js';
 import { logger } from '../utils/logger.js';
 import { bullConnection } from './connection.js';
+import { aiLabChatWorker } from './processors/aiLabChat.js';
+import { aiNewtonChatWorker } from './processors/aiNewtonChat.js';
+import { gradeWorksheetWorker } from './processors/gradeWorksheet.js';
 import { pdfToWorksheetWorker } from './processors/pdfToWorksheet.js';
+import { studentProgressChatWorker } from './processors/studentProgressChat.js';
 
-const workers: Worker<any>[] = [pdfToWorksheetWorker];
+const workers: Worker<any>[] = [
+  pdfToWorksheetWorker,
+  gradeWorksheetWorker,
+  aiLabChatWorker,
+  aiNewtonChatWorker,
+  studentProgressChatWorker,
+];
 
 logger.info('Workers ready', {
   pid: process.pid,

package/src/workers/processors/aiLabChat.ts

@@ -0,0 +1,65 @@
+import {
+  generateAndSendLabIntroduction,
+  generateAndSendLabResponse,
+} from '../../pipelines/aiLabChat.js';
+import { prisma } from '../../lib/prisma.js';
+import { isAIUser } from '../../utils/aiUser.js';
+import { createRunJobWorker } from './createRunJobWorker.js';
+
+export const aiLabChatWorker = createRunJobWorker({
+  type: 'AI_LAB_CHAT',
+  workerOptions: {
+    // Lab responses can produce PDFs and large schemas; cap concurrency to
+    // keep memory under control and to honour upstream model rate limits.
+    concurrency: 1,
+    limiter: { max: 5, duration: 60_000 },
+  },
+  run: async ({ conversationId, aiMessageId }) => {
+    const labChat = await prisma.labChat.findFirst({
+      where: { conversationId },
+      select: {
+        id: true,
+        classId: true,
+        context: true,
+        class: { select: { subject: true } },
+      },
+    });
+
+    if (!labChat) {
+      throw new Error(
+        `LabChat for conversationId=${conversationId} not found`,
+      );
+    }
+
+    // The AI message is a placeholder we created before enqueue; the
+    // pipeline fills it in. Look up the most recent non-AI message in the
+    // conversation to feed the response generator. If none exists, this is
+    // the introductory message at the top of a brand-new lab chat.
+    const triggeringMessage = await prisma.message.findFirst({
+      where: {
+        conversationId,
+        senderId: { not: 'AI_ASSISTANT' },
+      },
+      orderBy: { createdAt: 'desc' },
+      select: { id: true, content: true, senderId: true },
+    });
+
+    if (!triggeringMessage || isAIUser(triggeringMessage.senderId)) {
+      await generateAndSendLabIntroduction(
+        labChat.id,
+        conversationId,
+        labChat.context,
+        labChat.class?.subject || 'Lab',
+        aiMessageId,
+      );
+      return { labChatId: labChat.id, kind: 'introduction', aiMessageId };
+    }
+
+    await generateAndSendLabResponse(labChat.id, triggeringMessage.content, {
+      classId: labChat.classId,
+      aiMessageId,
+    });
+
+    return { labChatId: labChat.id, aiMessageId };
+  },
+});

package/src/workers/processors/aiNewtonChat.ts

@@ -0,0 +1,75 @@
+import {
+  generateAndSendNewtonIntroduction,
+  generateAndSendNewtonResponse,
+} from '../../pipelines/aiNewtonChat.js';
+import { prisma } from '../../lib/prisma.js';
+import { isAIUser } from '../../utils/aiUser.js';
+import { createRunJobWorker } from './createRunJobWorker.js';
+
+export const aiNewtonChatWorker = createRunJobWorker({
+  type: 'AI_NEWTON_CHAT',
+  workerOptions: {
+    concurrency: 2,
+    limiter: { max: 10, duration: 60_000 },
+  },
+  run: async ({ conversationId, aiMessageId }) => {
+    const newtonChat = await prisma.newtonChat.findFirst({
+      where: { conversationId },
+      select: {
+        id: true,
+        submission: {
+          select: {
+            id: true,
+            assignment: {
+              select: {
+                id: true,
+                title: true,
+                instructions: true,
+                class: { select: { subject: true } },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    if (!newtonChat) {
+      throw new Error(
+        `NewtonChat for conversationId=${conversationId} not found`,
+      );
+    }
+
+    // Resolve the triggering student message (if any). On a brand-new
+    // tutor session there are no student messages yet, so we run the
+    // introduction path; otherwise we run the response path against the
+    // most recent non-AI message.
+    const triggeringMessage = await prisma.message.findFirst({
+      where: {
+        conversationId,
+        senderId: { not: 'AI_ASSISTANT' },
+      },
+      orderBy: { createdAt: 'desc' },
+      select: { id: true, content: true, senderId: true },
+    });
+
+    if (!triggeringMessage || isAIUser(triggeringMessage.senderId)) {
+      await generateAndSendNewtonIntroduction(
+        newtonChat.id,
+        conversationId,
+        newtonChat.submission.id,
+        aiMessageId,
+      );
+      return { newtonChatId: newtonChat.id, kind: 'introduction', aiMessageId };
+    }
+
+    await generateAndSendNewtonResponse(
+      newtonChat.id,
+      triggeringMessage.content,
+      conversationId,
+      newtonChat.submission,
+      aiMessageId,
+    );
+
+    return { newtonChatId: newtonChat.id, aiMessageId };
+  },
+});

package/src/workers/processors/createRunJobWorker.ts

@@ -0,0 +1,164 @@
+/**
+ * `createRunJobWorker` — shared factory for every BullMQ processor in this app.
+ *
+ * Wraps the boilerplate that every RunJob-backed worker needs:
+ *   - Idempotent skip if the RunJob already SUCCEEDED (recovery after a crash
+ *     that lost the BullMQ ack).
+ *   - Status transitions: PENDING/RUNNING → RUNNING (with attempts++) → SUCCEEDED.
+ *   - Failure handling: record latest error every attempt, flip to FAILED only
+ *     on the final retry.
+ *   - Standardised structured logging on `error` / `failed` / `completed`.
+ *
+ * A processor implementation only has to provide its `RunJobType`, optional
+ * BullMQ options (concurrency, limiter, etc.), and a `run` callback that does
+ * the actual work. The callback receives the typed `JobInputs[type]` payload
+ * and a context object with `runJobId`, `bullJobId`, `attempt`, plus the
+ * `userId` / `classId` from the original `enqueueRunJob` call.
+ */
+import { Worker, type Job, type WorkerOptions } from 'bullmq';
+import { Prisma, type RunJobType } from '@prisma/client';
+import { bullConnection } from '../connection.js';
+import { prisma } from '../../lib/prisma.js';
+import { logger } from '../../utils/logger.js';
+import { QUEUE_NAMES, type JobInputs } from '../queues.js';
+
+export interface RunJobContext {
+  runJobId: string;
+  bullJobId: string | undefined;
+  /** 1-indexed attempt number of the current run. */
+  attempt: number;
+  /** From `EnqueueOptions.userId` on the producer side. */
+  userId: string | null;
+  /** From `EnqueueOptions.classId` on the producer side. */
+  classId: string | null;
+}
+
+export interface CreateRunJobWorkerOptions<T extends RunJobType> {
+  type: T;
+  /** BullMQ `WorkerOptions` minus `connection`, which is supplied by the helper. */
+  workerOptions?: Omit<WorkerOptions, 'connection'>;
+  /**
+   * The actual work. Return any JSON-serialisable value (or `null`) — it gets
+   * persisted to `RunJob.result` for the client to read back.
+   */
+  run: (
+    input: JobInputs[T],
+    ctx: RunJobContext,
+  ) => Promise<Prisma.InputJsonValue | null>;
+}
+
+type WorkerData<T extends RunJobType> = JobInputs[T] & { runJobId: string };
+
+export function createRunJobWorker<T extends RunJobType>({
+  type,
+  workerOptions,
+  run,
+}: CreateRunJobWorkerOptions<T>): Worker<WorkerData<T>> {
+  const name = QUEUE_NAMES[type];
+
+  const worker = new Worker<WorkerData<T>>(
+    name,
+    async (job: Job<WorkerData<T>>) => {
+      const { runJobId, ...rest } = job.data;
+      // The destructured rest is `Omit<JobInputs[T] & { runJobId }, 'runJobId'>`,
+      // which TS can't simplify back to `JobInputs[T]` while `T` is generic.
+      const input = rest as unknown as JobInputs[T];
+
+      const existing = await prisma.runJob.findUnique({
+        where: { id: runJobId },
+        select: { status: true, result: true, userId: true, classId: true },
+      });
+
+      if (existing?.status === 'SUCCEEDED') {
+        logger.info(`${name} RunJob already succeeded; skipping re-run`, {
+          runJobId,
+          bullJobId: job.id,
+        });
+        return existing.result;
+      }
+
+      await prisma.runJob.update({
+        where: { id: runJobId },
+        data: {
+          status: 'RUNNING',
+          startedAt: existing?.status === 'RUNNING' ? undefined : new Date(),
+          attempts: { increment: 1 },
+        },
+      });
+
+      const result = await run(input, {
+        runJobId,
+        bullJobId: job.id,
+        attempt: job.attemptsMade + 1,
+        userId: existing?.userId ?? null,
+        classId: existing?.classId ?? null,
+      });
+
+      await prisma.runJob.update({
+        where: { id: runJobId },
+        data: {
+          status: 'SUCCEEDED',
+          finishedAt: new Date(),
+          error: null,
+          result: result === null ? Prisma.JsonNull : result,
+        },
+      });
+
+      return result;
+    },
+    { connection: bullConnection, ...workerOptions },
+  );
+
+  worker.on('error', (err) => {
+    logger.error(`${name} worker error`, {
+      error: err.message,
+      stack: err.stack,
+    });
+  });
+
+  worker.on('failed', async (job, err) => {
+    if (!job) return;
+
+    const runJobId = job.data?.runJobId;
+    const isFinalAttempt = job.attemptsMade >= (job.opts.attempts ?? 1);
+
+    logger.error(`${name} job failed`, {
+      bullJobId: job.id,
+      runJobId,
+      attempt: job.attemptsMade,
+      finalAttempt: isFinalAttempt,
+      error: err.message,
+    });
+
+    if (!runJobId) return;
+
+    await prisma.runJob
+      .update({
+        where: { id: runJobId },
+        data: {
+          error: err.message,
+          ...(isFinalAttempt
+            ? { status: 'FAILED', finishedAt: new Date() }
+            : {}),
+        },
+      })
+      .catch((updateError) => {
+        logger.error(`Failed to record ${name} failure on RunJob`, {
+          runJobId,
+          error:
+            updateError instanceof Error
+              ? updateError.message
+              : String(updateError),
+        });
+      });
+  });
+
+  worker.on('completed', (job) => {
+    logger.info(`${name} job completed`, {
+      bullJobId: job.id,
+      runJobId: job.data?.runJobId,
+    });
+  });
+
+  return worker;
+}

package/src/workers/processors/gradeWorksheet.ts

@@ -0,0 +1,16 @@
+import { gradeWorksheetPipeline } from '../../pipelines/gradeWorksheet.js';
+import { createRunJobWorker } from './createRunJobWorker.js';
+
+export const gradeWorksheetWorker = createRunJobWorker({
+  type: 'GRADE_WORKSHEET',
+  workerOptions: {
+    concurrency: 2,
+    // Each pipeline run can fan out to many per-question inferences; keep
+    // throughput modest until we measure real-world usage.
+    limiter: { max: 5, duration: 60_000 },
+  },
+  run: async ({ worksheetResponseId }) => {
+    await gradeWorksheetPipeline(worksheetResponseId);
+    return { worksheetResponseId };
+  },
+});

package/src/workers/processors/pdfToWorksheet.ts

@@ -1,119 +1,17 @@
-import { Worker, type Job } from 'bullmq';
-import { Prisma } from '@prisma/client';
-import { bullConnection } from '../connection.js';
-import { prisma } from '../../lib/prisma.js';
-import { logger } from '../../utils/logger.js';
 import { pdfToWorksheet } from '../../pipelines/pdfToWorksheet.js';
+import { createRunJobWorker } from './createRunJobWorker.js';
 
-interface PdfToWorksheetJobData {
-  runJobId: string;
-  gcsUrl: string;
-  classId: string;
-}
-
-async function process(job: Job<PdfToWorksheetJobData>) {
-  const { runJobId, gcsUrl, classId } = job.data;
-
-  // If a previous attempt already succeeded for this RunJob (rare race after a
-  // crash that lost the BullMQ ack), return the prior result instead of
-  // re-running the AI call and creating a duplicate worksheet.
-  const existing = await prisma.runJob.findUnique({
-    where: { id: runJobId },
-    select: { status: true, result: true },
-  });
-  if (existing?.status === 'SUCCEEDED') {
-    logger.info('pdfToWorksheet RunJob already succeeded; skipping re-run', {
-      runJobId,
-      bullJobId: job.id,
-    });
-    return existing.result;
-  }
-
-  await prisma.runJob.update({
-    where: { id: runJobId },
-    data: {
-      status: 'RUNNING',
-      startedAt: existing?.status === 'RUNNING' ? undefined : new Date(),
-      attempts: { increment: 1 },
-    },
-  });
-
-  const worksheet = await pdfToWorksheet(gcsUrl, classId);
-
-  const result = worksheet ? { worksheetId: worksheet.id, name: worksheet.name } : null;
-
-  await prisma.runJob.update({
-    where: { id: runJobId },
-    data: {
-      status: 'SUCCEEDED',
-      finishedAt: new Date(),
-      error: null,
-      result: result === null ? Prisma.JsonNull : (result as Prisma.InputJsonValue),
-    },
-  });
-
-  return result;
-}
-
-export const pdfToWorksheetWorker = new Worker<PdfToWorksheetJobData>(
-  'pdfToWorksheet',
-  process,
-  {
-    connection: bullConnection,
-    // Conservative defaults — tune once we have real-world numbers.
+export const pdfToWorksheetWorker = createRunJobWorker({
+  type: 'PDF_TO_WORKSHEET',
+  workerOptions: {
     concurrency: 2,
-    limiter: {
-      max: 5,
-      duration: 60_000, // 5 jobs / minute, e.g. to stay under OpenAI rate limits
-    },
+    // 5 jobs / minute, e.g. to stay under OpenAI rate limits.
+    limiter: { max: 5, duration: 60_000 },
+  },
+  run: async ({ gcsUrl, classId, worksheetId }) => {
+    const worksheet = await pdfToWorksheet(gcsUrl, classId, { worksheetId });
+    return worksheet
+      ? { worksheetId: worksheet.id, name: worksheet.name }
+      : null;
   },
-);
-
-pdfToWorksheetWorker.on('error', (err) => {
-  logger.error('pdfToWorksheet worker error', {
-    error: err.message,
-    stack: err.stack,
-  });
-});
-
-pdfToWorksheetWorker.on('failed', async (job, err) => {
-  if (!job) return;
-
-  const runJobId = job.data?.runJobId;
-  const isFinalAttempt = job.attemptsMade >= (job.opts.attempts ?? 1);
-
-  logger.error('pdfToWorksheet job failed', {
-    bullJobId: job.id,
-    runJobId,
-    attempt: job.attemptsMade,
-    finalAttempt: isFinalAttempt,
-    error: err.message,
-  });
-
-  if (!runJobId) return;
-
-  // Always record the latest error message on the RunJob row.
-  // Only flip to FAILED on the final attempt — earlier failures are still
-  // "RUNNING" because BullMQ is going to retry.
-  await prisma.runJob.update({
-    where: { id: runJobId },
-    data: {
-      error: err.message,
-      ...(isFinalAttempt
-        ? { status: 'FAILED', finishedAt: new Date() }
-        : {}),
-    },
-  }).catch((updateError) => {
-    logger.error('Failed to record pdfToWorksheet failure on RunJob', {
-      runJobId,
-      error: updateError instanceof Error ? updateError.message : String(updateError),
-    });
-  });
-});
-
-pdfToWorksheetWorker.on('completed', (job) => {
-  logger.info('pdfToWorksheet job completed', {
-    bullJobId: job.id,
-    runJobId: job.data?.runJobId,
-  });
 });