@studious-lms/server 1.19.0 → 1.20.0

package/src/services/aiChatStream.ts

@@ -16,6 +16,7 @@ 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';
+import { logInferenceUsage, type AiUsageAttribution } from '../utils/inference.js';
 
 const STREAM_REDIS_TTL = 600; // 10 minutes
 const STREAM_KEY_PREFIX = 'stream:';
@@ -179,6 +180,10 @@ export interface StreamChatOptions {
   maxOutputTokens?: number;
   /** Max agent steps (tool round-trips). Defaults to 6. */
   maxSteps?: number;
+  /** Reason recorded on the AiUsageLog row. Defaults to 'chat_stream'. */
+  usageReason?: string;
+  /** Who/what this usage is attributed to (user / school / class). */
+  attribution?: AiUsageAttribution;
 }
 
 export interface StreamChatResult {
@@ -207,6 +212,8 @@ export async function streamChatResponse(
     temperature = 0.7,
     maxOutputTokens = 4096,
     maxSteps = 6,
+    usageReason = 'chat_stream',
+    attribution,
   } = options;
 
   const redis = getRedis();
@@ -332,7 +339,35 @@ export async function streamChatResponse(
       }
     }
 
+    const usage = await Promise.resolve(result.totalUsage).catch(() => undefined);
+    await logInferenceUsage({
+      model,
+      operation: 'stream.text',
+      success: true,
+      estimatedInputTokens: 0,
+      reason: usageReason,
+      usage: usage
+        ? {
+            promptTokens: usage.inputTokens,
+            completionTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+          }
+        : undefined,
+      attribution,
+    });
+
     return { text: fullText, toolCalls, parts };
