@studious-lms/server 1.12.0 → 1.14.0

package/src/services/discussionSummary.ts

@@ -0,0 +1,226 @@
+/**
+ * AI-powered discussion summary service with in-memory + Redis caching.
+ */
+import { prisma } from "../lib/prisma.js";
+import { getRedis } from "../lib/redis.js";
+import { inference } from "../utils/inference.js";
+import { logger } from "../utils/logger.js";
+import { TRPCError } from "@trpc/server";
+import { z } from "zod";
+import { classMemberOrSchoolAdminWhere } from "../models/access.js";
+
+const discussionSummarySchema = z.object({
+  summary: z
+    .string()
+    .describe("A concise 2-4 sentence TL;DR of the entire discussion thread."),
+  keyQuestions: z
+    .array(z.string())
+    .describe("Up to 5 important student questions raised in the thread."),
+  unresolvedIssues: z
+    .array(z.string())
+    .describe(
+      "Up to 3 questions or topics that remain unanswered or unresolved.",
+    ),
+  participantCount: z
+    .number()
+    .describe("Number of unique participants in the thread."),
+});
+
+export type DiscussionSummary = z.infer<typeof discussionSummarySchema>;
+
+const REDIS_PREFIX = "discussionSummary:";
+const REDIS_TTL_SECONDS = 60 * 30; // 30 min
+
+const memoryCache = new Map<
+  string,
+  { value: DiscussionSummary; replyCount: number; cachedAt: number }
+>();
+const MEMORY_TTL_MS = 10 * 60 * 1000; // 10 min
+
+function memoryCacheKey(discussionId: string) {
+  return discussionId;
+}
+
+function getMemoryCacheHit(
+  discussionId: string,
+  currentReplyCount: number,
+): DiscussionSummary | undefined {
+  const entry = memoryCache.get(memoryCacheKey(discussionId));
+  if (!entry) return undefined;
+  if (Date.now() - entry.cachedAt > MEMORY_TTL_MS) {
+    memoryCache.delete(memoryCacheKey(discussionId));
+    return undefined;
+  }
+  if (entry.replyCount !== currentReplyCount) {
+    memoryCache.delete(memoryCacheKey(discussionId));
+    return undefined;
+  }
+  return entry.value;
+}
+
+function setMemoryCache(
+  discussionId: string,
+  value: DiscussionSummary,
+  replyCount: number,
+) {
+  memoryCache.set(memoryCacheKey(discussionId), {
+    value,
+    replyCount,
+    cachedAt: Date.now(),
+  });
+}
+
+async function getRedisCacheHit(
+  discussionId: string,
+  currentReplyCount: number,
+): Promise<DiscussionSummary | undefined> {
+  const redis = getRedis();
+  if (!redis) return undefined;
+  try {
+    const raw = await redis.get(`${REDIS_PREFIX}${discussionId}`);
+    if (!raw) return undefined;
+    const parsed = JSON.parse(raw) as {
+      value: DiscussionSummary;
+      replyCount: number;
+    };
+    if (parsed.replyCount !== currentReplyCount) return undefined;
+    return parsed.value;
+  } catch {
+    return undefined;
+  }
+}
+
+async function setRedisCache(
+  discussionId: string,
+  value: DiscussionSummary,
+  replyCount: number,
+) {
+  const redis = getRedis();
+  if (!redis) return;
+  try {
+    await redis.set(
+      `${REDIS_PREFIX}${discussionId}`,
+      JSON.stringify({ value, replyCount }),
+      "EX",
+      REDIS_TTL_SECONDS,
+    );
+  } catch (err) {
+    logger.error("Failed to cache discussion summary in Redis", { err });
+  }
+}
+
+export async function getDiscussionSummary(
+  userId: string,
+  discussionId: string,
+): Promise<DiscussionSummary> {
+  const discussion = await prisma.discussion.findUnique({
+    where: { id: discussionId },
+    select: {
+      id: true,
+      classId: true,
+      title: true,
+      body: true,
+      type: true,
+      replies: {
+        where: { deletedAt: null },
+        select: {
+          body: true,
+          author: {
+            select: {
+              username: true,
+              profile: { select: { displayName: true } },
+            },
+          },
+          createdAt: true,
+        },
+        orderBy: { createdAt: "asc" },
+      },
+      author: {
+        select: {
+          username: true,
+          profile: { select: { displayName: true } },
+        },
+      },
+    },
+  });
+
+  if (!discussion) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Discussion not found",
+    });
+  }
+
+  // Verify user is a member of the class
+  const classMembership = await prisma.class.findFirst({
+    where: { id: discussion.classId, ...classMemberOrSchoolAdminWhere(userId) },
+    select: { id: true },
+  });
+  if (!classMembership) {
+    throw new TRPCError({
+      code: "UNAUTHORIZED",
+      message: "You are not a member of this class",
+    });
+  }
+
+  const replyCount = discussion.replies.length;
+
+  // Check memory cache
+  const memoryCached = getMemoryCacheHit(discussionId, replyCount);
+  if (memoryCached) return memoryCached;
+
+  // Check Redis cache
+  const redisCached = await getRedisCacheHit(discussionId, replyCount);
+  if (redisCached) {
+    setMemoryCache(discussionId, redisCached, replyCount);
+    return redisCached;
+  }
+
+  // Build context for inference
+  const authorName =
+    discussion.author.profile?.displayName ?? discussion.author.username;
+  const threadText = [
+    `Title: ${discussion.title}`,
+    `Type: ${discussion.type}`,
+    `Author: ${authorName}`,
+    `Original post:\n${discussion.body}`,
+    "",
+    ...discussion.replies.map((reply, i) => {
+      const name =
+        reply.author.profile?.displayName ?? reply.author.username;
+      return `Reply ${i + 1} by ${name}:\n${reply.body}`;
+    }),
+  ].join("\n\n");
+
+  const messages = [
+    {
+      role: "system" as const,
+      content:
+        "You are a helpful assistant summarizing a class discussion thread for a teacher. Be concise, specific, and grounded in the actual content. Do not fabricate information.",
+    },
+    {
+      role: "user" as const,
+      content: threadText,
+    },
+    {
+      role: "user" as const,
+      content:
+        "Generate a structured summary of this discussion thread. Include a TL;DR, key student questions, and any unresolved issues.",
+    },
+  ];
+
+  const result = await inference<DiscussionSummary>(
+    messages,
+    discussionSummarySchema,
+    {
+      reason: "discussion_summary",
+      metadata: { discussionId, classId: discussion.classId },
+    },
+  );
+
+  // Cache result
+  setMemoryCache(discussionId, result, replyCount);
+  await setRedisCache(discussionId, result, replyCount);
+
+  return result;
+}

