@thanh01.pmt/curriculum-kit

A high-fidelity AI curriculum and pedagogical content generation engine powered by Vercel AI SDK, Zod, and Bloom-aligned standards.

🌟 Overview

@thanh01.pmt/curriculum-kit transforms Roadmaps and Learning Paths from the Knowledge Graph (knowledge-tree) into rich, multi-modal educational materials:

• LESSON.md: Master Lesson Design Plan & Teaching Flow.
• ACT.md: Step-by-step hands-on activities with BOM (Hardware, Software, Consumables) and safety warnings.
• CODE: Starter code, solution code, and automated test cases.
• WKS.md: Scaffolded worksheets following the Gradual Release Model (I Do $\rightarrow$ We Do $\rightarrow$ You Do).
• SLIDE.md: 15-slide Marp presentation deck.
• HANDOUT.md: Instant-reference student cheat sheets (5-Second Rule).
• GUIDE.md: Teacher guides with misconception handling and rubrics.
• QUIZ: Bloom-aligned assessment questions consumable by @thanh01.pmt/interactive-quiz-kit.

📁 Architecture & Documentation

• Architecture Decision Record: docs/adrs/ADR-0001-curriculum-kit-architecture.md
• Implementation Plan & DoD: docs/plans/implementation-plan-and-dod.md

🌐 Language Policy

• 100% English Canonical Prompts: All system instructions and prompt builders are written strictly in English.
• Strict Target Output Language: Every generation flow accepts language ("vi", "en", etc.), and the AI strictly outputs pedagogical explanations in the requested language while preserving international technical syntax and keywords.

🧮 Planner Internals (P52, 2026-09-18)

buildCurriculumPlan turns a CurriculumFeed into a session plan in three ordered stages. All three are pure functions of the feed — no LLM calls.

1. Depth reconcile — reconcilePlanDepth (services/depthReconciler.ts)

Runs before unit building/packing, only when total_sessions is fixed. When the bottom-up minute total exceeds the course budget (total_sessions × session minutes × (1 − overhead_ratio)), the planner previously had only one direction: stretch time (part-sessions). The reconciler adds the missing one — lower knowledge depth along the Bruner spiral (SIO → CIO → ULO) instead of cutting phases.

• Downgrade priority (least pedagogical loss first): (1) advanced revisit nodes (__ADVxx ids), (2) SIO→CIO on leaf concepts, (3) SIO→CIO on non-leaf non-core, (4) CIO→ULO on leaf, (5) CIO→ULO on non-leaf non-core; within a tier, largest minutes_saved first. Leaf-ness is computed at the concept level (classifyDepthCandidates: a concept is a leaf when no other concept lists it as a prerequisite; __ADV/__PREV ids map back to their base).
• Absolute exclusions: is_core concepts (Master-Tree core — escalate instead), non-concept nodes (product steps are build work, not knowledge depth), and nodes with no declared depth_hint (never guess).
• Bound: fixed-point loop capped at 5 rounds; mutates only minutes/depth_hint — no edges added/removed, no order changes, so the teaching-order invariant is preserved by construction.
• Escalation: when candidates are exhausted while still over budget, returns escalate: true + deficitMinutes; the planner surfaces a budget_escalation: … human review required warning — it never silently cuts a phase.

2. Unit building + checkpoint-aware session cutting — packUnitSessions

Bins nodes into sessions at the content budget. When the next node would overflow, cutBackToCheckpoint searches for the latest node whose cumulative minutes fall inside the window [budget × (1 − SESSION_CUT_TOLERANCE), budget] (SESSION_CUT_TOLERANCE = 0.15, constants/pedagogy.ts) that carries a user_visible_deliverable (projected from the ProjectGraph step's outcome.user_visible by domain-kit). The cut lands on that checkpoint; displaced nodes are requeued in teaching order (nothing is dropped, wall-clock never exceeds the session length). Oversized nodes keep the existing multi-part split. No checkpoint inside the window → raw minute cut + a no-checkpoint-within-tolerance warning (the future hook for scaffold_candidates).

3. ZPD audit

The single ZPD/overload audit pass runs after reconcile and packing, so it always sees the final node set — the reconciler cannot invalidate it by construction (it only shrinks minutes/depth, never adds new-concept events).

Planning nodes carry the reconcile inputs from the feed: depth_variants ({ulo, cio, sio} minute estimates), depth_scaffold_candidates, and is_core. See the domain-kit README (Schemas → FeedNode) for the feed-side contract.