@studious-lms/server 1.4.3 → 1.4.4

package/src/routers/worksheet.ts

@@ -1,4 +1,10 @@
 import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.js";
+import {
+  confirmDirectUpload,
+  createDirectUploadFiles,
+  updateUploadProgress,
+} from "../lib/fileUpload.js";
 import {
   createTRPCRouter,
   protectedClassMemberProcedure,
@@ -13,6 +19,8 @@ import {
   updateWorksheetRecord,
   deleteWorksheetRecord,
   createWorksheetRecord,
+  createWorksheetFromPdf,
+  createWorksheetFromUploadedPdf,
   addQuestionToWorksheet,
   reorderWorksheetQuestions,
   updateWorksheetQuestionRecord,
@@ -25,6 +33,40 @@ import {
   addCommentToResponse,
 } from "../services/worksheet.js";
 
+const directFileSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+  size: z.number(),
+});
+
+const pdfFileSchema = directFileSchema.superRefine((file, ctx) => {
+  const isPdf =
+    file.type === "application/pdf" && file.name.toLowerCase().endsWith(".pdf");
+  if (!isPdf) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Only PDF files are supported",
+    });
+  }
+});
+
+const getWorksheetUploadUrlsSchema = z.object({
+  classId: z.string(),
+  files: z.array(pdfFileSchema),
+});
+
+const confirmWorksheetUploadSchema = z.object({
+  classId: z.string(),
+  fileId: z.string(),
+  uploadSuccess: z.boolean(),
+  errorMessage: z.string().optional(),
+});
+
+const updateUploadProgressSchema = z.object({
+  fileId: z.string(),
+  progress: z.number().min(0).max(100),
+});
+
 export const worksheetRouter = createTRPCRouter({
   getWorksheet: protectedProcedure
     .input(z.object({ worksheetId: z.string() }))
@@ -66,6 +108,75 @@ export const worksheetRouter = createTRPCRouter({
       createWorksheetRecord(input.classId, input.name)
     ),
 
+  createFromPdf: protectedTeacherProcedure
+    .input(z.object({ classId: z.string(), url: z.string().url() }))
+    .mutation(({ input }) => createWorksheetFromPdf(input.classId, input.url)),
+
+  getWorksheetUploadUrls: protectedTeacherProcedure
+    .input(getWorksheetUploadUrlsSchema)
+    .mutation(async ({ ctx, input }) => {
+      if (!ctx.user) {
+        throw new TRPCError({
+          code: "UNAUTHORIZED",
+          message: "You must be logged in to upload files",
+        });
+      }
+
+      const uploadFiles = await createDirectUploadFiles(
+        input.files,
+        ctx.user.id
+      );
+
+      return {
+        success: true,
+        uploadFiles,
+      };
+    }),
+
+  confirmWorksheetUpload: protectedTeacherProcedure
+    .input(confirmWorksheetUploadSchema)
+    .mutation(async ({ ctx, input }) => {
+      if (!ctx.user) {
+        throw new TRPCError({
+          code: "UNAUTHORIZED",
+          message: "You must be logged in",
+        });
+      }
+
+      const file = await prisma.file.findFirst({
+        where: {
+          id: input.fileId,
+          userId: ctx.user.id,
+        },
+      });
+
+      if (!file) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "File not found or you don't have permission",
+        });
+      }
+
+      await confirmDirectUpload(
+        input.fileId,
+        input.uploadSuccess,
+        input.errorMessage
+      );
+
+      return {
+        success: true,
+        message: input.uploadSuccess
+          ? "Upload confirmed successfully"
+          : "Upload failed",
+      };
+    }),
+
+  createFromUploadedPdf: protectedTeacherProcedure
+    .input(z.object({ classId: z.string(), fileId: z.string() }))
+    .mutation(({ ctx, input }) =>
+      createWorksheetFromUploadedPdf(input.classId, input.fileId, ctx.user!.id)
+    ),
+
   addQuestion: protectedProcedure
     .input(
       z.object({
@@ -261,4 +372,36 @@ export const worksheetRouter = createTRPCRouter({
         ctx.user!.id
       )
     ),
+
+  updateUploadProgress: protectedProcedure
+    .input(updateUploadProgressSchema)
+    .mutation(async ({ ctx, input }) => {
+      if (!ctx.user) {
+        throw new TRPCError({
+          code: "UNAUTHORIZED",
+          message: "You must be logged in",
+        });
+      }
+
+      const file = await prisma.file.findFirst({
+        where: {
+          id: input.fileId,
+          userId: ctx.user.id,
+        },
+      });
+
+      if (!file) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "File not found or you don't have permission",
+        });
+      }
+
+      await updateUploadProgress(input.fileId, input.progress);
+
+      return {
+        success: true,
+        progress: input.progress,
+      };
+    }),
 });

package/src/services/worksheet.ts