package/src/services/embedding.ts

@@ -0,0 +1,285 @@
+/**
+ * Embedding service – pgvector-backed RAG for class materials.
+ * Handles text chunking, embedding generation, storage, and semantic search.
+ */
+import { prisma } from '../lib/prisma.js';
+import { openAIClient } from '../utils/inference.js';
+import { logger } from '../utils/logger.js';
+import { enqueueRunJob } from '../workers/queues.js';
+import type { EmbeddingSourceType } from '@prisma/client';
+
+const EMBEDDING_MODEL = 'text-embedding-3-small';
+const EMBEDDING_DIMENSIONS = 1536;
+const CHUNK_SIZE = 512; // tokens (~2048 chars)
+const CHUNK_OVERLAP = 100; // tokens (~400 chars)
+const CHARS_PER_TOKEN = 4;
+
+export interface EmbeddingSearchResult {
+  id: string;
+  sourceType: EmbeddingSourceType;
+  sourceId: string;
+  content: string;
+  metadata: Record<string, unknown>;
+  similarity: number;
+}
+
+/**
+ * Split text into overlapping chunks for embedding.
+ */
+export function chunkText(text: string, chunkSize = CHUNK_SIZE, overlap = CHUNK_OVERLAP): string[] {
+  const maxChars = chunkSize * CHARS_PER_TOKEN;
+  const overlapChars = overlap * CHARS_PER_TOKEN;
+
+  if (text.length <= maxChars) {
+    return [text];
+  }
+
+  const chunks: string[] = [];
+  let start = 0;
+
+  while (start < text.length) {
+    const end = Math.min(start + maxChars, text.length);
+    chunks.push(text.slice(start, end));
+
+    if (end >= text.length) break;
+    start = end - overlapChars;
+  }
+
+  return chunks;
+}
+
+/**
+ * Generate embedding vector for a text string.
+ */
+export async function generateEmbedding(text: string): Promise<number[]> {
+  const response = await openAIClient.embeddings.create({
+    model: EMBEDDING_MODEL,
+    input: text,
+    dimensions: EMBEDDING_DIMENSIONS,
+  });
+
+  return response.data[0].embedding;
+}
+
+/**
+ * Generate embeddings for multiple texts in a single batch.
+ */
+export async function generateEmbeddings(texts: string[]): Promise<number[][]> {
+  if (texts.length === 0) return [];
+
+  const response = await openAIClient.embeddings.create({
+    model: EMBEDDING_MODEL,
+    input: texts,
+    dimensions: EMBEDDING_DIMENSIONS,
+  });
+
+  return response.data
+    .sort((a, b) => a.index - b.index)
+    .map((item) => item.embedding);
+}
+
+/**
+ * Store embeddings for a source document. Replaces any existing embeddings for
+ * the same sourceType + sourceId combination.
+ */
+export async function indexContent(params: {
+  classId: string;
+  sourceType: EmbeddingSourceType;
+  sourceId: string;
+  text: string;
+  metadata?: Record<string, unknown>;
+}): Promise<number> {
+  const { classId, sourceType, sourceId, text, metadata = {} } = params;
+
+  // Remove existing embeddings for this source
+  await prisma.embedding.deleteMany({
+    where: { classId, sourceType, sourceId },
+  });
+
+  const chunks = chunkText(text);
+  if (chunks.length === 0) return 0;
+
+  const embeddings = await generateEmbeddings(chunks);
+
+  // Insert using raw SQL for pgvector support
+  for (let i = 0; i < chunks.length; i++) {
+    const vectorStr = `[${embeddings[i].join(',')}]`;
+    const chunkMetadata = { ...metadata, chunkIndex: i, totalChunks: chunks.length };
+
+    await prisma.$executeRaw`
+      INSERT INTO "Embedding" (id, "classId", "sourceType", "sourceId", content, vector, metadata, "createdAt")
+      VALUES (
+        gen_random_uuid(),
+        ${classId},
+        ${sourceType}::"EmbeddingSourceType",
+        ${sourceId},
+        ${chunks[i]},
+        ${vectorStr}::vector,
+        ${JSON.stringify(chunkMetadata)}::jsonb,
+        NOW()
+      )
+    `;
+  }
+
+  logger.info('Content indexed', { classId, sourceType, sourceId, chunks: chunks.length });
+  return chunks.length;
+}
+
+/**
+ * Semantic search over class embeddings using cosine similarity.
+ */
+export async function searchEmbeddings(params: {
+  classId: string;
+  query: string;
+  limit?: number;
+  sourceTypes?: EmbeddingSourceType[];
+}): Promise<EmbeddingSearchResult[]> {
+  const { classId, query, limit = 5, sourceTypes } = params;
+
+  const queryEmbedding = await generateEmbedding(query);
+  const vectorStr = `[${queryEmbedding.join(',')}]`;
+
+  let results: EmbeddingSearchResult[];
+
+  if (sourceTypes && sourceTypes.length > 0) {
+    results = await prisma.$queryRaw<EmbeddingSearchResult[]>`
+      SELECT
+        id,
+        "sourceType",
+        "sourceId",
+        content,
+        metadata,
+        1 - (vector <=> ${vectorStr}::vector) as similarity
+      FROM "Embedding"
+      WHERE "classId" = ${classId}
+        AND "sourceType" = ANY(${sourceTypes}::"EmbeddingSourceType"[])
+      ORDER BY vector <=> ${vectorStr}::vector
+      LIMIT ${limit}
+    `;
+  } else {
+    results = await prisma.$queryRaw<EmbeddingSearchResult[]>`
+      SELECT
+        id,
+        "sourceType",
+        "sourceId",
+        content,
+        metadata,
+        1 - (vector <=> ${vectorStr}::vector) as similarity
+      FROM "Embedding"
+      WHERE "classId" = ${classId}
+      ORDER BY vector <=> ${vectorStr}::vector
+      LIMIT ${limit}
+    `;
+  }
+
+  return results;
+}
+
+/**
+ * Remove all embeddings for a given source.
+ */
+export async function removeEmbeddings(params: {
+  classId: string;
+  sourceType: EmbeddingSourceType;
+  sourceId: string;
+}): Promise<void> {
+  await prisma.embedding.deleteMany({
+    where: {
+      classId: params.classId,
+      sourceType: params.sourceType,
+      sourceId: params.sourceId,
+    },
+  });
+}
+
+/**
+ * Index an assignment (title + instructions) into the vector store.
+ */
+export async function indexAssignment(classId: string, assignmentId: string): Promise<void> {
+  const assignment = await prisma.assignment.findUnique({
+    where: { id: assignmentId },
+    select: { title: true, instructions: true, type: true },
+  });
+
+  if (!assignment) return;
+
+  const text = [
+    `Title: ${assignment.title}`,
+    `Type: ${assignment.type}`,
+    assignment.instructions ? `Instructions: ${assignment.instructions}` : '',
+  ].filter(Boolean).join('\n');
+
+  await indexContent({
+    classId,
+    sourceType: 'ASSIGNMENT',
+    sourceId: assignmentId,
+    text,
+    metadata: { title: assignment.title, type: assignment.type },
+  });
+}
+
+/**
+ * Index a worksheet (questions + answers) into the vector store.
+ */
+export async function indexWorksheet(classId: string, worksheetId: string): Promise<void> {
+  const worksheet = await prisma.worksheet.findUnique({
+    where: { id: worksheetId },
+    include: { questions: true },
+  });
+
+  if (!worksheet) return;
+
+  const questionTexts = worksheet.questions.map((q, i) =>
+    `Question ${i + 1} (${q.type}): ${q.question}\nAnswer: ${q.answer}`
+  );
+
+  const text = [
+    `Worksheet: ${worksheet.name}`,
+    ...questionTexts,
+  ].join('\n\n');
+
+  await indexContent({
+    classId,
+    sourceType: 'WORKSHEET',
+    sourceId: worksheetId,
+    text,
+    metadata: { name: worksheet.name, questionCount: worksheet.questions.length },
+  });
+}
+
+/**
+ * Index an announcement into the vector store.
+ */
+export async function indexAnnouncement(classId: string, announcementId: string): Promise<void> {
+  const announcement = await prisma.announcement.findUnique({
+    where: { id: announcementId },
+    select: { remarks: true, teacherId: true },
+  });
+
+  if (!announcement || !announcement.remarks) return;
+
+  const text = `Announcement: ${announcement.remarks}`;
+
+  await indexContent({
+    classId,
+    sourceType: 'ANNOUNCEMENT',
+    sourceId: announcementId,
+    text,
+    metadata: { teacherId: announcement.teacherId },
+  });
+}
+
+/**
+ * Fire-and-forget: enqueue a background job to embed content.
+ * Safe to call from service functions after a create/update.
+ */
+export function enqueueEmbedding(
+  classId: string,
+  sourceType: EmbeddingSourceType,
+  sourceId: string,
+): void {
+  enqueueRunJob('EMBED_CONTENT', { classId, sourceType: sourceType as string, sourceId }, { classId })
+    .catch((err) => {
+      logger.error('Failed to enqueue embedding job', { err, classId, sourceType, sourceId });
+    });
+}

