@studious-lms/server 1.12.0 → 1.14.0

package/src/seedDatabase.ts

@@ -42,7 +42,7 @@ export async function clearDatabase() {
     // Discussion tree.
     await prisma.discussionReply.deleteMany();
     await prisma.discussion.deleteMany();
-    await prisma.discussionTag.deleteMany();
+    await prisma.classTag.deleteMany();
 
     // Comments after their reactions are gone.
     await prisma.comment.deleteMany();
@@ -1425,13 +1425,13 @@ export const seedDatabase = async () => {
     // ---------------------------------------------------------------------
     // 15. Discussions (with replies, tags, reads, reactions)
     // ---------------------------------------------------------------------
-    const bioTag = await prisma.discussionTag.create({
+    const bioTag = await prisma.classTag.create({
         data: { classId: biologyClass.id, name: "Lab", color: "#10B981" },
     });
-    const bioTagHomework = await prisma.discussionTag.create({
+    const bioTagHomework = await prisma.classTag.create({
         data: { classId: biologyClass.id, name: "Homework Help", color: "#F59E0B" },
     });
-    const mathTagAP = await prisma.discussionTag.create({
+    const mathTagAP = await prisma.classTag.create({
         data: { classId: mathClass.id, name: "AP Prep", color: "#DC2626" },
     });
 

package/src/services/aiChatStream.ts

@@ -0,0 +1,219 @@
+/**
+ * Shared AI chat streaming helper.
+ *
+ * Runs a genuine token-by-token stream via the Vercel AI SDK (`streamText`)
+ * against OpenAI — the same provider the rest of the app's inference uses
+ * (`OPENAI_API_KEY`). Real text tokens are broadcast over Pusher as they are
+ * produced, and real tool calls are broadcast inline (in the order the model
+ * invokes them) instead of being derived after the fact from a JSON blob.
+ *
+ * Callers own persistence: this helper returns the accumulated text and the
+ * ordered tool calls so the pipeline can write `content`/`meta` and emit the
+ * terminal `message-stream-complete` / `message-updated` events.
+ */
+import { streamText, stepCountIs, type ModelMessage, type ToolSet } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { getRedis } from '../lib/redis.js';
+import { pusher, chatChannel } from '../lib/pusher.js';
+import { logger } from '../utils/logger.js';
+
+const STREAM_REDIS_TTL = 600; // 10 minutes
+const STREAM_KEY_PREFIX = 'stream:';
+
+/** Default streaming model — matches the existing streamAIResponse path. */
+export const DEFAULT_STREAM_MODEL = 'gpt-4o-mini';
+
+export interface StreamedToolCall {
+  toolName: string;
+  /** Args the model passed to the tool. */
+  input: unknown;
+  /** Value the tool returned (undefined for client-side / no-result tools). */
+  output?: unknown;
+  status: 'completed' | 'failed';
+}
+
+/**
+ * An ordered fragment of an AI message. The message is a sequence of these
+ * parts in the exact order the model produced them, so a tool call rendered
+ * "between paragraph 1 and 2" is represented as
+ * `[{text}, {tool}, {text}]` — enabling true inline rendering (and reload
+ * persistence) instead of text and tool calls living in separate buckets.
+ */
+export type StreamPart =
+  | { type: 'text'; text: string }
+  | {
+      type: 'tool';
+      toolCallId: string;
+      toolName: string;
+      /** Concrete entity label (e.g. assignment title / search query), if any. */
+      title?: string;
+      status: 'executing' | 'completed' | 'failed';
+    };
+
+/** Pull a human-meaningful label out of a tool's input args, if present. */
+function toolTitleFromInput(input: unknown): string | undefined {
+  if (input && typeof input === 'object') {
+    const obj = input as Record<string, unknown>;
+    for (const key of ['title', 'name', 'query'] as const) {
+      const val = obj[key];
+      if (typeof val === 'string' && val.trim()) return val.trim();
+    }
+  }
+  return undefined;
+}
+
+export interface StreamChatOptions {
+  conversationId: string;
+  aiMessageId: string;
+  system: string;
+  messages: ModelMessage[];
+  tools?: ToolSet;
+  model?: string;
+  temperature?: number;
+  maxOutputTokens?: number;
+  /** Max agent steps (tool round-trips). Defaults to 6. */
+  maxSteps?: number;
+}
+
+export interface StreamChatResult {
+  text: string;
+  toolCalls: StreamedToolCall[];
+  /** Ordered text/tool parts, in the exact order the model produced them. */
+  parts: StreamPart[];
+}
+
+/**
+ * Stream a chat completion, broadcasting real text chunks and tool-call
+ * events over Pusher. Does NOT persist the message or emit the terminal
+ * stream-complete event — the caller does that once it has assembled the
+ * final `content`/`meta` (e.g. PDF attachments, structured proposals).
+ */
+export async function streamChatResponse(
+  options: StreamChatOptions,
+): Promise<StreamChatResult> {
+  const {
+    conversationId,
+    aiMessageId,
+    system,
+    messages,
+    tools,
+    model = DEFAULT_STREAM_MODEL,
+    temperature = 0.7,
+    maxOutputTokens = 4096,
+    maxSteps = 6,
+  } = options;
+
+  const redis = getRedis();
+  const streamKey = `${STREAM_KEY_PREFIX}${aiMessageId}`;
+  if (redis) {
+    await redis.set(streamKey, '', 'EX', STREAM_REDIS_TTL);
+  }
+
+  let fullText = '';
+  const parts: StreamPart[] = [];
+  const toolCalls: StreamedToolCall[] = [];
+  // Map AI SDK toolCallId -> index in `parts` so the executing indicator can
+  // be flipped to completed/failed in place (preserving its position).
+  const toolPartIndexById = new Map<string, number>();
+
+  const appendText = (text: string) => {
+    fullText += text;
+    const last = parts[parts.length - 1];
+    if (last && last.type === 'text') {
+      last.text += text;
+    } else {
+      parts.push({ type: 'text', text });
+    }
+  };
+
+  const broadcast = async (event: string, payload: Record<string, unknown>) => {
+    try {
+      await pusher.trigger(chatChannel(conversationId), event, payload);
+    } catch (err) {
+      logger.warn(`Failed to broadcast ${event}`, { err, aiMessageId });
+    }
+  };
+
+  try {
+    const result = streamText({
+      model: openai(model),
+      system,
+      messages,
+      ...(tools ? { tools } : {}),
+      temperature,
+      maxOutputTokens,
+      stopWhen: stepCountIs(maxSteps),
+    });
+
+    // `fullStream` yields text deltas AND tool events in a single, correctly
+    // ordered sequence — this is what makes inline tool calls possible. We
+    // build an ordered `parts` list and broadcast each event as it happens.
+    for await (const part of result.fullStream) {
+      switch (part.type) {
+        case 'text-delta': {
+          appendText(part.text);
+          if (redis) {
+            await redis.append(streamKey, part.text).catch(() => {});
+          }
+          await broadcast('message-stream-chunk', {
+            messageId: aiMessageId,
+            chunk: part.text,
+          });
+          break;
+        }
+        case 'tool-call': {
+          const title = toolTitleFromInput(part.input);
+          toolPartIndexById.set(part.toolCallId, parts.length);
+          parts.push({
+            type: 'tool',
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            ...(title ? { title } : {}),
+            status: 'executing',
+          });
+          await broadcast('message-tool-call', {
+            messageId: aiMessageId,
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            ...(title ? { title } : {}),
+            status: 'executing',
+          });
+          break;
+        }
+        case 'tool-result':
+        case 'tool-error': {
+          const status: 'completed' | 'failed' =
+            part.type === 'tool-error' ? 'failed' : 'completed';
+          const idx = toolPartIndexById.get(part.toolCallId);
+          if (idx !== undefined) {
+            const existing = parts[idx];
+            if (existing && existing.type === 'tool') existing.status = status;
+          }
+          toolCalls.push({
+            toolName: part.toolName,
+            input: part.input,
+            output: part.type === 'tool-result' ? part.output : undefined,
+            status,
+          });
+          await broadcast('message-tool-call', {
+            messageId: aiMessageId,
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            ...(toolTitleFromInput(part.input) ? { title: toolTitleFromInput(part.input) } : {}),
+            status,
+          });
+          break;
+        }
+        default:
+          // ignore reasoning/source/step/finish/raw parts
+          break;
+      }
+    }
+
+    return { text: fullText, toolCalls, parts };
+  } finally {
+    if (redis) {
+      await redis.del(streamKey).catch(() => {});
+    }
+  }
+}

package/src/services/aiModifierTools.ts

@@ -0,0 +1,188 @@
+/**
+ * AI modifier "field-update" tools.
+ *
+ * Unlike the Lab-chat proposal tools (which only *record* a payload for the
+ * teacher to accept later), these tools DIRECTLY edit a single key of an
+ * existing assignment or worksheet and persist it immediately via the normal
+ * service layer. The modifier route locks the resource (Redis flag + Pusher
+ * `modifier-started`) while the stream runs, and each successful field write
+ * fires a callback so the route can broadcast `modifier-field-updated` to every
+ * open editor — they apply the change live and stay read-only until the run
+ * completes or fails.
+ *
+ * NOTE: like `aiTools.ts` / `aiProposalTools.ts`, these intentionally use
+ * `jsonSchema()` rather than the zod `tool()` helper to avoid the TS2589
+ * "excessively deep" compiler blow-up on nested schemas.
+ */
+import { jsonSchema, type ToolSet } from 'ai';
+import { updateAssignmentRecord } from './assignment.js';
+import { updateWorksheetRecord } from './worksheet.js';
+
+/** A single field write that was applied to a resource. */
+export interface ModifierFieldUpdate {
+  field: string;
+  value: unknown;
+  /** Human-readable label for the change, e.g. "title" or "due date". */
+  label: string;
+}
+
+const ASSIGNMENT_TYPES = [
+  'HOMEWORK', 'QUIZ', 'TEST', 'PROJECT', 'ESSAY', 'DISCUSSION', 'PRESENTATION', 'LAB', 'OTHER',
+] as const;
+
+/**
+ * Editable scalar keys of an assignment, with the coercion + human label used
+ * when the model passes a (string) value. Keys map 1:1 to
+ * `updateAssignmentRecord` input fields.
+ */
+const ASSIGNMENT_FIELDS: Record<
+  string,
+  { label: string; type: 'string' | 'number' | 'boolean' | 'date' | 'enum'; enumValues?: readonly string[] }
+> = {
+  title: { label: 'title', type: 'string' },
+  instructions: { label: 'instructions', type: 'string' },
+  dueDate: { label: 'due date', type: 'date' },
+  type: { label: 'type', type: 'enum', enumValues: ASSIGNMENT_TYPES },
+  maxGrade: { label: 'max grade', type: 'number' },
+  graded: { label: 'graded', type: 'boolean' },
+  weight: { label: 'weight', type: 'number' },
+  acceptFiles: { label: 'file submissions', type: 'boolean' },
+  acceptExtendedResponse: { label: 'extended response', type: 'boolean' },
+  acceptWorksheet: { label: 'worksheet submissions', type: 'boolean' },
+  aiPolicyLevel: { label: 'AI policy level', type: 'number' },
+};
+
+const WORKSHEET_FIELDS: Record<string, { label: string; type: 'string' }> = {
+  name: { label: 'name', type: 'string' },
+};
+
+/** Coerce a model-supplied string value into the type a field expects. */
+function coerceValue(
+  raw: string,
+  spec: { type: 'string' | 'number' | 'boolean' | 'date' | 'enum'; enumValues?: readonly string[] },
+): unknown {
+  switch (spec.type) {
+    case 'number': {
+      const n = Number(raw);
+      if (Number.isNaN(n)) throw new Error(`Expected a number but got "${raw}"`);
+      return n;
+    }
+    case 'boolean': {
+      const v = raw.trim().toLowerCase();
+      if (['true', 'yes', '1'].includes(v)) return true;
+      if (['false', 'no', '0'].includes(v)) return false;
+      throw new Error(`Expected a boolean but got "${raw}"`);
+    }
+    case 'date': {
+      const d = new Date(raw);
+      if (Number.isNaN(d.getTime())) throw new Error(`Expected an ISO date but got "${raw}"`);
+      return d.toISOString();
+    }
+    case 'enum': {
+      const v = raw.trim().toUpperCase();
+      if (spec.enumValues && !spec.enumValues.includes(v)) {
+        throw new Error(`Expected one of ${spec.enumValues.join(', ')} but got "${raw}"`);
+      }
+      return v;
+    }
+    default:
+      return raw;
+  }
+}
+
+/**
+ * Build the field-update tool for an assignment. The `onFieldUpdate` callback
+ * runs after a successful persist so the route can broadcast the change.
+ */
+export function assignmentModifierTools(
+  userId: string,
+  assignmentId: string,
+  classId: string,
+  onFieldUpdate: (update: ModifierFieldUpdate) => Promise<void> | void,
+): ToolSet {
+  const fieldNames = Object.keys(ASSIGNMENT_FIELDS);
+  return {
+    update_assignment_field: {
+      description:
+        'Directly update a single field of the assignment and save it immediately. ' +
+        'Call this once per field the teacher wants changed. The assignment is locked ' +
+        'for editing until you finish.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          field: {
+            type: 'string',
+            enum: fieldNames,
+            description: 'The assignment field to update.',
+          },
+          value: {
+            type: 'string',
+            description:
+              'The new value as a string. Booleans use "true"/"false", numbers as digits, ' +
+              'dates as ISO 8601, type as one of the allowed enum values.',
+          },
+        },
+        required: ['field', 'value'],
+      }),
+      execute: async ({ field, value }: { field: string; value: string }) => {
+        const spec = ASSIGNMENT_FIELDS[field];
+        if (!spec) {
+          return `Unknown field "${field}". Allowed: ${fieldNames.join(', ')}.`;
+        }
+        let coerced: unknown;
+        try {
+          coerced = coerceValue(value, spec);
+        } catch (err) {
+          return `Could not update ${spec.label}: ${(err as Error).message}`;
+        }
+        const updateInput: Parameters<typeof updateAssignmentRecord>[1] = {
+          id: assignmentId,
+          classId,
+        };
+        (updateInput as Record<string, unknown>)[field] = coerced;
+        await updateAssignmentRecord(userId, updateInput);
+        await onFieldUpdate({ field, value: coerced, label: spec.label });
+        return `Updated ${spec.label}.`;
+      },
+    },
+  };
+}
+
+/** Build the field-update tool for a worksheet. */
+export function worksheetModifierTools(
+  worksheetId: string,
+  userId: string,
+  onFieldUpdate: (update: ModifierFieldUpdate) => Promise<void> | void,
+): ToolSet {
+  const fieldNames = Object.keys(WORKSHEET_FIELDS);
+  return {
+    update_worksheet_field: {
+      description:
+        'Directly update a single field of the worksheet and save it immediately. ' +
+        'The worksheet is locked for editing until you finish.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          field: {
+            type: 'string',
+            enum: fieldNames,
+            description: 'The worksheet field to update.',
+          },
+          value: { type: 'string', description: 'The new value as a string.' },
+        },
+        required: ['field', 'value'],
+      }),
+      execute: async ({ field, value }: { field: string; value: string }) => {
+        const spec = WORKSHEET_FIELDS[field];
+        if (!spec) {
+          return `Unknown field "${field}". Allowed: ${fieldNames.join(', ')}.`;
+        }
+        const updateInput: Parameters<typeof updateWorksheetRecord>[2] = {};
+        (updateInput as Record<string, unknown>)[field] = value;
+        await updateWorksheetRecord(worksheetId, userId, updateInput);
+        await onFieldUpdate({ field, value, label: spec.label });
+        return `Updated ${spec.label}.`;
+      },
+    },
+  };
+}