@thanh01.pmt/research-kit 1.2.3 → 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-P6RHBJY2.js → chunk-S3JUCDKD.js} +62 -40
- 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 -36
- 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 -38
- 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-J3VCGH7Z.js +0 -3
- package/dist/chunk-P6RHBJY2.js.map +0 -1
- 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,30 +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} Practical Foundation`,
|
|
3689
|
-
description: scrapedSnippets[0].excerpt ? scrapedSnippets[0].excerpt.slice(0, 220) : `Hands-on implementation project for ${topic}.`,
|
|
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 = scrapedSnippets.length > 0 ? domain === "hardware" || Boolean(hardware) ? [
|
|
3697
|
-
"Power supply decoupling and current sufficiency when powering sensors or actuators.",
|
|
3698
|
-
"Logic level shifting and hardware pin mapping conflicts."
|
|
3699
|
-
] : [
|
|
3700
|
-
"SDK/runtime version compatibility and local environment dependencies."
|
|
3701
|
-
] : [];
|
|
3972
|
+
const defaultExemplars = [];
|
|
3973
|
+
const defaultBottlenecks = [];
|
|
3702
3974
|
let factsheet = {
|
|
3703
3975
|
topic,
|
|
3704
3976
|
domain,
|
|
3977
|
+
evidenceBacked: false,
|
|
3705
3978
|
compatibilityMatrix: {
|
|
3706
3979
|
hardwarePlatform: hardware || void 0,
|
|
3707
3980
|
softwareEnv: software || void 0,
|
|
3708
3981
|
verifiedCompatible: true,
|
|
3709
|
-
notes:
|
|
3982
|
+
notes: []
|
|
3710
3983
|
},
|
|
3711
3984
|
ageFeasibility: {
|
|
3712
3985
|
recommendedMinAge: ageBand[0],
|
|
@@ -3716,7 +3989,7 @@ var TechnicalGroundingEngine = class {
|
|
|
3716
3989
|
},
|
|
3717
3990
|
exemplarProjects: defaultExemplars,
|
|
3718
3991
|
technicalBottlenecks: defaultBottlenecks,
|
|
3719
|
-
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 })),
|
|
3720
3993
|
markdownReport: "",
|
|
3721
3994
|
codeSnippets: preservedCodeSnippets.slice(0, 4),
|
|
3722
3995
|
pinoutTables: preservedTables.slice(0, 4),
|
|
@@ -3724,9 +3997,10 @@ var TechnicalGroundingEngine = class {
|
|
|
3724
3997
|
};
|
|
3725
3998
|
if (llm && scrapedSnippets.length > 0) {
|
|
3726
3999
|
try {
|
|
4000
|
+
const roleByDomain = domain === "hardware" ? "Hardware & Embedded Systems Curriculum Specialist" : domain === "software" ? "Software & Technology Curriculum Specialist" : "Applied Subject Matter & Curriculum Specialist";
|
|
3727
4001
|
const prompt = [
|
|
3728
|
-
`You are a
|
|
3729
|
-
`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.`,
|
|
3730
4004
|
`
|
|
3731
4005
|
Harvested Sources:
|
|
3732
4006
|
${scrapedSnippets.map((s, i) => {
|
|
@@ -3743,7 +4017,7 @@ ${c.code}
|
|
|
3743
4017
|
return parts.join("\n");
|
|
3744
4018
|
}).join("\n\n")}`,
|
|
3745
4019
|
`
|
|
3746
|
-
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:`,
|
|
3747
4021
|
`{`,
|
|
3748
4022
|
` "compatibilityVerdict": boolean,`,
|
|
3749
4023
|
` "compatibilityNotes": string[],`,
|
|
@@ -3778,10 +4052,28 @@ Synthesize a strictly valid JSON object with:`,
|
|
|
3778
4052
|
}));
|
|
3779
4053
|
}
|
|
3780
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
|
+
}
|
|
3781
4058
|
}
|
|
3782
4059
|
} catch (err) {
|
|
3783
4060
|
console.warn("[TechnicalGroundingEngine] LLM synthesis error:", err?.message || err);
|
|
3784
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
|
+
}
|
|
3785
4077
|
}
|
|
3786
4078
|
factsheet.markdownReport = this.renderMarkdownReport(factsheet);
|
|
3787
4079
|
return factsheet;
|
|
@@ -3795,23 +4087,41 @@ Synthesize a strictly valid JSON object with:`,
|
|
|
3795
4087
|
`- **Hardware:** ${fs.compatibilityMatrix.hardwarePlatform || "N/A"}`,
|
|
3796
4088
|
`- **Software / SDK:** ${fs.compatibilityMatrix.softwareEnv || "N/A"}`,
|
|
3797
4089
|
`- **Verdict:** ${fs.compatibilityMatrix.verifiedCompatible ? "\u2705 Verified Compatible" : "\u26A0\uFE0F Compatibility Warning"}`,
|
|
3798
|
-
...fs.compatibilityMatrix.notes.map((n) => ` - ${n}`)
|
|
3799
|
-
|
|
4090
|
+
...fs.compatibilityMatrix.notes.map((n) => ` - ${n}`)
|
|
4091
|
+
];
|
|
4092
|
+
if (fs.ageFeasibility.potentialBarriers.length > 0) {
|
|
4093
|
+
lines.push(
|
|
4094
|
+
`
|
|
3800
4095
|
## 2. Age Feasibility & Learner Barriers (Ages ${fs.ageFeasibility.recommendedMinAge}\u2013${fs.ageFeasibility.recommendedMaxAge})`,
|
|
3801
|
-
|
|
3802
|
-
|
|
4096
|
+
...fs.ageFeasibility.potentialBarriers.map((b) => `- \u26A0\uFE0F ${b}`)
|
|
4097
|
+
);
|
|
4098
|
+
}
|
|
4099
|
+
if (fs.exemplarProjects.length > 0) {
|
|
4100
|
+
lines.push(
|
|
4101
|
+
`
|
|
3803
4102
|
## 3. Real-World Exemplar Projects`,
|
|
3804
|
-
|
|
4103
|
+
...fs.exemplarProjects.map(
|
|
4104
|
+
(ex, idx) => `### Exemplar ${idx + 1}: ${ex.title}
|
|
3805
4105
|
- **Summary:** ${ex.description}
|
|
3806
4106
|
- **Audience:** ${ex.targetAudience}${ex.sourceUrl ? `
|
|
3807
|
-
- **Reference:** [Link](${ex.sourceUrl})` : ""}`
|
|
3808
|
-
|
|
4107
|
+
- **Reference:** [Link](${ex.sourceUrl})` : ""}`
|
|
4108
|
+
)
|
|
4109
|
+
);
|
|
4110
|
+
}
|
|
4111
|
+
if (fs.technicalBottlenecks.length > 0) {
|
|
4112
|
+
lines.push(
|
|
4113
|
+
`
|
|
3809
4114
|
## 4. Technical Bottlenecks & Pitfalls to Avoid`,
|
|
3810
|
-
|
|
3811
|
-
|
|
4115
|
+
...fs.technicalBottlenecks.map((bn) => `- \u{1F6D1} ${bn}`)
|
|
4116
|
+
);
|
|
4117
|
+
}
|
|
4118
|
+
if (fs.groundingSources.length > 0) {
|
|
4119
|
+
lines.push(
|
|
4120
|
+
`
|
|
3812
4121
|
## 5. Grounding Citations`,
|
|
3813
|
-
|
|
3814
|
-
|
|
4122
|
+
...fs.groundingSources.map((s, idx) => `${idx + 1}. [${s.title}](${s.url})`)
|
|
4123
|
+
);
|
|
4124
|
+
}
|
|
3815
4125
|
if (fs.codeSnippets && fs.codeSnippets.length > 0) {
|
|
3816
4126
|
lines.push(
|
|
3817
4127
|
`
|
|
@@ -3822,15 +4132,1114 @@ ${c.code}
|
|
|
3822
4132
|
);
|
|
3823
4133
|
}
|
|
3824
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) {
|
|
3825
5160
|
lines.push(
|
|
3826
5161
|
`
|
|
3827
|
-
##
|
|
3828
|
-
...
|
|
5162
|
+
## Extracted Code Examples`,
|
|
5163
|
+
...allCode.map((c) => `From **[${c.id}]**:
|
|
5164
|
+
\`\`\`${c.language || "text"}
|
|
5165
|
+
${c.code}
|
|
5166
|
+
\`\`\``)
|
|
3829
5167
|
);
|
|
3830
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
|
+
);
|
|
3831
5184
|
return lines.join("\n");
|
|
3832
5185
|
}
|
|
3833
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
|
+
}
|
|
3834
5243
|
|
|
3835
5244
|
// src/services/researchKitClient.ts
|
|
3836
5245
|
var KnowledgeDiscoveryService = class {
|
|
@@ -3850,11 +5259,13 @@ var KnowledgeDiscoveryService = class {
|
|
|
3850
5259
|
});
|
|
3851
5260
|
this.youtubeService = new YouTubeIngestionService();
|
|
3852
5261
|
this.stemResearcher = new StemResourceResearcher();
|
|
5262
|
+
this.socialPulseHarvester = new SocialPulseHarvester(this.searchEngine);
|
|
3853
5263
|
}
|
|
3854
5264
|
searchEngine;
|
|
3855
5265
|
webScraper;
|
|
3856
5266
|
youtubeService;
|
|
3857
5267
|
stemResearcher;
|
|
5268
|
+
socialPulseHarvester;
|
|
3858
5269
|
async search(query, limit = 5) {
|
|
3859
5270
|
return this.searchEngine.search(query, {
|
|
3860
5271
|
limit,
|
|
@@ -3874,6 +5285,9 @@ var KnowledgeDiscoveryService = class {
|
|
|
3874
5285
|
async findStemResources(query, options) {
|
|
3875
5286
|
return this.stemResearcher.findResources(query, options);
|
|
3876
5287
|
}
|
|
5288
|
+
async searchSocialPulse(topic, options) {
|
|
5289
|
+
return this.socialPulseHarvester.harvest(topic, options);
|
|
5290
|
+
}
|
|
3877
5291
|
};
|
|
3878
5292
|
var TerminologyGraphService = class {
|
|
3879
5293
|
constructor(config) {
|
|
@@ -4069,8 +5483,9 @@ var ResearchKitClient = class {
|
|
|
4069
5483
|
this.verification = new EvidenceVerificationService(config);
|
|
4070
5484
|
this.orchestrator = new PedagogicalSynthesisService(config);
|
|
4071
5485
|
this.grounding = new TechnicalGroundingService(config);
|
|
5486
|
+
this.agent = new ResearchSubAgent(config);
|
|
4072
5487
|
}
|
|
4073
|
-
/** Service 1: Multi-Engine Web Search, Scraper
|
|
5488
|
+
/** Service 1: Multi-Engine Web Search, Scraper, YouTube Transcript & 30-Day Social Pulse */
|
|
4074
5489
|
discovery;
|
|
4075
5490
|
/** Service 2: Bilingual Pedagogical Term Extraction & Prerequisite Concept Graph (DAG) */
|
|
4076
5491
|
terminology;
|
|
@@ -4082,6 +5497,8 @@ var ResearchKitClient = class {
|
|
|
4082
5497
|
orchestrator;
|
|
4083
5498
|
/** Service 6: Technical Grounding, Hardware/Software Compatibility & Empirical Exemplars */
|
|
4084
5499
|
grounding;
|
|
5500
|
+
/** Service 7: Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent (v1.3.0) */
|
|
5501
|
+
agent;
|
|
4085
5502
|
};
|
|
4086
5503
|
|
|
4087
5504
|
exports.AcademicPaperSchema = AcademicPaperSchema;
|
|
@@ -4097,6 +5514,7 @@ exports.ClaimVerifier = ClaimVerifier;
|
|
|
4097
5514
|
exports.DEFAULT_RESEARCH_CONFIG = DEFAULT_RESEARCH_CONFIG;
|
|
4098
5515
|
exports.ECOMMERCE_AND_COMMERCIAL_PATTERNS = ECOMMERCE_AND_COMMERCIAL_PATTERNS;
|
|
4099
5516
|
exports.ECOMMERCE_DOMAINS = ECOMMERCE_DOMAINS;
|
|
5517
|
+
exports.EvidenceLedger = EvidenceLedger;
|
|
4100
5518
|
exports.EvidenceScorer = EvidenceScorer;
|
|
4101
5519
|
exports.EvidenceVerificationService = EvidenceVerificationService;
|
|
4102
5520
|
exports.GitHubCurriculumClient = GitHubCurriculumClient;
|
|
@@ -4106,13 +5524,18 @@ exports.KnowledgeDiscoveryService = KnowledgeDiscoveryService;
|
|
|
4106
5524
|
exports.LiteratureReviewSynthesizer = LiteratureReviewSynthesizer;
|
|
4107
5525
|
exports.MultiSourceSearchEngine = MultiSourceSearchEngine;
|
|
4108
5526
|
exports.NasaMediaClient = NasaMediaClient;
|
|
5527
|
+
exports.OpenAlexClient = OpenAlexClient;
|
|
4109
5528
|
exports.OpenverseClient = OpenverseClient;
|
|
4110
5529
|
exports.PedagogicalSynthesisService = PedagogicalSynthesisService;
|
|
4111
5530
|
exports.PedagogicalTermExtractor = PedagogicalTermExtractor;
|
|
4112
5531
|
exports.ProvenanceTracker = ProvenanceTracker;
|
|
5532
|
+
exports.RESEARCH_PROFILE_PRESETS = RESEARCH_PROFILE_PRESETS;
|
|
4113
5533
|
exports.ReferencePackBuilder = ReferencePackBuilder;
|
|
5534
|
+
exports.ResearchAgentToolInputSchema = ResearchAgentToolInputSchema;
|
|
4114
5535
|
exports.ResearchConfigSchema = ResearchConfigSchema;
|
|
4115
5536
|
exports.ResearchKitClient = ResearchKitClient;
|
|
5537
|
+
exports.ResearchSubAgent = ResearchSubAgent;
|
|
5538
|
+
exports.SocialPulseHarvester = SocialPulseHarvester;
|
|
4116
5539
|
exports.StemResourceResearcher = StemResourceResearcher;
|
|
4117
5540
|
exports.TechnicalGroundingEngine = TechnicalGroundingEngine;
|
|
4118
5541
|
exports.TechnicalGroundingService = TechnicalGroundingService;
|
|
@@ -4120,6 +5543,8 @@ exports.TerminologyGraphService = TerminologyGraphService;
|
|
|
4120
5543
|
exports.WebScraper = WebScraper;
|
|
4121
5544
|
exports.YouTubeIngestionService = YouTubeIngestionService;
|
|
4122
5545
|
exports.classifyTechnicalDomain = classifyTechnicalDomain;
|
|
5546
|
+
exports.cleanCrossrefAbstract = cleanCrossrefAbstract;
|
|
5547
|
+
exports.createResearchAgentTool = createResearchAgentTool;
|
|
4123
5548
|
exports.evaluateTechnicalDensity = evaluateTechnicalDensity;
|
|
4124
5549
|
exports.extractSubstantiveExcerpts = extractSubstantiveExcerpts;
|
|
4125
5550
|
exports.extractTopSentences = extractTopSentences;
|
|
@@ -4132,6 +5557,8 @@ exports.kahnTopologicalSort = kahnTopologicalSort;
|
|
|
4132
5557
|
exports.mapTopicToCS2023 = mapTopicToCS2023;
|
|
4133
5558
|
exports.normalizeUrlForDedup = normalizeUrlForDedup;
|
|
4134
5559
|
exports.reconstructOpenAlexAbstract = reconstructOpenAlexAbstract;
|
|
5560
|
+
exports.resolveResearchProfile = resolveResearchProfile;
|
|
5561
|
+
exports.runResearchSubAgent = runResearchSubAgent;
|
|
4135
5562
|
exports.stitchCaptionSegments = stitchCaptionSegments;
|
|
4136
5563
|
exports.transitiveReduction = transitiveReduction;
|
|
4137
5564
|
//# sourceMappingURL=index.cjs.map
|