@thanh01.pmt/research-kit 1.1.1 → 1.2.1

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 (59) 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/academic/index.js +2 -1
  5. package/dist/catalogBuilder-BaVRvg-9.d.cts +90 -0
  6. package/dist/catalogBuilder-DHV6y1gD.d.ts +90 -0
  7. package/dist/chunk-AKEI7H2C.js +223 -0
  8. package/dist/chunk-AKEI7H2C.js.map +1 -0
  9. package/dist/{chunk-XIF5YNI7.js → chunk-HZNSZDSM.js} +318 -8
  10. package/dist/chunk-HZNSZDSM.js.map +1 -0
  11. package/dist/chunk-LSMSIPTZ.js +3 -0
  12. package/dist/{chunk-2JEVBCIF.js.map → chunk-LSMSIPTZ.js.map} +1 -1
  13. package/dist/{chunk-KAFQVI2R.js → chunk-ON6VFCJO.js} +3 -3
  14. package/dist/{chunk-KAFQVI2R.js.map → chunk-ON6VFCJO.js.map} +1 -1
  15. package/dist/{chunk-GKF3NDEX.js → chunk-QFYM2NV4.js} +3 -3
  16. package/dist/{chunk-GKF3NDEX.js.map → chunk-QFYM2NV4.js.map} +1 -1
  17. package/dist/{chunk-AUGVVZTL.js → chunk-RW7VS7NI.js} +175 -7
  18. package/dist/chunk-RW7VS7NI.js.map +1 -0
  19. package/dist/{chunk-DOXSPRSP.js → chunk-UKGR45VZ.js} +3 -223
  20. package/dist/chunk-UKGR45VZ.js.map +1 -0
  21. package/dist/{chunk-J7XKDMGL.js → chunk-X3X26W2I.js} +2 -2
  22. package/dist/{chunk-J7XKDMGL.js.map → chunk-X3X26W2I.js.map} +1 -1
  23. package/dist/config/index.cjs.map +1 -1
  24. package/dist/config/index.d.cts +1 -1
  25. package/dist/config/index.d.ts +1 -1
  26. package/dist/config/index.js +1 -1
  27. package/dist/evidence/index.cjs.map +1 -1
  28. package/dist/evidence/index.d.cts +2 -2
  29. package/dist/evidence/index.d.ts +2 -2
  30. package/dist/evidence/index.js +2 -2
  31. package/dist/harvester/index.cjs +542 -6
  32. package/dist/harvester/index.cjs.map +1 -1
  33. package/dist/harvester/index.d.cts +63 -49
  34. package/dist/harvester/index.d.ts +63 -49
  35. package/dist/harvester/index.js +4 -3
  36. package/dist/{index-t8pahlJ4.d.ts → index-DlngvZBr.d.cts} +15 -1
  37. package/dist/{index-t8pahlJ4.d.cts → index-DlngvZBr.d.ts} +15 -1
  38. package/dist/index.cjs +515 -6
  39. package/dist/index.cjs.map +1 -1
  40. package/dist/index.d.cts +28 -13
  41. package/dist/index.d.ts +28 -13
  42. package/dist/index.js +41 -13
  43. package/dist/index.js.map +1 -1
  44. package/dist/{literatureReview-BTPFe7eb.d.cts → literatureReview-C7hsjrn4.d.cts} +1 -1
  45. package/dist/{literatureReview-hGbfrBmw.d.ts → literatureReview-DWl13r_3.d.ts} +1 -1
  46. package/dist/pipeline/index.cjs +658 -231
  47. package/dist/pipeline/index.cjs.map +1 -1
  48. package/dist/pipeline/index.d.cts +49 -5
  49. package/dist/pipeline/index.d.ts +49 -5
  50. package/dist/pipeline/index.js +6 -5
  51. package/dist/{webScraper-BhiQ8s9x.d.ts → webScraper-DBFUIqoO.d.ts} +1 -1
  52. package/dist/{webScraper-D9Ldus9p.d.cts → webScraper-yO9P-oLb.d.cts} +1 -1
  53. package/package.json +1 -1
  54. package/dist/catalogBuilder-CmmQzUnf.d.ts +0 -38
  55. package/dist/catalogBuilder-DgXYxL2F.d.cts +0 -38
  56. package/dist/chunk-2JEVBCIF.js +0 -3
  57. package/dist/chunk-AUGVVZTL.js.map +0 -1
  58. package/dist/chunk-DOXSPRSP.js.map +0 -1
  59. package/dist/chunk-XIF5YNI7.js.map +0 -1