@@ -5,7 +5,9 @@
 import { TRPCError } from "@trpc/server";
 import { GenerationStatus, type WorksheetQuestionType } from "@prisma/client";
 import { prisma } from "../lib/prisma.js";
+import { getFileUrl } from "../lib/fileUpload.js";
 import { cancelGradePipeline, regradeWorksheetPipeline } from "../pipelines/gradeWorksheet.js";
+import { pdfToWorksheet } from "../pipelines/pdfToWorksheet.js";
 import {
   findWorksheetByIdMinimal,
   findWorksheetByIdForClassMember,
@@ -121,6 +123,65 @@ export async function createWorksheetRecord(classId: string, name: string) {
   return createWorksheet({ classId, name });
 }
 
+/**
+ * Create a worksheet by converting a PDF (URL) into structured questions.
+ * Uses the `pdfToWorksheet` pipeline to do inference + persistence.
+ */
+export async function createWorksheetFromPdf(
+  classId: string,
+  url: string
+) {
+  const created = await pdfToWorksheet(url, classId);
+  if (!created) {
+    throw new TRPCError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Failed to create worksheet from PDF",
+    });
+  }
+  return created;
+}
+
+/**
+ * Create a worksheet from a PDF that was uploaded through the direct-upload flow.
+ */
+export async function createWorksheetFromUploadedPdf(
+  classId: string,
+  fileId: string,
+  userId: string
+) {
+  const file = await prisma.file.findFirst({
+    where: {
+      id: fileId,
+      userId,
+      uploadStatus: "COMPLETED",
+    },
+    select: {
+      id: true,
+      path: true,
+      type: true,
+    },
+  });
+
+  if (!file) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Uploaded file not found or not ready",
+    });
+  }
+
+  const isPdf =
+    file.type === "application/pdf" || file.path.toLowerCase().endsWith(".pdf");
+  if (!isPdf) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Only PDF files can be converted into worksheets",
+    });
+  }
+
+  const signedUrl = await getFileUrl(file.path);
+  return createWorksheetFromPdf(classId, signedUrl);
+}
+
 export async function addQuestionToWorksheet(
   worksheetId: string,
   userId: string,

package/src/utils/inference.ts

@@ -2,6 +2,7 @@
  * Inference util – OpenAI client, inference() for structured output, sendAIMessage for chat.
  */
 import OpenAI from 'openai';
+import type { ResponseInput } from "openai/resources/responses/responses.js";
 import { logger } from './logger.js';
 import { prisma } from '../lib/prisma.js';
 import { chatChannel, pusher } from '../lib/pusher.js';
@@ -275,25 +276,93 @@ export async function sendAIMessage(
   };
 }
 
