@thanh01.pmt/domain-kit 0.5.0 → 0.6.0

package/dist/graph/index.cjs

@@ -37,9 +37,10 @@ function resolveProviderChain(config) {
   return chain;
 }
 var MIN_REQUEST_INTERVAL_MS = 2500;
+var requestIntervalMs = Number(process.env.LLM_MIN_REQUEST_INTERVAL_MS || MIN_REQUEST_INTERVAL_MS);
 var lastRequestAt = 0;
 async function pacedDelay() {
-  const wait = lastRequestAt + MIN_REQUEST_INTERVAL_MS - Date.now();
+  const wait = lastRequestAt + requestIntervalMs - Date.now();
   if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
   lastRequestAt = Date.now();
 }
@@ -54,6 +55,10 @@ function createLlmClient(config) {
   primary.apiKey;
   primary.baseUrl;
   const model = primary.model;
+  if (config?.minRequestIntervalMs !== void 0) {
+    requestIntervalMs = Math.max(0, config.minRequestIntervalMs);
+  }
+  const callLog = [];
   async function chat(messages, options) {
     const temperature = options?.temperature ?? config?.temperature ?? 0.1;
     const maxTokens = options?.maxTokens ?? config?.maxTokens ?? parseInt(process.env.LLM_MAX_TOKENS || "65536", 10);
@@ -68,6 +73,7 @@ function createLlmClient(config) {
         await new Promise((resolve) => setTimeout(resolve, 2e4));
       }
       for (const provider of chain) {
+        const recIdx = callLog.push({ provider: provider.label, model: provider.model, ok: false }) - 1;
         try {
           const headers = {
             "Content-Type": "application/json",
@@ -128,6 +134,7 @@ function createLlmClient(config) {
               const retryData = await retry.json();
               const retryContent2 = retryData.choices?.[0]?.message?.content || "";
               if (!retryContent2.trim()) throw err;
+              callLog[recIdx] = { ...callLog[recIdx], ok: true };
               return {
                 content: retryContent2,
                 model: retryData.model || provider.model,
@@ -156,6 +163,7 @@ function createLlmClient(config) {
               if (!retry.ok) throw err;
               const retryData = await retry.json();
               const retryContent = retryData.choices?.[0]?.message?.content || "";
+              callLog[recIdx] = { ...callLog[recIdx], ok: true };
               return {
                 content: retryContent,
                 model: retryData.model || provider.model,
@@ -186,6 +194,7 @@ function createLlmClient(config) {
           };
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
+          callLog[recIdx] = { ...callLog[recIdx], ok: false, error: msg.slice(0, 200) };
           attempts.push(`${provider.label}: ${msg}`);
           lastError = err instanceof LlmClientError ? err : new LlmClientError(`[${provider.label}] ${msg}`);
         }
@@ -195,7 +204,7 @@ function createLlmClient(config) {
     }
     throw lastError ?? new LlmClientError("All LLM providers failed after " + MAX_CHAIN_ROUNDS + " rounds.");
   }
-  return { chat, model };
+  return { chat, model, callLog };
 }
 function parseJsonFromLlm(text) {
   let cleaned = text.trim();
@@ -259,8 +268,8 @@ async function llmChatJson(client, systemPrompt, userPrompt, options) {
 
 // src/graph/scaffoldExtractor.ts
 async function extractScaffold(options) {
-  const { goal, techStack, fileList, llmConfig } = options;
-  const client = createLlmClient(llmConfig);
+  const { goal, techStack, fileList, llmConfig, sharedClient } = options;
+  const client = sharedClient ?? createLlmClient(llmConfig);
   const fileListStr = fileList.length > 0 ? fileList.join("\n") : "(empty)";
   const systemPrompt = "You are a programming pedagogy expert. For ONE concrete project, extract the 'FOUNDATION & SETUP' feature (id F0) \u2014 the COMPLETE set of 'MUST-KNOW' steps the learner needs before studying the first feature. Break it into concrete ACTION steps (5-8 steps), each with completion_level='base'. Include:\n1. Tools required for this tech stack (IDE, simulator/emulator, terminal, git, package manager) + basic operations (open project, build, run, debug, commit).\n2. Create the initial project: from a template OR clone/open the base-project (the provided repo).\n3. MINIMAL programming knowledge of the language (variables, types, functions, if/for, view declaration) + build one small demo (e.g. a single-screen Hello World app) BEFORE touching the real project.\n4. Repo map of the actual project: folder structure, entry point, how to build/run, main architecture (MVVM/Flux...), important packages/modules.\n5. Development loop (build->run->see result->debug), how to read/fix basic compile errors, minimal git workflow (clone/branch/commit/push).\nkeywords[]: real tool/language terms (e.g. 'Xcode', 'Simulator', 'Git', 'Swift', '@main', 'MVVM'). files[]: leave [] or use real paths if the step touches specific files. description: ONE concise sentence, MAX 140 characters. intent: WHY this step matters. outcome: {user_visible: string, technical: string}. acceptance[]: 2 verifiable criteria. effort: {estimated_minutes: number, complexity: low|medium|high}. NEVER invent. ALL text must be in ENGLISH (technical terms stay as-is). Return JSON containing only feature F0.";
   const userPrompt = `App goal: ${goal}
@@ -345,8 +354,8 @@ ${content}`);
   return blocks.join("\n\n");
 }
 async function extractProjectOverview(options) {
-  const { goal, techStack, sdkApiIndex, fileContentsMap, astKeywords, llmConfig } = options;
-  const client = createLlmClient(llmConfig);
+  const { goal, techStack, sdkApiIndex, fileContentsMap, astKeywords, llmConfig, sharedClient } = options;
+  const client = sharedClient ?? createLlmClient(llmConfig);
   const usedSdkApis = sdkApiIndex.sdk_apis.filter((api) => api.used_in_demo).map((api) => api.name).slice(0, 2e3);
   const allFilesStr = buildSourceText(fileContentsMap);
   let keywordsAnchor = "";
@@ -415,8 +424,8 @@ ${content}`);
   return blocks.join("\n\n");
 }
 async function extractFeatureSteps(options) {
-  const { goal, techStack, sdkApiIndex, fileContentsMap, feature, llmConfig } = options;
-  const client = createLlmClient(llmConfig);
+  const { goal, techStack, sdkApiIndex, fileContentsMap, feature, llmConfig, sharedClient } = options;
+  const client = sharedClient ?? createLlmClient(llmConfig);
   const usedSdkApis = sdkApiIndex.sdk_apis.filter((api) => api.used_in_demo).map((api) => api.name).slice(0, 2e3);
   const allFilesStr = buildSourceText2(fileContentsMap);
   const fid = feature.id || "F_UNK";
@@ -483,8 +492,8 @@ Split this feature into 2-6 action steps. Return JSON:
     concept_codes: []
   }));
 }
-async function extractFeatureStepsBatched(goal, techStack, sdkApiIndex, fileContentsMap, featuresMeta, llmConfig) {
-  const client = createLlmClient(llmConfig);
+async function extractFeatureStepsBatched(goal, techStack, sdkApiIndex, fileContentsMap, featuresMeta, llmConfig, sharedClient) {
+  const client = sharedClient ?? createLlmClient(llmConfig);
   const usedSdkApis = sdkApiIndex.sdk_apis.filter((api) => api.used_in_demo).map((api) => api.name).slice(0, 2e3);
   const sourceText = buildSourceText2(fileContentsMap);
   const featuresListing = featuresMeta.map(
@@ -751,7 +760,7 @@ function inferDepthFromContext(keyword, fileContentsMap) {
   return { depth: "sio", rationale: `Default: treating '${keyword}' as SIO (implementation-level)` };
 }
 async function escalateAndMapConcepts(options) {
-  const { projectGraph, fileContentsMap, availableConcepts, conceptMapOverride, llmConfig } = options;
+  const { projectGraph, fileContentsMap, availableConcepts, conceptMapOverride, llmConfig, sharedClient } = options;
   const features = projectGraph.features || [];
   const allTerms = /* @__PURE__ */ new Set();
   for (const feature of features) {
@@ -767,7 +776,7 @@ async function escalateAndMapConcepts(options) {
     llmResults = conceptMapOverride;
   } else {
     try {
-      const client = createLlmClient(llmConfig);
+      const client = sharedClient ?? createLlmClient(llmConfig);
       const conceptBank = (availableConcepts || []).sort().join(", ") || "(empty)";
       const termEntries = termList.map((term) => {
         const snippets = extractTermSnippets(term, fileContentsMap);
@@ -820,13 +829,16 @@ Return JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "
       const cName = info.concept_name || kw;
       let depth = "sio";
       let depthRationale = "Default: SIO";
+      let depthSource = "override";
       if (info.depth && ["ulo", "cio", "sio"].includes(info.depth)) {
         depth = info.depth;
         depthRationale = `LLM classified as ${depth}`;
+        depthSource = "llm";
       } else {
         const inferred = inferDepthFromContext(kw, fileContentsMap);
         depth = inferred.depth;
         depthRationale = inferred.rationale;
+        depthSource = "heuristic";
       }
       const kwKey = `${cCode}::${kw}`;
       if (seen.has(kwKey)) continue;
@@ -844,6 +856,7 @@ Return JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "
         keyword: kw,
         depth,
         depth_rationale: depthRationale,
+        depth_source: depthSource,
         evidence_files: evidenceFiles
       });
     }
@@ -968,6 +981,13 @@ var ULO_CODE_RE = /^ULO-[A-Z][A-Z0-9_]*-\d{2}$/;
 var CIO_CODE_RE = /^CIO-[A-Z][A-Z0-9_]*-\d{2}-[A-Z][A-Z0-9_]*$/;
 var SIO_CODE_RE = /^SIO-[A-Z0-9]+-[A-Z][A-Z0-9_]*-\d{2}$/;
 
+// src/utils/diacritics.ts
+var COMBINING_MARKS = /[\u0300-\u036f]/g;
+var D_WITH_STROKE = /đ/gi;
+function stripDiacritics(s) {
+  return s.normalize("NFD").replace(COMBINING_MARKS, "").replace(D_WITH_STROKE, "d").toLowerCase();
+}
+
 // src/parsers/syllabusParser.ts
 var STOP_WORDS = /* @__PURE__ */ new Set([
   "and",
@@ -1730,7 +1750,7 @@ function loadKnowledgeTreeCatalog(tsvPath) {
 }
 function tokens(s) {
   return new Set(
-    s.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4)
+    stripDiacritics(s).replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4)
   );
 }
 function filterBySelection(catalog, selectedCategories, selectedTopics, analysisConcepts, maxConcepts = 120) {
@@ -1904,6 +1924,15 @@ async function standardizeConcepts(opts) {
 }
 
 // src/graph/knowledgeGraphPipeline.ts
+var MIN_CALIBRATION_MINUTES = 15;
+var MAX_CALIBRATION_MINUTES = 60;
+var DEFAULT_CONCEPT_MINUTES = 30;
+var MIN_CALIBRATION_DIVERGENCE = 0.5;
+function calibrateConceptMinutes(sioCount, problemTypeCount, prereqCount, hasHighBloom) {
+  const ratio = (value, cap) => Math.min(1, Math.max(0, value) / cap);
+  const score = 0.3 * ratio(sioCount, 4) + 0.25 * ratio(problemTypeCount, 4) + 0.2 * ratio(prereqCount, 4) + 0.25 * (hasHighBloom ? 1 : 0);
+  return Math.round(MIN_CALIBRATION_MINUTES + score * (MAX_CALIBRATION_MINUTES - MIN_CALIBRATION_MINUTES));
+}
 function topologicalSort(concepts) {
   const inDegree = /* @__PURE__ */ new Map();
   const adjacency = /* @__PURE__ */ new Map();
@@ -2069,7 +2098,7 @@ Return JSON:
   }
   {
     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));
+    const tokensFrom = (text) => stripDiacritics(text).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) {
@@ -2237,14 +2266,11 @@ Return JSON:
       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) {
+      const calibrated = calibrateConceptMinutes(sioCount, ptCount, prereqCount, hasHighBloom);
+      const llmEstimate = concept.estimated_minutes || DEFAULT_CONCEPT_MINUTES;
+      if (Math.abs(calibrated - llmEstimate) / llmEstimate > MIN_CALIBRATION_DIVERGENCE) {
         concept.estimated_minutes = calibrated;
-        if (llmEstimate !== calibrated) {
-          warnings.push("Concept " + concept.id + ": minutes calibrated " + llmEstimate + "m \u2192 " + calibrated + "m (score=" + score.toFixed(2) + ")");
-        }
+        warnings.push("Concept " + concept.id + ": minutes calibrated " + llmEstimate + "m \u2192 " + calibrated + "m");
       }
     }
     log("STEP_5c", "Minute calibration complete");
@@ -2269,7 +2295,8 @@ Return JSON:
   return {
     knowledgeGraph: verifiedGraph,
     warnings,
-    verificationReport: report
+    verificationReport: report,
+    provenance: client.callLog
   };
 }
 
@@ -2296,9 +2323,10 @@ async function generateHybridGraph(options) {
         description: "",
         total_project_minutes: 0,
         total_concept_minutes: 0,
-        estimated_total_minutes: 0
+        linked_prereq_minutes: 0
       },
-      warnings
+      warnings,
+      provenance: []
     };
   }
   const client = createLlmClient(llmConfig);
@@ -2379,9 +2407,14 @@ async function generateHybridGraph(options) {
       description: "Progressive completion path: " + phases.length + " phases, " + features.length + " features, " + concepts.length + " concepts",
       total_project_minutes: totalProjectMinutes,
       total_concept_minutes: totalConceptMinutes,
-      estimated_total_minutes: totalProjectMinutes + totalPrereqMinutes
+      // HG-1 (2026-10-05): renamed from estimated_total_minutes. It counts only
+      // concepts that HAVE a feature link (max per concept, not summed), so it
+      // is NOT the course total — see HybridGraphSchema.linked_prereq_minutes.
+      // The phase planner below commits to totalProjectMinutes + totalConceptMinutes.
+      linked_prereq_minutes: totalProjectMinutes + totalPrereqMinutes
     },
-    warnings
+    warnings,
+    provenance: client.callLog
   };
 }
 function auditPhasePlan(plan, features, concepts, links, warnings, log) {
@@ -2457,12 +2490,20 @@ function auditPhasePlan(plan, features, concepts, links, warnings, log) {
       } else {
         newIntroPhase.set(cid, order);
       }
+      introductions.push({ concept_id: cid, aspect, note: String(ri.note || "") });
+    }
+    for (const intro of introductions) {
+      const cid = intro.concept_id;
+      if (intro.aspect === "advanced") continue;
+      const introOrder = newIntroPhase.get(cid);
+      if (introOrder === void 0 || introOrder !== order) continue;
       for (const pre of prereqOf.get(cid) || []) {
-        if (!newIntroPhase.has(pre)) {
-          errors.push("Phase " + id + ": concept " + cid + " introduced before its prerequisite " + pre + " is introduced - violates the prerequisite chain");
+        const previewOrder = previewPhase.get(pre);
+        const covered = newIntroPhase.has(pre) || previewOrder !== void 0 && previewOrder < order;
+        if (!covered) {
+          errors.push("Phase " + id + ": concept " + cid + " introduced before its prerequisite " + pre + " is introduced (or previewed in an earlier phase) - violates the prerequisite chain");
         }
       }
-      introductions.push({ concept_id: cid, aspect, note: String(ri.note || "") });
     }
     phases.push({
       id,
@@ -2500,6 +2541,9 @@ function auditPhasePlan(plan, features, concepts, links, warnings, log) {
     if (anchor !== void 0 && anchor <= pOrder) {
       errors.push("Concept " + cid + " previewed in phase " + pOrder + " but fully introduced in phase " + anchor + " - preview must precede the anchor introduction");
     }
+    if (anchor === void 0) {
+      errors.push("Concept " + cid + " is previewed in phase " + pOrder + " but never fully introduced (aspect new) in any phase - a preview must have an anchor teach");
+    }
   }
   return { phases, errors };
 }