@studious-lms/server 1.13.0 → 1.15.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,341 @@
+/**
+ * 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;
+      /** Requested output type from the tool args (pdf, pptx, xlsx, …). */
+      format?: string;
+      /** Set after generated files are persisted on the message. */
+      fileId?: string;
+      fileName?: string;
+      status: 'executing' | 'completed' | 'failed';
+    };
+
+export interface GeneratedDocFileLink {
+  title: string;
+  fileId: string;
+  fileName: string;
+  format?: string;
+}
+
+/** Apply pipeline-resolved formats onto generate_document tool parts. */
+export function applyResolvedFormatsToStreamParts(
+  parts: StreamPart[],
+  docs: Array<{ title: string; format: string }>,
+): StreamPart[] {
+  if (docs.length === 0) return parts;
+
+  const pending = [...docs];
+  const takeDoc = (title?: string) => {
+    if (title) {
+      const idx = pending.findIndex(
+        (d) => d.title.trim().toLowerCase() === title.trim().toLowerCase(),
+      );
+      if (idx >= 0) return pending.splice(idx, 1)[0];
+    }
+    return pending.shift();
+  };
+
+  return parts.map((part) => {
+    if (part.type !== 'tool' || part.toolName !== 'generate_document') return part;
+    const doc = takeDoc(part.title);
+    return doc ? { ...part, format: doc.format } : part;
+  });
+}
+
+/** Tools that queue async work after the model stream; UI stays loading until the pipeline finishes. */
+const DEFERRED_COMPLETION_TOOLS = new Set(['generate_document']);
+
+function isDeferredCompletionTool(toolName: string): boolean {
+  return DEFERRED_COMPLETION_TOOLS.has(toolName);
+}
+
+/** Attach file IDs to `generate_document` tool parts for inline download chips. */
+export function enrichStreamPartsWithGeneratedFiles(
+  parts: StreamPart[],
+  files: GeneratedDocFileLink[],
+): StreamPart[] {
+  if (files.length === 0) return parts;
+
+  const docToolIndices = parts
+    .map((part, index) => ({ part, index }))
+    .filter(
+      ({ part }) =>
+        part.type === 'tool' && part.toolName === 'generate_document',
+    );
+
+  const unmatched = [...files];
+  const fileForTool = (toolTitle?: string): GeneratedDocFileLink | undefined => {
+    if (toolTitle) {
+      const idx = unmatched.findIndex(
+        (f) => f.title.trim().toLowerCase() === toolTitle.trim().toLowerCase(),
+      );
+      if (idx >= 0) return unmatched.splice(idx, 1)[0];
+    }
+    return unmatched.shift();
+  };
+
+  const fileByIndex = new Map<number, GeneratedDocFileLink>();
+  for (const { part, index } of docToolIndices) {
+    if (part.type !== 'tool') continue;
+    const file = fileForTool(part.title);
+    if (file) fileByIndex.set(index, file);
+  }
+
+  return parts.map((part, index) => {
+    const file = fileByIndex.get(index);
+    if (!file || part.type !== 'tool') return part;
+    return {
+      ...part,
+      fileId: file.fileId,
+      fileName: file.fileName,
+      status: 'completed',
+      ...(file.format ? { format: file.format } : {}),
+    };
+  });
+}
+
+/** Mark deferred tools completed (file linked) or failed (generation did not produce a file). */
+export function finalizeDeferredToolParts(parts: StreamPart[]): StreamPart[] {
+  return parts.map((part) => {
+    if (part.type !== 'tool' || !isDeferredCompletionTool(part.toolName)) {
+      return part;
+    }
+    if (part.fileId) return { ...part, status: 'completed' };
+    if (part.status === 'executing') return { ...part, status: 'failed' };
+    return part;
+  });
+}
+
+function toolFieldFromInput(input: unknown, key: string): string | undefined {
+  if (input && typeof input === 'object') {
+    const val = (input as Record<string, unknown>)[key];
+    if (typeof val === 'string' && val.trim()) return val.trim();
+  }
+  return undefined;
+}
+
+/** Pull a human-meaningful label out of a tool's input args, if present. */
+function toolTitleFromInput(input: unknown): string | undefined {
+  for (const key of ['title', 'name', 'query'] as const) {
+    const val = toolFieldFromInput(input, key);
+    if (val) return val;
+  }
+  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);
+          const format = toolFieldFromInput(part.input, 'format');
+          toolPartIndexById.set(part.toolCallId, parts.length);
+          parts.push({
+            type: 'tool',
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            ...(title ? { title } : {}),
+            ...(format ? { format } : {}),
+            status: 'executing',
+          });
+          await broadcast('message-tool-call', {
+            messageId: aiMessageId,
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            ...(title ? { title } : {}),
+            ...(format ? { format } : {}),
+            status: 'executing',
+          });
+          break;
+        }
+        case 'tool-result':
+        case 'tool-error': {
+          const failed = part.type === 'tool-error';
+          const deferred = isDeferredCompletionTool(part.toolName);
+          // Deferred tools (e.g. generate_document) only queue work during the
+          // stream — keep the spinner until the pipeline attaches a file.
+          const status: 'executing' | 'completed' | 'failed' = failed
+            ? 'failed'
+            : deferred
+              ? 'executing'
+              : 'completed';
+          const title = toolTitleFromInput(part.input);
+          const format = toolFieldFromInput(part.input, 'format');
+          const idx = toolPartIndexById.get(part.toolCallId);
+          if (idx !== undefined) {
+            const existing = parts[idx];
+            if (existing && existing.type === 'tool') {
+              existing.status = status;
+              if (format) existing.format = format;
+            }
+          }
+          toolCalls.push({
+            toolName: part.toolName,
+            input: part.input,
+            output: part.type === 'tool-result' ? part.output : undefined,
+            status: failed ? 'failed' : 'completed',
+          });
+          await broadcast('message-tool-call', {
+            messageId: aiMessageId,
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            ...(title ? { title } : {}),
+            ...(format ? { format } : {}),
+            status,
+          });
+          break;
+        }
+        default:
+          // ignore reasoning/source/step/finish/raw parts
+          break;
+      }
+    }
+
+    return { text: fullText, toolCalls, parts };
+  } finally {
+    if (redis) {
+      await redis.del(streamKey).catch(() => {});
+    }
+  }
+}