+/** Responses API user parts use `type: "input_*"`; chat completions use `text` / `image_url` / etc. */
+function isResponseInputWithInputParts(
+  content: OpenAI.Chat.Completions.ChatCompletionMessageParam[] | ResponseInput
+): content is ResponseInput {
+  if (!Array.isArray(content)) return false;
+  for (const msg of content) {
+    if (!msg || typeof msg !== "object" || !("content" in msg)) continue;
+    const parts = (msg as { content?: unknown }).content;
+    if (!Array.isArray(parts)) continue;
+    for (const part of parts) {
+      if (
+        part &&
+        typeof part === "object" &&
+        "type" in part &&
+        typeof (part as { type: string }).type === "string" &&
+        (part as { type: string }).type.startsWith("input_")
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function buildResponsesParseInput(
+  content: string | OpenAI.Chat.Completions.ChatCompletionMessageParam[] | ResponseInput
+): ResponseInput {
+  if (typeof content === "string") {
+    return [{ role: "user", content: [{ type: "input_text", text: content }] }];
+  }
+  if (isResponseInputWithInputParts(content)) {
+    return content;
+  }
+  return content as unknown as ResponseInput;
+}
+
 export async function inference<T>(
-  content: string | OpenAI.Chat.Completions.ChatCompletionMessageParam[],
+  content:
+    | string
+    | OpenAI.Chat.Completions.ChatCompletionMessageParam[]
+    | ResponseInput,
   format?: ZodSchema,
   options?: InferenceOptions,
 ): Promise<T> {
-  const input = normalizeInferenceInput(content);
   const reason = getInferenceReason(options);
   const model = options?.model ?? DEFAULT_INFERENCE_MODEL;
-  const estimatedInputTokens = input.reduce(
-    (total, message) => total + estimateTokenCount(message.content),
-    0,
-  );
+  const estimatedInputTokens =
+    typeof content === 'string'
+      ? estimateTokenCount(content)
+      : isResponseInputWithInputParts(content)
+        ? estimateTokenCount(
+            content
+              .flatMap((item) =>
+                typeof (item as any)?.content === 'string'
+                  ? [(item as any).content]
+                  : Array.isArray((item as any)?.content)
+                    ? (item as any).content
+                        .filter((p: any) => p?.type === 'input_text')
+                        .map((p: any) => p?.text ?? '')
+                    : [],
+              )
+              .join('\n'),
+          )
+        : (content as OpenAI.Chat.Completions.ChatCompletionMessageParam[]).reduce(
+            (total, message) =>
+              total +
+              estimateTokenCount(
+                typeof message.content === 'string' ? message.content : '',
+              ),
+            0,
+          );
   const operation = format ? 'responses.parse' : 'chat.completions';
 
   try {
     if (!format) {
+      if (typeof content !== 'string' && isResponseInputWithInputParts(content)) {
+        throw new Error(
+          'normalizeInferenceInput cannot handle ResponseInput content with input_* parts when format is undefined; pass a format to use responses.parse.',
+        );
+      }
+
+      const messages = normalizeInferenceInput(
+        content as string | OpenAI.Chat.Completions.ChatCompletionMessageParam[],
+      );
       const completion = await openAIClient.chat.completions.create({
         model,
-        messages: input,
+        messages,
         ...(options?.temperature !== undefined
           ? { temperature: options.temperature }
           : {}),
@@ -315,6 +384,7 @@ export async function inference<T>(
       return completion.choices[0]?.message?.content as T;
     }
 
+    const input = buildResponsesParseInput(content);
     const completion = await openAIClient.responses.parse({
       model,
       input,

package/tests/pipelines/pdfToWorksheet.test.ts

@@ -0,0 +1,176 @@
+/**
+ * `pdfToWorksheet` integration-style tests: real DB, mocked inference.
+ * CI does not call the model, and the PDF URL is passed through directly.
+ */
+import { describe, test, expect, vi, beforeAll, beforeEach, afterEach } from "vitest";
+import { user1Caller } from "../setup";
+import { prisma } from "../../src/lib/prisma";
+import { logger } from "../../src/utils/logger";
+
+vi.mock("../../src/utils/inference.js", () => ({
+  inference: vi.fn(),
+}));
+
+import { inference } from "../../src/utils/inference.js";
+import { pdfToWorksheet } from "../../src/pipelines/pdfToWorksheet.js";
+
+/** Same PDF path represented as a signed Google Cloud Storage URL. */
+export const CONV_TEST_PDF_GCS_URL =
+  "https://storage.googleapis.com/studious-test-bucket/worksheets/conv-test.pdf?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Signature=test-signature";
+
+export const NON_GCS_PDF_URL =
+  "https://drive.google.com/file/d/1BfotteM60Ax0krHzE6rFN1Df8S8kT3kb/view?usp=drive_link";
+
+/** Mirrors the 8-question conv-test worksheet shape the model is expected to return. */
+function draftWithEightQuestions(title = "Conv test worksheet") {
+  const types = [
+    "SHORT_ANSWER",
+    "MULTIPLE_CHOICE",
+    "TRUE_FALSE",
+    "SHORT_ANSWER",
+    "LONG_ANSWER",
+    "MATH_EXPRESSION",
+    "ESSAY",
+    "SHORT_ANSWER",
+  ] as const;
+
+  return {
+    title,
+    questions: types.map((type, i) => ({
+      type,
+      question: `Question ${i + 1}`,
+      answer: `Answer ${i + 1}`,
+      options:
+        type === "MULTIPLE_CHOICE"
+          ? [
+              { id: "a", text: "Wrong", isCorrect: false },
+              { id: "b", text: "Right", isCorrect: true },
+            ]
+          : [],
+      markScheme: [] as { id: string; points: number; description: string }[],
+      points: i + 1,
+      order: i + 1,
+    })),
+  };
+}
+
+describe("pdfToWorksheet", () => {
+  let classId: string;
+  const createdWorksheetIds: string[] = [];
+
+  beforeAll(async () => {
+    const cls = await user1Caller.class.create({
+      name: "pdfToWorksheet pipeline class",
+      subject: "Science",
+      section: "Test",
+    });
+    classId = cls.id;
+  });
+
+  beforeEach(() => {
+    vi.mocked(inference).mockReset();
+  });
+
+  afterEach(async () => {
+    for (const id of createdWorksheetIds.splice(0)) {
+      await prisma.worksheet.delete({ where: { id } }).catch(() => undefined);
+    }
+  });
+
+  test("passes the PDF URL directly to inference and persists a worksheet with 8 questions", async () => {
+    const draft = draftWithEightQuestions();
+    vi.mocked(inference).mockResolvedValue(draft);
+
+    const worksheet = await pdfToWorksheet(CONV_TEST_PDF_GCS_URL, classId);
+    expect(worksheet).not.toBeNull();
+    createdWorksheetIds.push(worksheet!.id);
+
+    expect(worksheet!.name).toBe(draft.title);
+    expect(worksheet!.classId).toBe(classId);
+
+    const questions = await prisma.worksheetQuestion.findMany({
+      where: { worksheetId: worksheet!.id },
+      orderBy: { order: "asc" },
+    });
+    expect(questions).toHaveLength(8);
+    expect(questions.map((q) => q.question)).toEqual(
+      draft.questions.map((q) => q.question)
+    );
+    expect(questions.map((q) => q.order)).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+    expect(questions.map((q) => q.points)).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+
+    expect(inference).toHaveBeenCalledTimes(1);
+    const input = vi.mocked(inference).mock.calls[0][0];
+    expect(Array.isArray(input)).toBe(true);
+    type InputPart = { type?: string; file_url?: string; text?: string };
+    const content = (input as { role: string; content: InputPart[] }[])[0].content;
+    const filePart = content.find((p) => p.type === "input_file");
+    expect(filePart).toEqual({
+      type: "input_file",
+      file_url: CONV_TEST_PDF_GCS_URL,
+    });
+    expect(vi.mocked(inference)).toHaveBeenCalledWith(
+      expect.any(Array),
+      expect.anything(),
+      expect.objectContaining({
+        reason: "pdf_to_worksheet_draft",
+        metadata: expect.objectContaining({
+          classId,
+          filename: "conv-test.pdf",
+        }),
+      })
+    );
+  });
+
+  test("rejects non-Google Cloud URLs and only logs a sanitized path", async () => {
+    const warnSpy = vi.spyOn(logger, "warn").mockImplementation(() => undefined);
+
+    await expect(pdfToWorksheet(NON_GCS_PDF_URL, classId)).rejects.toThrow(
+      "Only Google Cloud Storage URLs are supported"
+    );
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      "pdfToWorksheet: rejected unsupported PDF URL",
+      { sanitizedUrl: "https://drive.google.com/file/d/1BfotteM60Ax0krHzE6rFN1Df8S8kT3kb/view" }
+    );
+    expect(inference).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  test("rounds persisted integer fields from model output", async () => {
+    vi.mocked(inference).mockResolvedValue({
+      title: "Rounded worksheet",
+      questions: [{
+        type: "SHORT_ANSWER",
+        question: "Rounded question",
+        answer: "Rounded answer",
+        options: [],
+        markScheme: [{ id: "step-1", points: 0.6, description: "Half step" }],
+        points: 1.7,
+        order: 1.2,
+      }],
+    } as Awaited<ReturnType<typeof inference>>);
+
+    const worksheet = await pdfToWorksheet(CONV_TEST_PDF_GCS_URL, classId);
+    expect(worksheet).not.toBeNull();
+    createdWorksheetIds.push(worksheet!.id);
+
+    const [question] = await prisma.worksheetQuestion.findMany({
+      where: { worksheetId: worksheet!.id },
+    });
+
+    expect(question.points).toBe(2);
+    expect(question.order).toBe(1);
+    expect(question.markScheme).toEqual([{ id: "step-1", points: 1, description: "Half step" }]);
+  });
+
+  test("returns null when inference yields no parsed output", async () => {
+    vi.mocked(inference).mockResolvedValue(
+      null as unknown as Awaited<ReturnType<typeof inference>>
+    );
+
+    const out = await pdfToWorksheet(CONV_TEST_PDF_GCS_URL, classId);
+    expect(out).toBeNull();
+  });
+
+});

package/tests/utils/inference.test.ts

@@ -186,6 +186,43 @@ describe('inference', () => {
         metadata: { worksheetResponseId: 'response-1' },
       }),
     });
+    expect(responseParseMock).toHaveBeenCalledWith({
+      model: 'gpt-5-nano',
+      input: [{
+        role: 'user',
+        content: [{ type: 'input_text', text: 'Grade this' }],
+      }],
+      text: {
+        format: expect.any(Object),
+      },
+    });
+  });
+
+  test('rejects ResponseInput content with input parts when format is missing', async () => {
+    await expect(
+      inference<string>([
+        {
+          role: 'user',
+          content: [
+            { type: 'input_text', text: 'Read this PDF' },
+            { type: 'input_file', file_url: 'https://storage.googleapis.com/bucket/file.pdf' },
+          ],
+        },
+      ] as any, undefined, {
+        reason: 'pdf_without_format',
+      }),
+    ).rejects.toThrow(
+      'normalizeInferenceInput cannot handle ResponseInput content with input_* parts when format is undefined; pass a format to use responses.parse.',
+    );
+
+    expect(chatCreateMock).not.toHaveBeenCalled();
+    expect(prismaMocks.aiUsageLog.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        reason: 'pdf_without_format',
+        operation: 'chat.completions',
+        success: false,
+      }),
+    });
   });
 
   test('logs failed attempts before rethrowing', async () => {