@studious-lms/server 1.16.0 → 1.17.0

package/src/services/openaiDocumentGen.ts

@@ -6,12 +6,36 @@ import OpenAI from 'openai';
 import type { Response } from 'openai/resources/responses/responses.js';
 import { logger } from '../utils/logger.js';
 
-const DOCUMENT_GEN_MODEL = 'gpt-4o-mini';
+const DOCUMENT_GEN_MODEL = 'gpt-5.5';
 
+/**
+ * Extensions OpenAI Code Interpreter can read/write in its sandbox.
+ * @see https://developers.openai.com/api/docs/guides/tools-code-interpreter
+ */
 export const SUPPORTED_DOCUMENT_FORMATS = [
-  'pdf', 'docx', 'doc', 'xlsx', 'pptx', 'csv', 'md', 'html', 'txt', 'json',
-  'xml', 'tex', 'png', 'jpeg', 'jpg', 'gif', 'zip', 'tar', 'py', 'js', 'ts',
-  'css', 'sh',
+  'pdf',
+  'docx',
+  'doc',
+  'xlsx',
+  'pptx',
+  'csv',
+  'md',
+  'html',
+  'txt',
+  'json',
+  'xml',
+  'tex',
+  'png',
+  'jpeg',
+  'jpg',
+  'gif',
+  'zip',
+  'tar',
+  'py',
+  'js',
+  'ts',
+  'css',
+  'sh',
 ] as const;
 
 export type DocumentFormat = (typeof SUPPORTED_DOCUMENT_FORMATS)[number];
@@ -43,34 +67,75 @@ const FORMAT_MIME: Record<DocumentFormat, string> = {
 };
 
 const FORMAT_HINTS: Record<DocumentFormat, string> = {
-  pdf: 'fpdf2 or reportlab',
-  docx: 'python-docx',
-  doc: 'python-docx',
-  xlsx: 'openpyxl or pandas',
-  pptx: 'python-pptx',
-  csv: 'pandas or csv module',
-  md: 'write markdown directly',
-  html: 'write a complete HTML page',
-  txt: 'write plain text',
-  json: 'json.dumps with indentation',
-  xml: 'well-formed XML',
-  tex: 'LaTeX source',
-  png: 'matplotlib or Pillow',
-  jpeg: 'matplotlib or Pillow',
-  jpg: 'matplotlib or Pillow',
-  gif: 'matplotlib or Pillow',
-  zip: 'zipfile',
-  tar: 'tarfile',
-  py: 'Python source',
-  js: 'JavaScript source',
-  ts: 'TypeScript source',
-  css: 'CSS stylesheet',
-  sh: 'shell script',
+  pdf: 'fpdf2 or reportlab — polished document with headings, body text, and tables',
+  docx: 'python-docx — Word document with heading styles, paragraphs, and lists',
+  doc: 'python-docx saving as .doc if supported, otherwise .docx',
+  xlsx: 'openpyxl or pandas — spreadsheet with labelled columns, formulas where useful',
+  pptx: 'python-pptx — full slide deck: title slide, section slides, bullets, diagrams on slides',
+  csv: 'pandas or csv module — tabular data with headers',
+  md: 'write the markdown file directly',
+  html: 'write a complete, styled HTML page',
+  txt: 'write plain text with clear section breaks',
+  json: 'json.dumps with readable indentation',
+  xml: 'well-formed XML document',
+  tex: 'LaTeX source that compiles to the requested content',
+  png: 'matplotlib, networkx, or Pillow — render the described chart/diagram as a finished image',
+  jpeg: 'matplotlib or Pillow — high-quality visual saved as JPEG',
+  jpg: 'matplotlib or Pillow — high-quality visual saved as JPEG',
+  gif: 'matplotlib or Pillow — save as GIF',
+  zip: 'zipfile — bundle multiple related files if needed',
+  tar: 'tarfile — archive if multiple files are required',
+  py: 'valid, runnable Python source with comments',
+  js: 'valid JavaScript source with comments',
+  ts: 'valid TypeScript source with comments',
+  css: 'stylesheet file',
+  sh: 'shell script file',
+};
+
+/** Extra quality rules appended for formats that need more than a one-line library hint. */
+const FORMAT_QUALITY_RULES: Partial<Record<DocumentFormat, string[]>> = {
+  png: [
+    'Interpret the source content as a visual spec — draw it, do not dump text into the image.',
+    'Charts: labelled axes, legend, title, readable font sizes, 150+ DPI.',
+    'Diagrams/flowcharts: use matplotlib patches, networkx, or Pillow drawing — boxes, arrows, labels.',
+    'Geometry/maps: accurate relative positions; label every important part.',
+    'Use color meaningfully; avoid blank or placeholder images.',
+  ],
+  jpeg: [
+    'Same visual quality rules as PNG — polished chart or diagram, not a screenshot of text.',
+  ],
+  jpg: [
+    'Same visual quality rules as PNG — polished chart or diagram, not a screenshot of text.',
+  ],
+  gif: [
+    'Render a clear educational visual; static GIF is fine unless animation is described.',
+  ],
+  pptx: [
+    'Split slides on "---" lines or "Slide N:" / "# " headings in the source content.',
+    'Title slide first, then content slides with concise bullets (not walls of text).',
+    'If the content describes a diagram, draw it on a slide (shapes/arrows) or embed a generated chart.',
+    'Use distinct slide layouts where appropriate (title, title+content).',
+  ],
+  xlsx: [
+    'Parse markdown tables or tabular lists in the source into real rows/columns.',
+    'Bold header row; auto-fit column widths where possible.',
+  ],
+  pdf: [
+    'If the source describes a figure/chart, generate and embed it — do not leave a "[diagram]" placeholder.',
+  ],
+  docx: [
+    'Use Heading 1/2 styles for section titles; bullets and numbered lists for enumerations.',
+  ],
+  html: [
+    'Include embedded CSS for readable typography; use tables or simple layout for structured content.',
+  ],
 };
 
 export interface GenerateDocumentInput {
   title: string;
+  /** Markdown or plain-text source material for the output file. */
   content: string;
+  /** Output format. Defaults to pdf. */
   format?: DocumentFormat | string;
 }
 
