@thanh01.pmt/domain-kit 0.4.0 → 0.5.0

package/dist/graph/index.cjs

@@ -1963,7 +1963,42 @@ async function generateKnowledgeGraph(options) {
   const structuredTopicsGuide = parsedSyllabus && parsedSyllabus.allTopics.length > 0 ? `
 STRUCTURED SYLLABUS TOPICS (Every topic MUST map to at least one concept to ensure 100% syllabus coverage):
 ` + parsedSyllabus.allTopics.map((t) => `- [${t.unitTitle}] ${t.id}: ${t.title} (Keywords: ${t.keywords.join(", ")})`).join("\n") + "\n" : "";
-  const systemPrompt = "You are an expert curriculum designer. Decompose the given subject into a structured knowledge graph with concepts, prerequisites, and problem types.\n\nCRITICAL RULES:\n1. Each concept MUST have the three depth layers, authored against this CONTRACT:\n   - ulo (WHAT + WHY): bound to the CONCEPT's intrinsic NATURE. It explains what the\n     concept is and why it exists \u2014 the problem it solves in principle. It must be\n     TECHNOLOGY-AGNOSTIC: never name a concrete library, API, function, file format,\n     tool or language feature. Typical assessment level: Remember / Understand.\n   - cio (HOW): the MECHANISM \u2014 how the concept works and solves that problem, step\n     by step. Still bound to the concept's nature: more concrete than the ULO, but\n     NOT tied to one specific technology (no concrete API names). CIO capability is\n     assessed INDIRECTLY, through completing contextual work, not in isolation.\n   - sio (IMPLEMENTATION): an array of 2-4 items. EVERY item MUST reference concrete\n     KEYWORDS/technologies (a real API, function, module, file, or named pattern) and\n     describe a completable, context-specific implementation task. Application,\n     Analysis and Creation skills are assessed INDIRECTLY through completing these\n     items. There is NO fixed Bloom ceiling for a layer \u2014 but concreteness MUST\n     strictly increase: SIO more technology-bound than CIO, CIO more concrete than ULO.\n   - prerequisites: concept IDs that must be learned first (MUST NOT create cycles)\n   - problem_types: 2-4 problem types with bloom_level and difficulty. Remember and\n     Understand problem types test the ULO/CIO directly; Apply-and-above types are\n     proxies for SIO completion in context.\n   - techniques: methods, formulas, tools\n2. Prerequisite chains MUST be acyclic (no concept can depend on itself or create a loop)\n3. Concepts should be ordered by prerequisite dependency (topological sort)\n4. Problem types should range from Remember to Apply (not all at same level)\n5. Group concepts into categories (chapters/sections)\n6. ALL text in ENGLISH (even if input is Vietnamese)\n7. NEVER invent concepts not present in the syllabus\n8. Return JSON matching the KnowledgeGraphSchema";
+  const systemPrompt = `You are an expert curriculum designer. Decompose the given subject into a structured knowledge graph with concepts, prerequisites, and problem types.
+
+CRITICAL RULES:
+1. Each concept MUST have the three depth layers, authored against this CONTRACT:
+   - ulo (WHAT + WHY): bound to the CONCEPT's intrinsic NATURE. It explains what the
+     concept is and why it exists \u2014 the problem it solves in principle. It must be
+     TECHNOLOGY-AGNOSTIC: never name a concrete library, API, function, file format,
+     tool or language feature. Typical assessment level: Remember / Understand.
+   - cio (HOW): the MECHANISM \u2014 how the concept works and solves that problem, step
+     by step. Still bound to the concept's nature: more concrete than the ULO, but
+     NOT tied to one specific technology (no concrete API names). CIO capability is
+     assessed INDIRECTLY, through completing contextual work, not in isolation.
+   - sio (IMPLEMENTATION): an array of 2-4 items. EVERY item MUST reference concrete
+     KEYWORDS/technologies (a real API, function, module, file, or named pattern) and
+     describe a completable, context-specific implementation task. Application,
+     Analysis and Creation skills are assessed INDIRECTLY through completing these
+     items. There is NO fixed Bloom ceiling for a layer \u2014 but concreteness MUST
+     strictly increase: SIO more technology-bound than CIO, CIO more concrete than ULO.
+   - prerequisites: concept IDs that must be learned first (MUST NOT create cycles)
+   - problem_types: 2-4 problem types with bloom_level and difficulty. Remember and
+     Understand problem types test the ULO/CIO directly; Apply-and-above types are
+     proxies for SIO completion in context.
+   - techniques: methods, formulas, tools
+2. Prerequisite chains MUST be acyclic (no concept can depend on itself or create a loop)
+3. Concepts should be ordered by prerequisite dependency (topological sort)
+4. Problem types should range from Remember to Apply (not all at same level)
+5. Group concepts into categories (chapters/sections)
+6. ALL text in ENGLISH (even if input is Vietnamese)
+7. NEVER invent concepts not present in the syllabus
+8. KEYWORDS: Each concept MUST include 5-10 domain-specific keywords that:
+   - Are concrete terms a student encounters when studying THIS concept
+   - Include at least 2 technology-specific terms (APIs, functions, types, tools)
+   - Are DISTINCT from keywords of other concepts (minimal overlap)
+   - NEVER generic English words (e.g. "view", "data", "code" are TOO generic)
+   - Example for "SwiftUI Layout": ["VStack", "HStack", "ZStack", ".padding()", ".frame()", "alignment", "Spacer", "LazyVGrid"]
+9. Return JSON matching the KnowledgeGraphSchema`;
   const userPrompt = `Subject: ${subject}
 ${description ? `Description: ${description}` : ""}
 ${structuredTopicsGuide}${truncatedSyllabus ? `Syllabus:
@@ -1984,8 +2019,9 @@ Return JSON:
     {
       "id": "C1",
       "name": "Concept name",
-      "description": "Brief description",
+      "description": "2-3 sentence description: what this concept covers, why a learner encounters it, and what mastering it enables. Must be specific enough that a student reading only this description understands the concept's scope.",
       "category": "category_id",
+      "keywords": ["specific_term_1", "concrete_api_2", "method_call_3", "tool_or_type_4", "syntax_keyword_5", "concept_term_6"],
       "ulo": "WHAT + WHY in technology-agnostic language: what the concept is and the problem it exists to solve. No library/API/tool names.",
       "cio": "HOW the mechanism works, still technology-agnostic but more concrete than the ULO.",
       "sio": ["Concrete task naming a REAL API/function/module/file from the target technology, completable end to end", "Another technology-bound task using a different concrete keyword"],
@@ -2026,18 +2062,23 @@ Return JSON:
   log("STEP_2", "Validating and cleaning knowledge graph...");
   const concepts = result.concepts || [];
   const categories = result.categories || [];
+  for (const c of concepts) {
+    if ((c.description || "").length < 50) {
+      warnings.push("Concept " + c.id + ": description too short (" + (c.description || "").length + " chars) \u2014 may produce shallow KX narratives");
+    }
+  }
   {
     const STOP = /* @__PURE__ */ new Set(["and", "the", "for", "with", "from", "that", "this", "into", "when", "while", "using", "their", "your", "each", "how", "why", "what", "between", "through", "about"]);
     const tokensFrom = (text) => text.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4 && !STOP.has(w));
     for (const c of concepts) {
       const existing = (c.keywords || []).map((k) => String(k).trim()).filter(Boolean);
       if (existing.length === 0) {
-        const derived = [.../* @__PURE__ */ new Set([...tokensFrom(c.name), ...tokensFrom(c.description || "")])].slice(0, 5);
+        const derived = [.../* @__PURE__ */ new Set([...tokensFrom(c.name), ...tokensFrom(c.description || "")])].slice(0, 8);
         if (derived.length === 0) {
           throw new Error("Concept " + c.id + " (" + c.name + ") has no keywords and none could be derived from name/description \u2014 fail-closed");
         }
         c.keywords = derived;
-        warnings.push("Concept " + c.id + ": empty keyword set - derived " + derived.join(", ") + " from name/description");
+        warnings.push("Concept " + c.id + ": empty keyword set - derived " + derived.join(", ") + " from name/description (WARNING: LLM returned no keywords)");
       } else {
         c.keywords = existing;
       }
@@ -2162,6 +2203,52 @@ Return JSON:
     }
     log("STEP_5", "Depth layers authored: " + concepts.length + " concepts, audit " + lo.audits.filter((a) => a.passed).length + "/" + concepts.length + " passed");
   }
+  {
+    for (const concept of concepts) {
+      const sioText = (concept.sio || []).join(" ");
+      const techTokens = [];
+      let m;
+      const techTokenRe = /`([^`]+)`/g;
+      while ((m = techTokenRe.exec(sioText)) !== null) {
+        if (m[1].length >= 3 && m[1].length <= 40) techTokens.push(m[1]);
+      }
+      const annotationRe = /(?:^|[\s(])(@[A-Za-z]\w*)/g;
+      while ((m = annotationRe.exec(sioText)) !== null) techTokens.push(m[1]);
+      const dotRe = /\b\w+\.\w+\(/g;
+      while ((m = dotRe.exec(sioText)) !== null) techTokens.push(m[0].replace("(", ""));
+      const modifierRe = /(?:^|[\s(])(\.[a-z]\w*)\b/g;
+      while ((m = modifierRe.exec(sioText)) !== null) techTokens.push(m[1]);
+      const camelRe = /\b[a-z]+[A-Z][A-Za-z]+\b/g;
+      while ((m = camelRe.exec(sioText)) !== null) techTokens.push(m[0]);
+      const existing = new Set((concept.keywords || []).map((k) => k.toLowerCase()));
+      const newTokens = [...new Set(techTokens)].filter((t) => !existing.has(t.toLowerCase())).slice(0, 8);
+      if (newTokens.length > 0) {
+        concept.keywords = [...concept.keywords || [], ...newTokens];
+        warnings.push("Concept " + concept.id + ": enriched keywords with " + newTokens.length + " SIO-derived tokens");
+      }
+    }
+    log("STEP_5b", "SIO-keyword enrichment complete");
+  }
+  {
+    for (const concept of concepts) {
+      const sioCount = (concept.sio || []).length;
+      const ptCount = (concept.problem_types || []).length;
+      const prereqCount = (concept.prerequisites || []).length;
+      const hasHighBloom = (concept.problem_types || []).some(
+        (pt) => ["Analyze", "Evaluate", "Create"].includes(pt.bloom_level || "")
+      );
+      const score = Math.min(1, sioCount * 0.2 + ptCount * 0.15 + prereqCount * 0.15 + (hasHighBloom ? 0.2 : 0));
+      const calibrated = Math.round(15 + score * 45);
+      const llmEstimate = concept.estimated_minutes || 30;
+      if (llmEstimate === 30 || Math.abs(calibrated - llmEstimate) / llmEstimate > 0.5) {
+        concept.estimated_minutes = calibrated;
+        if (llmEstimate !== calibrated) {
+          warnings.push("Concept " + concept.id + ": minutes calibrated " + llmEstimate + "m \u2192 " + calibrated + "m (score=" + score.toFixed(2) + ")");
+        }
+      }
+    }
+    log("STEP_5c", "Minute calibration complete");
+  }
   for (const step of learningPath) {
     if (!conceptIds.has(step.concept_id)) {
       warnings.push(`Learning path references non-existent concept ${step.concept_id}`);
@@ -2427,8 +2514,12 @@ async function decomposePhases(args) {
   const linkList = links.map(
     (l) => "- " + l.feature_id + " -> " + l.concept_id + " (" + l.depth + ")"
   ).join("\n") || "(none)";
-  const systemPrompt = 'You decompose a software project build into PROGRESSIVE COMPLETION PHASES for learning purposes.\n\nA phase is NOT a feature and NOT a milestone list: it is a cross-feature slice of the\nproduct whose completion yields a DEMONSTRABLY more complete product. Build up gradually:\nthe product grows feature by feature across phases, and each phase adds its features to\nwhat previous phases already built.\n\nRULES:\n1. Every feature must be assigned to EXACTLY ONE phase (no feature reused, none skipped).\n2. Phases are ordered; later phases depend on earlier ones and yield a more complete product.\n3. product_completion describes concretely what the product can DO once the phase is done.\n4. introduces lists which concepts the phase must teach BEFORE its feature work starts:\n   - aspect new: first time the concept appears in the course\n   - aspect advanced: a concept introduced in an EARLIER phase, revisited here at a\n     higher depth (an advanced aspect of the same concept, e.g. validation rules on top\n     of basic data modeling). Use the note field to say which aspect.\n   - aspect preview: a light awareness pass ("know it exists", ULO depth only, ~5 min)\n     placed in an EARLIER phase when its feature work needs the vocabulary before the\n     full teach. The anchor phase still owns the full new introduction.\n5. A concept MUST be introduced (new) no later than the first phase that consumes it.\n6. A concept must not be introduced before its own prerequisites are introduced.\n7. Typically 3-6 phases for a small project; keep phases balanced.\n8. Phase 1 usually covers project setup/foundation features plus the first minimal slice.\n9. Return JSON only.';
-  const baseUserPrompt = "FEATURES:\n" + featureList + "\n\nCONCEPTS:\n" + conceptList + "\n\nFEATURE-CONCEPT LINKS:\n" + linkList + "\n\nReturn JSON with a phases array. Each phase: { id: PH1, name, product_completion, feature_ids: [F0, F1], introduces: [{ concept_id: C1, aspect: new or advanced, note }] }.\n";
+  const systemPrompt = 'You decompose a software project build into PROGRESSIVE COMPLETION PHASES for learning purposes.\n\nA phase is NOT a feature and NOT a milestone list: it is a cross-feature slice of the\nproduct whose completion yields a DEMONSTRABLY more complete product. Build up gradually:\nthe product grows feature by feature across phases, and each phase adds its features to\nwhat previous phases already built.\n\nRULES:\n1. Every feature must be assigned to EXACTLY ONE phase (no feature reused, none skipped).\n2. Phases are ordered; later phases depend on earlier ones and yield a more complete product.\n3. product_completion describes concretely what the product can DO once the phase is done.\n4. introduces lists which concepts the phase must teach BEFORE its feature work starts:\n   - aspect new: first time the concept appears in the course\n   - aspect advanced: a concept introduced in an EARLIER phase, revisited here at a\n     higher depth (an advanced aspect of the same concept, e.g. validation rules on top\n     of basic data modeling). Use the note field to say which aspect.\n   - aspect preview: a light awareness pass ("know it exists", ULO depth only, ~5 min)\n     placed in an EARLIER phase when its feature work needs the vocabulary before the\n     full teach. The anchor phase still owns the full new introduction.\n5. A concept MUST be introduced (new) no later than the first phase that consumes it.\n6. A concept must not be introduced before its own prerequisites are introduced.\n7. Typically 3-6 phases for a small project; keep phases balanced.\n8. MINUTE BALANCE: Each phase should contain approximately 120-240 total minutes of\n   concept + feature work (about 3-5 sessions of 90 minutes each). If a phase\n   would contain < 60 minutes (too thin) or > 400 minutes (too heavy), rebalance.\n9. Phase 1 usually covers project setup/foundation features plus the first minimal slice.\n10. Return JSON only.';
+  const totalFeatureMinutes = features.reduce((s, f) => s + (f.steps || []).reduce((ss, st) => ss + (st.effort?.estimated_minutes || 15), 0), 0);
+  const totalConceptMinutes = concepts.reduce((s, c) => s + (c.estimated_minutes || 30), 0);
+  const totalMinutes = totalFeatureMinutes + totalConceptMinutes;
+  const targetPhaseCount = Math.max(3, Math.round(totalMinutes / 180));
+  const baseUserPrompt = "FEATURES:\n" + featureList + "\n\nCONCEPTS:\n" + conceptList + "\n\nFEATURE-CONCEPT LINKS:\n" + linkList + "\n\nTOTAL MINUTES: ~" + totalMinutes + "m (" + totalFeatureMinutes + "m features + " + totalConceptMinutes + "m concepts)\nTARGET: ~" + targetPhaseCount + " phases of ~180m each\n\nReturn JSON with a phases array. Each phase: { id: PH1, name, product_completion, feature_ids: [F0, F1], introduces: [{ concept_id: C1, aspect: new or advanced, note }] }.\n";
   const MAX_DECOMPOSE_ATTEMPTS = 3;
   let auditErrors = [];
   let phases = [];