@thanh01.pmt/curriculum-kit 1.0.1 → 1.0.3

package/dist/index-BIhxrUEa.d.cts

@@ -0,0 +1,359 @@
+import { MilestoneInput, LessonPlan, CurriculumQualityReport, ActivityLab, CodeLab, SelfLab, DiagnosticQuiz, SlideDeck, Handout, Worksheet, TeacherGuide, Extension, ProjectRoadmap } from './schemas/index.cjs';
+import { M as ModelResolutionOptions } from './provider-factory-DH3udYlN.cjs';
+import { G as GitPublishOptions, a as GitPublishResult, S as SupabasePublishOptions, b as SupabasePublishResult } from './supabasePublisher-C627qXFT.cjs';
+import { z } from 'zod';
+import { F as FrameworkPack, m as CoverageGateReport } from './standardsCoverageGate-BWAkXY76.cjs';
+
+type ArtifactType = 'lesson' | 'slide' | 'act' | 'quiz' | 'guide' | 'handout' | 'worksheet' | 'rubric' | 'ext' | 'glossary' | 'codelab' | 'bom' | 'exit_ticket' | 'tiered_practice' | 'choice_board' | 'science_lab' | 'task_cards' | 'station_rotation' | 'bell_ringer' | 'review_game' | 'graphic_organizer';
+type ScaffoldingLevel = 'foundation' | 'balanced' | 'advanced';
+interface SingleArtifactRequest {
+    artifactType: ArtifactType;
+    topic: string;
+    lessonId?: string;
+    lessonTitle?: string;
+    pedagogy?: '5e' | 'edp' | 'pbl' | 'general';
+    targetAge?: string;
+    scaffoldingLevel?: ScaffoldingLevel;
+    hardwarePlatform?: string[];
+    gradeLevel?: string;
+    studentCount?: string;
+    language?: string;
+    extraContext?: string;
+    config?: Record<string, any>;
+    contextSot?: {
+        framework?: string;
+        learnerProfile?: string;
+        lessonPlan?: string;
+        handout?: string;
+    };
+    options?: {
+        model?: string;
+        temperature?: number;
+        openrouterKey?: string;
+        alibabaKey?: string;
+        deepseekKey?: string;
+        geminiKey?: string;
+        nvidiaKey?: string;
+        openaiKey?: string;
+        anthropicKey?: string;
+    };
+    onChunk?: (chunk: string, type: 'content' | 'thought') => void;
+}
+interface SingleArtifactResult {
+    artifactType: ArtifactType;
+    filename: string;
+    content: string;
+    persona: string;
+    thought?: string;
+}
+/**
+ * Maps artifact type to default canonical filename and responsible agent persona
+ */
+declare function getArtifactMetadata(type: ArtifactType, lessonId?: string, pedagogy?: string): {
+    filename: string;
+    persona: string;
+    templateFile: string;
+};
+/**
+ * Universal Single Artifact Generator Service for all 21 Pedagogical JTBD Artifacts
+ */
+declare function generateSingleArtifact(req: SingleArtifactRequest): Promise<SingleArtifactResult>;
+
+/**
+ * Gate Settings — toàn bộ logic "ai kiểm artifact nào" nằm ở đây, trong kit.
+ * Composer chỉ gọi: resolveGateSettings(projectConfig.gateModes) rồi dùng kết quả.
+ *
+ * Vocabulary chuẩn (duy nhất, không có biến thể thứ hai):
+ *   'OFF'       — không kiểm
+ *   'LLM_JUDGE' — Agent kiểm (LLM-as-Judge)
+ *   'HITL'      — Human kiểm (human-in-the-loop)
+ *
+ * Phạm vi phủ: SOT foundation (Learner Profile, Framework, Style Guide — duyệt trước khi
+ * sinh content) + toàn bộ content artifacts.
+ */
+type CurriculumGateMode = 'OFF' | 'LLM_JUDGE' | 'HITL';
+type CurriculumArtifactType = 'LEARNER_PROFILE' | 'PROJECT_BRIEF' | 'REFERENCE_PACK' | 'CURRICULUM_FRAMEWORK' | 'KNOWLEDGE_EXPOSITION' | 'STYLE_GUIDE' | 'ART_DIRECTION' | 'LESSON' | 'ACT' | 'QUIZ' | 'SLIDE' | 'GUIDE' | 'WKS' | 'HANDOUT' | 'EXT' | 'CODE' | 'MEDIA_SCRIPT' | 'EXIT_TICKET';
+type GateSettings = Partial<Record<CurriculumArtifactType, CurriculumGateMode>>;
+type ResolvedGateSettings = Readonly<Record<CurriculumArtifactType, CurriculumGateMode>>;
+/** Mặc định trùng hành vi production hiện tại: SOT nền = HITL, LESSON/CODE = Agent kiểm, còn lại OFF. */
+declare const DEFAULT_GATE_SETTINGS: ResolvedGateSettings;
+/**
+ * Chuẩn hoá config thô (vd: gateModes đọc từ project.config.json của Composer) thành GateSettings.
+ * Key/value không nhận diện được bị bỏ qua — config sai không bao giờ làm workflow chết.
+ */
+declare function parseGateSettings(raw: unknown): GateSettings;
+/**
+ * Điểm vào DUY NHẤT: raw config (hoặc đã chuẩn hoá) → settings đầy đủ cho mọi artifact type.
+ * Key không có trong config nhận DEFAULT_GATE_SETTINGS.
+ */
+declare function resolveGateSettings(raw?: unknown): ResolvedGateSettings;
+/** Mode đã resolve cho 1 artifact type. */
+declare function gateModeFor(resolved: ResolvedGateSettings, type: CurriculumArtifactType): CurriculumGateMode;
+
+interface GenerateMasterLessonStepInput {
+    milestone: MilestoneInput;
+    language: string;
+    topic?: string;
+    targetAudience?: string;
+    contextContinuity?: string;
+    /** Pre-rendered STANDARDS CONTEXT block (verbatim standard statements). */
+    standardsContext?: string;
+    modelOptions?: ModelResolutionOptions;
+}
+declare function generateMasterLessonStep(input: GenerateMasterLessonStepInput): Promise<LessonPlan>;
+interface JudgeMasterLessonStepInput {
+    lessonId: string;
+    lesson: LessonPlan;
+    language: string;
+    targetObjectives: Array<{
+        code: string;
+        description: string;
+        bloomLevel: string;
+    }>;
+    /** Verbatim standard statements (canonical ID -> text) for the Standards Alignment judge dimension. */
+    standardStatements?: Record<string, string>;
+    modelOptions?: ModelResolutionOptions;
+}
+declare function judgeMasterLessonStep(input: JudgeMasterLessonStepInput): Promise<CurriculumQualityReport>;
+interface RepairMasterLessonStepInput {
+    milestone: MilestoneInput;
+    language: string;
+    topic?: string;
+    targetAudience?: string;
+    auditReport: CurriculumQualityReport;
+    /** Pre-rendered STANDARDS CONTEXT block — kept across repair so grounding is never lost. */
+    standardsContext?: string;
+    modelOptions?: ModelResolutionOptions;
+}
+declare function repairMasterLessonStep(input: RepairMasterLessonStepInput): Promise<LessonPlan>;
+
+declare function generateActivityStep(options: {
+    lesson: LessonPlan;
+    language: string;
+    modelOptions?: ModelResolutionOptions;
+}): Promise<ActivityLab>;
+declare function generateCodeLabStep(options: {
+    lesson: LessonPlan;
+    activity: ActivityLab;
+    language: string;
+    targetTechStack?: string[];
+    modelOptions?: ModelResolutionOptions;
+}): Promise<CodeLab>;
+declare function generateSelfLabStep(options: {
+    milestone: MilestoneInput;
+    language: string;
+    targetTechStack?: string[];
+    modelOptions?: ModelResolutionOptions;
+}): Promise<SelfLab>;
+declare function generateDiagnosticQuizStep(options: {
+    milestone: MilestoneInput;
+    language: string;
+    modelOptions?: ModelResolutionOptions;
+}): Promise<DiagnosticQuiz>;
+declare function generateSlidesStep(options: {
+    lesson: LessonPlan;
+    language: string;
+    modelOptions?: ModelResolutionOptions;
+}): Promise<SlideDeck>;
+declare function generateHandoutStep(options: {
+    lesson: LessonPlan;
+    language: string;
+    modelOptions?: ModelResolutionOptions;
+}): Promise<Handout>;
+declare function generateWorksheetStep(options: {
+    lesson: LessonPlan;
+    language: string;
+    modelOptions?: ModelResolutionOptions;
+}): Promise<Worksheet>;
+declare function generateTeacherGuideStep(options: {
+    lesson: LessonPlan;
+    activity: ActivityLab;
+    language: string;
+    modelOptions?: ModelResolutionOptions;
+}): Promise<TeacherGuide>;
+declare function generateExtensionStep(options: {
+    lesson: LessonPlan;
+    activity: ActivityLab;
+    language: string;
+    modelOptions?: ModelResolutionOptions;
+}): Promise<Extension>;
+
+interface JudgeSatelliteStepInput {
+    artifactType: string;
+    artifactId: string;
+    artifact: unknown;
+    language: string;
+    targetObjectives: Array<{
+        code: string;
+        description: string;
+        bloomLevel: string;
+    }>;
+    standardStatements?: Record<string, string>;
+    modelOptions?: ModelResolutionOptions;
+}
+/**
+ * Gate step for satellite artifacts (LLM_JUDGE mode).
+ * Judges any artifact JSON against the same 6-dimension rubric; returns the report.
+ * The workflow decides what to do with the verdict (log / block / store) — gate config stays the single source of truth.
+ */
+declare function judgeSatelliteStep(input: JudgeSatelliteStepInput): Promise<CurriculumQualityReport>;
+
+interface SaveMilestoneArtifactsInput {
+    jobId: string;
+    milestoneSlug: string;
+    lesson: LessonPlan;
+    activity?: ActivityLab;
+    codeLab?: CodeLab;
+    selfLab?: SelfLab;
+    quiz?: DiagnosticQuiz;
+    slides?: SlideDeck;
+    handout?: Handout;
+    worksheet?: Worksheet;
+    teacherGuide?: TeacherGuide;
+    extension?: Extension;
+    cheatSheetMarkdown?: string;
+    baseWorkspaceDir?: string;
+}
+interface SavedMilestoneResult {
+    milestoneSlug: string;
+    savedFiles: string[];
+}
+declare function saveMilestoneToWorkspaceStep(input: SaveMilestoneArtifactsInput): Promise<SavedMilestoneResult>;
+declare function publishToGitStep(options: GitPublishOptions): Promise<GitPublishResult>;
+declare function publishToSupabaseStep(options: SupabasePublishOptions): Promise<SupabasePublishResult>;
+
+declare const approvalPayloadSchema: z.ZodObject<{
+    approved: z.ZodBoolean;
+    reviewerName: z.ZodOptional<z.ZodString>;
+    feedback: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    approved: boolean;
+    feedback?: string | undefined;
+    timestamp?: string | undefined;
+    reviewerName?: string | undefined;
+}, {
+    approved: boolean;
+    feedback?: string | undefined;
+    timestamp?: string | undefined;
+    reviewerName?: string | undefined;
+}>;
+type ApprovalPayload = z.infer<typeof approvalPayloadSchema>;
+/**
+ * Durable Hook for Human-in-the-Loop curriculum approval gates.
+ * Pauses workflow with zero compute cost until an authorized user approves via UI/API.
+ */
+declare const lessonApprovalHook: any;
+
+interface ExecuteWithRateLimitOptions<T> {
+    stepName: string;
+    fn: () => Promise<T>;
+    maxAttempts?: number;
+}
+/**
+ * Wraps async LLM functions to automatically catch 429/503/transient network errors
+ * and throw a durable RetryableError with exponential backoff for Vercel Workflow runtime.
+ */
+declare function withRateLimitBackoff<T>(options: ExecuteWithRateLimitOptions<T>): Promise<T>;
+
+interface MilestoneWorkflowInput {
+    jobId: string;
+    milestone: MilestoneInput;
+    language?: string;
+    topic?: string;
+    targetAudience?: string;
+    techStack?: string[];
+    bundleTier?: 'minimum' | 'full';
+    baseWorkspaceDir?: string;
+    modelOptions?: ModelResolutionOptions;
+    /** Adopted Framework Packs (hydrated from the Standards Registry) for standards-grounded generation. */
+    standardsPacks?: FrameworkPack[];
+    /** Hard-block the milestone when standards coverage FAILs (default: true when packs provided). */
+    enforceStandardsCoverage?: boolean;
+    /** Gate Settings thô (vd: gateModes từ project.config.json) — kit tự chuẩn hoá. */
+    gateSettings?: unknown;
+}
+interface MilestoneWorkflowResult {
+    milestoneId: string;
+    milestoneSlug: string;
+    status: 'SUCCESS' | 'FAILED';
+    savedResult: SavedMilestoneResult;
+    judgeReport?: CurriculumQualityReport;
+    /** Per-artifact-type judge reports for satellites (Gate mode LLM_JUDGE only). */
+    satelliteJudgeReports?: Record<string, CurriculumQualityReport>;
+    /** The resolved gate settings actually applied in this run (for traceability). */
+    gatesResolved?: Record<string, string>;
+    /** Set when a Gate (e.g. HITL rejection) BLOCKED downstream production. */
+    gateBlocked?: {
+        artifactType: string;
+        reason: 'HITL_REJECTED' | 'HITL_REJECTED_V2';
+        feedback?: string;
+    };
+    standardsCoverage?: CoverageGateReport;
+    artifacts: {
+        lesson: LessonPlan;
+        activity?: ActivityLab;
+        codeLab?: CodeLab;
+        selfLab?: SelfLab;
+        quiz?: DiagnosticQuiz;
+        slides?: SlideDeck;
+        handout?: Handout;
+        worksheet?: Worksheet;
+        teacherGuide?: TeacherGuide;
+        extension?: Extension;
+    };
+}
+/**
+ * Child Workflow: Executes fine-grained durable generation for a single Milestone.
+ * Uses Step-level memoization, automatic LLM retries, and parallel satellite generation.
+ */
+declare function generateMilestoneWorkflow(input: MilestoneWorkflowInput): Promise<MilestoneWorkflowResult>;
+
+interface GenerateRoadmapWorkflowInput {
+    jobId?: string;
+    roadmap: ProjectRoadmap;
+    language?: string;
+    bundleTier?: 'minimum' | 'full';
+    batchSize?: number;
+    /** Gate Settings thô (vd: gateModes từ project.config.json) — kit tự chuẩn hoá. */
+    gateSettings?: unknown;
+    baseWorkspaceDir?: string;
+    gitPublishOptions?: Omit<GitPublishOptions, 'jobId' | 'localJobDir'>;
+    supabasePublishOptions?: Omit<SupabasePublishOptions, 'jobId' | 'courseTitle' | 'topic' | 'language' | 'milestones'>;
+    modelOptions?: ModelResolutionOptions;
+}
+interface RoadmapWorkflowSummary {
+    jobId: string;
+    courseTitle: string;
+    topic: string;
+    language: string;
+    totalMilestones: number;
+    successfulMilestones: number;
+    failedMilestones: number;
+    results: Array<{
+        milestoneId: string;
+        status: 'FULFILLED' | 'REJECTED';
+        result?: MilestoneWorkflowResult;
+        error?: string;
+    }>;
+    gitPublishResult?: GitPublishResult;
+    supabasePublishResult?: SupabasePublishResult;
+    workspaceDir: string;
+}
+/**
+ * Parent Workflow: Orchestrates durable generation of an entire Curriculum Roadmap.
+ * Implements Batching (Pattern 1), Failure Isolation, and Dual-Target Publishing (Git + Supabase).
+ */
+declare function generateRoadmapWorkflow(input: GenerateRoadmapWorkflowInput): Promise<RoadmapWorkflowSummary>;
+
+/**
+ * Step-level durable execution for generating a single standalone artifact.
+ */
+declare function executeSingleArtifactStep(request: SingleArtifactRequest): Promise<SingleArtifactResult>;
+/**
+ * Workflow for on-demand single artifact generation.
+ * Supports Vercel Workflow durable execution, step memoization, and automatic retry.
+ */
+declare function generateSingleArtifactWorkflow(request: SingleArtifactRequest): Promise<SingleArtifactResult>;
+
+export { type ArtifactType as A, parseGateSettings as B, type CurriculumGateMode as C, DEFAULT_GATE_SETTINGS as D, resolveGateSettings as E, gateModeFor as F, type GenerateMasterLessonStepInput as G, approvalPayloadSchema as H, type ApprovalPayload as I, type JudgeMasterLessonStepInput as J, lessonApprovalHook as K, type ExecuteWithRateLimitOptions as L, withRateLimitBackoff as M, type MilestoneWorkflowInput as N, type MilestoneWorkflowResult as O, generateMilestoneWorkflow as P, type GenerateRoadmapWorkflowInput as Q, type ResolvedGateSettings as R, type ScaffoldingLevel as S, type RoadmapWorkflowSummary as T, generateRoadmapWorkflow as U, executeSingleArtifactStep as V, generateSingleArtifactWorkflow as W, type SingleArtifactRequest as a, type SingleArtifactResult as b, generateSingleArtifact as c, generateMasterLessonStep as d, type RepairMasterLessonStepInput as e, generateActivityStep as f, getArtifactMetadata as g, generateCodeLabStep as h, generateSelfLabStep as i, judgeMasterLessonStep as j, generateDiagnosticQuizStep as k, generateSlidesStep as l, generateHandoutStep as m, generateWorksheetStep as n, generateTeacherGuideStep as o, generateExtensionStep as p, type JudgeSatelliteStepInput as q, repairMasterLessonStep as r, judgeSatelliteStep as s, type SaveMilestoneArtifactsInput as t, type SavedMilestoneResult as u, saveMilestoneToWorkspaceStep as v, publishToGitStep as w, publishToSupabaseStep as x, type CurriculumArtifactType as y, type GateSettings as z };