@@ -87,7 +152,9 @@ export interface ContainerGeneratedFile {
   filename: string;
 }
 
-export function normalizeDocumentFormat(format?: string | null): DocumentFormat {
+export function normalizeDocumentFormat(
+  format?: string | null,
+): DocumentFormat {
   const raw = (format ?? 'pdf').toLowerCase().replace(/^\./, '');
   if ((SUPPORTED_DOCUMENT_FORMATS as readonly string[]).includes(raw)) {
     return raw as DocumentFormat;
@@ -99,13 +166,25 @@ export function mimeTypeForFormat(format: DocumentFormat): string {
   return FORMAT_MIME[format];
 }
 
+export function extensionForFormat(format: DocumentFormat): string {
+  return format === 'jpg' ? 'jpg' : format;
+}
+
+/** Pull generated-file citations for a given extension out of a Responses output. */
 export function extractContainerGeneratedFiles(
   response: Response,
   extension: DocumentFormat,
 ): ContainerGeneratedFile[] {
-  const suffix = `.${extension}`;
   const seen = new Set<string>();
   const files: ContainerGeneratedFile[] = [];
+  const suffix = `.${extension}`;
+
+  const add = (containerId: string, fileId: string, filename: string) => {
+    const key = `${containerId}:${fileId}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    files.push({ containerId, fileId, filename });
+  };
 
   for (const item of response.output ?? []) {
     if (item.type !== 'message') continue;
@@ -114,18 +193,13 @@ export function extractContainerGeneratedFiles(
       for (const ann of block.annotations ?? []) {
         if (ann.type !== 'container_file_citation') continue;
         const name = ann.filename?.toLowerCase() ?? '';
-        if (!name.endsWith(suffix)) continue;
-        const key = `${ann.container_id}:${ann.file_id}`;
-        if (seen.has(key)) continue;
-        seen.add(key);
-        files.push({
-          containerId: ann.container_id,
-          fileId: ann.file_id,
-          filename: ann.filename,
-        });
+        if (name.endsWith(suffix)) {
+          add(ann.container_id, ann.file_id, ann.filename);
+        }
       }
     }
   }
+
   return files;
 }
 
@@ -158,13 +232,50 @@ async function listContainerGeneratedFiles(
   return files;
 }
 
+async function downloadContainerFile(
+  client: OpenAI,
+  file: ContainerGeneratedFile,
+): Promise<Buffer | null> {
+  try {
+    const res = await client.containers.files.content.retrieve(file.fileId, {
+      container_id: file.containerId,
+    });
+    const bytes = await res.arrayBuffer();
+    return Buffer.from(bytes);
+  } catch (error) {
+    logger.error('Failed to download container file', { error, file });
+    return null;
+  }
+}
+
 function safeBasename(title: string): string {
-  return (
-    title
-      .replace(/[^a-zA-Z0-9\s\-_]/g, '')
-      .replace(/\s+/g, '_')
-      .substring(0, 60) || 'document'
-  );
+  const base = title
+    .replace(/[^a-zA-Z0-9\s\-_]/g, '')
+    .replace(/\s+/g, '_')
+    .substring(0, 60);
+  return base || 'document';
+}
+
+function buildDocumentGenInstructions(format: DocumentFormat): string {
+  const qualityRules = FORMAT_QUALITY_RULES[format] ?? [];
+  return [
+    'You are a document generator for K-12 and university teachers.',
+    'When given a title, output format, and source content:',
+    '1. Use the python tool to create exactly ONE output file of the requested type.',
+    `2. For this format use: ${FORMAT_HINTS[format]}.`,
+    `3. You MUST output a ${format.toUpperCase()} file — not any other format.`,
+    `4. The saved filename MUST end with .${extensionForFormat(format)}.`,
+    '5. Faithfully adapt ALL source content to the output medium — do not summarize away detail.',
+    '6. Include the document title prominently where the format allows.',
+    '7. Put ONLY the educational content in the file — no meta commentary.',
+    '8. You MUST save the file to disk in the working directory before you finish.',
+    ...(format !== 'pdf'
+      ? [`9. Do NOT create a PDF when ${format.toUpperCase()} was requested.`]
+      : []),
+    ...(qualityRules.length > 0
+      ? ['', 'Format-specific quality:', ...qualityRules.map((r, i) => `${i + 1}. ${r}`)]
+      : []),
+  ].join('\n');
 }
 
 /** Generate a file via OpenAI Code Interpreter. */
@@ -173,33 +284,31 @@ export async function generateDocumentWithOpenAI(
 ): Promise<GeneratedDocumentResult | null> {
   const client = new OpenAI();
   const format = normalizeDocumentFormat(input.format);
-  const ext = format === 'jpg' ? 'jpg' : format;
+  const ext = extensionForFormat(format);
   const filename = `${safeBasename(input.title)}.${ext}`;
 
   try {
     const response = await client.responses.create({
       model: DOCUMENT_GEN_MODEL,
-      instructions: [
-        'You generate classroom-ready files for teachers using the python tool.',
-        `You MUST output a ${ext.toUpperCase()} file — not any other format.`,
-        `Use: ${FORMAT_HINTS[format]}.`,
-        `The saved filename MUST end with .${ext}.`,
-        'Save exactly one output file with the requested filename.',
-        'Include only educational content — no chat commentary.',
-        ...(format !== 'pdf' ? [`Do NOT create a PDF when ${ext.toUpperCase()} was requested.`] : []),
-      ].join(' '),
-      tools: [{ type: 'code_interpreter', container: { type: 'auto' } }],
+      instructions: buildDocumentGenInstructions(format),
+      tools: [
+        {
+          type: 'code_interpreter',
+          container: { type: 'auto' },
+        },
+      ],
       tool_choice: 'required',
       input: [
-        `Create a ${ext.toUpperCase()} file.`,
-        `Filename (exact): ${filename}`,
-        `Title: ${input.title}`,
-        'Content:',
-        input.content,
+        `Create a ${ext.toUpperCase()} file using the python tool.`,
+        `Output filename (exact): ${filename}`,
+        `Output format: ${ext}`,
+        `Document title: ${input.title}`,
+        ['Source content — adapt fully to the output medium (do not paste raw markdown into slides/images):', input.content].join('\n'),
       ].join('\n\n'),
     });
 
     let matches = extractContainerGeneratedFiles(response, format);
+
     if (matches.length === 0) {
       const containerId = containerIdFromResponse(response);
       if (containerId) {
@@ -208,9 +317,10 @@ export async function generateDocumentWithOpenAI(
     }
 
     if (matches.length === 0) {
-      logger.error('OpenAI document gen: no output file', {
+      logger.error('OpenAI document gen produced no matching files', {
         title: input.title,
         format,
+        outputTypes: (response.output ?? []).map((o) => o.type),
       });
       return null;
     }
@@ -219,10 +329,8 @@ export async function generateDocumentWithOpenAI(
       matches.find((f) => f.filename.toLowerCase() === filename.toLowerCase()) ??
       matches[0];
 
-    const res = await client.containers.files.content.retrieve(preferred.fileId, {
-      container_id: preferred.containerId,
-    });
-    const bytes = Buffer.from(await res.arrayBuffer());
+    const bytes = await downloadContainerFile(client, preferred);
+    if (!bytes) return null;
 
     return {
       bytes,
@@ -231,7 +339,23 @@ export async function generateDocumentWithOpenAI(
       format,
     };
   } catch (error) {
-    logger.error('OpenAI document generation failed', { error, title: input.title, format });
+    logger.error('OpenAI document generation failed', {
+      error,
+      title: input.title,
+      format,
+    });
     return null;
   }
 }
+
+/** @deprecated Use {@link generateDocumentWithOpenAI} */
+export async function generatePdfWithOpenAI(
+  input: Omit<GenerateDocumentInput, 'format'>,
+): Promise<Buffer | null> {
+  const result = await generateDocumentWithOpenAI({ ...input, format: 'pdf' });
+  return result?.bytes ?? null;
+}
+
+/** @deprecated Use {@link extractContainerGeneratedFiles} */
+export const extractContainerPdfFiles = (response: Response) =>
+  extractContainerGeneratedFiles(response, 'pdf');

package/src/services/school.ts

@@ -540,6 +540,237 @@ export async function getStudentTimeline(
   };
 }
 
+/**
+ * Role-aware overview used by `/view/[userId]`.
+ *
+ * - For STUDENT members it returns the same timeline as `getStudentTimeline`
+ *   (events, assignments, attendance) so teachers/admins can audit progress.
+ * - For TEACHER/ADMIN members it returns their teaching agenda: every event in
+ *   a class they teach plus their personal events, alongside the classes they
+ *   run with enrolment counts.
+ *
+ * Permissions:
+ * - School admins can view anyone in the institution.
+ * - A teacher can view a STUDENT they share a class with.
+ * - A teacher/admin can always view their own overview.
+ */
+export async function getMemberTimeline(
+  userId: string,
+  input: {
+    schoolId: string;
+    memberId: string;
+    from?: Date;
+    to?: Date;
+  }
+) {
+  const callerIsAdmin = Boolean(
+    await findActiveSchoolAdminMembership(input.schoolId, userId)
+  );
+
+  const membership = await prisma.schoolMembership.findFirst({
+    where: {
+      schoolId: input.schoolId,
+      userId: input.memberId,
+      status: "ACTIVE",
+    },
+    select: {
+      role: true,
+      user: {
+        select: {
+          id: true,
+          username: true,
+          profile: { select: { displayName: true, profilePicture: true } },
+        },
+      },
+    },
+  });
+  if (!membership) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "This person is not in this institution",
+    });
+  }
+
+  const range = {
+    ...(input.from ? { gte: input.from } : {}),
+    ...(input.to ? { lte: input.to } : {}),
+  };
+  const hasRange = Object.keys(range).length > 0;
+
+  if (membership.role === "STUDENT") {
+    if (!callerIsAdmin) {
+      const sharedClass = await prisma.class.findFirst({
+        where: {
+          schoolId: input.schoolId,
+          teachers: { some: { id: userId } },
+          students: { some: { id: input.memberId } },
+        },
+        select: { id: true },
+      });
+      if (!sharedClass) {
+        throw new TRPCError({
+          code: "FORBIDDEN",
+          message: "You don't share a class with this student",
+        });
+      }
+    }
+
+    const [events, assignments, attendance] = await Promise.all([
+      prisma.event.findMany({
+        where: {
+          userId: input.memberId,
+          ...(hasRange ? { startTime: range } : {}),
+        },
+        select: {
+          id: true,
+          name: true,
+          startTime: true,
+          endTime: true,
+          location: true,
+          remarks: true,
+          color: true,
+          class: { select: { id: true, name: true, color: true } },
+        },
+        orderBy: { startTime: "asc" },
+      }),
+      prisma.assignment.findMany({
+        where: {
+          class: { students: { some: { id: input.memberId } } },
+          template: false,
+          ...(hasRange ? { dueDate: range } : {}),
+        },
+        select: {
+          id: true,
+          title: true,
+          dueDate: true,
+          type: true,
+          graded: true,
+          maxGrade: true,
+          weight: true,
+          class: {
+            select: {
+              id: true,
+              name: true,
+              section: true,
+              subject: true,
+              color: true,
+            },
+          },
+          submissions: {
+            where: { studentId: input.memberId },
+            select: {
+              id: true,
+              submitted: true,
+              submittedAt: true,
+              returned: true,
+              gradeReceived: true,
+            },
+          },
+        },
+        orderBy: { dueDate: "asc" },
+      }),
+      prisma.attendance.findMany({
+        where: {
+          OR: [
+            { present: { some: { id: input.memberId } } },
+            { late: { some: { id: input.memberId } } },
+            { absent: { some: { id: input.memberId } } },
+          ],
+          ...(hasRange ? { date: range } : {}),
+        },
+        select: {
+          id: true,
+          date: true,
+          class: { select: { id: true, name: true, color: true } },
+          present: { where: { id: input.memberId }, select: { id: true } },
+          late: { where: { id: input.memberId }, select: { id: true } },
+          absent: { where: { id: input.memberId }, select: { id: true } },
+        },
+        orderBy: { date: "asc" },
+      }),
+    ]);
+
+    const attendanceShaped = attendance.map((record) => ({
+      id: record.id,
+      date: record.date,
+      class: record.class,
+      status: record.present.length
+        ? ("PRESENT" as const)
+        : record.late.length
+          ? ("LATE" as const)
+          : ("ABSENT" as const),
+    }));
+
+    return {
+      role: "STUDENT" as const,
+      member: membership.user,
+      events,
+      assignments,
+      attendance: attendanceShaped,
+    };
+  }
+
+  // TEACHER or ADMIN: only admins (or the member themselves) may view.
+  if (!callerIsAdmin && userId !== input.memberId) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only school admins can view this member",
+    });
+  }
+
+  const [events, classes] = await Promise.all([
+    prisma.event.findMany({
+      where: {
+        OR: [
+          { userId: input.memberId },
+          { class: { teachers: { some: { id: input.memberId } } } },
+        ],
+        ...(hasRange ? { startTime: range } : {}),
+      },
+      select: {
+        id: true,
+        name: true,
+        startTime: true,
+        endTime: true,
+        location: true,
+        remarks: true,
+        color: true,
+        class: { select: { id: true, name: true, color: true } },
+      },
+      orderBy: { startTime: "asc" },
+    }),
+    prisma.class.findMany({
+      where: {
+        schoolId: input.schoolId,
+        teachers: { some: { id: input.memberId } },
+      },
+      select: {
+        id: true,
+        name: true,
+        section: true,
+        subject: true,
+        color: true,
+        _count: { select: { students: true } },
+      },
+      orderBy: { name: "asc" },
+    }),
+  ]);
+
+  return {
+    role: membership.role as "TEACHER" | "ADMIN",
+    member: membership.user,
+    events,
+    classes: classes.map((c) => ({
+      id: c.id,
+      name: c.name,
+      section: c.section,
+      subject: c.subject,
+      color: c.color,
+      studentCount: c._count.students,
+    })),
+  };
+}
+
 export async function createInvite(
   userId: string,
   input: {