@studious-lms/server 1.13.0 → 1.15.0

package/src/services/aiStream.ts

@@ -0,0 +1,175 @@
+/**
+ * AI Streaming service – handles streamed AI responses with tool calls.
+ * Uses Vercel AI SDK for streaming and Redis for temporary chunk caching.
+ */
+import { streamText, stepCountIs, type ModelMessage } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { getRedis } from '../lib/redis.js';
+import { prisma } from '../lib/prisma.js';
+import { pusher, chatChannel } from '../lib/pusher.js';
+import { getAIUserId, ensureAIUserExists } from '../utils/aiUser.js';
+import { logger } from '../utils/logger.js';
+import { JobStatus } from '@prisma/client';
+import { aiTools, type ToolCallResult } from './aiTools.js';
+
+const STREAM_REDIS_TTL = 600; // 10 minutes TTL for stream keys
+const STREAM_KEY_PREFIX = 'stream:';
+
+export interface StreamOptions {
+  conversationId: string;
+  aiMessageId: string;
+  messages: ModelMessage[];
+  systemPrompt: string;
+  classId?: string;
+  enableTools?: boolean;
+  model?: string;
+  temperature?: number;
+  maxOutputTokens?: number;
+}
+
+/**
+ * Stream an AI response, broadcasting chunks via Pusher and caching in Redis.
+ * On completion, persists the full response to the database.
+ */
+export async function streamAIResponse(options: StreamOptions): Promise<void> {
+  const {
+    conversationId,
+    aiMessageId,
+    messages,
+    systemPrompt,
+    classId,
+    enableTools = true,
+    model = 'gpt-4o-mini',
+    temperature = 0.7,
+    maxOutputTokens = 4096,
+  } = options;
+
+  await ensureAIUserExists();
+
+  const redis = getRedis();
+  const streamKey = `${STREAM_KEY_PREFIX}${aiMessageId}`;
+
+  // Initialize Redis stream cache
+  if (redis) {
+    await redis.set(streamKey, '', 'EX', STREAM_REDIS_TTL);
+  }
+
+  let fullContent = '';
+  const toolCallResults: ToolCallResult[] = [];
+
+  try {
+    const toolSet = enableTools && classId ? aiTools(classId) : undefined;
+
+    const result = streamText({
+      model: openai(model),
+      system: systemPrompt,
+      messages,
+      tools: toolSet,
+      temperature,
+      maxOutputTokens,
+      stopWhen: stepCountIs(5),
+      onStepFinish: async ({ toolCalls, toolResults }) => {
+        if (toolCalls && toolCalls.length > 0) {
+          for (const tc of toolCalls) {
+            try {
+              await pusher.trigger(chatChannel(conversationId), 'message-tool-call', {
+                messageId: aiMessageId,
+                toolName: tc.toolName,
+                status: 'executing',
+              });
+            } catch (err) {
+              logger.error('Failed to broadcast tool call event', { err, aiMessageId });
+            }
+          }
+        }
+
+        if (toolResults) {
+          for (const tr of toolResults) {
+            toolCallResults.push({
+              toolName: tr.toolName,
+              result: tr.output,
+            });
+          }
+        }
+      },
+    });
+
+    // Stream text chunks to client
+    for await (const chunk of result.textStream) {
+      fullContent += chunk;
+
+      // Cache in Redis
+      if (redis) {
+        await redis.append(streamKey, chunk);
+      }
+
+      // Broadcast chunk to client via Pusher
+      try {
+        await pusher.trigger(chatChannel(conversationId), 'message-stream-chunk', {
+          messageId: aiMessageId,
+          chunk,
+          accumulated: fullContent.length,
+        });
+      } catch (err) {
+        logger.warn('Failed to broadcast stream chunk', { err, aiMessageId });
+      }
+    }
+
+    // Stream complete — persist to DB
+    const meta = toolCallResults.length > 0
+      ? JSON.stringify({ toolCalls: toolCallResults })
+      : undefined;
+
+    await prisma.message.update({
+      where: { id: aiMessageId },
+      data: {
+        content: fullContent,
+        status: JobStatus.COMPLETED,
+        ...(meta ? { meta: JSON.parse(meta) } : {}),
+      },
+    });
+
+    // Broadcast final message-updated event
+    await pusher.trigger(chatChannel(conversationId), 'message-updated', {
+      id: aiMessageId,
+      content: fullContent,
+      senderId: getAIUserId(),
+      conversationId,
+      status: JobStatus.COMPLETED,
+      sender: {
+        id: getAIUserId(),
+        username: 'Newton_AI',
+        profile: { displayName: 'Newton AI', profilePicture: null },
+      },
+      mentionedUserIds: [],
+      meta: meta ? JSON.parse(meta) : {},
+      attachments: [],
+    });
+
+    logger.info('AI stream completed', {
+      aiMessageId,
+      conversationId,
+      contentLength: fullContent.length,
+      toolCalls: toolCallResults.length,
+    });
+  } catch (error) {
+    logger.error('AI stream failed', { error, aiMessageId, conversationId });
+
+    await prisma.message.update({
+      where: { id: aiMessageId },
+      data: { status: JobStatus.FAILED },
+    });
+
+    await pusher.trigger(chatChannel(conversationId), 'message-updated', {
+      id: aiMessageId,
+      conversationId,
+      status: JobStatus.FAILED,
+    });
+
+    throw error;
+  } finally {
+    if (redis) {
+      await redis.del(streamKey);
+    }
+  }
+}

