@thanh01.pmt/research-kit 1.2.4 → 1.3.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 (69) hide show
  1. package/dist/academic/index.cjs +122 -0
  2. package/dist/academic/index.cjs.map +1 -1
  3. package/dist/academic/index.d.cts +27 -4
  4. package/dist/academic/index.d.ts +27 -4
  5. package/dist/academic/index.js +2 -1
  6. package/dist/agent/index.cjs +3441 -0
  7. package/dist/agent/index.cjs.map +1 -0
  8. package/dist/agent/index.d.cts +10 -0
  9. package/dist/agent/index.d.ts +10 -0
  10. package/dist/agent/index.js +10 -0
  11. package/dist/agent/index.js.map +1 -0
  12. package/dist/{catalogBuilder-B4eiLS_S.d.cts → catalogBuilder-BBCa9jqI.d.cts} +2 -2
  13. package/dist/{catalogBuilder-BNB_gaWP.d.ts → catalogBuilder-D-UiM37y.d.ts} +2 -2
  14. package/dist/chunk-2GBXVPOQ.js +3 -0
  15. package/dist/{chunk-J3VCGH7Z.js.map → chunk-2GBXVPOQ.js.map} +1 -1
  16. package/dist/chunk-2RMBLKP5.js +581 -0
  17. package/dist/chunk-2RMBLKP5.js.map +1 -0
  18. package/dist/{chunk-2XIEWCUE.js → chunk-32B5PVTQ.js} +2 -2
  19. package/dist/{chunk-2XIEWCUE.js.map → chunk-32B5PVTQ.js.map} +1 -1
  20. package/dist/chunk-LDCZ33AC.js +3 -0
  21. package/dist/chunk-LDCZ33AC.js.map +1 -0
  22. package/dist/chunk-NSY6KU4G.js +125 -0
  23. package/dist/chunk-NSY6KU4G.js.map +1 -0
  24. package/dist/{chunk-SAHBBO3U.js → chunk-RYLZYZRF.js} +4 -580
  25. package/dist/chunk-RYLZYZRF.js.map +1 -0
  26. package/dist/{chunk-GK5KI5PB.js → chunk-S3JUCDKD.js} +62 -43
  27. package/dist/chunk-S3JUCDKD.js.map +1 -0
  28. package/dist/chunk-TYQEC24G.js +3 -0
  29. package/dist/chunk-TYQEC24G.js.map +1 -0
  30. package/dist/chunk-WWQ45RQK.js +1114 -0
  31. package/dist/chunk-WWQ45RQK.js.map +1 -0
  32. package/dist/{chunk-YICMTZS5.js → chunk-ZNGU4ZYX.js} +171 -3
  33. package/dist/chunk-ZNGU4ZYX.js.map +1 -0
  34. package/dist/config/index.d.cts +1 -1
  35. package/dist/config/index.d.ts +1 -1
  36. package/dist/evidence/index.d.cts +2 -2
  37. package/dist/evidence/index.d.ts +2 -2
  38. package/dist/evidence/index.js +2 -1
  39. package/dist/harvester/index.cjs +168 -1
  40. package/dist/harvester/index.cjs.map +1 -1
  41. package/dist/harvester/index.d.cts +5 -161
  42. package/dist/harvester/index.d.ts +5 -161
  43. package/dist/harvester/index.js +4 -2
  44. package/dist/index-CN8gei7k.d.ts +518 -0
  45. package/dist/{index-9rDiFuR4.d.ts → index-CxoD81QN.d.cts} +1 -1
  46. package/dist/{index-9rDiFuR4.d.cts → index-CxoD81QN.d.ts} +1 -1
  47. package/dist/index-onQDKDNo.d.cts +518 -0
  48. package/dist/index.cjs +1463 -39
  49. package/dist/index.cjs.map +1 -1
  50. package/dist/index.d.cts +11 -174
  51. package/dist/index.d.ts +11 -174
  52. package/dist/index.js +25 -10
  53. package/dist/index.js.map +1 -1
  54. package/dist/{literatureReview-DOzgm9Q2.d.ts → literatureReview-Bn2iEGRO.d.ts} +1 -1
  55. package/dist/{literatureReview-BwidpYJo.d.cts → literatureReview-Bvlqk4DB.d.cts} +1 -1
  56. package/dist/pipeline/index.cjs +59 -41
  57. package/dist/pipeline/index.cjs.map +1 -1
  58. package/dist/pipeline/index.d.cts +5 -4
  59. package/dist/pipeline/index.d.ts +5 -4
  60. package/dist/pipeline/index.js +3 -2
  61. package/dist/socialPulseHarvester-CN4MwrpY.d.cts +204 -0
  62. package/dist/socialPulseHarvester-IbdT3zD1.d.ts +204 -0
  63. package/dist/{webScraper-CAQjE46m.d.cts → webScraper-BVvNW4yj.d.cts} +1 -1
  64. package/dist/{webScraper-CXIpvyA6.d.ts → webScraper-C9pB5Rgd.d.ts} +1 -1
  65. package/package.json +6 -1
  66. package/dist/chunk-GK5KI5PB.js.map +0 -1
  67. package/dist/chunk-J3VCGH7Z.js +0 -3
  68. package/dist/chunk-SAHBBO3U.js.map +0 -1
  69. package/dist/chunk-YICMTZS5.js.map +0 -1
package/dist/index.cjs CHANGED
@@ -258,6 +258,126 @@ var AcademicSearchEngine = class {
258
258
  }
259
259
  };
260
260
 
