@studious-lms/server 1.13.0 → 1.14.0

package/src/services/aiProposalTools.ts

@@ -0,0 +1,272 @@
+/**
+ * Lab-chat "proposal" tools.
+ *
+ * In the agentic Lab pipeline the model produces create-actions by *calling
+ * tools* (e.g. `propose_assignment`) instead of returning a JSON blob. Each
+ * tool records a structured payload into a shared accumulator and returns a
+ * short confirmation so the model can keep narrating. After the stream ends
+ * the pipeline turns the accumulator into the `message.meta.*ToCreate` shape
+ * the frontend accept-cards already consume — so the data contract is
+ * preserved while the generation becomes genuine inline tool calls.
+ *
+ * NOTE: these tools intentionally use `jsonSchema()` rather than the zod
+ * `tool()` helper. Zod-typed `tool()` definitions with deeply nested schemas
+ * make the TS compiler instantiate excessively deep types (TS2589) and OOM,
+ * so we mirror the existing `aiTools.ts` pattern (plain JSON Schema + manually
+ * typed execute args).
+ */
+import { jsonSchema, type ToolSet } from 'ai';
+import { v4 } from 'uuid';
+import type {
+  AssignmentToCreate,
+  WorksheetToCreate,
+  SectionToCreate,
+  DocToCreate,
+} from '../pipelines/aiLabChatContract.js';
+import type { DocumentBlock } from '../lib/jsonStyles.js';
+
+export interface LabProposals {
+  assignments: AssignmentToCreate[];
+  worksheets: WorksheetToCreate[];
+  sections: SectionToCreate[];
+  docs: DocToCreate[];
+}
+
+export function createLabProposals(): LabProposals {
+  return { assignments: [], worksheets: [], sections: [], docs: [] };
+}
+
+function normalizeDueDate(input?: string | null): string {
+  if (input) {
+    const parsed = new Date(input);
+    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString();
+  }
+  // Default: one week out.
+  return new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();
+}
+
+const ASSIGNMENT_TYPES = [
+  'HOMEWORK', 'QUIZ', 'TEST', 'PROJECT', 'ESSAY', 'DISCUSSION', 'PRESENTATION', 'LAB', 'OTHER',
+] as const;
+type AssignmentType = (typeof ASSIGNMENT_TYPES)[number];
+
+const QUESTION_TYPES = [
+  'MULTIPLE_CHOICE', 'TRUE_FALSE', 'SHORT_ANSWER', 'LONG_ANSWER', 'MATH_EXPRESSION', 'ESSAY',
+] as const;
+type QuestionType = (typeof QUESTION_TYPES)[number];
+
+interface ProposeSectionArgs {
+  name: string;
+  color?: string | null;
+}
+
+interface ProposeWorksheetArgs {
+  title: string;
+  questions: Array<{
+    type: QuestionType;
+    question: string;
+    answer?: string;
+    options?: Array<{ text: string; isCorrect: boolean }>;
+    markScheme?: Array<{ points: number; description: string }>;
+    points?: number;
+  }>;
+}
+
+interface ProposeAssignmentArgs {
+  title: string;
+  instructions: string;
+  dueDate?: string;
+  type?: AssignmentType;
+  maxGrade?: number;
+  acceptFiles?: boolean;
+  acceptExtendedResponse?: boolean;
+  acceptWorksheet?: boolean;
+}
+
+interface GenerateDocumentArgs {
+  title: string;
+  blocks: DocumentBlock[];
+}
+
+/**
+ * Build the set of proposal tools backed by the given accumulator.
+ * Merge these with the read-only RAG tools from `aiTools(classId)`.
+ */
+export function labProposalTools(proposals: LabProposals): ToolSet {
+  return {
+    propose_section: {
+      description:
+        'Propose a new section (folder) to organise class content. Call once per section you want to create.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Section name' },
+          color: { type: 'string', description: 'Optional hex color like #3b82f6' },
+        },
+        required: ['name'],
+      }),
+      execute: async ({ name, color }: ProposeSectionArgs) => {
+        proposals.sections.push({ name, color: color ?? null });
+        return `Section "${name}" proposed.`;
+      },
+    },
+
+    propose_worksheet: {
+      description:
+        'Propose a worksheet of questions for the teacher to review and create. Include all questions in a single call.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: 'Worksheet title' },
+          questions: {
+            type: 'array',
+            description: 'The list of questions',
+            items: {
+              type: 'object',
+              properties: {
+                type: { type: 'string', enum: QUESTION_TYPES as unknown as string[] },
+                question: { type: 'string' },
+                answer: { type: 'string' },
+                options: {
+                  type: 'array',
+                  description: 'For MULTIPLE_CHOICE/TRUE_FALSE questions',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      text: { type: 'string' },
+                      isCorrect: { type: 'boolean' },
+                    },
+                    required: ['text', 'isCorrect'],
+                  },
+                },
+                markScheme: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      points: { type: 'number' },
+                      description: { type: 'string' },
+                    },
+                    required: ['points', 'description'],
+                  },
+                },
+                points: { type: 'number' },
+              },
+              required: ['type', 'question'],
+            },
+          },
+        },
+        required: ['title', 'questions'],
+      }),
+      execute: async ({ title, questions }: ProposeWorksheetArgs) => {
+        const worksheet: WorksheetToCreate = {
+          title,
+          questions: (questions ?? []).map((q, index) => ({
+            type: q.type,
+            question: q.question,
+            answer: q.answer ?? '',
+            options: (q.options ?? []).map((o) => ({
+              id: v4(),
+              text: o.text,
+              isCorrect: o.isCorrect,
+            })),
+            markScheme: (q.markScheme ?? []).map((m) => ({
+              id: v4(),
+              points: m.points,
+              description: m.description,
+            })),
+            points: q.points ?? 0,
+            order: index,
+          })),
+        };
+        proposals.worksheets.push(worksheet);
+        return `Worksheet "${title}" with ${worksheet.questions.length} question(s) proposed.`;
+      },
+    },
+
+    propose_assignment: {
+      description:
+        'Propose an assignment for the teacher to review and create. Call once per assignment.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          instructions: { type: 'string' },
+          dueDate: {
+            type: 'string',
+            description: 'ISO 8601 datetime. Defaults to one week from now if omitted.',
+          },
+          type: { type: 'string', enum: ASSIGNMENT_TYPES as unknown as string[] },
+          maxGrade: { type: 'number' },
+          acceptFiles: { type: 'boolean' },
+          acceptExtendedResponse: { type: 'boolean' },
+          acceptWorksheet: { type: 'boolean' },
+        },
+        required: ['title', 'instructions'],
+      }),
+      execute: async ({
+        title,
+        instructions,
+        dueDate,
+        type,
+        maxGrade,
+        acceptFiles,
+        acceptExtendedResponse,
+        acceptWorksheet,
+      }: ProposeAssignmentArgs) => {
+        const assignment: AssignmentToCreate = {
+          title,
+          instructions,
+          dueDate: normalizeDueDate(dueDate),
+          type: type ?? 'HOMEWORK',
+          maxGrade: maxGrade ?? 100,
+          acceptFiles: acceptFiles ?? true,
+          acceptExtendedResponse: acceptExtendedResponse ?? false,
+          acceptWorksheet: acceptWorksheet ?? false,
+          gradingBoundaryId: null,
+          markSchemeId: null,
+          worksheetIds: [],
+          studentIds: [],
+          sectionId: null,
+          attachments: [],
+        };
+        proposals.assignments.push(assignment);
+        return `Assignment "${title}" proposed.`;
+      },
+    },
+
+    generate_document: {
+      description:
+        'Generate a document (rendered to a PDF and attached to the message). Provide the document title and an ordered list of formatting blocks.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          blocks: {
+            type: 'array',
+            description: 'Ordered list of document formatting blocks',
+            items: {
+              type: 'object',
+              properties: {
+                format: { type: 'number', description: 'Block format id (0-12)' },
+                content: {
+                  description: 'String, or array of strings for list blocks',
+                },
+                metadata: {
+                  type: 'object',
+                  description: 'Optional styling metadata',
+                },
+              },
+              required: ['format', 'content'],
+            },
+          },
+        },
+        required: ['title', 'blocks'],
+      }),
+      execute: async ({ title, blocks }: GenerateDocumentArgs) => {
+        proposals.docs.push({ title, blocks } as unknown as DocToCreate);
+        return `Document "${title}" queued for generation.`;
+      },
+    },
+  };
+}

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);
+    }
+  }
+}