package/src/services/aiTools.ts

@@ -0,0 +1,290 @@
+/**
+ * AI Tool definitions and execution for agent tool calls.
+ * Provides RAG search, assignment lookup, worksheet creation, student progress,
+ * and web search tools.
+ */
+import { jsonSchema, type ToolSet } from 'ai';
+import OpenAI from 'openai';
+import { searchEmbeddings } from './embedding.js';
+import { prisma } from '../lib/prisma.js';
+import { logger } from '../utils/logger.js';
+
+export interface ToolCallResult {
+  toolName: string;
+  result: unknown;
+}
+
+/**
+ * Build the tool set for a given class context.
+ * Tools are scoped to a specific class for security.
+ */
+export function aiTools(classId: string): ToolSet {
+  return {
+    search_materials: {
+      description: 'Search class materials, files, assignments, worksheets, and announcements using semantic similarity. Use this to find relevant context for answering questions.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'The search query to find relevant materials' },
+          limit: { type: 'number', description: 'Maximum results (1-10)', default: 5 },
+        },
+        required: ['query'],
+      }),
+      execute: async ({ query, limit = 5 }: { query: string; limit?: number }) => {
+        try {
+          const results = await searchEmbeddings({ classId, query, limit });
+          return results.map((r) => ({
+            sourceType: r.sourceType,
+            sourceId: r.sourceId,
+            content: r.content.slice(0, 500),
+            similarity: Math.round(r.similarity * 100) / 100,
+            metadata: r.metadata,
+          }));
+        } catch (error) {
+          logger.error('search_materials tool failed', { error, classId, query });
+          return [];
+        }
+      },
+    },
+
+    search_assignments: {
+      description: 'Search existing assignments by title, instructions, or type. Returns assignment details including due dates and submission types.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Search query for assignments' },
+          limit: { type: 'number', description: 'Maximum results (1-10)', default: 5 },
+        },
+        required: ['query'],
+      }),
+      execute: async ({ query, limit = 5 }: { query: string; limit?: number }) => {
+        try {
+          const results = await searchEmbeddings({
+            classId,
+            query,
+            limit,
+            sourceTypes: ['ASSIGNMENT'],
+          });
+
+          const assignmentIds = results.map((r) => r.sourceId);
+          const assignments = await prisma.assignment.findMany({
+            where: { id: { in: assignmentIds } },
+            select: {
+              id: true,
+              title: true,
+              instructions: true,
+              type: true,
+              dueDate: true,
+              maxGrade: true,
+              section: { select: { name: true } },
+            },
+          });
+
+          return assignments.map((a) => ({
+            id: a.id,
+            title: a.title,
+            instructions: a.instructions?.slice(0, 200) ?? null,
+            type: a.type,
+            dueDate: a.dueDate.toISOString(),
+            maxGrade: a.maxGrade,
+            section: a.section?.name ?? null,
+          }));
+        } catch (error) {
+          logger.error('search_assignments tool failed', { error, classId, query });
+          return [];
+        }
+      },
+    },
+
+    get_student_progress: {
+      description: 'Get progress summary for a specific student in this class, including grades and submission status.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          studentId: { type: 'string', description: 'The student user ID' },
+        },
+        required: ['studentId'],
+      }),
+      execute: async ({ studentId }: { studentId: string }) => {
+        try {
+          const submissions = await prisma.submission.findMany({
+            where: {
+              studentId,
+              assignment: { classId },
+            },
+            select: {
+              id: true,
+              gradeReceived: true,
+              submittedAt: true,
+              assignment: {
+                select: {
+                  title: true,
+                  maxGrade: true,
+                  type: true,
+                },
+              },
+            },
+            orderBy: { submittedAt: 'desc' },
+            take: 20,
+          });
+
+          const totalAssignments = await prisma.assignment.count({
+            where: { classId },
+          });
+
+          const submitted = submissions.filter((s) => s.submittedAt);
+          const graded = submissions.filter((s) => s.gradeReceived !== null);
+          const avgGrade = graded.length > 0
+            ? graded.reduce((sum, s) => sum + (s.gradeReceived || 0), 0) / graded.length
+            : null;
+
+          return {
+            studentId,
+            totalAssignments,
+            submittedCount: submitted.length,
+            gradedCount: graded.length,
+            averageGrade: avgGrade ? Math.round(avgGrade * 10) / 10 : null,
+            recentSubmissions: submissions.slice(0, 5).map((s) => ({
+              assignment: s.assignment.title,
+              gradeReceived: s.gradeReceived,
+              maxGrade: s.assignment.maxGrade,
+              submittedAt: s.submittedAt?.toISOString() ?? null,
+            })),
+          };
+        } catch (error) {
+          logger.error('get_student_progress tool failed', { error, classId, studentId });
+          return { error: 'Failed to fetch student progress' };
+        }
+      },
+    },
+
+    get_worksheet_details: {
+      description: 'Get full details of a worksheet including all questions, answers, and mark schemes.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          worksheetId: { type: 'string', description: 'The worksheet ID to look up' },
+        },
+        required: ['worksheetId'],
+      }),
+      execute: async ({ worksheetId }: { worksheetId: string }) => {
+        try {
+          const worksheet = await prisma.worksheet.findUnique({
+            where: { id: worksheetId, classId },
+            include: {
+              questions: {
+                orderBy: { order: 'asc' },
+              },
+            },
+          });
+
+          if (!worksheet) {
+            return { error: 'Worksheet not found' };
+          }
+
+          return {
+            id: worksheet.id,
+            name: worksheet.name,
+            questions: worksheet.questions.map((q) => ({
+              id: q.id,
+              type: q.type,
+              question: q.question,
+              answer: q.answer,
+              options: q.options,
+              points: q.points,
+              order: q.order,
+            })),
+          };
+        } catch (error) {
+          logger.error('get_worksheet_details tool failed', { error, classId, worksheetId });
+          return { error: 'Failed to fetch worksheet' };
+        }
+      },
+    },
+
+    get_mark_scheme: {
+      description: 'Get a mark scheme (rubric) by ID, including criteria and point allocations.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          markSchemeId: { type: 'string', description: 'The mark scheme ID' },
+        },
+        required: ['markSchemeId'],
+      }),
+      execute: async ({ markSchemeId }: { markSchemeId: string }) => {
+        try {
+          const markScheme = await prisma.markScheme.findUnique({
+            where: { id: markSchemeId },
+            select: { id: true, name: true, structured: true },
+          });
+
+          if (!markScheme) {
+            return { error: 'Mark scheme not found' };
+          }
+
+          let parsed: unknown = {};
+          try { parsed = JSON.parse(markScheme.structured || '{}'); } catch { /* noop */ }
+
+          return {
+            id: markScheme.id,
+            name: markScheme.name,
+            structured: parsed,
+          };
+        } catch (error) {
+          logger.error('get_mark_scheme tool failed', { error, classId, markSchemeId });
+          return { error: 'Failed to fetch mark scheme' };
+        }
+      },
+    },
+
+    web_search: {
+      description: 'Search the web for current information on a topic. Use this when you need up-to-date facts, definitions, explanations, or context beyond the class materials.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'The search query to look up on the web' },
+        },
+        required: ['query'],
+      }),
+      execute: async ({ query }: { query: string }) => {
+        try {
+          const client = new OpenAI();
+          const response = await client.responses.create({
+            model: 'gpt-4o-mini',
+            tools: [{ type: 'web_search' }],
+            input: query,
+          });
+
+          const messageOutput = response.output.find(
+            (item) => item.type === 'message',
+          );
+          if (!messageOutput || messageOutput.type !== 'message') {
+            return { summary: 'No results found.', sources: [] };
+          }
+
+          const textContent = messageOutput.content.find(
+            (c) => c.type === 'output_text',
+          );
+          if (!textContent || textContent.type !== 'output_text') {
+            return { summary: 'No results found.', sources: [] };
+          }
+
+          const sources = textContent.annotations
+            .filter(
+              (a): a is Extract<typeof a, { type: 'url_citation' }> =>
+                a.type === 'url_citation',
+            )
+            .map((a) => ({ url: a.url, title: a.title }));
+
+          return {
+            summary: textContent.text.slice(0, 2000),
+            sources: sources.slice(0, 5),
+          };
+        } catch (error) {
+          logger.error('web_search tool failed', { error, query });
+          return { summary: 'Web search failed. Please try again.', sources: [] };
+        }
+      },
+    },
+  };
+}