package/dist/index.cjs CHANGED
@@ -700,14 +700,25 @@ var MultiSourceSearchEngine = class {
700
700
  tavilyKey;
701
701
  exaKey;
702
702
  serperKey;
703
+ searxngHost;
704
+ searxngHeaders;
703
705
  allowEnvFallback;
704
706
  customAdapter;
707
+ academicEngine;
705
708
  constructor(options = {}) {
706
709
  this.allowEnvFallback = options.allowEnvFallback ?? true;
707
710
  this.tavilyKey = options.apiKeys?.tavily || options.tavilyKey || (this.allowEnvFallback ? process.env.TAVILY_API_KEY : void 0);
708
711
  this.exaKey = options.apiKeys?.exa || options.exaKey || (this.allowEnvFallback ? process.env.EXA_API_KEY : void 0);
709
712
  this.serperKey = options.apiKeys?.serper || options.serperKey || (this.allowEnvFallback ? process.env.SERPER_API_KEY : void 0);
713
+ this.searxngHost = options.searxngHost || (this.allowEnvFallback ? process.env.SEARXNG_URL || process.env.SEARXNG_HOST : void 0);
714
+ const cfId = process.env.CF_ACCESS_CLIENT_ID;
715
+ const cfSecret = process.env.CF_ACCESS_CLIENT_SECRET;
716
+ this.searxngHeaders = {
717
+ ...options.searxngHeaders || {},
718
+ ...cfId && cfSecret ? { "CF-Access-Client-Id": cfId, "CF-Access-Client-Secret": cfSecret } : {}
719
+ };
710
720
  this.customAdapter = options.customAdapter;
721
+ this.academicEngine = new AcademicSearchEngine({ allowEnvFallback: this.allowEnvFallback });
711
722
  }
712
723
  setCustomAdapter(adapter) {
713
724
  this.customAdapter = adapter;
@@ -717,6 +728,12 @@ var MultiSourceSearchEngine = class {
717
728
  if (keys.exa !== void 0) this.exaKey = keys.exa;
718
729
  if (keys.serper !== void 0) this.serperKey = keys.serper;
719
730
  }
731
+ setSearxng(host, headers) {
732
+ this.searxngHost = host;
733
+ if (headers) {
734
+ this.searxngHeaders = { ...this.searxngHeaders, ...headers };
735
+ }
736
+ }
720
737
  async search(query, options = {}) {
721
738
  const limit = options.limit ?? 5;
722
739
  const adapter = options.customAdapter || this.customAdapter;
@@ -737,9 +754,30 @@ var MultiSourceSearchEngine = class {
737
754
  console.warn("[MultiSourceSearchEngine] Custom search adapter failed:", e?.message || e);
738
755
  }
739
756
  }
757
+ if (preferred === "academic") {
758
+ try {
759
+ const papers = await this.academicEngine.searchPapers(query, { limit });
760
+ if (papers.length > 0) {
761
+ return papers.map((p) => ({
762
+ title: p.title,
763
+ url: p.url || p.pdfUrl || (p.doi ? `https://doi.org/${p.doi}` : `https://openalex.org/${p.id}`),
764
+ content: p.tldr || p.abstract || "",
765
+ score: p.citationCount,
766
+ engine: "academic"
767
+ }));
768
+ }
769
+ } catch (e) {
770
+ console.warn("[MultiSourceSearchEngine] Academic search failed:", e?.message || e);
771
+ }
772
+ }
740
773
  const tavilyKey = options.apiKeys?.tavily || options.tavilyKey || this.tavilyKey;
741
774
  const exaKey = options.apiKeys?.exa || options.exaKey || this.exaKey;
742
775
  const serperKey = options.apiKeys?.serper || options.serperKey || this.serperKey;
776
+ const searxngHost = options.searxngHost || this.searxngHost;
777
+ if (preferred === "searxng" && searxngHost) {
778
+ const searxHits = await this.querySearxng(query, searxngHost, limit, options.searxngHeaders);
779
+ if (searxHits.length > 0) return searxHits;
780
+ }
743
781
  if (preferred === "exa" && exaKey) {
744
782
  const exaHits = await this.queryExa(query, exaKey, limit, options.domainFilter);
745
783
  if (exaHits.length > 0) return exaHits;
@@ -794,10 +832,44 @@ var MultiSourceSearchEngine = class {
794
832
  const serperHits = await this.querySerper(query, serperKey, limit);
795
833
  if (serperHits.length > 0) return serperHits;
796
834
  }
835
+ if (searxngHost) {
836
+ const searxHits = await this.querySearxng(query, searxngHost, limit, options.searxngHeaders);
837
+ if (searxHits.length > 0) return searxHits;
838
+ }
797
839
  const ddgHits = await this.queryDuckDuckGo(query, limit);
798
840
  if (ddgHits.length > 0) return ddgHits;
799
841
  return [];
800
842
  }
843
+ async querySearxng(query, searxngHost, limit, customHeaders) {
844
+ try {
845
+ const cleanHost = searxngHost.replace(/\/$/, "");
846
+ const searchUrl = `${cleanHost}/search?q=${encodeURIComponent(query)}&format=json`;
847
+ const headers = {
848
+ "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
849
+ ...this.searxngHeaders || {},
850
+ ...customHeaders || {}
851
+ };
852
+ const res = await fetch(searchUrl, {
853
+ headers,
854
+ signal: AbortSignal.timeout(1e4)
855
+ });
856
+ if (res.ok) {
857
+ const data = await res.json();
858
+ if (Array.isArray(data?.results) && data.results.length > 0) {
859
+ return data.results.slice(0, limit).map((r) => ({
860
+ title: r.title || "Untitled",
861
+ url: r.url,
862
+ content: r.content || r.snippet || "",
863
+ score: r.score,
864
+ engine: "searxng"
865
+ }));
866
+ }
867
+ }
868
+ } catch (e) {
869
+ console.warn("[MultiSourceSearchEngine] SearXNG attempt failed:", e?.message || e);
870
+ }
871
+ return [];
872
+ }
801
873
  async queryExa(query, exaKey, limit, domainFilter) {
802
874
  try {
803
875
  const body = {
@@ -1141,7 +1213,7 @@ var WebScraper = class {
1141
1213
  }
1142
1214
  const res = await fetch(jinaUrl, {
1143
1215
  headers,
1144
- signal: AbortSignal.timeout(15e3)
1216
+ signal: AbortSignal.timeout(8e3)
1145
1217
  });
1146
1218
  if (res.ok) {
1147
1219
  const markdown = await res.text();
@@ -1226,6 +1298,214 @@ ${p.replace(/<[^>]+>/g, " ").trim()}
1226
1298
  }
1227
1299
  };
1228
1300
 
1301
+ // src/harvester/noiseFilter.ts
1302
+ var ECOMMERCE_DOMAINS = /* @__PURE__ */ new Set([
1303
+ "shopee.vn",
1304
+ "shopee.com",
1305
+ "lazada.vn",
1306
+ "lazada.com",
1307
+ "tiki.vn",
1308
+ "sendo.vn",
1309
+ "aliexpress.com",
1310
+ "taobao.com",
1311
+ "amazon.com",
1312
+ "ebay.com",
1313
+ "banggood.com"
1314
+ ]);
1315
+ var ECOMMERCE_AND_COMMERCIAL_PATTERNS = [
1316
+ /\b(shopee|lazada|tiki|sendo|taobao|aliexpress)\b/i,
1317
+ /\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,
1318
+ /\b(buy now|add to cart|free shipping|discount|best price|on sale|shop now|in stock|order now)\b/i,
1319
+ /\b(\d+[kKđ]|₫|\$\d+|\d+\s*(?:VNĐ|VND|usd))\b/i
1320
+ ];
1321
+ function isCommercialOrNoise(input) {
1322
+ if (input.url) {
1323
+ try {
1324
+ const hostname = new URL(input.url).hostname.toLowerCase().replace(/^www\./, "");
1325
+ if (ECOMMERCE_DOMAINS.has(hostname) || [...ECOMMERCE_DOMAINS].some((d) => hostname.endsWith(`.${d}`))) {
1326
+ return true;
1327
+ }
1328
+ } catch {
1329
+ }
1330
+ }
1331
+ const combined = `${input.title || ""} ${input.snippet || ""}`;
1332
+ if (!combined.trim()) return false;
1333
+ for (const pattern of ECOMMERCE_AND_COMMERCIAL_PATTERNS) {
1334
+ if (pattern.test(combined)) {
1335
+ return true;
1336
+ }
1337
+ }
1338
+ return false;
1339
+ }
1340
+ function evaluateTechnicalDensity(markdown) {
1341
+ if (!markdown || markdown.trim().length < 80) {
1342
+ return {
1343
+ score: 1,
1344
+ isSufficientQuality: false,
1345
+ codeDensity: 0,
1346
+ technicalTermDensity: 0,
1347
+ hasStructure: false,
1348
+ reasons: ["Content is too short or empty."]
1349
+ };
1350
+ }
1351
+ const reasons = [];
1352
+ const totalLength = markdown.length;
1353
+ const codeBlocks = markdown.match(/```[\s\S]*?```/g) || [];
1354
+ const inlineCode = markdown.match(/`[^`\n]+`/g) || [];
1355
+ const totalCodeChars = codeBlocks.reduce((sum, b) => sum + b.length, 0) + inlineCode.reduce((sum, c) => sum + c.length, 0);
1356
+ const codeDensity = Math.min(1, totalCodeChars / Math.max(1, totalLength));
1357
+ const headings = markdown.match(/^#{1,4}\s+.+$/gm) || [];
1358
+ const hasStructure = headings.length >= 2;
1359
+ const techKeywords = markdown.match(
1360
+ /\b(function|class|method|struct|interface|api|hardware|sensor|pin|circuit|logic|loop|state|algorithm|test|debug|schema|protocol|variable)\b/gi
1361
+ ) || [];
1362
+ const technicalTermDensity = Math.min(1, techKeywords.length * 10 / Math.max(100, markdown.split(/\s+/).length));
1363
+ let score = 5;
1364
+ if (codeDensity > 0.15) {
1365
+ score += 2;
1366
+ } else if (codeDensity > 0.05) {
1367
+ score += 1;
1368
+ } else {
1369
+ reasons.push("Low code or API snippet density.");
1370
+ }
1371
+ if (hasStructure) {
1372
+ score += 1.5;
1373
+ } else {
1374
+ reasons.push("Lacks clear hierarchical markdown headings.");
1375
+ }
1376
+ if (technicalTermDensity > 0.08) {
1377
+ score += 1.5;
1378
+ }
1379
+ const finalScore = Math.min(10, Math.max(1, Math.round(score * 10) / 10));
1380
+ return {
1381
+ score: finalScore,
1382
+ isSufficientQuality: finalScore >= 6,
1383
+ codeDensity,
1384
+ technicalTermDensity,
1385
+ hasStructure,
1386
+ reasons
1387
+ };
1388
+ }
1389
+
1390
+ // src/harvester/graphUtils.ts
1391
+ function transitiveReduction(edges) {
1392
+ const uniqueEdges = [];
1393
+ const edgeSet = /* @__PURE__ */ new Set();
1394
+ for (const e of edges) {
1395
+ if (!e.source || !e.target || e.source === e.target) continue;
1396
+ const key = `${e.source}-->${e.target}`;
1397
+ if (!edgeSet.has(key)) {
1398
+ edgeSet.add(key);
1399
+ uniqueEdges.push(e);
1400
+ }
1401
+ }
1402
+ const adj = /* @__PURE__ */ new Map();
1403
+ for (const e of uniqueEdges) {
1404
+ if (!adj.has(e.source)) adj.set(e.source, /* @__PURE__ */ new Set());
1405
+ adj.get(e.source).add(e.target);
1406
+ }
1407
+ const reducedEdges = [];
1408
+ const removedTransitiveEdges = [];
1409
+ const hasAlternatePath = (start, target) => {
1410
+ const directNeighbors = adj.get(start);
1411
+ if (!directNeighbors) return false;
1412
+ const queue = [];
1413
+ const visited = /* @__PURE__ */ new Set([start]);
1414
+ for (const nxt of directNeighbors) {
1415
+ if (nxt !== target) {
1416
+ queue.push(nxt);
1417
+ visited.add(nxt);
1418
+ }
1419
+ }
1420
+ while (queue.length > 0) {
1421
+ const curr = queue.shift();
1422
+ if (curr === target) return true;
1423
+ const nextSet = adj.get(curr);
1424
+ if (!nextSet) continue;
1425
+ for (const nxt of nextSet) {
1426
+ if (nxt === target) return true;
1427
+ if (!visited.has(nxt)) {
1428
+ visited.add(nxt);
1429
+ queue.push(nxt);
1430
+ }
1431
+ }
1432
+ }
1433
+ return false;
1434
+ };
1435
+ for (const e of uniqueEdges) {
1436
+ if (hasAlternatePath(e.source, e.target) && !hasAlternatePath(e.target, e.source)) {
1437
+ removedTransitiveEdges.push(e);
1438
+ } else {
1439
+ reducedEdges.push(e);
1440
+ }
1441
+ }
1442
+ return { reducedEdges, removedTransitiveEdges };
1443
+ }
1444
+ function kahnTopologicalSort(nodes, edges) {
1445
+ const nodeSet = new Set(nodes);
1446
+ const validEdges = edges.filter((e) => nodeSet.has(e.source) && nodeSet.has(e.target) && e.source !== e.target);
1447
+ const inDegree = /* @__PURE__ */ new Map();
1448
+ const adj = /* @__PURE__ */ new Map();
1449
+ for (const n of nodes) {
1450
+ inDegree.set(n, 0);
1451
+ adj.set(n, /* @__PURE__ */ new Set());
1452
+ }
1453
+ for (const e of validEdges) {
1454
+ adj.get(e.source).add(e.target);
1455
+ inDegree.set(e.target, (inDegree.get(e.target) ?? 0) + 1);
1456
+ }
1457
+ const queue = [];
1458
+ for (const [node, deg] of inDegree.entries()) {
1459
+ if (deg === 0) queue.push(node);
1460
+ }
1461
+ const order = [];
1462
+ const cyclesBroken = [];
1463
+ const droppedEdges = [];
1464
+ while (order.length < nodes.length) {
1465
+ if (queue.length > 0) {
1466
+ queue.sort((a, b) => a.localeCompare(b));
1467
+ const curr = queue.shift();
1468
+ order.push(curr);
1469
+ const neighbors = adj.get(curr);
1470
+ if (neighbors) {
1471
+ for (const nxt of neighbors) {
1472
+ const nextDeg = (inDegree.get(nxt) ?? 1) - 1;
1473
+ inDegree.set(nxt, nextDeg);
1474
+ if (nextDeg === 0) queue.push(nxt);
1475
+ }
1476
+ }
1477
+ } else {
1478
+ const remaining = nodes.filter((n) => !order.includes(n));
1479
+ if (remaining.length === 0) break;
1480
+ remaining.sort((a, b) => (inDegree.get(a) ?? 0) - (inDegree.get(b) ?? 0) || a.localeCompare(b));
1481
+ const candidate = remaining[0];
1482
+ let dropped = false;
1483
+ for (const [src, targets] of adj.entries()) {
1484
+ if (remaining.includes(src) && targets.has(candidate)) {
1485
+ targets.delete(candidate);
1486
+ droppedEdges.push({ source: src, target: candidate });
1487
+ cyclesBroken.push(`${src} -> ${candidate}`);
1488
+ inDegree.set(candidate, Math.max(0, (inDegree.get(candidate) ?? 1) - 1));
1489
+ if (inDegree.get(candidate) === 0) {
1490
+ queue.push(candidate);
1491
+ }
1492
+ dropped = true;
1493
+ break;
1494
+ }
1495
+ }
1496
+ if (!dropped) {
1497
+ order.push(candidate);
1498
+ }
1499
+ }
1500
+ }
1501
+ return {
1502
+ isDag: cyclesBroken.length === 0,
1503
+ order,
1504
+ cyclesBroken,
1505
+ droppedEdges
1506
+ };
1507
+ }
1508
+
1229
1509
  // src/harvester/termExtractor.ts
1230
1510
  var VIETNAMESE_STOPWORDS = /* @__PURE__ */ new Set([
1231
1511
  "l\xE0",
@@ -1439,6 +1719,7 @@ var PedagogicalTermExtractor = class {
1439
1719
  }
1440
1720
  };
1441
1721
  for (const { resourceId, doc } of docs) {
1722
+ if (isCommercialOrNoise({ url: doc.url, title: doc.title })) continue;
1442
1723
  const md = doc.markdownContent || "";
1443
1724
  const mdWithoutCode = md.replace(/```[\s\S]*?```/g, "\n");
1444
1725
  const bilingualMatches = mdWithoutCode.matchAll(
@@ -1542,7 +1823,7 @@ ${corpusPreview}`,
1542
1823
  `
1543
1824
  Return ONLY a valid JSON array of 6 to 12 atomic pedagogical concepts ordered from foundational to advanced.`,
1544
1825
  `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.`,
1545
- `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"]}`
1826
+ `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": ["..."]}`
1546
1827
  ].filter(Boolean).join("\n");
1547
1828
  const rawResponse = await options.llm(prompt, {
1548
1829
  system: "You are a Principal Computer Science Curriculum Architect & Bilingual Terminology Specialist (Vietnamese-English). Output strictly valid JSON array without markdown commentary.",
@@ -1554,9 +1835,26 @@ Return ONLY a valid JSON array of 6 to 12 atomic pedagogical concepts ordered fr
1554
1835
  const parsed = JSON.parse(jsonMatch[0]);
1555
1836
  if (Array.isArray(parsed) && parsed.length > 0) {
1556
1837
  const validIds = new Set(parsed.map((item, idx) => String(item.id || `C_${String(idx + 1).padStart(2, "0")}`)));
1838
+ const rawEdges = [];
1839
+ for (const item of parsed) {
1840
+ const targetId = String(item.id || "");
1841
+ if (!validIds.has(targetId)) continue;
1842
+ for (const p of item.prerequisites || []) {
1843
+ const srcId = String(p);
1844
+ if (validIds.has(srcId) && srcId !== targetId) {
1845
+ rawEdges.push({ source: srcId, target: targetId });
1846
+ }
1847
+ }
1848
+ }
1849
+ const { reducedEdges } = transitiveReduction(rawEdges);
1850
+ const reducedPrereqMap = /* @__PURE__ */ new Map();
1851
+ for (const e of reducedEdges) {
1852
+ if (!reducedPrereqMap.has(e.target)) reducedPrereqMap.set(e.target, []);
1853
+ reducedPrereqMap.get(e.target).push(e.source);
1854
+ }
1557
1855
  const concepts = parsed.map((item, idx) => {
1558
1856
  const id = String(item.id || `C_${String(idx + 1).padStart(2, "0")}`);
1559
- const prereqs = Array.isArray(item.prerequisites) ? item.prerequisites.map(String).filter((p) => p !== id && validIds.has(p)) : [];
1857
+ const prereqs = reducedPrereqMap.get(id) || [];
1560
1858
  return {
1561
1859
  id,
1562
1860
  term: String(item.term || item.termVi || item.termEn || `Concept ${idx + 1}`),
@@ -1568,12 +1866,22 @@ Return ONLY a valid JSON array of 6 to 12 atomic pedagogical concepts ordered fr
1568
1866
  salienceScore: Number(item.salienceScore) || 8,
1569
1867
  definition: String(item.definition || ""),
1570
1868
  prerequisites: prereqs,
1571
- sourceIds: Array.isArray(item.sourceIds) && item.sourceIds.length > 0 ? item.sourceIds.map(String) : ["RES-01"]
1869
+ sourceIds: Array.isArray(item.sourceIds) && item.sourceIds.length > 0 ? item.sourceIds.map(String) : ["RES-01"],
1870
+ facets: item.facets && typeof item.facets === "object" ? {
1871
+ computationalPrinciple: item.facets.computationalPrinciple ? String(item.facets.computationalPrinciple) : void 0,
1872
+ mentalModel: item.facets.mentalModel ? String(item.facets.mentalModel) : void 0,
1873
+ syntaxAndTools: Array.isArray(item.facets.syntaxAndTools) ? item.facets.syntaxAndTools.map(String) : void 0
1874
+ } : void 0,
1875
+ commonMisconceptions: Array.isArray(item.commonMisconceptions) ? item.commonMisconceptions.map(String) : void 0,
1876
+ troubleshootingHints: Array.isArray(item.troubleshootingHints) ? item.troubleshootingHints.map(String) : void 0
1572
1877
  };
1573
1878
  });
1879
+ const topoResult = kahnTopologicalSort(concepts.map((c) => c.id), reducedEdges);
1880
+ const conceptMap = new Map(concepts.map((c) => [c.id, c]));
1881
+ const sortedConcepts = topoResult.order.map((id) => conceptMap.get(id)).filter(Boolean);
1574
1882
  return {
1575
- concepts,
1576
- conceptDagTsv: this.formatConceptDagTsv(concepts),
1883
+ concepts: sortedConcepts.length > 0 ? sortedConcepts : concepts,
1884
+ conceptDagTsv: this.formatConceptDagTsv(sortedConcepts.length > 0 ? sortedConcepts : concepts),
1577
1885
  isLlmRefined: true,
1578
1886
  unrefinedCandidatesCount: detBundle.unrefinedCandidatesCount
1579
1887
  };
@@ -2619,6 +2927,173 @@ Return ONLY a valid JSON object with this structure:`,
2619
2927
  }
2620
2928
  };
2621
2929
 
2930
+ // src/pipeline/groundingEngine.ts
2931
+ var TechnicalGroundingEngine = class {
2932
+ constructor(searchEngine = new MultiSourceSearchEngine(), scraper = new WebScraper()) {
2933
+ this.searchEngine = searchEngine;
2934
+ this.scraper = scraper;
2935
+ }
2936
+ async buildFactsheet(topic, domain, context, llm) {
2937
+ const hardware = context?.hardwarePlatform || "";
2938
+ const software = context?.softwareEnv || "";
2939
+ const ageBand = context?.ageBand || [12, 18];
2940
+ const queries = [
2941
+ `${hardware} ${software} ${topic} compatibility setup official guide`.trim(),
2942
+ `${hardware || software || topic} beginner student project tutorial`.trim(),
2943
+ `${hardware || software || topic} common errors debugging mistakes pitfalls`.trim()
2944
+ ];
2945
+ const rawHits = [];
2946
+ for (const q of queries) {
2947
+ try {
2948
+ const hits = await this.searchEngine.search(q, { limit: 3 });
2949
+ for (const h of hits) {
2950
+ if (!isCommercialOrNoise({ url: h.url, title: h.title, snippet: h.content })) {
2951
+ if (!rawHits.some((existing) => existing.url === h.url)) {
2952
+ rawHits.push(h);
2953
+ }
2954
+ }
2955
+ }
2956
+ } catch {
2957
+ }
2958
+ }
2959
+ const hitsToScrape = rawHits.slice(0, 3);
2960
+ const scrapeResults = await Promise.allSettled(
2961
+ hitsToScrape.map(async (h) => {
2962
+ try {
2963
+ const doc = await this.scraper.scrapeUrl(h.url);
2964
+ if (doc && doc.markdownContent) {
2965
+ return {
2966
+ title: h.title,
2967
+ url: h.url,
2968
+ excerpt: doc.markdownContent.slice(0, 1500)
2969
+ };
2970
+ }
2971
+ } catch {
2972
+ }
2973
+ return { title: h.title, url: h.url, excerpt: h.content.slice(0, 500) };
2974
+ })
2975
+ );
2976
+ const scrapedSnippets = scrapeResults.map(
2977
+ (res, idx) => res.status === "fulfilled" ? res.value : { title: hitsToScrape[idx].title, url: hitsToScrape[idx].url, excerpt: hitsToScrape[idx].content.slice(0, 500) }
2978
+ );
2979
+ const defaultBottlenecks = [
2980
+ "Power supply insufficiency when driving motors or actuators simultaneously with microcontrollers.",
2981
+ "Baud rate mismatch or driver incompatibility across host OS versions.",
2982
+ "Syntax confusion between blocking loops (delay/sleep) and non-blocking event handling."
2983
+ ];
2984
+ const defaultExemplars = [
2985
+ {
2986
+ title: `${topic} Hands-on Foundation Project`,
2987
+ description: `Verified core implementation integrating ${hardware || "hardware"} and ${software || "software logic"}.`,
2988
+ targetAudience: `Students aged ${ageBand[0]}-${ageBand[1]}`,
2989
+ sourceUrl: scrapedSnippets[0]?.url,
2990
+ hardwareRequirements: hardware ? [hardware] : void 0,
2991
+ softwareRequirements: software ? [software] : void 0
2992
+ }
2993
+ ];
2994
+ let factsheet = {
2995
+ topic,
2996
+ domain,
2997
+ compatibilityMatrix: {
2998
+ hardwarePlatform: hardware || void 0,
2999
+ softwareEnv: software || void 0,
3000
+ verifiedCompatible: true,
3001
+ notes: [`Targeting ${hardware || "General Platform"} with ${software || "Standard SDK"}.`]
3002
+ },
3003
+ ageFeasibility: {
3004
+ recommendedMinAge: ageBand[0],
3005
+ recommendedMaxAge: ageBand[1],
3006
+ cognitiveReadinessVerdict: "feasible",
3007
+ potentialBarriers: ["Understanding abstract signal flows and state-based logic."]
3008
+ },
3009
+ exemplarProjects: defaultExemplars,
3010
+ technicalBottlenecks: defaultBottlenecks,
3011
+ groundingSources: scrapedSnippets.map((s) => ({ title: s.title, url: s.url })),
3012
+ markdownReport: ""
3013
+ };
3014
+ if (llm && scrapedSnippets.length > 0) {
3015
+ try {
3016
+ const prompt = [
3017
+ `You are a Lead STEM Curriculum Engineer. Analyze these research excerpts for topic: "${topic}".`,
3018
+ `Hardware: ${hardware || "N/A"}, Software/Env: ${software || "N/A"}, Student Age Band: ${ageBand[0]}-${ageBand[1]} years old.`,
3019
+ `
3020
+ Harvested Sources:
3021
+ ${scrapedSnippets.map((s, i) => `[Source ${i + 1}: ${s.title} (${s.url})]
3022
+ ${s.excerpt}`).join("\n\n")}`,
3023
+ `
3024
+ Synthesize a strictly valid JSON object with:`,
3025
+ `{`,
3026
+ ` "compatibilityVerdict": boolean,`,
3027
+ ` "compatibilityNotes": string[],`,
3028
+ ` "cognitiveReadiness": "feasible" | "challenging" | "excessive",`,
3029
+ ` "potentialBarriers": string[],`,
3030
+ ` "exemplars": [{"title": string, "description": string, "targetAudience": string, "hardwareRequirements": string[], "softwareRequirements": string[]}],`,
3031
+ ` "technicalBottlenecks": string[]`,
3032
+ `}`
3033
+ ].join("\n");
3034
+ const raw = await llm(prompt, {
3035
+ system: "Output strictly valid JSON object without markdown commentary.",
3036
+ temperature: 0.2,
3037
+ jsonMode: true
3038
+ });
3039
+ const jsonMatch = raw.match(/\{[\s\S]*\}/);
3040
+ if (jsonMatch) {
3041
+ const parsed = JSON.parse(jsonMatch[0]);
3042
+ factsheet.compatibilityMatrix.verifiedCompatible = Boolean(parsed.compatibilityVerdict ?? true);
3043
+ if (Array.isArray(parsed.compatibilityNotes)) factsheet.compatibilityMatrix.notes = parsed.compatibilityNotes.map(String);
3044
+ if (["feasible", "challenging", "excessive"].includes(parsed.cognitiveReadiness)) {
3045
+ factsheet.ageFeasibility.cognitiveReadinessVerdict = parsed.cognitiveReadiness;
3046
+ }
3047
+ if (Array.isArray(parsed.potentialBarriers)) factsheet.ageFeasibility.potentialBarriers = parsed.potentialBarriers.map(String);
3048
+ if (Array.isArray(parsed.exemplars) && parsed.exemplars.length > 0) {
3049
+ factsheet.exemplarProjects = parsed.exemplars.map((ex) => ({
3050
+ title: String(ex.title || "Verified Project"),
3051
+ description: String(ex.description || ""),
3052
+ targetAudience: String(ex.targetAudience || `Ages ${ageBand[0]}-${ageBand[1]}`),
3053
+ hardwareRequirements: Array.isArray(ex.hardwareRequirements) ? ex.hardwareRequirements.map(String) : void 0,
3054
+ softwareRequirements: Array.isArray(ex.softwareRequirements) ? ex.softwareRequirements.map(String) : void 0,
3055
+ sourceUrl: scrapedSnippets[0]?.url
3056
+ }));
3057
+ }
3058
+ if (Array.isArray(parsed.technicalBottlenecks)) factsheet.technicalBottlenecks = parsed.technicalBottlenecks.map(String);
3059
+ }
3060
+ } catch (err) {
3061
+ console.warn("[TechnicalGroundingEngine] LLM synthesis fallback to baseline:", err?.message || err);
3062
+ }
3063
+ }
3064
+ factsheet.markdownReport = this.renderMarkdownReport(factsheet);
3065
+ return factsheet;
3066
+ }
3067
+ renderMarkdownReport(fs) {
3068
+ const lines = [
3069
+ `# \u{1F6E0}\uFE0F Technical Grounding & Empirical Factsheet: ${fs.topic}`,
3070
+ `> **Domain:** \`${fs.domain.toUpperCase()}\` | **Feasibility:** \`${fs.ageFeasibility.cognitiveReadinessVerdict.toUpperCase()}\``,
3071
+ `
3072
+ ## 1. Compatibility & Tooling Verification`,
3073
+ `- **Hardware:** ${fs.compatibilityMatrix.hardwarePlatform || "N/A"}`,
3074
+ `- **Software / SDK:** ${fs.compatibilityMatrix.softwareEnv || "N/A"}`,
3075
+ `- **Verdict:** ${fs.compatibilityMatrix.verifiedCompatible ? "\u2705 Verified Compatible" : "\u26A0\uFE0F Compatibility Warning"}`,
3076
+ ...fs.compatibilityMatrix.notes.map((n) => ` - ${n}`),
3077
+ `
3078
+ ## 2. Age Feasibility & Learner Barriers (Ages ${fs.ageFeasibility.recommendedMinAge}\u2013${fs.ageFeasibility.recommendedMaxAge})`,
3079
+ ...fs.ageFeasibility.potentialBarriers.map((b) => `- \u26A0\uFE0F ${b}`),
3080
+ `
3081
+ ## 3. Real-World Exemplar Projects`,
3082
+ ...fs.exemplarProjects.map((ex, idx) => `### Exemplar ${idx + 1}: ${ex.title}
3083
+ - **Summary:** ${ex.description}
3084
+ - **Audience:** ${ex.targetAudience}${ex.sourceUrl ? `
3085
+ - **Reference:** [Link](${ex.sourceUrl})` : ""}`),
3086
+ `
3087
+ ## 4. Technical Bottlenecks & Pitfalls to Avoid`,
3088
+ ...fs.technicalBottlenecks.map((bn) => `- \u{1F6D1} ${bn}`),
3089
+ `
3090
+ ## 5. Grounding Citations`,
3091
+ ...fs.groundingSources.map((s, idx) => `${idx + 1}. [${s.title}](${s.url})`)
3092
+ ];
3093
+ return lines.join("\n");
3094
+ }
3095
+ };
3096
+
2622
3097
  // src/services/researchKitClient.ts
2623
3098
  var KnowledgeDiscoveryService = class {
2624
3099
  constructor(config) {
@@ -2818,6 +3293,29 @@ var PedagogicalSynthesisService = class {
2818
3293
  });
2819
3294
  }
2820
3295
  };
3296
+ var TechnicalGroundingService = class {
3297
+ constructor(config) {
3298
+ this.config = config;
3299
+ const searchEngine = new MultiSourceSearchEngine({
3300
+ apiKeys: config.apiKeys,
3301
+ allowEnvFallback: config.allowEnvFallback,
3302
+ customAdapter: config.customSearchAdapter
3303
+ });
3304
+ const scraper = new WebScraper({
3305
+ crawl4aiHost: config.crawl4aiHost,
3306
+ jinaKey: config.apiKeys?.jina,
3307
+ allowEnvFallback: config.allowEnvFallback,
3308
+ customAdapter: config.customCrawlerAdapter
3309
+ });
3310
+ this.engine = new TechnicalGroundingEngine(searchEngine, scraper);
3311
+ }
3312
+ engine;
3313
+ async buildFactsheet(topic, options) {
3314
+ const ctx = options?.context ?? this.config.defaultCourseContext;
3315
+ const domain = options?.domain ?? classifyTechnicalDomain(topic, void 0, ctx).domain;
3316
+ return this.engine.buildFactsheet(topic, domain, ctx, this.config.llm);
3317
+ }
3318
+ };
2821
3319
  var ResearchKitClient = class {
2822
3320
  constructor(config = {}) {
2823
3321
  this.config = config;
@@ -2826,6 +3324,7 @@ var ResearchKitClient = class {
2826
3324
  this.academic = new AcademicStandardsService(config);
2827
3325
  this.verification = new EvidenceVerificationService(config);
2828
3326
  this.orchestrator = new PedagogicalSynthesisService(config);
3327
+ this.grounding = new TechnicalGroundingService(config);
2829
3328
  }
2830
3329
  /** Service 1: Multi-Engine Web Search, Scraper & YouTube Transcript Ingestion */
2831
3330
  discovery;
@@ -2837,6 +3336,8 @@ var ResearchKitClient = class {
2837
3336
  verification;
2838
3337
  /** Service 5: Campaign Planning, Semantic Synthesis & Canonical Reference Pack Orchestration */
2839
3338
  orchestrator;
3339
+ /** Service 6: Technical Grounding, Hardware/Software Compatibility & Empirical Exemplars */
3340
+ grounding;
2840
3341
  };
2841
3342
 
2842
3343
  exports.AcademicPaperSchema = AcademicPaperSchema;
@@ -2850,6 +3351,8 @@ exports.CatalogBuilder = CatalogBuilder;
2850
3351
  exports.CitationManager = CitationManager;
2851
3352
  exports.ClaimVerifier = ClaimVerifier;
2852
3353
  exports.DEFAULT_RESEARCH_CONFIG = DEFAULT_RESEARCH_CONFIG;
3354
+ exports.ECOMMERCE_AND_COMMERCIAL_PATTERNS = ECOMMERCE_AND_COMMERCIAL_PATTERNS;
3355
+ exports.ECOMMERCE_DOMAINS = ECOMMERCE_DOMAINS;
2853
3356
  exports.EvidenceScorer = EvidenceScorer;
2854
3357
  exports.EvidenceVerificationService = EvidenceVerificationService;
2855
3358
  exports.HarvestPipeline = HarvestPipeline;
@@ -2863,19 +3366,25 @@ exports.ProvenanceTracker = ProvenanceTracker;
2863
3366
  exports.ReferencePackBuilder = ReferencePackBuilder;
2864
3367
  exports.ResearchConfigSchema = ResearchConfigSchema;
2865
3368
  exports.ResearchKitClient = ResearchKitClient;
3369
+ exports.TechnicalGroundingEngine = TechnicalGroundingEngine;
3370
+ exports.TechnicalGroundingService = TechnicalGroundingService;
2866
3371
  exports.TerminologyGraphService = TerminologyGraphService;
2867
3372
  exports.WebScraper = WebScraper;
2868
3373
  exports.YouTubeIngestionService = YouTubeIngestionService;
2869
3374
  exports.classifyTechnicalDomain = classifyTechnicalDomain;
3375
+ exports.evaluateTechnicalDensity = evaluateTechnicalDensity;
2870
3376
  exports.extractSubstantiveExcerpts = extractSubstantiveExcerpts;
2871
3377
  exports.extractTopSentences = extractTopSentences;
2872
3378
  exports.extractYouTubeVideoId = extractYouTubeVideoId;
2873
3379
  exports.formatTimestamp = formatTimestamp;
2874
3380
  exports.inferPrimaryCodeLanguage = inferPrimaryCodeLanguage;
3381
+ exports.isCommercialOrNoise = isCommercialOrNoise;
2875
3382
  exports.isYouTubeUrl = isYouTubeUrl;
3383
+ exports.kahnTopologicalSort = kahnTopologicalSort;
2876
3384
  exports.mapTopicToCS2023 = mapTopicToCS2023;
2877
3385
  exports.normalizeUrlForDedup = normalizeUrlForDedup;
2878
3386
  exports.reconstructOpenAlexAbstract = reconstructOpenAlexAbstract;
2879
3387
  exports.stitchCaptionSegments = stitchCaptionSegments;
3388
+ exports.transitiveReduction = transitiveReduction;
2880
3389
  //# sourceMappingURL=index.cjs.map
2881
3390
  //# sourceMappingURL=index.cjs.map