@thanh01.pmt/research-kit 1.1.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +27 -14
  2. package/dist/academic/index.d.cts +3 -3
  3. package/dist/academic/index.d.ts +3 -3
  4. package/dist/catalogBuilder-2i5KASUF.d.ts +82 -0
  5. package/dist/catalogBuilder-nrGYEY4b.d.cts +82 -0
  6. package/dist/chunk-LSMSIPTZ.js +3 -0
  7. package/dist/{chunk-2JEVBCIF.js.map → chunk-LSMSIPTZ.js.map} +1 -1
  8. package/dist/{chunk-KAFQVI2R.js → chunk-ON6VFCJO.js} +3 -3
  9. package/dist/{chunk-KAFQVI2R.js.map → chunk-ON6VFCJO.js.map} +1 -1
  10. package/dist/{chunk-GKF3NDEX.js → chunk-QFYM2NV4.js} +3 -3
  11. package/dist/{chunk-GKF3NDEX.js.map → chunk-QFYM2NV4.js.map} +1 -1
  12. package/dist/{chunk-XIF5YNI7.js → chunk-QK3LVGI7.js} +244 -8
  13. package/dist/chunk-QK3LVGI7.js.map +1 -0
  14. package/dist/{chunk-J7XKDMGL.js → chunk-X3X26W2I.js} +2 -2
  15. package/dist/{chunk-J7XKDMGL.js.map → chunk-X3X26W2I.js.map} +1 -1
  16. package/dist/{chunk-AUGVVZTL.js → chunk-XDDTHWJW.js} +173 -6
  17. package/dist/chunk-XDDTHWJW.js.map +1 -0
  18. package/dist/config/index.cjs.map +1 -1
  19. package/dist/config/index.d.cts +1 -1
  20. package/dist/config/index.d.ts +1 -1
  21. package/dist/config/index.js +1 -1
  22. package/dist/evidence/index.cjs.map +1 -1
  23. package/dist/evidence/index.d.cts +2 -2
  24. package/dist/evidence/index.d.ts +2 -2
  25. package/dist/evidence/index.js +2 -2
  26. package/dist/harvester/index.cjs +248 -6
  27. package/dist/harvester/index.cjs.map +1 -1
  28. package/dist/harvester/index.d.cts +63 -49
  29. package/dist/harvester/index.d.ts +63 -49
  30. package/dist/harvester/index.js +3 -3
  31. package/dist/{index-t8pahlJ4.d.ts → index-DlngvZBr.d.cts} +15 -1
  32. package/dist/{index-t8pahlJ4.d.cts → index-DlngvZBr.d.ts} +15 -1
  33. package/dist/index.cjs +443 -6
  34. package/dist/index.cjs.map +1 -1
  35. package/dist/index.d.cts +28 -13
  36. package/dist/index.d.ts +28 -13
  37. package/dist/index.js +37 -11
  38. package/dist/index.js.map +1 -1
  39. package/dist/{literatureReview-BTPFe7eb.d.cts → literatureReview-C7hsjrn4.d.cts} +1 -1
  40. package/dist/{literatureReview-hGbfrBmw.d.ts → literatureReview-DWl13r_3.d.ts} +1 -1
  41. package/dist/pipeline/index.cjs +361 -6
  42. package/dist/pipeline/index.cjs.map +1 -1
  43. package/dist/pipeline/index.d.cts +49 -5
  44. package/dist/pipeline/index.d.ts +49 -5
  45. package/dist/pipeline/index.js +4 -4
  46. package/dist/{webScraper-BhiQ8s9x.d.ts → webScraper-DBFUIqoO.d.ts} +1 -1
  47. package/dist/{webScraper-D9Ldus9p.d.cts → webScraper-yO9P-oLb.d.cts} +1 -1
  48. package/package.json +9 -8
  49. package/LICENSE +0 -21
  50. package/dist/catalogBuilder-CmmQzUnf.d.ts +0 -38
  51. package/dist/catalogBuilder-DgXYxL2F.d.cts +0 -38
  52. package/dist/chunk-2JEVBCIF.js +0 -3
  53. package/dist/chunk-AUGVVZTL.js.map +0 -1
  54. package/dist/chunk-XIF5YNI7.js.map +0 -1
@@ -775,7 +775,7 @@ var WebScraper = class {
775
775
  }