package/src/services/announcement.ts

@@ -16,6 +16,7 @@ import { createDirectUploadFiles, type DirectUploadFile } from "../lib/fileUploa
 import { deleteFile } from "../lib/googleCloudStorage.js";
 import { sendToMultiple } from "./notification.js";
 import { logger } from "../utils/logger.js";
+import { enqueueEmbedding } from "./embedding.js";
 
 export async function getAllAnnouncements(classId: string) {
   const announcements = await findAnnouncementsByClassId(classId);
@@ -127,6 +128,9 @@ export async function createAnnouncementRecord(
     logger.error("Failed to send announcement notifications:", error);
   });
 
+  // Auto-index announcement for RAG search
+  enqueueEmbedding(classId, 'ANNOUNCEMENT', announcement.id);
+
   return {
     announcement: announcementWithAttachments || announcement,
     uploadFiles: directUploadFiles.length > 0 ? directUploadFiles : undefined,
@@ -263,6 +267,9 @@ export async function updateAnnouncementRecord(
     },
   });
 
+  // Re-index announcement for RAG search after update
+  enqueueEmbedding(input.classId, 'ANNOUNCEMENT', input.id);
+
   return {
     announcement: updatedAnnouncement,
     uploadFiles: directUploadFiles.length > 0 ? directUploadFiles : undefined,

package/src/services/assignment.ts

@@ -27,6 +27,7 @@ import { sendToMultiple } from "./notification.js";
 import { enqueueRunJob } from "../workers/queues.js";
 import { logger } from "../utils/logger.js";
 import { invalidateStudentProgressInferenceCache } from "./studentProgressInferenceCache.js";
+import { enqueueEmbedding } from "./embedding.js";
 
 export async function assignmentExists(id: string) {
   const assignment = await findAssignmentById(id);
@@ -311,13 +312,18 @@ export async function createAssignmentRecord(
   }
   await Promise.all(fileOperations);
 
-  sendToMultiple({
-    receiverIds: (studentIds && studentIds.length > 0) ? studentIds : classData.students.map((s) => s.id),
-    title: `New assignment in ${classData.name}`,
-    content: `"${title}" is due ${new Date(dueDate).toLocaleDateString()}.\n\n[View assignment](/class/${classId}/assignments/${assignment.id})`,
-  }).catch((error) => {
-    logger.error("Failed to send assignment notifications:", error);
-  });
+  if (!inProgress) {
+    sendToMultiple({
+      receiverIds: (studentIds && studentIds.length > 0) ? studentIds : classData.students.map((s) => s.id),
+      title: `New assignment in ${classData.name}`,
+      content: `"${title}" is due ${new Date(dueDate).toLocaleDateString()}.\n\n[View assignment](/class/${classId}/assignments/${assignment.id})`,
+    }).catch((error) => {
+      logger.error("Failed to send assignment notifications:", error);
+    });
+  }
+
+  // Auto-index assignment for RAG search
+  enqueueEmbedding(classId, 'ASSIGNMENT', assignment.id);
 
   return assignment;
 }
@@ -591,6 +597,21 @@ export async function updateAssignmentRecord(
       .catch((error) => logger.error("Failed to update max grade from rubric:", error));
   }
 
+  // Re-index assignment for RAG search after update
+  enqueueEmbedding(input.classId, 'ASSIGNMENT', input.id);
+  if (assignment.inProgress && input.inProgress === false && classData) {
+    const receiverIds = input.studentIds?.length
+      ? input.studentIds
+      : classData.students.map((s) => s.id);
+    sendToMultiple({
+      receiverIds,
+      title: `New assignment in ${classData.name}`,
+      content: `"${updatedAssignment.title}" is due ${new Date(updatedAssignment.dueDate).toLocaleDateString()}.\n\n[View assignment](/class/${classData.id}/assignments/${updatedAssignment.id})`,
+    }).catch((error) => {
+      logger.error("Failed to send assignment publish notifications:", error);
+    });
+  }
+
   return updatedAssignment;
 }
 
