@thanh01.pmt/research-kit 1.2.4 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/dist/academic/index.cjs +122 -0
  2. package/dist/academic/index.cjs.map +1 -1
  3. package/dist/academic/index.d.cts +27 -4
  4. package/dist/academic/index.d.ts +27 -4
  5. package/dist/academic/index.js +2 -1
  6. package/dist/agent/index.cjs +3441 -0
  7. package/dist/agent/index.cjs.map +1 -0
  8. package/dist/agent/index.d.cts +10 -0
  9. package/dist/agent/index.d.ts +10 -0
  10. package/dist/agent/index.js +10 -0
  11. package/dist/agent/index.js.map +1 -0
  12. package/dist/{catalogBuilder-B4eiLS_S.d.cts → catalogBuilder-BBCa9jqI.d.cts} +2 -2
  13. package/dist/{catalogBuilder-BNB_gaWP.d.ts → catalogBuilder-D-UiM37y.d.ts} +2 -2
  14. package/dist/chunk-2GBXVPOQ.js +3 -0
  15. package/dist/{chunk-J3VCGH7Z.js.map → chunk-2GBXVPOQ.js.map} +1 -1
  16. package/dist/chunk-2RMBLKP5.js +581 -0
  17. package/dist/chunk-2RMBLKP5.js.map +1 -0
  18. package/dist/{chunk-2XIEWCUE.js → chunk-32B5PVTQ.js} +2 -2
  19. package/dist/{chunk-2XIEWCUE.js.map → chunk-32B5PVTQ.js.map} +1 -1
  20. package/dist/chunk-LDCZ33AC.js +3 -0
  21. package/dist/chunk-LDCZ33AC.js.map +1 -0
  22. package/dist/chunk-NSY6KU4G.js +125 -0
  23. package/dist/chunk-NSY6KU4G.js.map +1 -0
  24. package/dist/{chunk-SAHBBO3U.js → chunk-RYLZYZRF.js} +4 -580
  25. package/dist/chunk-RYLZYZRF.js.map +1 -0
  26. package/dist/{chunk-GK5KI5PB.js → chunk-S3JUCDKD.js} +62 -43
  27. package/dist/chunk-S3JUCDKD.js.map +1 -0
  28. package/dist/chunk-TYQEC24G.js +3 -0
  29. package/dist/chunk-TYQEC24G.js.map +1 -0
  30. package/dist/chunk-WWQ45RQK.js +1114 -0
  31. package/dist/chunk-WWQ45RQK.js.map +1 -0
  32. package/dist/{chunk-YICMTZS5.js → chunk-ZNGU4ZYX.js} +171 -3
  33. package/dist/chunk-ZNGU4ZYX.js.map +1 -0
  34. package/dist/config/index.d.cts +1 -1
  35. package/dist/config/index.d.ts +1 -1
  36. package/dist/evidence/index.d.cts +2 -2
  37. package/dist/evidence/index.d.ts +2 -2
  38. package/dist/evidence/index.js +2 -1
  39. package/dist/harvester/index.cjs +168 -1
  40. package/dist/harvester/index.cjs.map +1 -1
  41. package/dist/harvester/index.d.cts +5 -161
  42. package/dist/harvester/index.d.ts +5 -161
  43. package/dist/harvester/index.js +4 -2
  44. package/dist/index-CN8gei7k.d.ts +518 -0
  45. package/dist/{index-9rDiFuR4.d.ts → index-CxoD81QN.d.cts} +1 -1
  46. package/dist/{index-9rDiFuR4.d.cts → index-CxoD81QN.d.ts} +1 -1
  47. package/dist/index-onQDKDNo.d.cts +518 -0
  48. package/dist/index.cjs +1463 -39
  49. package/dist/index.cjs.map +1 -1
  50. package/dist/index.d.cts +11 -174
  51. package/dist/index.d.ts +11 -174
  52. package/dist/index.js +25 -10
  53. package/dist/index.js.map +1 -1
  54. package/dist/{literatureReview-DOzgm9Q2.d.ts → literatureReview-Bn2iEGRO.d.ts} +1 -1
  55. package/dist/{literatureReview-BwidpYJo.d.cts → literatureReview-Bvlqk4DB.d.cts} +1 -1
  56. package/dist/pipeline/index.cjs +59 -41
  57. package/dist/pipeline/index.cjs.map +1 -1
  58. package/dist/pipeline/index.d.cts +5 -4
  59. package/dist/pipeline/index.d.ts +5 -4
  60. package/dist/pipeline/index.js +3 -2
  61. package/dist/socialPulseHarvester-CN4MwrpY.d.cts +204 -0
  62. package/dist/socialPulseHarvester-IbdT3zD1.d.ts +204 -0
  63. package/dist/{webScraper-CAQjE46m.d.cts → webScraper-BVvNW4yj.d.cts} +1 -1
  64. package/dist/{webScraper-CXIpvyA6.d.ts → webScraper-C9pB5Rgd.d.ts} +1 -1
  65. package/package.json +6 -1
  66. package/dist/chunk-GK5KI5PB.js.map +0 -1
  67. package/dist/chunk-J3VCGH7Z.js +0 -3
  68. package/dist/chunk-SAHBBO3U.js.map +0 -1
  69. package/dist/chunk-YICMTZS5.js.map +0 -1