776
776
  const res = await fetch(jinaUrl, {
777
777
  headers,
778
- signal: AbortSignal.timeout(15e3)
778
+ signal: AbortSignal.timeout(8e3)
779
779
  });
780
780
  if (res.ok) {
781
781
  const markdown = await res.text();
@@ -971,6 +971,165 @@ var HealthAuditor = class {
971
971
  }
972
972
  };
973
973
 
974
+ // src/harvester/noiseFilter.ts
975
+ var ECOMMERCE_DOMAINS = /* @__PURE__ */ new Set([
976
+ "shopee.vn",
977
+ "shopee.com",
978
+ "lazada.vn",
979
+ "lazada.com",
980
+ "tiki.vn",
981
+ "sendo.vn",
982
+ "aliexpress.com",
983
+ "taobao.com",
984
+ "amazon.com",
985
+ "ebay.com",
986
+ "banggood.com"
987
+ ]);
988
+ var ECOMMERCE_AND_COMMERCIAL_PATTERNS = [
989
+ /\b(shopee|lazada|tiki|sendo|taobao|aliexpress)\b/i,
990
+ /\b(mua ngay|giá tốt|khuyến mãi|freeship|bán chạy|nhập khẩu chính hãng|cửa hàng|bảng giá|đặt hàng)\b/i,
991
+ /\b(buy now|add to cart|free shipping|discount|best price|on sale|shop now|in stock|order now)\b/i,
992
+ /\b(\d+[kKđ]|₫|\$\d+|\d+\s*(?:VNĐ|VND|usd))\b/i
993
+ ];
994
+ function isCommercialOrNoise(input) {
995
+ if (input.url) {
996
+ try {
997
+ const hostname = new URL(input.url).hostname.toLowerCase().replace(/^www\./, "");
998
+ if (ECOMMERCE_DOMAINS.has(hostname) || [...ECOMMERCE_DOMAINS].some((d) => hostname.endsWith(`.${d}`))) {
999
+ return true;
1000
+ }
1001
+ } catch {
1002
+ }
1003
+ }
1004
+ const combined = `${input.title || ""} ${input.snippet || ""}`;
1005
+ if (!combined.trim()) return false;
1006
+ for (const pattern of ECOMMERCE_AND_COMMERCIAL_PATTERNS) {
1007
+ if (pattern.test(combined)) {
1008
+ return true;
1009
+ }
1010
+ }
1011
+ return false;
1012
+ }
1013
+
1014
+ // src/harvester/graphUtils.ts
1015
+ function transitiveReduction(edges) {
1016
+ const uniqueEdges = [];
1017
+ const edgeSet = /* @__PURE__ */ new Set();
1018
+ for (const e of edges) {
1019
+ if (!e.source || !e.target || e.source === e.target) continue;
1020
+ const key = `${e.source}-->${e.target}`;
1021
+ if (!edgeSet.has(key)) {
1022
+ edgeSet.add(key);
1023
+ uniqueEdges.push(e);
1024
+ }
1025
+ }
1026
+ const adj = /* @__PURE__ */ new Map();
1027
+ for (const e of uniqueEdges) {
1028
+ if (!adj.has(e.source)) adj.set(e.source, /* @__PURE__ */ new Set());
1029
+ adj.get(e.source).add(e.target);
1030
+ }
1031
+ const reducedEdges = [];
1032
+ const removedTransitiveEdges = [];
1033
+ const hasAlternatePath = (start, target) => {
1034
+ const directNeighbors = adj.get(start);
1035
+ if (!directNeighbors) return false;
1036
+ const queue = [];
1037
+ const visited = /* @__PURE__ */ new Set([start]);
1038
+ for (const nxt of directNeighbors) {
1039
+ if (nxt !== target) {
1040
+ queue.push(nxt);
1041
+ visited.add(nxt);
1042
+ }
1043
+ }
1044
+ while (queue.length > 0) {
1045
+ const curr = queue.shift();
1046
+ if (curr === target) return true;
1047
+ const nextSet = adj.get(curr);
1048
+ if (!nextSet) continue;
1049
+ for (const nxt of nextSet) {
1050
+ if (nxt === target) return true;
1051
+ if (!visited.has(nxt)) {
1052
+ visited.add(nxt);
1053
+ queue.push(nxt);
1054
+ }
1055
+ }
1056
+ }
1057
+ return false;
1058
+ };
1059
+ for (const e of uniqueEdges) {
1060
+ if (hasAlternatePath(e.source, e.target) && !hasAlternatePath(e.target, e.source)) {
1061
+ removedTransitiveEdges.push(e);
1062
+ } else {
1063
+ reducedEdges.push(e);
1064
+ }
1065
+ }
1066
+ return { reducedEdges, removedTransitiveEdges };
1067
+ }
1068
+ function kahnTopologicalSort(nodes, edges) {
1069
+ const nodeSet = new Set(nodes);
1070
+ const validEdges = edges.filter((e) => nodeSet.has(e.source) && nodeSet.has(e.target) && e.source !== e.target);
1071
+ const inDegree = /* @__PURE__ */ new Map();
1072
+ const adj = /* @__PURE__ */ new Map();
1073
+ for (const n of nodes) {
1074
+ inDegree.set(n, 0);
1075
+ adj.set(n, /* @__PURE__ */ new Set());
1076
+ }
1077
+ for (const e of validEdges) {
1078
+ adj.get(e.source).add(e.target);
1079
+ inDegree.set(e.target, (inDegree.get(e.target) ?? 0) + 1);
1080
+ }
1081
+ const queue = [];
1082
+ for (const [node, deg] of inDegree.entries()) {
1083
+ if (deg === 0) queue.push(node);
1084
+ }
1085
+ const order = [];
1086
+ const cyclesBroken = [];
1087
+ const droppedEdges = [];
1088
+ while (order.length < nodes.length) {
1089
+ if (queue.length > 0) {
1090
+ queue.sort((a, b) => a.localeCompare(b));
1091
+ const curr = queue.shift();
1092
+ order.push(curr);
1093
+ const neighbors = adj.get(curr);
1094
+ if (neighbors) {
1095
+ for (const nxt of neighbors) {
1096
+ const nextDeg = (inDegree.get(nxt) ?? 1) - 1;
1097
+ inDegree.set(nxt, nextDeg);
1098
+ if (nextDeg === 0) queue.push(nxt);
1099
+ }
1100
+ }
1101
+ } else {
1102
+ const remaining = nodes.filter((n) => !order.includes(n));
1103
+ if (remaining.length === 0) break;
1104
+ remaining.sort((a, b) => (inDegree.get(a) ?? 0) - (inDegree.get(b) ?? 0) || a.localeCompare(b));
1105
+ const candidate = remaining[0];
1106
+ let dropped = false;
1107
+ for (const [src, targets] of adj.entries()) {
1108
+ if (remaining.includes(src) && targets.has(candidate)) {
1109
+ targets.delete(candidate);
1110
+ droppedEdges.push({ source: src, target: candidate });
1111
+ cyclesBroken.push(`${src} -> ${candidate}`);
1112
+ inDegree.set(candidate, Math.max(0, (inDegree.get(candidate) ?? 1) - 1));
1113
+ if (inDegree.get(candidate) === 0) {
1114
+ queue.push(candidate);
1115
+ }
1116
+ dropped = true;
1117
+ break;
1118
+ }
1119
+ }
1120
+ if (!dropped) {
1121
+ order.push(candidate);
1122
+ }
1123
+ }
1124
+ }
1125
+ return {
1126
+ isDag: cyclesBroken.length === 0,
1127
+ order,
1128
+ cyclesBroken,
1129
+ droppedEdges
1130
+ };
1131
+ }
1132
+
974
1133
  // src/harvester/termExtractor.ts
