@telebort/question-banks 2.2.0 → 2.3.0

package/README.md

@@ -2,12 +2,104 @@
 
 Question Banks SDK for Telebort educational assessments. Provides Zod schemas, TypeScript types, client-side quiz generation, v2.0 Knowledge Graph access, and CAT (Computerized Adaptive Testing) orchestration.
 
-**v2.1.1** - Full CAT engine with Sympson-Hetter exposure control, IRT 4PL calibration, and 256K question bank access.
+**v2.3.0** - Expanded schema validation for all 27 courses, full CAT engine with Sympson-Hetter exposure control, IRT 4PL calibration, and 1.45M+ question bank access.
+
+---
 
 ## Installation
 
 ```bash
+# SDK + CLI (recommended)
 npm install @telebort/question-banks zod
+
+# CLI only (no install required)
+npx @telebort/question-banks <command>
+```
+
+---
+
+## Quick Start (3 Scenarios)
+
+### Scenario A: Validate Course Files (CLI)
+
+Quickly validate JSON files against schemas:
+
+```bash
+# Validate all course files in a directory
+npx @telebort/question-banks validate ./data/courses/ --verbose
+
+# Show question bank statistics
+npx @telebort/question-banks stats --data-dir ./data/courses/
+
+# Run guessability analysis (anti-guessing QA)
+npx @telebort/question-banks score ./data/courses/ai-1.json
+```
+
+### Scenario B: Build a Quiz App (SDK)
+
+Use the factory function to create a fully-featured SDK instance:
+
+```typescript
+import { createQuestionBanksSDK } from '@telebort/question-banks'
+
+const sdk = createQuestionBanksSDK({
+  dataSource: {
+    async loadCourses() {
+      const res = await fetch('https://content-warehouse.vercel.app/question-banks/v2.0/courses/CS1.json')
+      return [await res.json()]
+    }
+  }
+})
+
+// Generate a quiz
+const quiz = await sdk.quiz.generateQuiz({ questionCount: 5 })
+
+// Check an answer with feedback
+const result = await sdk.validate.checkAnswer('cs-1-l1-q1', 'B', 'formative')
+// { isCorrect: true, feedback: {...}, misconceptionId: null }
+```
+
+### Scenario C: Validate Data Structures (Schemas Only)
+
+Import just the Zod schemas for lightweight validation:
+
+```typescript
+import { QuestionSchema, CourseSchema } from '@telebort/question-banks/schemas'
+
+const result = QuestionSchema.safeParse(myQuestion)
+if (!result.success) {
+  console.error('Validation failed:', result.error.issues)
+}
+
+// TypeScript type inference
+import type { Question, Course } from '@telebort/question-banks'
+```
+
+---
+
+## Entry Points
+
+| Import Path | Purpose | Use Case |
+|-------------|---------|----------|
+| `@telebort/question-banks` | Full SDK factory | Quiz apps, data access |
+| `@telebort/question-banks/schemas` | Zod schemas only | Lightweight validation |
+| `@telebort/question-banks/validation` | ValidationClient | Answer checking |
+| `@telebort/question-banks/premium` | PremiumClient (JWT) | Full API access |
+| `@telebort/question-banks/irt-calibration` | IRT calibration tools | Psychometric analysis |
+| `@telebort/question-banks/cat` | CAT engine | Adaptive testing |
+
+---
+
+## ⚠️ Migration Notice
+
+If you're using the deprecated CLI package:
+
+```bash
+# Uninstall old CLI package
+npm uninstall @telebort/question-banks-cli
+
+# Use the canonical package (CLI included)
+npx @telebort/question-banks validate ./data/
 ```
 
 ## What's New in v2.1.x
@@ -19,7 +111,8 @@ npm install @telebort/question-banks zod
 - **IRT 4PL**: Full 4-parameter logistic model with `estimateAbilityEAP()` Bayesian estimation
 
 ### Scale
-- **256K Questions**: 26 CDN shards (~20MB each) for global delivery
+- **1.45M+ Questions**: 120 JSON files (2.7GB) with 26 CDN shards for global delivery
+- **CS Algorithms**: 1.35M procedurally generated questions (arrays, DP, graphs, recursion, sorting, strings)
 - **Malaysian Math**: 94K bilingual questions (KSSR 30K + KSSM 22K + SPM 34K + STPM 8K)
 - **Knowledge Graph v2.0**: 4-level taxonomy with topic-based queries
 
@@ -157,7 +250,7 @@ const knowledge = createKnowledgeModule({
 })
 ```
 
-### v2.0 CDN Structure (256K Questions)
+### v2.0 CDN Structure
 
 ```
 /question-banks/v2.0/
