@studious-lms/server 1.9.0 → 1.12.0

package/src/services/studentProgress.ts

@@ -3,10 +3,15 @@
  */
 import { TRPCError } from "@trpc/server";
 import type { AssignmentType } from "@prisma/client";
+import { z } from "zod";
 import { prisma } from "../lib/prisma.js";
 import { isTeacherInClass } from "../models/class.js";
 import { inference } from "../utils/inference.js";
 import { logger } from "../utils/logger.js";
+import {
+  getStudentProgressInferenceCacheHit,
+  setStudentProgressInferenceCache,
+} from "./studentProgressInferenceCache.js";
 
 type ProgressChatMessage = {
   role: "user" | "assistant";
@@ -38,10 +43,38 @@ type ProgressStudent = {
   profile: { displayName: string | null } | null;
 };
 
-type RecommendationType =
-  | "missing"
-  | "low_score"
-  | "awaiting_feedback";
+const insightItemSchema = z.object({
+  label: z.string(),
+  evidence: z.string(),
+});
+
+const studentProgressInsightsSchema = z.object({
+  summary: z.string(),
+  strengths: z.array(insightItemSchema).min(2).max(4),
+  growth: z.array(insightItemSchema).min(2).max(4),
+  talkingPoints: z.array(z.string()).min(3).max(5),
+});
+
+const studentProgressForecastSchema = z.object({
+  forecastLow: z.number().min(0).max(100),
+  forecastHigh: z.number().min(0).max(100),
+  risk: z.enum(["on_track", "watch", "at_risk"]),
+  reason: z.string(),
+});
+
+const studentProgressFocusSchema = z.object({
+  focusItems: z.array(z.string()).min(3).max(5),
+});
+
+export type StudentProgressInsights = z.infer<
+  typeof studentProgressInsightsSchema
+>;
+export type StudentProgressForecast = z.infer<
+  typeof studentProgressForecastSchema
+>;
+export type StudentProgressFocus = z.infer<typeof studentProgressFocusSchema>;
+
+type RecommendationType = "missing" | "low_score" | "awaiting_feedback";
 
 function calculatePercentage(submission: GradeSubmission) {
   if (submission.gradeReceived == null || !submission.assignment.maxGrade) {
@@ -131,8 +164,7 @@ function buildSuggestedAssignment(
       percentage != null
         ? `${displayName} scored ${percentage}% and needs targeted reinforcement on the underlying concepts.`
         : `${displayName} needs targeted reinforcement on the underlying concepts.`,
-    awaiting_feedback:
-      `${displayName} has work in progress here, so a short follow-up can keep momentum once feedback lands.`,
+    awaiting_feedback: `${displayName} has work in progress here, so a short follow-up can keep momentum once feedback lands.`,
   };
 
   return {
@@ -429,9 +461,14 @@ export async function getStudentProgressRecommendations(
     studentId,
   );
 
-  const summary = await summarizeStudentRecommendationsWithCases(student, submissions);
-  const { recommendationCandidates: _recommendationCandidates, ...summaryResponse } =
-    summary;
+  const summary = await summarizeStudentRecommendationsWithCases(
+    student,
+    submissions,
+  );
+  const {
+    recommendationCandidates: _recommendationCandidates,
+    ...summaryResponse
+  } = summary;
   return {
     student: summaryResponse.student,
     summary: summaryResponse.summary,
@@ -498,7 +535,10 @@ export async function getClassProgressRecommendations(
       ),
     )
   )
-    .map(({ recommendationCandidates: _recommendationCandidates, ...student }) => student)
+    .map(
+      ({ recommendationCandidates: _recommendationCandidates, ...student }) =>
+        student,
+    )
     .filter((student) => student.recommendations.length > 0)
     .sort((a, b) => b.priorityScore - a.priorityScore);
 
@@ -591,6 +631,225 @@ function buildProgressSummary(submissions: GradeSubmission[]) {
   }));
 }
 