package/src/services/message.ts

@@ -2,7 +2,7 @@
  * Message service – send, update, delete messages; mark as read; track mentions.
  * Broadcasts real-time updates via Pusher.
  */
-import type { Prisma } from "@prisma/client";
+import type { AppTransactionClient } from "../lib/prisma.js";
 import { TRPCError } from "@trpc/server";
 import { prisma } from "../lib/prisma.js";
 import { chatChannel, pusher } from "../lib/pusher.js";
@@ -35,7 +35,7 @@ export function ensureMessageHasContentOrAttachments(
 }
 
 export async function claimMessageAttachments(
-  tx: Prisma.TransactionClient,
+  tx: AppTransactionClient,
   userId: string,
   conversationId: string,
   messageId: string,

package/src/services/search.ts

@@ -1,4 +1,7 @@
 import { prisma } from "../lib/prisma.js";
+import { generateEmbedding } from "./embedding.js";
+import { logger } from "../utils/logger.js";
+import type { EmbeddingSourceType } from "@prisma/client";
 
 type SearchScope =
   | "class"
@@ -395,3 +398,138 @@ export async function searchGlobalClasses(
 
   return { query, results: trimResults(results, limit) };
 }
+
+const SOURCE_TYPE_TO_SCOPE: Record<EmbeddingSourceType, SearchScope> = {
+  ASSIGNMENT: "assignment",
+  WORKSHEET: "worksheet",
+  ANNOUNCEMENT: "announcement",
+  FILE: "file",
+  SECTION: "section",
+};
+
+const MIN_SIMILARITY = 0.25;
+
+/**
+ * Cross-class semantic search via pgvector.
+ * Generates an embedding for `query`, searches across all classes the user
+ * belongs to, and maps hits back to SearchResult shape.
+ */
+export async function searchSemanticGlobal(
+  userId: string,
+  input: { query: string; limit?: number },
+) {
+  const query = input.query.trim().slice(0, 200);
+  if (!query) {
+    return { query, results: [] as SearchResult[] };
+  }
+  const limit = Math.min(Math.max(input.limit ?? SEARCH_LIMIT, 1), 30);
+
+  const memberships = await prisma.class.findMany({
+    where: {
+      OR: [
+        { teachers: { some: { id: userId } } },
+        { students: { some: { id: userId } } },
+      ],
+    },
+    select: { id: true, name: true },
+  });
+  const allClassIds = memberships.map((cls) => cls.id);
+  if (allClassIds.length === 0) {
+    return { query, results: [] as SearchResult[] };
+  }
+  const classById = new Map(memberships.map((cls) => [cls.id, cls]));
+
+  let queryVector: number[];
+  try {
+    queryVector = await generateEmbedding(query);
+  } catch (err) {
+    logger.error("Semantic search embedding failed", { err });
+    return { query, results: [] as SearchResult[] };
+  }
+
+  const vectorStr = `[${queryVector.join(",")}]`;
+
+  type SemanticRow = {
+    sourceType: EmbeddingSourceType;
+    sourceId: string;
+    classId: string;
+    content: string;
+    similarity: number;
+  };
+
+  const hits = await prisma.$queryRaw<SemanticRow[]>`
+    SELECT DISTINCT ON ("sourceType", "sourceId")
+      "sourceType",
+      "sourceId",
+      "classId",
+      content,
+      1 - (vector <=> ${vectorStr}::vector) as similarity
+    FROM "Embedding"
+    WHERE "classId" = ANY(${allClassIds}::text[])
+    ORDER BY "sourceType", "sourceId", vector <=> ${vectorStr}::vector
+    LIMIT ${limit * 3}
+  `;
+
+  const filtered = hits
+    .filter((h) => h.similarity >= MIN_SIMILARITY)
+    .sort((a, b) => b.similarity - a.similarity)
+    .slice(0, limit);
+
+  const results: SearchResult[] = [];
+  for (const hit of filtered) {
+    const cls = classById.get(hit.classId);
+    const className = cls?.name ?? "Class";
+    const scope = SOURCE_TYPE_TO_SCOPE[hit.sourceType];
+    if (!scope) continue;
+
+    const snippet = hit.content.replace(/\s+/g, " ").trim().slice(0, 140);
+
+    let title = snippet.slice(0, 60);
+    let href = `/class/${hit.classId}`;
+
+    if (scope === "assignment") {
+      const assignment = await prisma.assignment.findUnique({
+        where: { id: hit.sourceId },
+        select: { title: true },
+      });
+      title = assignment?.title ?? title;
+      href = `/class/${hit.classId}/assignment/${hit.sourceId}`;
+    } else if (scope === "worksheet") {
+      const worksheet = await prisma.worksheet.findUnique({
+        where: { id: hit.sourceId },
+        select: { name: true },
+      });
+      title = worksheet?.name ?? title;
+      href = `/class/${hit.classId}/worksheets`;
+    } else if (scope === "announcement") {
+      href = `/class/${hit.classId}`;
+    } else if (scope === "file") {
+      const file = await prisma.file.findUnique({
+        where: { id: hit.sourceId },
+        select: { name: true },
+      });
+      title = file?.name ?? title;
+      href = `/class/${hit.classId}/files`;
+    } else if (scope === "section") {
+      const section = await prisma.section.findUnique({
+        where: { id: hit.sourceId },
+        select: { name: true },
+      });
+      title = section?.name ?? title;
+      href = `/class/${hit.classId}/assignments`;
+    }
+
+    results.push({
+      id: `semantic:${hit.sourceId}`,
+      type: scope,
+      title,
+      subtitle: `${className} · ${scope.charAt(0).toUpperCase() + scope.slice(1)}`,
+      classId: hit.classId,
+      className,
+      href,
+      matchedText: snippet,
+    });
+  }
+
+  return { query, results };
+}