@@ -169,7 +262,7 @@ const knowledge = createKnowledgeModule({
     └── shards/shard-{00001-00026}.json      # 10K questions each (~20MB)
 ```
 
-**Total:** 256,037 questions in 26 CDN shards for global delivery.
+**Total:** 1,449,830+ questions in 26 CDN shards for global delivery.
 
 ---
 
@@ -262,7 +355,52 @@ client.clearCache()
 
 ---
 
-## SDK Interface
+## SDK API Reference
+
+The SDK is organized into focused modules. Each module handles a specific domain:
+
+| Module | Purpose | Key Methods |
+|--------|---------|-------------|
+| `sdk.data` | Data access | `getCourses()`, `getCourse()`, `getQuestion()` |
+| `sdk.quiz` | Quiz generation | `generateQuiz()`, `getLessonQuiz()` |
+| `sdk.validate` | Answer checking | `checkAnswer()` |
+| `sdk.query` | Filtering | `filterQuestions()`, `getRandomQuestions()` |
+| `sdk.search` | Full-text search | `search()`, `searchByTags()` |
+| `sdk.analytics` | Statistics | `getStatistics()`, `getCourseStatistics()` |
+| `sdk.knowledge` | v2.0 Knowledge Graph | `getByTopic()`, `getByDomain()`, `search()` |
+| `sdk.taxonomy` | Topic taxonomy | `getDomains()`, `getTopics()` |
+
+### Common Workflows
+
+**Build a quiz from a specific course:**
+```typescript
+const quiz = await sdk.quiz.generateQuiz({
+  courseId: 'cs-1',
+  questionCount: 10,
+  difficulty: 'medium'
+})
+```
+
+**Check an answer with feedback:**
+```typescript
+const result = await sdk.validate.checkAnswer('cs-1-l1-q1', 'B', 'formative')
+// Returns: { isCorrect, feedback, misconceptionId }
+```
+
+**Search by topic (v2.0 Knowledge Graph):**
+```typescript
+const questions = await sdk.knowledge.getByTopic('computer-science/algorithms/sorting')
+```
+
+**Get course statistics:**
+```typescript
+const stats = await sdk.analytics.getCourseStatistics('ai-1')
+// Returns: { totalQuestions, byDifficulty, byType, ... }
+```
+
+---
+
+## SDK Interface (TypeScript)
 
 ```typescript
 interface QuestionBanksSDK {
@@ -352,56 +490,77 @@ GradedAssessmentSchema      // Graded result with misconception analysis
 
 ---
 
-## CLI Tools
+## CLI Reference
 
-The SDK includes command-line tools for working with question bank data:
+The CLI provides validation, statistics, and QA tools. Use via npx (no install) or globally:
 
 ```bash
-# Install globally
-npm install -g @telebort/question-banks
-
-# Or use via npx
-npx @telebort/question-banks <command>
+npx @telebort/question-banks <command> [options]
 ```
 
 ### Commands
 
-#### `validate` - Validate Course JSON Files
+| Command | Description |
+|---------|-------------|
+| `validate <path>` | Validate JSON files against schemas |
+| `stats` | Show question bank statistics |
+| `quiz` | Generate sample quizzes |
+| `score` | Guessability analysis (anti-guessing QA) |
+
+### `validate` - Schema Validation
 
 ```bash
 # Validate a single file
-question-banks validate ./data/courses/ai-1.json
+npx @telebort/question-banks validate ./data/courses/ai-1.json
 
 # Validate all files in a directory
-question-banks validate ./data/courses/
+npx @telebort/question-banks validate ./data/courses/
 
-# Show all validation errors
-question-banks validate ./data/courses/ --verbose
+# Verbose output with all errors
+npx @telebort/question-banks validate ./data/courses/ --verbose
 ```
 
-#### `stats` - Show Statistics
+### `stats` - Question Bank Statistics
 
 ```bash
-# Show aggregate statistics
-question-banks stats --data-dir ./data/courses/
+# Show aggregate statistics across all courses
+npx @telebort/question-banks stats --data-dir ./data/courses/
 
-# Show statistics for a specific course
-question-banks stats --course ai-1 --data-dir ./data/courses/
+# Statistics for a specific course
+npx @telebort/question-banks stats --course ai-1 --data-dir ./data/courses/
 ```
 
-#### `quiz` - Generate Sample Quizzes
+### `quiz` - Sample Quiz Generation
 
 ```bash
 # Generate 5 random questions
-question-banks quiz --data-dir ./data/courses/
+npx @telebort/question-banks quiz --data-dir ./data/courses/
 
 # Generate 10 questions from a specific course
-question-banks quiz --course ai-1 --count 10 --data-dir ./data/courses/
+npx @telebort/question-banks quiz --course ai-1 --count 10 --data-dir ./data/courses/
 
-# Filter by difficulty and show answers
-question-banks quiz --difficulty hard --show-answers --data-dir ./data/courses/
+# Filter by difficulty and show correct answers
+npx @telebort/question-banks quiz --difficulty hard --show-answers --data-dir ./data/courses/
 ```
 
+### `score` - Guessability Analysis
+
+Run psychometric QA analysis to detect testwiseness vulnerabilities:
+
+```bash
+# Analyze a single course file
+npx @telebort/question-banks score ./data/courses/ai-1.json
+
+# Analyze with detailed output
+npx @telebort/question-banks score ./data/courses/ --verbose
+```
+
+**Output includes:**
+- Guessability score (0-100, lower is better)
+- Distractor quality metrics
+- Option length bias detection
+- Grammatical cue warnings
+
 ---
 
 ## Question Schema (v1.1)
@@ -471,6 +630,14 @@ MIT
 
 ---
 
+## Related Documentation
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) - Technical deep-dive (CAT, IRT, CDN)
+- [KNOWLEDGE-GRAPH.md](./KNOWLEDGE-GRAPH.md) - Topic-based query guide
+- [../ECOSYSTEM-OVERVIEW.md](../ECOSYSTEM-OVERVIEW.md) - High-level ecosystem overview
+
+---
+
 ## Support
 
 - Issues: [GitHub Issues](https://github.com/telebort/question-banks/issues)

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([
@@ -58,8 +88,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,
@@ -99,6 +129,8 @@ var CourseDomainSchema = zod.z.enum([
   "ai_ml_cv",
   "ai_generative",
   "ai_advanced",
+  "ai",
+  // Prompt Engineering (general AI)
   // Web Development
   "web_development",
   // Mobile Development
@@ -108,11 +140,21 @@ var CourseDomainSchema = zod.z.enum([
   "block_based",
   "python_programming",
   "design",
+  "artificial_intelligence",
+  // Block-based AI courses (BBAI)
+  // Computer Science
+  "cs_foundations",
+  // CS1-CS4 courses
   // Foundation
   "foundation",
-  "creative_computing"
+  "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"