@@ -916,6 +937,9 @@ export async function updateSubmissionAsTeacherRecord(
     );
   }
 
+  // Index submission for RAG search after teacher grades/feedback
+  enqueueEmbedding(input.classId, 'SUBMISSION', submissionId);
+
   return updated;
 }
 

package/src/services/auth.ts

@@ -10,6 +10,7 @@ import { sendMail } from "../utils/email.js";
 import { prismaWrapper } from "../utils/prismaWrapper.js";
 import { env } from "../lib/config/env.js";
 import { logger } from "../utils/logger.js";
+import { CURRENT_TERMS_VERSION } from "../lib/legal.js";
 import {
   findUserByUsername,
   findUserByUsernameOrEmail,
@@ -32,8 +33,17 @@ export async function register(input: {
   username: string;
   email: string;
   password: string;
+  agreeToTerms: true;
+  termsVersion: string;
 }) {
-  const { username, email, password } = input;
+  const { username, email, password, termsVersion } = input;
+
+  if (termsVersion !== CURRENT_TERMS_VERSION) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Please accept the current Terms of Service and Privacy Policy.",
+    });
+  }
 
   const existingUser = await prismaWrapper.findFirst(
     () => findUserByUsernameOrEmail(username, email),
@@ -70,7 +80,9 @@ export async function register(input: {
         username,
         email,
         password: await hash(password, 10),
-        verified: true,
+        verified: false,
+        termsAcceptedAt: new Date(),
+        termsVersion,
       }),
     "creating new user during registration"
   );

