@telebort/question-banks 2.3.0 → 2.4.0

package/dist/{assessment-DnV2240e.d.cts → assessment-BhkjdWy1.d.cts}

@@ -1,5 +1,38 @@
 import { z } from 'zod';
 
+/**
+ * Defines a summative assessment (quiz) that covers multiple lessons.
+ * Stored in CDN course exports and used by the assessment module to build quizzes.
+ */
+declare const AssessmentBlueprintSchema: z.ZodObject<{
+    assessmentId: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    lessonRange: z.ZodEffects<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, [number, number], [number, number]>;
+    questionCount: z.ZodNumber;
+    passingScore: z.ZodNumber;
+    timeLimitMinutes: z.ZodNullable<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    assessmentId: string;
+    title: string;
+    description: string;
+    lessonRange: [number, number];
+    questionCount: number;
+    passingScore: number;
+    timeLimitMinutes: number | null;
+    tags?: string[] | undefined;
+}, {
+    assessmentId: string;
+    title: string;
+    description: string;
+    lessonRange: [number, number];
+    questionCount: number;
+    passingScore: number;
+    timeLimitMinutes: number | null;
+    tags?: string[] | undefined;
+}>;
+type AssessmentBlueprint = z.infer<typeof AssessmentBlueprintSchema>;
 /**
  * A single user response to a question
  */
@@ -234,8 +267,8 @@ declare const GradedAssessmentSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     courseId: string;
     totalQuestions: number;
-    submittedAt: string;
     assessmentId: string;
