@studious-lms/server 1.13.0 → 1.14.0

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_preview' }],
+            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;
 }
 

package/src/services/class.ts

@@ -27,6 +27,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)];
@@ -748,7 +750,7 @@ export async function publishLabDraft(
     });
   }
 
-  return prisma.assignment.update({
+  const published = await prisma.assignment.update({
     where: { id: draftId },
     data: {
       inProgress: false,
@@ -759,6 +761,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) {

package/src/services/discussion.ts

@@ -1,4 +1,5 @@
 import type { DiscussionType, Prisma, ReactionType } from "@prisma/client";
+import type { AppTransactionClient } from "../lib/prisma.js";
 import { TRPCError } from "@trpc/server";
 import { prisma } from "../lib/prisma.js";
 import { discussionChannel, pusher } from "../lib/pusher.js";
@@ -225,7 +226,7 @@ async function getDiscussionForUser(discussionId: string, userId: string) {
 }
 
 async function claimDiscussionAttachments(
-  tx: Prisma.TransactionClient,
+  tx: AppTransactionClient,
   userId: string,
   discussionId: string,
   attachmentIds: string[] = []
@@ -242,7 +243,7 @@ async function claimDiscussionAttachments(
 }
 
 async function claimReplyAttachments(
-  tx: Prisma.TransactionClient,
+  tx: AppTransactionClient,
   userId: string,
   replyId: string,
   attachmentIds: string[] = []
@@ -674,28 +675,28 @@ export async function toggleDiscussionReaction(userId: string, input: { discussi
 
 export async function listDiscussionTags(userId: string, classId: string) {
   await getDiscussionClassAccess(classId, userId);
-  return prisma.discussionTag.findMany({ where: { classId }, orderBy: { name: "asc" } });
+  return prisma.classTag.findMany({ where: { classId }, orderBy: { name: "asc" } });
 }
 
 export async function createDiscussionTag(userId: string, input: { classId: string; name: string; color: string }) {
   const isTeacher = await prisma.class.findFirst({ where: { id: input.classId, ...classTeacherOrSchoolAdminWhere(userId) }, select: { id: true, discussionsEnabled: true } });
   if (!isTeacher?.discussionsEnabled) throw new TRPCError({ code: "FORBIDDEN", message: "Only teachers can manage discussion tags" });
-  return prisma.discussionTag.create({ data: { classId: input.classId, name: input.name.trim(), color: input.color } });
+  return prisma.classTag.create({ data: { classId: input.classId, name: input.name.trim(), color: input.color } });
 }
 
 export async function updateDiscussionTag(userId: string, input: { tagId: string; name?: string; color?: string }) {
-  const tag = await prisma.discussionTag.findUnique({ where: { id: input.tagId }, select: { classId: true } });
+  const tag = await prisma.classTag.findUnique({ where: { id: input.tagId }, select: { classId: true } });
   if (!tag) throw new TRPCError({ code: "NOT_FOUND", message: "Tag not found" });
   const isTeacher = await prisma.class.findFirst({ where: { id: tag.classId, ...classTeacherOrSchoolAdminWhere(userId) }, select: { id: true, discussionsEnabled: true } });
   if (!isTeacher?.discussionsEnabled) throw new TRPCError({ code: "FORBIDDEN", message: "Only teachers can manage discussion tags" });
-  return prisma.discussionTag.update({ where: { id: input.tagId }, data: { name: input.name?.trim(), color: input.color } });
+  return prisma.classTag.update({ where: { id: input.tagId }, data: { name: input.name?.trim(), color: input.color } });
 }
 
 export async function deleteDiscussionTag(userId: string, tagId: string) {
-  const tag = await prisma.discussionTag.findUnique({ where: { id: tagId }, select: { classId: true } });
+  const tag = await prisma.classTag.findUnique({ where: { id: tagId }, select: { classId: true } });
   if (!tag) throw new TRPCError({ code: "NOT_FOUND", message: "Tag not found" });
   const isTeacher = await prisma.class.findFirst({ where: { id: tag.classId, ...classTeacherOrSchoolAdminWhere(userId) }, select: { id: true, discussionsEnabled: true } });
   if (!isTeacher?.discussionsEnabled) throw new TRPCError({ code: "FORBIDDEN", message: "Only teachers can manage discussion tags" });
-  await prisma.discussionTag.delete({ where: { id: tagId } });
+  await prisma.classTag.delete({ where: { id: tagId } });
   return { success: true };
 }