+  } catch (error) {
+    await logInferenceUsage({
+      model,
+      operation: 'stream.text',
+      success: false,
+      estimatedInputTokens: 0,
+      reason: usageReason,
+      error,
+      attribution,
+    });
+    throw error;
   } finally {
     if (redis) {
       await redis.del(streamKey).catch(() => {});

package/src/services/aiStream.ts

@@ -8,6 +8,7 @@ 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 { logInferenceUsage, type AiUsageAttribution } from '../utils/inference.js';
 import { logger } from '../utils/logger.js';
 import { JobStatus } from '@prisma/client';
 import { aiTools, type ToolCallResult } from './aiTools.js';
@@ -25,6 +26,10 @@ export interface StreamOptions {
   model?: string;
   temperature?: number;
   maxOutputTokens?: number;
+  /** Reason recorded on the AiUsageLog row. Defaults to 'ai_stream'. */
+  usageReason?: string;
+  /** Who/what this usage is attributed to (user / school / class). */
+  attribution?: AiUsageAttribution;
 }
 
 /**
@@ -42,6 +47,8 @@ export async function streamAIResponse(options: StreamOptions): Promise<void> {
     model = 'gpt-4o-mini',
     temperature = 0.7,
     maxOutputTokens = 4096,
+    usageReason = 'ai_stream',
+    attribution,
   } = options;
 
   await ensureAIUserExists();
@@ -146,6 +153,23 @@ export async function streamAIResponse(options: StreamOptions): Promise<void> {
       attachments: [],
     });
 
+    const usage = await Promise.resolve(result.totalUsage).catch(() => undefined);
+    await logInferenceUsage({
+      model,
+      operation: 'stream.text',
+      success: true,
+      estimatedInputTokens: 0,
+      reason: usageReason,
+      usage: usage
+        ? {
+            promptTokens: usage.inputTokens,
+            completionTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+          }
+        : undefined,
+      attribution: attribution ?? { classId },
+    });
+
     logger.info('AI stream completed', {
       aiMessageId,
       conversationId,
@@ -155,6 +179,16 @@ export async function streamAIResponse(options: StreamOptions): Promise<void> {
   } catch (error) {
     logger.error('AI stream failed', { error, aiMessageId, conversationId });
 
+    await logInferenceUsage({
+      model,
+      operation: 'stream.text',
+      success: false,
+      estimatedInputTokens: 0,
+      reason: usageReason,
+      error,
+      attribution: attribution ?? { classId },
+    });
+
     await prisma.message.update({
       where: { id: aiMessageId },
       data: { status: JobStatus.FAILED },

package/src/services/aiUsage.ts

@@ -0,0 +1,202 @@
+import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.js";
+import { findActiveSchoolAdminMembership } from "../models/school.js";
+
+export interface UsageLogRow {
+  userId: string | null;
+  model: string;
+  operation: string;
+  totalTokens: number | null;
+  promptTokens: number | null;
+  completionTokens: number | null;
+  createdAt: Date;
+}
+
+export interface UsageBucket {
+  requests: number;
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+export interface UsageAggregation {
+  totals: UsageBucket;
+  byDay: Array<{ day: string } & UsageBucket>;
+  byModel: Array<{ model: string } & UsageBucket>;
+  byOperation: Array<{ operation: string } & UsageBucket>;
+}
+
+const emptyBucket = (): UsageBucket => ({
+  requests: 0,
+  promptTokens: 0,
+  completionTokens: 0,
+  totalTokens: 0,
+});
+
+function addToBucket(bucket: UsageBucket, row: UsageLogRow) {
+  bucket.requests += 1;
+  bucket.promptTokens += row.promptTokens ?? 0;
+  bucket.completionTokens += row.completionTokens ?? 0;
+  bucket.totalTokens += row.totalTokens ?? 0;
+}
+
+/** UTC calendar day (YYYY-MM-DD) for a timestamp. */
+export function usageDayKey(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+/** Aggregate raw usage rows into totals and by-day / by-model / by-operation buckets. */
+export function aggregateUsage(rows: UsageLogRow[]): UsageAggregation {
+  const totals = emptyBucket();
+  const byDay = new Map<string, UsageBucket>();
+  const byModel = new Map<string, UsageBucket>();
+  const byOperation = new Map<string, UsageBucket>();
+
+  for (const row of rows) {
+    addToBucket(totals, row);
+
+    const dayKey = usageDayKey(row.createdAt);
+    for (const [map, key] of [
+      [byDay, dayKey],
+      [byModel, row.model],
+      [byOperation, row.operation],
+    ] as const) {
+      let bucket = map.get(key);
+      if (!bucket) {
+        bucket = emptyBucket();
+        map.set(key, bucket);
+      }
+      addToBucket(bucket, row);
+    }
+  }
+
+  return {
+    totals,
+    byDay: [...byDay.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([day, bucket]) => ({ day, ...bucket })),
+    byModel: [...byModel.entries()]
+      .sort(([, a], [, b]) => b.totalTokens - a.totalTokens)
+      .map(([model, bucket]) => ({ model, ...bucket })),
+    byOperation: [...byOperation.entries()]
+      .sort(([, a], [, b]) => b.totalTokens - a.totalTokens)
+      .map(([operation, bucket]) => ({ operation, ...bucket })),
+  };
+}
+
+/** Rank users by total token usage, descending. Rows without a userId are skipped. */
+export function aggregateTopUsers(
+  rows: UsageLogRow[],
+  limit: number,
+): Array<{ userId: string } & UsageBucket> {
+  const byUser = new Map<string, UsageBucket>();
+  for (const row of rows) {
+    if (!row.userId) continue;
+    let bucket = byUser.get(row.userId);
+    if (!bucket) {
+      bucket = emptyBucket();
+      byUser.set(row.userId, bucket);
+    }
+    addToBucket(bucket, row);
+  }
+
+  return [...byUser.entries()]
+    .sort(([, a], [, b]) => b.totalTokens - a.totalTokens)
+    .slice(0, limit)
+    .map(([userId, bucket]) => ({ userId, ...bucket }));
+}
+
+const USAGE_ROW_SELECT = {
+  userId: true,
+  model: true,
+  operation: true,
+  totalTokens: true,
+  promptTokens: true,
+  completionTokens: true,
+  createdAt: true,
+} as const;
+
+function createdAtRange(startDate?: Date, endDate?: Date) {
+  if (!startDate && !endDate) return undefined;
+  return {
+    ...(startDate ? { gte: startDate } : {}),
+    ...(endDate ? { lte: endDate } : {}),
+  };
+}
+
+/**
+ * Per-school aggregate AI usage over a date range. School admins only.
+ */
+export async function getSchoolAiUsage(
+  userId: string,
+  input: {
+    schoolId: string;
+    startDate?: Date;
+    endDate?: Date;
+    topUsersLimit?: number;
+  },
+) {
+  const membership = await findActiveSchoolAdminMembership(
+    input.schoolId,
+    userId,
+  );
+  if (!membership) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only school admins can view school AI usage",
+    });
+  }
+
+  const rows = await prisma.aiUsageLog.findMany({
+    where: {
+      schoolId: input.schoolId,
+      ...(createdAtRange(input.startDate, input.endDate)
+        ? { createdAt: createdAtRange(input.startDate, input.endDate) }
+        : {}),
+    },
+    select: USAGE_ROW_SELECT,
+  });
+
+  const topUsers = aggregateTopUsers(rows, input.topUsersLimit ?? 10);
+  const userIds = topUsers.map((entry) => entry.userId);
+  const users = userIds.length
+    ? await prisma.user.findMany({
+        where: { id: { in: userIds } },
+        select: {
+          id: true,
+          username: true,
+          profile: { select: { displayName: true } },
+        },
+      })
+    : [];
+  const userById = new Map(users.map((user) => [user.id, user]));
+
+  return {
+    ...aggregateUsage(rows),
+    topUsers: topUsers.map((entry) => ({
+      ...entry,
+      username: userById.get(entry.userId)?.username ?? null,
+      displayName: userById.get(entry.userId)?.profile?.displayName ?? null,
+    })),
+  };
+}
+
+/**
+ * The calling user's own AI usage over a date range.
+ */
+export async function getMyAiUsage(
+  userId: string,
+  input: { startDate?: Date; endDate?: Date } = {},
+) {
+  const rows = await prisma.aiUsageLog.findMany({
+    where: {
+      userId,
+      ...(createdAtRange(input.startDate, input.endDate)
+        ? { createdAt: createdAtRange(input.startDate, input.endDate) }
+        : {}),
+    },
+    select: USAGE_ROW_SELECT,
+  });
+
+  return aggregateUsage(rows);
+}

