@telebort/question-banks 2.2.0 → 2.4.0

package/dist/cli/index.cjs

@@ -19,22 +19,52 @@ var OptionSchema = zod.z.object({
   text: zod.z.string().min(1),
   isCorrect: zod.z.boolean(),
   // v1.1 fields - optional for backward compatibility
-  misconceptionId: zod.z.string().optional(),
+  misconceptionId: zod.z.string().nullish(),
   feedback: FeedbackSchema.optional()
 });
 var QuestionTypeSchema = zod.z.enum([
+  // Core assessment types (original v1.0)
   "vocabulary",
   "code_understanding",
   "problem_solving",
   "application",
-  "reflection"
+  "reflection",
+  // Code-focused types
+  "debugging",
+  "trace",
+  "predict",
+  // Higher-order thinking
+  "analyze",
+  "evaluation",
+  "synthesis",
+  "design",
+  "conceptual",
+  "explain",
+  // Domain-specific
+  "bebras",
+  "blockmodel",
+  "ethical_reasoning"
 ]);
 var QuestionArchetypeSchema = zod.z.enum([
+  // Original archetypes (v1.1)
   "vocabulary",
   "trace",
   "bebras",
   "blockmodel",
-  "parsons"
+  "parsons",
+  // Assessment patterns
+  "application",
+  "problem_solving",
+  "debugging",
+  "predict",
+  "explain",
+  "evaluation",
+  "reflection",
+  "conceptual",
+  "analysis",
+  "design",
+  "synthesis",
+  "code"
 ]);
 var DifficultySchema = zod.z.enum(["easy", "medium", "hard", "challenge"]);
 var BloomsTaxonomySchema = zod.z.enum([
@@ -51,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(),
@@ -58,8 +92,8 @@ var QuestionMetadataSchema = zod.z.object({
 });
 var QuestionSchema = zod.z.object({
   // Identifiers
-  questionId: zod.z.string().regex(/^[a-z0-9-]+-l\d+-q\d+$/),
-  globalId: zod.z.string().regex(/^exit-ticket-\d{4}$/),
+  questionId: zod.z.string().regex(/^[a-z0-9][-a-z0-9]*-(?:l\d+-)?q\d+$/),
+  globalId: zod.z.string().regex(/^exit-ticket-[a-z0-9][-a-z0-9]*$/),
   questionNumber: zod.z.number().int().positive().max(5),
   // Classification
   questionType: QuestionTypeSchema,
@@ -93,58 +127,17 @@ QuestionSchema.omit({
     })
   ).length(4)
 });
-var CourseDomainSchema = zod.z.enum([
-  // AI & Data Science
-  "ai_data_science",
-  "ai_ml_cv",
-  "ai_generative",
-  "ai_advanced",
-  // Web Development
-  "web_development",
-  // Mobile Development
-  "mobile_development",
-  "mobile",
-  // Block-based Programming
-  "block_based",
-  "python_programming",
-  "design",
-  // Foundation
-  "foundation",
-  "creative_computing"
-]);
-var CourseTierSchema = zod.z.enum([
-  "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(),
@@ -185,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(),
@@ -221,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(),
@@ -508,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 {
@@ -23249,6 +23442,7 @@ function createExitTicketsSDK(config) {
   };
   const malaysiaMath = createMalaysiaMathModule(malaysiaMathConfig);
   const malaysiaMathTaxonomy = createMalaysiaMathTaxonomyModule(malaysiaMathConfig);
+  const assessment = createAssessmentModule(data.getCourse);
   return {
     data,
     query,
@@ -23259,7 +23453,8 @@ function createExitTicketsSDK(config) {
     knowledge,
     taxonomy,
     malaysiaMath,
-    malaysiaMathTaxonomy
+    malaysiaMathTaxonomy,
+    assessment
   };
 }
 
@@ -23428,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;
 }