package/src/services/class.ts

@@ -6,6 +6,7 @@ import { SessionType } from "@prisma/client";
 import { TRPCError } from "@trpc/server";
 import { prisma } from "../lib/prisma.js";
 import { generateInviteCode } from "../utils/generateInviteCode.js";
+import { enqueueEmbedding } from "./embedding.js";
 import {
   findTeacherClasses,
   findStudentClasses,
@@ -27,6 +28,8 @@ import {
 } from "../models/class.js";
 import { Class, Folder } from "@prisma/client";
 import { invalidateStudentProgressInferenceCache } from "./studentProgressInferenceCache.js";
+import { sendToMultiple } from "./notification.js";
+import { logger } from "../utils/logger.js";
 
 async function requireActiveSchoolMembers(schoolId: string, userIds: string[]) {
   const uniqueUserIds = [...new Set(userIds)];
@@ -624,10 +627,15 @@ export async function updateSyllabus(classId: string, contents: string) {
       message: "Missing key contents",
     });
   }
-  return prisma.class.update({
+  const updated = await prisma.class.update({
     where: { id: classId },
     data: { syllabus: contents },
   });
+
+  // Index syllabus for RAG search
+  enqueueEmbedding(classId, 'SYLLABUS', classId);
+
+  return updated;
 }
 
 export async function listLabDrafts(classId: string, teacherId: string) {
@@ -748,7 +756,7 @@ export async function publishLabDraft(
     });
   }
 
-  return prisma.assignment.update({
+  const published = await prisma.assignment.update({
     where: { id: draftId },
     data: {
       inProgress: false,
@@ -759,6 +767,23 @@ export async function publishLabDraft(
       modifiedAt: new Date(),
     },
   });
+
+  const classData = await prisma.class.findUnique({
+    where: { id: classId },
+    select: { name: true, students: { select: { id: true } } },
+  });
+
+  if (classData) {
+    sendToMultiple({
+      receiverIds: classData.students.map((s) => s.id),
+      title: `New assignment in ${classData.name}`,
+      content: `"${published.title}" is due ${new Date(published.dueDate).toLocaleDateString()}.\n\n[View assignment](/class/${classId}/assignments/${published.id})`,
+    }).catch((error) => {
+      logger.error("Failed to send lab draft publish notifications:", error);
+    });
+  }
+
+  return published;
 }
 
 export async function getFiles(classId: string) {