package/src/services/announcement.ts

@@ -124,6 +124,11 @@ export async function createAnnouncementRecord(
     receiverIds: classData.students.map((s) => s.id),
     title: `New announcement in ${classData.name}`,
     content: `${remarks}\n\n[View announcement](/class/${classId})`,
+    senderId: userId,
+    type: "ANNOUNCEMENT",
+    entityType: "ANNOUNCEMENT",
+    entityId: announcement.id,
+    classId,
   }).catch((error) => {
     logger.error("Failed to send announcement notifications:", error);
   });

package/src/services/assignment.ts

@@ -23,7 +23,7 @@ import {
 } from "../models/assignment.js";
 import { createDirectUploadFiles, type UploadedFile } from "../lib/fileUpload.js";
 import { deleteFile } from "../lib/googleCloudStorage.js";
-import { sendToMultiple } from "./notification.js";
+import { sendNotification, sendToMultiple } from "./notification.js";
 import { enqueueRunJob } from "../workers/queues.js";
 import { logger } from "../utils/logger.js";
 import { invalidateStudentProgressInferenceCache } from "./studentProgressInferenceCache.js";
@@ -317,6 +317,11 @@ export async function createAssignmentRecord(
       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})`,
+      senderId: userId,
+      type: "ASSIGNMENT_POSTED",
+      entityType: "ASSIGNMENT",
+      entityId: assignment.id,
+      classId,
     }).catch((error) => {
       logger.error("Failed to send assignment notifications:", error);
     });
@@ -607,6 +612,11 @@ export async function updateAssignmentRecord(
       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})`,
+      senderId: userId,
+      type: "ASSIGNMENT_POSTED",
+      entityType: "ASSIGNMENT",
+      entityId: updatedAssignment.id,
+      classId: classData.id,
     }).catch((error) => {
       logger.error("Failed to send assignment publish notifications:", error);
     });