975
1134
  var VIETNAMESE_STOPWORDS = /* @__PURE__ */ new Set([
976
1135
  "l\xE0",
@@ -1184,6 +1343,7 @@ var PedagogicalTermExtractor = class {
1184
1343
  }
1185
1344
  };
1186
1345
  for (const { resourceId, doc } of docs) {
1346
+ if (isCommercialOrNoise({ url: doc.url, title: doc.title })) continue;
1187
1347
  const md = doc.markdownContent || "";
1188
1348
  const mdWithoutCode = md.replace(/```[\s\S]*?```/g, "\n");
1189
1349
  const bilingualMatches = mdWithoutCode.matchAll(
@@ -1287,7 +1447,7 @@ ${corpusPreview}`,
1287
1447
  `
1288
1448
  Return ONLY a valid JSON array of 6 to 12 atomic pedagogical concepts ordered from foundational to advanced.`,
1289
1449
  `IMPORTANT FOR VIETNAMESE TERMS: Keep multi-syllable Vietnamese compound terms intact (e.g. "Bi\u1EBFn tr\u1EA1ng th\xE1i", "C\u1EA3m bi\u1EBFn \xE1nh s\xE1ng", "V\xF2ng l\u1EB7p s\u1EF1 ki\u1EC7n") and pair them with accurate English canonical terms.`,
1290
- `Each item in the JSON array must have: {"id": "C_01", "term": "Display Name", "termVi": "Thu\u1EADt ng\u1EEF Ti\u1EBFng Vi\u1EC7t chu\u1EA9n", "termEn": "Canonical English Term", "category": "core_concept"|"api_syntax"|"hardware_component"|"pedagogical_pattern", "marrLayer": "ULO"|"CIO"|"SIO", "bloomLevel": "understand"|"apply"|"analyze", "salienceScore": 9.0, "definition": "1-sentence clear definition grounded in sources", "prerequisites": ["C_01"], "sourceIds": ["RES-01"]}`
1450
+ `Each item in the JSON array must have: {"id": "C_01", "term": "Display Name", "termVi": "Thu\u1EADt ng\u1EEF Ti\u1EBFng Vi\u1EC7t chu\u1EA9n", "termEn": "Canonical English Term", "category": "core_concept"|"api_syntax"|"hardware_component"|"pedagogical_pattern", "marrLayer": "ULO"|"CIO"|"SIO", "bloomLevel": "understand"|"apply"|"analyze", "salienceScore": 9.0, "definition": "1-sentence clear definition grounded in sources", "prerequisites": ["C_01"], "sourceIds": ["RES-01"], "facets": {"computationalPrinciple": "...", "mentalModel": "...", "syntaxAndTools": ["..."]}, "commonMisconceptions": ["..."]}`
1291
1451
  ].filter(Boolean).join("\n");
1292
1452
  const rawResponse = await options.llm(prompt, {
1293
1453
  system: "You are a Principal Computer Science Curriculum Architect & Bilingual Terminology Specialist (Vietnamese-English). Output strictly valid JSON array without markdown commentary.",
@@ -1299,9 +1459,26 @@ Return ONLY a valid JSON array of 6 to 12 atomic pedagogical concepts ordered fr
1299
1459
  const parsed = JSON.parse(jsonMatch[0]);
1300
1460
  if (Array.isArray(parsed) && parsed.length > 0) {
1301
1461
  const validIds = new Set(parsed.map((item, idx) => String(item.id || `C_${String(idx + 1).padStart(2, "0")}`)));
1462
+ const rawEdges = [];
1463
+ for (const item of parsed) {
1464
+ const targetId = String(item.id || "");
1465
+ if (!validIds.has(targetId)) continue;
1466
+ for (const p of item.prerequisites || []) {
1467
+ const srcId = String(p);
1468
+ if (validIds.has(srcId) && srcId !== targetId) {
1469
+ rawEdges.push({ source: srcId, target: targetId });
1470
+ }
1471
+ }
1472
+ }
1473
+ const { reducedEdges } = transitiveReduction(rawEdges);
1474
+ const reducedPrereqMap = /* @__PURE__ */ new Map();
1475
+ for (const e of reducedEdges) {
1476
+ if (!reducedPrereqMap.has(e.target)) reducedPrereqMap.set(e.target, []);
1477
+ reducedPrereqMap.get(e.target).push(e.source);
1478
+ }
1302
1479
  const concepts = parsed.map((item, idx) => {
1303
1480
  const id = String(item.id || `C_${String(idx + 1).padStart(2, "0")}`);
1304
- const prereqs = Array.isArray(item.prerequisites) ? item.prerequisites.map(String).filter((p) => p !== id && validIds.has(p)) : [];
1481
+ const prereqs = reducedPrereqMap.get(id) || [];
1305
1482
  return {
1306
1483
  id,
1307
1484
  term: String(item.term || item.termVi || item.termEn || `Concept ${idx + 1}`),
@@ -1313,12 +1490,22 @@ Return ONLY a valid JSON array of 6 to 12 atomic pedagogical concepts ordered fr
1313
1490
  salienceScore: Number(item.salienceScore) || 8,
1314
1491
  definition: String(item.definition || ""),
1315
1492
  prerequisites: prereqs,
1316
- sourceIds: Array.isArray(item.sourceIds) && item.sourceIds.length > 0 ? item.sourceIds.map(String) : ["RES-01"]
1493
+ sourceIds: Array.isArray(item.sourceIds) && item.sourceIds.length > 0 ? item.sourceIds.map(String) : ["RES-01"],
1494
+ facets: item.facets && typeof item.facets === "object" ? {
1495
+ computationalPrinciple: item.facets.computationalPrinciple ? String(item.facets.computationalPrinciple) : void 0,
1496
+ mentalModel: item.facets.mentalModel ? String(item.facets.mentalModel) : void 0,
1497
+ syntaxAndTools: Array.isArray(item.facets.syntaxAndTools) ? item.facets.syntaxAndTools.map(String) : void 0
1498
+ } : void 0,
1499
+ commonMisconceptions: Array.isArray(item.commonMisconceptions) ? item.commonMisconceptions.map(String) : void 0,
1500
+ troubleshootingHints: Array.isArray(item.troubleshootingHints) ? item.troubleshootingHints.map(String) : void 0
1317
1501
  };
1318
1502
  });
1503
+ const topoResult = kahnTopologicalSort(concepts.map((c) => c.id), reducedEdges);
1504
+ const conceptMap = new Map(concepts.map((c) => [c.id, c]));
1505
+ const sortedConcepts = topoResult.order.map((id) => conceptMap.get(id)).filter(Boolean);
1319
1506
  return {
1320
- concepts,
1321
- conceptDagTsv: this.formatConceptDagTsv(concepts),
1507
+ concepts: sortedConcepts.length > 0 ? sortedConcepts : concepts,
1508
+ conceptDagTsv: this.formatConceptDagTsv(sortedConcepts.length > 0 ? sortedConcepts : concepts),
1322
1509
  isLlmRefined: true,
1323
1510
  unrefinedCandidatesCount: detBundle.unrefinedCandidatesCount
1324
1511
  };
@@ -2320,9 +2507,177 @@ Return ONLY a valid JSON object with this structure:`,
2320
2507
  }
2321
2508
  };
2322
2509
 
2510
+ // src/pipeline/groundingEngine.ts
2511
+ var TechnicalGroundingEngine = class {
2512
+ constructor(searchEngine = new MultiSourceSearchEngine(), scraper = new WebScraper()) {
2513
+ this.searchEngine = searchEngine;
2514
+ this.scraper = scraper;
2515
+ }
2516
+ async buildFactsheet(topic, domain, context, llm) {
2517
+ const hardware = context?.hardwarePlatform || "";
2518
+ const software = context?.softwareEnv || "";
2519
+ const ageBand = context?.ageBand || [12, 18];
2520
+ const queries = [
2521
+ `${hardware} ${software} ${topic} compatibility setup official guide`.trim(),
2522
+ `${hardware || software || topic} beginner student project tutorial`.trim(),
2523
+ `${hardware || software || topic} common errors debugging mistakes pitfalls`.trim()
2524
+ ];
2525
+ const rawHits = [];
2526
+ for (const q of queries) {
2527
+ try {
2528
+ const hits = await this.searchEngine.search(q, { limit: 3 });
2529
+ for (const h of hits) {
2530
+ if (!isCommercialOrNoise({ url: h.url, title: h.title, snippet: h.content })) {
2531
+ if (!rawHits.some((existing) => existing.url === h.url)) {
2532
+ rawHits.push(h);
2533
+ }
2534
+ }
2535
+ }
2536
+ } catch {
2537
+ }
2538
+ }
2539
+ const hitsToScrape = rawHits.slice(0, 3);
2540
+ const scrapeResults = await Promise.allSettled(
2541
+ hitsToScrape.map(async (h) => {
2542
+ try {
2543
+ const doc = await this.scraper.scrapeUrl(h.url);
2544
+ if (doc && doc.markdownContent) {
2545
+ return {
2546
+ title: h.title,
2547
+ url: h.url,
2548
+ excerpt: doc.markdownContent.slice(0, 1500)
2549
+ };
2550
+ }
2551
+ } catch {
2552
+ }
2553
+ return { title: h.title, url: h.url, excerpt: h.content.slice(0, 500) };
2554
+ })
2555
+ );
2556
+ const scrapedSnippets = scrapeResults.map(
2557
+ (res, idx) => res.status === "fulfilled" ? res.value : { title: hitsToScrape[idx].title, url: hitsToScrape[idx].url, excerpt: hitsToScrape[idx].content.slice(0, 500) }
2558
+ );
2559
+ const defaultBottlenecks = [
2560
+ "Power supply insufficiency when driving motors or actuators simultaneously with microcontrollers.",
2561
+ "Baud rate mismatch or driver incompatibility across host OS versions.",
2562
+ "Syntax confusion between blocking loops (delay/sleep) and non-blocking event handling."
2563
+ ];
2564
+ const defaultExemplars = [
2565
+ {
2566
+ title: `${topic} Hands-on Foundation Project`,
2567
+ description: `Verified core implementation integrating ${hardware || "hardware"} and ${software || "software logic"}.`,
2568
+ targetAudience: `Students aged ${ageBand[0]}-${ageBand[1]}`,
2569
+ sourceUrl: scrapedSnippets[0]?.url,
2570
+ hardwareRequirements: hardware ? [hardware] : void 0,
2571
+ softwareRequirements: software ? [software] : void 0
2572
+ }
2573
+ ];
2574
+ let factsheet = {
2575
+ topic,
2576
+ domain,
2577
+ compatibilityMatrix: {
2578
+ hardwarePlatform: hardware || void 0,
2579
+ softwareEnv: software || void 0,
2580
+ verifiedCompatible: true,
2581
+ notes: [`Targeting ${hardware || "General Platform"} with ${software || "Standard SDK"}.`]
2582
+ },
2583
+ ageFeasibility: {
2584
+ recommendedMinAge: ageBand[0],
2585
+ recommendedMaxAge: ageBand[1],
2586
+ cognitiveReadinessVerdict: "feasible",
2587
+ potentialBarriers: ["Understanding abstract signal flows and state-based logic."]
2588
+ },
2589
+ exemplarProjects: defaultExemplars,
2590
+ technicalBottlenecks: defaultBottlenecks,
2591
+ groundingSources: scrapedSnippets.map((s) => ({ title: s.title, url: s.url })),
2592
+ markdownReport: ""
2593
+ };
2594
+ if (llm && scrapedSnippets.length > 0) {
2595
+ try {
2596
+ const prompt = [
2597
+ `You are a Lead STEM Curriculum Engineer. Analyze these research excerpts for topic: "${topic}".`,
2598
+ `Hardware: ${hardware || "N/A"}, Software/Env: ${software || "N/A"}, Student Age Band: ${ageBand[0]}-${ageBand[1]} years old.`,
2599
+ `
2600
+ Harvested Sources:
2601
+ ${scrapedSnippets.map((s, i) => `[Source ${i + 1}: ${s.title} (${s.url})]
2602
+ ${s.excerpt}`).join("\n\n")}`,
2603
+ `
2604
+ Synthesize a strictly valid JSON object with:`,
2605
+ `{`,
2606
+ ` "compatibilityVerdict": boolean,`,
2607
+ ` "compatibilityNotes": string[],`,
2608
+ ` "cognitiveReadiness": "feasible" | "challenging" | "excessive",`,
2609
+ ` "potentialBarriers": string[],`,
2610
+ ` "exemplars": [{"title": string, "description": string, "targetAudience": string, "hardwareRequirements": string[], "softwareRequirements": string[]}],`,
2611
+ ` "technicalBottlenecks": string[]`,
2612
+ `}`
2613
+ ].join("\n");
2614
+ const raw = await llm(prompt, {
2615
+ system: "Output strictly valid JSON object without markdown commentary.",
2616
+ temperature: 0.2,
2617
+ jsonMode: true
2618
+ });
2619
+ const jsonMatch = raw.match(/\{[\s\S]*\}/);
2620
+ if (jsonMatch) {
2621
+ const parsed = JSON.parse(jsonMatch[0]);
2622
+ factsheet.compatibilityMatrix.verifiedCompatible = Boolean(parsed.compatibilityVerdict ?? true);
2623
+ if (Array.isArray(parsed.compatibilityNotes)) factsheet.compatibilityMatrix.notes = parsed.compatibilityNotes.map(String);
2624
+ if (["feasible", "challenging", "excessive"].includes(parsed.cognitiveReadiness)) {
2625
+ factsheet.ageFeasibility.cognitiveReadinessVerdict = parsed.cognitiveReadiness;
2626
+ }
2627
+ if (Array.isArray(parsed.potentialBarriers)) factsheet.ageFeasibility.potentialBarriers = parsed.potentialBarriers.map(String);
2628
+ if (Array.isArray(parsed.exemplars) && parsed.exemplars.length > 0) {
2629
+ factsheet.exemplarProjects = parsed.exemplars.map((ex) => ({
2630
+ title: String(ex.title || "Verified Project"),
2631
+ description: String(ex.description || ""),
2632
+ targetAudience: String(ex.targetAudience || `Ages ${ageBand[0]}-${ageBand[1]}`),
2633
+ hardwareRequirements: Array.isArray(ex.hardwareRequirements) ? ex.hardwareRequirements.map(String) : void 0,
2634
+ softwareRequirements: Array.isArray(ex.softwareRequirements) ? ex.softwareRequirements.map(String) : void 0,
2635
+ sourceUrl: scrapedSnippets[0]?.url
2636
+ }));
2637
+ }
2638
+ if (Array.isArray(parsed.technicalBottlenecks)) factsheet.technicalBottlenecks = parsed.technicalBottlenecks.map(String);
2639
+ }
2640
+ } catch (err) {
2641
+ console.warn("[TechnicalGroundingEngine] LLM synthesis fallback to baseline:", err?.message || err);
2642
+ }
2643
+ }
2644
+ factsheet.markdownReport = this.renderMarkdownReport(factsheet);
2645
+ return factsheet;
2646
+ }
2647
+ renderMarkdownReport(fs) {
2648
+ const lines = [
2649
+ `# \u{1F6E0}\uFE0F Technical Grounding & Empirical Factsheet: ${fs.topic}`,
2650
+ `> **Domain:** \`${fs.domain.toUpperCase()}\` | **Feasibility:** \`${fs.ageFeasibility.cognitiveReadinessVerdict.toUpperCase()}\``,
2651
+ `
2652
+ ## 1. Compatibility & Tooling Verification`,
2653
+ `- **Hardware:** ${fs.compatibilityMatrix.hardwarePlatform || "N/A"}`,
2654
+ `- **Software / SDK:** ${fs.compatibilityMatrix.softwareEnv || "N/A"}`,
2655
+ `- **Verdict:** ${fs.compatibilityMatrix.verifiedCompatible ? "\u2705 Verified Compatible" : "\u26A0\uFE0F Compatibility Warning"}`,
2656
+ ...fs.compatibilityMatrix.notes.map((n) => ` - ${n}`),
2657
+ `
2658
+ ## 2. Age Feasibility & Learner Barriers (Ages ${fs.ageFeasibility.recommendedMinAge}\u2013${fs.ageFeasibility.recommendedMaxAge})`,
2659
+ ...fs.ageFeasibility.potentialBarriers.map((b) => `- \u26A0\uFE0F ${b}`),
2660
+ `
2661
+ ## 3. Real-World Exemplar Projects`,
2662
+ ...fs.exemplarProjects.map((ex, idx) => `### Exemplar ${idx + 1}: ${ex.title}
2663
+ - **Summary:** ${ex.description}
2664
+ - **Audience:** ${ex.targetAudience}${ex.sourceUrl ? `
2665
+ - **Reference:** [Link](${ex.sourceUrl})` : ""}`),
2666
+ `
2667
+ ## 4. Technical Bottlenecks & Pitfalls to Avoid`,
2668
+ ...fs.technicalBottlenecks.map((bn) => `- \u{1F6D1} ${bn}`),
2669
+ `
2670
+ ## 5. Grounding Citations`,
2671
+ ...fs.groundingSources.map((s, idx) => `${idx + 1}. [${s.title}](${s.url})`)
2672
+ ];
2673
+ return lines.join("\n");
2674
+ }
2675
+ };
2676
+
2323
2677
  exports.CampaignPlanner = CampaignPlanner;
2324
2678
  exports.HarvestPipeline = HarvestPipeline;
2325
2679
  exports.ReferencePackBuilder = ReferencePackBuilder;
2680
+ exports.TechnicalGroundingEngine = TechnicalGroundingEngine;
2326
2681
  exports.normalizeUrlForDedup = normalizeUrlForDedup;
2327
2682
  //# sourceMappingURL=index.cjs.map
2328
2683
  //# sourceMappingURL=index.cjs.map