@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.
- package/dist/academic/index.cjs +122 -0
- package/dist/academic/index.cjs.map +1 -1
- package/dist/academic/index.d.cts +27 -4
- package/dist/academic/index.d.ts +27 -4
- package/dist/academic/index.js +2 -1
- package/dist/agent/index.cjs +3441 -0
- package/dist/agent/index.cjs.map +1 -0
- package/dist/agent/index.d.cts +10 -0
- package/dist/agent/index.d.ts +10 -0
- package/dist/agent/index.js +10 -0
- package/dist/agent/index.js.map +1 -0
- package/dist/{catalogBuilder-B4eiLS_S.d.cts → catalogBuilder-BBCa9jqI.d.cts} +2 -2
- package/dist/{catalogBuilder-BNB_gaWP.d.ts → catalogBuilder-D-UiM37y.d.ts} +2 -2
- package/dist/chunk-2GBXVPOQ.js +3 -0
- package/dist/{chunk-J3VCGH7Z.js.map → chunk-2GBXVPOQ.js.map} +1 -1
- package/dist/chunk-2RMBLKP5.js +581 -0
- package/dist/chunk-2RMBLKP5.js.map +1 -0
- package/dist/{chunk-2XIEWCUE.js → chunk-32B5PVTQ.js} +2 -2
- package/dist/{chunk-2XIEWCUE.js.map → chunk-32B5PVTQ.js.map} +1 -1
- package/dist/chunk-LDCZ33AC.js +3 -0
- package/dist/chunk-LDCZ33AC.js.map +1 -0
- package/dist/chunk-NSY6KU4G.js +125 -0
- package/dist/chunk-NSY6KU4G.js.map +1 -0
- package/dist/{chunk-SAHBBO3U.js → chunk-RYLZYZRF.js} +4 -580
- package/dist/chunk-RYLZYZRF.js.map +1 -0
- package/dist/{chunk-GK5KI5PB.js → chunk-S3JUCDKD.js} +62 -43
- package/dist/chunk-S3JUCDKD.js.map +1 -0
- package/dist/chunk-TYQEC24G.js +3 -0
- package/dist/chunk-TYQEC24G.js.map +1 -0
- package/dist/chunk-WWQ45RQK.js +1114 -0
- package/dist/chunk-WWQ45RQK.js.map +1 -0
- package/dist/{chunk-YICMTZS5.js → chunk-ZNGU4ZYX.js} +171 -3
- package/dist/chunk-ZNGU4ZYX.js.map +1 -0
- package/dist/config/index.d.cts +1 -1
- package/dist/config/index.d.ts +1 -1
- package/dist/evidence/index.d.cts +2 -2
- package/dist/evidence/index.d.ts +2 -2
- package/dist/evidence/index.js +2 -1
- package/dist/harvester/index.cjs +168 -1
- package/dist/harvester/index.cjs.map +1 -1
- package/dist/harvester/index.d.cts +5 -161
- package/dist/harvester/index.d.ts +5 -161
- package/dist/harvester/index.js +4 -2
- package/dist/index-CN8gei7k.d.ts +518 -0
- package/dist/{index-9rDiFuR4.d.ts → index-CxoD81QN.d.cts} +1 -1
- package/dist/{index-9rDiFuR4.d.cts → index-CxoD81QN.d.ts} +1 -1
- package/dist/index-onQDKDNo.d.cts +518 -0
- package/dist/index.cjs +1463 -39
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +11 -174
- package/dist/index.d.ts +11 -174
- package/dist/index.js +25 -10
- package/dist/index.js.map +1 -1
- package/dist/{literatureReview-DOzgm9Q2.d.ts → literatureReview-Bn2iEGRO.d.ts} +1 -1
- package/dist/{literatureReview-BwidpYJo.d.cts → literatureReview-Bvlqk4DB.d.cts} +1 -1
- package/dist/pipeline/index.cjs +59 -41
- package/dist/pipeline/index.cjs.map +1 -1
- package/dist/pipeline/index.d.cts +5 -4
- package/dist/pipeline/index.d.ts +5 -4
- package/dist/pipeline/index.js +3 -2
- package/dist/socialPulseHarvester-CN4MwrpY.d.cts +204 -0
- package/dist/socialPulseHarvester-IbdT3zD1.d.ts +204 -0
- package/dist/{webScraper-CAQjE46m.d.cts → webScraper-BVvNW4yj.d.cts} +1 -1
- package/dist/{webScraper-CXIpvyA6.d.ts → webScraper-C9pB5Rgd.d.ts} +1 -1
- package/package.json +6 -1
- package/dist/chunk-GK5KI5PB.js.map +0 -1
- package/dist/chunk-J3VCGH7Z.js +0 -3
- package/dist/chunk-SAHBBO3U.js.map +0 -1
- 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)
|
|
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:
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
3831
|
-
...
|
|
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
|
|
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
|