@@ -877,11 +887,28 @@ export async function updateSubmissionAsTeacherRecord(
   }
 
   if (returnSubmission !== undefined) {
-    return prisma.submission.update({
+    const updated = await prisma.submission.update({
       where: { id: submissionId },
       data: { returned: !submission.returned },
       include: submissionTeacherInclude,
     });
+
+    if (updated.returned) {
+      sendNotification({
+        receiverId: submission.studentId,
+        title: `Assignment returned in ${submission.assignment.class.name}`,
+        content: `"${submission.assignment.title}" has been returned.\n\n[View assignment](/class/${submission.assignment.class.id}/assignments/${submission.assignment.id})`,
+        senderId: teacherId,
+        type: "ASSIGNMENT_RETURNED",
+        entityType: "ASSIGNMENT",
+        entityId: submission.assignment.id,
+        classId: submission.assignment.class.id,
+      }).catch((error) => {
+        logger.error("Failed to send assignment returned notification:", error);
+      });
+    }
+
+    return updated;
   }
 
   if (existingFileIds?.length) {

package/src/services/attendance.ts

@@ -143,11 +143,19 @@ async function notifyMarkedLateOrAbsent(input: {
       receiverIds: lateReceiverIds,
       title: `Marked late in ${input.className}`,
       content: `You were marked late for ${attendanceLabel}.\n[View attendance](${link})`,
+      type: "ATTENDANCE",
+      entityType: "ATTENDANCE",
+      entityId: input.eventId,
+      classId: input.classId,
     }),
     sendAttendanceNotification({
       receiverIds: absentReceiverIds,
       title: `Marked absent in ${input.className}`,
       content: `You were marked absent for ${attendanceLabel}.\n[View attendance](${link})`,
+      type: "ATTENDANCE",
+      entityType: "ATTENDANCE",
+      entityId: input.eventId,
+      classId: input.classId,
     }),
   ]);
 }