+function buildStructuredProgressContext(
+  classData: { id: string; name: string; subject: string | null },
+  student: ProgressStudent,
+  submissions: GradeSubmission[],
+) {
+  const displayName = student.profile?.displayName ?? student.username;
+  const recommendationSummary = summarizeStudentRecommendations(
+    student,
+    submissions,
+  );
+
+  return {
+    class: classData,
+    student: { id: student.id, username: student.username, displayName },
+    progress: {
+      overallGrade: getOverallGrade(submissions),
+      trend: calculateTrend(submissions),
+      summary: recommendationSummary.summary,
+      assignments: buildProgressSummary(submissions),
+      recommendations: recommendationSummary.recommendations.map(
+        (recommendation) => ({
+          title: recommendation.title,
+          recommendationType: recommendation.recommendationType,
+          percentage: recommendation.percentage,
+          submitted: recommendation.submitted,
+          reasons: recommendation.reasons,
+          sectionName: recommendation.sectionName,
+        }),
+      ),
+    },
+  };
+}
+
+function buildStructuredInferenceMessages(
+  instruction: string,
+  context: ReturnType<typeof buildStructuredProgressContext>,
+) {
+  return [
+    {
+      role: "system" as const,
+      content:
+        "You are an educational progress analyst. Use only the provided class and grade context. Be specific, concise, supportive, and do not fabricate assignments, grades, or sections.",
+    },
+    {
+      role: "user" as const,
+      content: JSON.stringify(context),
+    },
+    {
+      role: "user" as const,
+      content: instruction,
+    },
+  ];
+}
+
+type ProgressInferenceCacheRow<T> = {
+  epoch: number;
+  cachedAt: number;
+  value: T;
+};
+
+const studentProgressInsightsCache = new Map<
+  string,
+  ProgressInferenceCacheRow<StudentProgressInsights>
+>();
+const studentProgressForecastCache = new Map<
+  string,
+  ProgressInferenceCacheRow<StudentProgressForecast>
+>();
+const studentProgressFocusCache = new Map<
+  string,
+  ProgressInferenceCacheRow<StudentProgressFocus>
+>();
+
+export async function getStudentProgressInsights(
+  viewerId: string,
+  classId: string,
+  studentId: string,
+) {
+  const cached = getStudentProgressInferenceCacheHit(
+    studentProgressInsightsCache,
+    classId,
+    studentId,
+  );
+
+  const { classData, student, submissions } = await loadStudentProgressContext(
+    viewerId,
+    classId,
+    studentId,
+  );
+
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const context = buildStructuredProgressContext(
+    classData,
+    student,
+    submissions,
+  );
+
+  const value = await inference<StudentProgressInsights>(
+    buildStructuredInferenceMessages(
+      [
+        "Generate an AI analytics summary for this one student's dashboard.",
+        "The summary must be 2-4 plain-prose sentences: lead with overall grade and trajectory, then call out one strength and one concern with assignment titles.",
+        "Strengths and growth items need 2-6 word labels and one-line evidence grounded in assignment titles or sections.",
+        "Talking points must be 3-5 specific teacher check-in prompts with no numbering.",
+      ].join(" "),
+      context,
+    ),
+    studentProgressInsightsSchema,
+    {
+      reason: "student_progress_insights",
+      metadata: { viewerId, classId, studentId },
+    },
+  );
+  setStudentProgressInferenceCache(
+    studentProgressInsightsCache,
+    classId,
+    studentId,
+    value,
+  );
+  return value;
+}
+
+export async function getStudentProgressForecast(
+  viewerId: string,
+  classId: string,
+  studentId: string,
+) {
+  const cached = getStudentProgressInferenceCacheHit(
+    studentProgressForecastCache,
+    classId,
+    studentId,
+  );
+
+  const { classData, student, submissions } = await loadStudentProgressContext(
+    viewerId,
+    classId,
+    studentId,
+  );
+
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const context = buildStructuredProgressContext(
+    classData,
+    student,
+    submissions,
+  );
+
+  const value = await inference<StudentProgressForecast>(
+    buildStructuredInferenceMessages(
+      "Predict the student's next graded assignment percentage band and risk status. Base the forecast on trajectory, missing work, low scores, and assignment recency. Keep the reason to one sentence.",
+      context,
+    ),
+    studentProgressForecastSchema,
+    {
+      reason: "student_progress_forecast",
+      metadata: { viewerId, classId, studentId },
+    },
+  );
+  setStudentProgressInferenceCache(
+    studentProgressForecastCache,
+    classId,
+    studentId,
+    value,
+  );
+  return value;
+}
+
+export async function getStudentProgressFocus(
+  viewerId: string,
+  classId: string,
+  studentId: string,
+) {
+  const cached = getStudentProgressInferenceCacheHit(
+    studentProgressFocusCache,
+    classId,
+    studentId,
+  );
+
+  const { classData, student, submissions } = await loadStudentProgressContext(
+    viewerId,
+    classId,
+    studentId,
+  );
+
+  if (cached !== undefined) {
+    return cached;
+  }
+  
+  const context = buildStructuredProgressContext(
+    classData,
+    student,
+    submissions,
+  );
+
+  const value = await inference<StudentProgressFocus>(
+    buildStructuredInferenceMessages(
+      "Generate 3-5 student-facing weekly focus items. Each item should be specific, actionable, and grounded in the student's grade pattern or assignment titles. No numbering in the strings.",
+      context,
+    ),
+    studentProgressFocusSchema,
+    {
+      reason: "student_progress_focus",
+      metadata: { viewerId, classId, studentId },
+    },
+  );
+  setStudentProgressInferenceCache(
+    studentProgressFocusCache,
+    classId,
+    studentId,
+    value,
+  );
+  return value;
+}
+
 export async function chatAboutStudentProgress(
   viewerId: string,
   input: {
@@ -637,7 +896,11 @@ export async function chatAboutStudentProgress(
   try {
     const response = await inference<string>(messages, undefined, {
       reason: "student_progress_chat",
-      metadata: { viewerId, classId: input.classId, studentId: input.studentId },
+      metadata: {
+        viewerId,
+        classId: input.classId,
+        studentId: input.studentId,
+      },
     });
     if (typeof response !== "string" || response.trim().length === 0) {
       throw new Error("Student progress chat returned an empty response");

package/src/services/studentProgressInferenceCache.ts

@@ -0,0 +1,64 @@
+/**
+ * In-process cache for student progress AI panels (insights / forecast / focus).
+ * Epoch bumps invalidate all three for a given class + student (e.g. after a grade update).
+ * Entries also expire after one week so stale AI summaries eventually refresh.
+ */
+
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+const epochByScope = new Map<string, number>();
+
+function scopeKey(classId: string, studentId: string) {
+  return `${classId}:${studentId}`;
+}
+
+function currentStudentProgressInferenceEpoch(
+  classId: string,
+  studentId: string,
+) {
+  return epochByScope.get(scopeKey(classId, studentId)) ?? 0;
+}
+
+/** Call when a teacher updates `gradeReceived` for that student's work in this class. */
+export function invalidateStudentProgressInferenceCache(
+  classId: string,
+  studentId: string,
+) {
+  const key = scopeKey(classId, studentId);
+  epochByScope.set(key, (epochByScope.get(key) ?? 0) + 1);
+}
+
+type CacheRow<T> = { epoch: number; cachedAt: number; value: T };
+
+export function getStudentProgressInferenceCacheHit<T>(
+  store: Map<string, CacheRow<T>>,
+  classId: string,
+  studentId: string,
+): T | undefined {
+  const key = scopeKey(classId, studentId);
+  const epoch = currentStudentProgressInferenceEpoch(classId, studentId);
+  const hit = store.get(key);
+  if (!hit) {
+    return undefined;
+  }
+  const fresh =
+    hit.epoch === epoch && Date.now() - hit.cachedAt < WEEK_MS;
+  if (!fresh) {
+    store.delete(key);
+    return undefined;
+  }
+  return hit.value;
+}
+
+export function setStudentProgressInferenceCache<T>(
+  store: Map<string, CacheRow<T>>,
+  classId: string,
+  studentId: string,
+  value: T,
+) {
+  store.set(scopeKey(classId, studentId), {
+    epoch: currentStudentProgressInferenceEpoch(classId, studentId),
+    cachedAt: Date.now(),
+    value,
+  });
+}

package/src/services/worksheet.ts

@@ -35,6 +35,7 @@ import {
   createStudentQuestionProgressForGrading,
   createComment,
   findStudentQuestionProgressByIdForTeacher,
+  findStudentQuestionProgressByIdForStudentOrTeacher,
   findStudentQuestionProgressByIdForTeacherAndResponse,
 } from "../models/worksheet.js";
 
@@ -645,14 +646,15 @@ export async function addCommentToResponse(
   comment: string,
   authorId: string
 ) {
-  const progress = await findStudentQuestionProgressByIdForTeacher(
+  const progress = await findStudentQuestionProgressByIdForStudentOrTeacher(
     responseId,
     authorId
   );
   if (!progress) {
     throw new TRPCError({
       code: "FORBIDDEN",
-      message: "Only class teachers can comment on worksheet responses",
+      message:
+        "You can only comment on your own worksheet answers or on answers for classes you teach",
     });
   }
 

package/src/trpc.ts

@@ -7,6 +7,7 @@ import { Request, Response } from 'express';
 import { z } from 'zod';
 import { handlePrismaError, PrismaErrorInfo } from './utils/prismaErrorHandler.js';
 import { findUserBySessionToken } from './models/auth.js';
+import { assertAdminPanelUser } from './utils/adminPanelAccess.js';
 
 interface CreateContextOptions {
   req: Request;
@@ -88,6 +89,20 @@ export const publicProcedure = t.procedure.use(loggingMiddleware);
 // Protected procedures
 export const protectedProcedure = publicProcedure.use(isAuthed);
 
+const adminPanelMiddleware = t.middleware(({ ctx, next }) => {
+  if (!ctx.user) {
+    throw new TRPCError({
+      code: 'UNAUTHORIZED',
+      message: 'Not authenticated',
+    });
+  }
+  assertAdminPanelUser(ctx.user.id);
+  return next({ ctx });
+});
+
+/** Authenticated + env allowlist (see `assertAdminPanelUser`). */
+export const adminProcedure = protectedProcedure.use(adminPanelMiddleware);
+
 export const protectedClassMemberProcedure = protectedProcedure
   .input(z.object({ classId: z.string() }).passthrough())
   .use(isMemberInClass);

package/src/utils/adminPanelAccess.ts

@@ -0,0 +1,46 @@
+import { TRPCError } from '@trpc/server';
+import { env } from '../lib/config/env.js';
+
+function parseAdminUserIds(raw: string | undefined): Set<string> {
+  if (!raw?.trim()) return new Set();
+  return new Set(
+    raw
+      .split(/[\s,]+/)
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Admin tRPC routes: in production `ADMIN_PANEL_USER_IDS` must be a non-empty
+ * comma/whitespace-separated list of user UUIDs. In non-production, an empty
+ * unset value allows any authenticated user (local ops); a non-empty list is
+ * still enforced.
+ */
+export function assertAdminPanelUser(userId: string): void {
+  const allowed = parseAdminUserIds(env.ADMIN_PANEL_USER_IDS);
+
+  if (env.NODE_ENV === 'production') {
+    if (allowed.size === 0) {
+      throw new TRPCError({
+        code: 'FORBIDDEN',
+        message:
+          'Admin API disabled: set ADMIN_PANEL_USER_IDS to a non-empty list of user ids.',
+      });
+    }
+    if (!allowed.has(userId)) {
+      throw new TRPCError({
+        code: 'FORBIDDEN',
+        message: 'You are not allowed to use the admin API.',
+      });
+    }
+    return;
+  }
+
+  if (allowed.size > 0 && !allowed.has(userId)) {
+    throw new TRPCError({
+      code: 'FORBIDDEN',
+      message: 'You are not allowed to use the admin API.',
+    });
+  }
+}