261
+ // src/academic/openAlexClient.ts
262
+ function cleanCrossrefAbstract(rawAbstract) {
263
+ if (!rawAbstract || typeof rawAbstract !== "string") return void 0;
264
+ const cleaned = rawAbstract.replace(/<\/?jats:[^>]+>/gi, " ").replace(/<\/?[^>]+>/g, " ").replace(/\s+/g, " ").trim();
265
+ return cleaned.length > 0 ? cleaned : void 0;
266
+ }
267
+ var OpenAlexClient = class {
268
+ mailto;
269
+ constructor(options = {}) {
270
+ this.mailto = options.mailto || "team@orchable.app";
271
+ }
272
+ async searchWorks(query, options = {}) {
273
+ const limit = options.limit ?? 5;
274
+ const papers = [];
275
+ const seenTitles = /* @__PURE__ */ new Set();
276
+ const pushUnique = (paper) => {
277
+ const norm = paper.title.toLowerCase().replace(/[^a-z0-9\u00C0-\u1EF9]+/g, "");
278
+ if (!norm || seenTitles.has(norm)) return;
279
+ seenTitles.add(norm);
280
+ papers.push(paper);
281
+ };
282
+ try {
283
+ const filters = [];
284
+ if (options.yearRange) {
285
+ const match = options.yearRange.match(/^(\d{4})-(\d{4})$/);
286
+ if (match) {
287
+ filters.push(`publication_year:${match[1]}-${match[2]}`);
288
+ } else if (/^\d{4}$/.test(options.yearRange)) {
289
+ filters.push(`publication_year:${options.yearRange}`);
290
+ }
291
+ }
292
+ if (options.openAccessOnly) {
293
+ filters.push("is_oa:true");
294
+ }
295
+ const params = new URLSearchParams({
296
+ search: query,
297
+ "per-page": String(limit)
298
+ });
299
+ if (filters.length > 0) {
300
+ params.set("filter", filters.join(","));
301
+ }
302
+ const res = await fetch(`https://api.openalex.org/works?${params.toString()}`, {
303
+ headers: {
304
+ "User-Agent": `OrchableResearchKit/1.3 (mailto:${this.mailto})`
305
+ },
306
+ signal: AbortSignal.timeout(7e3)
307
+ });
308
+ if (res.ok) {
309
+ const data = await res.json();
310
+ if (Array.isArray(data?.results)) {
311
+ for (const item of data.results) {
312
+ const abstractText = reconstructOpenAlexAbstract(item.abstract_inverted_index);
313
+ const concepts = Array.isArray(item.concepts) ? item.concepts.slice(0, 4).map((c) => c.display_name).filter(Boolean) : ["Computer Science"];
314
+ const cleanDoi = item.doi ? String(item.doi).replace(/^https?:\/\/doi\.org\//i, "") : void 0;
315
+ pushUnique({
316
+ id: item.id || `oa-${Math.random().toString(36).slice(2, 8)}`,
317
+ title: item.title || item.display_name || "Untitled",
318
+ abstract: abstractText,
319
+ authors: Array.isArray(item.authorships) ? item.authorships.map((a) => a.author?.display_name).filter(Boolean) : [],
320
+ year: item.publication_year,
321
+ citationCount: item.cited_by_count || 0,
322
+ venue: item.primary_location?.source?.display_name || void 0,
323
+ doi: cleanDoi,
324
+ url: item.doi || item.primary_location?.landing_page_url || item.id,
325
+ pdfUrl: item.open_access?.oa_url || item.primary_location?.pdf_url || void 0,
326
+ fieldsOfStudy: concepts.length > 0 ? concepts : ["Computer Science"]
327
+ });
328
+ }
329
+ }
330
+ }
331
+ } catch (e) {
332
+ console.warn("[OpenAlexClient] OpenAlex request failed:", e?.message || e);
333
+ }
334
+ if (papers.length < limit && options.includeCrossrefFallback !== false) {
335
+ try {
336
+ const remaining = limit - papers.length;
337
+ const params = new URLSearchParams({
338
+ query,
339
+ rows: String(remaining),
340
+ mailto: this.mailto
341
+ });
342
+ const res = await fetch(`https://api.crossref.org/works?${params.toString()}`, {
343
+ headers: {
344
+ "User-Agent": `OrchableResearchKit/1.3 (mailto:${this.mailto})`
345
+ },
346
+ signal: AbortSignal.timeout(7e3)
347
+ });
348
+ if (res.ok) {
349
+ const data = await res.json();
350
+ const items = data?.message?.items;
351
+ if (Array.isArray(items)) {
352
+ for (const item of items) {
353
+ const title = Array.isArray(item.title) ? item.title[0] : item.title;
354
+ if (!title) continue;
355
+ const year = item.published?.["date-parts"]?.[0]?.[0] || item["published-print"]?.["date-parts"]?.[0]?.[0] || item["published-online"]?.["date-parts"]?.[0]?.[0];
356
+ const authors = Array.isArray(item.author) ? item.author.map((a) => [a.given, a.family].filter(Boolean).join(" ").trim()).filter(Boolean) : [];
357
+ const doi = item.DOI ? String(item.DOI) : void 0;
358
+ pushUnique({
359
+ id: doi ? `crossref-${doi}` : `cr-${Math.random().toString(36).slice(2, 8)}`,
360
+ title: String(title),
361
+ abstract: cleanCrossrefAbstract(item.abstract),
362
+ authors,
363
+ year: typeof year === "number" ? year : void 0,
364
+ citationCount: Number(item["is-referenced-by-count"]) || 0,
365
+ venue: Array.isArray(item["container-title"]) ? item["container-title"][0] : void 0,
366
+ doi,
367
+ url: item.URL || (doi ? `https://doi.org/${doi}` : void 0),
368
+ fieldsOfStudy: Array.isArray(item.subject) && item.subject.length > 0 ? item.subject.slice(0, 3) : ["Academic"]
369
+ });
370
+ }
371
+ }
372
+ }
373
+ } catch (e) {
374
+ console.warn("[OpenAlexClient] Crossref fallback failed:", e?.message || e);
375
+ }
376
+ }
377
+ return papers.slice(0, limit);
378
+ }
379
+ };
380
+
261
381
  // src/academic/cs2023Taxonomy.ts
262
382
  var CSTA_K12_STRANDS = {
263
383
  CS: {
@@ -765,7 +885,7 @@ var MultiSourceSearchEngine = class {
765
885
  if (adapter && (!preferred || preferred === "custom")) {
766
886
  try {
767
887
  const customResults = await adapter.search(query, { limit, domainFilter: options.domainFilter });
768
- if (Array.isArray(customResults) && customResults.length > 0) {
888
+ if (Array.isArray(customResults)) {
769
889
  return customResults.map((r) => ({
770
890
  title: r.title,
771
891
  url: r.url,
@@ -2698,6 +2818,172 @@ var StemResourceResearcher = class {
2698
2818
  }
2699
2819
  };
2700
2820
 
2821
+ // src/harvester/socialPulseHarvester.ts
2822
+ var SocialPulseHarvester = class {
2823
+ constructor(searchEngine = new MultiSourceSearchEngine()) {
2824
+ this.searchEngine = searchEngine;
2825
+ }
2826
+ async harvest(topic, options = {}) {
2827
+ const recencyDays = Math.max(1, options.recencyDays ?? 30);
2828
+ const limitPerPlatform = options.limitPerPlatform ?? 4;
2829
+ const cutoffMs = Date.now() - recencyDays * 24 * 60 * 60 * 1e3;
2830
+ const cutoffUnixSec = Math.floor(cutoffMs / 1e3);
2831
+ const cutoffIsoDate = new Date(cutoffMs).toISOString().slice(0, 10);
2832
+ const items = [];
2833
+ const seenUrls = /* @__PURE__ */ new Set();
2834
+ const pushUnique = (item) => {
2835
+ const normUrl = item.url.trim().replace(/\/$/, "");
2836
+ if (!normUrl || seenUrls.has(normUrl)) return;
2837
+ seenUrls.add(normUrl);
2838
+ items.push(item);
2839
+ };
2840
+ const tasks = [];
2841
+ if (options.includeHackerNews !== false) {
2842
+ tasks.push(
2843
+ (async () => {
2844
+ try {
2845
+ const params = new URLSearchParams({
2846
+ query: topic,
2847
+ tags: "story",
2848
+ numericFilters: `created_at_i>${cutoffUnixSec}`,
2849
+ hitsPerPage: String(limitPerPlatform)
2850
+ });
2851
+ const res = await fetch(`https://hn.algolia.com/api/v1/search?${params.toString()}`, {
2852
+ headers: { "User-Agent": "OrchableResearchKit/1.3" },
2853
+ signal: AbortSignal.timeout(6500)
2854
+ });
2855
+ if (res.ok) {
2856
+ const data = await res.json();
2857
+ if (Array.isArray(data?.hits)) {
2858
+ for (const hit of data.hits) {
2859
+ const points = Number(hit.points) || 0;
2860
+ const comments = Number(hit.num_comments) || 0;
2861
+ const hnUrl = `https://news.ycombinator.com/item?id=${hit.objectID}`;
2862
+ const targetUrl = hit.url || hnUrl;
2863
+ const score = Math.min(10, Math.max(4, Math.round(4 + Math.log10(points + comments + 1) * 2)));
2864
+ pushUnique({
2865
+ id: `hn-${hit.objectID}`,
2866
+ platform: "hackernews",
2867
+ title: String(hit.title || "HackerNews Discussion"),
2868
+ url: targetUrl,
2869
+ snippet: `${hit.title} (${points} pts, ${comments} comments on HN: ${hnUrl})`,
2870
+ author: hit.author,
2871
+ createdAt: hit.created_at,
2872
+ engagementScore: score,
2873
+ rawMetrics: { points, comments }
2874
+ });
2875
+ }
2876
+ }
2877
+ }
2878
+ } catch (e) {
2879
+ console.warn("[SocialPulseHarvester] HackerNews query failed:", e?.message || e);
2880
+ }
2881
+ })()
2882
+ );
2883
+ }
2884
+ if (options.includeGitHub !== false) {
2885
+ tasks.push(
2886
+ (async () => {
2887
+ try {
2888
+ const q = `${topic} pushed:>=${cutoffIsoDate}`;
2889
+ const params = new URLSearchParams({
2890
+ q,
2891
+ sort: "stars",
2892
+ order: "desc",
2893
+ per_page: String(limitPerPlatform)
2894
+ });
2895
+ const res = await fetch(`https://api.github.com/search/repositories?${params.toString()}`, {
2896
+ headers: {
2897
+ Accept: "application/vnd.github+json",
2898
+ "User-Agent": "OrchableResearchKit/1.3"
2899
+ },
2900
+ signal: AbortSignal.timeout(6500)
2901
+ });
2902
+ if (res.ok) {
2903
+ const data = await res.json();
2904
+ if (Array.isArray(data?.items)) {
2905
+ for (const repo of data.items) {
2906
+ const stars = Number(repo.stargazers_count) || 0;
2907
+ const score = Math.min(10, Math.max(5, Math.round(4 + Math.log10(stars + 1) * 1.8)));
2908
+ pushUnique({
2909
+ id: `gh-${repo.id || repo.full_name}`,
2910
+ platform: "github",
2911
+ title: `${repo.full_name}: ${repo.description || "GitHub Repository"}`.slice(0, 180),
2912
+ url: repo.html_url,
2913
+ snippet: `${repo.description || ""} [Stars: ${stars}, Language: ${repo.language || "N/A"}, Updated: ${String(repo.pushed_at || "").slice(0, 10)}]`.trim(),
2914
+ author: repo.owner?.login,
2915
+ createdAt: repo.pushed_at || repo.created_at,
2916
+ engagementScore: score,
2917
+ rawMetrics: { stars }
2918
+ });
2919
+ }
2920
+ }
2921
+ }
2922
+ } catch (e) {
2923
+ console.warn("[SocialPulseHarvester] GitHub search failed:", e?.message || e);
2924
+ }
2925
+ })()
2926
+ );
2927
+ }
2928
+ if (options.includeRedditWeb !== false) {
2929
+ tasks.push(
2930
+ (async () => {
2931
+ try {
2932
+ const timeRange = recencyDays <= 7 ? "week" : recencyDays <= 35 ? "month" : "year";
2933
+ const hits = await this.searchEngine.search(`${topic} reddit OR community discussion pitfalls`, {
2934
+ limit: limitPerPlatform,
2935
+ timeRange
2936
+ });
2937
+ for (const [idx, h] of hits.entries()) {
2938
+ const isReddit = /reddit\.com/i.test(h.url);
2939
+ pushUnique({
2940
+ id: `pulse-${idx + 1}`,
2941
+ platform: isReddit ? "reddit" : "web",
2942
+ title: h.title,
2943
+ url: h.url,
2944
+ snippet: h.content.slice(0, 350),
2945
+ engagementScore: isReddit ? 7 : 6
2946
+ });
2947
+ }
2948
+ } catch (e) {
2949
+ console.warn("[SocialPulseHarvester] Recency web search failed:", e?.message || e);
2950
+ }
2951
+ })()
2952
+ );
2953
+ }
2954
+ await Promise.allSettled(tasks);
2955
+ items.sort((a, b) => b.engagementScore - a.engagementScore);
2956
+ const trendingReposAndTools = items.filter((i) => i.platform === "github").map((i) => `${i.title} (${i.url})`);
2957
+ const communityHighlights = items.slice(0, 6).map((i) => `[${i.platform.toUpperCase()}] ${i.title}: ${i.snippet}`);
2958
+ const mdLines = [
2959
+ `# \u{1F4E1} Social & Developer Pulse Report (Last ${recencyDays} Days): ${topic}`,
2960
+ `> **Harvested At:** \`${(/* @__PURE__ */ new Date()).toISOString()}\` | **Window:** \`Last ${recencyDays} days\` | **Total Signals:** \`${items.length}\``,
2961
+ `
2962
+ ## 1. Community Signals & Discussions`,
2963
+ ...items.length > 0 ? items.map(
2964
+ (item, idx) => `${idx + 1}. **[${item.platform.toUpperCase()}] [${item.title}](${item.url})** (Score: \`${item.engagementScore}/10\`)
2965
+ - ${item.snippet}`
2966
+ ) : ["- No recent social pulse items found within the specified window."]
2967
+ ];
2968
+ if (trendingReposAndTools.length > 0) {
2969
+ mdLines.push(
2970
+ `
2971
+ ## 2. Active Repositories & Tooling`,
2972
+ ...trendingReposAndTools.map((r) => `- ${r}`)
2973
+ );
2974
+ }
2975
+ return {
2976
+ topic,
2977
+ recencyDays,
2978
+ harvestedAt: (/* @__PURE__ */ new Date()).toISOString(),
2979
+ items,
2980
+ trendingReposAndTools,
2981
+ communityHighlights,
2982
+ markdownReport: mdLines.join("\n")
2983
+ };
2984
+ }
2985
+ };
2986
+
2701
2987
  // src/evidence/evidenceScorer.ts
2702
2988
  function tokenizeBilingualKeywords(text) {
2703
2989
  return text.normalize("NFC").toLowerCase().replace(/[.,;:!?()[\]{}"“”‘’/\\|`*_~#-]+/g, " ").split(/\s+/).filter((w) => w.length >= 2 && !/^(and|the|for|with|from|into|của|trong|được|những|các|cho|với|khi|và|hoặc|để|từ|đến|về)$/.test(w));
@@ -3683,33 +3969,17 @@ var TechnicalGroundingEngine = class {
3683
3969
  preservedKeyExcerpts.push(...s.keyExcerpts);
3684
3970
  }
3685
3971
  }
3686
- const defaultExemplars = [
3687
- {
3688
- title: scrapedSnippets[0]?.title || `${topic} Hands-on Foundation Project`,
3689
- description: scrapedSnippets[0]?.excerpt ? scrapedSnippets[0].excerpt.slice(0, 220) : `Verified practical implementation integrating ${hardware || "core principles"} and ${software || "standard development tools"}.`,
3690
- targetAudience: `Students aged ${ageBand[0]}-${ageBand[1]}`,
3691
- sourceUrl: scrapedSnippets[0]?.url,
3692
- hardwareRequirements: hardware ? [hardware] : void 0,
3693
- softwareRequirements: software ? [software] : void 0
3694
- }
3695
- ];
3696
- const defaultBottlenecks = domain === "hardware" || Boolean(hardware) ? [
3697
- "Power supply decoupling and current surge when powering sensors or actuators.",
3698
- "Logic level shifting and hardware pin mapping conflicts."
3699
- ] : domain === "academic" ? [
3700
- "Cognitive load pacing and abstract concept grounding with physical analogies."
3701
- ] : [
3702
- "SDK/runtime version compatibility and local environment dependencies.",
3703
- "Syntax confusion between asynchronous event handling and blocking calls."
3704
- ];
3972
+ const defaultExemplars = [];
3973
+ const defaultBottlenecks = [];
3705
3974
  let factsheet = {
3706
3975
  topic,
3707
3976
  domain,
3977
+ evidenceBacked: false,
3708
3978
  compatibilityMatrix: {
3709
3979
  hardwarePlatform: hardware || void 0,
3710
3980
  softwareEnv: software || void 0,
3711
3981
  verifiedCompatible: true,
3712
- notes: hardware || software ? [`Targeting ${hardware || "General Platform"} with ${software || "Standard SDK"}.`] : [`Baseline technical verification for ${topic}.`]
3982
+ notes: []
3713
3983
  },
3714
3984
  ageFeasibility: {
3715
3985
  recommendedMinAge: ageBand[0],
@@ -3719,7 +3989,7 @@ var TechnicalGroundingEngine = class {
3719
3989
  },
3720
3990
  exemplarProjects: defaultExemplars,
3721
3991
  technicalBottlenecks: defaultBottlenecks,
3722
- groundingSources: scrapedSnippets.map((s) => ({ title: s.title, url: s.url })),
3992
+ groundingSources: scrapedSnippets.filter((s) => Boolean(s.url)).map((s) => ({ title: s.title, url: s.url })),
3723
3993
  markdownReport: "",
3724
3994
  codeSnippets: preservedCodeSnippets.slice(0, 4),
3725
3995
  pinoutTables: preservedTables.slice(0, 4),
@@ -3727,9 +3997,10 @@ var TechnicalGroundingEngine = class {
3727
3997
  };
3728
3998
  if (llm && scrapedSnippets.length > 0) {
3729
3999
  try {
4000
+ const roleByDomain = domain === "hardware" ? "Hardware & Embedded Systems Curriculum Specialist" : domain === "software" ? "Software & Technology Curriculum Specialist" : "Applied Subject Matter & Curriculum Specialist";
3730
4001
  const prompt = [
3731
- `You are a Lead STEM Curriculum Engineer. Analyze these research excerpts for topic: "${topic}".`,
3732
- `Hardware: ${hardware || "N/A"}, Software/Env: ${software || "N/A"}, Student Age Band: ${ageBand[0]}-${ageBand[1]} years old.`,
4002
+ `You are a ${roleByDomain}. Analyze these verified research excerpts for topic: "${topic}".`,
4003
+ `Domain: ${domain}, Hardware: ${hardware || "N/A"}, Software/Env: ${software || "N/A"}, Student Age Band: ${ageBand[0]}-${ageBand[1]} years old.`,
3733
4004
  `
3734
4005
  Harvested Sources:
3735
4006
  ${scrapedSnippets.map((s, i) => {
@@ -3746,7 +4017,7 @@ ${c.code}
3746
4017
  return parts.join("\n");
3747
4018
  }).join("\n\n")}`,
3748
4019
  `
3749
- Synthesize a strictly valid JSON object with:`,
4020
+ Synthesize a strictly valid JSON object based ONLY on the evidence above. If no evidence exists for a field, leave it as an empty array [] without inventing facts:`,
3750
4021
  `{`,
3751
4022
  ` "compatibilityVerdict": boolean,`,
3752
4023
  ` "compatibilityNotes": string[],`,
@@ -3781,10 +4052,28 @@ Synthesize a strictly valid JSON object with:`,
3781
4052
  }));
3782
4053
  }
3783
4054
  if (Array.isArray(parsed.technicalBottlenecks)) factsheet.technicalBottlenecks = parsed.technicalBottlenecks.map(String);
4055
+ if (factsheet.exemplarProjects.length > 0 || factsheet.technicalBottlenecks.length > 0) {
4056
+ factsheet.evidenceBacked = true;
4057
+ }
3784
4058
  }
3785
4059
  } catch (err) {
3786
4060
  console.warn("[TechnicalGroundingEngine] LLM synthesis error:", err?.message || err);
3787
4061
  }
4062
+ } else if (scrapedSnippets.length > 0 && scrapedSnippets[0]?.excerpt?.trim()) {
4063
+ const first = scrapedSnippets[0];
4064
+ if (first.title || first.excerpt) {
4065
+ factsheet.exemplarProjects = [
4066
+ {
4067
+ title: first.title || `${topic} Hands-on Foundation Project`,
4068
+ description: first.excerpt.slice(0, 220),
4069
+ targetAudience: `Students aged ${ageBand[0]}-${ageBand[1]}`,
4070
+ sourceUrl: first.url,
4071
+ hardwareRequirements: hardware ? [hardware] : void 0,
4072
+ softwareRequirements: software ? [software] : void 0
4073
+ }
4074
+ ];
4075
+ factsheet.evidenceBacked = true;
4076
+ }
3788
4077
  }
3789
4078
  factsheet.markdownReport = this.renderMarkdownReport(factsheet);
3790
4079
  return factsheet;
@@ -3798,23 +4087,41 @@ Synthesize a strictly valid JSON object with:`,
3798
4087
  `- **Hardware:** ${fs.compatibilityMatrix.hardwarePlatform || "N/A"}`,
3799
4088
  `- **Software / SDK:** ${fs.compatibilityMatrix.softwareEnv || "N/A"}`,
3800
4089
  `- **Verdict:** ${fs.compatibilityMatrix.verifiedCompatible ? "\u2705 Verified Compatible" : "\u26A0\uFE0F Compatibility Warning"}`,
3801
- ...fs.compatibilityMatrix.notes.map((n) => ` - ${n}`),
3802
- `
4090
+ ...fs.compatibilityMatrix.notes.map((n) => ` - ${n}`)
4091
+ ];
4092
+ if (fs.ageFeasibility.potentialBarriers.length > 0) {
4093
+ lines.push(
4094
+ `
3803
4095
  ## 2. Age Feasibility & Learner Barriers (Ages ${fs.ageFeasibility.recommendedMinAge}\u2013${fs.ageFeasibility.recommendedMaxAge})`,
3804
- ...fs.ageFeasibility.potentialBarriers.map((b) => `- \u26A0\uFE0F ${b}`),
3805
- `
4096
+ ...fs.ageFeasibility.potentialBarriers.map((b) => `- \u26A0\uFE0F ${b}`)
4097
+ );
4098
+ }
4099
+ if (fs.exemplarProjects.length > 0) {
4100
+ lines.push(
4101
+ `
3806
4102
  ## 3. Real-World Exemplar Projects`,
3807
- ...fs.exemplarProjects.map((ex, idx) => `### Exemplar ${idx + 1}: ${ex.title}
4103
+ ...fs.exemplarProjects.map(
4104
+ (ex, idx) => `### Exemplar ${idx + 1}: ${ex.title}
3808
4105
  - **Summary:** ${ex.description}
3809
4106
  - **Audience:** ${ex.targetAudience}${ex.sourceUrl ? `
3810
- - **Reference:** [Link](${ex.sourceUrl})` : ""}`),
3811
- `
4107
+ - **Reference:** [Link](${ex.sourceUrl})` : ""}`
4108
+ )
4109
+ );
4110
+ }
4111
+ if (fs.technicalBottlenecks.length > 0) {
4112
+ lines.push(
4113
+ `
3812
4114
  ## 4. Technical Bottlenecks & Pitfalls to Avoid`,
3813
- ...fs.technicalBottlenecks.map((bn) => `- \u{1F6D1} ${bn}`),
3814
- `
4115
+ ...fs.technicalBottlenecks.map((bn) => `- \u{1F6D1} ${bn}`)
4116
+ );
4117
+ }
4118
+ if (fs.groundingSources.length > 0) {
4119
+ lines.push(
4120
+ `
3815
4121
  ## 5. Grounding Citations`,
3816
- ...fs.groundingSources.map((s, idx) => `${idx + 1}. [${s.title}](${s.url})`)
3817
- ];
4122
+ ...fs.groundingSources.map((s, idx) => `${idx + 1}. [${s.title}](${s.url})`)
4123
+ );
4124
+ }
3818
4125
  if (fs.codeSnippets && fs.codeSnippets.length > 0) {
3819
4126
  lines.push(
3820
4127
  `
@@ -3825,15 +4132,1114 @@ ${c.code}
3825
4132
  );
3826
4133
  }
3827
4134
  if (fs.pinoutTables && fs.pinoutTables.length > 0) {
4135
+ lines.push(`
4136
+ ## 7. Pinout & Specification Tables`, ...fs.pinoutTables);
4137
+ }
4138
+ return lines.join("\n");
4139
+ }
4140
+ };
4141
+
4142
+ // src/agent/types.ts
4143
+ var RESEARCH_PROFILE_PRESETS = {
4144
+ fast_grounded: {
4145
+ maxRounds: 2,
4146
+ maxQueriesPerRound: 3,
4147
+ maxScrapePerRound: 3,
4148
+ timeoutMs: 35e3,
4149
+ enableWeb: true,
4150
+ enableAcademic: false,
4151
+ enableSocialPulse: false,
4152
+ enableStemOer: false
4153
+ },
4154
+ deep_autonomous: {
4155
+ maxRounds: 3,
4156
+ maxQueriesPerRound: 4,
4157
+ maxScrapePerRound: 4,
4158
+ timeoutMs: 12e4,
4159
+ enableWeb: true,
4160
+ enableAcademic: true,
4161
+ enableSocialPulse: true,
4162
+ enableStemOer: true
4163
+ },
4164
+ technical: {
4165
+ maxRounds: 2,
4166
+ maxQueriesPerRound: 3,
4167
+ maxScrapePerRound: 4,
4168
+ timeoutMs: 45e3,
4169
+ enableWeb: true,
4170
+ enableAcademic: false,
4171
+ enableSocialPulse: true,
4172
+ enableStemOer: false
4173
+ },
4174
+ academic: {
4175
+ maxRounds: 2,
4176
+ maxQueriesPerRound: 3,
4177
+ maxScrapePerRound: 2,
4178
+ timeoutMs: 45e3,
4179
+ enableWeb: true,
4180
+ enableAcademic: true,
4181
+ enableSocialPulse: false,
4182
+ enableStemOer: false
4183
+ },
4184
+ social_pulse: {
4185
+ maxRounds: 2,
4186
+ maxQueriesPerRound: 3,
4187
+ maxScrapePerRound: 2,
4188
+ timeoutMs: 35e3,
4189
+ enableWeb: true,
4190
+ enableAcademic: false,
4191
+ enableSocialPulse: true,
4192
+ enableStemOer: false
4193
+ },
4194
+ curriculum_oer: {
4195
+ maxRounds: 2,
4196
+ maxQueriesPerRound: 3,
4197
+ maxScrapePerRound: 3,
4198
+ timeoutMs: 45e3,
4199
+ enableWeb: true,
4200
+ enableAcademic: false,
4201
+ enableSocialPulse: false,
4202
+ enableStemOer: true
4203
+ },
4204
+ general: {
4205
+ maxRounds: 2,
4206
+ maxQueriesPerRound: 3,
4207
+ maxScrapePerRound: 3,
4208
+ timeoutMs: 45e3,
4209
+ enableWeb: true,
4210
+ enableAcademic: false,
4211
+ enableSocialPulse: false,
4212
+ enableStemOer: false
4213
+ }
4214
+ };
4215
+
4216
+ // src/agent/evidenceLedger.ts
4217
+ function normalizeUrlKey(rawUrl) {
4218
+ try {
4219
+ const u = new URL(rawUrl.trim());
4220
+ u.hash = "";
4221
+ for (const param of ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "ref"]) {
4222
+ u.searchParams.delete(param);
4223
+ }
4224
+ return u.toString().replace(/\/$/, "").toLowerCase();
4225
+ } catch {
4226
+ return rawUrl.trim().replace(/\/$/, "").toLowerCase();
4227
+ }
4228
+ }
4229
+ var EvidenceLedger = class {
4230
+ items = [];
4231
+ urlIndex = /* @__PURE__ */ new Map();
4232
+ idIndex = /* @__PURE__ */ new Map();
4233
+ allocateId() {
4234
+ const nextNum = this.items.length + 1;
4235
+ return `RES-${String(nextNum).padStart(2, "0")}`;
4236
+ }
4237
+ /**
4238
+ * Records or upgrades a ledger entry from a full `ScrapedDocument`.
4239
+ */
4240
+ addScrapedDocument(doc, relevanceScore, extraTakeaways = []) {
4241
+ const key = normalizeUrlKey(doc.url);
4242
+ const existing = this.urlIndex.get(key);
4243
+ const mergedExcerpts = Array.from(
4244
+ new Set([
4245
+ ...extraTakeaways,
4246
+ ...doc.keyExcerpts || [],
4247
+ doc.markdownContent.replace(/```[\s\S]*?```/g, " ").replace(/\s+/g, " ").trim().slice(0, 450)
4248
+ ].filter((e) => e && e.trim().length > 20))
4249
+ ).slice(0, 6);
4250
+ const sourceType = doc.fetchProvider === "youtube" ? "youtube" : "web";
4251
+ if (existing) {
4252
+ existing.title = doc.title || existing.title;
4253
+ existing.relevanceScore = Math.max(existing.relevanceScore, relevanceScore);
4254
+ existing.headings = doc.extractedHeadings?.slice(0, 8) || existing.headings;
4255
+ existing.keyExcerpts = mergedExcerpts.length > 0 ? mergedExcerpts : existing.keyExcerpts;
4256
+ existing.codeBlocks = (doc.extractedCodeBlocks || []).slice(0, 4);
4257
+ existing.tables = (doc.extractedTables || []).slice(0, 4);
4258
+ existing.rawByteSize = Math.max(existing.rawByteSize, doc.byteSize || 0);
4259
+ return this.toCompactReceipt(existing);
4260
+ }
4261
+ const item = {
4262
+ id: this.allocateId(),
4263
+ sourceType,
4264
+ title: doc.title || "Untitled Document",
4265
+ url: doc.url,
4266
+ relevanceScore: Math.max(1, Math.min(10, Math.round(relevanceScore))),
4267
+ headings: (doc.extractedHeadings || []).slice(0, 8),
4268
+ keyExcerpts: mergedExcerpts,
4269
+ codeBlocks: (doc.extractedCodeBlocks || []).slice(0, 4),
4270
+ tables: (doc.extractedTables || []).slice(0, 4),
4271
+ rawByteSize: doc.byteSize || Buffer.byteLength(doc.markdownContent || "", "utf-8"),
4272
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4273
+ };
4274
+ this.items.push(item);
4275
+ this.urlIndex.set(key, item);
4276
+ this.idIndex.set(item.id, item);
4277
+ return this.toCompactReceipt(item);
4278
+ }
4279
+ /**
4280
+ * Records a lightweight search hit when full scraping is skipped or pending.
4281
+ */
4282
+ addSearchHit(hit, relevanceScore = 6) {
4283
+ const key = normalizeUrlKey(hit.url);
4284
+ const existing = this.urlIndex.get(key);
4285
+ if (existing) {
4286
+ return this.toCompactReceipt(existing);
4287
+ }
4288
+ const snippet = (hit.content || "").replace(/\s+/g, " ").trim();
4289
+ const item = {
4290
+ id: this.allocateId(),
4291
+ sourceType: hit.engine === "academic" ? "academic" : "web",
4292
+ title: hit.title || "Search Result",
4293
+ url: hit.url,
4294
+ relevanceScore: Math.max(1, Math.min(10, Math.round(relevanceScore))),
4295
+ headings: [],
4296
+ keyExcerpts: snippet ? [snippet.slice(0, 450)] : [],
4297
+ codeBlocks: [],
4298
+ tables: [],
4299
+ rawByteSize: Buffer.byteLength(snippet, "utf-8"),
4300
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4301
+ };
4302
+ this.items.push(item);
4303
+ this.urlIndex.set(key, item);
4304
+ this.idIndex.set(item.id, item);
4305
+ return this.toCompactReceipt(item);
4306
+ }
4307
+ /**
4308
+ * Records a peer-reviewed or preprint paper from Semantic Scholar, OpenAlex, Crossref, or arXiv.
4309
+ */
4310
+ addAcademicPaper(paper) {
4311
+ const url = paper.url || paper.pdfUrl || (paper.doi ? `https://doi.org/${paper.doi}` : `https://openalex.org/${paper.id}`);
4312
+ const key = normalizeUrlKey(url);
4313
+ const existing = this.urlIndex.get(key);
4314
+ if (existing) {
4315
+ return this.toCompactReceipt(existing);
4316
+ }
4317
+ const abstractOrTldr = [paper.tldr, paper.abstract].filter(Boolean).join(" \u2014 ").trim();
4318
+ const citationBonus = paper.citationCount >= 50 ? 9 : paper.citationCount >= 10 ? 8 : 7;
4319
+ const item = {
4320
+ id: this.allocateId(),
4321
+ sourceType: "academic",
4322
+ title: paper.title,
4323
+ url,
4324
+ authorOrVenue: [paper.authors?.slice(0, 3).join(", "), paper.venue, paper.year].filter(Boolean).join(" \xB7 "),
4325
+ publishedDate: paper.year ? String(paper.year) : void 0,
4326
+ relevanceScore: citationBonus,
4327
+ headings: paper.fieldsOfStudy || [],
4328
+ keyExcerpts: abstractOrTldr ? [abstractOrTldr.slice(0, 600)] : [`Academic paper: ${paper.title}`],
4329
+ codeBlocks: [],
4330
+ tables: [],
4331
+ rawByteSize: Buffer.byteLength(abstractOrTldr || paper.title, "utf-8"),
4332
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4333
+ };
4334
+ this.items.push(item);
4335
+ this.urlIndex.set(key, item);
4336
+ this.idIndex.set(item.id, item);
4337
+ return this.toCompactReceipt(item);
4338
+ }
4339
+ /**
4340
+ * Records a 30-day social/developer pulse signal (HackerNews, GitHub, Reddit).
4341
+ */
4342
+ addSocialPulseItem(pulse) {
4343
+ const key = normalizeUrlKey(pulse.url);
4344
+ const existing = this.urlIndex.get(key);
4345
+ if (existing) {
4346
+ return this.toCompactReceipt(existing);
4347
+ }
4348
+ const item = {
4349
+ id: this.allocateId(),
4350
+ sourceType: "social_pulse",
4351
+ title: pulse.title,
4352
+ url: pulse.url,
4353
+ authorOrVenue: `${pulse.platform.toUpperCase()}${pulse.author ? ` (@${pulse.author})` : ""}`,
4354
+ publishedDate: pulse.createdAt,
4355
+ relevanceScore: Math.max(1, Math.min(10, pulse.engagementScore)),
4356
+ headings: [pulse.platform.toUpperCase()],
4357
+ keyExcerpts: [pulse.snippet.slice(0, 450)],
4358
+ codeBlocks: [],
4359
+ tables: [],
4360
+ rawByteSize: Buffer.byteLength(pulse.snippet, "utf-8"),
4361
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4362
+ };
4363
+ this.items.push(item);
4364
+ this.urlIndex.set(key, item);
4365
+ this.idIndex.set(item.id, item);
4366
+ return this.toCompactReceipt(item);
4367
+ }
4368
+ /**
4369
+ * Records a verified STEM OER simulation/resource (PhET, OpenStax, NASA, CS Unplugged).
4370
+ */
4371
+ addStemResource(resource) {
4372
+ const key = normalizeUrlKey(resource.url);
4373
+ const existing = this.urlIndex.get(key);
4374
+ if (existing) {
4375
+ return this.toCompactReceipt(existing);
4376
+ }
4377
+ const excerpt = `${resource.description} [Provider: ${resource.provider}${resource.license ? `, License: ${resource.license}` : ""}]`;
4378
+ const item = {
4379
+ id: this.allocateId(),
4380
+ sourceType: "stem_oer",
4381
+ title: resource.title,
4382
+ url: resource.url,
4383
+ authorOrVenue: resource.provider,
4384
+ relevanceScore: 8,
4385
+ headings: [resource.provider],
4386
+ keyExcerpts: [excerpt.slice(0, 450)],
4387
+ codeBlocks: [],
4388
+ tables: [],
4389
+ rawByteSize: Buffer.byteLength(excerpt, "utf-8"),
4390
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
4391
+ };
4392
+ this.items.push(item);
4393
+ this.urlIndex.set(key, item);
4394
+ this.idIndex.set(item.id, item);
4395
+ return this.toCompactReceipt(item);
4396
+ }
4397
+ /**
4398
+ * Projects a full `LedgerItem` into a compact receipt (<= 150 tokens) for Stage A planning & gap analysis.
4399
+ */
4400
+ toCompactReceipt(item) {
4401
+ const rawExcerpt = item.keyExcerpts[0] || item.title;
4402
+ return {
4403
+ id: item.id,
4404
+ sourceType: item.sourceType,
4405
+ title: item.title.slice(0, 140),
4406
+ url: item.url,
4407
+ relevanceScore: item.relevanceScore,
4408
+ headings: item.headings.slice(0, 5),
4409
+ codeBlockCount: item.codeBlocks.length,
4410
+ tableCount: item.tables.length,
4411
+ briefExcerpt: rawExcerpt.slice(0, 300)
4412
+ };
4413
+ }
4414
+ getItems() {
4415
+ return [...this.items];
4416
+ }
4417
+ getApprovedItems(minScore = 6) {
4418
+ return this.items.filter((i) => i.relevanceScore >= minScore);
4419
+ }
4420
+ getReceipts() {
4421
+ return this.items.map((i) => this.toCompactReceipt(i));
4422
+ }
4423
+ getById(id) {
4424
+ return this.idIndex.get(id.toUpperCase());
4425
+ }
4426
+ getTotalCodeBlocks() {
4427
+ return this.items.reduce((sum, i) => sum + i.codeBlocks.length, 0);
4428
+ }
4429
+ getTotalTables() {
4430
+ return this.items.reduce((sum, i) => sum + i.tables.length, 0);
4431
+ }
4432
+ /**
4433
+ * Formats the top verified items with `[RES-xx]` tags, substantive excerpts, code blocks,
4434
+ * and tables for Stage B Contract Synthesis.
4435
+ */
4436
+ buildSynthesisCorpus(maxItems = 12) {
4437
+ const sorted = [...this.items].sort((a, b) => b.relevanceScore - a.relevanceScore).slice(0, maxItems);
4438
+ if (sorted.length === 0) {
4439
+ return "No verified sources recorded in EvidenceLedger.";
4440
+ }
4441
+ return sorted.map((item) => {
4442
+ const parts = [
4443
+ `[${item.id}] (${item.sourceType.toUpperCase()} \xB7 Score ${item.relevanceScore}/10) Title: ${item.title}`,
4444
+ `URL: ${item.url}`
4445
+ ];
4446
+ if (item.authorOrVenue) {
4447
+ parts.push(`Source/Author: ${item.authorOrVenue}`);
4448
+ }
4449
+ if (item.headings.length > 0) {
4450
+ parts.push(`Sections: ${item.headings.join(" | ")}`);
4451
+ }
4452
+ if (item.keyExcerpts.length > 0) {
4453
+ parts.push(`Verified Excerpts:
4454
+ ${item.keyExcerpts.map((e) => `- ${e}`).join("\n")}`);
4455
+ }
4456
+ if (item.codeBlocks.length > 0) {
4457
+ parts.push(
4458
+ `Extracted Code Blocks:
4459
+ ` + item.codeBlocks.slice(0, 2).map((cb) => `\`\`\`${cb.language || "text"}
4460
+ ${cb.code.slice(0, 600)}
4461
+ \`\`\``).join("\n")
4462
+ );
4463
+ }
4464
+ if (item.tables.length > 0) {
4465
+ parts.push(`Extracted Tables:
4466
+ ${item.tables.slice(0, 2).join("\n\n")}`);
4467
+ }
4468
+ return parts.join("\n");
4469
+ }).join("\n\n---\n\n");
4470
+ }
4471
+ /**
4472
+ * Returns concatenated plain text of all ledger items for deterministic/LLM `ClaimVerifier` checks.
4473
+ */
4474
+ buildFullRawCorpus() {
4475
+ return this.items.map(
4476
+ (i) => `${i.title}
4477
+ ${i.keyExcerpts.join("\n")}
4478
+ ${i.codeBlocks.map((c) => c.code).join("\n")}
4479
+ ${i.tables.join("\n")}`
4480
+ ).join("\n\n");
4481
+ }
4482
+ /**
4483
+ * Scans any synthesized report or JSON string for `[RES-xx]` citation markers
4484
+ * and verifies every marker against the ledger.
4485
+ */
4486
+ verifyCitationTags(synthesizedText) {
4487
+ const matches = [...synthesizedText.matchAll(/\[?(RES-\d{2,3})\]?/gi)];
4488
+ const validSet = /* @__PURE__ */ new Set();
4489
+ const invalidSet = /* @__PURE__ */ new Set();
4490
+ for (const m of matches) {
4491
+ const tag = m[1].toUpperCase();
4492
+ if (this.idIndex.has(tag)) {
4493
+ validSet.add(tag);
4494
+ } else {
4495
+ invalidSet.add(tag);
4496
+ }
4497
+ }
4498
+ return {
4499
+ validCitationIds: Array.from(validSet),
4500
+ invalidCitationIds: Array.from(invalidSet)
4501
+ };
4502
+ }
4503
+ /**
4504
+ * Maps ledger items into `ProvenanceRecord[]` for `ProvenanceTracker`.
4505
+ */
4506
+ toProvenanceRecords(defaultDomain = "general") {
4507
+ return this.items.map((item) => ({
4508
+ resourceId: item.id,
4509
+ sourceUrl: item.url,
4510
+ accessedAt: item.accessedAt,
4511
+ domain: item.sourceType || defaultDomain,
4512
+ relevanceScore: item.relevanceScore,
4513
+ byteSize: item.rawByteSize
4514
+ }));
4515
+ }
4516
+ };
4517
+ function describeZodSchemaKeys(schema) {
4518
+ if (!schema) return void 0;
4519
+ const def = schema?._def;
4520
+ if (def?.typeName === "ZodObject" && typeof def.shape === "function") {
4521
+ const shapeObj = def.shape();
4522
+ const keys = Object.keys(shapeObj);
4523
+ if (keys.length > 0) {
4524
+ return `JSON object with required top-level keys: ${keys.map((k) => `"${k}"`).join(", ")}`;
4525
+ }
4526
+ }
4527
+ return void 0;
4528
+ }
4529
+ function resolveResearchProfile(contract) {
4530
+ if (contract.profile && contract.profile !== "auto") {
4531
+ return contract.profile;
4532
+ }
4533
+ const text = `${contract.objective} ${contract.context?.positioning || ""}`.toLowerCase();
4534
+ if (/\b(hackernews|reddit|social|pulse|trend|last 30 days|community sentiment|github stars)\b/.test(text)) {
4535
+ return "social_pulse";
4536
+ }
4537
+ if (/\b(literature review|academic|peer-reviewed|openalex|arxiv|citation|paper|cs2023)\b/.test(text)) {
4538
+ return "academic";
4539
+ }
4540
+ if (/\b(phet|oer|openstax|simulation|worksheet|unplugged)\b/.test(text)) {
4541
+ return "curriculum_oer";
4542
+ }
4543
+ if (contract.context?.hardwarePlatform || contract.context?.softwareEnv || /\b(pinout|datasheet|gpio|i2c|pwm|api|sdk|compiler|microcontroller|arduino|esp32|roblox|swift|python)\b/.test(text)) {
4544
+ return "technical";
4545
+ }
4546
+ return "general";
4547
+ }
4548
+ var ResearchSubAgent = class {
4549
+ constructor(config = {}) {
4550
+ this.config = config;
4551
+ this.searchEngine = new MultiSourceSearchEngine({
4552
+ apiKeys: config.apiKeys,
4553
+ allowEnvFallback: config.allowEnvFallback,
4554
+ customAdapter: config.customSearchAdapter
4555
+ });
4556
+ this.webScraper = new WebScraper({
4557
+ crawl4aiHost: config.crawl4aiHost,
4558
+ jinaKey: config.apiKeys?.jina,
4559
+ brightDataKey: config.apiKeys?.brightdata || config.apiKeys?.brightData,
4560
+ allowEnvFallback: config.allowEnvFallback,
4561
+ customAdapter: config.customCrawlerAdapter
4562
+ });
4563
+ this.academicEngine = new AcademicSearchEngine({
4564
+ apiKey: config.apiKeys?.semanticScholar,
4565
+ allowEnvFallback: config.allowEnvFallback,
4566
+ customAdapter: config.customAcademicSearchAdapter
4567
+ });
4568
+ this.openAlexClient = new OpenAlexClient();
4569
+ this.socialPulseHarvester = new SocialPulseHarvester(this.searchEngine);
4570
+ this.stemResearcher = new StemResourceResearcher();
4571
+ this.healthAuditor = new HealthAuditor();
4572
+ this.evidenceScorer = new EvidenceScorer();
4573
+ this.claimVerifier = new ClaimVerifier();
4574
+ this.provenanceTracker = new ProvenanceTracker();
4575
+ }
4576
+ searchEngine;
4577
+ webScraper;
4578
+ academicEngine;
4579
+ openAlexClient;
4580
+ socialPulseHarvester;
4581
+ stemResearcher;
4582
+ healthAuditor;
4583
+ evidenceScorer;
4584
+ claimVerifier;
4585
+ provenanceTracker;
4586
+ /**
4587
+ * Executes a complete Plan-and-Execute research campaign governed by `contract`.
4588
+ */
4589
+ async run(contract, options) {
4590
+ const llm = options?.llm ?? this.config.llm;
4591
+ const resolvedProfile = resolveResearchProfile(contract);
4592
+ const preset = RESEARCH_PROFILE_PRESETS[resolvedProfile];
4593
+ const ctx = contract.context ?? this.config.defaultCourseContext;
4594
+ const domain = classifyTechnicalDomain(contract.objective, void 0, ctx).domain;
4595
+ const maxRounds = Math.max(1, Math.min(5, contract.budget?.maxRounds ?? preset.maxRounds));
4596
+ const maxQueriesPerRound = Math.max(1, Math.min(6, contract.budget?.maxQueriesPerRound ?? preset.maxQueriesPerRound));
4597
+ const maxScrapePerRound = Math.max(1, Math.min(6, contract.budget?.maxScrapePerRound ?? preset.maxScrapePerRound));
4598
+ const minSources = contract.acceptanceCriteria?.minSources ?? 2;
4599
+ const minRelevanceScore = contract.acceptanceCriteria?.minRelevanceScore ?? 6;
4600
+ const recencyDays = contract.acceptanceCriteria?.recencyDays ?? 30;
4601
+ const ledger = new EvidenceLedger();
4602
+ const executedQueries = /* @__PURE__ */ new Set();
4603
+ const scrapedUrls = /* @__PURE__ */ new Set();
4604
+ const roundTraces = [];
4605
+ let currentMissingGaps = [
4606
+ ...contract.acceptanceCriteria?.requiredAttributes || [],
4607
+ ...contract.requiredSections || []
4608
+ ];
4609
+ for (let round = 1; round <= maxRounds; round++) {
4610
+ const beforeReceiptCount = ledger.getReceipts().length;
4611
+ const plannedQueries = await this.planQueriesForRound({
4612
+ round,
4613
+ contract,
4614
+ profile: resolvedProfile,
4615
+ missingGaps: currentMissingGaps,
4616
+ receipts: ledger.getReceipts(),
4617
+ executedQueries,
4618
+ maxQueries: maxQueriesPerRound,
4619
+ llm
4620
+ });
4621
+ for (const q of plannedQueries) {
4622
+ executedQueries.add(q.toLowerCase());
4623
+ }
4624
+ await this.executeHarvestRound({
4625
+ round,
4626
+ queries: plannedQueries,
4627
+ contract,
4628
+ preset,
4629
+ domain,
4630
+ recencyDays,
4631
+ maxScrapePerRound,
4632
+ scrapedUrls,
4633
+ ledger
4634
+ });
4635
+ const afterReceiptCount = ledger.getReceipts().length;
4636
+ const newReceiptsAdded = afterReceiptCount - beforeReceiptCount;
4637
+ const evaluation = await this.evaluateRoundGaps({
4638
+ contract,
4639
+ ledger,
4640
+ minSources,
4641
+ minRelevanceScore,
4642
+ llm
4643
+ });
4644
+ currentMissingGaps = evaluation.missingGaps;
4645
+ roundTraces.push({
4646
+ round,
4647
+ plannedQueries,
4648
+ newReceiptsAdded,
4649
+ satisfiedAttributes: evaluation.satisfiedAttributes,
4650
+ missingGaps: evaluation.missingGaps
4651
+ });
4652
+ if (evaluation.missingGaps.length === 0) {
4653
+ break;
4654
+ }
4655
+ }
4656
+ const allItems = ledger.getItems();
4657
+ const approvedItems = ledger.getApprovedItems(minRelevanceScore);
4658
+ const provenanceSidecar = this.provenanceTracker.generateSidecar(
4659
+ contract.objective,
4660
+ ledger.toProvenanceRecords(domain)
4661
+ );
4662
+ if (allItems.length === 0) {
4663
+ const failMsg = `Research Sub-Agent failed to harvest any verified sources for objective: "${contract.objective}".`;
4664
+ return {
4665
+ status: "failed",
4666
+ objective: contract.objective,
4667
+ profile: resolvedProfile,
4668
+ roundsExecuted: roundTraces.length,
4669
+ data: null,
4670
+ markdownReport: `# \u274C Research Harvest Failed: ${contract.objective}
4671
+
4672
+ > ${failMsg}
4673
+
4674
+ ### Unresolved Gaps
4675
+ ${currentMissingGaps.length > 0 ? currentMissingGaps.map((g) => `- ${g}`).join("\n") : "- No reachable sources."}`,
4676
+ tier1Summary: failMsg,
4677
+ tier2TechnicalDigest: failMsg,
4678
+ ledgerItems: [],
4679
+ receipts: [],
4680
+ validCitationIds: [],
4681
+ invalidCitationIds: [],
4682
+ missingGaps: currentMissingGaps.length > 0 ? currentMissingGaps : ["minSources not met (0 harvested)"],
4683
+ roundTraces,
4684
+ provenanceMd: provenanceSidecar.provenanceMd
4685
+ };
4686
+ }
4687
+ return this.synthesizeAndVerify({
4688
+ contract,
4689
+ profile: resolvedProfile,
4690
+ domain,
4691
+ ledger,
4692
+ approvedCount: approvedItems.length,
4693
+ minSources,
4694
+ missingGaps: currentMissingGaps,
4695
+ roundTraces,
4696
+ provenanceMd: provenanceSidecar.provenanceMd,
4697
+ llm
4698
+ });
4699
+ }
4700
+ /**
4701
+ * Plans targeted search queries for Round 1 (initial coverage) or Round > 1 (surgical gap filling).
4702
+ */
4703
+ async planQueriesForRound(params) {
4704
+ const { round, contract, profile, missingGaps, receipts, executedQueries, maxQueries, llm } = params;
4705
+ const ctx = contract.context ?? this.config.defaultCourseContext;
4706
+ const toolAnchor = [ctx?.hardwarePlatform, ctx?.softwareEnv].filter(Boolean).join(" ").trim();
4707
+ const baseTopic = toolAnchor ? `${toolAnchor} ${contract.objective}` : contract.objective;
4708
+ if (llm) {
4709
+ try {
4710
+ const promptLines = [
4711
+ `You are a Principal Research Planner for an autonomous Plan-and-Execute Research Sub-Agent.`,
4712
+ `Objective: "${contract.objective}"`,
4713
+ `Profile: ${profile} | Round: ${round}`,
4714
+ toolAnchor ? `Hardware/Software Context: ${toolAnchor}` : "",
4715
+ ctx?.ageBand ? `Target Learner Age Band: ${ctx.ageBand[0]}-${ctx.ageBand[1]}` : "",
4716
+ contract.requiredSections?.length ? `Required Sections: ${contract.requiredSections.join(", ")}` : "",
4717
+ contract.acceptanceCriteria?.requiredAttributes?.length ? `Required Attributes: ${contract.acceptanceCriteria.requiredAttributes.join(", ")}` : "",
4718
+ contract.acceptanceCriteria?.requireCodeExamples ? `Must find verified code examples.` : "",
4719
+ contract.acceptanceCriteria?.requireTables ? `Must find specification/pinout tables.` : ""
4720
+ ];
4721
+ if (round > 1 && receipts.length > 0) {
4722
+ promptLines.push(
4723
+ `
4724
+ Compact Receipts Collected So Far (${receipts.length} sources):`,
4725
+ ...receipts.slice(0, 8).map(
4726
+ (r) => `- [${r.id}] ${r.title} (score:${r.relevanceScore}, code:${r.codeBlockCount}, tables:${r.tableCount}): ${r.briefExcerpt.slice(0, 140)}`
4727
+ ),
4728
+ `
4729
+ Remaining Unresolved Gaps to Fill in Round ${round}:`,
4730
+ ...missingGaps.map((g) => `- ${g}`),
4731
+ `
4732
+ Previously Executed Queries (DO NOT REPEAT): ${Array.from(executedQueries).join(" | ")}`
4733
+ );
4734
+ }
4735
+ promptLines.push(
4736
+ `
4737
+ Generate ${maxQueries} high-precision search queries to fulfill ${round === 1 ? "the objective and required attributes" : "ONLY the remaining unresolved gaps"}.`,
4738
+ `Return ONLY a valid JSON array of query strings: ["query 1", "query 2"]`
4739
+ );
4740
+ const raw = await llm(promptLines.filter(Boolean).join("\n"), {
4741
+ system: "Return strictly a valid JSON array of search query strings.",
4742
+ temperature: 0.2,
4743
+ jsonMode: true
4744
+ });
4745
+ const match = raw.match(/\[[\s\S]*\]/);
4746
+ if (match) {
4747
+ const parsed = JSON.parse(match[0]);
4748
+ if (Array.isArray(parsed)) {
4749
+ const candidateQueries = parsed.map((q) => String(q).trim()).filter((q) => q.length > 3 && !executedQueries.has(q.toLowerCase())).slice(0, maxQueries);
4750
+ if (candidateQueries.length > 0) {
4751
+ return candidateQueries;
4752
+ }
4753
+ }
4754
+ }
4755
+ } catch (e) {
4756
+ console.warn(`[ResearchSubAgent] Round ${round} LLM query planning fallback:`, e?.message || e);
4757
+ }
4758
+ }
4759
+ const fallbackQueries = [];
4760
+ if (round === 1) {
4761
+ fallbackQueries.push(
4762
+ `${baseTopic} official documentation architecture specification`.trim(),
4763
+ `${baseTopic} practical examples tutorial implementation`.trim(),
4764
+ `${baseTopic} common pitfalls debugging troubleshooting bottlenecks`.trim()
4765
+ );
4766
+ if (contract.acceptanceCriteria?.requireTables) {
4767
+ fallbackQueries.push(`${baseTopic} pinout specification comparison table`.trim());
4768
+ }
4769
+ } else {
4770
+ for (const gap of missingGaps) {
4771
+ const candidate = `${baseTopic} ${gap}`.trim();
4772
+ if (!executedQueries.has(candidate.toLowerCase())) {
4773
+ fallbackQueries.push(candidate);
4774
+ }
4775
+ }
4776
+ if (fallbackQueries.length === 0) {
4777
+ fallbackQueries.push(`${baseTopic} advanced reference guide code examples`.trim());
4778
+ }
4779
+ }
4780
+ return fallbackQueries.filter((q) => !executedQueries.has(q.toLowerCase())).slice(0, maxQueries);
4781
+ }
4782
+ /**
4783
+ * Executes active harvesters in parallel and stores results in the Out-of-Band `EvidenceLedger`.
4784
+ */
4785
+ async executeHarvestRound(params) {
4786
+ const { round, queries, contract, preset, domain, recencyDays, maxScrapePerRound, scrapedUrls, ledger } = params;
4787
+ if (queries.length === 0) return;
4788
+ const tasks = [];
4789
+ if (preset.enableWeb) {
4790
+ tasks.push(
4791
+ (async () => {
4792
+ const candidateHits = [];
4793
+ for (const q of queries) {
4794
+ try {
4795
+ const hits = await this.searchEngine.search(q, { limit: 3 });
4796
+ for (const h of hits) {
4797
+ if (!isCommercialOrNoise({ url: h.url, title: h.title, snippet: h.content })) {
4798
+ if (!candidateHits.some((existing) => existing.url === h.url)) {
4799
+ candidateHits.push(h);
4800
+ }
4801
+ }
4802
+ }
4803
+ } catch {
4804
+ }
4805
+ }
4806
+ const urlsToScrape = candidateHits.filter((h) => !scrapedUrls.has(h.url)).slice(0, maxScrapePerRound);
4807
+ await Promise.allSettled(
4808
+ urlsToScrape.map(async (hit) => {
4809
+ scrapedUrls.add(hit.url);
4810
+ try {
4811
+ const doc = await this.webScraper.scrapeUrl(hit.url);
4812
+ const health = this.healthAuditor.auditDocument(doc);
4813
+ if (health.passed && doc.markdownContent.trim().length > 80) {
4814
+ const scored = this.evidenceScorer.scoreDocument(doc, domain, contract.objective);
4815
+ ledger.addScrapedDocument(doc, scored.score, scored.keyTakeaways);
4816
+ return;
4817
+ }
4818
+ } catch {
4819
+ }
4820
+ if (hit.content && hit.content.trim().length > 30) {
4821
+ ledger.addSearchHit(hit, 6);
4822
+ }
4823
+ })
4824
+ );
4825
+ for (const hit of candidateHits.slice(maxScrapePerRound, maxScrapePerRound + 2)) {
4826
+ if (hit.content && hit.content.trim().length > 40) {
4827
+ ledger.addSearchHit(hit, 6);
4828
+ }
4829
+ }
4830
+ })()
4831
+ );
4832
+ }
4833
+ if (preset.enableAcademic && round === 1) {
4834
+ tasks.push(
4835
+ (async () => {
4836
+ try {
4837
+ const primaryQuery = queries[0] || contract.objective;
4838
+ const [s2Papers, oaPapers] = await Promise.all([
4839
+ this.academicEngine.searchPapers(primaryQuery, { limit: 3 }),
4840
+ this.openAlexClient.searchWorks(primaryQuery, { limit: 3 })
4841
+ ]);
4842
+ for (const p of [...s2Papers, ...oaPapers].slice(0, 5)) {
4843
+ ledger.addAcademicPaper(p);
4844
+ }
4845
+ } catch (e) {
4846
+ console.warn("[ResearchSubAgent] Academic harvest error:", e?.message || e);
4847
+ }
4848
+ })()
4849
+ );
4850
+ }
4851
+ if (preset.enableSocialPulse && round === 1) {
4852
+ tasks.push(
4853
+ (async () => {
4854
+ try {
4855
+ const pulseReport = await this.socialPulseHarvester.harvest(contract.objective, {
4856
+ recencyDays,
4857
+ limitPerPlatform: 3
4858
+ });
4859
+ for (const item of pulseReport.items.slice(0, 5)) {
4860
+ ledger.addSocialPulseItem(item);
4861
+ }
4862
+ } catch (e) {
4863
+ console.warn("[ResearchSubAgent] Social pulse harvest error:", e?.message || e);
4864
+ }
4865
+ })()
4866
+ );
4867
+ }
4868
+ if (preset.enableStemOer && round === 1) {
4869
+ tasks.push(
4870
+ (async () => {
4871
+ try {
4872
+ const oerCatalog = await this.stemResearcher.findResources(contract.objective, {
4873
+ limit: 4
4874
+ });
4875
+ for (const res of oerCatalog.resources.slice(0, 4)) {
4876
+ ledger.addStemResource({
4877
+ title: res.title,
4878
+ url: res.url,
4879
+ description: res.description,
4880
+ provider: res.provider,
4881
+ license: res.license?.type
4882
+ });
4883
+ }
4884
+ } catch (e) {
4885
+ console.warn("[ResearchSubAgent] STEM OER harvest error:", e?.message || e);
4886
+ }
4887
+ })()
4888
+ );
4889
+ }
4890
+ await Promise.allSettled(tasks);
4891
+ }
4892
+ /**
4893
+ * Evaluates whether the current `EvidenceLedger` satisfies `acceptanceCriteria`,
4894
+ * `requiredAttributes`, and `requiredSections`.
4895
+ */
4896
+ async evaluateRoundGaps(params) {
4897
+ const { contract, ledger, minSources, minRelevanceScore, llm } = params;
4898
+ const missingGaps = [];
4899
+ const satisfiedAttributes = [];
4900
+ const approved = ledger.getApprovedItems(minRelevanceScore);
4901
+ if (approved.length < minSources) {
4902
+ missingGaps.push(`Need at least ${minSources} verified sources with score >= ${minRelevanceScore} (currently ${approved.length})`);
4903
+ } else {
4904
+ satisfiedAttributes.push(`minSources(${approved.length}/${minSources})`);
4905
+ }
4906
+ if (contract.acceptanceCriteria?.requireCodeExamples && ledger.getTotalCodeBlocks() === 0) {
4907
+ missingGaps.push("Missing verified code examples / syntax snippets");
4908
+ } else if (contract.acceptanceCriteria?.requireCodeExamples) {
4909
+ satisfiedAttributes.push(`codeExamples(${ledger.getTotalCodeBlocks()})`);
4910
+ }
4911
+ if (contract.acceptanceCriteria?.requireTables && ledger.getTotalTables() === 0) {
4912
+ missingGaps.push("Missing specification or pinout markdown tables");
4913
+ } else if (contract.acceptanceCriteria?.requireTables) {
4914
+ satisfiedAttributes.push(`tables(${ledger.getTotalTables()})`);
4915
+ }
4916
+ const targetCheckList = [
4917
+ ...contract.acceptanceCriteria?.requiredAttributes || [],
4918
+ ...contract.requiredSections || []
4919
+ ];
4920
+ if (targetCheckList.length > 0) {
4921
+ const receipts = ledger.getReceipts();
4922
+ if (receipts.length === 0) {
4923
+ missingGaps.push(...targetCheckList);
4924
+ } else if (llm) {
4925
+ try {
4926
+ const prompt = [
4927
+ `Evaluate which of the required attributes/sections are covered by the collected Citation Receipts for "${contract.objective}".`,
4928
+ `Required Items: ${JSON.stringify(targetCheckList)}`,
4929
+ `Collected Citation Receipts:
4930
+ ${receipts.map((r) => `- [${r.id}] ${r.title} (headings: ${r.headings.join(", ")}): ${r.briefExcerpt}`).join("\n")}`,
4931
+ `Return ONLY a JSON object: {"satisfied": ["item1"], "missing": ["item2"]}`
4932
+ ].join("\n");
4933
+ const raw = await llm(prompt, {
4934
+ system: 'Output strictly valid JSON object with "satisfied" and "missing" string arrays.',
4935
+ temperature: 0.1,
4936
+ jsonMode: true
4937
+ });
4938
+ const match = raw.match(/\{[\s\S]*\}/);
4939
+ if (match) {
4940
+ const parsed = JSON.parse(match[0]);
4941
+ if (Array.isArray(parsed.satisfied)) {
4942
+ satisfiedAttributes.push(...parsed.satisfied.map(String));
4943
+ }
4944
+ if (Array.isArray(parsed.missing)) {
4945
+ missingGaps.push(...parsed.missing.map(String));
4946
+ }
4947
+ return { satisfiedAttributes, missingGaps };
4948
+ }
4949
+ } catch {
4950
+ }
4951
+ }
4952
+ const lowerCorpus = ledger.buildFullRawCorpus().toLowerCase();
4953
+ for (const reqItem of targetCheckList) {
4954
+ const tokens = reqItem.toLowerCase().replace(/[^a-z0-9\u00C0-\u1EF9]+/g, " ").split(/\s+/).filter((t) => t.length >= 3);
4955
+ const matched = tokens.filter((t) => lowerCorpus.includes(t)).length;
4956
+ if (tokens.length === 0 || matched / tokens.length >= 0.5) {
4957
+ satisfiedAttributes.push(reqItem);
4958
+ } else {
4959
+ missingGaps.push(reqItem);
4960
+ }
4961
+ }
4962
+ }
4963
+ return { satisfiedAttributes, missingGaps };
4964
+ }
4965
+ /**
4966
+ * Stage B: Synthesizes `EvidenceLedger` excerpts into `outputSchema<T>` + `markdownReport`
4967
+ * and runs deterministic schema, citation, and claim verification gates.
4968
+ */
4969
+ async synthesizeAndVerify(params) {
4970
+ const { contract, profile, ledger, approvedCount, minSources, missingGaps, roundTraces, provenanceMd, llm } = params;
4971
+ const synthesisCorpus = ledger.buildSynthesisCorpus(12);
4972
+ const items = ledger.getItems();
4973
+ const receipts = ledger.getReceipts();
4974
+ let synthesizedData = null;
4975
+ let markdownReport = "";
4976
+ let tier1Summary = "";
4977
+ let tier2TechnicalDigest = "";
4978
+ let keyClaims = [];
4979
+ let isLlmSynthesized = false;
4980
+ const schemaHint = contract.outputSchemaDescription || describeZodSchemaKeys(contract.outputSchema) || "JSON object capturing the key structured findings, technical constraints, exemplars, and citations";
4981
+ if (llm) {
4982
+ try {
4983
+ const requiredSectionsText = contract.requiredSections && contract.requiredSections.length > 0 ? contract.requiredSections.join(", ") : "Executive Summary, Key Technical & Empirical Findings, Practical Exemplars & Code/Specs, Common Pitfalls & Bottlenecks, Verified Sources";
4984
+ const prompt = [
4985
+ `You are a Principal Research Synthesizer. Synthesize the verified EvidenceLedger sources below to fulfill the Research Contract.`,
4986
+ `Objective: "${contract.objective}"`,
4987
+ `Profile: ${profile}`,
4988
+ contract.context?.ageBand ? `Learner Age Band: ${contract.context.ageBand[0]}-${contract.context.ageBand[1]}` : "",
4989
+ contract.context?.hardwarePlatform ? `Hardware Platform: ${contract.context.hardwarePlatform}` : "",
4990
+ contract.context?.softwareEnv ? `Software/Tools: ${contract.context.softwareEnv}` : "",
4991
+ `Required Markdown Sections: ${requiredSectionsText}`,
4992
+ `Required Structured "data" Payload Format: ${schemaHint}`,
4993
+ contract.acceptanceCriteria?.forbiddenTerms?.length ? `Forbidden Terms (MUST NOT APPEAR): ${contract.acceptanceCriteria.forbiddenTerms.join(", ")}` : "",
4994
+ `
4995
+ CRITICAL GROUNDING RULES:`,
4996
+ `1. Every claim, metric, pinout, or recommendation MUST cite its EvidenceLedger ID in brackets, e.g. [RES-01], [RES-02].`,
4997
+ `2. NEVER invent citation IDs outside [RES-01]..[RES-${String(items.length).padStart(2, "0")}].`,
4998
+ `3. If evidence for a specific attribute is missing from the ledger, state that explicitly rather than fabricating facts.`,
4999
+ `
5000
+ === VERIFIED EVIDENCE LEDGER ===
5001
+ ${synthesisCorpus}`,
5002
+ `
5003
+ Return ONLY a valid JSON object with the exact envelope:`,
5004
+ `{`,
5005
+ ` "data": { ...structured payload matching the Required Structured "data" Payload Format... },`,
5006
+ ` "markdownReport": "# Full Markdown Report with [RES-xx] citations and Required Markdown Sections...",`,
5007
+ ` "tier1Summary": "Concise <=200-word executive summary with [RES-xx] citations",`,
5008
+ ` "tier2TechnicalDigest": "Bulleted technical digest (<=600 words) preserving concrete APIs, specs, code/tables, and pitfalls with [RES-xx] tags",`,
5009
+ ` "keyClaims": ["Core factual claim 1 from report", "Core factual claim 2"]`,
5010
+ `}`
5011
+ ].filter(Boolean).join("\n");
5012
+ const raw = await llm(prompt, {
5013
+ system: "Output strictly valid JSON matching the requested synthesis envelope. Ground every claim in [RES-xx].",
5014
+ temperature: 0.2,
5015
+ jsonMode: true
5016
+ });
5017
+ const match = raw.match(/\{[\s\S]*\}/);
5018
+ if (match) {
5019
+ const parsed = JSON.parse(match[0]);
5020
+ markdownReport = typeof parsed.markdownReport === "string" ? parsed.markdownReport : "";
5021
+ tier1Summary = typeof parsed.tier1Summary === "string" ? parsed.tier1Summary : "";
5022
+ tier2TechnicalDigest = typeof parsed.tier2TechnicalDigest === "string" ? parsed.tier2TechnicalDigest : "";
5023
+ keyClaims = Array.isArray(parsed.keyClaims) ? parsed.keyClaims.map(String) : [];
5024
+ const candidateData = parsed.data !== void 0 ? parsed.data : parsed;
5025
+ if (contract.outputSchema) {
5026
+ const validation = contract.outputSchema.safeParse(candidateData);
5027
+ if (validation.success) {
5028
+ synthesizedData = validation.data;
5029
+ isLlmSynthesized = true;
5030
+ } else {
5031
+ const issuesText = validation.error.issues.map((iss) => `${iss.path.join(".") || "root"}: ${iss.message}`).join("; ");
5032
+ const repairPrompt = [
5033
+ `The synthesized "data" object failed Zod schema validation with issues: ${issuesText}`,
5034
+ `Schema requirement: ${schemaHint}`,
5035
+ `Original candidate data: ${JSON.stringify(candidateData)}`,
5036
+ `Repair and return ONLY the valid JSON object for "data" grounded strictly in the EvidenceLedger.`
5037
+ ].join("\n");
5038
+ const repairedRaw = await llm(repairPrompt, {
5039
+ system: "Return strictly valid JSON object matching the schema.",
5040
+ temperature: 0.1,
5041
+ jsonMode: true
5042
+ });
5043
+ const repMatch = repairedRaw.match(/\{[\s\S]*\}/);
5044
+ if (repMatch) {
5045
+ const repParsed = JSON.parse(repMatch[0]);
5046
+ const repCheck = contract.outputSchema.safeParse(repParsed);
5047
+ if (repCheck.success) {
5048
+ synthesizedData = repCheck.data;
5049
+ isLlmSynthesized = true;
5050
+ } else {
5051
+ missingGaps.push(`Output schema validation incomplete: ${issuesText}`);
5052
+ }
5053
+ }
5054
+ }
5055
+ } else {
5056
+ synthesizedData = candidateData;
5057
+ isLlmSynthesized = true;
5058
+ }
5059
+ }
5060
+ } catch (e) {
5061
+ console.warn("[ResearchSubAgent] Stage B LLM synthesis error, falling back to deterministic ledger compilation:", e?.message || e);
5062
+ }
5063
+ }
5064
+ if (!markdownReport) {
5065
+ markdownReport = this.buildDeterministicMarkdownReport(contract.objective, profile, items, contract.requiredSections);
5066
+ }
5067
+ if (!tier1Summary) {
5068
+ tier1Summary = items.slice(0, 3).map((i) => `[${i.id}] ${i.title}: ${i.keyExcerpts[0] || ""}`).join(" ");
5069
+ }
5070
+ if (!tier2TechnicalDigest) {
5071
+ tier2TechnicalDigest = items.slice(0, 6).map((i) => `- **[${i.id}] ${i.title}** (${i.url}): ${i.keyExcerpts.slice(0, 2).join(" ")}`).join("\n");
5072
+ }
5073
+ if (synthesizedData === null && !contract.outputSchema) {
5074
+ synthesizedData = {
5075
+ objective: contract.objective,
5076
+ profile,
5077
+ sources: receipts,
5078
+ codeSnippets: items.flatMap((i) => i.codeBlocks).slice(0, 4),
5079
+ tables: items.flatMap((i) => i.tables).slice(0, 4)
5080
+ };
5081
+ }
5082
+ const combinedText = `${markdownReport}
5083
+ ${tier1Summary}
5084
+ ${tier2TechnicalDigest}
5085
+ ${JSON.stringify(synthesizedData || {})}`;
5086
+ const { validCitationIds, invalidCitationIds } = ledger.verifyCitationTags(combinedText);
5087
+ if (invalidCitationIds.length > 0) {
5088
+ for (const badId of invalidCitationIds) {
5089
+ const regex = new RegExp(`\\[?${badId}\\]?`, "gi");
5090
+ markdownReport = markdownReport.replace(regex, "[UNVERIFIED-CITATION-REMOVED]");
5091
+ tier1Summary = tier1Summary.replace(regex, "");
5092
+ tier2TechnicalDigest = tier2TechnicalDigest.replace(regex, "");
5093
+ }
5094
+ }
5095
+ if (contract.acceptanceCriteria?.forbiddenTerms?.length) {
5096
+ const lowerReport = markdownReport.toLowerCase();
5097
+ for (const forbidden of contract.acceptanceCriteria.forbiddenTerms) {
5098
+ if (lowerReport.includes(forbidden.toLowerCase())) {
5099
+ missingGaps.push(`Forbidden term detected in output: "${forbidden}"`);
5100
+ }
5101
+ }
5102
+ }
5103
+ const claimsToVerify = keyClaims.length > 0 ? keyClaims : items.slice(0, 4).map((i) => i.keyExcerpts[0]).filter((e) => Boolean(e && e.length > 25));
5104
+ const claimVerification = claimsToVerify.length > 0 ? this.claimVerifier.verifyClaimsDeterministic(claimsToVerify, ledger.buildFullRawCorpus()) : void 0;
5105
+ let status = "success";
5106
+ if (!isLlmSynthesized && llm) {
5107
+ status = "degraded";
5108
+ } else if (missingGaps.length > 0 || approvedCount < minSources || contract.outputSchema && synthesizedData === null) {
5109
+ status = "partial";
5110
+ } else if (!llm) {
5111
+ status = contract.outputSchema && synthesizedData === null ? "degraded" : "success";
5112
+ }
5113
+ return {
5114
+ status,
5115
+ objective: contract.objective,
5116
+ profile,
5117
+ roundsExecuted: roundTraces.length,
5118
+ data: synthesizedData,
5119
+ markdownReport,
5120
+ tier1Summary: tier1Summary.slice(0, 1800),
5121
+ tier2TechnicalDigest: tier2TechnicalDigest.slice(0, 4e3),
5122
+ ledgerItems: items,
5123
+ receipts,
5124
+ validCitationIds,
5125
+ invalidCitationIds,
5126
+ missingGaps: Array.from(new Set(missingGaps)),
5127
+ roundTraces,
5128
+ claimVerification,
5129
+ provenanceMd
5130
+ };
5131
+ }
5132
+ buildDeterministicMarkdownReport(objective, profile, items, requiredSections) {
5133
+ const lines = [
5134
+ `# \u{1F52C} Autonomous Research Dossier: ${objective}`,
5135
+ `> **Profile:** \`${profile.toUpperCase()}\` | **Verified Ledger Sources:** \`${items.length}\``
5136
+ ];
5137
+ if (requiredSections && requiredSections.length > 0) {
5138
+ for (const section of requiredSections) {
5139
+ lines.push(`
5140
+ ## ${section}`);
5141
+ for (const item of items.slice(0, 4)) {
5142
+ if (item.keyExcerpts[0]) {
5143
+ lines.push(`- **[${item.id}] ${item.title}**: ${item.keyExcerpts[0]}`);
5144
+ }
5145
+ }
5146
+ }
5147
+ } else {
5148
+ lines.push(`
5149
+ ## 1. Executive Summary & Verified Findings`);
5150
+ for (const item of items) {
5151
+ lines.push(
5152
+ `### [${item.id}] ${item.title} (${item.sourceType.toUpperCase()} \xB7 Score \`${item.relevanceScore}/10\`)`,
5153
+ `- **URL:** ${item.url}`,
5154
+ ...item.keyExcerpts.slice(0, 3).map((ex) => `- ${ex}`)
5155
+ );
5156
+ }
5157
+ }
5158
+ const allCode = items.flatMap((i) => i.codeBlocks.map((cb) => ({ id: i.id, ...cb }))).slice(0, 4);
5159
+ if (allCode.length > 0) {
3828
5160
  lines.push(
3829
5161
  `
3830
- ## 7. Pinout & Specification Tables`,
3831
- ...fs.pinoutTables
5162
+ ## Extracted Code Examples`,
5163
+ ...allCode.map((c) => `From **[${c.id}]**:
5164
+ \`\`\`${c.language || "text"}
5165
+ ${c.code}
5166
+ \`\`\``)
3832
5167
  );
3833
5168
  }
5169
+ const allTables = items.flatMap((i) => i.tables.map((t) => ({ id: i.id, table: t }))).slice(0, 4);
5170
+ if (allTables.length > 0) {
5171
+ lines.push(
5172
+ `
5173
+ ## Extracted Specification Tables`,
5174
+ ...allTables.map((t) => `From **[${t.id}]**:
5175
+
5176
+ ${t.table}`)
5177
+ );
5178
+ }
5179
+ lines.push(
5180
+ `
5181
+ ## Evidence Ledger Citations`,
5182
+ ...items.map((i) => `- **[${i.id}]** [${i.title}](${i.url}) \u2014 *${i.sourceType}, score ${i.relevanceScore}/10*`)
5183
+ );
3834
5184
  return lines.join("\n");
3835
5185
  }
3836
5186
  };
5187
+ async function runResearchSubAgent(contract, config = {}) {
5188
+ const agent = new ResearchSubAgent(config);
5189
+ return agent.run(contract, { llm: config.llm });
5190
+ }
5191
+ var ResearchAgentToolInputSchema = zod.z.object({
5192
+ objective: zod.z.string().min(3).describe("The specific research question, topic, or technical requirement to investigate."),
5193
+ profile: zod.z.enum(["auto", "fast_grounded", "deep_autonomous", "technical", "academic", "social_pulse", "curriculum_oer", "general"]).optional().default("auto").describe("Execution profile selecting the appropriate multi-source harvesters and loop budget."),
5194
+ requiredSections: zod.z.array(zod.z.string()).optional().describe("Optional list of required Markdown sections in the synthesized report."),
5195
+ requiredAttributes: zod.z.array(zod.z.string()).optional().describe("Optional list of specific technical attributes, specs, or sub-questions that must be verified."),
5196
+ requireCodeExamples: zod.z.boolean().optional().describe("Set true if verified code examples are mandatory."),
5197
+ requireTables: zod.z.boolean().optional().describe("Set true if pinout or specification tables are mandatory."),
5198
+ recencyDays: zod.z.number().int().min(1).max(365).optional().describe("Recency window in days for social/community pulse."),
5199
+ maxRounds: zod.z.number().int().min(1).max(4).optional().describe("Maximum Plan-Harvest-Evaluate rounds (1-4).")
5200
+ });
5201
+ function createResearchAgentTool(config = {}) {
5202
+ const subAgent = new ResearchSubAgent(config);
5203
+ return {
5204
+ name: "research_subagent",
5205
+ description: "Autonomous Plan-and-Execute Research Sub-Agent. Plans multi-source queries (Web, Official Docs, Semantic Scholar, OpenAlex, HackerNews/GitHub 30-day Pulse, STEM OER), verifies sources into an immutable EvidenceLedger [RES-xx], checks for coverage gaps, and returns a citation-grounded report.",
5206
+ parameters: ResearchAgentToolInputSchema,
5207
+ inputSchema: ResearchAgentToolInputSchema,
5208
+ execute: async (input) => {
5209
+ const result = await subAgent.run({
5210
+ objective: input.objective,
5211
+ profile: input.profile,
5212
+ requiredSections: input.requiredSections,
5213
+ acceptanceCriteria: {
5214
+ requiredAttributes: input.requiredAttributes,
5215
+ requireCodeExamples: input.requireCodeExamples,
5216
+ requireTables: input.requireTables,
5217
+ recencyDays: input.recencyDays
5218
+ },
5219
+ budget: {
5220
+ maxRounds: input.maxRounds
5221
+ }
5222
+ });
5223
+ return {
5224
+ status: result.status,
5225
+ objective: result.objective,
5226
+ profile: result.profile,
5227
+ roundsExecuted: result.roundsExecuted,
5228
+ tier1Summary: result.tier1Summary,
5229
+ tier2TechnicalDigest: result.tier2TechnicalDigest,
5230
+ citations: result.receipts.map((r) => ({
5231
+ id: r.id,
5232
+ title: r.title,
5233
+ url: r.url,
5234
+ sourceType: r.sourceType,
5235
+ score: r.relevanceScore
5236
+ })),
5237
+ missingGaps: result.missingGaps,
5238
+ fullResult: result
5239
+ };
5240
+ }
5241
+ };
5242
+ }
3837
5243
 
3838
5244
  // src/services/researchKitClient.ts
3839
5245
  var KnowledgeDiscoveryService = class {
@@ -3853,11 +5259,13 @@ var KnowledgeDiscoveryService = class {
3853
5259
  });
3854
5260
  this.youtubeService = new YouTubeIngestionService();
3855
5261
  this.stemResearcher = new StemResourceResearcher();
5262
+ this.socialPulseHarvester = new SocialPulseHarvester(this.searchEngine);
3856
5263
  }
3857
5264
  searchEngine;
3858
5265
  webScraper;
3859
5266
  youtubeService;
3860
5267
  stemResearcher;
5268
+ socialPulseHarvester;
3861
5269
  async search(query, limit = 5) {
3862
5270
  return this.searchEngine.search(query, {
3863
5271
  limit,
@@ -3877,6 +5285,9 @@ var KnowledgeDiscoveryService = class {
3877
5285
  async findStemResources(query, options) {
3878
5286
  return this.stemResearcher.findResources(query, options);
3879
5287
  }
5288
+ async searchSocialPulse(topic, options) {
5289
+ return this.socialPulseHarvester.harvest(topic, options);
5290
+ }
3880
5291
  };
3881
5292
  var TerminologyGraphService = class {
3882
5293
  constructor(config) {
@@ -4072,8 +5483,9 @@ var ResearchKitClient = class {
4072
5483
  this.verification = new EvidenceVerificationService(config);
4073
5484
  this.orchestrator = new PedagogicalSynthesisService(config);
4074
5485
  this.grounding = new TechnicalGroundingService(config);
5486
+ this.agent = new ResearchSubAgent(config);
4075
5487
  }
4076
- /** Service 1: Multi-Engine Web Search, Scraper & YouTube Transcript Ingestion */
5488
+ /** Service 1: Multi-Engine Web Search, Scraper, YouTube Transcript & 30-Day Social Pulse */
4077
5489
  discovery;
4078
5490
  /** Service 2: Bilingual Pedagogical Term Extraction & Prerequisite Concept Graph (DAG) */
4079
5491
  terminology;
@@ -4085,6 +5497,8 @@ var ResearchKitClient = class {
4085
5497
  orchestrator;
4086
5498
  /** Service 6: Technical Grounding, Hardware/Software Compatibility & Empirical Exemplars */
4087
5499
  grounding;
5500
+ /** Service 7: Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent (v1.3.0) */
5501
+ agent;
4088
5502
  };
4089
5503
 
4090
5504
  exports.AcademicPaperSchema = AcademicPaperSchema;
@@ -4100,6 +5514,7 @@ exports.ClaimVerifier = ClaimVerifier;
4100
5514
  exports.DEFAULT_RESEARCH_CONFIG = DEFAULT_RESEARCH_CONFIG;
4101
5515
  exports.ECOMMERCE_AND_COMMERCIAL_PATTERNS = ECOMMERCE_AND_COMMERCIAL_PATTERNS;
4102
5516
  exports.ECOMMERCE_DOMAINS = ECOMMERCE_DOMAINS;
5517
+ exports.EvidenceLedger = EvidenceLedger;
4103
5518
  exports.EvidenceScorer = EvidenceScorer;
4104
5519
  exports.EvidenceVerificationService = EvidenceVerificationService;
4105
5520
  exports.GitHubCurriculumClient = GitHubCurriculumClient;
@@ -4109,13 +5524,18 @@ exports.KnowledgeDiscoveryService = KnowledgeDiscoveryService;
4109
5524
  exports.LiteratureReviewSynthesizer = LiteratureReviewSynthesizer;
4110
5525
  exports.MultiSourceSearchEngine = MultiSourceSearchEngine;
4111
5526
  exports.NasaMediaClient = NasaMediaClient;
5527
+ exports.OpenAlexClient = OpenAlexClient;
4112
5528
  exports.OpenverseClient = OpenverseClient;
4113
5529
  exports.PedagogicalSynthesisService = PedagogicalSynthesisService;
4114
5530
  exports.PedagogicalTermExtractor = PedagogicalTermExtractor;
4115
5531
  exports.ProvenanceTracker = ProvenanceTracker;
5532
+ exports.RESEARCH_PROFILE_PRESETS = RESEARCH_PROFILE_PRESETS;
4116
5533
  exports.ReferencePackBuilder = ReferencePackBuilder;
5534
+ exports.ResearchAgentToolInputSchema = ResearchAgentToolInputSchema;
4117
5535
  exports.ResearchConfigSchema = ResearchConfigSchema;
4118
5536
  exports.ResearchKitClient = ResearchKitClient;
5537
+ exports.ResearchSubAgent = ResearchSubAgent;
5538
+ exports.SocialPulseHarvester = SocialPulseHarvester;
4119
5539
  exports.StemResourceResearcher = StemResourceResearcher;
4120
5540
  exports.TechnicalGroundingEngine = TechnicalGroundingEngine;
4121
5541
  exports.TechnicalGroundingService = TechnicalGroundingService;
@@ -4123,6 +5543,8 @@ exports.TerminologyGraphService = TerminologyGraphService;
4123
5543
  exports.WebScraper = WebScraper;
4124
5544
  exports.YouTubeIngestionService = YouTubeIngestionService;
4125
5545
  exports.classifyTechnicalDomain = classifyTechnicalDomain;
5546
+ exports.cleanCrossrefAbstract = cleanCrossrefAbstract;
5547
+ exports.createResearchAgentTool = createResearchAgentTool;
4126
5548
  exports.evaluateTechnicalDensity = evaluateTechnicalDensity;
4127
5549
  exports.extractSubstantiveExcerpts = extractSubstantiveExcerpts;
4128
5550
  exports.extractTopSentences = extractTopSentences;
@@ -4135,6 +5557,8 @@ exports.kahnTopologicalSort = kahnTopologicalSort;
4135
5557
  exports.mapTopicToCS2023 = mapTopicToCS2023;
4136
5558
  exports.normalizeUrlForDedup = normalizeUrlForDedup;
4137
5559
  exports.reconstructOpenAlexAbstract = reconstructOpenAlexAbstract;
5560
+ exports.resolveResearchProfile = resolveResearchProfile;
5561
+ exports.runResearchSubAgent = runResearchSubAgent;
4138
5562
  exports.stitchCaptionSegments = stitchCaptionSegments;
4139
5563
  exports.transitiveReduction = transitiveReduction;
4140
5564
  //# sourceMappingURL=index.cjs.map