@@ -157,6 +165,10 @@ async function sendAttendanceNotification(input: {
   receiverIds: string[];
   title: string;
   content: string;
+  type: "ATTENDANCE";
+  entityType: string;
+  entityId: string | null;
+  classId: string;
 }) {
   if (input.receiverIds.length === 0) {
     return;

package/src/services/class.ts

@@ -785,6 +785,10 @@ export async function publishLabDraft(
       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})`,
+      type: "ASSIGNMENT_POSTED",
+      entityType: "ASSIGNMENT",
+      entityId: published.id,
+      classId,
     }).catch((error) => {
       logger.error("Failed to send lab draft publish notifications:", error);
     });

package/src/services/discussion.ts

@@ -1,4 +1,4 @@
-import type { DiscussionType, Prisma, ReactionType } from "@prisma/client";
+import type { DiscussionType, NotificationType, Prisma, ReactionType } from "@prisma/client";
 import type { AppTransactionClient } from "../lib/prisma.js";
 import { TRPCError } from "@trpc/server";
 import { prisma } from "../lib/prisma.js";
@@ -266,14 +266,29 @@ function triggerDiscussionEvent(classId: string, event: string, payload: unknown
   });
 }
 
-async function notify(receiverId: string | null | undefined, senderId: string, title: string, content: string) {
+async function notify(
+  receiverId: string | null | undefined,
+  senderId: string,
+  title: string,
+  content: string,
+  meta: { type: NotificationType; classId: string; discussionId: string }
+) {
   if (!receiverId || receiverId === senderId) return;
-  await sendNotification({ receiverId, title, content }).catch((error) => {
+  await sendNotification({
+    receiverId,
+    senderId,
+    title,
+    content,
+    type: meta.type,
+    entityType: "DISCUSSION",
+    entityId: meta.discussionId,
+    classId: meta.classId,
+  }).catch((error) => {
     logger.error("Failed to send discussion notification", { receiverId, error });
   });
 }
 
-async function notifyMentionedUsers(classId: string, senderId: string, body: string, link: string) {
+async function notifyMentionedUsers(classId: string, senderId: string, body: string, link: string, discussionId: string) {
   const usernames = [...new Set(Array.from(body.matchAll(/(^|\s)@([a-zA-Z0-9_.-]{2,32})/g)).map((match) => match[2]))];
   if (!usernames.length) return;
   const members = await prisma.user.findMany({
@@ -287,7 +302,15 @@ async function notifyMentionedUsers(classId: string, senderId: string, body: str
     },
     select: { id: true },
   });
-  await Promise.all(members.map((member) => notify(member.id, senderId, "You were mentioned in a discussion", link)));
+  await Promise.all(
+    members.map((member) =>
+      notify(member.id, senderId, "You were mentioned in a discussion", link, {
+        type: "DISCUSSION_MENTION",
+        classId,
+        discussionId,
+      })
+    )
+  );
 }
 
 async function unreadCountsForDiscussions(userId: string, discussionIds: string[]) {
@@ -441,7 +464,7 @@ export async function createDiscussion(userId: string, input: {
   });
 
   triggerDiscussionEvent(input.classId, "discussion-created", { discussion: serializeDiscussion(discussion, userId) });
-  await notifyMentionedUsers(input.classId, userId, input.body, `/class/${input.classId}/discussions/${discussion.id}`);
+  await notifyMentionedUsers(input.classId, userId, input.body, `/class/${input.classId}/discussions/${discussion.id}`, discussion.id);
 
   // Auto-index discussion for RAG search
   enqueueEmbedding(input.classId, 'DISCUSSION', discussion.id);
@@ -530,9 +553,17 @@ export async function replyToDiscussion(userId: string, input: {
   });
   const link = `/class/${discussion.classId}/discussions/${discussion.id}#${reply.id}`;
   await Promise.all([
-    notify(discussion.authorId, userId, "New reply to your discussion", link),
-    notify(parent?.authorId, userId, "New reply in a discussion thread", link),
-    notifyMentionedUsers(discussion.classId, userId, input.body, link),
+    notify(discussion.authorId, userId, "New reply to your discussion", link, {
+      type: "DISCUSSION_REPLY",
+      classId: discussion.classId,
+      discussionId: discussion.id,
+    }),
+    notify(parent?.authorId, userId, "New reply in a discussion thread", link, {
+      type: "DISCUSSION_REPLY",
+      classId: discussion.classId,
+      discussionId: discussion.id,
+    }),
+    notifyMentionedUsers(discussion.classId, userId, input.body, link, discussion.id),
   ]);
   triggerDiscussionEvent(discussion.classId, "reply-created", { discussionId: discussion.id, reply: serializeReply(reply, userId) });
 
@@ -582,7 +613,11 @@ export async function pinDiscussion(userId: string, discussionId: string, isPinn
   const { discussion, isTeacher } = await getDiscussionForUser(discussionId, userId);
   if (!isTeacher) throw new TRPCError({ code: "FORBIDDEN", message: "Only teachers can pin discussions" });
   const updated = await prisma.discussion.update({ where: { id: discussionId }, data: { isPinned }, include: discussionInclude });
-  await notify(discussion.authorId, userId, isPinned ? "Your discussion was pinned" : "Your discussion was unpinned", `/class/${discussion.classId}/discussions/${discussionId}`);
+  await notify(discussion.authorId, userId, isPinned ? "Your discussion was pinned" : "Your discussion was unpinned", `/class/${discussion.classId}/discussions/${discussionId}`, {
+    type: "DISCUSSION_REPLY",
+    classId: discussion.classId,
+    discussionId,
+  });
   triggerDiscussionEvent(discussion.classId, "discussion-updated", { discussion: serializeDiscussion(updated, userId) });
   return { discussion: serializeDiscussion(updated, userId) };
 }
@@ -611,7 +646,11 @@ export async function markAcceptedAnswer(userId: string, replyId: string, accept
     }
     return tx.discussionReply.update({ where: { id: replyId }, data: { isAcceptedAnswer: accepted }, include: replyInclude });
   });
-  await notify(reply.authorId, userId, accepted ? "Your answer was accepted" : "Your answer was unmarked", `/class/${reply.discussion.classId}/discussions/${reply.discussionId}#${replyId}`);
+  await notify(reply.authorId, userId, accepted ? "Your answer was accepted" : "Your answer was unmarked", `/class/${reply.discussion.classId}/discussions/${reply.discussionId}#${replyId}`, {
+    type: "DISCUSSION_REPLY",
+    classId: reply.discussion.classId,
+    discussionId: reply.discussionId,
+  });
   triggerDiscussionEvent(reply.discussion.classId, "reply-updated", { discussionId: reply.discussionId, reply: serializeReply(updated, userId) });
   return { reply: serializeReply(updated, userId) };
 }

package/src/services/discussionSummary.ts

@@ -215,6 +215,7 @@ export async function getDiscussionSummary(
     {
       reason: "discussion_summary",
       metadata: { discussionId, classId: discussion.classId },
+      attribution: { userId, classId: discussion.classId },
     },
   );