@@ -0,0 +1,3441 @@
1
+ 'use strict';
2
+
3
+ var zod = require('zod');
4
+
5
+ // src/agent/types.ts
6
+ var RESEARCH_PROFILE_PRESETS = {
7
+ fast_grounded: {
8
+ maxRounds: 2,
9
+ maxQueriesPerRound: 3,
10
+ maxScrapePerRound: 3,
11
+ timeoutMs: 35e3,
12
+ enableWeb: true,
13
+ enableAcademic: false,
14
+ enableSocialPulse: false,
15
+ enableStemOer: false
16
+ },
17
+ deep_autonomous: {
18
+ maxRounds: 3,
19
+ maxQueriesPerRound: 4,
20
+ maxScrapePerRound: 4,
21
+ timeoutMs: 12e4,
22
+ enableWeb: true,
23
+ enableAcademic: true,
24
+ enableSocialPulse: true,
25
+ enableStemOer: true
26
+ },
27
+ technical: {
28
+ maxRounds: 2,
29
+ maxQueriesPerRound: 3,
30
+ maxScrapePerRound: 4,
31
+ timeoutMs: 45e3,
32
+ enableWeb: true,
33
+ enableAcademic: false,
34
+ enableSocialPulse: true,
35
+ enableStemOer: false
36
+ },
37
+ academic: {
38
+ maxRounds: 2,
39
+ maxQueriesPerRound: 3,
40
+ maxScrapePerRound: 2,
41
+ timeoutMs: 45e3,
42
+ enableWeb: true,
43
+ enableAcademic: true,
44
+ enableSocialPulse: false,
45
+ enableStemOer: false
46
+ },
47
+ social_pulse: {
48
+ maxRounds: 2,
49
+ maxQueriesPerRound: 3,
50
+ maxScrapePerRound: 2,
51
+ timeoutMs: 35e3,
52
+ enableWeb: true,
53
+ enableAcademic: false,
54
+ enableSocialPulse: true,
55
+ enableStemOer: false
56
+ },
57
+ curriculum_oer: {
58
+ maxRounds: 2,
59
+ maxQueriesPerRound: 3,
60
+ maxScrapePerRound: 3,
61
+ timeoutMs: 45e3,
62
+ enableWeb: true,
63
+ enableAcademic: false,
64
+ enableSocialPulse: false,
65
+ enableStemOer: true
66
+ },
67
+ general: {
68
+ maxRounds: 2,
69
+ maxQueriesPerRound: 3,
70
+ maxScrapePerRound: 3,
71
+ timeoutMs: 45e3,
72
+ enableWeb: true,
73
+ enableAcademic: false,
74
+ enableSocialPulse: false,
75
+ enableStemOer: false
76
+ }
77
+ };
78
+
79
+ // src/agent/evidenceLedger.ts
80
+ function normalizeUrlKey(rawUrl) {
81
+ try {
82
+ const u = new URL(rawUrl.trim());
83
+ u.hash = "";
84
+ for (const param of ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "ref"]) {
85
+ u.searchParams.delete(param);
86
+ }
87
+ return u.toString().replace(/\/$/, "").toLowerCase();
88
+ } catch {
89
+ return rawUrl.trim().replace(/\/$/, "").toLowerCase();
90
+ }
91
+ }
92
+ var EvidenceLedger = class {
93
+ items = [];
94
+ urlIndex = /* @__PURE__ */ new Map();
95
+ idIndex = /* @__PURE__ */ new Map();
96
+ allocateId() {
97
+ const nextNum = this.items.length + 1;
98
+ return `RES-${String(nextNum).padStart(2, "0")}`;
99
+ }
100
+ /**
101
+ * Records or upgrades a ledger entry from a full `ScrapedDocument`.
102
+ */
103
+ addScrapedDocument(doc, relevanceScore, extraTakeaways = []) {
104
+ const key = normalizeUrlKey(doc.url);
105
+ const existing = this.urlIndex.get(key);
106
+ const mergedExcerpts = Array.from(
107
+ new Set([
108
+ ...extraTakeaways,
109
+ ...doc.keyExcerpts || [],
110
+ doc.markdownContent.replace(/```[\s\S]*?```/g, " ").replace(/\s+/g, " ").trim().slice(0, 450)
111
+ ].filter((e) => e && e.trim().length > 20))
112
+ ).slice(0, 6);
113
+ const sourceType = doc.fetchProvider === "youtube" ? "youtube" : "web";
114
+ if (existing) {
115
+ existing.title = doc.title || existing.title;
116
+ existing.relevanceScore = Math.max(existing.relevanceScore, relevanceScore);
117
+ existing.headings = doc.extractedHeadings?.slice(0, 8) || existing.headings;
118
+ existing.keyExcerpts = mergedExcerpts.length > 0 ? mergedExcerpts : existing.keyExcerpts;
119
+ existing.codeBlocks = (doc.extractedCodeBlocks || []).slice(0, 4);
120
+ existing.tables = (doc.extractedTables || []).slice(0, 4);
121
+ existing.rawByteSize = Math.max(existing.rawByteSize, doc.byteSize || 0);
122
+ return this.toCompactReceipt(existing);
123
+ }
124
+ const item = {
125
+ id: this.allocateId(),
126
+ sourceType,
127
+ title: doc.title || "Untitled Document",
128
+ url: doc.url,
129
+ relevanceScore: Math.max(1, Math.min(10, Math.round(relevanceScore))),
130
+ headings: (doc.extractedHeadings || []).slice(0, 8),
131
+ keyExcerpts: mergedExcerpts,
132
+ codeBlocks: (doc.extractedCodeBlocks || []).slice(0, 4),
133
+ tables: (doc.extractedTables || []).slice(0, 4),
134
+ rawByteSize: doc.byteSize || Buffer.byteLength(doc.markdownContent || "", "utf-8"),
135
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
136
+ };
137
+ this.items.push(item);
138
+ this.urlIndex.set(key, item);
139
+ this.idIndex.set(item.id, item);
140
+ return this.toCompactReceipt(item);
141
+ }
142
+ /**
143
+ * Records a lightweight search hit when full scraping is skipped or pending.
144
+ */
145
+ addSearchHit(hit, relevanceScore = 6) {
146
+ const key = normalizeUrlKey(hit.url);
147
+ const existing = this.urlIndex.get(key);
148
+ if (existing) {
149
+ return this.toCompactReceipt(existing);
150
+ }
151
+ const snippet = (hit.content || "").replace(/\s+/g, " ").trim();
152
+ const item = {
153
+ id: this.allocateId(),
154
+ sourceType: hit.engine === "academic" ? "academic" : "web",
155
+ title: hit.title || "Search Result",
156
+ url: hit.url,
157
+ relevanceScore: Math.max(1, Math.min(10, Math.round(relevanceScore))),
158
+ headings: [],
159
+ keyExcerpts: snippet ? [snippet.slice(0, 450)] : [],
160
+ codeBlocks: [],
161
+ tables: [],
162
+ rawByteSize: Buffer.byteLength(snippet, "utf-8"),
163
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
164
+ };
165
+ this.items.push(item);
166
+ this.urlIndex.set(key, item);
167
+ this.idIndex.set(item.id, item);
168
+ return this.toCompactReceipt(item);
169
+ }
170
+ /**
171
+ * Records a peer-reviewed or preprint paper from Semantic Scholar, OpenAlex, Crossref, or arXiv.
172
+ */
173
+ addAcademicPaper(paper) {
174
+ const url = paper.url || paper.pdfUrl || (paper.doi ? `https://doi.org/${paper.doi}` : `https://openalex.org/${paper.id}`);
175
+ const key = normalizeUrlKey(url);
176
+ const existing = this.urlIndex.get(key);
177
+ if (existing) {
178
+ return this.toCompactReceipt(existing);
179
+ }
180
+ const abstractOrTldr = [paper.tldr, paper.abstract].filter(Boolean).join(" \u2014 ").trim();
181
+ const citationBonus = paper.citationCount >= 50 ? 9 : paper.citationCount >= 10 ? 8 : 7;
182
+ const item = {
183
+ id: this.allocateId(),
184
+ sourceType: "academic",
185
+ title: paper.title,
186
+ url,
187
+ authorOrVenue: [paper.authors?.slice(0, 3).join(", "), paper.venue, paper.year].filter(Boolean).join(" \xB7 "),
188
+ publishedDate: paper.year ? String(paper.year) : void 0,
189
+ relevanceScore: citationBonus,
190
+ headings: paper.fieldsOfStudy || [],
191
+ keyExcerpts: abstractOrTldr ? [abstractOrTldr.slice(0, 600)] : [`Academic paper: ${paper.title}`],
192
+ codeBlocks: [],
193
+ tables: [],
194
+ rawByteSize: Buffer.byteLength(abstractOrTldr || paper.title, "utf-8"),
195
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
196
+ };
197
+ this.items.push(item);
198
+ this.urlIndex.set(key, item);
199
+ this.idIndex.set(item.id, item);
200
+ return this.toCompactReceipt(item);
201
+ }
202
+ /**
203
+ * Records a 30-day social/developer pulse signal (HackerNews, GitHub, Reddit).
204
+ */
205
+ addSocialPulseItem(pulse) {
206
+ const key = normalizeUrlKey(pulse.url);
207
+ const existing = this.urlIndex.get(key);
208
+ if (existing) {
209
+ return this.toCompactReceipt(existing);
210
+ }
211
+ const item = {
212
+ id: this.allocateId(),
213
+ sourceType: "social_pulse",
214
+ title: pulse.title,
215
+ url: pulse.url,
216
+ authorOrVenue: `${pulse.platform.toUpperCase()}${pulse.author ? ` (@${pulse.author})` : ""}`,
217
+ publishedDate: pulse.createdAt,
218
+ relevanceScore: Math.max(1, Math.min(10, pulse.engagementScore)),
219
+ headings: [pulse.platform.toUpperCase()],
220
+ keyExcerpts: [pulse.snippet.slice(0, 450)],
221
+ codeBlocks: [],
222
+ tables: [],
223
+ rawByteSize: Buffer.byteLength(pulse.snippet, "utf-8"),
224
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
225
+ };
226
+ this.items.push(item);
227
+ this.urlIndex.set(key, item);
228
+ this.idIndex.set(item.id, item);
229
+ return this.toCompactReceipt(item);
230
+ }
231
+ /**
232
+ * Records a verified STEM OER simulation/resource (PhET, OpenStax, NASA, CS Unplugged).
233
+ */
234
+ addStemResource(resource) {
235
+ const key = normalizeUrlKey(resource.url);
236
+ const existing = this.urlIndex.get(key);
237
+ if (existing) {
238
+ return this.toCompactReceipt(existing);
239
+ }
240
+ const excerpt = `${resource.description} [Provider: ${resource.provider}${resource.license ? `, License: ${resource.license}` : ""}]`;
241
+ const item = {
242
+ id: this.allocateId(),
243
+ sourceType: "stem_oer",
244
+ title: resource.title,
245
+ url: resource.url,
246
+ authorOrVenue: resource.provider,
247
+ relevanceScore: 8,
248
+ headings: [resource.provider],
249
+ keyExcerpts: [excerpt.slice(0, 450)],
250
+ codeBlocks: [],
251
+ tables: [],
252
+ rawByteSize: Buffer.byteLength(excerpt, "utf-8"),
253
+ accessedAt: (/* @__PURE__ */ new Date()).toISOString()
254
+ };
255
+ this.items.push(item);
256
+ this.urlIndex.set(key, item);
257
+ this.idIndex.set(item.id, item);
258
+ return this.toCompactReceipt(item);
259
+ }
260
+ /**
261
+ * Projects a full `LedgerItem` into a compact receipt (<= 150 tokens) for Stage A planning & gap analysis.
262
+ */
263
+ toCompactReceipt(item) {
264
+ const rawExcerpt = item.keyExcerpts[0] || item.title;
265
+ return {
266
+ id: item.id,
267
+ sourceType: item.sourceType,
268
+ title: item.title.slice(0, 140),
269
+ url: item.url,
270
+ relevanceScore: item.relevanceScore,
271
+ headings: item.headings.slice(0, 5),
272
+ codeBlockCount: item.codeBlocks.length,
273
+ tableCount: item.tables.length,
274
+ briefExcerpt: rawExcerpt.slice(0, 300)
275
+ };
276
+ }
277
+ getItems() {
278
+ return [...this.items];
279
+ }
280
+ getApprovedItems(minScore = 6) {
281
+ return this.items.filter((i) => i.relevanceScore >= minScore);
282
+ }
283
+ getReceipts() {
284
+ return this.items.map((i) => this.toCompactReceipt(i));
285
+ }
286
+ getById(id) {
287
+ return this.idIndex.get(id.toUpperCase());
288
+ }
289
+ getTotalCodeBlocks() {
290
+ return this.items.reduce((sum, i) => sum + i.codeBlocks.length, 0);
291
+ }
292
+ getTotalTables() {
293
+ return this.items.reduce((sum, i) => sum + i.tables.length, 0);
294
+ }
295
+ /**
296
+ * Formats the top verified items with `[RES-xx]` tags, substantive excerpts, code blocks,
297
+ * and tables for Stage B Contract Synthesis.
298
+ */
299
+ buildSynthesisCorpus(maxItems = 12) {
300
+ const sorted = [...this.items].sort((a, b) => b.relevanceScore - a.relevanceScore).slice(0, maxItems);
301
+ if (sorted.length === 0) {
302
+ return "No verified sources recorded in EvidenceLedger.";
303
+ }
304
+ return sorted.map((item) => {
305
+ const parts = [
306
+ `[${item.id}] (${item.sourceType.toUpperCase()} \xB7 Score ${item.relevanceScore}/10) Title: ${item.title}`,
307
+ `URL: ${item.url}`
308
+ ];
309
+ if (item.authorOrVenue) {
310
+ parts.push(`Source/Author: ${item.authorOrVenue}`);
311
+ }
312
+ if (item.headings.length > 0) {
313
+ parts.push(`Sections: ${item.headings.join(" | ")}`);
314
+ }
315
+ if (item.keyExcerpts.length > 0) {
316
+ parts.push(`Verified Excerpts:
317
+ ${item.keyExcerpts.map((e) => `- ${e}`).join("\n")}`);
318
+ }
319
+ if (item.codeBlocks.length > 0) {
320
+ parts.push(
321
+ `Extracted Code Blocks:
322
+ ` + item.codeBlocks.slice(0, 2).map((cb) => `\`\`\`${cb.language || "text"}
323
+ ${cb.code.slice(0, 600)}
324
+ \`\`\``).join("\n")
325
+ );
326
+ }
327
+ if (item.tables.length > 0) {
328
+ parts.push(`Extracted Tables:
329
+ ${item.tables.slice(0, 2).join("\n\n")}`);
330
+ }
331
+ return parts.join("\n");
332
+ }).join("\n\n---\n\n");
333
+ }
334
+ /**
335
+ * Returns concatenated plain text of all ledger items for deterministic/LLM `ClaimVerifier` checks.
336
+ */
337
+ buildFullRawCorpus() {
338
+ return this.items.map(
339
+ (i) => `${i.title}
340
+ ${i.keyExcerpts.join("\n")}
341
+ ${i.codeBlocks.map((c) => c.code).join("\n")}
342
+ ${i.tables.join("\n")}`
343
+ ).join("\n\n");
344
+ }
345
+ /**
346
+ * Scans any synthesized report or JSON string for `[RES-xx]` citation markers
347
+ * and verifies every marker against the ledger.
348
+ */
349
+ verifyCitationTags(synthesizedText) {
350
+ const matches = [...synthesizedText.matchAll(/\[?(RES-\d{2,3})\]?/gi)];
351
+ const validSet = /* @__PURE__ */ new Set();
352
+ const invalidSet = /* @__PURE__ */ new Set();
353
+ for (const m of matches) {
354
+ const tag = m[1].toUpperCase();
355
+ if (this.idIndex.has(tag)) {
356
+ validSet.add(tag);
357
+ } else {
358
+ invalidSet.add(tag);
359
+ }
360
+ }
361
+ return {
362
+ validCitationIds: Array.from(validSet),
363
+ invalidCitationIds: Array.from(invalidSet)
364
+ };
365
+ }
366
+ /**
367
+ * Maps ledger items into `ProvenanceRecord[]` for `ProvenanceTracker`.
368
+ */
369
+ toProvenanceRecords(defaultDomain = "general") {
370
+ return this.items.map((item) => ({
371
+ resourceId: item.id,
372
+ sourceUrl: item.url,
373
+ accessedAt: item.accessedAt,
374
+ domain: item.sourceType || defaultDomain,
375
+ relevanceScore: item.relevanceScore,
376
+ byteSize: item.rawByteSize
377
+ }));
378
+ }
379
+ };
380
+
381
+ // src/academic/arxivClient.ts
382
+ var ArXivSearchEngine = class {
383
+ /**
384
+ * Search ArXiv repository using the public atom XML API
385
+ */
386
+ async search(query, maxResults = 5) {
387
+ const papers = [];
388
+ try {
389
+ const url = `https://export.arxiv.org/api/query?search_query=all:${encodeURIComponent(query)}&start=0&max_results=${maxResults}&sortBy=relevance&sortOrder=descending`;
390
+ const res = await fetch(url, { signal: AbortSignal.timeout(1e4) });
391
+ if (res.ok) {
392
+ const xmlText = await res.text();
393
+ const entryMatches = xmlText.match(/<entry>[\s\S]*?<\/entry>/g) || [];
394
+ for (const entry of entryMatches) {
395
+ const idMatch = entry.match(/<id>([\s\S]*?)<\/id>/);
396
+ const titleMatch = entry.match(/<title>([\s\S]*?)<\/title>/);
397
+ const summaryMatch = entry.match(/<summary>([\s\S]*?)<\/summary>/);
398
+ const publishedMatch = entry.match(/<published>(\d{4})/);
399
+ const authorMatches = [...entry.matchAll(/<author>\s*<name>([\s\S]*?)<\/name>/g)].map((m) => m[1]?.trim()).filter(Boolean);
400
+ const arxivUrl = idMatch ? idMatch[1]?.trim() : "";
401
+ const pdfUrl = arxivUrl ? arxivUrl.replace("/abs/", "/pdf/") + ".pdf" : void 0;
402
+ if (titleMatch) {
403
+ papers.push({
404
+ id: arxivUrl || `arxiv-${Math.random().toString(36).substring(7)}`,
405
+ title: titleMatch[1]?.trim().replace(/\s+/g, " ") || "Untitled ArXiv Paper",
406
+ abstract: summaryMatch ? summaryMatch[1]?.trim().replace(/\s+/g, " ") : "",
407
+ authors: authorMatches,
408
+ year: publishedMatch ? parseInt(publishedMatch[1], 10) : (/* @__PURE__ */ new Date()).getFullYear(),
409
+ citationCount: 0,
410
+ venue: "arXiv preprint",
411
+ url: arxivUrl,
412
+ pdfUrl,
413
+ fieldsOfStudy: ["Computer Science", "AI & Machine Learning"]
414
+ });
415
+ }
416
+ }
417
+ }
418
+ } catch (e) {
419
+ console.warn("[ArXivSearchEngine] ArXiv search failed:", e?.message || e);
420
+ }
421
+ return papers;
422
+ }
423
+ };
424
+
425
+ // src/academic/semanticScholar.ts
426
+ zod.z.object({
427
+ id: zod.z.string(),
428
+ title: zod.z.string(),
429
+ abstract: zod.z.string().optional(),
430
+ authors: zod.z.array(zod.z.string()).default([]),
431
+ year: zod.z.number().optional(),
432
+ citationCount: zod.z.number().default(0),
433
+ venue: zod.z.string().optional(),
434
+ doi: zod.z.string().optional(),
435
+ url: zod.z.string().optional(),
436
+ pdfUrl: zod.z.string().optional(),
437
+ tldr: zod.z.string().optional(),
438
+ fieldsOfStudy: zod.z.array(zod.z.string()).default([])
439
+ });
440
+ function reconstructOpenAlexAbstract(invertedIndex) {
441
+ if (!invertedIndex || typeof invertedIndex !== "object") return void 0;
442
+ const entries = Object.entries(invertedIndex);
443
+ if (entries.length === 0) return void 0;
444
+ let maxIndex = 0;
445
+ for (const [, positions] of entries) {
446
+ if (Array.isArray(positions)) {
447
+ for (const p of positions) {
448
+ if (typeof p === "number" && p > maxIndex) maxIndex = p;
449
+ }
450
+ }
451
+ }
452
+ if (maxIndex > 5e3) maxIndex = 5e3;
453
+ const words = new Array(maxIndex + 1);
454
+ for (const [word, positions] of entries) {
455
+ if (Array.isArray(positions)) {
456
+ for (const p of positions) {
457
+ if (typeof p === "number" && p >= 0 && p <= maxIndex) {
458
+ words[p] = word;
459
+ }
460
+ }
461
+ }
462
+ }
463
+ const reconstructed = words.filter(Boolean).join(" ").trim();
464
+ return reconstructed.length > 0 ? reconstructed : void 0;
465
+ }
466
+ var AcademicSearchEngine = class {
467
+ apiKey;
468
+ allowEnvFallback;
469
+ customAdapter;
470
+ arxivEngine;
471
+ constructor(options = {}) {
472
+ this.arxivEngine = new ArXivSearchEngine();
473
+ if (typeof options === "string") {
474
+ this.apiKey = options;
475
+ this.allowEnvFallback = true;
476
+ } else {
477
+ this.allowEnvFallback = options.allowEnvFallback ?? true;
478
+ this.apiKey = options.apiKey || (this.allowEnvFallback ? process.env.SEMANTIC_SCHOLAR_API_KEY : void 0);
479
+ this.customAdapter = options.customAdapter;
480
+ }
481
+ }
482
+ setCustomAdapter(adapter) {
483
+ this.customAdapter = adapter;
484
+ }
485
+ setApiKey(apiKey) {
486
+ this.apiKey = apiKey;
487
+ }
488
+ /**
489
+ * Search academic papers across Semantic Scholar with OpenAlex and ArXiv fallback or Custom Adapter
490
+ */
491
+ async searchPapers(query, options = {}) {
492
+ const adapter = options.customAdapter || this.customAdapter;
493
+ if (adapter) {
494
+ try {
495
+ const customPapers = await adapter.searchPapers(query, { limit: options.limit, yearRange: options.yearRange });
496
+ if (Array.isArray(customPapers) && customPapers.length > 0) {
497
+ return customPapers;
498
+ }
499
+ } catch (e) {
500
+ console.warn("[AcademicSearchEngine] Custom academic adapter failed:", e?.message || e);
501
+ }
502
+ }
503
+ const limit = options.limit ?? 5;
504
+ const papers = [];
505
+ const seenTitles = /* @__PURE__ */ new Set();
506
+ const pushUnique = (p) => {
507
+ const normTitle = p.title.toLowerCase().replace(/[^a-z0-9\u00C0-\u1EF9]+/g, "");
508
+ if (!normTitle || seenTitles.has(normTitle)) return;
509
+ seenTitles.add(normTitle);
510
+ papers.push(p);
511
+ };
512
+ try {
513
+ const apiKey = options.apiKey || this.apiKey;
514
+ const headers = { "Content-Type": "application/json" };
515
+ if (apiKey) {
516
+ headers["x-api-key"] = apiKey;
517
+ }
518
+ const params = new URLSearchParams({
519
+ query,
520
+ limit: limit.toString(),
521
+ fields: "paperId,title,abstract,authors,year,citationCount,venue,externalIds,url,openAccessPdf,tldr,fieldsOfStudy"
522
+ });
523
+ if (options.yearRange) {
524
+ params.append("year", options.yearRange);
525
+ }
526
+ const res = await fetch(`https://api.semanticscholar.org/graph/v1/paper/search?${params.toString()}`, {
527
+ headers,
528
+ signal: AbortSignal.timeout(6e3)
529
+ });
530
+ if (res.ok) {
531
+ const data = await res.json();
532
+ if (Array.isArray(data?.data)) {
533
+ for (const item of data.data) {
534
+ pushUnique({
535
+ id: item.paperId || `s2-${Math.random().toString(36).slice(2, 8)}`,
536
+ title: item.title || "Untitled",
537
+ abstract: item.abstract || void 0,
538
+ authors: Array.isArray(item.authors) ? item.authors.map((a) => a.name).filter(Boolean) : [],
539
+ year: item.year,
540
+ citationCount: item.citationCount || 0,
541
+ venue: item.venue || void 0,
542
+ doi: item.externalIds?.DOI,
543
+ url: item.url || (item.externalIds?.DOI ? `https://doi.org/${item.externalIds.DOI}` : void 0),
544
+ pdfUrl: item.openAccessPdf?.url,
545
+ tldr: item.tldr?.text,
546
+ fieldsOfStudy: Array.isArray(item.fieldsOfStudy) && item.fieldsOfStudy.length > 0 ? item.fieldsOfStudy : ["Computer Science"]
547
+ });
548
+ }
549
+ if (papers.length >= limit) return papers.slice(0, limit);
550
+ }
551
+ }
552
+ } catch (e) {
553
+ console.warn("[AcademicSearchEngine] Semantic Scholar failed:", e?.message || e);
554
+ }
555
+ if (papers.length < limit) {
556
+ try {
557
+ const res = await fetch(`https://api.openalex.org/works?search=${encodeURIComponent(query)}&per-page=${limit}`, {
558
+ headers: { "User-Agent": "OrchableComposer/1.0 (mailto:team@orchable.app)" },
559
+ signal: AbortSignal.timeout(6e3)
560
+ });
561
+ if (res.ok) {
562
+ const data = await res.json();
563
+ if (Array.isArray(data?.results)) {
564
+ for (const item of data.results) {
565
+ const abstractText = reconstructOpenAlexAbstract(item.abstract_inverted_index);
566
+ const concepts = Array.isArray(item.concepts) ? item.concepts.slice(0, 3).map((c) => c.display_name).filter(Boolean) : ["Computer Science"];
567
+ pushUnique({
568
+ id: item.id || `oa-${Math.random().toString(36).slice(2, 8)}`,
569
+ title: item.title || "Untitled",
570
+ abstract: abstractText,
571
+ authors: Array.isArray(item.authorships) ? item.authorships.map((a) => a.author?.display_name).filter(Boolean) : [],
572
+ year: item.publication_year,
573
+ citationCount: item.cited_by_count || 0,
574
+ venue: item.primary_location?.source?.display_name,
575
+ doi: item.doi ? String(item.doi).replace(/^https?:\/\/doi\.org\//i, "") : void 0,
576
+ url: item.doi || item.id,
577
+ pdfUrl: item.open_access?.oa_url,
578
+ fieldsOfStudy: concepts.length > 0 ? concepts : ["Computer Science"]
579
+ });
580
+ }
581
+ }
582
+ }
583
+ } catch (e) {
584
+ console.warn("[AcademicSearchEngine] OpenAlex failed:", e?.message || e);
585
+ }
586
+ }
587
+ if (papers.length < limit && options.includeArxivFallback !== false) {
588
+ try {
589
+ const arxivPapers = await this.arxivEngine.search(query, limit - papers.length);
590
+ for (const p of arxivPapers) {
591
+ pushUnique(p);
592
+ }
593
+ } catch (e) {
594
+ console.warn("[AcademicSearchEngine] ArXiv fallback failed:", e?.message || e);
595
+ }
596
+ }
597
+ return papers.slice(0, limit);
598
+ }
599
+ };
600
+
601
+ // src/academic/openAlexClient.ts
602
+ function cleanCrossrefAbstract(rawAbstract) {
603
+ if (!rawAbstract || typeof rawAbstract !== "string") return void 0;
604
+ const cleaned = rawAbstract.replace(/<\/?jats:[^>]+>/gi, " ").replace(/<\/?[^>]+>/g, " ").replace(/\s+/g, " ").trim();
605
+ return cleaned.length > 0 ? cleaned : void 0;
606
+ }
607
+ var OpenAlexClient = class {
608
+ mailto;
609
+ constructor(options = {}) {
610
+ this.mailto = options.mailto || "team@orchable.app";
611
+ }
612
+ async searchWorks(query, options = {}) {
613
+ const limit = options.limit ?? 5;
614
+ const papers = [];
615
+ const seenTitles = /* @__PURE__ */ new Set();
616
+ const pushUnique = (paper) => {
617
+ const norm = paper.title.toLowerCase().replace(/[^a-z0-9\u00C0-\u1EF9]+/g, "");
618
+ if (!norm || seenTitles.has(norm)) return;
619
+ seenTitles.add(norm);
620
+ papers.push(paper);
621
+ };
622
+ try {
623
+ const filters = [];
624
+ if (options.yearRange) {
625
+ const match = options.yearRange.match(/^(\d{4})-(\d{4})$/);
626
+ if (match) {
627
+ filters.push(`publication_year:${match[1]}-${match[2]}`);
628
+ } else if (/^\d{4}$/.test(options.yearRange)) {
629
+ filters.push(`publication_year:${options.yearRange}`);
630
+ }
631
+ }
632
+ if (options.openAccessOnly) {
633
+ filters.push("is_oa:true");
634
+ }
635
+ const params = new URLSearchParams({
636
+ search: query,
637
+ "per-page": String(limit)
638
+ });
639
+ if (filters.length > 0) {
640
+ params.set("filter", filters.join(","));
641
+ }
642
+ const res = await fetch(`https://api.openalex.org/works?${params.toString()}`, {
643
+ headers: {
644
+ "User-Agent": `OrchableResearchKit/1.3 (mailto:${this.mailto})`
645
+ },
646
+ signal: AbortSignal.timeout(7e3)
647
+ });
648
+ if (res.ok) {
649
+ const data = await res.json();
650
+ if (Array.isArray(data?.results)) {
651
+ for (const item of data.results) {
652
+ const abstractText = reconstructOpenAlexAbstract(item.abstract_inverted_index);
653
+ const concepts = Array.isArray(item.concepts) ? item.concepts.slice(0, 4).map((c) => c.display_name).filter(Boolean) : ["Computer Science"];
654
+ const cleanDoi = item.doi ? String(item.doi).replace(/^https?:\/\/doi\.org\//i, "") : void 0;
655
+ pushUnique({
656
+ id: item.id || `oa-${Math.random().toString(36).slice(2, 8)}`,
657
+ title: item.title || item.display_name || "Untitled",
658
+ abstract: abstractText,
659
+ authors: Array.isArray(item.authorships) ? item.authorships.map((a) => a.author?.display_name).filter(Boolean) : [],
660
+ year: item.publication_year,
661
+ citationCount: item.cited_by_count || 0,
662
+ venue: item.primary_location?.source?.display_name || void 0,
663
+ doi: cleanDoi,
664
+ url: item.doi || item.primary_location?.landing_page_url || item.id,
665
+ pdfUrl: item.open_access?.oa_url || item.primary_location?.pdf_url || void 0,
666
+ fieldsOfStudy: concepts.length > 0 ? concepts : ["Computer Science"]
667
+ });
668
+ }
669
+ }
670
+ }
671
+ } catch (e) {
672
+ console.warn("[OpenAlexClient] OpenAlex request failed:", e?.message || e);
673
+ }
674
+ if (papers.length < limit && options.includeCrossrefFallback !== false) {
675
+ try {
676
+ const remaining = limit - papers.length;
677
+ const params = new URLSearchParams({
678
+ query,
679
+ rows: String(remaining),
680
+ mailto: this.mailto
681
+ });
682
+ const res = await fetch(`https://api.crossref.org/works?${params.toString()}`, {
683
+ headers: {
684
+ "User-Agent": `OrchableResearchKit/1.3 (mailto:${this.mailto})`
685
+ },
686
+ signal: AbortSignal.timeout(7e3)
687
+ });
688
+ if (res.ok) {
689
+ const data = await res.json();
690
+ const items = data?.message?.items;
691
+ if (Array.isArray(items)) {
692
+ for (const item of items) {
693
+ const title = Array.isArray(item.title) ? item.title[0] : item.title;
694
+ if (!title) continue;
695
+ const year = item.published?.["date-parts"]?.[0]?.[0] || item["published-print"]?.["date-parts"]?.[0]?.[0] || item["published-online"]?.["date-parts"]?.[0]?.[0];
696
+ const authors = Array.isArray(item.author) ? item.author.map((a) => [a.given, a.family].filter(Boolean).join(" ").trim()).filter(Boolean) : [];
697
+ const doi = item.DOI ? String(item.DOI) : void 0;
698
+ pushUnique({
699
+ id: doi ? `crossref-${doi}` : `cr-${Math.random().toString(36).slice(2, 8)}`,
700
+ title: String(title),
701
+ abstract: cleanCrossrefAbstract(item.abstract),
702
+ authors,
703
+ year: typeof year === "number" ? year : void 0,
704
+ citationCount: Number(item["is-referenced-by-count"]) || 0,
705
+ venue: Array.isArray(item["container-title"]) ? item["container-title"][0] : void 0,
706
+ doi,
707
+ url: item.URL || (doi ? `https://doi.org/${doi}` : void 0),
708
+ fieldsOfStudy: Array.isArray(item.subject) && item.subject.length > 0 ? item.subject.slice(0, 3) : ["Academic"]
709
+ });
710
+ }
711
+ }
712
+ }
713
+ } catch (e) {
714
+ console.warn("[OpenAlexClient] Crossref fallback failed:", e?.message || e);
715
+ }
716
+ }
717
+ return papers.slice(0, limit);
718
+ }
719
+ };
720
+
721
+ // src/evidence/claimVerifier.ts
722
+ var CLAIM_STOPWORDS = /* @__PURE__ */ new Set([
723
+ "the",
724
+ "and",
725
+ "for",
726
+ "with",
727
+ "that",
728
+ "this",
729
+ "from",
730
+ "into",
731
+ "are",
732
+ "was",
733
+ "were",
734
+ "have",
735
+ "has",
736
+ "will",
737
+ "would",
738
+ "through",
739
+ "their",
740
+ "these",
741
+ "those",
742
+ "which",
743
+ "while",
744
+ "c\u1EE7a",
745
+ "trong",
746
+ "\u0111\u01B0\u1EE3c",
747
+ "nh\u1EEFng",
748
+ "c\xE1c",
749
+ "cho",
750
+ "v\u1EDBi",
751
+ "v\xE0",
752
+ "ho\u1EB7c",
753
+ "\u0111\u1EC3",
754
+ "t\u1EEB",
755
+ "\u0111\u1EBFn",
756
+ "v\u1EC1",
757
+ "n\xE0y",
758
+ "\u0111\xF3",
759
+ "m\u1ED9t",
760
+ "nh\u01B0",
761
+ "s\u1EBD",
762
+ "\u0111ang",
763
+ "\u0111\xE3",
764
+ "ra",
765
+ "v\xE0o",
766
+ "l\xE0"
767
+ ]);
768
+ function extractSignificantTokens(text) {
769
+ return text.normalize("NFC").toLowerCase().replace(/[.,;:!?()[\]{}"“”‘’/\\|`*_~#-]+/g, " ").split(/\s+/).filter((w) => w.length >= 3 && !CLAIM_STOPWORDS.has(w));
770
+ }
771
+ function tokenMatchesCorpus(token, lowerCorpus) {
772
+ if (lowerCorpus.includes(token)) return true;
773
+ if (token.length >= 6) {
774
+ const stem = token.replace(/(?:ing|tion|ions|ment|ments|ed|es|s)$/, "");
775
+ if (stem.length >= 4 && lowerCorpus.includes(stem)) return true;
776
+ }
777
+ return false;
778
+ }
779
+ var ClaimVerifier = class {
780
+ /**
781
+ * Deterministic lexical match baseline.
782
+ * Explicitly marks verdict as 'lexical_match_only' to prevent false sense of semantic verification.
783
+ */
784
+ verifyClaimsDeterministic(claims, sourceCorpus) {
785
+ const verifiedList = [];
786
+ const normCorpus = sourceCorpus.normalize("NFC");
787
+ const lowerCorpus = normCorpus.toLowerCase();
788
+ const corpusSentences = normCorpus.split(/(?<=[.!?。\n])\s+/).map((s) => s.replace(/^[-*•#>\s]+/, "").replace(/\s+/g, " ").trim()).filter((s) => {
789
+ if (s.length < 25) return false;
790
+ if (/^(title:|url source:|final url:|http|!\[)/i.test(s)) return false;
791
+ return true;
792
+ });
793
+ for (const claim of claims) {
794
+ const claimTokens = extractSignificantTokens(claim);
795
+ const matchCount = claimTokens.filter((t) => tokenMatchesCorpus(t, lowerCorpus)).length;
796
+ const matchRatio = claimTokens.length > 0 ? matchCount / claimTokens.length : 0;
797
+ let bestQuote;
798
+ let bestSentenceRatio = 0;
799
+ for (const sent of corpusSentences) {
800
+ const lowerSent = sent.toLowerCase();
801
+ const sentMatches = claimTokens.filter((t) => tokenMatchesCorpus(t, lowerSent)).length;
802
+ const sentRatio = claimTokens.length > 0 ? sentMatches / claimTokens.length : 0;
803
+ if (sentRatio > bestSentenceRatio) {
804
+ bestSentenceRatio = sentRatio;
805
+ bestQuote = sent.slice(0, 240);
806
+ }
807
+ }
808
+ const effectiveRatio = Math.max(matchRatio, bestSentenceRatio);
809
+ const hasLexicalEvidence = effectiveRatio >= 0.55;
810
+ verifiedList.push({
811
+ claimText: claim,
812
+ verdict: "lexical_match_only",
813
+ isSupported: hasLexicalEvidence,
814
+ isLlmVerified: false,
815
+ confidenceScore: Math.round(effectiveRatio * 100),
816
+ extractedQuote: hasLexicalEvidence ? bestQuote : void 0,
817
+ explanation: hasLexicalEvidence ? `Lexical token match found (${Math.round(effectiveRatio * 100)}% token overlap). Semantic entailment requires LLM verification.` : `Insufficient lexical overlap in harvest corpus (${Math.round(effectiveRatio * 100)}%).`
818
+ });
819
+ }
820
+ const supportedCount = verifiedList.filter((c) => c.isSupported).length;
821
+ const supportPct = claims.length > 0 ? supportedCount / claims.length * 100 : 100;
822
+ const hallucinationRisk = supportPct >= 80 ? "low" : supportPct >= 50 ? "medium" : "high";
823
+ const mdLines = [
824
+ `# \u{1F50D} Claim-Support Sweep & Verification Report (Lexical Scan Mode)`,
825
+ `> **Notice:** *Scored via deterministic lexical token matching. True semantic entailment requires an LLM call.*`,
826
+ `> **Lexical Coverage:** \`${supportPct.toFixed(1)}%\` (${supportedCount}/${claims.length} claims with token matches) | **Hallucination Risk (Lexical):** \`${hallucinationRisk.toUpperCase()}\``,
827
+ `
828
+ | Pedagogical / Technical Claim | Evidence Status | Token Match | Supporting Quote | Semantic Status |`,
829
+ `|---|---|---|---|---|`,
830
+ ...verifiedList.map(
831
+ (c) => `| ${c.claimText.replace(/\|/g, "/")} | ${c.isSupported ? "\u{1F7E1} **LEXICAL MATCH**" : "\u26A0\uFE0F *UNVERIFIED / GAP*"} | \`${c.confidenceScore}%\` | ${(c.extractedQuote || "\u2014").replace(/\|/g, "/")} | *Awaiting LLM Entailment* |`
832
+ )
833
+ ];
834
+ return {
835
+ totalClaimsChecked: claims.length,
836
+ supportedClaimsCount: supportedCount,
837
+ refutedClaimsCount: 0,
838
+ unverifiedClaimsCount: claims.length - supportedCount,
839
+ hallucinationRisk,
840
+ isLlmVerified: false,
841
+ claims: verifiedList,
842
+ reportMd: mdLines.join("\n")
843
+ };
844
+ }
845
+ /**
846
+ * Primary verification interface.
847
+ * If an LLM callback is provided, performs genuine Semantic Entailment (NLI).
848
+ * Otherwise falls back to deterministic lexical retrieval with honest labeling.
849
+ */
850
+ async verifyClaims(claims, sourceCorpus, options = {}) {
851
+ const detReport = this.verifyClaimsDeterministic(claims, sourceCorpus);
852
+ if (!options.llm || claims.length === 0) {
853
+ return detReport;
854
+ }
855
+ try {
856
+ const normCorpus = sourceCorpus.normalize("NFC");
857
+ const cleanSubstantiveText = normCorpus.replace(/```[\s\S]*?```/g, "\n").split("\n").filter((l) => !/^(title:|url source:|final url:|http|!\[|#)/i.test(l.trim())).join("\n").trim();
858
+ const corpusSentences = cleanSubstantiveText.split(/(?<=[.!?。\n])\s+/).map((s) => s.replace(/^[-*•#>\s]+/, "").replace(/\s+/g, " ").trim()).filter((s) => s.length >= 25 && !/^(cookie|privacy|sign in|all rights reserved)/i.test(s));
859
+ const fallbackExcerpts = corpusSentences.slice(0, 8).join("\n");
860
+ const claimContexts = claims.map((claim, idx) => {
861
+ const tokens = extractSignificantTokens(claim);
862
+ const topSentences = corpusSentences.map((sent) => ({
863
+ sent,
864
+ overlap: tokens.filter((t) => tokenMatchesCorpus(t, sent.toLowerCase())).length
865
+ })).filter((item) => item.overlap > 0).sort((a, b) => b.overlap - a.overlap).slice(0, 5).map((item) => item.sent);
866
+ const candidates = topSentences.length > 0 ? `${topSentences.join("\n")}
867
+
868
+ [General Reference Excerpts]:
869
+ ${fallbackExcerpts}` : fallbackExcerpts || "No substantive text found.";
870
+ return {
871
+ idx,
872
+ claim,
873
+ candidatePassages: candidates
874
+ };
875
+ });
876
+ const prompt = [
877
+ `You are a Rigorous Scientific & Pedagogical Fact-Checking System (Natural Language Inference).`,
878
+ `Evaluate whether each technical/pedagogical claim is strictly SUPPORTED, directly REFUTED, or has NOT_ENOUGH_EVIDENCE in the harvested technical reference text.`,
879
+ `Pay careful attention to NEGATION words ("kh\xF4ng", "never", "tr\xE1nh", "do not"), causal relationships, hardware pin constraints, and edge cases. Do not assume truth without textual evidence.`,
880
+ `
881
+ Harvested Reference Excerpts for Claims:
882
+ `,
883
+ claimContexts.map((c) => `[Claim ${c.idx + 1}]: "${c.claim}"
884
+ [Passage Candidates]: ${c.candidatePassages}`).join("\n\n"),
885
+ `
886
+ Return ONLY a valid JSON array of objects with the exact structure:`,
887
+ `[{"claimIndex": 1, "verdict": "supported"|"refuted"|"not_enough_evidence", "confidenceScore": 95, "extractedQuote": "exact quote from passage", "explanation": "1-sentence semantic reason"}]`
888
+ ].join("\n");
889
+ const raw = await options.llm(prompt, {
890
+ system: "You are an exacting academic fact-checker. Output strictly valid JSON array without commentary.",
891
+ temperature: 0.1,
892
+ jsonMode: true
893
+ });
894
+ let parsed = [];
895
+ const arrayMatch = raw.match(/\[[\s\S]*\]/);
896
+ if (arrayMatch) {
897
+ try {
898
+ const res = JSON.parse(arrayMatch[0]);
899
+ if (Array.isArray(res)) parsed = res;
900
+ } catch {
901
+ }
902
+ }
903
+ if (parsed.length === 0) {
904
+ const objMatch = raw.match(/\{[\s\S]*\}/);
905
+ if (objMatch) {
906
+ try {
907
+ const obj = JSON.parse(objMatch[0]);
908
+ const candidateList = obj.claims || obj.results || obj.verifications || Object.values(obj).find(Array.isArray);
909
+ if (Array.isArray(candidateList)) parsed = candidateList;
910
+ } catch {
911
+ }
912
+ }
913
+ }
914
+ if (parsed.length > 0) {
915
+ const verifiedList = claims.map((claim, idx) => {
916
+ const item = parsed.find((p) => p.claimIndex === idx + 1) || parsed[idx];
917
+ const verdict = item && ["supported", "refuted", "not_enough_evidence"].includes(item.verdict) ? item.verdict : detReport.claims[idx]?.isSupported ? "supported" : "not_enough_evidence";
918
+ const isSupported = verdict === "supported";
919
+ return {
920
+ claimText: claim,
921
+ verdict,
922
+ isSupported,
923
+ isLlmVerified: true,
924
+ confidenceScore: Number(item?.confidenceScore) || (isSupported ? 90 : 30),
925
+ extractedQuote: item?.extractedQuote || detReport.claims[idx]?.extractedQuote,
926
+ explanation: item?.explanation || (isSupported ? "Semantically entailed by reference corpus." : "Not verified.")
927
+ };
928
+ });
929
+ const supportedCount = verifiedList.filter((c) => c.verdict === "supported").length;
930
+ const refutedCount = verifiedList.filter((c) => c.verdict === "refuted").length;
931
+ const unverifiedCount = claims.length - supportedCount;
932
+ const supportPct = claims.length > 0 ? supportedCount / claims.length * 100 : 100;
933
+ const hallucinationRisk = refutedCount > 0 ? "high" : supportPct >= 75 ? "low" : "medium";
934
+ const mdLines = [
935
+ `# \u{1F50D} Claim-Support Sweep & Semantic Verification Report (LLM NLI Evaluated)`,
936
+ `> **Semantic Verification Rate:** \`${supportPct.toFixed(1)}%\` (${supportedCount}/${claims.length} claims supported) | **Refuted / Contradictions:** \`${refutedCount}\` | **Hallucination Risk:** \`${hallucinationRisk.toUpperCase()}\``,
937
+ `
938
+ | Pedagogical / Technical Claim | Semantic Verdict | Confidence | Supporting Quote / Evidence | Explanation |`,
939
+ `|---|---|---|---|---|`,
940
+ ...verifiedList.map(
941
+ (c) => `| ${c.claimText.replace(/\|/g, "/")} | ${c.verdict === "supported" ? "\u2705 **SUPPORTED**" : c.verdict === "refuted" ? "\u274C **REFUTED**" : "\u26A0\uFE0F *NOT ENOUGH EVIDENCE*"} | \`${c.confidenceScore}%\` | ${(c.extractedQuote || "\u2014").replace(/\|/g, "/")} | ${(c.explanation || "").replace(/\|/g, "/")} |`
942
+ )
943
+ ];
944
+ return {
945
+ totalClaimsChecked: claims.length,
946
+ supportedClaimsCount: supportedCount,
947
+ refutedClaimsCount: refutedCount,
948
+ unverifiedClaimsCount: unverifiedCount,
949
+ hallucinationRisk,
950
+ isLlmVerified: true,
951
+ claims: verifiedList,
952
+ reportMd: mdLines.join("\n")
953
+ };
954
+ }
955
+ } catch (e) {
956
+ console.warn("[ClaimVerifier] LLM semantic verification failed, falling back to deterministic lexical report:", e?.message || e);
957
+ }
958
+ return detReport;
959
+ }
960
+ };
961
+
962
+ // src/harvester/youtubeTranscript.ts
963
+ var SPONSOR_NOISE_PATTERNS = [
964
+ /\b(sponsored by|this video is brought to you by|use (?:promo )?code\b|don't forget to like and subscribe|hit the bell icon|link in the description)\b/i,
965
+ /(nhớ nhấn like và đăng ký kênh|bấm chuông thông báo|video(?:\s+này)?\s+được tài trợ bởi|được tài trợ bởi|link mua hàng dưới phần mô tả)/i
966
+ ];
967
+ function extractYouTubeVideoId(urlOrId) {
968
+ const trimmed = urlOrId.trim();
969
+ if (/^[a-zA-Z0-9_-]{11}$/.test(trimmed)) return trimmed;
970
+ try {
971
+ const u = new URL(trimmed);
972
+ const host = u.hostname.replace(/^www\./, "").toLowerCase();
973
+ if (host === "youtu.be") {
974
+ const id = u.pathname.split("/").filter(Boolean)[0];
975
+ return id && /^[a-zA-Z0-9_-]{11}$/.test(id) ? id : null;
976
+ }
977
+ if (host === "youtube.com" || host === "m.youtube.com" || host === "youtube-nocookie.com") {
978
+ const v = u.searchParams.get("v");
979
+ if (v && /^[a-zA-Z0-9_-]{11}$/.test(v)) return v;
980
+ const parts = u.pathname.split("/").filter(Boolean);
981
+ if ((parts[0] === "embed" || parts[0] === "shorts" || parts[0] === "v") && parts[1]) {
982
+ return /^[a-zA-Z0-9_-]{11}$/.test(parts[1]) ? parts[1] : null;
983
+ }
984
+ }
985
+ } catch {
986
+ }
987
+ return null;
988
+ }
989
+ function isYouTubeUrl(url) {
990
+ return extractYouTubeVideoId(url) !== null;
991
+ }
992
+ function formatTimestamp(seconds) {
993
+ const total = Math.max(0, Math.floor(seconds));
994
+ const hrs = Math.floor(total / 3600);
995
+ const mins = Math.floor(total % 3600 / 60);
996
+ const secs = total % 60;
997
+ if (hrs > 0) {
998
+ return `${String(hrs).padStart(2, "0")}:${String(mins).padStart(2, "0")}:${String(secs).padStart(2, "0")}`;
999
+ }
1000
+ return `${String(mins).padStart(2, "0")}:${String(secs).padStart(2, "0")}`;
1001
+ }
1002
+ function decodeHtmlEntities(str) {
1003
+ return str.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&#x27;/g, "'").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
1004
+ }
1005
+ function stitchCaptionSegments(segments) {
1006
+ const cleaned = segments.map((s) => ({
1007
+ startSec: s.startSec,
1008
+ durationSec: s.durationSec,
1009
+ text: decodeHtmlEntities(s.text)
1010
+ })).filter((s) => s.text.length > 0 && !SPONSOR_NOISE_PATTERNS.some((re) => re.test(s.text)));
1011
+ if (cleaned.length === 0) return [];
1012
+ const stitched = [];
1013
+ let bucketStart = cleaned[0].startSec;
1014
+ let bucketEnd = cleaned[0].startSec + cleaned[0].durationSec;
1015
+ let bucketTexts = [];
1016
+ for (const seg of cleaned) {
1017
+ bucketTexts.push(seg.text);
1018
+ bucketEnd = Math.max(bucketEnd, seg.startSec + seg.durationSec);
1019
+ const joined = bucketTexts.join(" ");
1020
+ const elapsed = seg.startSec - bucketStart;
1021
+ const endsSentence = /[.!?…]$/.test(seg.text);
1022
+ if (elapsed >= 30 && endsSentence || elapsed >= 50 || joined.length >= 360) {
1023
+ stitched.push({
1024
+ startSec: bucketStart,
1025
+ durationSec: Math.max(1, Math.round(bucketEnd - bucketStart)),
1026
+ timestamp: formatTimestamp(bucketStart),
1027
+ text: joined
1028
+ });
1029
+ bucketTexts = [];
1030
+ bucketStart = seg.startSec + seg.durationSec;
1031
+ }
1032
+ }
1033
+ if (bucketTexts.length > 0) {
1034
+ stitched.push({
1035
+ startSec: bucketStart,
1036
+ durationSec: Math.max(1, Math.round(bucketEnd - bucketStart)),
1037
+ timestamp: formatTimestamp(bucketStart),
1038
+ text: bucketTexts.join(" ")
1039
+ });
1040
+ }
1041
+ return stitched;
1042
+ }
1043
+ var YouTubeIngestionService = class {
1044
+ async fetchTranscript(urlOrId, preferredLanguages = ["vi", "en"]) {
1045
+ const videoId = extractYouTubeVideoId(urlOrId);
1046
+ if (!videoId) {
1047
+ throw new Error(`Invalid YouTube URL or Video ID: ${urlOrId}`);
1048
+ }
1049
+ const canonicalUrl = `https://www.youtube.com/watch?v=${videoId}`;
1050
+ const res = await fetch(canonicalUrl, {
1051
+ headers: {
1052
+ "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
1053
+ "Accept-Language": "vi-VN,vi;q=0.9,en-US;q=0.8,en;q=0.7"
1054
+ },
1055
+ signal: AbortSignal.timeout(12e3)
1056
+ });
1057
+ if (!res.ok) {
1058
+ throw new Error(`Failed to fetch YouTube watch page (${res.status})`);
1059
+ }
1060
+ const html = await res.text();
1061
+ const playerMatch = html.match(/ytInitialPlayerResponse\s*=\s*(\{[\s\S]*?\});\s*(?:var\s|window\.|<\/script>)/);
1062
+ let title = `YouTube Video (${videoId})`;
1063
+ let author;
1064
+ let shortDescription = "";
1065
+ let rawSegments = [];
1066
+ let selectedLang = "en";
1067
+ let isAutoGenerated = false;
1068
+ if (playerMatch?.[1]) {
1069
+ try {
1070
+ const playerData = JSON.parse(playerMatch[1]);
1071
+ title = playerData?.videoDetails?.title || title;
1072
+ author = playerData?.videoDetails?.author;
1073
+ shortDescription = playerData?.videoDetails?.shortDescription || "";
1074
+ const tracks = playerData?.captions?.playerCaptionsTracklistRenderer?.captionTracks || [];
1075
+ if (tracks.length > 0) {
1076
+ let chosenTrack = tracks.find(
1077
+ (t) => preferredLanguages.includes(t.languageCode) && t.kind !== "asr"
1078
+ ) || tracks.find((t) => preferredLanguages.includes(t.languageCode)) || tracks[0];
1079
+ if (chosenTrack?.baseUrl) {
1080
+ selectedLang = chosenTrack.languageCode || "en";
1081
+ isAutoGenerated = chosenTrack.kind === "asr";
1082
+ const trackRes = await fetch(chosenTrack.baseUrl, {
1083
+ signal: AbortSignal.timeout(1e4)
1084
+ });
1085
+ if (trackRes.ok) {
1086
+ const xml = await trackRes.text();
1087
+ const textMatches = [
1088
+ ...xml.matchAll(/<text\s+start="([\d.]+)"(?:\s+dur="([\d.]+)")?[^>]*>([\s\S]*?)<\/text>/g)
1089
+ ];
1090
+ for (const m of textMatches) {
1091
+ rawSegments.push({
1092
+ startSec: parseFloat(m[1] || "0"),
1093
+ durationSec: parseFloat(m[2] || "2"),
1094
+ text: (m[3] || "").replace(/<[^>]+>/g, " ")
1095
+ });
1096
+ }
1097
+ }
1098
+ }
1099
+ }
1100
+ } catch {
1101
+ }
1102
+ }
1103
+ if (title === `YouTube Video (${videoId})`) {
1104
+ const titleMeta = html.match(/<title>([\s\S]*?)<\/title>/i);
1105
+ if (titleMeta?.[1]) {
1106
+ title = decodeHtmlEntities(titleMeta[1].replace(/\s*-\s*YouTube$/i, ""));
1107
+ }
1108
+ }
1109
+ const stitched = stitchCaptionSegments(rawSegments);
1110
+ const mdLines = [
1111
+ `# ${title}`,
1112
+ `> **Source:** ${canonicalUrl}${author ? ` | **Channel:** ${author}` : ""} | **Language:** \`${selectedLang}\`${isAutoGenerated ? " (Auto-caption)" : ""}`
1113
+ ];
1114
+ if (shortDescription.trim()) {
1115
+ mdLines.push(`
1116
+ ## Video Overview & Description
1117
+ ${shortDescription.trim().slice(0, 1500)}`);
1118
+ }
1119
+ if (stitched.length > 0) {
1120
+ mdLines.push(`
1121
+ ## Timestamped Transcript`);
1122
+ for (const seg of stitched) {
1123
+ mdLines.push(`- **[${seg.timestamp}]** ${seg.text}`);
1124
+ }
1125
+ }
1126
+ return {
1127
+ videoId,
1128
+ url: canonicalUrl,
1129
+ title,
1130
+ author,
1131
+ language: selectedLang,
1132
+ isAutoGenerated,
1133
+ segments: stitched,
1134
+ stitchedMarkdown: mdLines.join("\n")
1135
+ };
1136
+ }
1137
+ };
1138
+
1139
+ // src/harvester/webScraper.ts
1140
+ function extractSubstantiveExcerpts(markdown, maxExcerpts = 6) {
1141
+ const withoutCode = markdown.replace(/```[\s\S]*?```/g, "\n");
1142
+ const blocks = withoutCode.split(/\n{2,}/).map((b) => b.replace(/\s+/g, " ").trim()).filter((b) => {
1143
+ if (b.length < 60 || b.length > 900) return false;
1144
+ if (b.startsWith("#") || b.startsWith("|")) return false;
1145
+ const linkRatio = (b.match(/\[[^\]]+\]\([^)]+\)/g) || []).join("").length / b.length;
1146
+ if (linkRatio > 0.45) return false;
1147
+ if (/\b(cookie policy|privacy policy|all rights reserved|terms of service|sign in|log in|subscribe to our newsletter)\b/i.test(b)) {
1148
+ return false;
1149
+ }
1150
+ return true;
1151
+ });
1152
+ return blocks.slice(0, maxExcerpts);
1153
+ }
1154
+ var WebScraper = class {
1155
+ crawl4aiHost;
1156
+ jinaKey;
1157
+ brightDataKey;
1158
+ brightDataZone;
1159
+ allowEnvFallback;
1160
+ customAdapter;
1161
+ youtubeService;
1162
+ constructor(options = {}) {
1163
+ this.allowEnvFallback = options.allowEnvFallback ?? true;
1164
+ this.crawl4aiHost = options.crawl4aiHost || (this.allowEnvFallback ? process.env.CRAWL4AI_HOST : void 0) || "http://localhost:11235";
1165
+ this.jinaKey = options.jinaKey || (this.allowEnvFallback ? process.env.JINA_API_KEY : void 0);
1166
+ this.brightDataKey = options.brightDataKey || (this.allowEnvFallback ? process.env.BRIGHTDATA_API_KEY || process.env.BRIGHT_DATA_KEY : void 0);
1167
+ this.brightDataZone = options.brightDataZone || (this.allowEnvFallback ? process.env.BRIGHTDATA_UNLOCKER_ZONE : void 0) || "cli_unlocker";
1168
+ this.customAdapter = options.customAdapter;
1169
+ this.youtubeService = new YouTubeIngestionService();
1170
+ }
1171
+ setCustomAdapter(adapter) {
1172
+ this.customAdapter = adapter;
1173
+ }
1174
+ setJinaKey(key) {
1175
+ this.jinaKey = key;
1176
+ }
1177
+ setBrightData(key, zone) {
1178
+ if (key !== void 0) this.brightDataKey = key;
1179
+ if (zone !== void 0) this.brightDataZone = zone;
1180
+ }
1181
+ async scrapeUrl(targetUrl, options = {}) {
1182
+ const adapter = options.customAdapter || this.customAdapter;
1183
+ const bdKey = options.brightDataKey || this.brightDataKey;
1184
+ const bdZone = options.brightDataZone || this.brightDataZone;
1185
+ const preferred = options.preferredProvider;
1186
+ if (adapter) {
1187
+ try {
1188
+ const result = await adapter.crawl(targetUrl);
1189
+ if (result && result.markdownContent) {
1190
+ return this.packageDocument(targetUrl, result.markdownContent, "custom", result.title);
1191
+ }
1192
+ } catch (e) {
1193
+ console.warn(`[WebScraper] Custom crawler adapter failed for ${targetUrl}:`, e?.message || e);
1194
+ }
1195
+ }
1196
+ if (isYouTubeUrl(targetUrl)) {
1197
+ try {
1198
+ const yt = await this.youtubeService.fetchTranscript(targetUrl, options.preferredLanguages);
1199
+ if (yt.stitchedMarkdown && yt.stitchedMarkdown.length > 80) {
1200
+ return this.packageDocument(yt.url, yt.stitchedMarkdown, "youtube", yt.title);
1201
+ }
1202
+ } catch (e) {
1203
+ console.warn(`[WebScraper] YouTube transcript extraction failed for ${targetUrl}:`, e?.message || e);
1204
+ }
1205
+ }
1206
+ if (preferred === "brightdata" && bdKey) {
1207
+ try {
1208
+ return await this.scrapeWithBrightData(targetUrl, bdKey, bdZone);
1209
+ } catch (e) {
1210
+ console.warn(`[WebScraper] Preferred Bright Data failed for ${targetUrl}:`, e?.message || e);
1211
+ }
1212
+ }
1213
+ try {
1214
+ const jinaUrl = `https://r.jina.ai/${targetUrl}`;
1215
+ const jinaKey = options.jinaKey || this.jinaKey;
1216
+ const headers = {
1217
+ "User-Agent": "OrchableComposer/1.0",
1218
+ "X-Return-Format": "markdown"
1219
+ };
1220
+ if (jinaKey) {
1221
+ headers["Authorization"] = `Bearer ${jinaKey}`;
1222
+ }
1223
+ const res = await fetch(jinaUrl, {
1224
+ headers,
1225
+ signal: AbortSignal.timeout(8e3)
1226
+ });
1227
+ if (res.ok) {
1228
+ const markdown = await res.text();
1229
+ if (markdown && markdown.length > 100) {
1230
+ return this.packageDocument(targetUrl, markdown, "jina");
1231
+ }
1232
+ }
1233
+ } catch (e) {
1234
+ console.warn(`[WebScraper] Jina Reader failed for ${targetUrl}:`, e?.message || e);
1235
+ }
1236
+ if (this.crawl4aiHost) {
1237
+ try {
1238
+ const res = await fetch(`${this.crawl4aiHost}/crawl`, {
1239
+ method: "POST",
1240
+ headers: { "Content-Type": "application/json" },
1241
+ body: JSON.stringify({
1242
+ urls: targetUrl,
1243
+ priority: 10
1244
+ }),
1245
+ signal: AbortSignal.timeout(15e3)
1246
+ });
1247
+ if (res.ok) {
1248
+ const data = await res.json();
1249
+ const markdown = data?.results?.[0]?.markdown || data?.markdown;
1250
+ if (markdown) {
1251
+ return this.packageDocument(targetUrl, markdown, "crawl4ai");
1252
+ }
1253
+ }
1254
+ } catch {
1255
+ }
1256
+ }
1257
+ if (bdKey) {
1258
+ try {
1259
+ return await this.scrapeWithBrightData(targetUrl, bdKey, bdZone);
1260
+ } catch (e) {
1261
+ console.warn(`[WebScraper] Bright Data fallback failed for ${targetUrl}:`, e?.message || e);
1262
+ }
1263
+ }
1264
+ try {
1265
+ const res = await fetch(targetUrl, {
1266
+ headers: { "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" },
1267
+ signal: AbortSignal.timeout(1e4)
1268
+ });
1269
+ if (res.ok) {
1270
+ const rawHtml = await res.text();
1271
+ const titleTag = rawHtml.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim();
1272
+ const clean = rawHtml.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "").replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, "").replace(/<nav\b[^<]*(?:(?!<\/nav>)<[^<]*)*<\/nav>/gi, "").replace(/<footer\b[^<]*(?:(?!<\/footer>)<[^<]*)*<\/footer>/gi, "").replace(/<h([1-3])[^>]*>([\s\S]*?)<\/h\1>/gi, (_, lvl, txt) => `
1273
+ ${"#".repeat(Number(lvl))} ${txt.replace(/<[^>]+>/g, "").trim()}
1274
+ `).replace(/<pre[^>]*><code[^>]*>([\s\S]*?)<\/code><\/pre>/gi, (_, code) => `
1275
+ \`\`\`
1276
+ ${code.replace(/<[^>]+>/g, "").trim()}
1277
+ \`\`\`
1278
+ `).replace(/<p[^>]*>([\s\S]*?)<\/p>/gi, (_, p) => `
1279
+ ${p.replace(/<[^>]+>/g, " ").trim()}
1280
+ `).replace(/<[^>]+>/g, " ").replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
1281
+ return this.packageDocument(targetUrl, clean, "direct", titleTag);
1282
+ }
1283
+ } catch (e) {
1284
+ console.warn(`[WebScraper] Direct fetch failed for ${targetUrl}:`, e?.message || e);
1285
+ }
1286
+ throw new Error(`Unable to fetch content from URL: ${targetUrl}`);
1287
+ }
1288
+ async scrapeWithBrightData(targetUrl, key, zone) {
1289
+ const reqZone = zone || this.brightDataZone || "cli_unlocker";
1290
+ const res = await fetch("https://api.brightdata.com/request", {
1291
+ method: "POST",
1292
+ headers: {
1293
+ Authorization: `Bearer ${key}`,
1294
+ "Content-Type": "application/json"
1295
+ },
1296
+ body: JSON.stringify({
1297
+ zone: reqZone,
1298
+ url: targetUrl,
1299
+ format: "raw",
1300
+ data_format: "markdown"
1301
+ }),
1302
+ signal: AbortSignal.timeout(2e4)
1303
+ });
1304
+ if (res.ok) {
1305
+ const markdown = await res.text();
1306
+ if (markdown && markdown.length > 30) {
1307
+ return this.packageDocument(targetUrl, markdown, "brightdata");
1308
+ }
1309
+ }
1310
+ throw new Error(`Bright Data Web Unlocker failed with HTTP ${res.status}`);
1311
+ }
1312
+ packageDocument(url, markdown, provider, explicitTitle) {
1313
+ const titleMatch = markdown.match(/^#\s+(.+)$/m) || markdown.match(/^Title:\s*(.+)$/im);
1314
+ const title = (explicitTitle || (titleMatch ? titleMatch[1].trim() : url.split("/").filter(Boolean).pop() || "Document")).slice(0, 180);
1315
+ const codeBlockMatches = [...markdown.matchAll(/```([a-zA-Z0-9_+-]*)\n([\s\S]*?)```/g)];
1316
+ const extractedCodeBlocks = codeBlockMatches.map((m) => ({
1317
+ language: (m[1] || "").trim().toLowerCase(),
1318
+ code: (m[2] || "").trim()
1319
+ })).filter((b) => b.code.length > 0);
1320
+ const extractedCodeSnippets = extractedCodeBlocks.map((b) => b.code);
1321
+ const tableBlocks = markdown.match(/(?:^\|.+\|\s*\n)+^\|[-:| ]+\|\s*\n(?:^\|.+\|\s*\n?)+/gm) || markdown.match(/\|[\s\S]*?\|[\s\S]*?\|/g) || [];
1322
+ const extractedTables = tableBlocks.map((t) => t.trim()).filter((t) => t.length > 15);
1323
+ const extractedHeadings = [...markdown.matchAll(/^#{1,3}\s+(.+)$/gm)].map((m) => m[1].trim()).filter((h) => h.length > 2 && h.length < 120);
1324
+ const keyExcerpts = extractSubstantiveExcerpts(markdown, 6);
1325
+ return {
1326
+ url,
1327
+ title,
1328
+ markdownContent: markdown,
1329
+ byteSize: Buffer.byteLength(markdown, "utf-8"),
1330
+ extractedCodeSnippets,
1331
+ extractedCodeBlocks,
1332
+ extractedTables,
1333
+ extractedHeadings,
1334
+ keyExcerpts,
1335
+ tablesCount: extractedTables.length,
1336
+ fetchProvider: provider
1337
+ };
1338
+ }
1339
+ };
1340
+
1341
+ // src/evidence/evidenceScorer.ts
1342
+ function tokenizeBilingualKeywords(text) {
1343
+ 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));
1344
+ }
1345
+ function extractTopSentences(markdown, targetTopic, maxSentences = 3) {
1346
+ const keywords = tokenizeBilingualKeywords(targetTopic);
1347
+ const withoutCode = markdown.replace(/```[\s\S]*?```/g, " ");
1348
+ const rawSentences = withoutCode.split(/(?<=[.!?。\n])\s+/).map((s) => s.replace(/^[-*•#>\s]+/, "").replace(/\s+/g, " ").trim()).filter((s) => {
1349
+ if (s.length < 45 || s.length > 320) return false;
1350
+ if (s.startsWith("|") || s.startsWith("http")) return false;
1351
+ if (/\b(cookie|privacy policy|sign in|subscribe|all rights reserved)\b/i.test(s)) return false;
1352
+ return true;
1353
+ });
1354
+ if (rawSentences.length === 0) return [];
1355
+ const scored = rawSentences.map((sentence, idx) => {
1356
+ const lower = sentence.normalize("NFC").toLowerCase();
1357
+ const matchedCount = keywords.filter((k) => lower.includes(k)).length;
1358
+ const positionBonus = idx < 8 ? 1.5 : idx < 20 ? 0.5 : 0;
1359
+ const technicalBonus = /(`[^`]+`|\b(?:api|function|class|actor|async|sensor|pin|loop|state|biến|hàm|cảm biến|vòng lặp|mạch)\b)/i.test(
1360
+ sentence
1361
+ ) ? 1.5 : 0;
1362
+ return {
1363
+ sentence,
1364
+ idx,
1365
+ score: matchedCount * 2 + positionBonus + technicalBonus
1366
+ };
1367
+ });
1368
+ return scored.sort((a, b) => b.score - a.score || a.idx - b.idx).slice(0, maxSentences).sort((a, b) => a.idx - b.idx).map((s) => s.sentence);
1369
+ }
1370
+ var EvidenceScorer = class {
1371
+ scoreDocument(doc, domain, targetTopic) {
1372
+ let depthScore = 5;
1373
+ const hasCode = doc.extractedCodeSnippets.length > 0;
1374
+ let codeScore = hasCode ? Math.min(10, 7 + Math.min(3, doc.extractedCodeSnippets.length)) : 5;
1375
+ let noiseScore = 2;
1376
+ const lowerContent = doc.markdownContent.normalize("NFC").toLowerCase();
1377
+ const targetKeywords = tokenizeBilingualKeywords(targetTopic);
1378
+ const keywordMatches = targetKeywords.filter((k) => lowerContent.includes(k)).length;
1379
+ const matchRatio = targetKeywords.length > 0 ? keywordMatches / targetKeywords.length : 1;
1380
+ if (matchRatio >= 0.75) depthScore += 3;
1381
+ else if (matchRatio >= 0.4) depthScore += 2;
1382
+ else if (keywordMatches >= 1) depthScore += 1;
1383
+ if (doc.tablesCount > 0) depthScore += 1;
1384
+ if (doc.byteSize > 1500) depthScore += 1;
1385
+ if ((doc.extractedHeadings?.length || 0) >= 2) depthScore += 1;
1386
+ depthScore = Math.min(10, depthScore);
1387
+ if (!hasCode && doc.byteSize > 1200 && matchRatio >= 0.5) {
1388
+ codeScore = 6;
1389
+ }
1390
+ if (lowerContent.includes("subscribe") && lowerContent.includes("advertisement")) {
1391
+ noiseScore += 3;
1392
+ }
1393
+ const rawTotal = depthScore * 0.55 + codeScore * 0.35 - noiseScore * 0.1 + 0.5;
1394
+ const score = Math.max(1, Math.min(10, Math.round(rawTotal)));
1395
+ const isApproved = score >= 6;
1396
+ const topSentences = extractTopSentences(doc.markdownContent, targetTopic, 3);
1397
+ const excerpts = doc.keyExcerpts?.length ? doc.keyExcerpts : extractSubstantiveExcerpts(doc.markdownContent, 3);
1398
+ const keyTakeaways = topSentences.length > 0 ? topSentences : excerpts.slice(0, 2);
1399
+ const summary = keyTakeaways.length > 0 ? `${keyTakeaways[0]} [Evidence ${score}/10 \xB7 ${doc.extractedCodeSnippets.length} code blocks \xB7 ${doc.tablesCount} tables]` : `Evidence scored ${score}/10 (${isApproved ? "APPROVED" : "REJECTED"}) for ${domain} (${doc.byteSize} bytes).`;
1400
+ return {
1401
+ doc,
1402
+ score,
1403
+ isApproved,
1404
+ isLlmEvaluated: false,
1405
+ breakdown: {
1406
+ technicalDepth: depthScore,
1407
+ structuralRichness: depthScore,
1408
+ codeSnippetQuality: codeScore,
1409
+ noiseFactor: noiseScore
1410
+ },
1411
+ summary,
1412
+ keyTakeaways
1413
+ };
1414
+ }
1415
+ /**
1416
+ * Evaluates evidence with host LLM for genuine pedagogical relevance, conceptual depth,
1417
+ * and accuracy for the target learner age band.
1418
+ */
1419
+ async scoreDocumentWithLlm(doc, domain, targetTopic, options = {}) {
1420
+ const baseline = this.scoreDocument(doc, domain, targetTopic);
1421
+ if (!options.llm) {
1422
+ return baseline;
1423
+ }
1424
+ try {
1425
+ const prompt = [
1426
+ `You are a Senior Curriculum Researcher. Evaluate this harvested web document for the course topic "${targetTopic}" (Domain: ${domain}).`,
1427
+ options.context?.ageBand ? `Target Learner Age Band: ${options.context.ageBand[0]}-${options.context.ageBand[1]}` : "",
1428
+ options.context?.hardwarePlatform ? `Hardware Platform: ${options.context.hardwarePlatform}` : "",
1429
+ options.context?.softwareEnv ? `Software / Tools: ${options.context.softwareEnv}` : "",
1430
+ `
1431
+ Document Title: ${doc.title}`,
1432
+ `Document URL: ${doc.url}`,
1433
+ `Sample Excerpts:
1434
+ ${(doc.keyExcerpts || []).slice(0, 3).join("\n")}`,
1435
+ `Code Blocks Found: ${doc.extractedCodeSnippets.length}`,
1436
+ `
1437
+ Return ONLY a JSON object:`,
1438
+ `{"score": 8, "isApproved": true, "pedagogicalRelevance": 9, "summary": "1-sentence evaluative summary", "keyTakeaways": ["Takeaway 1 grounded in text", "Takeaway 2"]}`
1439
+ ].filter(Boolean).join("\n");
1440
+ const raw = await options.llm(prompt, {
1441
+ system: "You are an educational curriculum auditor. Output strictly valid JSON.",
1442
+ temperature: 0.2,
1443
+ jsonMode: true
1444
+ });
1445
+ const match = raw.match(/\{[\s\S]*\}/);
1446
+ if (match) {
1447
+ const parsed = JSON.parse(match[0]);
1448
+ const score = Math.max(1, Math.min(10, Number(parsed.score) || baseline.score));
1449
+ return {
1450
+ doc,
1451
+ score,
1452
+ isApproved: score >= 6,
1453
+ isLlmEvaluated: true,
1454
+ breakdown: {
1455
+ ...baseline.breakdown,
1456
+ pedagogicalRelevance: Number(parsed.pedagogicalRelevance) || score
1457
+ },
1458
+ summary: String(parsed.summary || baseline.summary),
1459
+ keyTakeaways: Array.isArray(parsed.keyTakeaways) && parsed.keyTakeaways.length > 0 ? parsed.keyTakeaways.map(String) : baseline.keyTakeaways
1460
+ };
1461
+ }
1462
+ } catch (e) {
1463
+ console.warn("[EvidenceScorer] LLM evidence evaluation failed, using structural baseline:", e?.message || e);
1464
+ }
1465
+ return baseline;
1466
+ }
1467
+ };
1468
+
1469
+ // src/evidence/provenanceTracker.ts
1470
+ var ProvenanceTracker = class {
1471
+ generateSidecar(topic, records) {
1472
+ const campaignId = `CAMP-${Math.random().toString(36).substring(2, 9).toUpperCase()}`;
1473
+ const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
1474
+ const mdLines = [
1475
+ `# \u{1F4DC} Provenance & Audit Trail: ${topic}`,
1476
+ `> **Campaign ID:** \`${campaignId}\` | **Generated At:** \`${generatedAt}\` | **Total Verified Sources:** \`${records.length}\``,
1477
+ `
1478
+ ## Audit Trail Table`,
1479
+ `| Resource ID | Domain | Relevancy | Size (Bytes) | Source URL | Timestamp |`,
1480
+ `|---|---|---|---|---|---|`,
1481
+ ...records.map((r) => `| **${r.resourceId}** | \`${r.domain}\` | \u2B50 \`${r.relevanceScore}/10\` | \`${r.byteSize}\` | [Access Source](${r.sourceUrl}) | \`${r.accessedAt.slice(0, 19)}\` |`),
1482
+ `
1483
+ ## Integrity Guarantee`,
1484
+ `- Every pedagogical claim and technical snippet in the curriculum maps 1-to-1 to the physical sources listed above.`,
1485
+ `- Unverified citations or hallucinated sources are strictly prohibited under Curriculum OS Rule \xA75.`
1486
+ ];
1487
+ return {
1488
+ topic,
1489
+ campaignId,
1490
+ generatedAt,
1491
+ totalRecords: records.length,
1492
+ records,
1493
+ provenanceMd: mdLines.join("\n")
1494
+ };
1495
+ }
1496
+ };
1497
+
1498
+ // src/harvester/domainClassifier.ts
1499
+ var HARDWARE_PATTERNS = [
1500
+ /\b(esp32|esp8266|arduino|raspberry\s*pi|stm32|micro:?bit|mblock|makecode|lego|spike\s*prime|mindstorms|ev3|wedo|vex)\b/i,
1501
+ /\b(sensor|sensors|circuit|circuits|gpio|breadboard|microcontroller|firmware|embedded|iot|led|servo|ultrasonic|ldr|dht11|dht22|i2c|spi|uart|pwm|adc|actuator|robotics)\b/i,
1502
+ /(cảm biến|vi điều khiển|mạch điện|linh kiện|điện tử|nhúng|động cơ servo|đèn led|bảng mạch)/i
1503
+ ];
1504
+ var PLATFORM_PATTERNS = [
1505
+ /\b(supabase|firebase|aws|amazon web services|gcp|google cloud|azure|cloudflare|vercel|netlify|docker|kubernetes|k8s|terraform|backend-as-a-service|baas|ci\/cd|github actions)\b/i,
1506
+ /(điện toán đám mây|hạ tầng cloud|triển khai hệ thống|container hóa)/i
1507
+ ];
1508
+ var ACADEMIC_PATTERNS = [
1509
+ /\b(theorem|complexity|np-hard|np-complete|pedagogy|bloom|constructivism|formal verification|computational theory|automata|turing|lambda calculus|type theory|big-o|asymptotic)\b/i,
1510
+ /(lý thuyết tính toán|độ phức tạp thuật toán|chứng minh hình thức|sư phạm|tải nhận thức)/i
1511
+ ];
1512
+ function inferPrimaryCodeLanguage(topic, context, domain) {
1513
+ const combined = [
1514
+ topic,
1515
+ context?.courseTitle,
1516
+ context?.hardwarePlatform,
1517
+ context?.softwareEnv,
1518
+ ...context?.inScopeTopics || []
1519
+ ].filter(Boolean).join(" ").toLowerCase();
1520
+ if (/\b(swift|swiftui|xcode|playground)\b/.test(combined)) return "swift";
1521
+ if (/\b(lua|roblox|lovr|love2d)\b/.test(combined)) return "lua";
1522
+ if (/\b(python|pygame|jupyter|pandas|numpy|pytorch|tensorflow|micropython)\b/.test(combined)) return "python";
1523
+ if (/\b(typescript|tsx|nextjs|next\.js|angular|nestjs)\b/.test(combined)) return "typescript";
1524
+ if (/\b(javascript|nodejs|node\.js|react|vue|svelte|p5\.js|makecode)\b/.test(combined)) return "javascript";
1525
+ if (/\b(c\+\+|cpp|arduino|ino|esp-idf|stm32)\b/.test(combined)) return "cpp";
1526
+ if (/\b(c#|csharp|unity|\.net|dotnet)\b/.test(combined)) return "csharp";
1527
+ if (/\b(gdscript|godot)\b/.test(combined)) return "gdscript";
1528
+ if (/\b(java|spring|android|kotlin)\b/.test(combined)) return "java";
1529
+ if (/\b(rust|cargo)\b/.test(combined)) return "rust";
1530
+ if (/\b(golang|\bgo\b)\b/.test(combined)) return "go";
1531
+ if (/\b(sql|postgres|postgresql|mysql|sqlite)\b/.test(combined)) return "sql";
1532
+ if (/\b(scratch|mblock|blockly)\b/.test(combined)) return "text";
1533
+ if (domain === "hardware") return "cpp";
1534
+ return "text";
1535
+ }
1536
+ function classifyTechnicalDomain(topic, explicitDomain, context) {
1537
+ const combined = [
1538
+ topic,
1539
+ context?.courseTitle,
1540
+ context?.positioning,
1541
+ context?.hardwarePlatform,
1542
+ context?.softwareEnv,
1543
+ ...context?.inScopeTopics || []
1544
+ ].filter(Boolean).join(" ");
1545
+ if (HARDWARE_PATTERNS.some((re) => re.test(combined))) {
1546
+ return {
1547
+ domain: "hardware",
1548
+ confidence: 0.95,
1549
+ rationale: "Topic or context contains microcontrollers, sensors, robotics kits, or physical electronics keywords.",
1550
+ recommendedExtractors: getExtractorsForDomain("hardware"),
1551
+ primaryCodeLanguage: inferPrimaryCodeLanguage(topic, context, "hardware")
1552
+ };
1553
+ }
1554
+ if (PLATFORM_PATTERNS.some((re) => re.test(combined))) {
1555
+ return {
1556
+ domain: "platform",
1557
+ confidence: 0.9,
1558
+ rationale: "Topic represents a cloud infrastructure, hosting, DevOps, or BaaS platform.",
1559
+ recommendedExtractors: getExtractorsForDomain("platform"),
1560
+ primaryCodeLanguage: inferPrimaryCodeLanguage(topic, context, "platform")
1561
+ };
1562
+ }
1563
+ if (ACADEMIC_PATTERNS.some((re) => re.test(combined))) {
1564
+ return {
1565
+ domain: "academic",
1566
+ confidence: 0.9,
1567
+ rationale: "Topic focuses on theoretical foundations, pedagogical models, or formal proofs.",
1568
+ recommendedExtractors: getExtractorsForDomain("academic"),
1569
+ primaryCodeLanguage: inferPrimaryCodeLanguage(topic, context, "academic")
1570
+ };
1571
+ }
1572
+ return {
1573
+ domain: "software",
1574
+ confidence: 0.85,
1575
+ rationale: "Topic is a programming language, game engine, client/server library, or software application.",
1576
+ recommendedExtractors: getExtractorsForDomain("software"),
1577
+ primaryCodeLanguage: inferPrimaryCodeLanguage(topic, context, "software")
1578
+ };
1579
+ }
1580
+ function getExtractorsForDomain(domain) {
1581
+ switch (domain) {
1582
+ case "hardware":
1583
+ return ["PinoutTableExtractor", "DatasheetSpecsExtractor", "CircuitSchematicExtractor"];
1584
+ case "platform":
1585
+ return ["ArchitectureDiagramExtractor", "CLICommandExtractor", "SDKIntegrationExtractor"];
1586
+ case "academic":
1587
+ return ["SemanticScholarExtractor", "ArXivExtractor", "TheoremFormulaExtractor"];
1588
+ case "software":
1589
+ default:
1590
+ return ["APISignatureExtractor", "CodeExampleExtractor", "DependencyTreeExtractor"];
1591
+ }
1592
+ }
1593
+
1594
+ // src/harvester/healthAuditor.ts
1595
+ var HealthAuditor = class {
1596
+ auditDocument(doc) {
1597
+ const issues = [];
1598
+ const warnings = [];
1599
+ if (!doc.markdownContent || doc.markdownContent.length < 80) {
1600
+ issues.push("Document content is too short or empty (< 80 characters).");
1601
+ }
1602
+ if (doc.markdownContent.includes("403 Forbidden") || doc.markdownContent.includes("Cloudflare Ray ID") || doc.markdownContent.includes("Access Denied")) {
1603
+ issues.push("Document blocked by firewall / Cloudflare / WAF.");
1604
+ }
1605
+ if (doc.extractedCodeSnippets.length === 0 && !doc.markdownContent.includes("|")) {
1606
+ warnings.push("Document does not contain any code snippets or reference tables.");
1607
+ }
1608
+ const passed = issues.length === 0;
1609
+ const score = passed ? warnings.length > 0 ? 80 : 100 : 20;
1610
+ return { passed, score, issues, warnings };
1611
+ }
1612
+ };
1613
+
1614
+ // src/harvester/multiSourceSearch.ts
1615
+ var MultiSourceSearchEngine = class {
1616
+ tavilyKey;
1617
+ exaKey;
1618
+ serperKey;
1619
+ brightDataKey;
1620
+ brightDataZone;
1621
+ searxngHost;
1622
+ searxngHeaders;
1623
+ allowEnvFallback;
1624
+ customAdapter;
1625
+ academicEngine;
1626
+ constructor(options = {}) {
1627
+ this.allowEnvFallback = options.allowEnvFallback ?? true;
1628
+ this.tavilyKey = options.apiKeys?.tavily || options.tavilyKey || (this.allowEnvFallback ? process.env.TAVILY_API_KEY : void 0);
1629
+ this.exaKey = options.apiKeys?.exa || options.exaKey || (this.allowEnvFallback ? process.env.EXA_API_KEY : void 0);
1630
+ this.serperKey = options.apiKeys?.serper || options.serperKey || (this.allowEnvFallback ? process.env.SERPER_API_KEY : void 0);
1631
+ this.brightDataKey = options.apiKeys?.brightdata || options.apiKeys?.brightData || options.brightDataKey || (this.allowEnvFallback ? process.env.BRIGHTDATA_API_KEY || process.env.BRIGHT_DATA_KEY : void 0);
1632
+ this.brightDataZone = options.brightDataZone || (this.allowEnvFallback ? process.env.BRIGHTDATA_SERP_ZONE || process.env.BRIGHTDATA_UNLOCKER_ZONE : void 0) || "cli_unlocker";
1633
+ this.searxngHost = options.searxngHost || (this.allowEnvFallback ? process.env.SEARXNG_URL || process.env.SEARXNG_HOST : void 0);
1634
+ const cfId = process.env.CF_ACCESS_CLIENT_ID;
1635
+ const cfSecret = process.env.CF_ACCESS_CLIENT_SECRET;
1636
+ this.searxngHeaders = {
1637
+ ...options.searxngHeaders || {},
1638
+ ...cfId && cfSecret ? { "CF-Access-Client-Id": cfId, "CF-Access-Client-Secret": cfSecret } : {}
1639
+ };
1640
+ this.customAdapter = options.customAdapter;
1641
+ this.academicEngine = new AcademicSearchEngine({ allowEnvFallback: this.allowEnvFallback });
1642
+ }
1643
+ setCustomAdapter(adapter) {
1644
+ this.customAdapter = adapter;
1645
+ }
1646
+ setApiKeys(keys) {
1647
+ if (keys.tavily !== void 0) this.tavilyKey = keys.tavily;
1648
+ if (keys.exa !== void 0) this.exaKey = keys.exa;
1649
+ if (keys.serper !== void 0) this.serperKey = keys.serper;
1650
+ if (keys.brightdata !== void 0) this.brightDataKey = keys.brightdata;
1651
+ if (keys.brightData !== void 0) this.brightDataKey = keys.brightData;
1652
+ }
1653
+ setBrightData(key, zone) {
1654
+ if (key !== void 0) this.brightDataKey = key;
1655
+ if (zone !== void 0) this.brightDataZone = zone;
1656
+ }
1657
+ setSearxng(host, headers) {
1658
+ this.searxngHost = host;
1659
+ if (headers) {
1660
+ this.searxngHeaders = { ...this.searxngHeaders, ...headers };
1661
+ }
1662
+ }
1663
+ async search(query, options = {}) {
1664
+ const limit = options.limit ?? 5;
1665
+ const adapter = options.customAdapter || this.customAdapter;
1666
+ const preferred = options.preferredEngine;
1667
+ if (adapter && (!preferred || preferred === "custom")) {
1668
+ try {
1669
+ const customResults = await adapter.search(query, { limit, domainFilter: options.domainFilter });
1670
+ if (Array.isArray(customResults)) {
1671
+ return customResults.map((r) => ({
1672
+ title: r.title,
1673
+ url: r.url,
1674
+ content: r.content,
1675
+ score: r.score,
1676
+ engine: "custom"
1677
+ }));
1678
+ }
1679
+ } catch (e) {
1680
+ console.warn("[MultiSourceSearchEngine] Custom search adapter failed:", e?.message || e);
1681
+ }
1682
+ }
1683
+ if (preferred === "academic") {
1684
+ try {
1685
+ const papers = await this.academicEngine.searchPapers(query, { limit });
1686
+ if (papers.length > 0) {
1687
+ return papers.map((p) => ({
1688
+ title: p.title,
1689
+ url: p.url || p.pdfUrl || (p.doi ? `https://doi.org/${p.doi}` : `https://openalex.org/${p.id}`),
1690
+ content: p.tldr || p.abstract || "",
1691
+ score: p.citationCount,
1692
+ engine: "academic"
1693
+ }));
1694
+ }
1695
+ } catch (e) {
1696
+ console.warn("[MultiSourceSearchEngine] Academic search failed:", e?.message || e);
1697
+ }
1698
+ }
1699
+ const tavilyKey = options.apiKeys?.tavily || options.tavilyKey || this.tavilyKey;
1700
+ const exaKey = options.apiKeys?.exa || options.exaKey || this.exaKey;
1701
+ const serperKey = options.apiKeys?.serper || options.serperKey || this.serperKey;
1702
+ const brightDataKey = options.apiKeys?.brightdata || options.apiKeys?.brightData || options.brightDataKey || this.brightDataKey;
1703
+ const brightDataZone = options.brightDataZone || this.brightDataZone;
1704
+ const searxngHost = options.searxngHost || this.searxngHost;
1705
+ if (preferred === "searxng" && searxngHost) {
1706
+ const searxHits = await this.querySearxng(query, searxngHost, limit, options.searxngHeaders);
1707
+ if (searxHits.length > 0) return searxHits;
1708
+ }
1709
+ if (preferred === "brightdata" && brightDataKey) {
1710
+ const bdHits = await this.queryBrightData(query, brightDataKey, limit, {
1711
+ zone: brightDataZone,
1712
+ engine: options.brightDataEngine
1713
+ });
1714
+ if (bdHits.length > 0) return bdHits;
1715
+ }
1716
+ if (preferred === "exa" && exaKey) {
1717
+ const exaHits = await this.queryExa(query, exaKey, limit, options.domainFilter);
1718
+ if (exaHits.length > 0) return exaHits;
1719
+ }
1720
+ if (preferred === "serper" && serperKey) {
1721
+ const serperHits = await this.querySerper(query, serperKey, limit);
1722
+ if (serperHits.length > 0) return serperHits;
1723
+ }
1724
+ if (preferred === "duckduckgo") {
1725
+ const ddgHits2 = await this.queryDuckDuckGo(query, limit);
1726
+ if (ddgHits2.length > 0) return ddgHits2;
1727
+ }
1728
+ if (tavilyKey && (!preferred || preferred === "tavily")) {
1729
+ try {
1730
+ const body = {
1731
+ api_key: tavilyKey,
1732
+ query,
1733
+ search_depth: "advanced",
1734
+ include_answer: true,
1735
+ max_results: limit
1736
+ };
1737
+ if (options.timeRange) {
1738
+ body.time_range = options.timeRange;
1739
+ }
1740
+ if (options.domainFilter && options.domainFilter.length > 0) {
1741
+ body.include_domains = options.domainFilter;
1742
+ }
1743
+ const res = await fetch("https://api.tavily.com/search", {
1744
+ method: "POST",
1745
+ headers: { "Content-Type": "application/json" },
1746
+ body: JSON.stringify(body),
1747
+ signal: AbortSignal.timeout(12e3)
1748
+ });
1749
+ if (res.ok) {
1750
+ const data = await res.json();
1751
+ if (Array.isArray(data?.results) && data.results.length > 0) {
1752
+ return data.results.map((r) => ({
1753
+ title: r.title || "Untitled",
1754
+ url: r.url,
1755
+ content: r.content || "",
1756
+ score: r.score,
1757
+ engine: "tavily"
1758
+ }));
1759
+ }
1760
+ }
1761
+ } catch (e) {
1762
+ console.warn("[MultiSourceSearchEngine] Tavily attempt failed:", e?.message || e);
1763
+ }
1764
+ }
1765
+ if (exaKey) {
1766
+ const exaHits = await this.queryExa(query, exaKey, limit, options.domainFilter, options.timeRange);
1767
+ if (exaHits.length > 0) return exaHits;
1768
+ }
1769
+ if (serperKey) {
1770
+ const serperHits = await this.querySerper(query, serperKey, limit, options.timeRange);
1771
+ if (serperHits.length > 0) return serperHits;
1772
+ }
1773
+ if (brightDataKey) {
1774
+ const bdHits = await this.queryBrightData(query, brightDataKey, limit, {
1775
+ zone: brightDataZone,
1776
+ engine: options.brightDataEngine
1777
+ });
1778
+ if (bdHits.length > 0) return bdHits;
1779
+ }
1780
+ if (searxngHost) {
1781
+ const searxHits = await this.querySearxng(query, searxngHost, limit, options.searxngHeaders, options.timeRange);
1782
+ if (searxHits.length > 0) return searxHits;
1783
+ }
1784
+ const ddgHits = await this.queryDuckDuckGo(query, limit);
1785
+ if (ddgHits.length > 0) return ddgHits;
1786
+ return [];
1787
+ }
1788
+ async queryBrightData(query, key, limit = 5, options = {}) {
1789
+ try {
1790
+ const zone = options.zone || this.brightDataZone || "cli_unlocker";
1791
+ const engine = options.engine || "bing";
1792
+ let searchUrl = `https://www.bing.com/search?q=${encodeURIComponent(query)}&brd_json=1`;
1793
+ if (engine === "google") {
1794
+ searchUrl = `https://www.google.com/search?q=${encodeURIComponent(query)}&brd_json=1&hl=en&gl=us`;
1795
+ } else if (engine === "yandex") {
1796
+ searchUrl = `https://www.yandex.com/search?q=${encodeURIComponent(query)}&brd_json=1`;
1797
+ }
1798
+ const res = await fetch("https://api.brightdata.com/request", {
1799
+ method: "POST",
1800
+ headers: {
1801
+ Authorization: `Bearer ${key}`,
1802
+ "Content-Type": "application/json"
1803
+ },
1804
+ body: JSON.stringify({
1805
+ zone,
1806
+ url: searchUrl,
1807
+ format: "raw"
1808
+ }),
1809
+ signal: AbortSignal.timeout(15e3)
1810
+ });
1811
+ if (res.ok) {
1812
+ const data = await res.json();
1813
+ const organic = Array.isArray(data?.organic) ? data.organic : [];
1814
+ if (organic.length > 0) {
1815
+ return organic.slice(0, limit).map((r, idx) => ({
1816
+ title: r.title || "Untitled",
1817
+ url: r.link,
1818
+ content: r.description || r.snippet || "",
1819
+ score: r.rank ? 1 / r.rank : 1 / (idx + 1),
1820
+ engine: "brightdata"
1821
+ }));
1822
+ }
1823
+ }
1824
+ } catch (e) {
1825
+ console.warn("[MultiSourceSearchEngine] Bright Data attempt failed:", e?.message || e);
1826
+ }
1827
+ return [];
1828
+ }
1829
+ async querySearxng(query, searxngHost, limit, customHeaders, timeRange) {
1830
+ try {
1831
+ const cleanHost = searxngHost.replace(/\/$/, "");
1832
+ let searchUrl = `${cleanHost}/search?q=${encodeURIComponent(query)}&format=json`;
1833
+ if (timeRange) {
1834
+ searchUrl += `&time_range=${encodeURIComponent(timeRange)}`;
1835
+ }
1836
+ const headers = {
1837
+ "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
1838
+ ...this.searxngHeaders || {},
1839
+ ...customHeaders || {}
1840
+ };
1841
+ const res = await fetch(searchUrl, {
1842
+ headers,
1843
+ signal: AbortSignal.timeout(1e4)
1844
+ });
1845
+ if (res.ok) {
1846
+ const data = await res.json();
1847
+ if (Array.isArray(data?.results) && data.results.length > 0) {
1848
+ return data.results.slice(0, limit).map((r) => ({
1849
+ title: r.title || "Untitled",
1850
+ url: r.url,
1851
+ content: r.content || r.snippet || "",
1852
+ score: r.score,
1853
+ engine: "searxng"
1854
+ }));
1855
+ }
1856
+ }
1857
+ } catch (e) {
1858
+ console.warn("[MultiSourceSearchEngine] SearXNG attempt failed:", e?.message || e);
1859
+ }
1860
+ return [];
1861
+ }
1862
+ async queryExa(query, exaKey, limit, domainFilter, timeRange) {
1863
+ try {
1864
+ const body = {
1865
+ query,
1866
+ numResults: limit,
1867
+ useAutoprompt: true
1868
+ };
1869
+ if (domainFilter && domainFilter.length > 0) {
1870
+ body.includeDomains = domainFilter;
1871
+ }
1872
+ if (timeRange) {
1873
+ const now = /* @__PURE__ */ new Date();
1874
+ if (timeRange === "day") now.setDate(now.getDate() - 1);
1875
+ else if (timeRange === "week") now.setDate(now.getDate() - 7);
1876
+ else if (timeRange === "month") now.setMonth(now.getMonth() - 1);
1877
+ else if (timeRange === "year") now.setFullYear(now.getFullYear() - 1);
1878
+ body.startPublishedDate = now.toISOString();
1879
+ }
1880
+ const res = await fetch("https://api.exa.ai/search", {
1881
+ method: "POST",
1882
+ headers: {
1883
+ "x-api-key": exaKey,
1884
+ "Content-Type": "application/json"
1885
+ },
1886
+ body: JSON.stringify(body),
1887
+ signal: AbortSignal.timeout(1e4)
1888
+ });
1889
+ if (res.ok) {
1890
+ const data = await res.json();
1891
+ if (Array.isArray(data?.results) && data.results.length > 0) {
1892
+ return data.results.map((r) => ({
1893
+ title: r.title || "Untitled",
1894
+ url: r.url,
1895
+ content: r.text || r.snippet || "",
1896
+ score: r.score,
1897
+ engine: "exa"
1898
+ }));
1899
+ }
1900
+ }
1901
+ } catch (e) {
1902
+ console.warn("[MultiSourceSearchEngine] Exa attempt failed:", e?.message || e);
1903
+ }
1904
+ return [];
1905
+ }
1906
+ async querySerper(query, serperKey, limit, timeRange) {
1907
+ try {
1908
+ const body = { q: query, num: limit };
1909
+ if (timeRange) {
1910
+ const tbsMap = { day: "qdr:d", week: "qdr:w", month: "qdr:m", year: "qdr:y" };
1911
+ if (tbsMap[timeRange]) {
1912
+ body.tbs = tbsMap[timeRange];
1913
+ }
1914
+ }
1915
+ const res = await fetch("https://google.serper.dev/search", {
1916
+ method: "POST",
1917
+ headers: {
1918
+ "X-API-KEY": serperKey,
1919
+ "Content-Type": "application/json"
1920
+ },
1921
+ body: JSON.stringify(body),
1922
+ signal: AbortSignal.timeout(1e4)
1923
+ });
1924
+ if (res.ok) {
1925
+ const data = await res.json();
1926
+ if (Array.isArray(data?.organic) && data.organic.length > 0) {
1927
+ return data.organic.slice(0, limit).map((r) => ({
1928
+ title: r.title || "Untitled",
1929
+ url: r.link,
1930
+ content: r.snippet || "",
1931
+ engine: "serper"
1932
+ }));
1933
+ }
1934
+ }
1935
+ } catch (e) {
1936
+ console.warn("[MultiSourceSearchEngine] Serper attempt failed:", e?.message || e);
1937
+ }
1938
+ return [];
1939
+ }
1940
+ async queryDuckDuckGo(query, limit) {
1941
+ try {
1942
+ const ddgUrl = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
1943
+ const res = await fetch(ddgUrl, {
1944
+ headers: { "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" },
1945
+ signal: AbortSignal.timeout(8e3)
1946
+ });
1947
+ if (res.ok) {
1948
+ const html = await res.text();
1949
+ const hits = [];
1950
+ const resultRegex = /<a[^>]*class="result__a"[^>]*>([\s\S]*?)<\/a>[\s\S]*?<a class="result__url" href="([^"]+)">[\s\S]*?<a class="result__snippet[^>]*>([\s\S]*?)<\/a>/g;
1951
+ let match;
1952
+ while ((match = resultRegex.exec(html)) !== null && hits.length < limit) {
1953
+ const rawTitle = match[1]?.replace(/<[^>]+>/g, "").trim() || query;
1954
+ const rawUrl = match[2]?.trim();
1955
+ const cleanUrl = rawUrl?.startsWith("//duckduckgo.com/l/?uddg=") ? decodeURIComponent(rawUrl.split("uddg=")[1]?.split("&")[0] || "") : rawUrl;
1956
+ const snippet = match[3]?.replace(/<[^>]+>/g, "").trim() || "";
1957
+ if (cleanUrl && !cleanUrl.includes("duckduckgo.com")) {
1958
+ hits.push({
1959
+ title: rawTitle,
1960
+ url: cleanUrl,
1961
+ content: snippet,
1962
+ engine: "duckduckgo"
1963
+ });
1964
+ }
1965
+ }
1966
+ if (hits.length > 0) return hits;
1967
+ }
1968
+ } catch (e) {
1969
+ console.warn("[MultiSourceSearchEngine] DuckDuckGo attempt failed:", e?.message || e);
1970
+ }
1971
+ return [];
1972
+ }
1973
+ };
1974
+
1975
+ // src/harvester/noiseFilter.ts
1976
+ var ECOMMERCE_DOMAINS = /* @__PURE__ */ new Set([
1977
+ "shopee.vn",
1978
+ "shopee.com",
1979
+ "lazada.vn",
1980
+ "lazada.com",
1981
+ "tiki.vn",
1982
+ "sendo.vn",
1983
+ "aliexpress.com",
1984
+ "taobao.com",
1985
+ "amazon.com",
1986
+ "ebay.com",
1987
+ "banggood.com"
1988
+ ]);
1989
+ var ECOMMERCE_AND_COMMERCIAL_PATTERNS = [
1990
+ /\b(shopee|lazada|tiki|sendo|taobao|aliexpress)\b/i,
1991
+ /\b(mua ngay|giá tốt|khuyến mãi|freeship|bán chạy|nhập khẩu chính hãng|cửa hàng|bảng giá|đặt hàng)\b/i,
1992
+ /\b(buy now|add to cart|free shipping|discount|best price|on sale|shop now|in stock|order now)\b/i,
1993
+ /\b(\d+[kKđ]|₫|\$\d+|\d+\s*(?:VNĐ|VND|usd))\b/i
1994
+ ];
1995
+ function isCommercialOrNoise(input) {
1996
+ if (input.url) {
1997
+ try {
1998
+ const hostname = new URL(input.url).hostname.toLowerCase().replace(/^www\./, "");
1999
+ if (ECOMMERCE_DOMAINS.has(hostname) || [...ECOMMERCE_DOMAINS].some((d) => hostname.endsWith(`.${d}`))) {
2000
+ return true;
2001
+ }
2002
+ } catch {
2003
+ }
2004
+ }
2005
+ const combined = `${input.title || ""} ${input.snippet || ""}`;
2006
+ if (!combined.trim()) return false;
2007
+ for (const pattern of ECOMMERCE_AND_COMMERCIAL_PATTERNS) {
2008
+ if (pattern.test(combined)) {
2009
+ return true;
2010
+ }
2011
+ }
2012
+ return false;
2013
+ }
2014
+
2015
+ // src/harvester/socialPulseHarvester.ts
2016
+ var SocialPulseHarvester = class {
2017
+ constructor(searchEngine = new MultiSourceSearchEngine()) {
2018
+ this.searchEngine = searchEngine;
2019
+ }
2020
+ async harvest(topic, options = {}) {
2021
+ const recencyDays = Math.max(1, options.recencyDays ?? 30);
2022
+ const limitPerPlatform = options.limitPerPlatform ?? 4;
2023
+ const cutoffMs = Date.now() - recencyDays * 24 * 60 * 60 * 1e3;
2024
+ const cutoffUnixSec = Math.floor(cutoffMs / 1e3);
2025
+ const cutoffIsoDate = new Date(cutoffMs).toISOString().slice(0, 10);
2026
+ const items = [];
2027
+ const seenUrls = /* @__PURE__ */ new Set();
2028
+ const pushUnique = (item) => {
2029
+ const normUrl = item.url.trim().replace(/\/$/, "");
2030
+ if (!normUrl || seenUrls.has(normUrl)) return;
2031
+ seenUrls.add(normUrl);
2032
+ items.push(item);
2033
+ };
2034
+ const tasks = [];
2035
+ if (options.includeHackerNews !== false) {
2036
+ tasks.push(
2037
+ (async () => {
2038
+ try {
2039
+ const params = new URLSearchParams({
2040
+ query: topic,
2041
+ tags: "story",
2042
+ numericFilters: `created_at_i>${cutoffUnixSec}`,
2043
+ hitsPerPage: String(limitPerPlatform)
2044
+ });
2045
+ const res = await fetch(`https://hn.algolia.com/api/v1/search?${params.toString()}`, {
2046
+ headers: { "User-Agent": "OrchableResearchKit/1.3" },
2047
+ signal: AbortSignal.timeout(6500)
2048
+ });
2049
+ if (res.ok) {
2050
+ const data = await res.json();
2051
+ if (Array.isArray(data?.hits)) {
2052
+ for (const hit of data.hits) {
2053
+ const points = Number(hit.points) || 0;
2054
+ const comments = Number(hit.num_comments) || 0;
2055
+ const hnUrl = `https://news.ycombinator.com/item?id=${hit.objectID}`;
2056
+ const targetUrl = hit.url || hnUrl;
2057
+ const score = Math.min(10, Math.max(4, Math.round(4 + Math.log10(points + comments + 1) * 2)));
2058
+ pushUnique({
2059
+ id: `hn-${hit.objectID}`,
2060
+ platform: "hackernews",
2061
+ title: String(hit.title || "HackerNews Discussion"),
2062
+ url: targetUrl,
2063
+ snippet: `${hit.title} (${points} pts, ${comments} comments on HN: ${hnUrl})`,
2064
+ author: hit.author,
2065
+ createdAt: hit.created_at,
2066
+ engagementScore: score,
2067
+ rawMetrics: { points, comments }
2068
+ });
2069
+ }
2070
+ }
2071
+ }
2072
+ } catch (e) {
2073
+ console.warn("[SocialPulseHarvester] HackerNews query failed:", e?.message || e);
2074
+ }
2075
+ })()
2076
+ );
2077
+ }
2078
+ if (options.includeGitHub !== false) {
2079
+ tasks.push(
2080
+ (async () => {
2081
+ try {
2082
+ const q = `${topic} pushed:>=${cutoffIsoDate}`;
2083
+ const params = new URLSearchParams({
2084
+ q,
2085
+ sort: "stars",
2086
+ order: "desc",
2087
+ per_page: String(limitPerPlatform)
2088
+ });
2089
+ const res = await fetch(`https://api.github.com/search/repositories?${params.toString()}`, {
2090
+ headers: {
2091
+ Accept: "application/vnd.github+json",
2092
+ "User-Agent": "OrchableResearchKit/1.3"
2093
+ },
2094
+ signal: AbortSignal.timeout(6500)
2095
+ });
2096
+ if (res.ok) {
2097
+ const data = await res.json();
2098
+ if (Array.isArray(data?.items)) {
2099
+ for (const repo of data.items) {
2100
+ const stars = Number(repo.stargazers_count) || 0;
2101
+ const score = Math.min(10, Math.max(5, Math.round(4 + Math.log10(stars + 1) * 1.8)));
2102
+ pushUnique({
2103
+ id: `gh-${repo.id || repo.full_name}`,
2104
+ platform: "github",
2105
+ title: `${repo.full_name}: ${repo.description || "GitHub Repository"}`.slice(0, 180),
2106
+ url: repo.html_url,
2107
+ snippet: `${repo.description || ""} [Stars: ${stars}, Language: ${repo.language || "N/A"}, Updated: ${String(repo.pushed_at || "").slice(0, 10)}]`.trim(),
2108
+ author: repo.owner?.login,
2109
+ createdAt: repo.pushed_at || repo.created_at,
2110
+ engagementScore: score,
2111
+ rawMetrics: { stars }
2112
+ });
2113
+ }
2114
+ }
2115
+ }
2116
+ } catch (e) {
2117
+ console.warn("[SocialPulseHarvester] GitHub search failed:", e?.message || e);
2118
+ }
2119
+ })()
2120
+ );
2121
+ }
2122
+ if (options.includeRedditWeb !== false) {
2123
+ tasks.push(
2124
+ (async () => {
2125
+ try {
2126
+ const timeRange = recencyDays <= 7 ? "week" : recencyDays <= 35 ? "month" : "year";
2127
+ const hits = await this.searchEngine.search(`${topic} reddit OR community discussion pitfalls`, {
2128
+ limit: limitPerPlatform,
2129
+ timeRange
2130
+ });
2131
+ for (const [idx, h] of hits.entries()) {
2132
+ const isReddit = /reddit\.com/i.test(h.url);
2133
+ pushUnique({
2134
+ id: `pulse-${idx + 1}`,
2135
+ platform: isReddit ? "reddit" : "web",
2136
+ title: h.title,
2137
+ url: h.url,
2138
+ snippet: h.content.slice(0, 350),
2139
+ engagementScore: isReddit ? 7 : 6
2140
+ });
2141
+ }
2142
+ } catch (e) {
2143
+ console.warn("[SocialPulseHarvester] Recency web search failed:", e?.message || e);
2144
+ }
2145
+ })()
2146
+ );
2147
+ }
2148
+ await Promise.allSettled(tasks);
2149
+ items.sort((a, b) => b.engagementScore - a.engagementScore);
2150
+ const trendingReposAndTools = items.filter((i) => i.platform === "github").map((i) => `${i.title} (${i.url})`);
2151
+ const communityHighlights = items.slice(0, 6).map((i) => `[${i.platform.toUpperCase()}] ${i.title}: ${i.snippet}`);
2152
+ const mdLines = [
2153
+ `# \u{1F4E1} Social & Developer Pulse Report (Last ${recencyDays} Days): ${topic}`,
2154
+ `> **Harvested At:** \`${(/* @__PURE__ */ new Date()).toISOString()}\` | **Window:** \`Last ${recencyDays} days\` | **Total Signals:** \`${items.length}\``,
2155
+ `
2156
+ ## 1. Community Signals & Discussions`,
2157
+ ...items.length > 0 ? items.map(
2158
+ (item, idx) => `${idx + 1}. **[${item.platform.toUpperCase()}] [${item.title}](${item.url})** (Score: \`${item.engagementScore}/10\`)
2159
+ - ${item.snippet}`
2160
+ ) : ["- No recent social pulse items found within the specified window."]
2161
+ ];
2162
+ if (trendingReposAndTools.length > 0) {
2163
+ mdLines.push(
2164
+ `
2165
+ ## 2. Active Repositories & Tooling`,
2166
+ ...trendingReposAndTools.map((r) => `- ${r}`)
2167
+ );
2168
+ }
2169
+ return {
2170
+ topic,
2171
+ recencyDays,
2172
+ harvestedAt: (/* @__PURE__ */ new Date()).toISOString(),
2173
+ items,
2174
+ trendingReposAndTools,
2175
+ communityHighlights,
2176
+ markdownReport: mdLines.join("\n")
2177
+ };
2178
+ }
2179
+ };
2180
+
2181
+ // src/harvester/stemResources.ts
2182
+ var PHET_SIMULATIONS = [
2183
+ {
2184
+ id: "phet-circuit-construction-kit-dc",
2185
+ titleEn: "Circuit Construction Kit: DC",
2186
+ titleVi: "B\u1ED9 L\u1EAFp R\xE1p M\u1EA1ch \u0110i\u1EC7n M\u1ED9t Chi\u1EC1u (DC)",
2187
+ descriptionEn: "Build circuits with batteries, light bulbs, resistors, switches, and conductors. Measure voltage and current with voltmeter and ammeter.",
2188
+ descriptionVi: "X\xE2y d\u1EF1ng m\u1EA1ch \u0111i\u1EC7n m\u1ED9t chi\u1EC1u v\u1EDBi pin, b\xF3ng \u0111\xE8n, \u0111i\u1EC7n tr\u1EDF, c\xF4ng t\u1EAFc. \u0110o \u0111i\u1EC7n \xE1p v\xE0 d\xF2ng \u0111i\u1EC7n b\u1EB1ng v\xF4n k\u1EBF v\xE0 ampe k\u1EBF.",
2189
+ simUrl: "https://phet.colorado.edu/sims/html/circuit-construction-kit-dc/latest/circuit-construction-kit-dc_all.html",
2190
+ thumbnailUrl: "https://phet.colorado.edu/sims/html/circuit-construction-kit-dc/latest/circuit-construction-kit-dc-600.png",
2191
+ subject: "electronics",
2192
+ targetLevel: "all",
2193
+ keywords: ["circuit", "m\u1EA1ch \u0111i\u1EC7n", "\u0111i\u1EC7n tr\u1EDF", "resistor", "pin", "battery", "led", "voltage", "current", "d\xF2ng \u0111i\u1EC7n", "hi\u1EC7u \u0111i\u1EC7n th\u1EBF", "ohm", "\u0111o \u0111i\u1EC7n"]
2194
+ },
2195
+ {
2196
+ id: "phet-wave-on-a-string",
2197
+ titleEn: "Wave on a String",
2198
+ titleVi: "S\xF3ng Tr\xEAn D\xE2y",
2199
+ descriptionEn: "Simulate mechanical wave pulse and periodic oscillations. Adjust frequency, amplitude, tension, and damping.",
2200
+ descriptionVi: "M\xF4 ph\u1ECFng s\xF3ng c\u01A1 h\u1ECDc tr\xEAn d\xE2y. \u0110i\u1EC1u ch\u1EC9nh t\u1EA7n s\u1ED1, bi\xEAn \u0111\u1ED9, l\u1EF1c c\u0103ng v\xE0 \u0111\u1ED9 suy gi\u1EA3m.",
2201
+ simUrl: "https://phet.colorado.edu/sims/html/wave-on-a-string/latest/wave-on-a-string_all.html",
2202
+ thumbnailUrl: "https://phet.colorado.edu/sims/html/wave-on-a-string/latest/wave-on-a-string-600.png",
2203
+ subject: "physics",
2204
+ targetLevel: "lower_secondary",
2205
+ keywords: ["wave", "s\xF3ng", "t\u1EA7n s\u1ED1", "frequency", "bi\xEAn \u0111\u1ED9", "amplitude", "sound", "\xE2m thanh", "si\xEAu \xE2m", "ultrasonic"]
2206
+ },
2207
+ {
2208
+ id: "phet-balloons-and-static-electricity",
2209
+ titleEn: "Balloons and Static Electricity",
2210
+ titleVi: "B\xF3ng Bay v\xE0 T\u0129nh \u0110i\u1EC7n",
2211
+ descriptionEn: "Explore electrical charges, attraction, repulsion, and static electricity by rubbing a balloon on a sweater.",
2212
+ descriptionVi: "Kh\xE1m ph\xE1 \u0111i\u1EC7n t\xEDch, l\u1EF1c h\xFAt, l\u1EF1c \u0111\u1EA9y v\xE0 hi\u1EC7n t\u01B0\u1EE3ng t\u0129nh \u0111i\u1EC7n qua qu\u1EA3 b\xF3ng bay v\xE0 \xE1o len.",
2213
+ simUrl: "https://phet.colorado.edu/sims/html/balloons-and-static-electricity/latest/balloons-and-static-electricity_all.html",
2214
+ thumbnailUrl: "https://phet.colorado.edu/sims/html/balloons-and-static-electricity/latest/balloons-and-static-electricity-600.png",
2215
+ subject: "physics",
2216
+ targetLevel: "primary",
2217
+ keywords: ["static electricity", "t\u0129nh \u0111i\u1EC7n", "\u0111i\u1EC7n t\xEDch", "electron", "charge", "l\u1EF1c \u0111i\u1EC7n", "h\xFAt \u0111\u1EA9y"]
2218
+ },
2219
+ {
2220
+ id: "phet-faradays-law",
2221
+ titleEn: "Faraday's Law & Electromagnetic Induction",
2222
+ titleVi: "\u0110\u1ECBnh Lu\u1EADt Faraday & C\u1EA3m \u1EE8ng \u0110i\u1EC7n T\u1EEB",
2223
+ descriptionEn: "Move a bar magnet through a coil of wire to generate an electric current and illuminate a bulb. Observe magnet direction and voltage.",
2224
+ descriptionVi: "Di chuy\u1EC3n nam ch\xE2m qua cu\u1ED9n d\xE2y \u0111\u1EC3 t\u1EA1o ra d\xF2ng \u0111i\u1EC7n c\u1EA3m \u1EE9ng l\xE0m s\xE1ng b\xF3ng \u0111\xE8n. Quan s\xE1t chi\u1EC1u d\xF2ng \u0111i\u1EC7n v\xE0 c\u1EF1c t\u1EEB.",
2225
+ simUrl: "https://phet.colorado.edu/sims/html/faradays-law/latest/faradays-law_all.html",
2226
+ thumbnailUrl: "https://phet.colorado.edu/sims/html/faradays-law/latest/faradays-law-600.png",
2227
+ subject: "electronics",
2228
+ targetLevel: "upper_secondary",
2229
+ keywords: ["faraday", "c\u1EA3m \u1EE9ng \u0111i\u1EC7n t\u1EEB", "nam ch\xE2m", "magnet", "cu\u1ED9n d\xE2y", "coil", "\u0111\u1ED9ng c\u01A1", "motor", "m\xE1y ph\xE1t \u0111i\u1EC7n", "generator"]
2230
+ },
2231
+ {
2232
+ id: "phet-color-vision",
2233
+ titleEn: "Color Vision (RGB & Light Filters)",
2234
+ titleVi: "Th\u1ECB Gi\xE1c M\xE0u (Ph\u1ED1i M\xE0u RGB & B\u1ED9 L\u1ECDc \xC1nh S\xE1ng)",
2235
+ descriptionEn: "Combine red, green, and blue light sources to create full spectrum colors. Ideal for teaching RGB LEDs, sensors, and display screens.",
2236
+ descriptionVi: "K\u1EBFt h\u1EE3p c\xE1c ngu\u1ED3n s\xE1ng \u0110\u1ECF (Red), Xanh l\u1EE5c (Green), Xanh lam (Blue) \u0111\u1EC3 t\u1EA1o ra c\xE1c d\u1EA3i m\xE0u. R\u1EA5t ph\xF9 h\u1EE3p khi d\u1EA1y LED RGB v\xE0 c\u1EA3m bi\u1EBFn m\xE0u.",
2237
+ simUrl: "https://phet.colorado.edu/sims/html/color-vision/latest/color-vision_all.html",
2238
+ thumbnailUrl: "https://phet.colorado.edu/sims/html/color-vision/latest/color-vision-600.png",
2239
+ subject: "physics",
2240
+ targetLevel: "all",
2241
+ keywords: ["color", "m\xE0u s\u1EAFc", "rgb", "led rgb", "\xE1nh s\xE1ng", "light", "c\u1EA3m bi\u1EBFn \xE1nh s\xE1ng", "ldr", "quang h\u1ECDc", "optics"]
2242
+ },
2243
+ {
2244
+ id: "phet-forces-and-motion-basics",
2245
+ titleEn: "Forces and Motion: Basics",
2246
+ titleVi: "L\u1EF1c v\xE0 Chuy\u1EC3n \u0110\u1ED9ng C\u01A1 B\u1EA3n",
2247
+ descriptionEn: "Explore the forces at work when tugging a crate, sliding on ice, or pushing objects. Observe friction, acceleration, and Newton laws.",
2248
+ descriptionVi: "Kh\xE1m ph\xE1 c\xE1c l\u1EF1c t\xE1c d\u1EE5ng khi k\xE9o th\xF9ng h\xE0ng, ma s\xE1t, gia t\u1ED1c v\xE0 \u0111\u1ECBnh lu\u1EADt Newton. C\u1ED1t l\xF5i cho robot di \u0111\u1ED9ng v\xE0 xe t\u1EF1 h\xE0nh.",
2249
+ simUrl: "https://phet.colorado.edu/sims/html/forces-and-motion-basics/latest/forces-and-motion-basics_all.html",
2250
+ thumbnailUrl: "https://phet.colorado.edu/sims/html/forces-and-motion-basics/latest/forces-and-motion-basics-600.png",
2251
+ subject: "physics",
2252
+ targetLevel: "all",
2253
+ keywords: ["force", "l\u1EF1c", "motion", "chuy\u1EC3n \u0111\u1ED9ng", "friction", "ma s\xE1t", "robotics", "xe t\u1EF1 h\xE0nh", "newton", "v\u1EADn t\u1ED1c", "gia t\u1ED1c"]
2254
+ },
2255
+ {
2256
+ id: "phet-gravity-and-orbits",
2257
+ titleEn: "Gravity and Orbits",
2258
+ titleVi: "L\u1EF1c H\u1EA5p D\u1EABn v\xE0 Qu\u1EF9 \u0110\u1EA1o V\u1EC7 Tinh",
2259
+ descriptionEn: "Move the sun, earth, moon and space station to see how gravity controls orbital velocity and gravitational pull.",
2260
+ descriptionVi: "Di chuy\u1EC3n M\u1EB7t Tr\u1EDDi, Tr\xE1i \u0110\u1EA5t, M\u1EB7t Tr\u0103ng v\xE0 tr\u1EA1m kh\xF4ng gian \u0111\u1EC3 xem l\u1EF1c h\u1EA5p d\u1EABn \u0111i\u1EC1u khi\u1EC3n qu\u1EF9 \u0111\u1EA1o v\xE0 v\u1EADn t\u1ED1c.",
2261
+ simUrl: "https://phet.colorado.edu/sims/html/gravity-and-orbits/latest/gravity-and-orbits_all.html",
2262
+ thumbnailUrl: "https://phet.colorado.edu/sims/html/gravity-and-orbits/latest/gravity-and-orbits-600.png",
2263
+ subject: "physics",
2264
+ targetLevel: "lower_secondary",
2265
+ keywords: ["gravity", "tr\u1ECDng l\u1EF1c", "l\u1EF1c h\u1EA5p d\u1EABn", "qu\u1EF9 \u0111\u1EA1o", "orbit", "nasa", "kh\xF4ng gian", "space", "v\u1EC7 tinh", "satellite", "earth", "moon"]
2266
+ },
2267
+ {
2268
+ id: "phet-projectile-motion",
2269
+ titleEn: "Projectile Motion",
2270
+ titleVi: "Chuy\u1EC3n \u0110\u1ED9ng N\xE9m Ngang & N\xE9m Xi\xEAn",
2271
+ descriptionEn: "Blast cannonballs, baseballs, or pianos. Adjust launch angle, initial speed, mass, and air resistance to hit targets.",
2272
+ descriptionVi: "B\u1EAFn \u0111\u1EA1i b\xE1c, b\xF3ng ch\xE0y ho\u1EB7c \u0111\xE0n piano. \u0110i\u1EC1u ch\u1EC9nh g\xF3c b\u1EAFn, v\u1EADn t\u1ED1c \u0111\u1EA7u v\xE0 l\u1EF1c c\u1EA3n kh\xF4ng kh\xED. C\u1EF1c k\u1EF3 h\u1EEFu \xEDch cho l\u1EADp tr\xECnh game v\u1EADt l\xFD.",
2273
+ simUrl: "https://phet.colorado.edu/sims/html/projectile-motion/latest/projectile-motion_all.html",
2274
+ thumbnailUrl: "https://phet.colorado.edu/sims/html/projectile-motion/latest/projectile-motion-600.png",
2275
+ subject: "physics",
2276
+ targetLevel: "upper_secondary",
2277
+ keywords: ["projectile", "n\xE9m xi\xEAn", "qu\u1EF9 \u0111\u1EA1o", "trajectory", "game physics", "v\u1EADt l\xFD tr\xF2 ch\u01A1i", "v\u1EADn t\u1ED1c", "g\xF3c b\u1EAFn"]
2278
+ }
2279
+ ];
2280
+ var OpenverseClient = class {
2281
+ baseUrl = "https://api.openverse.org/v1";
2282
+ async searchImages(query, options = {}) {
2283
+ try {
2284
+ const limit = Math.min(options.limit ?? 5, 20);
2285
+ const params = new URLSearchParams({
2286
+ q: query,
2287
+ page_size: String(limit)
2288
+ });
2289
+ if (options.license) {
2290
+ params.set("license", options.license);
2291
+ }
2292
+ const res = await fetch(`${this.baseUrl}/images/?${params.toString()}`, {
2293
+ headers: {
2294
+ "User-Agent": "CurriculumStudio-ResearchKit/1.2.2",
2295
+ Accept: "application/json"
2296
+ },
2297
+ signal: AbortSignal.timeout(8e3)
2298
+ });
2299
+ if (!res.ok) return [];
2300
+ const data = await res.json();
2301
+ const results = Array.isArray(data?.results) ? data.results : [];
2302
+ return results.map((item) => {
2303
+ const licenseType = (item.license || "CC").toUpperCase();
2304
+ const licenseVer = item.license_version ? ` ${item.license_version}` : "";
2305
+ const creator = item.creator ? ` b\u1EDFi ${item.creator}` : "";
2306
+ return {
2307
+ id: `openverse-${item.id}`,
2308
+ title: item.title || `H\xECnh \u1EA3nh minh h\u1ECDa: ${query}`,
2309
+ url: item.foreign_landing_url || item.url,
2310
+ description: `H\xECnh \u1EA3nh gi\u1EA5y ph\xE9p m\u1EDF (${licenseType}${licenseVer})${creator} t\u1EEB ngu\u1ED3n ${item.source || item.provider || "Openverse"}.`,
2311
+ type: "media_image",
2312
+ provider: "openverse",
2313
+ thumbnailUrl: item.thumbnail || item.url,
2314
+ mediaType: "image",
2315
+ license: {
2316
+ type: `${licenseType}${licenseVer}`,
2317
+ attributionText: `\u1EA2nh: "${item.title || query}"${creator} (${licenseType}${licenseVer}) via Openverse.`,
2318
+ url: item.license_url,
2319
+ commercialUseAllowed: !licenseType.includes("NC")
2320
+ },
2321
+ subject: "general_stem",
2322
+ targetLevel: "all",
2323
+ tags: Array.isArray(item.tags) ? item.tags.slice(0, 5).map((t) => t.name || String(t)) : [query],
2324
+ relevanceScore: 8.5
2325
+ };
2326
+ });
2327
+ } catch (e) {
2328
+ console.warn("[OpenverseClient] Kh\xF4ng th\u1EC3 t\xECm ki\u1EBFm media Openverse:", e?.message || e);
2329
+ return [];
2330
+ }
2331
+ }
2332
+ };
2333
+ var NasaMediaClient = class {
2334
+ baseUrl = "https://images-api.nasa.gov";
2335
+ async search(query, options = {}) {
2336
+ try {
2337
+ const limit = Math.min(options.limit ?? 5, 20);
2338
+ const mediaType = options.mediaType || "image";
2339
+ const params = new URLSearchParams({
2340
+ q: query,
2341
+ media_type: mediaType,
2342
+ page_size: String(limit)
2343
+ });
2344
+ const res = await fetch(`${this.baseUrl}/search?${params.toString()}`, {
2345
+ headers: {
2346
+ "User-Agent": "CurriculumStudio-ResearchKit/1.2.2",
2347
+ Accept: "application/json"
2348
+ },
2349
+ signal: AbortSignal.timeout(8e3)
2350
+ });
2351
+ if (!res.ok) return [];
2352
+ const data = await res.json();
2353
+ const items = Array.isArray(data?.collection?.items) ? data.collection.items : [];
2354
+ return items.slice(0, limit).map((item) => {
2355
+ const meta = Array.isArray(item.data) && item.data[0] ? item.data[0] : {};
2356
+ const link = Array.isArray(item.links) && item.links[0] ? item.links[0] : {};
2357
+ const title = meta.title || `NASA Media: ${query}`;
2358
+ const desc = (meta.description || meta.caption || "").slice(0, 220);
2359
+ const nasaId = meta.nasa_id || item.href;
2360
+ const actualMediaType = meta.media_type === "video" ? "video" : "image";
2361
+ return {
2362
+ id: `nasa-${nasaId}`,
2363
+ title,
2364
+ url: `https://images.nasa.gov/details/${encodeURIComponent(nasaId)}`,
2365
+ description: desc || `T\u01B0 li\u1EC7u khoa h\u1ECDc v\u0169 tr\u1EE5, v\u1EC7 tinh v\xE0 k\u1EF9 thu\u1EADt kh\xF4ng gian t\u1EEB NASA.`,
2366
+ type: actualMediaType === "video" ? "media_video" : "media_image",
2367
+ provider: "nasa",
2368
+ thumbnailUrl: link.href,
2369
+ mediaType: actualMediaType,
2370
+ license: {
2371
+ type: "Public Domain (NASA Media Guidelines)",
2372
+ attributionText: `T\u01B0 li\u1EC7u khoa h\u1ECDc t\u1EEB NASA (ID: ${nasaId}). S\u1EED d\u1EE5ng t\u1EF1 do cho m\u1EE5c \u0111\xEDch gi\xE1o d\u1EE5c.`,
2373
+ url: "https://www.nasa.gov/multimedia/guidelines/index.html",
2374
+ commercialUseAllowed: true
2375
+ },
2376
+ subject: "physics",
2377
+ targetLevel: "all",
2378
+ tags: Array.isArray(meta.keywords) ? meta.keywords.slice(0, 5) : ["nasa", "space", "stem"],
2379
+ relevanceScore: 9
2380
+ };
2381
+ });
2382
+ } catch (e) {
2383
+ console.warn("[NasaMediaClient] L\u1ED7i t\xECm ki\u1EBFm NASA media:", e?.message || e);
2384
+ return [];
2385
+ }
2386
+ }
2387
+ };
2388
+ var GitHubCurriculumClient = class {
2389
+ baseUrl = "https://api.github.com";
2390
+ async searchCurricula(query, options = {}) {
2391
+ try {
2392
+ const limit = Math.min(options.limit ?? 5, 10);
2393
+ const q = `${query} curriculum in:name,description,topics`;
2394
+ const params = new URLSearchParams({
2395
+ q,
2396
+ sort: "stars",
2397
+ order: "desc",
2398
+ per_page: String(limit)
2399
+ });
2400
+ const headers = {
2401
+ "User-Agent": "CurriculumStudio-ResearchKit/1.2.2",
2402
+ Accept: "application/vnd.github.v3+json"
2403
+ };
2404
+ if (options.token || process.env.GITHUB_TOKEN) {
2405
+ headers["Authorization"] = `token ${options.token || process.env.GITHUB_TOKEN}`;
2406
+ }
2407
+ const res = await fetch(`${this.baseUrl}/search/repositories?${params.toString()}`, {
2408
+ headers,
2409
+ signal: AbortSignal.timeout(8e3)
2410
+ });
2411
+ if (!res.ok) return [];
2412
+ const data = await res.json();
2413
+ const items = Array.isArray(data?.items) ? data.items : [];
2414
+ return items.map((repo) => {
2415
+ const licenseName = repo.license?.name || repo.license?.spdx_id || "Open Source";
2416
+ return {
2417
+ id: `github-${repo.id}`,
2418
+ title: `${repo.name} (${repo.stargazers_count.toLocaleString()} \u2B50)`,
2419
+ url: repo.html_url,
2420
+ description: repo.description || `Gi\xE1o tr\xECnh v\xE0 m\xE3 ngu\u1ED3n m\u1EDF tr\xEAn GitHub b\u1EDFi ${repo.owner?.login}.`,
2421
+ type: "curriculum",
2422
+ provider: "github",
2423
+ mediaType: "code",
2424
+ license: {
2425
+ type: licenseName,
2426
+ attributionText: `Gi\xE1o tr\xECnh m\u1EDF t\u1EEB repo "${repo.full_name}" tr\xEAn GitHub (${licenseName}).`,
2427
+ url: repo.license?.url || repo.html_url,
2428
+ commercialUseAllowed: !licenseName.toLowerCase().includes("non-commercial")
2429
+ },
2430
+ subject: "computer_science",
2431
+ targetLevel: "upper_secondary",
2432
+ tags: Array.isArray(repo.topics) ? repo.topics.slice(0, 5) : ["curriculum", "education", "programming"],
2433
+ relevanceScore: Math.min(10, 7 + Math.log10(Math.max(1, repo.stargazers_count)) * 0.7)
2434
+ };
2435
+ });
2436
+ } catch (e) {
2437
+ console.warn("[GitHubCurriculumClient] L\u1ED7i t\xECm ki\u1EBFm GitHub curriculum:", e?.message || e);
2438
+ return [];
2439
+ }
2440
+ }
2441
+ };
2442
+ var CURATED_OER_PROGRAMS = [
2443
+ {
2444
+ id: "cs-unplugged-algorithms",
2445
+ title: "CS Unplugged: H\u1ECDc Khoa H\u1ECDc M\xE1y T\xEDnh Kh\xF4ng C\u1EA7n M\xE1y T\xEDnh",
2446
+ url: "https://www.csunplugged.org/en/",
2447
+ description: "B\u1ED9 ho\u1EA1t \u0111\u1ED9ng offline gi\u1EA3ng d\u1EA1y thu\u1EADt to\xE1n, h\u1EC7 nh\u1ECB ph\xE2n, c\u1EA5u tr\xFAc d\u1EEF li\u1EC7u qua tr\xF2 ch\u01A1i \u0111\xF3ng vai, x\u1EBFp h\xECnh v\xE0 b\xE0i t\u1EADp nh\xF3m.",
2448
+ type: "hands_on_lab",
2449
+ provider: "cs_unplugged",
2450
+ subject: "computer_science",
2451
+ targetLevel: "primary",
2452
+ keywords: ["unplugged", "kh\xF4ng d\xF9ng m\xE1y", "thu\u1EADt to\xE1n", "nh\u1ECB ph\xE2n", "binary", "sorting", "s\u1EAFp x\u1EBFp", "tr\u1EBB em", "kids", "logic"],
2453
+ licenseType: "Creative Commons CC BY-NC-SA 4.0"
2454
+ },
2455
+ {
2456
+ id: "scratch-mit-studio",
2457
+ title: "Scratch MIT: M\xF4i Tr\u01B0\u1EDDng L\u1EADp Tr\xECnh Kh\u1ED1i & S\xE1ng T\u1EA1o Tr\u1EF1c Quan",
2458
+ url: "https://scratch.mit.edu/",
2459
+ description: "N\u1EC1n t\u1EA3ng l\u1EADp tr\xECnh kh\u1ED1i do MIT Media Lab ph\xE1t tri\u1EC3n, th\xEDch h\u1EE3p l\xE0m quen v\u1EDBi t\u01B0 duy bi\u1EBFn s\u1ED1, r\u1EBD nh\xE1nh, v\xF2ng l\u1EB7p v\xE0 s\u1EF1 ki\u1EC7n \xE2m thanh/h\xECnh \u1EA3nh.",
2460
+ type: "curriculum",
2461
+ provider: "scratch",
2462
+ subject: "computer_science",
2463
+ targetLevel: "primary",
2464
+ keywords: ["scratch", "blockly", "l\u1EADp tr\xECnh kh\u1ED1i", "k\xE9o th\u1EA3", "game 2d", "ho\u1EA1t h\xECnh", "tr\u1EBB em", "mit scratch"],
2465
+ licenseType: "Free & Open Educational Platform"
2466
+ },
2467
+ {
2468
+ id: "freecodecamp-responsive-web",
2469
+ title: "freeCodeCamp: L\u1ED9 Tr\xECnh L\u1EADp Tr\xECnh D\u1EF1 \xC1n Th\u1EF1c Chi\u1EBFn Mi\u1EC5n Ph\xED",
2470
+ url: "https://www.freecodecamp.org/learn",
2471
+ description: "H\xE0ng ng\xE0n gi\u1EDD b\xE0i h\u1ECDc t\u01B0\u01A1ng t\xE1c t\u1EEB c\u01A1 b\u1EA3n \u0111\u1EBFn n\xE2ng cao: HTML/CSS, JavaScript, Python, C\u1EA5u tr\xFAc d\u1EEF li\u1EC7u v\xE0 AI.",
2472
+ type: "curriculum",
2473
+ provider: "web",
2474
+ subject: "computer_science",
2475
+ targetLevel: "upper_secondary",
2476
+ keywords: ["freecodecamp", "web", "javascript", "python", "html", "css", "l\u1EADp tr\xECnh web", "ch\u1EE9ng ch\u1EC9 mi\u1EC5n ph\xED"],
2477
+ licenseType: "Creative Commons CC BY-SA 4.0 / Open Source"
2478
+ },
2479
+ {
2480
+ id: "the-odin-project-fullstack",
2481
+ title: "The Odin Project: L\u1ED9 Tr\xECnh Full-Stack Web Open Source",
2482
+ url: "https://www.theodinproject.com/",
2483
+ description: "Curriculum h\u1ECDc ph\xE1t tri\u1EC3n web b\xE0i b\u1EA3n theo chu\u1EA9n c\xF4ng nghi\u1EC7p: Git, CLI, HTML/CSS, JavaScript hi\u1EC7n \u0111\u1EA1i, Node.js v\xE0 React.",
2484
+ type: "curriculum",
2485
+ provider: "web",
2486
+ subject: "computer_science",
2487
+ targetLevel: "developer",
2488
+ keywords: ["odin project", "fullstack", "git", "github", "frontend", "backend", "react", "web developer"],
2489
+ licenseType: "Open Source Curriculum"
2490
+ },
2491
+ {
2492
+ id: "openstax-physics-volume-1",
2493
+ title: "OpenStax: S\xE1ch Gi\xE1o Tr\xECnh V\u1EADt L\xFD \u0110\u1EA1i H\u1ECDc & Ph\u1ED5 Th\xF4ng M\u1EDF",
2494
+ url: "https://openstax.org/subjects/science",
2495
+ description: "S\xE1ch gi\xE1o khoa s\u1ED1 chu\u1EA9n h\u1ECDc thu\u1EADt \u0111\u01B0\u1EE3c b\xECnh duy\u1EC7t \u0111\u1ED9c l\u1EADp, bao g\u1ED3m C\u01A1 h\u1ECDc, S\xF3ng, \u0110i\u1EC7n t\u1EEB h\u1ECDc v\xE0 Quang h\u1ECDc.",
2496
+ type: "textbook",
2497
+ provider: "openstax",
2498
+ subject: "physics",
2499
+ targetLevel: "upper_secondary",
2500
+ keywords: ["openstax", "gi\xE1o tr\xECnh", "s\xE1ch gi\xE1o khoa", "v\u1EADt l\xFD", "physics", "c\u01A1 h\u1ECDc", "\u0111i\u1EC7n t\u1EEB", "s\xE1ch m\u1EDF"],
2501
+ licenseType: "Creative Commons CC BY 4.0"
2502
+ },
2503
+ {
2504
+ id: "exercism-coding-practice",
2505
+ title: "Exercism: Luy\u1EC7n T\u1EADp T\u01B0 Duy Thu\u1EADt To\xE1n & Code Review \u0110a Ng\xF4n Ng\u1EEF",
2506
+ url: "https://exercism.org/",
2507
+ description: "H\u01A1n 70 ng\xF4n ng\u1EEF l\u1EADp tr\xECnh (Python, C++, Rust, Swift, JavaScript) v\u1EDBi l\u1ED9 tr\xECnh b\xE0i t\u1EADp r\xE8n luy\u1EC7n c\xFA ph\xE1p v\xE0 phong c\xE1ch m\xE3 ngu\u1ED3n chu\u1EA9n.",
2508
+ type: "problem_set",
2509
+ provider: "exercism",
2510
+ subject: "computer_science",
2511
+ targetLevel: "developer",
2512
+ keywords: ["exercism", "thu\u1EADt to\xE1n", "luy\u1EC7n code", "b\xE0i t\u1EADp l\u1EADp tr\xECnh", "c++", "python", "swift", "clean code"],
2513
+ licenseType: "Open Source & Free Non-profit Education"
2514
+ }
2515
+ ];
2516
+ var StemResourceResearcher = class {
2517
+ openverse = new OpenverseClient();
2518
+ nasa = new NasaMediaClient();
2519
+ github = new GitHubCurriculumClient();
2520
+ async findResources(query, options = {}) {
2521
+ const limit = options.limit ?? 10;
2522
+ const rawTypes = options.types && options.types.length > 0 ? options.types : ["simulation", "curriculum", "media_image", "media_video", "hands_on_lab", "textbook", "problem_set"];
2523
+ const requestedTypes = /* @__PURE__ */ new Set();
2524
+ for (const t of rawTypes) {
2525
+ if (t === "interactive") {
2526
+ requestedTypes.add("simulation");
2527
+ requestedTypes.add("hands_on_lab");
2528
+ } else if (t === "open_media") {
2529
+ requestedTypes.add("media_image");
2530
+ requestedTypes.add("media_video");
2531
+ } else {
2532
+ requestedTypes.add(t);
2533
+ }
2534
+ }
2535
+ const lowerQuery = query.toLowerCase();
2536
+ const queryTokens = lowerQuery.split(/\s+/).filter((t) => t.length > 1);
2537
+ const matches = [];
2538
+ if (requestedTypes.has("simulation")) {
2539
+ for (const sim of PHET_SIMULATIONS) {
2540
+ let score = 0;
2541
+ for (const token of queryTokens) {
2542
+ if (sim.keywords.some((k) => k.toLowerCase().includes(token))) score += 2;
2543
+ if (sim.titleEn.toLowerCase().includes(token) || sim.titleVi.toLowerCase().includes(token)) score += 3;
2544
+ if (sim.descriptionEn.toLowerCase().includes(token) || sim.descriptionVi.toLowerCase().includes(token)) score += 1;
2545
+ }
2546
+ if (score > 0) {
2547
+ matches.push({
2548
+ id: sim.id,
2549
+ title: `${sim.titleVi} (${sim.titleEn})`,
2550
+ url: sim.simUrl,
2551
+ description: sim.descriptionVi,
2552
+ type: "simulation",
2553
+ provider: "phet",
2554
+ thumbnailUrl: sim.thumbnailUrl,
2555
+ embedUrl: sim.simUrl,
2556
+ mediaType: "interactive",
2557
+ license: {
2558
+ type: "Creative Commons CC BY 4.0",
2559
+ attributionText: `M\xF4 ph\u1ECFng PhET Interactive Simulations, University of Colorado Boulder (https://phet.colorado.edu). CC BY 4.0.`,
2560
+ url: "https://phet.colorado.edu/en/licensing",
2561
+ commercialUseAllowed: true
2562
+ },
2563
+ subject: sim.subject,
2564
+ targetLevel: sim.targetLevel,
2565
+ tags: ["phet", "simulation", sim.subject, ...sim.keywords.slice(0, 3)],
2566
+ relevanceScore: Math.min(10, 7.5 + score * 0.4)
2567
+ });
2568
+ }
2569
+ }
2570
+ }
2571
+ for (const prog of CURATED_OER_PROGRAMS) {
2572
+ if (!requestedTypes.has(prog.type)) continue;
2573
+ let score = 0;
2574
+ for (const token of queryTokens) {
2575
+ if (prog.keywords.some((k) => k.toLowerCase().includes(token))) score += 2;
2576
+ if (prog.title.toLowerCase().includes(token)) score += 3;
2577
+ if (prog.description.toLowerCase().includes(token)) score += 1;
2578
+ }
2579
+ if (score > 0) {
2580
+ matches.push({
2581
+ id: prog.id,
2582
+ title: prog.title,
2583
+ url: prog.url,
2584
+ description: prog.description,
2585
+ type: prog.type,
2586
+ provider: prog.provider,
2587
+ mediaType: prog.type === "hands_on_lab" || prog.type === "curriculum" ? "text" : "code",
2588
+ license: {
2589
+ type: prog.licenseType,
2590
+ attributionText: `T\xE0i nguy\xEAn gi\xE1o d\u1EE5c m\u1EDF t\u1EEB ${prog.provider.toUpperCase()} (${prog.licenseType}).`,
2591
+ commercialUseAllowed: !prog.licenseType.includes("NC")
2592
+ },
2593
+ subject: prog.subject,
2594
+ targetLevel: prog.targetLevel,
2595
+ tags: [prog.provider, prog.type, ...prog.keywords.slice(0, 3)],
2596
+ relevanceScore: Math.min(10, 7 + score * 0.4)
2597
+ });
2598
+ }
2599
+ }
2600
+ const asyncTasks = [];
2601
+ if (requestedTypes.has("media_image")) {
2602
+ asyncTasks.push(this.openverse.searchImages(query, { limit: 4 }));
2603
+ }
2604
+ if (requestedTypes.has("media_image") || requestedTypes.has("media_video")) {
2605
+ const isSpaceOrPhysics = /(vũ trụ|space|physics|vật lý|quỹ đạo|orbit|sensor|cảm biến|robot|nasa|trọng lực|gravity|earth|solar)/i.test(query);
2606
+ if (isSpaceOrPhysics) {
2607
+ asyncTasks.push(this.nasa.search(query, { limit: 3 }));
2608
+ }
2609
+ }
2610
+ if (requestedTypes.has("curriculum")) {
2611
+ asyncTasks.push(this.github.searchCurricula(query, { limit: 3, token: options.githubToken }));
2612
+ }
2613
+ const asyncResults = await Promise.allSettled(asyncTasks);
2614
+ for (const r of asyncResults) {
2615
+ if (r.status === "fulfilled" && Array.isArray(r.value)) {
2616
+ matches.push(...r.value);
2617
+ }
2618
+ }
2619
+ let filtered = matches;
2620
+ if (options.licenseFilter === "creative_commons") {
2621
+ filtered = filtered.filter((item) => /cc\s*by|creative\s*commons|cc0/i.test(item.license.type));
2622
+ } else if (options.licenseFilter === "public_domain") {
2623
+ filtered = filtered.filter((item) => /public\s*domain|cc0/i.test(item.license.type));
2624
+ }
2625
+ const seen = /* @__PURE__ */ new Set();
2626
+ const deduped = [];
2627
+ for (const item of filtered) {
2628
+ const key = item.url || item.id;
2629
+ if (seen.has(key)) continue;
2630
+ seen.add(key);
2631
+ deduped.push(item);
2632
+ }
2633
+ deduped.sort((a, b) => b.relevanceScore - a.relevanceScore);
2634
+ const topResults = deduped.slice(0, limit);
2635
+ const categoryCounts = {
2636
+ simulation: 0,
2637
+ curriculum: 0,
2638
+ media_image: 0,
2639
+ media_video: 0,
2640
+ hands_on_lab: 0,
2641
+ textbook: 0,
2642
+ problem_set: 0
2643
+ };
2644
+ for (const item of topResults) {
2645
+ if (categoryCounts[item.type] !== void 0) {
2646
+ categoryCounts[item.type]++;
2647
+ }
2648
+ }
2649
+ const markdownSummary = this.generateMarkdownSummary(query, topResults);
2650
+ return {
2651
+ query,
2652
+ totalFound: topResults.length,
2653
+ categoryCounts,
2654
+ resources: topResults,
2655
+ items: topResults,
2656
+ markdownSummary,
2657
+ markdownReport: markdownSummary
2658
+ };
2659
+ }
2660
+ async searchAndCatalog(query, options = {}) {
2661
+ return this.findResources(query, options);
2662
+ }
2663
+ generateMarkdown(catalog) {
2664
+ return catalog.markdownSummary;
2665
+ }
2666
+ generateMarkdownSummary(query, items) {
2667
+ if (items.length === 0) {
2668
+ return `Kh\xF4ng t\xECm th\u1EA5y t\xE0i nguy\xEAn gi\xE1o d\u1EE5c m\u1EDF ph\xF9 h\u1EE3p cho ch\u1EE7 \u0111\u1EC1: "${query}".`;
2669
+ }
2670
+ const sections = [`### \u{1F52C} Danh m\u1EE5c T\xE0i nguy\xEAn STEM & L\u1EADp tr\xECnh cho "${query}"
2671
+ `];
2672
+ const typeLabels = {
2673
+ simulation: "\u{1F3AE} M\xF4 ph\u1ECFng T\u01B0\u01A1ng t\xE1c (PhET / Labs)",
2674
+ curriculum: "\u{1F4DA} Gi\xE1o tr\xECnh & L\u1ED9 tr\xECnh M\u1EDF",
2675
+ media_image: "\u{1F5BC}\uFE0F H\xECnh \u1EA3nh & S\u01A1 \u0111\u1ED3 Gi\u1EA5y ph\xE9p M\u1EDF (CC / Public Domain)",
2676
+ media_video: "\u{1F3AC} Video & T\u01B0 li\u1EC7u Khoa h\u1ECDc",
2677
+ hands_on_lab: "\u{1F9EA} Ho\u1EA1t \u0111\u1ED9ng Th\u1EF1c h\xE0nh & Kh\xE1m ph\xE1 (Hands-on)",
2678
+ textbook: "\u{1F4D6} S\xE1ch Gi\xE1o tr\xECnh M\u1EDF (OpenStax / OER)",
2679
+ problem_set: "\u{1F4A1} B\xE0i t\u1EADp & Th\u1EED th\xE1ch L\u1EADp tr\xECnh"
2680
+ };
2681
+ const grouped = {};
2682
+ for (const it of items) {
2683
+ if (!grouped[it.type]) grouped[it.type] = [];
2684
+ grouped[it.type].push(it);
2685
+ }
2686
+ for (const [type, groupItems] of Object.entries(grouped)) {
2687
+ sections.push(`#### ${typeLabels[type] || type}`);
2688
+ for (const it of groupItems) {
2689
+ it.thumbnailUrl ? `![preview](${it.thumbnailUrl})
2690
+ ` : "";
2691
+ const embed = it.embedUrl ? `> \u{1F517} **T\u01B0\u01A1ng t\xE1c tr\u1EF1c ti\u1EBFp**: [M\u1EDF Simulation To\xE0n m\xE0n h\xECnh](${it.embedUrl})
2692
+ ` : "";
2693
+ sections.push(
2694
+ `- **[${it.title}](${it.url})** \u2014 *${it.provider.toUpperCase()}* (${it.license.type})
2695
+ ${it.description}
2696
+ ${embed} *Tr\xEDch d\u1EABn b\u1EA3n quy\u1EC1n*: \`${it.license.attributionText}\``
2697
+ );
2698
+ }
2699
+ sections.push("");
2700
+ }
2701
+ return sections.join("\n");
2702
+ }
2703
+ };
2704
+
2705
+ // src/agent/researchSubAgent.ts
2706
+ function describeZodSchemaKeys(schema) {
2707
+ if (!schema) return void 0;
2708
+ const def = schema?._def;
2709
+ if (def?.typeName === "ZodObject" && typeof def.shape === "function") {
2710
+ const shapeObj = def.shape();
2711
+ const keys = Object.keys(shapeObj);
2712
+ if (keys.length > 0) {
2713
+ return `JSON object with required top-level keys: ${keys.map((k) => `"${k}"`).join(", ")}`;
2714
+ }
2715
+ }
2716
+ return void 0;
2717
+ }
2718
+ function resolveResearchProfile(contract) {
2719
+ if (contract.profile && contract.profile !== "auto") {
2720
+ return contract.profile;
2721
+ }
2722
+ const text = `${contract.objective} ${contract.context?.positioning || ""}`.toLowerCase();
2723
+ if (/\b(hackernews|reddit|social|pulse|trend|last 30 days|community sentiment|github stars)\b/.test(text)) {
2724
+ return "social_pulse";
2725
+ }
2726
+ if (/\b(literature review|academic|peer-reviewed|openalex|arxiv|citation|paper|cs2023)\b/.test(text)) {
2727
+ return "academic";
2728
+ }
2729
+ if (/\b(phet|oer|openstax|simulation|worksheet|unplugged)\b/.test(text)) {
2730
+ return "curriculum_oer";
2731
+ }
2732
+ 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)) {
2733
+ return "technical";
2734
+ }
2735
+ return "general";
2736
+ }
2737
+ var ResearchSubAgent = class {
2738
+ constructor(config = {}) {
2739
+ this.config = config;
2740
+ this.searchEngine = new MultiSourceSearchEngine({
2741
+ apiKeys: config.apiKeys,
2742
+ allowEnvFallback: config.allowEnvFallback,
2743
+ customAdapter: config.customSearchAdapter
2744
+ });
2745
+ this.webScraper = new WebScraper({
2746
+ crawl4aiHost: config.crawl4aiHost,
2747
+ jinaKey: config.apiKeys?.jina,
2748
+ brightDataKey: config.apiKeys?.brightdata || config.apiKeys?.brightData,
2749
+ allowEnvFallback: config.allowEnvFallback,
2750
+ customAdapter: config.customCrawlerAdapter
2751
+ });
2752
+ this.academicEngine = new AcademicSearchEngine({
2753
+ apiKey: config.apiKeys?.semanticScholar,
2754
+ allowEnvFallback: config.allowEnvFallback,
2755
+ customAdapter: config.customAcademicSearchAdapter
2756
+ });
2757
+ this.openAlexClient = new OpenAlexClient();
2758
+ this.socialPulseHarvester = new SocialPulseHarvester(this.searchEngine);
2759
+ this.stemResearcher = new StemResourceResearcher();
2760
+ this.healthAuditor = new HealthAuditor();
2761
+ this.evidenceScorer = new EvidenceScorer();
2762
+ this.claimVerifier = new ClaimVerifier();
2763
+ this.provenanceTracker = new ProvenanceTracker();
2764
+ }
2765
+ searchEngine;
2766
+ webScraper;
2767
+ academicEngine;
2768
+ openAlexClient;
2769
+ socialPulseHarvester;
2770
+ stemResearcher;
2771
+ healthAuditor;
2772
+ evidenceScorer;
2773
+ claimVerifier;
2774
+ provenanceTracker;
2775
+ /**
2776
+ * Executes a complete Plan-and-Execute research campaign governed by `contract`.
2777
+ */
2778
+ async run(contract, options) {
2779
+ const llm = options?.llm ?? this.config.llm;
2780
+ const resolvedProfile = resolveResearchProfile(contract);
2781
+ const preset = RESEARCH_PROFILE_PRESETS[resolvedProfile];
2782
+ const ctx = contract.context ?? this.config.defaultCourseContext;
2783
+ const domain = classifyTechnicalDomain(contract.objective, void 0, ctx).domain;
2784
+ const maxRounds = Math.max(1, Math.min(5, contract.budget?.maxRounds ?? preset.maxRounds));
2785
+ const maxQueriesPerRound = Math.max(1, Math.min(6, contract.budget?.maxQueriesPerRound ?? preset.maxQueriesPerRound));
2786
+ const maxScrapePerRound = Math.max(1, Math.min(6, contract.budget?.maxScrapePerRound ?? preset.maxScrapePerRound));
2787
+ const minSources = contract.acceptanceCriteria?.minSources ?? 2;
2788
+ const minRelevanceScore = contract.acceptanceCriteria?.minRelevanceScore ?? 6;
2789
+ const recencyDays = contract.acceptanceCriteria?.recencyDays ?? 30;
2790
+ const ledger = new EvidenceLedger();
2791
+ const executedQueries = /* @__PURE__ */ new Set();
2792
+ const scrapedUrls = /* @__PURE__ */ new Set();
2793
+ const roundTraces = [];
2794
+ let currentMissingGaps = [
2795
+ ...contract.acceptanceCriteria?.requiredAttributes || [],
2796
+ ...contract.requiredSections || []
2797
+ ];
2798
+ for (let round = 1; round <= maxRounds; round++) {
2799
+ const beforeReceiptCount = ledger.getReceipts().length;
2800
+ const plannedQueries = await this.planQueriesForRound({
2801
+ round,
2802
+ contract,
2803
+ profile: resolvedProfile,
2804
+ missingGaps: currentMissingGaps,
2805
+ receipts: ledger.getReceipts(),
2806
+ executedQueries,
2807
+ maxQueries: maxQueriesPerRound,
2808
+ llm
2809
+ });
2810
+ for (const q of plannedQueries) {
2811
+ executedQueries.add(q.toLowerCase());
2812
+ }
2813
+ await this.executeHarvestRound({
2814
+ round,
2815
+ queries: plannedQueries,
2816
+ contract,
2817
+ preset,
2818
+ domain,
2819
+ recencyDays,
2820
+ maxScrapePerRound,
2821
+ scrapedUrls,
2822
+ ledger
2823
+ });
2824
+ const afterReceiptCount = ledger.getReceipts().length;
2825
+ const newReceiptsAdded = afterReceiptCount - beforeReceiptCount;
2826
+ const evaluation = await this.evaluateRoundGaps({
2827
+ contract,
2828
+ ledger,
2829
+ minSources,
2830
+ minRelevanceScore,
2831
+ llm
2832
+ });
2833
+ currentMissingGaps = evaluation.missingGaps;
2834
+ roundTraces.push({
2835
+ round,
2836
+ plannedQueries,
2837
+ newReceiptsAdded,
2838
+ satisfiedAttributes: evaluation.satisfiedAttributes,
2839
+ missingGaps: evaluation.missingGaps
2840
+ });
2841
+ if (evaluation.missingGaps.length === 0) {
2842
+ break;
2843
+ }
2844
+ }
2845
+ const allItems = ledger.getItems();
2846
+ const approvedItems = ledger.getApprovedItems(minRelevanceScore);
2847
+ const provenanceSidecar = this.provenanceTracker.generateSidecar(
2848
+ contract.objective,
2849
+ ledger.toProvenanceRecords(domain)
2850
+ );
2851
+ if (allItems.length === 0) {
2852
+ const failMsg = `Research Sub-Agent failed to harvest any verified sources for objective: "${contract.objective}".`;
2853
+ return {
2854
+ status: "failed",
2855
+ objective: contract.objective,
2856
+ profile: resolvedProfile,
2857
+ roundsExecuted: roundTraces.length,
2858
+ data: null,
2859
+ markdownReport: `# \u274C Research Harvest Failed: ${contract.objective}
2860
+
2861
+ > ${failMsg}
2862
+
2863
+ ### Unresolved Gaps
2864
+ ${currentMissingGaps.length > 0 ? currentMissingGaps.map((g) => `- ${g}`).join("\n") : "- No reachable sources."}`,
2865
+ tier1Summary: failMsg,
2866
+ tier2TechnicalDigest: failMsg,
2867
+ ledgerItems: [],
2868
+ receipts: [],
2869
+ validCitationIds: [],
2870
+ invalidCitationIds: [],
2871
+ missingGaps: currentMissingGaps.length > 0 ? currentMissingGaps : ["minSources not met (0 harvested)"],
2872
+ roundTraces,
2873
+ provenanceMd: provenanceSidecar.provenanceMd
2874
+ };
2875
+ }
2876
+ return this.synthesizeAndVerify({
2877
+ contract,
2878
+ profile: resolvedProfile,
2879
+ domain,
2880
+ ledger,
2881
+ approvedCount: approvedItems.length,
2882
+ minSources,
2883
+ missingGaps: currentMissingGaps,
2884
+ roundTraces,
2885
+ provenanceMd: provenanceSidecar.provenanceMd,
2886
+ llm
2887
+ });
2888
+ }
2889
+ /**
2890
+ * Plans targeted search queries for Round 1 (initial coverage) or Round > 1 (surgical gap filling).
2891
+ */
2892
+ async planQueriesForRound(params) {
2893
+ const { round, contract, profile, missingGaps, receipts, executedQueries, maxQueries, llm } = params;
2894
+ const ctx = contract.context ?? this.config.defaultCourseContext;
2895
+ const toolAnchor = [ctx?.hardwarePlatform, ctx?.softwareEnv].filter(Boolean).join(" ").trim();
2896
+ const baseTopic = toolAnchor ? `${toolAnchor} ${contract.objective}` : contract.objective;
2897
+ if (llm) {
2898
+ try {
2899
+ const promptLines = [
2900
+ `You are a Principal Research Planner for an autonomous Plan-and-Execute Research Sub-Agent.`,
2901
+ `Objective: "${contract.objective}"`,
2902
+ `Profile: ${profile} | Round: ${round}`,
2903
+ toolAnchor ? `Hardware/Software Context: ${toolAnchor}` : "",
2904
+ ctx?.ageBand ? `Target Learner Age Band: ${ctx.ageBand[0]}-${ctx.ageBand[1]}` : "",
2905
+ contract.requiredSections?.length ? `Required Sections: ${contract.requiredSections.join(", ")}` : "",
2906
+ contract.acceptanceCriteria?.requiredAttributes?.length ? `Required Attributes: ${contract.acceptanceCriteria.requiredAttributes.join(", ")}` : "",
2907
+ contract.acceptanceCriteria?.requireCodeExamples ? `Must find verified code examples.` : "",
2908
+ contract.acceptanceCriteria?.requireTables ? `Must find specification/pinout tables.` : ""
2909
+ ];
2910
+ if (round > 1 && receipts.length > 0) {
2911
+ promptLines.push(
2912
+ `
2913
+ Compact Receipts Collected So Far (${receipts.length} sources):`,
2914
+ ...receipts.slice(0, 8).map(
2915
+ (r) => `- [${r.id}] ${r.title} (score:${r.relevanceScore}, code:${r.codeBlockCount}, tables:${r.tableCount}): ${r.briefExcerpt.slice(0, 140)}`
2916
+ ),
2917
+ `
2918
+ Remaining Unresolved Gaps to Fill in Round ${round}:`,
2919
+ ...missingGaps.map((g) => `- ${g}`),
2920
+ `
2921
+ Previously Executed Queries (DO NOT REPEAT): ${Array.from(executedQueries).join(" | ")}`
2922
+ );
2923
+ }
2924
+ promptLines.push(
2925
+ `
2926
+ Generate ${maxQueries} high-precision search queries to fulfill ${round === 1 ? "the objective and required attributes" : "ONLY the remaining unresolved gaps"}.`,
2927
+ `Return ONLY a valid JSON array of query strings: ["query 1", "query 2"]`
2928
+ );
2929
+ const raw = await llm(promptLines.filter(Boolean).join("\n"), {
2930
+ system: "Return strictly a valid JSON array of search query strings.",
2931
+ temperature: 0.2,
2932
+ jsonMode: true
2933
+ });
2934
+ const match = raw.match(/\[[\s\S]*\]/);
2935
+ if (match) {
2936
+ const parsed = JSON.parse(match[0]);
2937
+ if (Array.isArray(parsed)) {
2938
+ const candidateQueries = parsed.map((q) => String(q).trim()).filter((q) => q.length > 3 && !executedQueries.has(q.toLowerCase())).slice(0, maxQueries);
2939
+ if (candidateQueries.length > 0) {
2940
+ return candidateQueries;
2941
+ }
2942
+ }
2943
+ }
2944
+ } catch (e) {
2945
+ console.warn(`[ResearchSubAgent] Round ${round} LLM query planning fallback:`, e?.message || e);
2946
+ }
2947
+ }
2948
+ const fallbackQueries = [];
2949
+ if (round === 1) {
2950
+ fallbackQueries.push(
2951
+ `${baseTopic} official documentation architecture specification`.trim(),
2952
+ `${baseTopic} practical examples tutorial implementation`.trim(),
2953
+ `${baseTopic} common pitfalls debugging troubleshooting bottlenecks`.trim()
2954
+ );
2955
+ if (contract.acceptanceCriteria?.requireTables) {
2956
+ fallbackQueries.push(`${baseTopic} pinout specification comparison table`.trim());
2957
+ }
2958
+ } else {
2959
+ for (const gap of missingGaps) {
2960
+ const candidate = `${baseTopic} ${gap}`.trim();
2961
+ if (!executedQueries.has(candidate.toLowerCase())) {
2962
+ fallbackQueries.push(candidate);
2963
+ }
2964
+ }
2965
+ if (fallbackQueries.length === 0) {
2966
+ fallbackQueries.push(`${baseTopic} advanced reference guide code examples`.trim());
2967
+ }
2968
+ }
2969
+ return fallbackQueries.filter((q) => !executedQueries.has(q.toLowerCase())).slice(0, maxQueries);
2970
+ }
2971
+ /**
2972
+ * Executes active harvesters in parallel and stores results in the Out-of-Band `EvidenceLedger`.
2973
+ */
2974
+ async executeHarvestRound(params) {
2975
+ const { round, queries, contract, preset, domain, recencyDays, maxScrapePerRound, scrapedUrls, ledger } = params;
2976
+ if (queries.length === 0) return;
2977
+ const tasks = [];
2978
+ if (preset.enableWeb) {
2979
+ tasks.push(
2980
+ (async () => {
2981
+ const candidateHits = [];
2982
+ for (const q of queries) {
2983
+ try {
2984
+ const hits = await this.searchEngine.search(q, { limit: 3 });
2985
+ for (const h of hits) {
2986
+ if (!isCommercialOrNoise({ url: h.url, title: h.title, snippet: h.content })) {
2987
+ if (!candidateHits.some((existing) => existing.url === h.url)) {
2988
+ candidateHits.push(h);
2989
+ }
2990
+ }
2991
+ }
2992
+ } catch {
2993
+ }
2994
+ }
2995
+ const urlsToScrape = candidateHits.filter((h) => !scrapedUrls.has(h.url)).slice(0, maxScrapePerRound);
2996
+ await Promise.allSettled(
2997
+ urlsToScrape.map(async (hit) => {
2998
+ scrapedUrls.add(hit.url);
2999
+ try {
3000
+ const doc = await this.webScraper.scrapeUrl(hit.url);
3001
+ const health = this.healthAuditor.auditDocument(doc);
3002
+ if (health.passed && doc.markdownContent.trim().length > 80) {
3003
+ const scored = this.evidenceScorer.scoreDocument(doc, domain, contract.objective);
3004
+ ledger.addScrapedDocument(doc, scored.score, scored.keyTakeaways);
3005
+ return;
3006
+ }
3007
+ } catch {
3008
+ }
3009
+ if (hit.content && hit.content.trim().length > 30) {
3010
+ ledger.addSearchHit(hit, 6);
3011
+ }
3012
+ })
3013
+ );
3014
+ for (const hit of candidateHits.slice(maxScrapePerRound, maxScrapePerRound + 2)) {
3015
+ if (hit.content && hit.content.trim().length > 40) {
3016
+ ledger.addSearchHit(hit, 6);
3017
+ }
3018
+ }
3019
+ })()
3020
+ );
3021
+ }
3022
+ if (preset.enableAcademic && round === 1) {
3023
+ tasks.push(
3024
+ (async () => {
3025
+ try {
3026
+ const primaryQuery = queries[0] || contract.objective;
3027
+ const [s2Papers, oaPapers] = await Promise.all([
3028
+ this.academicEngine.searchPapers(primaryQuery, { limit: 3 }),
3029
+ this.openAlexClient.searchWorks(primaryQuery, { limit: 3 })
3030
+ ]);
3031
+ for (const p of [...s2Papers, ...oaPapers].slice(0, 5)) {
3032
+ ledger.addAcademicPaper(p);
3033
+ }
3034
+ } catch (e) {
3035
+ console.warn("[ResearchSubAgent] Academic harvest error:", e?.message || e);
3036
+ }
3037
+ })()
3038
+ );
3039
+ }
3040
+ if (preset.enableSocialPulse && round === 1) {
3041
+ tasks.push(
3042
+ (async () => {
3043
+ try {
3044
+ const pulseReport = await this.socialPulseHarvester.harvest(contract.objective, {
3045
+ recencyDays,
3046
+ limitPerPlatform: 3
3047
+ });
3048
+ for (const item of pulseReport.items.slice(0, 5)) {
3049
+ ledger.addSocialPulseItem(item);
3050
+ }
3051
+ } catch (e) {
3052
+ console.warn("[ResearchSubAgent] Social pulse harvest error:", e?.message || e);
3053
+ }
3054
+ })()
3055
+ );
3056
+ }
3057
+ if (preset.enableStemOer && round === 1) {
3058
+ tasks.push(
3059
+ (async () => {
3060
+ try {
3061
+ const oerCatalog = await this.stemResearcher.findResources(contract.objective, {
3062
+ limit: 4
3063
+ });
3064
+ for (const res of oerCatalog.resources.slice(0, 4)) {
3065
+ ledger.addStemResource({
3066
+ title: res.title,
3067
+ url: res.url,
3068
+ description: res.description,
3069
+ provider: res.provider,
3070
+ license: res.license?.type
3071
+ });
3072
+ }
3073
+ } catch (e) {
3074
+ console.warn("[ResearchSubAgent] STEM OER harvest error:", e?.message || e);
3075
+ }
3076
+ })()
3077
+ );
3078
+ }
3079
+ await Promise.allSettled(tasks);
3080
+ }
3081
+ /**
3082
+ * Evaluates whether the current `EvidenceLedger` satisfies `acceptanceCriteria`,
3083
+ * `requiredAttributes`, and `requiredSections`.
3084
+ */
3085
+ async evaluateRoundGaps(params) {
3086
+ const { contract, ledger, minSources, minRelevanceScore, llm } = params;
3087
+ const missingGaps = [];
3088
+ const satisfiedAttributes = [];
3089
+ const approved = ledger.getApprovedItems(minRelevanceScore);
3090
+ if (approved.length < minSources) {
3091
+ missingGaps.push(`Need at least ${minSources} verified sources with score >= ${minRelevanceScore} (currently ${approved.length})`);
3092
+ } else {
3093
+ satisfiedAttributes.push(`minSources(${approved.length}/${minSources})`);
3094
+ }
3095
+ if (contract.acceptanceCriteria?.requireCodeExamples && ledger.getTotalCodeBlocks() === 0) {
3096
+ missingGaps.push("Missing verified code examples / syntax snippets");
3097
+ } else if (contract.acceptanceCriteria?.requireCodeExamples) {
3098
+ satisfiedAttributes.push(`codeExamples(${ledger.getTotalCodeBlocks()})`);
3099
+ }
3100
+ if (contract.acceptanceCriteria?.requireTables && ledger.getTotalTables() === 0) {
3101
+ missingGaps.push("Missing specification or pinout markdown tables");
3102
+ } else if (contract.acceptanceCriteria?.requireTables) {
3103
+ satisfiedAttributes.push(`tables(${ledger.getTotalTables()})`);
3104
+ }
3105
+ const targetCheckList = [
3106
+ ...contract.acceptanceCriteria?.requiredAttributes || [],
3107
+ ...contract.requiredSections || []
3108
+ ];
3109
+ if (targetCheckList.length > 0) {
3110
+ const receipts = ledger.getReceipts();
3111
+ if (receipts.length === 0) {
3112
+ missingGaps.push(...targetCheckList);
3113
+ } else if (llm) {
3114
+ try {
3115
+ const prompt = [
3116
+ `Evaluate which of the required attributes/sections are covered by the collected Citation Receipts for "${contract.objective}".`,
3117
+ `Required Items: ${JSON.stringify(targetCheckList)}`,
3118
+ `Collected Citation Receipts:
3119
+ ${receipts.map((r) => `- [${r.id}] ${r.title} (headings: ${r.headings.join(", ")}): ${r.briefExcerpt}`).join("\n")}`,
3120
+ `Return ONLY a JSON object: {"satisfied": ["item1"], "missing": ["item2"]}`
3121
+ ].join("\n");
3122
+ const raw = await llm(prompt, {
3123
+ system: 'Output strictly valid JSON object with "satisfied" and "missing" string arrays.',
3124
+ temperature: 0.1,
3125
+ jsonMode: true
3126
+ });
3127
+ const match = raw.match(/\{[\s\S]*\}/);
3128
+ if (match) {
3129
+ const parsed = JSON.parse(match[0]);
3130
+ if (Array.isArray(parsed.satisfied)) {
3131
+ satisfiedAttributes.push(...parsed.satisfied.map(String));
3132
+ }
3133
+ if (Array.isArray(parsed.missing)) {
3134
+ missingGaps.push(...parsed.missing.map(String));
3135
+ }
3136
+ return { satisfiedAttributes, missingGaps };
3137
+ }
3138
+ } catch {
3139
+ }
3140
+ }
3141
+ const lowerCorpus = ledger.buildFullRawCorpus().toLowerCase();
3142
+ for (const reqItem of targetCheckList) {
3143
+ const tokens = reqItem.toLowerCase().replace(/[^a-z0-9\u00C0-\u1EF9]+/g, " ").split(/\s+/).filter((t) => t.length >= 3);
3144
+ const matched = tokens.filter((t) => lowerCorpus.includes(t)).length;
3145
+ if (tokens.length === 0 || matched / tokens.length >= 0.5) {
3146
+ satisfiedAttributes.push(reqItem);
3147
+ } else {
3148
+ missingGaps.push(reqItem);
3149
+ }
3150
+ }
3151
+ }
3152
+ return { satisfiedAttributes, missingGaps };
3153
+ }
3154
+ /**
3155
+ * Stage B: Synthesizes `EvidenceLedger` excerpts into `outputSchema<T>` + `markdownReport`
3156
+ * and runs deterministic schema, citation, and claim verification gates.
3157
+ */
3158
+ async synthesizeAndVerify(params) {
3159
+ const { contract, profile, ledger, approvedCount, minSources, missingGaps, roundTraces, provenanceMd, llm } = params;
3160
+ const synthesisCorpus = ledger.buildSynthesisCorpus(12);
3161
+ const items = ledger.getItems();
3162
+ const receipts = ledger.getReceipts();
3163
+ let synthesizedData = null;
3164
+ let markdownReport = "";
3165
+ let tier1Summary = "";
3166
+ let tier2TechnicalDigest = "";
3167
+ let keyClaims = [];
3168
+ let isLlmSynthesized = false;
3169
+ const schemaHint = contract.outputSchemaDescription || describeZodSchemaKeys(contract.outputSchema) || "JSON object capturing the key structured findings, technical constraints, exemplars, and citations";
3170
+ if (llm) {
3171
+ try {
3172
+ 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";
3173
+ const prompt = [
3174
+ `You are a Principal Research Synthesizer. Synthesize the verified EvidenceLedger sources below to fulfill the Research Contract.`,
3175
+ `Objective: "${contract.objective}"`,
3176
+ `Profile: ${profile}`,
3177
+ contract.context?.ageBand ? `Learner Age Band: ${contract.context.ageBand[0]}-${contract.context.ageBand[1]}` : "",
3178
+ contract.context?.hardwarePlatform ? `Hardware Platform: ${contract.context.hardwarePlatform}` : "",
3179
+ contract.context?.softwareEnv ? `Software/Tools: ${contract.context.softwareEnv}` : "",
3180
+ `Required Markdown Sections: ${requiredSectionsText}`,
3181
+ `Required Structured "data" Payload Format: ${schemaHint}`,
3182
+ contract.acceptanceCriteria?.forbiddenTerms?.length ? `Forbidden Terms (MUST NOT APPEAR): ${contract.acceptanceCriteria.forbiddenTerms.join(", ")}` : "",
3183
+ `
3184
+ CRITICAL GROUNDING RULES:`,
3185
+ `1. Every claim, metric, pinout, or recommendation MUST cite its EvidenceLedger ID in brackets, e.g. [RES-01], [RES-02].`,
3186
+ `2. NEVER invent citation IDs outside [RES-01]..[RES-${String(items.length).padStart(2, "0")}].`,
3187
+ `3. If evidence for a specific attribute is missing from the ledger, state that explicitly rather than fabricating facts.`,
3188
+ `
3189
+ === VERIFIED EVIDENCE LEDGER ===
3190
+ ${synthesisCorpus}`,
3191
+ `
3192
+ Return ONLY a valid JSON object with the exact envelope:`,
3193
+ `{`,
3194
+ ` "data": { ...structured payload matching the Required Structured "data" Payload Format... },`,
3195
+ ` "markdownReport": "# Full Markdown Report with [RES-xx] citations and Required Markdown Sections...",`,
3196
+ ` "tier1Summary": "Concise <=200-word executive summary with [RES-xx] citations",`,
3197
+ ` "tier2TechnicalDigest": "Bulleted technical digest (<=600 words) preserving concrete APIs, specs, code/tables, and pitfalls with [RES-xx] tags",`,
3198
+ ` "keyClaims": ["Core factual claim 1 from report", "Core factual claim 2"]`,
3199
+ `}`
3200
+ ].filter(Boolean).join("\n");
3201
+ const raw = await llm(prompt, {
3202
+ system: "Output strictly valid JSON matching the requested synthesis envelope. Ground every claim in [RES-xx].",
3203
+ temperature: 0.2,
3204
+ jsonMode: true
3205
+ });
3206
+ const match = raw.match(/\{[\s\S]*\}/);
3207
+ if (match) {
3208
+ const parsed = JSON.parse(match[0]);
3209
+ markdownReport = typeof parsed.markdownReport === "string" ? parsed.markdownReport : "";
3210
+ tier1Summary = typeof parsed.tier1Summary === "string" ? parsed.tier1Summary : "";
3211
+ tier2TechnicalDigest = typeof parsed.tier2TechnicalDigest === "string" ? parsed.tier2TechnicalDigest : "";
3212
+ keyClaims = Array.isArray(parsed.keyClaims) ? parsed.keyClaims.map(String) : [];
3213
+ const candidateData = parsed.data !== void 0 ? parsed.data : parsed;
3214
+ if (contract.outputSchema) {
3215
+ const validation = contract.outputSchema.safeParse(candidateData);
3216
+ if (validation.success) {
3217
+ synthesizedData = validation.data;
3218
+ isLlmSynthesized = true;
3219
+ } else {
3220
+ const issuesText = validation.error.issues.map((iss) => `${iss.path.join(".") || "root"}: ${iss.message}`).join("; ");
3221
+ const repairPrompt = [
3222
+ `The synthesized "data" object failed Zod schema validation with issues: ${issuesText}`,
3223
+ `Schema requirement: ${schemaHint}`,
3224
+ `Original candidate data: ${JSON.stringify(candidateData)}`,
3225
+ `Repair and return ONLY the valid JSON object for "data" grounded strictly in the EvidenceLedger.`
3226
+ ].join("\n");
3227
+ const repairedRaw = await llm(repairPrompt, {
3228
+ system: "Return strictly valid JSON object matching the schema.",
3229
+ temperature: 0.1,
3230
+ jsonMode: true
3231
+ });
3232
+ const repMatch = repairedRaw.match(/\{[\s\S]*\}/);
3233
+ if (repMatch) {
3234
+ const repParsed = JSON.parse(repMatch[0]);
3235
+ const repCheck = contract.outputSchema.safeParse(repParsed);
3236
+ if (repCheck.success) {
3237
+ synthesizedData = repCheck.data;
3238
+ isLlmSynthesized = true;
3239
+ } else {
3240
+ missingGaps.push(`Output schema validation incomplete: ${issuesText}`);
3241
+ }
3242
+ }
3243
+ }
3244
+ } else {
3245
+ synthesizedData = candidateData;
3246
+ isLlmSynthesized = true;
3247
+ }
3248
+ }
3249
+ } catch (e) {
3250
+ console.warn("[ResearchSubAgent] Stage B LLM synthesis error, falling back to deterministic ledger compilation:", e?.message || e);
3251
+ }
3252
+ }
3253
+ if (!markdownReport) {
3254
+ markdownReport = this.buildDeterministicMarkdownReport(contract.objective, profile, items, contract.requiredSections);
3255
+ }
3256
+ if (!tier1Summary) {
3257
+ tier1Summary = items.slice(0, 3).map((i) => `[${i.id}] ${i.title}: ${i.keyExcerpts[0] || ""}`).join(" ");
3258
+ }
3259
+ if (!tier2TechnicalDigest) {
3260
+ tier2TechnicalDigest = items.slice(0, 6).map((i) => `- **[${i.id}] ${i.title}** (${i.url}): ${i.keyExcerpts.slice(0, 2).join(" ")}`).join("\n");
3261
+ }
3262
+ if (synthesizedData === null && !contract.outputSchema) {
3263
+ synthesizedData = {
3264
+ objective: contract.objective,
3265
+ profile,
3266
+ sources: receipts,
3267
+ codeSnippets: items.flatMap((i) => i.codeBlocks).slice(0, 4),
3268
+ tables: items.flatMap((i) => i.tables).slice(0, 4)
3269
+ };
3270
+ }
3271
+ const combinedText = `${markdownReport}
3272
+ ${tier1Summary}
3273
+ ${tier2TechnicalDigest}
3274
+ ${JSON.stringify(synthesizedData || {})}`;
3275
+ const { validCitationIds, invalidCitationIds } = ledger.verifyCitationTags(combinedText);
3276
+ if (invalidCitationIds.length > 0) {
3277
+ for (const badId of invalidCitationIds) {
3278
+ const regex = new RegExp(`\\[?${badId}\\]?`, "gi");
3279
+ markdownReport = markdownReport.replace(regex, "[UNVERIFIED-CITATION-REMOVED]");
3280
+ tier1Summary = tier1Summary.replace(regex, "");
3281
+ tier2TechnicalDigest = tier2TechnicalDigest.replace(regex, "");
3282
+ }
3283
+ }
3284
+ if (contract.acceptanceCriteria?.forbiddenTerms?.length) {
3285
+ const lowerReport = markdownReport.toLowerCase();
3286
+ for (const forbidden of contract.acceptanceCriteria.forbiddenTerms) {
3287
+ if (lowerReport.includes(forbidden.toLowerCase())) {
3288
+ missingGaps.push(`Forbidden term detected in output: "${forbidden}"`);
3289
+ }
3290
+ }
3291
+ }
3292
+ const claimsToVerify = keyClaims.length > 0 ? keyClaims : items.slice(0, 4).map((i) => i.keyExcerpts[0]).filter((e) => Boolean(e && e.length > 25));
3293
+ const claimVerification = claimsToVerify.length > 0 ? this.claimVerifier.verifyClaimsDeterministic(claimsToVerify, ledger.buildFullRawCorpus()) : void 0;
3294
+ let status = "success";
3295
+ if (!isLlmSynthesized && llm) {
3296
+ status = "degraded";
3297
+ } else if (missingGaps.length > 0 || approvedCount < minSources || contract.outputSchema && synthesizedData === null) {
3298
+ status = "partial";
3299
+ } else if (!llm) {
3300
+ status = contract.outputSchema && synthesizedData === null ? "degraded" : "success";
3301
+ }
3302
+ return {
3303
+ status,
3304
+ objective: contract.objective,
3305
+ profile,
3306
+ roundsExecuted: roundTraces.length,
3307
+ data: synthesizedData,
3308
+ markdownReport,
3309
+ tier1Summary: tier1Summary.slice(0, 1800),
3310
+ tier2TechnicalDigest: tier2TechnicalDigest.slice(0, 4e3),
3311
+ ledgerItems: items,
3312
+ receipts,
3313
+ validCitationIds,
3314
+ invalidCitationIds,
3315
+ missingGaps: Array.from(new Set(missingGaps)),
3316
+ roundTraces,
3317
+ claimVerification,
3318
+ provenanceMd
3319
+ };
3320
+ }
3321
+ buildDeterministicMarkdownReport(objective, profile, items, requiredSections) {
3322
+ const lines = [
3323
+ `# \u{1F52C} Autonomous Research Dossier: ${objective}`,
3324
+ `> **Profile:** \`${profile.toUpperCase()}\` | **Verified Ledger Sources:** \`${items.length}\``
3325
+ ];
3326
+ if (requiredSections && requiredSections.length > 0) {
3327
+ for (const section of requiredSections) {
3328
+ lines.push(`
3329
+ ## ${section}`);
3330
+ for (const item of items.slice(0, 4)) {
3331
+ if (item.keyExcerpts[0]) {
3332
+ lines.push(`- **[${item.id}] ${item.title}**: ${item.keyExcerpts[0]}`);
3333
+ }
3334
+ }
3335
+ }
3336
+ } else {
3337
+ lines.push(`
3338
+ ## 1. Executive Summary & Verified Findings`);
3339
+ for (const item of items) {
3340
+ lines.push(
3341
+ `### [${item.id}] ${item.title} (${item.sourceType.toUpperCase()} \xB7 Score \`${item.relevanceScore}/10\`)`,
3342
+ `- **URL:** ${item.url}`,
3343
+ ...item.keyExcerpts.slice(0, 3).map((ex) => `- ${ex}`)
3344
+ );
3345
+ }
3346
+ }
3347
+ const allCode = items.flatMap((i) => i.codeBlocks.map((cb) => ({ id: i.id, ...cb }))).slice(0, 4);
3348
+ if (allCode.length > 0) {
3349
+ lines.push(
3350
+ `
3351
+ ## Extracted Code Examples`,
3352
+ ...allCode.map((c) => `From **[${c.id}]**:
3353
+ \`\`\`${c.language || "text"}
3354
+ ${c.code}
3355
+ \`\`\``)
3356
+ );
3357
+ }
3358
+ const allTables = items.flatMap((i) => i.tables.map((t) => ({ id: i.id, table: t }))).slice(0, 4);
3359
+ if (allTables.length > 0) {
3360
+ lines.push(
3361
+ `
3362
+ ## Extracted Specification Tables`,
3363
+ ...allTables.map((t) => `From **[${t.id}]**:
3364
+
3365
+ ${t.table}`)
3366
+ );
3367
+ }
3368
+ lines.push(
3369
+ `
3370
+ ## Evidence Ledger Citations`,
3371
+ ...items.map((i) => `- **[${i.id}]** [${i.title}](${i.url}) \u2014 *${i.sourceType}, score ${i.relevanceScore}/10*`)
3372
+ );
3373
+ return lines.join("\n");
3374
+ }
3375
+ };
3376
+ async function runResearchSubAgent(contract, config = {}) {
3377
+ const agent = new ResearchSubAgent(config);
3378
+ return agent.run(contract, { llm: config.llm });
3379
+ }
3380
+ var ResearchAgentToolInputSchema = zod.z.object({
3381
+ objective: zod.z.string().min(3).describe("The specific research question, topic, or technical requirement to investigate."),
3382
+ 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."),
3383
+ requiredSections: zod.z.array(zod.z.string()).optional().describe("Optional list of required Markdown sections in the synthesized report."),
3384
+ requiredAttributes: zod.z.array(zod.z.string()).optional().describe("Optional list of specific technical attributes, specs, or sub-questions that must be verified."),
3385
+ requireCodeExamples: zod.z.boolean().optional().describe("Set true if verified code examples are mandatory."),
3386
+ requireTables: zod.z.boolean().optional().describe("Set true if pinout or specification tables are mandatory."),
3387
+ recencyDays: zod.z.number().int().min(1).max(365).optional().describe("Recency window in days for social/community pulse."),
3388
+ maxRounds: zod.z.number().int().min(1).max(4).optional().describe("Maximum Plan-Harvest-Evaluate rounds (1-4).")
3389
+ });
3390
+ function createResearchAgentTool(config = {}) {
3391
+ const subAgent = new ResearchSubAgent(config);
3392
+ return {
3393
+ name: "research_subagent",
3394
+ 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.",
3395
+ parameters: ResearchAgentToolInputSchema,
3396
+ inputSchema: ResearchAgentToolInputSchema,
3397
+ execute: async (input) => {
3398
+ const result = await subAgent.run({
3399
+ objective: input.objective,
3400
+ profile: input.profile,
3401
+ requiredSections: input.requiredSections,
3402
+ acceptanceCriteria: {
3403
+ requiredAttributes: input.requiredAttributes,
3404
+ requireCodeExamples: input.requireCodeExamples,
3405
+ requireTables: input.requireTables,
3406
+ recencyDays: input.recencyDays
3407
+ },
3408
+ budget: {
3409
+ maxRounds: input.maxRounds
3410
+ }
3411
+ });
3412
+ return {
3413
+ status: result.status,
3414
+ objective: result.objective,
3415
+ profile: result.profile,
3416
+ roundsExecuted: result.roundsExecuted,
3417
+ tier1Summary: result.tier1Summary,
3418
+ tier2TechnicalDigest: result.tier2TechnicalDigest,
3419
+ citations: result.receipts.map((r) => ({
3420
+ id: r.id,
3421
+ title: r.title,
3422
+ url: r.url,
3423
+ sourceType: r.sourceType,
3424
+ score: r.relevanceScore
3425
+ })),
3426
+ missingGaps: result.missingGaps,
3427
+ fullResult: result
3428
+ };
3429
+ }
3430
+ };
3431
+ }
3432
+
3433
+ exports.EvidenceLedger = EvidenceLedger;
3434
+ exports.RESEARCH_PROFILE_PRESETS = RESEARCH_PROFILE_PRESETS;
3435
+ exports.ResearchAgentToolInputSchema = ResearchAgentToolInputSchema;
3436
+ exports.ResearchSubAgent = ResearchSubAgent;
3437
+ exports.createResearchAgentTool = createResearchAgentTool;
3438
+ exports.resolveResearchProfile = resolveResearchProfile;
3439
+ exports.runResearchSubAgent = runResearchSubAgent;
3440
+ //# sourceMappingURL=index.cjs.map
3441
+ //# sourceMappingURL=index.cjs.map