+    submittedAt: string;
     responses: {
         questionId: string;
         isCorrect: boolean;
@@ -269,8 +302,8 @@ declare const GradedAssessmentSchema: z.ZodObject<{
 }, {
     courseId: string;
     totalQuestions: number;
-    submittedAt: string;
     assessmentId: string;
+    submittedAt: string;
     responses: {
         questionId: string;
         isCorrect: boolean;
@@ -327,8 +360,8 @@ declare const ValidationResultSchema: z.ZodObject<{
     answeredCount: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     valid: boolean;
-    isComplete: boolean;
     questionCount: number;
+    isComplete: boolean;
     answeredCount: number;
     errors?: {
         path: (string | number)[];
@@ -337,8 +370,8 @@ declare const ValidationResultSchema: z.ZodObject<{
     }[] | undefined;
 }, {
     valid: boolean;
-    isComplete: boolean;
     questionCount: number;
+    isComplete: boolean;
     answeredCount: number;
     errors?: {
         path: (string | number)[];
@@ -348,4 +381,4 @@ declare const ValidationResultSchema: z.ZodObject<{
 }>;
 type ValidationResult = z.infer<typeof ValidationResultSchema>;
 
-export { type AssessmentSubmission as A, type GradedAssessment as G, MisconceptionReportSchema as M, UserResponseSchema as U, type ValidationResult as V, AssessmentSubmissionSchema as a, GradedResponseSchema as b, GradedAssessmentSchema as c, ValidationResultSchema as d, type UserResponse as e, type GradedResponse as f, type MisconceptionReport as g };
+export { type AssessmentSubmission as A, type GradedAssessment as G, MisconceptionReportSchema as M, type UserResponse as U, type ValidationResult as V, type AssessmentBlueprint as a, AssessmentBlueprintSchema as b, UserResponseSchema as c, AssessmentSubmissionSchema as d, GradedResponseSchema as e, GradedAssessmentSchema as f, ValidationResultSchema as g, type GradedResponse as h, type MisconceptionReport as i };

package/dist/{assessment-DnV2240e.d.ts → assessment-BhkjdWy1.d.ts}

@@ -1,5 +1,38 @@
 import { z } from 'zod';
 
+/**
+ * Defines a summative assessment (quiz) that covers multiple lessons.
+ * Stored in CDN course exports and used by the assessment module to build quizzes.
+ */
+declare const AssessmentBlueprintSchema: z.ZodObject<{
+    assessmentId: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    lessonRange: z.ZodEffects<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, [number, number], [number, number]>;
+    questionCount: z.ZodNumber;
+    passingScore: z.ZodNumber;
+    timeLimitMinutes: z.ZodNullable<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    assessmentId: string;
+    title: string;
+    description: string;
+    lessonRange: [number, number];
+    questionCount: number;
+    passingScore: number;
+    timeLimitMinutes: number | null;
+    tags?: string[] | undefined;
+}, {
+    assessmentId: string;
+    title: string;
+    description: string;
+    lessonRange: [number, number];
+    questionCount: number;
+    passingScore: number;
+    timeLimitMinutes: number | null;
+    tags?: string[] | undefined;
+}>;
+type AssessmentBlueprint = z.infer<typeof AssessmentBlueprintSchema>;
 /**
  * A single user response to a question
  */
@@ -234,8 +267,8 @@ declare const GradedAssessmentSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     courseId: string;
     totalQuestions: number;
-    submittedAt: string;
     assessmentId: string;
+    submittedAt: string;
     responses: {
         questionId: string;
         isCorrect: boolean;
@@ -269,8 +302,8 @@ declare const GradedAssessmentSchema: z.ZodObject<{
 }, {
     courseId: string;
     totalQuestions: number;
-    submittedAt: string;
     assessmentId: string;
+    submittedAt: string;
     responses: {
         questionId: string;
         isCorrect: boolean;
@@ -327,8 +360,8 @@ declare const ValidationResultSchema: z.ZodObject<{
     answeredCount: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     valid: boolean;
-    isComplete: boolean;
     questionCount: number;
+    isComplete: boolean;
     answeredCount: number;
     errors?: {
         path: (string | number)[];
@@ -337,8 +370,8 @@ declare const ValidationResultSchema: z.ZodObject<{
     }[] | undefined;
 }, {
     valid: boolean;
-    isComplete: boolean;
     questionCount: number;
+    isComplete: boolean;
     answeredCount: number;
     errors?: {
         path: (string | number)[];
@@ -348,4 +381,4 @@ declare const ValidationResultSchema: z.ZodObject<{
 }>;
 type ValidationResult = z.infer<typeof ValidationResultSchema>;
 
-export { type AssessmentSubmission as A, type GradedAssessment as G, MisconceptionReportSchema as M, UserResponseSchema as U, type ValidationResult as V, AssessmentSubmissionSchema as a, GradedResponseSchema as b, GradedAssessmentSchema as c, ValidationResultSchema as d, type UserResponse as e, type GradedResponse as f, type MisconceptionReport as g };
+export { type AssessmentSubmission as A, type GradedAssessment as G, MisconceptionReportSchema as M, type UserResponse as U, type ValidationResult as V, type AssessmentBlueprint as a, AssessmentBlueprintSchema as b, UserResponseSchema as c, AssessmentSubmissionSchema as d, GradedResponseSchema as e, GradedAssessmentSchema as f, ValidationResultSchema as g, type GradedResponse as h, type MisconceptionReport as i };

package/dist/cli/index.cjs

@@ -81,6 +81,10 @@ var QuestionMetadataSchema = zod.z.object({
   // seconds
   bloomsTaxonomy: BloomsTaxonomySchema,
   tags: zod.z.array(zod.z.string()),
+  conceptTags: zod.z.array(zod.z.string()).optional(),
+  // mastery-relevant concept tags
+  metaTags: zod.z.array(zod.z.string()).optional(),
+  // Bloom's types, course codes, internal
   source: zod.z.string().default("exit-ticket"),
   version: zod.z.string().default("1.1"),
   createdDate: zod.z.string().optional(),
@@ -123,70 +127,17 @@ QuestionSchema.omit({
     })
   ).length(4)
 });
-var CourseDomainSchema = zod.z.enum([
-  // AI & Data Science
-  "ai_data_science",
-  "ai_ml_cv",
-  "ai_generative",
-  "ai_advanced",
-  "ai",
-  // Prompt Engineering (general AI)
-  // Web Development
-  "web_development",
-  // Mobile Development
-  "mobile_development",
-  "mobile",
-  // Block-based Programming
-  "block_based",
-  "python_programming",
-  "design",
-  "artificial_intelligence",
-  // Block-based AI courses (BBAI)
-  // Computer Science
-  "cs_foundations",
-  // CS1-CS4 courses
-  // Foundation
-  "foundation",
-  "creative_computing",
-  // Utility / Tools
-  "tools"
-  // IDE Setup, Git, Vibe Coding
-]);
-var CourseTierSchema = zod.z.enum([
-  "beginner",
-  // Block-based courses (BBW, BBP, BBD, BBAI)
-  "foundation",
-  "intermediate",
-  "advanced"
-]);
-var LessonSchema = zod.z.object({
-  lessonId: zod.z.string(),
-  // e.g., "ai-1-lesson-1"
-  lessonNumber: zod.z.number().int().positive(),
-  lessonTitle: zod.z.string(),
-  lessonSlug: zod.z.string().optional(),
-  totalQuestions: zod.z.number().int().positive().default(5),
-  questions: zod.z.array(QuestionSchema)
-});
-var CourseSchema = zod.z.object({
-  courseId: zod.z.string(),
-  // e.g., "ai-1"
-  courseName: zod.z.string(),
-  // e.g., "AI-1 Data Analysis and Data Science"
-  courseCode: zod.z.string(),
-  // e.g., "AI1"
-  domain: CourseDomainSchema,
-  tier: CourseTierSchema,
-  difficulty: zod.z.number().int().min(1).max(5),
-  totalLessons: zod.z.number().int().positive(),
-  totalQuestions: zod.z.number().int().positive(),
-  sourceFile: zod.z.string().optional(),
-  lessons: zod.z.array(LessonSchema)
-});
-CourseSchema.omit({ lessons: true }).extend({
-  lessons: zod.z.array(
-    LessonSchema.omit({ questions: true })
-  ).optional()
+var AssessmentBlueprintSchema = zod.z.object({
+  assessmentId: zod.z.string(),
+  // e.g., "cs1-quiz-1"
+  title: zod.z.string(),
+  // e.g., "Quiz 1"
+  description: zod.z.string(),
+  lessonRange: zod.z.tuple([zod.z.number().int().positive(), zod.z.number().int().positive()]).refine(([start2, end2]) => start2 <= end2, { message: "lessonRange start must be <= end" }),
+  questionCount: zod.z.number().int().positive(),
+  passingScore: zod.z.number().min(0).max(100),
+  timeLimitMinutes: zod.z.number().int().positive().nullable(),
+  tags: zod.z.array(zod.z.string()).optional()
 });
 var UserResponseSchema = zod.z.object({
   questionId: zod.z.string(),
@@ -227,7 +178,7 @@ var MisconceptionReportSchema = zod.z.object({
   description: zod.z.string().optional()
 });
 zod.z.object({
-  assessmentId: zod.z.string().uuid(),
+  assessmentId: zod.z.string(),
   userId: zod.z.string().optional(),
   courseId: zod.z.string(),
   lessonId: zod.z.string().optional(),
@@ -263,6 +214,74 @@ zod.z.object({
   questionCount: zod.z.number().int(),
   answeredCount: zod.z.number().int()
 });
+
+// src/schemas/course.ts
+var CourseDomainSchema = zod.z.enum([
+  // AI & Data Science
+  "ai_data_science",
+  "ai_ml_cv",
+  "ai_generative",
+  "ai_advanced",
+  "ai",
+  // Prompt Engineering (general AI)
+  // Web Development
+  "web_development",
+  // Mobile Development
+  "mobile_development",
+  "mobile",
+  // Block-based Programming
+  "block_based",
+  "python_programming",
+  "design",
+  "artificial_intelligence",
+  // Block-based AI courses (BBAI)
+  // Computer Science
+  "cs_foundations",
+  // CS1-CS4 courses
+  // Foundation
+  "foundation",
+  "creative_computing",
+  // Utility / Tools
+  "tools"
+  // IDE Setup, Git, Vibe Coding
+]);
+var CourseTierSchema = zod.z.enum([
+  "beginner",
+  // Block-based courses (BBW, BBP, BBD, BBAI)
+  "foundation",
+  "intermediate",
+  "advanced"
+]);
+var LessonSchema = zod.z.object({
+  lessonId: zod.z.string(),
+  // e.g., "ai-1-lesson-1"
+  lessonNumber: zod.z.number().int().positive(),
+  lessonTitle: zod.z.string(),
+  lessonSlug: zod.z.string().optional(),
+  totalQuestions: zod.z.number().int().positive().default(5),
+  questions: zod.z.array(QuestionSchema)
+});
+var CourseSchema = zod.z.object({
+  courseId: zod.z.string(),
+  // e.g., "ai-1"
+  courseName: zod.z.string(),
+  // e.g., "AI-1 Data Analysis and Data Science"
+  courseCode: zod.z.string(),
+  // e.g., "AI1"
+  domain: CourseDomainSchema,
+  tier: CourseTierSchema,
+  difficulty: zod.z.number().int().min(1).max(5),
+  totalLessons: zod.z.number().int().positive(),
+  totalQuestions: zod.z.number().int().positive(),
+  sourceFile: zod.z.string().optional(),
+  lessons: zod.z.array(LessonSchema),
+  assessments: zod.z.array(AssessmentBlueprintSchema).optional()
+});
+CourseSchema.omit({ lessons: true }).extend({
+  lessons: zod.z.array(
+    LessonSchema.omit({ questions: true })
+  ).optional()
+});
 var CertificationProjectSchema = zod.z.object({
   projectNumber: zod.z.number().int().positive(),
   projectName: zod.z.string(),
@@ -550,6 +569,138 @@ ${green(bold("Valid!"))} File passed schema validation.
   }
 }
 
+// src/core/assessment.ts
+var SeededRandom = class {
+  constructor(seed) {
+    this.state = seed;
+  }
+  next() {
+    this.state = (this.state * 1103515245 + 12345) % 2147483648;
+    return this.state / 2147483648;
+  }
+  /** Fisher-Yates shuffle */
+  shuffle(array) {
+    const result = [...array];
+    for (let i3 = result.length - 1; i3 > 0; i3--) {
+      const j2 = Math.floor(this.next() * (i3 + 1));
+      const temp = result[i3];
+      result[i3] = result[j2];
+      result[j2] = temp;
+    }
+    return result;
+  }
+};
+function hashString(str) {
+  let hash = 0;
+  for (let i3 = 0; i3 < str.length; i3++) {
+    const char = str.charCodeAt(i3);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash);
+}
+function createAssessmentModule(getCourse) {
+  return {
+    async getAssessments(courseId) {
+      const course = await getCourse(courseId);
+      return course?.assessments ?? [];
+    },
+    async buildAssessmentQuiz(courseId, assessmentId, seed) {
+      const course = await getCourse(courseId);
+      if (!course) throw new Error(`Course not found: ${courseId}`);
+      const blueprint = course.assessments?.find((a2) => a2.assessmentId === assessmentId);
+      if (!blueprint) throw new Error(`Assessment not found: ${assessmentId}`);
+      const [rangeStart, rangeEnd] = blueprint.lessonRange;
+      const pool = [];
+      for (const lesson of course.lessons) {
+        if (lesson.lessonNumber >= rangeStart && lesson.lessonNumber <= rangeEnd) {
+          pool.push(...lesson.questions);
+        }
+      }
+      if (pool.length === 0) {
+        throw new Error(`No questions found for lessons ${rangeStart}-${rangeEnd} in ${courseId}`);
+      }
+      const seedValue = seed ? hashString(seed) : Date.now();
+      const rng = new SeededRandom(seedValue);
+      const shuffled = rng.shuffle(pool);
+      return shuffled.slice(0, Math.min(blueprint.questionCount, shuffled.length));
+    },
+    async gradeAssessment(courseId, assessmentId, responses, passingScore) {
+      const course = await getCourse(courseId);
+      if (!course) throw new Error(`Course not found: ${courseId}`);
+      const blueprint = course.assessments?.find((a2) => a2.assessmentId === assessmentId);
+      if (!blueprint) throw new Error(`Assessment not found: ${assessmentId}`);
+      const threshold = passingScore ?? blueprint.passingScore;
+      const questionMap = /* @__PURE__ */ new Map();
+      for (const lesson of course.lessons) {
+        for (const q of lesson.questions) {
+          questionMap.set(q.questionId, q);
+        }
+      }
+      const gradedResponses = [];
+      let correctCount = 0;
+      for (const response of responses) {
+        const question = questionMap.get(response.questionId);
+        if (!question) continue;
+        const selectedOption = question.options.find((o2) => o2.key === response.selectedAnswer);
+        const isCorrect = selectedOption?.isCorrect ?? false;
+        if (isCorrect) correctCount++;
+        gradedResponses.push({
+          questionId: response.questionId,
+          selectedAnswer: response.selectedAnswer,
+          correctAnswer: question.correctAnswer,
+          isCorrect,
+          misconceptionId: isCorrect ? null : selectedOption?.misconceptionId ?? null,
+          feedback: selectedOption?.feedback,
+          timeSpent: response.timeSpent
+        });
+      }
+      const totalQuestions = gradedResponses.length;
+      const score = totalQuestions > 0 ? Math.round(correctCount / totalQuestions * 100) : 0;
+      const misconceptionCounts = /* @__PURE__ */ new Map();
+      for (const gr of gradedResponses) {
+        if (gr.misconceptionId) {
+          const existing = misconceptionCounts.get(gr.misconceptionId);
+          if (existing) {
+            existing.count++;
+            existing.questionIds.push(gr.questionId);
+          } else {
+            misconceptionCounts.set(gr.misconceptionId, {
+              count: 1,
+              questionIds: [gr.questionId]
+            });
+          }
+        }
+      }
+      const misconceptions = Array.from(misconceptionCounts.entries()).map(([id, data]) => ({
+        misconceptionId: id,
+        count: data.count,
+        percentage: Math.round(data.count / totalQuestions * 100),
+        questionIds: data.questionIds
+      })).sort((a2, b) => b.count - a2.count);
+      if (totalQuestions === 0) {
+        throw new Error(`No valid questions matched for assessment ${assessmentId}. All ${responses.length} response(s) referenced unknown questionIds.`);
+      }
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const generatedId = `grade-${courseId}-${assessmentId}-${hashString(now).toString(36)}`;
+      return {
+        assessmentId: generatedId,
+        courseId,
+        totalQuestions,
+        correctCount,
+        incorrectCount: totalQuestions - correctCount,
+        score,
+        passed: score >= threshold,
+        responses: gradedResponses,
+        misconceptions,
+        topMisconceptions: misconceptions.slice(0, 3).map((m3) => m3.misconceptionId),
+        submittedAt: now,
+        gradedAt: now
+      };
+    }
+  };
+}
+
 // src/knowledge/index.ts
 function createLogger(config) {
   return {
@@ -23291,6 +23442,7 @@ function createExitTicketsSDK(config) {
   };
   const malaysiaMath = createMalaysiaMathModule(malaysiaMathConfig);
   const malaysiaMathTaxonomy = createMalaysiaMathTaxonomyModule(malaysiaMathConfig);
+  const assessment = createAssessmentModule(data.getCourse);
   return {
     data,
     query,
@@ -23301,7 +23453,8 @@ function createExitTicketsSDK(config) {
     knowledge,
     taxonomy,
     malaysiaMath,
-    malaysiaMathTaxonomy
+    malaysiaMathTaxonomy,
+    assessment
   };
 }
 
@@ -23470,26 +23623,32 @@ async function loadCourseData(filePath) {
 }
 function extractQuestions(courseData) {
   const questions = [];
+  const pushQuestion = (q) => {
+    questions.push({
+      questionId: q.questionId || q.globalId || `${courseData.courseId || "unknown"}-unknown`,
+      prompt: q.prompt || "",
+      options: (q.options || []).map((o2) => ({
+        key: o2.key || "",
+        text: o2.text || "",
+        isCorrect: o2.isCorrect || false
+      })),
+      hasCodeBlock: q.hasCodeBlock || false,
+      codeLanguage: q.codeLanguage || null,
+      codeContent: q.codeContent || null
+    });
+  };
   if (courseData.lessons) {
     for (const lesson of courseData.lessons) {
       if (lesson.questions) {
         for (const q of lesson.questions) {
-          questions.push({
-            questionId: q.questionId || `${courseData.courseId}-unknown`,
-            prompt: q.prompt || "",
-            options: (q.options || []).map((o2) => ({
-              key: o2.key || "",
-              text: o2.text || "",
-              isCorrect: o2.isCorrect || false
-            })),
-            // CS-specific fields for enhanced analysis
-            hasCodeBlock: q.hasCodeBlock || false,
-            codeLanguage: q.codeLanguage || null,
-            codeContent: q.codeContent || null
-          });
+          pushQuestion(q);
         }
       }
     }
+  } else if (courseData.questions && Array.isArray(courseData.questions)) {
+    for (const q of courseData.questions) {
+      pushQuestion(q);
+    }
   }
   return questions;
 }