@thanh01.pmt/research-kit 1.3.0 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/dist/academic/index.cjs +4 -4
  2. package/dist/academic/index.cjs.map +1 -1
  3. package/dist/academic/index.js +2 -2
  4. package/dist/agent/index.cjs +1137 -301
  5. package/dist/agent/index.cjs.map +1 -1
  6. package/dist/agent/index.d.cts +1 -1
  7. package/dist/agent/index.d.ts +1 -1
  8. package/dist/agent/index.js +7 -7
  9. package/dist/chunk-4S6UMYBA.js +1931 -0
  10. package/dist/chunk-4S6UMYBA.js.map +1 -0
  11. package/dist/{chunk-S3JUCDKD.js → chunk-6U2H2DMQ.js} +7 -7
  12. package/dist/{chunk-S3JUCDKD.js.map → chunk-6U2H2DMQ.js.map} +1 -1
  13. package/dist/{chunk-ZNGU4ZYX.js → chunk-7BGR4E37.js} +5 -5
  14. package/dist/{chunk-ZNGU4ZYX.js.map → chunk-7BGR4E37.js.map} +1 -1
  15. package/dist/{chunk-AKEI7H2C.js → chunk-EWIAA2CC.js} +4 -4
  16. package/dist/{chunk-AKEI7H2C.js.map → chunk-EWIAA2CC.js.map} +1 -1
  17. package/dist/{chunk-QQZQNBJC.js → chunk-JV6Z6WUQ.js} +4 -4
  18. package/dist/{chunk-QQZQNBJC.js.map → chunk-JV6Z6WUQ.js.map} +1 -1
  19. package/dist/{chunk-2RMBLKP5.js → chunk-MJIREPKJ.js} +3 -3
  20. package/dist/{chunk-2RMBLKP5.js.map → chunk-MJIREPKJ.js.map} +1 -1
  21. package/dist/{chunk-KXJDQBSJ.js → chunk-PFECHAAR.js} +12 -5
  22. package/dist/chunk-PFECHAAR.js.map +1 -0
  23. package/dist/{chunk-NSY6KU4G.js → chunk-SEHHDO7X.js} +5 -5
  24. package/dist/{chunk-NSY6KU4G.js.map → chunk-SEHHDO7X.js.map} +1 -1
  25. package/dist/{chunk-RYLZYZRF.js → chunk-UCPWBRZ2.js} +3 -3
  26. package/dist/{chunk-RYLZYZRF.js.map → chunk-UCPWBRZ2.js.map} +1 -1
  27. package/dist/evidence/index.cjs +9 -2
  28. package/dist/evidence/index.cjs.map +1 -1
  29. package/dist/evidence/index.js +2 -2
  30. package/dist/harvester/index.cjs +6 -6
  31. package/dist/harvester/index.cjs.map +1 -1
  32. package/dist/harvester/index.js +5 -5
  33. package/dist/{index-onQDKDNo.d.cts → index-BOwJ1jON.d.cts} +317 -71
  34. package/dist/{index-CN8gei7k.d.ts → index-_aiOh8jX.d.ts} +317 -71
  35. package/dist/index.cjs +1145 -302
  36. package/dist/index.cjs.map +1 -1
  37. package/dist/index.d.cts +1 -1
  38. package/dist/index.d.ts +1 -1
  39. package/dist/index.js +25 -18
  40. package/dist/index.js.map +1 -1
  41. package/dist/pipeline/index.cjs +13 -6
  42. package/dist/pipeline/index.cjs.map +1 -1
  43. package/dist/pipeline/index.js +6 -6
  44. package/package.json +1 -1
  45. package/dist/chunk-KXJDQBSJ.js.map +0 -1
  46. package/dist/chunk-WWQ45RQK.js +0 -1114
  47. package/dist/chunk-WWQ45RQK.js.map +0 -1
package/dist/index.cjs CHANGED
@@ -185,7 +185,7 @@ var AcademicSearchEngine = class {
185
185
  }
186
186
  const res = await fetch(`https://api.semanticscholar.org/graph/v1/paper/search?${params.toString()}`, {
187
187
  headers,
188
- signal: AbortSignal.timeout(6e3)
188
+ signal: AbortSignal.timeout(12e3)
189
189
  });
190
190
  if (res.ok) {
191
191
  const data = await res.json();
@@ -216,7 +216,7 @@ var AcademicSearchEngine = class {
216
216
  try {
217
217
  const res = await fetch(`https://api.openalex.org/works?search=${encodeURIComponent(query)}&per-page=${limit}`, {
218
218
  headers: { "User-Agent": "OrchableComposer/1.0 (mailto:team@orchable.app)" },
219
- signal: AbortSignal.timeout(6e3)
219
+ signal: AbortSignal.timeout(12e3)
220
220
  });
221
221
  if (res.ok) {
222
222
  const data = await res.json();
@@ -303,7 +303,7 @@ var OpenAlexClient = class {
303
303
  headers: {
304
304
  "User-Agent": `OrchableResearchKit/1.3 (mailto:${this.mailto})`
305
305
  },
306
- signal: AbortSignal.timeout(7e3)
306
+ signal: AbortSignal.timeout(12e3)
307
307
  });
308
308
  if (res.ok) {
309
309
  const data = await res.json();
@@ -343,7 +343,7 @@ var OpenAlexClient = class {
343
343
  headers: {
344
344
  "User-Agent": `OrchableResearchKit/1.3 (mailto:${this.mailto})`
345
345
  },
346
- signal: AbortSignal.timeout(7e3)
346
+ signal: AbortSignal.timeout(12e3)
347
347
  });
348
348
  if (res.ok) {
349
349
  const data = await res.json();
@@ -1453,7 +1453,7 @@ var WebScraper = class {
1453
1453
  }
1454
1454
  const res = await fetch(jinaUrl, {
1455
1455
  headers,
1456
- signal: AbortSignal.timeout(8e3)
1456
+ signal: AbortSignal.timeout(15e3)
1457
1457
  });
1458
1458
  if (res.ok) {
1459
1459
  const markdown = await res.text();
@@ -1495,7 +1495,7 @@ var WebScraper = class {
1495
1495
  try {
1496
1496
  const res = await fetch(targetUrl, {
1497
1497
  headers: { "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" },
1498
- signal: AbortSignal.timeout(1e4)
1498
+ signal: AbortSignal.timeout(15e3)
1499
1499
  });
1500
1500
  if (res.ok) {
1501
1501
  const rawHtml = await res.text();
@@ -2850,7 +2850,7 @@ var SocialPulseHarvester = class {
2850
2850
  });
2851
2851
  const res = await fetch(`https://hn.algolia.com/api/v1/search?${params.toString()}`, {
2852
2852
  headers: { "User-Agent": "OrchableResearchKit/1.3" },
2853
- signal: AbortSignal.timeout(6500)
2853
+ signal: AbortSignal.timeout(12e3)
2854
2854
  });
2855
2855
  if (res.ok) {
2856
2856
  const data = await res.json();
@@ -2897,7 +2897,7 @@ var SocialPulseHarvester = class {
2897
2897
  Accept: "application/vnd.github+json",
2898
2898
  "User-Agent": "OrchableResearchKit/1.3"
2899
2899
  },
2900
- signal: AbortSignal.timeout(6500)
2900
+ signal: AbortSignal.timeout(12e3)
2901
2901
  });
2902
2902
  if (res.ok) {
2903
2903
  const data = await res.json();
@@ -2988,6 +2988,13 @@ var SocialPulseHarvester = class {
2988
2988
  function tokenizeBilingualKeywords(text) {
2989
2989
  return text.normalize("NFC").toLowerCase().replace(/[.,;:!?()[\]{}"“”‘’/\\|`*_~#-]+/g, " ").split(/\s+/).filter((w) => w.length >= 2 && !/^(and|the|for|with|from|into|của|trong|được|những|các|cho|với|khi|và|hoặc|để|từ|đến|về)$/.test(w));
2990
2990
  }
2991
+ function keywordMatchesText(keyword, lowerText) {
2992
+ if (keyword.length <= 3) {
2993
+ const escaped = keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
2994
+ return new RegExp(`(?:^|[^a-z0-9\\u00C0-\\u1EF9])${escaped}(?:$|[^a-z0-9\\u00C0-\\u1EF9])`, "i").test(lowerText);
2995
+ }
2996
+ return lowerText.includes(keyword);
2997
+ }
2991
2998
  function extractTopSentences(markdown, targetTopic, maxSentences = 3) {
2992
2999
  const keywords = tokenizeBilingualKeywords(targetTopic);
2993
3000
  const withoutCode = markdown.replace(/```[\s\S]*?```/g, " ");
@@ -3000,7 +3007,7 @@ function extractTopSentences(markdown, targetTopic, maxSentences = 3) {
3000
3007
  if (rawSentences.length === 0) return [];
3001
3008
  const scored = rawSentences.map((sentence, idx) => {
3002
3009
  const lower = sentence.normalize("NFC").toLowerCase();
3003
- const matchedCount = keywords.filter((k) => lower.includes(k)).length;
3010
+ const matchedCount = keywords.filter((k) => keywordMatchesText(k, lower)).length;
3004
3011
  const positionBonus = idx < 8 ? 1.5 : idx < 20 ? 0.5 : 0;
3005
3012
  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(
3006
3013
  sentence
@@ -3021,7 +3028,7 @@ var EvidenceScorer = class {
3021
3028
  let noiseScore = 2;
3022
3029
  const lowerContent = doc.markdownContent.normalize("NFC").toLowerCase();
3023
3030
  const targetKeywords = tokenizeBilingualKeywords(targetTopic);
3024
- const keywordMatches = targetKeywords.filter((k) => lowerContent.includes(k)).length;
3031
+ const keywordMatches = targetKeywords.filter((k) => keywordMatchesText(k, lowerContent)).length;
3025
3032
  const matchRatio = targetKeywords.length > 0 ? keywordMatches / targetKeywords.length : 1;
3026
3033
  if (matchRatio >= 0.75) depthScore += 3;
3027
3034
  else if (matchRatio >= 0.4) depthScore += 2;
@@ -4140,12 +4147,44 @@ ${c.code}
4140
4147
  };
4141
4148
 
4142
4149
  // src/agent/types.ts
4150
+ var RESEARCH_MODE_PRESETS = {
4151
+ search: {
4152
+ mode: "search",
4153
+ timeoutMs: 15e3,
4154
+ maxChannels: 1,
4155
+ channelConcurrency: 1,
4156
+ maxRounds: 1,
4157
+ maxQueriesPerRound: 1,
4158
+ maxScrapePerRound: 0,
4159
+ verifyClaims: false
4160
+ },
4161
+ research: {
4162
+ mode: "research",
4163
+ timeoutMs: 18e4,
4164
+ maxChannels: 2,
4165
+ channelConcurrency: 2,
4166
+ maxRounds: 1,
4167
+ maxQueriesPerRound: 3,
4168
+ maxScrapePerRound: 3,
4169
+ verifyClaims: false
4170
+ },
4171
+ "deep-research": {
4172
+ mode: "deep-research",
4173
+ timeoutMs: 6e5,
4174
+ maxChannels: 5,
4175
+ channelConcurrency: 2,
4176
+ maxRounds: 3,
4177
+ maxQueriesPerRound: 4,
4178
+ maxScrapePerRound: 4,
4179
+ verifyClaims: true
4180
+ }
4181
+ };
4143
4182
  var RESEARCH_PROFILE_PRESETS = {
4144
4183
  fast_grounded: {
4145
- maxRounds: 2,
4184
+ maxRounds: 1,
4146
4185
  maxQueriesPerRound: 3,
4147
4186
  maxScrapePerRound: 3,
4148
- timeoutMs: 35e3,
4187
+ timeoutMs: 18e4,
4149
4188
  enableWeb: true,
4150
4189
  enableAcademic: false,
4151
4190
  enableSocialPulse: false,
@@ -4155,57 +4194,57 @@ var RESEARCH_PROFILE_PRESETS = {
4155
4194
  maxRounds: 3,
4156
4195
  maxQueriesPerRound: 4,
4157
4196
  maxScrapePerRound: 4,
4158
- timeoutMs: 12e4,
4197
+ timeoutMs: 6e5,
4159
4198
  enableWeb: true,
4160
4199
  enableAcademic: true,
4161
4200
  enableSocialPulse: true,
4162
4201
  enableStemOer: true
4163
4202
  },
4164
4203
  technical: {
4165
- maxRounds: 2,
4204
+ maxRounds: 1,
4166
4205
  maxQueriesPerRound: 3,
4167
- maxScrapePerRound: 4,
4168
- timeoutMs: 45e3,
4206
+ maxScrapePerRound: 3,
4207
+ timeoutMs: 18e4,
4169
4208
  enableWeb: true,
4170
4209
  enableAcademic: false,
4171
4210
  enableSocialPulse: true,
4172
4211
  enableStemOer: false
4173
4212
  },
4174
4213
  academic: {
4175
- maxRounds: 2,
4214
+ maxRounds: 1,
4176
4215
  maxQueriesPerRound: 3,
4177
4216
  maxScrapePerRound: 2,
4178
- timeoutMs: 45e3,
4217
+ timeoutMs: 18e4,
4179
4218
  enableWeb: true,
4180
4219
  enableAcademic: true,
4181
4220
  enableSocialPulse: false,
4182
4221
  enableStemOer: false
4183
4222
  },
4184
4223
  social_pulse: {
4185
- maxRounds: 2,
4224
+ maxRounds: 1,
4186
4225
  maxQueriesPerRound: 3,
4187
4226
  maxScrapePerRound: 2,
4188
- timeoutMs: 35e3,
4227
+ timeoutMs: 18e4,
4189
4228
  enableWeb: true,
4190
4229
  enableAcademic: false,
4191
4230
  enableSocialPulse: true,
4192
4231
  enableStemOer: false
4193
4232
  },
4194
4233
  curriculum_oer: {
4195
- maxRounds: 2,
4234
+ maxRounds: 1,
4196
4235
  maxQueriesPerRound: 3,
4197
4236
  maxScrapePerRound: 3,
4198
- timeoutMs: 45e3,
4237
+ timeoutMs: 18e4,
4199
4238
  enableWeb: true,
4200
4239
  enableAcademic: false,
4201
4240
  enableSocialPulse: false,
4202
4241
  enableStemOer: true
4203
4242
  },
4204
4243
  general: {
4205
- maxRounds: 2,
4244
+ maxRounds: 1,
4206
4245
  maxQueriesPerRound: 3,
4207
4246
  maxScrapePerRound: 3,
4208
- timeoutMs: 45e3,
4247
+ timeoutMs: 18e4,
4209
4248
  enableWeb: true,
4210
4249
  enableAcademic: false,
4211
4250
  enableSocialPulse: false,
@@ -4514,6 +4553,443 @@ ${i.tables.join("\n")}`
4514
4553
  }));
4515
4554
  }
4516
4555
  };
4556
+
4557
+ // src/agent/decisionRouter.ts
4558
+ var QUESTION_FACETS = [
4559
+ "official_spec",
4560
+ "how_to_example",
4561
+ "pitfalls",
4562
+ "pedagogy_theory",
4563
+ "standards_policy",
4564
+ "emerging_trend",
4565
+ "learning_resources"
4566
+ ];
4567
+ var SOURCE_CHANNELS = [
4568
+ "web_docs",
4569
+ "academic",
4570
+ "social_pulse",
4571
+ "stem_oer",
4572
+ "video_media"
4573
+ ];
4574
+ var PRIOR_MATRIX = {
4575
+ official_spec: {
4576
+ web_docs: 0.95,
4577
+ academic: 0.2,
4578
+ social_pulse: 0.3,
4579
+ stem_oer: 0.15,
4580
+ video_media: 0.25
4581
+ },
4582
+ how_to_example: {
4583
+ web_docs: 0.9,
4584
+ academic: 0.15,
4585
+ social_pulse: 0.65,
4586
+ stem_oer: 0.35,
4587
+ video_media: 0.6
4588
+ },
4589
+ pitfalls: {
4590
+ web_docs: 0.65,
4591
+ academic: 0.25,
4592
+ social_pulse: 0.9,
4593
+ stem_oer: 0.1,
4594
+ video_media: 0.35
4595
+ },
4596
+ pedagogy_theory: {
4597
+ web_docs: 0.45,
4598
+ academic: 0.95,
4599
+ social_pulse: 0.2,
4600
+ stem_oer: 0.7,
4601
+ video_media: 0.3
4602
+ },
4603
+ standards_policy: {
4604
+ web_docs: 0.75,
4605
+ academic: 0.85,
4606
+ social_pulse: 0.15,
4607
+ stem_oer: 0.6,
4608
+ video_media: 0.15
4609
+ },
4610
+ emerging_trend: {
4611
+ web_docs: 0.6,
4612
+ academic: 0.45,
4613
+ social_pulse: 0.95,
4614
+ stem_oer: 0.1,
4615
+ video_media: 0.5
4616
+ },
4617
+ learning_resources: {
4618
+ web_docs: 0.65,
4619
+ academic: 0.3,
4620
+ social_pulse: 0.25,
4621
+ stem_oer: 0.95,
4622
+ video_media: 0.7
4623
+ }
4624
+ };
4625
+ function clampScore0to4(val, fallback = 1) {
4626
+ const n = Number(val);
4627
+ if (!Number.isFinite(n)) return fallback;
4628
+ return Math.max(0, Math.min(4, n));
4629
+ }
4630
+ function computeContractComplexityScore(contract) {
4631
+ let score = 0;
4632
+ const reqAttrs = contract.acceptanceCriteria?.requiredAttributes?.length || 0;
4633
+ const reqSecs = contract.requiredSections?.length || 0;
4634
+ const totalReqs = reqAttrs + reqSecs;
4635
+ if (totalReqs >= 4) score += 2;
4636
+ else if (totalReqs >= 2) score += 1;
4637
+ if (contract.acceptanceCriteria?.requireCodeExamples || contract.acceptanceCriteria?.requireTables) {
4638
+ score += 1;
4639
+ }
4640
+ if ((contract.acceptanceCriteria?.minSources ?? 2) >= 4 || Boolean(contract.outputSchema)) {
4641
+ score += 1;
4642
+ }
4643
+ return Math.min(4, score);
4644
+ }
4645
+ function inferFallbackFacetProbabilities(contract) {
4646
+ const dist = {
4647
+ official_spec: 0.25,
4648
+ how_to_example: 0.25,
4649
+ pitfalls: 0.15,
4650
+ pedagogy_theory: 0.1,
4651
+ standards_policy: 0.05,
4652
+ emerging_trend: 0.1,
4653
+ learning_resources: 0.1
4654
+ };
4655
+ if (contract.profile === "academic" || (contract.acceptanceCriteria?.minPeerReviewedSources ?? 0) >= 1) {
4656
+ return {
4657
+ official_spec: 0.05,
4658
+ how_to_example: 0.05,
4659
+ pitfalls: 0.05,
4660
+ pedagogy_theory: 0.5,
4661
+ standards_policy: 0.25,
4662
+ emerging_trend: 0.05,
4663
+ learning_resources: 0.05
4664
+ };
4665
+ }
4666
+ if (contract.profile === "social_pulse") {
4667
+ return {
4668
+ official_spec: 0.05,
4669
+ how_to_example: 0.15,
4670
+ pitfalls: 0.35,
4671
+ pedagogy_theory: 0.02,
4672
+ standards_policy: 0.03,
4673
+ emerging_trend: 0.35,
4674
+ learning_resources: 0.05
4675
+ };
4676
+ }
4677
+ if (contract.profile === "curriculum_oer") {
4678
+ return {
4679
+ official_spec: 0.05,
4680
+ how_to_example: 0.15,
4681
+ pitfalls: 0.05,
4682
+ pedagogy_theory: 0.2,
4683
+ standards_policy: 0.1,
4684
+ emerging_trend: 0.05,
4685
+ learning_resources: 0.4
4686
+ };
4687
+ }
4688
+ return dist;
4689
+ }
4690
+ function rankChannelsByExpectedPrior(facetProbabilities, contract) {
4691
+ const scores = {
4692
+ web_docs: 0,
4693
+ academic: 0,
4694
+ social_pulse: 0,
4695
+ stem_oer: 0,
4696
+ video_media: 0
4697
+ };
4698
+ for (const facet of QUESTION_FACETS) {
4699
+ const p = facetProbabilities[facet] ?? 0;
4700
+ const row = PRIOR_MATRIX[facet];
4701
+ for (const channel of SOURCE_CHANNELS) {
4702
+ scores[channel] += p * row[channel];
4703
+ }
4704
+ }
4705
+ if ((contract.acceptanceCriteria?.minPeerReviewedSources ?? 0) >= 1 || contract.profile === "academic") {
4706
+ scores.academic += 0.3;
4707
+ }
4708
+ if (contract.profile === "social_pulse" || contract.acceptanceCriteria?.recencyDays !== void 0 && contract.acceptanceCriteria.recencyDays <= 30) {
4709
+ scores.social_pulse += 0.2;
4710
+ }
4711
+ if (contract.acceptanceCriteria?.requireCodeExamples || contract.acceptanceCriteria?.requireTables || contract.context?.hardwarePlatform || contract.context?.softwareEnv) {
4712
+ scores.web_docs += 0.15;
4713
+ }
4714
+ if (contract.profile === "curriculum_oer") {
4715
+ scores.stem_oer += 0.3;
4716
+ }
4717
+ if (contract.preferredChannels && contract.preferredChannels.length > 0) {
4718
+ contract.preferredChannels.forEach((ch, idx) => {
4719
+ if (scores[ch] !== void 0) {
4720
+ scores[ch] += Math.max(0.25, 0.6 - idx * 0.1);
4721
+ }
4722
+ });
4723
+ }
4724
+ return SOURCE_CHANNELS.map((channel) => ({
4725
+ channel,
4726
+ score: Number(scores[channel].toFixed(4))
4727
+ })).sort((a, b) => b.score - a.score);
4728
+ }
4729
+ async function classifyModeAndPrior(contract, decision) {
4730
+ let requestedMode = contract.mode ?? "auto";
4731
+ if (!contract.mode && contract.profile) {
4732
+ if (contract.profile === "deep_autonomous") {
4733
+ requestedMode = "deep-research";
4734
+ } else if (contract.profile !== "auto") {
4735
+ requestedMode = "research";
4736
+ }
4737
+ }
4738
+ const contractScore = computeContractComplexityScore(contract);
4739
+ const hardEscalated = contract.acceptanceCriteria?.verifyClaims === true || (contract.acceptanceCriteria?.minPeerReviewedSources ?? 0) >= 2;
4740
+ let readingDepth = 1.5;
4741
+ let sourceDiversity = 1.5;
4742
+ let decomposition = 1 + Math.min(2, (contract.acceptanceCriteria?.requiredAttributes?.length || 0) * 0.5);
4743
+ let verificationStakes = hardEscalated ? 3.5 : 1.5;
4744
+ let decisionEvaluated = false;
4745
+ let facetProbabilities = inferFallbackFacetProbabilities(contract);
4746
+ if (decision) {
4747
+ try {
4748
+ const contextLines = [
4749
+ `Research Objective: ${contract.objective}`,
4750
+ contract.context?.hardwarePlatform ? `Hardware Platform: ${contract.context.hardwarePlatform}` : "",
4751
+ contract.context?.softwareEnv ? `Software Environment: ${contract.context.softwareEnv}` : "",
4752
+ contract.context?.ageBand ? `Target Learner Age Band: ${contract.context.ageBand[0]}-${contract.context.ageBand[1]}` : "",
4753
+ contract.acceptanceCriteria?.requiredAttributes?.length ? `Required Attributes: ${contract.acceptanceCriteria.requiredAttributes.join(", ")}` : "",
4754
+ contract.requiredSections?.length ? `Required Report Sections: ${contract.requiredSections.join(", ")}` : ""
4755
+ ].filter(Boolean).join("\n");
4756
+ const result = await decision({
4757
+ context: contextLines,
4758
+ questions: [
4759
+ {
4760
+ id: "reading_depth",
4761
+ type: "score",
4762
+ criteria: "Evaluate how much document reading depth is required to answer the research objective (0 = single snippet or quick fact lookup, 2 = full document or API tutorial reading, 4 = multi-document cross-comparison and deep synthesis)."
4763
+ },
4764
+ {
4765
+ id: "source_diversity",
4766
+ type: "score",
4767
+ criteria: "Evaluate how many distinct knowledge modalities (official web docs, peer-reviewed academic papers, developer community pulse, interactive STEM OER simulations) are required (0 = 1 source type suffices, 2 = 2 complementary channels needed, 4 = 3 or more heterogeneous channels required)."
4768
+ },
4769
+ {
4770
+ id: "decomposition",
4771
+ type: "score",
4772
+ criteria: "Evaluate how many distinct sub-questions, technical constraints, or comparative dimensions must be decomposed and resolved (0 = single atomic question, 2 = 2 to 3 related facets, 4 = 4 or more complex interdependent facets)."
4773
+ },
4774
+ {
4775
+ id: "verification_stakes",
4776
+ type: "score",
4777
+ criteria: "Evaluate the factual verification stakes and risk of conflicting claims or hallucination (0 = low-stakes lookup, 2 = standard technical or pedagogical grounding, 4 = high-stakes factual or academic audit requiring strict claim verification)."
4778
+ },
4779
+ {
4780
+ id: "question_facet",
4781
+ type: "choice",
4782
+ criteria: "Classify the primary information need of this research objective into the most fitting facet.",
4783
+ options: [...QUESTION_FACETS]
4784
+ }
4785
+ ]
4786
+ });
4787
+ const aDepth = result.answers["reading_depth"];
4788
+ const aDiv = result.answers["source_diversity"];
4789
+ const aDecomp = result.answers["decomposition"];
4790
+ const aStakes = result.answers["verification_stakes"];
4791
+ const aFacet = result.answers["question_facet"];
4792
+ if (aDepth?.type === "score") readingDepth = clampScore0to4(aDepth.score, readingDepth);
4793
+ if (aDiv?.type === "score") sourceDiversity = clampScore0to4(aDiv.score, sourceDiversity);
4794
+ if (aDecomp?.type === "score") decomposition = clampScore0to4(aDecomp.score, decomposition);
4795
+ if (aStakes?.type === "score") verificationStakes = clampScore0to4(aStakes.score, verificationStakes);
4796
+ if (aFacet?.type === "choice") {
4797
+ const rawProbs = aFacet.probabilities;
4798
+ if (rawProbs && Object.keys(rawProbs).length > 0) {
4799
+ let sum = 0;
4800
+ const nextProbs = {};
4801
+ for (const f of QUESTION_FACETS) {
4802
+ const v = Math.max(0, Number(rawProbs[f] ?? 0));
4803
+ nextProbs[f] = v;
4804
+ sum += v;
4805
+ }
4806
+ if (sum > 0) {
4807
+ for (const f of QUESTION_FACETS) {
4808
+ nextProbs[f] = Number((nextProbs[f] / sum).toFixed(4));
4809
+ }
4810
+ facetProbabilities = nextProbs;
4811
+ }
4812
+ } else if (QUESTION_FACETS.includes(aFacet.choice)) {
4813
+ const chosen = aFacet.choice;
4814
+ const nextProbs = {};
4815
+ for (const f of QUESTION_FACETS) {
4816
+ nextProbs[f] = f === chosen ? 0.7 : 0.05;
4817
+ }
4818
+ facetProbabilities = nextProbs;
4819
+ }
4820
+ }
4821
+ decisionEvaluated = true;
4822
+ } catch (e) {
4823
+ console.warn("[DecisionRouter] Decision model evaluation failed, using deterministic fallback:", e?.message || e);
4824
+ }
4825
+ }
4826
+ const totalScore = Math.max(
4827
+ 0,
4828
+ Math.min(20, Math.round(readingDepth + sourceDiversity + decomposition + verificationStakes + contractScore))
4829
+ );
4830
+ let resolvedMode;
4831
+ if (requestedMode !== "auto") {
4832
+ resolvedMode = requestedMode;
4833
+ } else if (hardEscalated || totalScore >= 13) {
4834
+ resolvedMode = "deep-research";
4835
+ } else if (totalScore <= 4) {
4836
+ resolvedMode = "search";
4837
+ } else {
4838
+ resolvedMode = "research";
4839
+ }
4840
+ const channelPriors = rankChannelsByExpectedPrior(facetProbabilities, contract);
4841
+ return {
4842
+ requestedMode,
4843
+ resolvedMode,
4844
+ decisionEvaluated,
4845
+ hardEscalated,
4846
+ rubricBreakdown: {
4847
+ readingDepth: Number(readingDepth.toFixed(2)),
4848
+ sourceDiversity: Number(sourceDiversity.toFixed(2)),
4849
+ decomposition: Number(decomposition.toFixed(2)),
4850
+ verificationStakes: Number(verificationStakes.toFixed(2)),
4851
+ contractScore,
4852
+ totalScore
4853
+ },
4854
+ facetProbabilities,
4855
+ channelPriors
4856
+ };
4857
+ }
4858
+ async function evaluateAttributeCoverageWithDecision(params) {
4859
+ const { objective, targetCheckList, receiptsText, decision } = params;
4860
+ if (targetCheckList.length === 0) {
4861
+ return { satisfied: [], missing: [] };
4862
+ }
4863
+ try {
4864
+ const questions = targetCheckList.map((attr, idx) => ({
4865
+ id: `attr_${idx}`,
4866
+ type: "noul",
4867
+ criteria: `Does the collected evidence contain concrete, substantive information addressing "${attr}" for the research objective "${objective}"?`
4868
+ }));
4869
+ const res = await decision({
4870
+ context: `Research Objective: "${objective}"
4871
+
4872
+ Collected Citation Receipts:
4873
+ ${receiptsText}`,
4874
+ questions
4875
+ });
4876
+ const satisfied = [];
4877
+ const missing = [];
4878
+ targetCheckList.forEach((attr, idx) => {
4879
+ const ans = res.answers[`attr_${idx}`];
4880
+ if (ans && ans.type === "noul" && ans.probability >= 0.55) {
4881
+ satisfied.push(attr);
4882
+ } else {
4883
+ missing.push(attr);
4884
+ }
4885
+ });
4886
+ return { satisfied, missing };
4887
+ } catch (e) {
4888
+ console.warn("[DecisionRouter] Attribute coverage noul check failed:", e?.message || e);
4889
+ return null;
4890
+ }
4891
+ }
4892
+
4893
+ // src/agent/channelScheduler.ts
4894
+ function classifyChannelStatus(itemsAdded, substantiveBytes, error) {
4895
+ if (error) return "error";
4896
+ if (itemsAdded <= 0) return "empty";
4897
+ if (itemsAdded >= 2 || substantiveBytes >= 450) return "ok";
4898
+ return "weak";
4899
+ }
4900
+ async function runConcurrentRefillScheduler(params) {
4901
+ const { channelQueue, maxChannels, signal, executeChannel } = params;
4902
+ const effectiveMax = Math.max(1, maxChannels);
4903
+ const concurrency = Math.max(1, Math.min(params.concurrency ?? 2, effectiveMax));
4904
+ const queue = [...channelQueue];
4905
+ const traces = [];
4906
+ const inFlightControllers = /* @__PURE__ */ new Set();
4907
+ let okChannels = 0;
4908
+ let stopped = false;
4909
+ const abortAllInFlight = () => {
4910
+ stopped = true;
4911
+ for (const ctrl of inFlightControllers) {
4912
+ try {
4913
+ ctrl.abort();
4914
+ } catch {
4915
+ }
4916
+ }
4917
+ inFlightControllers.clear();
4918
+ };
4919
+ if (signal) {
4920
+ if (signal.aborted) {
4921
+ return { traces: [], okChannels: 0 };
4922
+ }
4923
+ signal.addEventListener("abort", abortAllInFlight, { once: true });
4924
+ }
4925
+ return new Promise((resolve) => {
4926
+ let settled = false;
4927
+ const finishIfDone = () => {
4928
+ if (settled) return;
4929
+ if (stopped || okChannels >= effectiveMax || queue.length === 0 && inFlightControllers.size === 0) {
4930
+ settled = true;
4931
+ if (signal) {
4932
+ signal.removeEventListener("abort", onExternalAbort);
4933
+ }
4934
+ abortAllInFlight();
4935
+ resolve({ traces, okChannels });
4936
+ }
4937
+ };
4938
+ const onExternalAbort = () => {
4939
+ abortAllInFlight();
4940
+ finishIfDone();
4941
+ };
4942
+ const scheduleNext = () => {
4943
+ if (settled || stopped || signal?.aborted) {
4944
+ finishIfDone();
4945
+ return;
4946
+ }
4947
+ const remainingNeeded = effectiveMax - okChannels;
4948
+ const targetInFlight = Math.min(concurrency, remainingNeeded);
4949
+ while (!stopped && inFlightControllers.size < targetInFlight && queue.length > 0) {
4950
+ const next = queue.shift();
4951
+ if (!next) break;
4952
+ const channelController = new AbortController();
4953
+ inFlightControllers.add(channelController);
4954
+ const startMs = Date.now();
4955
+ executeChannel(next.channel, next.score, channelController.signal).then((trace) => {
4956
+ inFlightControllers.delete(channelController);
4957
+ if (settled || stopped) {
4958
+ finishIfDone();
4959
+ return;
4960
+ }
4961
+ traces.push(trace);
4962
+ if (trace.status === "ok") {
4963
+ okChannels += 1;
4964
+ if (okChannels >= effectiveMax) {
4965
+ abortAllInFlight();
4966
+ finishIfDone();
4967
+ return;
4968
+ }
4969
+ }
4970
+ scheduleNext();
4971
+ }).catch((err) => {
4972
+ inFlightControllers.delete(channelController);
4973
+ if (settled || stopped) {
4974
+ finishIfDone();
4975
+ return;
4976
+ }
4977
+ traces.push({
4978
+ channel: next.channel,
4979
+ status: "error",
4980
+ priorScore: next.score,
4981
+ itemsAdded: 0,
4982
+ durationMs: Date.now() - startMs,
4983
+ errorMessage: err?.message || String(err)
4984
+ });
4985
+ scheduleNext();
4986
+ });
4987
+ }
4988
+ finishIfDone();
4989
+ };
4990
+ scheduleNext();
4991
+ });
4992
+ }
4517
4993
  function describeZodSchemaKeys(schema) {
4518
4994
  if (!schema) return void 0;
4519
4995
  const def = schema?._def;
@@ -4545,6 +5021,16 @@ function resolveResearchProfile(contract) {
4545
5021
  }
4546
5022
  return "general";
4547
5023
  }
5024
+ function isSemanticRankedHit(hit) {
5025
+ return hit.engine === "exa" || hit.engine === "tavily" || hit.engine === "academic" || typeof hit.score === "number" && hit.score > 0;
5026
+ }
5027
+ function computeNativeHitScore(hit, defaultSemantic = 8, defaultLexical = 6) {
5028
+ if (typeof hit.score === "number" && hit.score > 0) {
5029
+ const scaled = hit.score <= 1 ? hit.score * 10 : hit.score;
5030
+ return Math.max(6, Math.min(10, Math.round(scaled)));
5031
+ }
5032
+ return isSemanticRankedHit(hit) ? defaultSemantic : defaultLexical;
5033
+ }
4548
5034
  var ResearchSubAgent = class {
4549
5035
  constructor(config = {}) {
4550
5036
  this.config = config;
@@ -4568,6 +5054,7 @@ var ResearchSubAgent = class {
4568
5054
  this.openAlexClient = new OpenAlexClient();
4569
5055
  this.socialPulseHarvester = new SocialPulseHarvester(this.searchEngine);
4570
5056
  this.stemResearcher = new StemResourceResearcher();
5057
+ this.youtubeService = new YouTubeIngestionService();
4571
5058
  this.healthAuditor = new HealthAuditor();
4572
5059
  this.evidenceScorer = new EvidenceScorer();
4573
5060
  this.claimVerifier = new ClaimVerifier();
@@ -4579,6 +5066,7 @@ var ResearchSubAgent = class {
4579
5066
  openAlexClient;
4580
5067
  socialPulseHarvester;
4581
5068
  stemResearcher;
5069
+ youtubeService;
4582
5070
  healthAuditor;
4583
5071
  evidenceScorer;
4584
5072
  claimVerifier;
@@ -4588,70 +5076,122 @@ var ResearchSubAgent = class {
4588
5076
  */
4589
5077
  async run(contract, options) {
4590
5078
  const llm = options?.llm ?? this.config.llm;
5079
+ const decision = options?.decision ?? this.config.decision;
5080
+ const modeTrace = await classifyModeAndPrior(contract, decision);
5081
+ const resolvedMode = modeTrace.resolvedMode;
5082
+ const modePreset = RESEARCH_MODE_PRESETS[resolvedMode];
4591
5083
  const resolvedProfile = resolveResearchProfile(contract);
4592
- const preset = RESEARCH_PROFILE_PRESETS[resolvedProfile];
5084
+ const profilePreset = RESEARCH_PROFILE_PRESETS[resolvedProfile];
4593
5085
  const ctx = contract.context ?? this.config.defaultCourseContext;
4594
5086
  const domain = classifyTechnicalDomain(contract.objective, void 0, ctx).domain;
4595
- const maxRounds = Math.max(1, Math.min(5, contract.budget?.maxRounds ?? preset.maxRounds));
4596
- const maxQueriesPerRound = Math.max(1, Math.min(6, contract.budget?.maxQueriesPerRound ?? preset.maxQueriesPerRound));
4597
- const maxScrapePerRound = Math.max(1, Math.min(6, contract.budget?.maxScrapePerRound ?? preset.maxScrapePerRound));
4598
- const minSources = contract.acceptanceCriteria?.minSources ?? 2;
5087
+ const timeoutMs = Math.max(1e3, contract.budget?.timeoutMs ?? modePreset.timeoutMs);
5088
+ const maxChannels = Math.max(1, Math.min(5, contract.budget?.maxChannels ?? modePreset.maxChannels));
5089
+ const channelConcurrency = Math.max(
5090
+ 1,
5091
+ Math.min(3, contract.budget?.channelConcurrency ?? modePreset.channelConcurrency)
5092
+ );
5093
+ const maxRounds = resolvedMode === "search" ? 1 : Math.max(1, Math.min(5, contract.budget?.maxRounds ?? modePreset.maxRounds));
5094
+ const maxQueriesPerRound = Math.max(
5095
+ 1,
5096
+ Math.min(6, contract.budget?.maxQueriesPerRound ?? modePreset.maxQueriesPerRound)
5097
+ );
5098
+ const maxScrapePerRound = resolvedMode === "search" ? contract.budget?.maxScrapePerRound ?? 0 : Math.max(0, Math.min(6, contract.budget?.maxScrapePerRound ?? modePreset.maxScrapePerRound));
5099
+ const minSources = contract.acceptanceCriteria?.minSources ?? (resolvedMode === "search" ? 1 : 2);
4599
5100
  const minRelevanceScore = contract.acceptanceCriteria?.minRelevanceScore ?? 6;
4600
5101
  const recencyDays = contract.acceptanceCriteria?.recencyDays ?? 30;
5102
+ const shouldVerifyClaims = contract.acceptanceCriteria?.verifyClaims ?? modePreset.verifyClaims;
5103
+ const harvestBudgetMs = resolvedMode === "search" ? timeoutMs : Math.floor(timeoutMs * 0.75);
5104
+ const harvestAbortController = new AbortController();
5105
+ const harvestTimer = setTimeout(() => {
5106
+ harvestAbortController.abort();
5107
+ }, harvestBudgetMs);
5108
+ if (contract.signal) {
5109
+ if (contract.signal.aborted) {
5110
+ harvestAbortController.abort();
5111
+ } else {
5112
+ contract.signal.addEventListener("abort", () => harvestAbortController.abort(), { once: true });
5113
+ }
5114
+ }
4601
5115
  const ledger = new EvidenceLedger();
4602
5116
  const executedQueries = /* @__PURE__ */ new Set();
4603
5117
  const scrapedUrls = /* @__PURE__ */ new Set();
4604
5118
  const roundTraces = [];
5119
+ const allChannelTraces = [];
4605
5120
  let currentMissingGaps = [
4606
5121
  ...contract.acceptanceCriteria?.requiredAttributes || [],
4607
5122
  ...contract.requiredSections || []
4608
5123
  ];
4609
- for (let round = 1; round <= maxRounds; round++) {
4610
- const beforeReceiptCount = ledger.getReceipts().length;
4611
- const plannedQueries = await this.planQueriesForRound({
4612
- round,
4613
- contract,
4614
- profile: resolvedProfile,
4615
- missingGaps: currentMissingGaps,
4616
- receipts: ledger.getReceipts(),
4617
- executedQueries,
4618
- maxQueries: maxQueriesPerRound,
4619
- llm
4620
- });
4621
- for (const q of plannedQueries) {
4622
- executedQueries.add(q.toLowerCase());
4623
- }
4624
- await this.executeHarvestRound({
4625
- round,
4626
- queries: plannedQueries,
4627
- contract,
4628
- preset,
4629
- domain,
4630
- recencyDays,
4631
- maxScrapePerRound,
4632
- scrapedUrls,
4633
- ledger
4634
- });
4635
- const afterReceiptCount = ledger.getReceipts().length;
4636
- const newReceiptsAdded = afterReceiptCount - beforeReceiptCount;
4637
- const evaluation = await this.evaluateRoundGaps({
4638
- contract,
4639
- ledger,
4640
- minSources,
4641
- minRelevanceScore,
4642
- llm
4643
- });
4644
- currentMissingGaps = evaluation.missingGaps;
4645
- roundTraces.push({
4646
- round,
4647
- plannedQueries,
4648
- newReceiptsAdded,
4649
- satisfiedAttributes: evaluation.satisfiedAttributes,
4650
- missingGaps: evaluation.missingGaps
4651
- });
4652
- if (evaluation.missingGaps.length === 0) {
4653
- break;
5124
+ try {
5125
+ for (let round = 1; round <= maxRounds; round++) {
5126
+ if (harvestAbortController.signal.aborted) {
5127
+ break;
5128
+ }
5129
+ const beforeReceiptCount = ledger.getReceipts().length;
5130
+ const plannedQueries = await this.planQueriesForRound({
5131
+ round,
5132
+ contract,
5133
+ mode: resolvedMode,
5134
+ profile: resolvedProfile,
5135
+ missingGaps: currentMissingGaps,
5136
+ receipts: ledger.getReceipts(),
5137
+ executedQueries,
5138
+ maxQueries: maxQueriesPerRound,
5139
+ llm: resolvedMode === "search" ? void 0 : llm
5140
+ });
5141
+ for (const q of plannedQueries) {
5142
+ executedQueries.add(q.toLowerCase());
5143
+ }
5144
+ const roundChannelQueue = this.buildRoundChannelQueue(
5145
+ round,
5146
+ modeTrace.channelPriors,
5147
+ profilePreset,
5148
+ contract
5149
+ );
5150
+ const schedulerResult = await runConcurrentRefillScheduler({
5151
+ channelQueue: roundChannelQueue,
5152
+ maxChannels,
5153
+ concurrency: channelConcurrency,
5154
+ signal: harvestAbortController.signal,
5155
+ executeChannel: (channel, priorScore, channelSignal) => this.executeSingleChannel({
5156
+ channel,
5157
+ priorScore,
5158
+ queries: plannedQueries,
5159
+ contract,
5160
+ domain,
5161
+ recencyDays,
5162
+ maxScrapePerRound,
5163
+ scrapedUrls,
5164
+ ledger,
5165
+ signal: channelSignal
5166
+ })
5167
+ });
5168
+ allChannelTraces.push(...schedulerResult.traces);
5169
+ const afterReceiptCount = ledger.getReceipts().length;
5170
+ const newReceiptsAdded = afterReceiptCount - beforeReceiptCount;
5171
+ const evaluation = await this.evaluateRoundGaps({
5172
+ contract,
5173
+ mode: resolvedMode,
5174
+ ledger,
5175
+ minSources,
5176
+ minRelevanceScore,
5177
+ decision: resolvedMode === "search" ? void 0 : decision,
5178
+ llm: resolvedMode === "search" ? void 0 : llm
5179
+ });
5180
+ currentMissingGaps = evaluation.missingGaps;
5181
+ roundTraces.push({
5182
+ round,
5183
+ plannedQueries,
5184
+ newReceiptsAdded,
5185
+ satisfiedAttributes: evaluation.satisfiedAttributes,
5186
+ missingGaps: evaluation.missingGaps,
5187
+ channelTraces: schedulerResult.traces
5188
+ });
5189
+ if (evaluation.missingGaps.length === 0) {
5190
+ break;
5191
+ }
4654
5192
  }
5193
+ } finally {
5194
+ clearTimeout(harvestTimer);
4655
5195
  }
4656
5196
  const allItems = ledger.getItems();
4657
5197
  const approvedItems = ledger.getApprovedItems(minRelevanceScore);
@@ -4664,6 +5204,7 @@ var ResearchSubAgent = class {
4664
5204
  return {
4665
5205
  status: "failed",
4666
5206
  objective: contract.objective,
5207
+ mode: resolvedMode,
4667
5208
  profile: resolvedProfile,
4668
5209
  roundsExecuted: roundTraces.length,
4669
5210
  data: null,
@@ -4681,36 +5222,306 @@ ${currentMissingGaps.length > 0 ? currentMissingGaps.map((g) => `- ${g}`).join("
4681
5222
  invalidCitationIds: [],
4682
5223
  missingGaps: currentMissingGaps.length > 0 ? currentMissingGaps : ["minSources not met (0 harvested)"],
4683
5224
  roundTraces,
5225
+ modeClassificationTrace: modeTrace,
5226
+ channelTraces: allChannelTraces,
5227
+ provenanceMd: provenanceSidecar.provenanceMd
5228
+ };
5229
+ }
5230
+ if (resolvedMode === "search") {
5231
+ const receipts = ledger.getReceipts();
5232
+ const markdownReport = this.buildDeterministicMarkdownReport(
5233
+ contract.objective,
5234
+ resolvedProfile,
5235
+ allItems,
5236
+ contract.requiredSections
5237
+ );
5238
+ const tier1Summary = allItems.slice(0, 3).map((i) => `[${i.id}] ${i.title}: ${i.keyExcerpts[0] || ""}`).join(" ");
5239
+ const tier2TechnicalDigest = allItems.slice(0, 6).map((i) => `- **[${i.id}] ${i.title}** (${i.url}): ${i.keyExcerpts.slice(0, 2).join(" ")}`).join("\n");
5240
+ return {
5241
+ status: approvedItems.length >= minSources ? "success" : "partial",
5242
+ objective: contract.objective,
5243
+ mode: resolvedMode,
5244
+ profile: resolvedProfile,
5245
+ roundsExecuted: roundTraces.length,
5246
+ data: {
5247
+ objective: contract.objective,
5248
+ mode: resolvedMode,
5249
+ sources: receipts
5250
+ },
5251
+ markdownReport,
5252
+ tier1Summary,
5253
+ tier2TechnicalDigest,
5254
+ ledgerItems: allItems,
5255
+ receipts,
5256
+ validCitationIds: allItems.map((i) => i.id),
5257
+ invalidCitationIds: [],
5258
+ missingGaps: currentMissingGaps,
5259
+ roundTraces,
5260
+ modeClassificationTrace: modeTrace,
5261
+ channelTraces: allChannelTraces,
4684
5262
  provenanceMd: provenanceSidecar.provenanceMd
4685
5263
  };
4686
5264
  }
4687
5265
  return this.synthesizeAndVerify({
4688
5266
  contract,
5267
+ mode: resolvedMode,
4689
5268
  profile: resolvedProfile,
4690
5269
  domain,
4691
5270
  ledger,
4692
5271
  approvedCount: approvedItems.length,
4693
5272
  minSources,
5273
+ shouldVerifyClaims,
4694
5274
  missingGaps: currentMissingGaps,
4695
5275
  roundTraces,
5276
+ modeClassificationTrace: modeTrace,
5277
+ channelTraces: allChannelTraces,
4696
5278
  provenanceMd: provenanceSidecar.provenanceMd,
4697
- llm
5279
+ llm,
5280
+ decision
4698
5281
  });
4699
5282
  }
5283
+ /**
5284
+ * Builds the Prior-sorted channel queue for a specific round.
5285
+ */
5286
+ buildRoundChannelQueue(round, channelPriors, profilePreset, contract) {
5287
+ if (contract.preferredChannels && contract.preferredChannels.length > 0) {
5288
+ const preferredSet = new Set(contract.preferredChannels);
5289
+ const preferred = channelPriors.filter((c) => preferredSet.has(c.channel));
5290
+ const others = channelPriors.filter((c) => !preferredSet.has(c.channel));
5291
+ if (this.config.allowEnvFallback === false) {
5292
+ return preferred;
5293
+ }
5294
+ return [...preferred, ...others];
5295
+ }
5296
+ if (contract.profile && contract.profile !== "auto") {
5297
+ const filtered = channelPriors.filter((c) => {
5298
+ if (c.channel === "web_docs") return profilePreset.enableWeb;
5299
+ if (c.channel === "academic") return profilePreset.enableAcademic;
5300
+ if (c.channel === "social_pulse") return profilePreset.enableSocialPulse;
5301
+ if (c.channel === "stem_oer") return profilePreset.enableStemOer;
5302
+ return false;
5303
+ });
5304
+ if (filtered.length > 0) {
5305
+ return filtered;
5306
+ }
5307
+ }
5308
+ if (this.config.allowEnvFallback === false) {
5309
+ const isolated = channelPriors.filter((c) => {
5310
+ if (c.channel === "web_docs") return Boolean(this.config.customSearchAdapter || this.config.apiKeys);
5311
+ if (c.channel === "academic") return Boolean(this.config.customAcademicSearchAdapter || this.config.apiKeys?.semanticScholar);
5312
+ return false;
5313
+ });
5314
+ if (isolated.length > 0) {
5315
+ return isolated;
5316
+ }
5317
+ }
5318
+ if (round > 1) {
5319
+ return [...channelPriors].sort((a, b) => {
5320
+ const boostA = a.channel === "web_docs" ? 0.3 : a.channel === "academic" ? 0.2 : 0;
5321
+ const boostB = b.channel === "web_docs" ? 0.3 : b.channel === "academic" ? 0.2 : 0;
5322
+ return b.score + boostB - (a.score + boostA);
5323
+ });
5324
+ }
5325
+ return [...channelPriors];
5326
+ }
5327
+ /**
5328
+ * Executes a single source channel and classifies its outcome (`'ok' | 'weak' | 'empty' | 'error'`)
5329
+ * using Non-Redundant Evidence Gating (ADR-0019).
5330
+ */
5331
+ async executeSingleChannel(params) {
5332
+ const {
5333
+ channel,
5334
+ priorScore,
5335
+ queries,
5336
+ contract,
5337
+ domain,
5338
+ recencyDays,
5339
+ maxScrapePerRound,
5340
+ scrapedUrls,
5341
+ ledger,
5342
+ signal
5343
+ } = params;
5344
+ const startMs = Date.now();
5345
+ const beforeItems = ledger.getItems().length;
5346
+ let substantiveBytes = 0;
5347
+ try {
5348
+ if (signal.aborted) {
5349
+ return {
5350
+ channel,
5351
+ status: "empty",
5352
+ priorScore,
5353
+ itemsAdded: 0,
5354
+ durationMs: 0
5355
+ };
5356
+ }
5357
+ if (channel === "web_docs") {
5358
+ const candidateHits = [];
5359
+ for (const q of queries) {
5360
+ if (signal.aborted) break;
5361
+ try {
5362
+ const hits = await this.searchEngine.search(q, { limit: 3 });
5363
+ for (const h of hits) {
5364
+ if (!isCommercialOrNoise({ url: h.url, title: h.title, snippet: h.content })) {
5365
+ if (!candidateHits.some((existing) => existing.url === h.url)) {
5366
+ candidateHits.push(h);
5367
+ }
5368
+ }
5369
+ }
5370
+ } catch {
5371
+ }
5372
+ }
5373
+ const urlsToScrape = maxScrapePerRound > 0 ? candidateHits.filter((h) => !scrapedUrls.has(h.url)).slice(0, maxScrapePerRound) : [];
5374
+ if (urlsToScrape.length > 0 && !signal.aborted) {
5375
+ await Promise.allSettled(
5376
+ urlsToScrape.map(async (hit) => {
5377
+ if (signal.aborted) return;
5378
+ scrapedUrls.add(hit.url);
5379
+ try {
5380
+ const doc = await this.webScraper.scrapeUrl(hit.url);
5381
+ const health = this.healthAuditor.auditDocument(doc);
5382
+ if (health.passed && doc.markdownContent.trim().length > 80) {
5383
+ if (isSemanticRankedHit(hit)) {
5384
+ const nativeScore = computeNativeHitScore(hit, 8, 7);
5385
+ const takeaways = extractTopSentences(doc.markdownContent, contract.objective, 3);
5386
+ const receipt = ledger.addScrapedDocument(doc, nativeScore, takeaways);
5387
+ const added = ledger.getById(receipt.id);
5388
+ substantiveBytes += added?.rawByteSize || doc.byteSize || 1e3;
5389
+ return;
5390
+ } else {
5391
+ const scored = this.evidenceScorer.scoreDocument(doc, domain, contract.objective);
5392
+ const receipt = ledger.addScrapedDocument(doc, scored.score, scored.keyTakeaways);
5393
+ const added = ledger.getById(receipt.id);
5394
+ substantiveBytes += added?.rawByteSize || doc.byteSize || 800;
5395
+ return;
5396
+ }
5397
+ }
5398
+ } catch {
5399
+ }
5400
+ if (hit.content && hit.content.trim().length > 30) {
5401
+ const hitScore = computeNativeHitScore(hit, 7, 6);
5402
+ ledger.addSearchHit(hit, hitScore);
5403
+ substantiveBytes += Buffer.byteLength(hit.content, "utf-8");
5404
+ }
5405
+ })
5406
+ );
5407
+ }
5408
+ const remainingHits = maxScrapePerRound > 0 ? candidateHits.slice(maxScrapePerRound, maxScrapePerRound + 3) : candidateHits.slice(0, 5);
5409
+ for (const hit of remainingHits) {
5410
+ if (hit.content && hit.content.trim().length > 35) {
5411
+ const hitScore = computeNativeHitScore(hit, 7, 6);
5412
+ ledger.addSearchHit(hit, hitScore);
5413
+ substantiveBytes += Math.max(
5414
+ maxScrapePerRound === 0 ? 500 : 100,
5415
+ Buffer.byteLength(hit.content, "utf-8")
5416
+ );
5417
+ }
5418
+ }
5419
+ } else if (channel === "academic") {
5420
+ const primaryQuery = queries[0] || contract.objective;
5421
+ const [s2Papers, oaPapers] = await Promise.all([
5422
+ this.academicEngine.searchPapers(primaryQuery, { limit: 3 }).catch(() => []),
5423
+ this.openAlexClient.searchWorks(primaryQuery, { limit: 3 }).catch(() => [])
5424
+ ]);
5425
+ for (const p of [...s2Papers, ...oaPapers].slice(0, 5)) {
5426
+ const receipt = ledger.addAcademicPaper(p);
5427
+ const item = ledger.getById(receipt.id);
5428
+ substantiveBytes += Math.max(850, item?.rawByteSize || 0);
5429
+ }
5430
+ } else if (channel === "social_pulse") {
5431
+ const pulseReport = await this.socialPulseHarvester.harvest(contract.objective, {
5432
+ recencyDays,
5433
+ limitPerPlatform: 3
5434
+ });
5435
+ for (const item of pulseReport.items.slice(0, 5)) {
5436
+ ledger.addSocialPulseItem(item);
5437
+ substantiveBytes += Math.max(450, Buffer.byteLength(item.snippet || "", "utf-8"));
5438
+ }
5439
+ } else if (channel === "stem_oer") {
5440
+ const oerCatalog = await this.stemResearcher.findResources(contract.objective, {
5441
+ limit: 4
5442
+ });
5443
+ for (const res of oerCatalog.resources.slice(0, 4)) {
5444
+ ledger.addStemResource({
5445
+ title: res.title,
5446
+ url: res.url,
5447
+ description: res.description,
5448
+ provider: res.provider,
5449
+ license: res.license?.type
5450
+ });
5451
+ substantiveBytes += Math.max(500, Buffer.byteLength(res.description || "", "utf-8"));
5452
+ }
5453
+ } else if (channel === "video_media") {
5454
+ const videoQuery = `${queries[0] || contract.objective} site:youtube.com tutorial lecture`;
5455
+ const hits = await this.searchEngine.search(videoQuery, { limit: 3 });
5456
+ for (const h of hits.slice(0, 3)) {
5457
+ if (signal.aborted) break;
5458
+ if (/youtube\.com\/watch|youtu\.be\//i.test(h.url)) {
5459
+ try {
5460
+ const transcript = await this.youtubeService.fetchTranscript(h.url, ["vi", "en"]);
5461
+ if (transcript && transcript.stitchedMarkdown && transcript.stitchedMarkdown.length > 60) {
5462
+ ledger.addScrapedDocument(
5463
+ {
5464
+ url: h.url,
5465
+ title: transcript.title || h.title || "YouTube Educational Video",
5466
+ markdownContent: transcript.stitchedMarkdown,
5467
+ byteSize: Buffer.byteLength(transcript.stitchedMarkdown, "utf-8"),
5468
+ extractedCodeSnippets: [],
5469
+ tablesCount: 0,
5470
+ fetchProvider: "youtube",
5471
+ keyExcerpts: [transcript.stitchedMarkdown.slice(0, 450)]
5472
+ },
5473
+ 8
5474
+ );
5475
+ substantiveBytes += Buffer.byteLength(transcript.stitchedMarkdown, "utf-8");
5476
+ continue;
5477
+ }
5478
+ } catch {
5479
+ }
5480
+ }
5481
+ if (h.content && h.content.trim().length > 30) {
5482
+ ledger.addSearchHit(h, 6);
5483
+ substantiveBytes += Buffer.byteLength(h.content, "utf-8");
5484
+ }
5485
+ }
5486
+ }
5487
+ const itemsAdded = Math.max(0, ledger.getItems().length - beforeItems);
5488
+ const status = classifyChannelStatus(itemsAdded, substantiveBytes);
5489
+ return {
5490
+ channel,
5491
+ status,
5492
+ priorScore,
5493
+ itemsAdded,
5494
+ durationMs: Date.now() - startMs
5495
+ };
5496
+ } catch (err) {
5497
+ const itemsAdded = Math.max(0, ledger.getItems().length - beforeItems);
5498
+ return {
5499
+ channel,
5500
+ status: itemsAdded > 0 ? classifyChannelStatus(itemsAdded, substantiveBytes) : "error",
5501
+ priorScore,
5502
+ itemsAdded,
5503
+ durationMs: Date.now() - startMs,
5504
+ errorMessage: err?.message || String(err)
5505
+ };
5506
+ }
5507
+ }
4700
5508
  /**
4701
5509
  * Plans targeted search queries for Round 1 (initial coverage) or Round > 1 (surgical gap filling).
4702
5510
  */
4703
5511
  async planQueriesForRound(params) {
4704
- const { round, contract, profile, missingGaps, receipts, executedQueries, maxQueries, llm } = params;
5512
+ const { round, contract, mode, profile, missingGaps, receipts, executedQueries, maxQueries, llm } = params;
4705
5513
  const ctx = contract.context ?? this.config.defaultCourseContext;
4706
5514
  const toolAnchor = [ctx?.hardwarePlatform, ctx?.softwareEnv].filter(Boolean).join(" ").trim();
4707
5515
  const baseTopic = toolAnchor ? `${toolAnchor} ${contract.objective}` : contract.objective;
5516
+ if (mode === "search") {
5517
+ return [baseTopic.trim()].slice(0, maxQueries);
5518
+ }
4708
5519
  if (llm) {
4709
5520
  try {
4710
5521
  const promptLines = [
4711
5522
  `You are a Principal Research Planner for an autonomous Plan-and-Execute Research Sub-Agent.`,
4712
5523
  `Objective: "${contract.objective}"`,
4713
- `Profile: ${profile} | Round: ${round}`,
5524
+ `Mode: ${mode} | Profile: ${profile} | Round: ${round}`,
4714
5525
  toolAnchor ? `Hardware/Software Context: ${toolAnchor}` : "",
4715
5526
  ctx?.ageBand ? `Target Learner Age Band: ${ctx.ageBand[0]}-${ctx.ageBand[1]}` : "",
4716
5527
  contract.requiredSections?.length ? `Required Sections: ${contract.requiredSections.join(", ")}` : "",
@@ -4779,122 +5590,13 @@ Generate ${maxQueries} high-precision search queries to fulfill ${round === 1 ?
4779
5590
  }
4780
5591
  return fallbackQueries.filter((q) => !executedQueries.has(q.toLowerCase())).slice(0, maxQueries);
4781
5592
  }
4782
- /**
4783
- * Executes active harvesters in parallel and stores results in the Out-of-Band `EvidenceLedger`.
4784
- */
4785
- async executeHarvestRound(params) {
4786
- const { round, queries, contract, preset, domain, recencyDays, maxScrapePerRound, scrapedUrls, ledger } = params;
4787
- if (queries.length === 0) return;
4788
- const tasks = [];
4789
- if (preset.enableWeb) {
4790
- tasks.push(
4791
- (async () => {
4792
- const candidateHits = [];
4793
- for (const q of queries) {
4794
- try {
4795
- const hits = await this.searchEngine.search(q, { limit: 3 });
4796
- for (const h of hits) {
4797
- if (!isCommercialOrNoise({ url: h.url, title: h.title, snippet: h.content })) {
4798
- if (!candidateHits.some((existing) => existing.url === h.url)) {
4799
- candidateHits.push(h);
4800
- }
4801
- }
4802
- }
4803
- } catch {
4804
- }
4805
- }
4806
- const urlsToScrape = candidateHits.filter((h) => !scrapedUrls.has(h.url)).slice(0, maxScrapePerRound);
4807
- await Promise.allSettled(
4808
- urlsToScrape.map(async (hit) => {
4809
- scrapedUrls.add(hit.url);
4810
- try {
4811
- const doc = await this.webScraper.scrapeUrl(hit.url);
4812
- const health = this.healthAuditor.auditDocument(doc);
4813
- if (health.passed && doc.markdownContent.trim().length > 80) {
4814
- const scored = this.evidenceScorer.scoreDocument(doc, domain, contract.objective);
4815
- ledger.addScrapedDocument(doc, scored.score, scored.keyTakeaways);
4816
- return;
4817
- }
4818
- } catch {
4819
- }
4820
- if (hit.content && hit.content.trim().length > 30) {
4821
- ledger.addSearchHit(hit, 6);
4822
- }
4823
- })
4824
- );
4825
- for (const hit of candidateHits.slice(maxScrapePerRound, maxScrapePerRound + 2)) {
4826
- if (hit.content && hit.content.trim().length > 40) {
4827
- ledger.addSearchHit(hit, 6);
4828
- }
4829
- }
4830
- })()
4831
- );
4832
- }
4833
- if (preset.enableAcademic && round === 1) {
4834
- tasks.push(
4835
- (async () => {
4836
- try {
4837
- const primaryQuery = queries[0] || contract.objective;
4838
- const [s2Papers, oaPapers] = await Promise.all([
4839
- this.academicEngine.searchPapers(primaryQuery, { limit: 3 }),
4840
- this.openAlexClient.searchWorks(primaryQuery, { limit: 3 })
4841
- ]);
4842
- for (const p of [...s2Papers, ...oaPapers].slice(0, 5)) {
4843
- ledger.addAcademicPaper(p);
4844
- }
4845
- } catch (e) {
4846
- console.warn("[ResearchSubAgent] Academic harvest error:", e?.message || e);
4847
- }
4848
- })()
4849
- );
4850
- }
4851
- if (preset.enableSocialPulse && round === 1) {
4852
- tasks.push(
4853
- (async () => {
4854
- try {
4855
- const pulseReport = await this.socialPulseHarvester.harvest(contract.objective, {
4856
- recencyDays,
4857
- limitPerPlatform: 3
4858
- });
4859
- for (const item of pulseReport.items.slice(0, 5)) {
4860
- ledger.addSocialPulseItem(item);
4861
- }
4862
- } catch (e) {
4863
- console.warn("[ResearchSubAgent] Social pulse harvest error:", e?.message || e);
4864
- }
4865
- })()
4866
- );
4867
- }
4868
- if (preset.enableStemOer && round === 1) {
4869
- tasks.push(
4870
- (async () => {
4871
- try {
4872
- const oerCatalog = await this.stemResearcher.findResources(contract.objective, {
4873
- limit: 4
4874
- });
4875
- for (const res of oerCatalog.resources.slice(0, 4)) {
4876
- ledger.addStemResource({
4877
- title: res.title,
4878
- url: res.url,
4879
- description: res.description,
4880
- provider: res.provider,
4881
- license: res.license?.type
4882
- });
4883
- }
4884
- } catch (e) {
4885
- console.warn("[ResearchSubAgent] STEM OER harvest error:", e?.message || e);
4886
- }
4887
- })()
4888
- );
4889
- }
4890
- await Promise.allSettled(tasks);
4891
- }
4892
5593
  /**
4893
5594
  * Evaluates whether the current `EvidenceLedger` satisfies `acceptanceCriteria`,
4894
5595
  * `requiredAttributes`, and `requiredSections`.
5596
+ * Prioritizes Decision Model (`noul`) over Generative LLM when available (ADR-0019).
4895
5597
  */
4896
5598
  async evaluateRoundGaps(params) {
4897
- const { contract, ledger, minSources, minRelevanceScore, llm } = params;
5599
+ const { contract, ledger, minSources, minRelevanceScore, decision, llm } = params;
4898
5600
  const missingGaps = [];
4899
5601
  const satisfiedAttributes = [];
4900
5602
  const approved = ledger.getApprovedItems(minRelevanceScore);
@@ -4903,6 +5605,16 @@ Generate ${maxQueries} high-precision search queries to fulfill ${round === 1 ?
4903
5605
  } else {
4904
5606
  satisfiedAttributes.push(`minSources(${approved.length}/${minSources})`);
4905
5607
  }
5608
+ if (contract.acceptanceCriteria?.minPeerReviewedSources) {
5609
+ const academicCount = ledger.getItems().filter((i) => i.sourceType === "academic").length;
5610
+ if (academicCount < contract.acceptanceCriteria.minPeerReviewedSources) {
5611
+ missingGaps.push(
5612
+ `Need at least ${contract.acceptanceCriteria.minPeerReviewedSources} peer-reviewed academic sources (currently ${academicCount})`
5613
+ );
5614
+ } else {
5615
+ satisfiedAttributes.push(`peerReviewedSources(${academicCount}/${contract.acceptanceCriteria.minPeerReviewedSources})`);
5616
+ }
5617
+ }
4906
5618
  if (contract.acceptanceCriteria?.requireCodeExamples && ledger.getTotalCodeBlocks() === 0) {
4907
5619
  missingGaps.push("Missing verified code examples / syntax snippets");
4908
5620
  } else if (contract.acceptanceCriteria?.requireCodeExamples) {
@@ -4921,53 +5633,141 @@ Generate ${maxQueries} high-precision search queries to fulfill ${round === 1 ?
4921
5633
  const receipts = ledger.getReceipts();
4922
5634
  if (receipts.length === 0) {
4923
5635
  missingGaps.push(...targetCheckList);
4924
- } else if (llm) {
4925
- try {
4926
- const prompt = [
4927
- `Evaluate which of the required attributes/sections are covered by the collected Citation Receipts for "${contract.objective}".`,
4928
- `Required Items: ${JSON.stringify(targetCheckList)}`,
4929
- `Collected Citation Receipts:
4930
- ${receipts.map((r) => `- [${r.id}] ${r.title} (headings: ${r.headings.join(", ")}): ${r.briefExcerpt}`).join("\n")}`,
4931
- `Return ONLY a JSON object: {"satisfied": ["item1"], "missing": ["item2"]}`
4932
- ].join("\n");
4933
- const raw = await llm(prompt, {
4934
- system: 'Output strictly valid JSON object with "satisfied" and "missing" string arrays.',
4935
- temperature: 0.1,
4936
- jsonMode: true
5636
+ } else {
5637
+ const receiptsText = receipts.map((r) => `- [${r.id}] ${r.title} (headings: ${r.headings.join(", ")}): ${r.briefExcerpt}`).join("\n");
5638
+ if (decision) {
5639
+ const decEval = await evaluateAttributeCoverageWithDecision({
5640
+ objective: contract.objective,
5641
+ targetCheckList,
5642
+ receiptsText,
5643
+ decision
4937
5644
  });
4938
- const match = raw.match(/\{[\s\S]*\}/);
4939
- if (match) {
4940
- const parsed = JSON.parse(match[0]);
4941
- if (Array.isArray(parsed.satisfied)) {
4942
- satisfiedAttributes.push(...parsed.satisfied.map(String));
4943
- }
4944
- if (Array.isArray(parsed.missing)) {
4945
- missingGaps.push(...parsed.missing.map(String));
4946
- }
5645
+ if (decEval) {
5646
+ satisfiedAttributes.push(...decEval.satisfied);
5647
+ missingGaps.push(...decEval.missing);
4947
5648
  return { satisfiedAttributes, missingGaps };
4948
5649
  }
4949
- } catch {
4950
5650
  }
4951
- }
4952
- const lowerCorpus = ledger.buildFullRawCorpus().toLowerCase();
4953
- for (const reqItem of targetCheckList) {
4954
- const tokens = reqItem.toLowerCase().replace(/[^a-z0-9\u00C0-\u1EF9]+/g, " ").split(/\s+/).filter((t) => t.length >= 3);
4955
- const matched = tokens.filter((t) => lowerCorpus.includes(t)).length;
4956
- if (tokens.length === 0 || matched / tokens.length >= 0.5) {
4957
- satisfiedAttributes.push(reqItem);
4958
- } else {
4959
- missingGaps.push(reqItem);
5651
+ if (llm) {
5652
+ try {
5653
+ const prompt = [
5654
+ `Evaluate which of the required attributes/sections are covered by the collected Citation Receipts for "${contract.objective}".`,
5655
+ `Required Items: ${JSON.stringify(targetCheckList)}`,
5656
+ `Collected Citation Receipts:
5657
+ ${receiptsText}`,
5658
+ `Return ONLY a JSON object: {"satisfied": ["item1"], "missing": ["item2"]}`
5659
+ ].join("\n");
5660
+ const raw = await llm(prompt, {
5661
+ system: 'Output strictly valid JSON object with "satisfied" and "missing" string arrays.',
5662
+ temperature: 0.1,
5663
+ jsonMode: true
5664
+ });
5665
+ const match = raw.match(/\{[\s\S]*\}/);
5666
+ if (match) {
5667
+ const parsed = JSON.parse(match[0]);
5668
+ if (Array.isArray(parsed.satisfied)) {
5669
+ satisfiedAttributes.push(...parsed.satisfied.map(String));
5670
+ }
5671
+ if (Array.isArray(parsed.missing)) {
5672
+ missingGaps.push(...parsed.missing.map(String));
5673
+ }
5674
+ return { satisfiedAttributes, missingGaps };
5675
+ }
5676
+ } catch {
5677
+ }
5678
+ }
5679
+ const lowerCorpus = ledger.buildFullRawCorpus().toLowerCase();
5680
+ for (const reqItem of targetCheckList) {
5681
+ const tokens = reqItem.toLowerCase().replace(/[^a-z0-9\u00C0-\u1EF9]+/g, " ").split(/\s+/).filter((t) => t.length >= 3);
5682
+ const matched = tokens.filter((t) => lowerCorpus.includes(t)).length;
5683
+ if (tokens.length === 0 || matched / tokens.length >= 0.5) {
5684
+ satisfiedAttributes.push(reqItem);
5685
+ } else {
5686
+ missingGaps.push(reqItem);
5687
+ }
4960
5688
  }
4961
5689
  }
4962
5690
  }
4963
5691
  return { satisfiedAttributes, missingGaps };
4964
5692
  }
5693
+ /**
5694
+ * Verifies claims using Decision Model `choice` (`supported | refuted | not_enough_evidence`)
5695
+ * or Generative LLM NLI (`ClaimVerifier.verifyClaims`) when `shouldVerifyClaims` is enabled (e.g., `deep-research`).
5696
+ */
5697
+ async verifyClaimsWithDecisionOrLlm(claims, sourceCorpus, options) {
5698
+ if (claims.length === 0) {
5699
+ return this.claimVerifier.verifyClaimsDeterministic([], sourceCorpus);
5700
+ }
5701
+ if (options.decision) {
5702
+ try {
5703
+ const detBaseline = this.claimVerifier.verifyClaimsDeterministic(claims, sourceCorpus);
5704
+ const res = await options.decision({
5705
+ context: `Verified Evidence Corpus:
5706
+ ${sourceCorpus.slice(0, 6e3)}`,
5707
+ questions: claims.map((claim, idx) => ({
5708
+ id: `claim_${idx}`,
5709
+ type: "choice",
5710
+ criteria: `Evaluate whether the following claim is strictly supported, directly refuted, or has not_enough_evidence in the Verified Evidence Corpus: "${claim}"`,
5711
+ options: ["supported", "refuted", "not_enough_evidence"]
5712
+ }))
5713
+ });
5714
+ const verifiedClaims = claims.map((claim, idx) => {
5715
+ const ans = res.answers[`claim_${idx}`];
5716
+ const verdict = ans?.type === "choice" && ["supported", "refuted", "not_enough_evidence"].includes(ans.choice) ? ans.choice : detBaseline.claims[idx]?.isSupported ? "supported" : "not_enough_evidence";
5717
+ const prob = ans?.probabilities?.[verdict] ?? (verdict === "supported" ? 0.85 : 0.4);
5718
+ return {
5719
+ claimText: claim,
5720
+ verdict,
5721
+ isSupported: verdict === "supported",
5722
+ isLlmVerified: true,
5723
+ confidenceScore: Math.round(prob * 100),
5724
+ extractedQuote: detBaseline.claims[idx]?.extractedQuote,
5725
+ explanation: `Evaluated via Decision Model NLI choice (${verdict}).`
5726
+ };
5727
+ });
5728
+ const supportedCount = verifiedClaims.filter((c) => c.verdict === "supported").length;
5729
+ const refutedCount = verifiedClaims.filter((c) => c.verdict === "refuted").length;
5730
+ const supportPct = supportedCount / claims.length * 100;
5731
+ const hallucinationRisk = refutedCount > 0 ? "high" : supportPct >= 75 ? "low" : "medium";
5732
+ return {
5733
+ totalClaimsChecked: claims.length,
5734
+ supportedClaimsCount: supportedCount,
5735
+ refutedClaimsCount: refutedCount,
5736
+ unverifiedClaimsCount: claims.length - supportedCount,
5737
+ hallucinationRisk,
5738
+ isLlmVerified: true,
5739
+ claims: verifiedClaims,
5740
+ reportMd: detBaseline.reportMd
5741
+ };
5742
+ } catch {
5743
+ }
5744
+ }
5745
+ if (options.llm) {
5746
+ return this.claimVerifier.verifyClaims(claims, sourceCorpus, { llm: options.llm });
5747
+ }
5748
+ return this.claimVerifier.verifyClaimsDeterministic(claims, sourceCorpus);
5749
+ }
4965
5750
  /**
4966
5751
  * Stage B: Synthesizes `EvidenceLedger` excerpts into `outputSchema<T>` + `markdownReport`
4967
5752
  * and runs deterministic schema, citation, and claim verification gates.
4968
5753
  */
4969
5754
  async synthesizeAndVerify(params) {
4970
- const { contract, profile, ledger, approvedCount, minSources, missingGaps, roundTraces, provenanceMd, llm } = params;
5755
+ const {
5756
+ contract,
5757
+ mode,
5758
+ profile,
5759
+ ledger,
5760
+ approvedCount,
5761
+ minSources,
5762
+ shouldVerifyClaims,
5763
+ missingGaps,
5764
+ roundTraces,
5765
+ modeClassificationTrace,
5766
+ channelTraces,
5767
+ provenanceMd,
5768
+ llm,
5769
+ decision
5770
+ } = params;
4971
5771
  const synthesisCorpus = ledger.buildSynthesisCorpus(12);
4972
5772
  const items = ledger.getItems();
4973
5773
  const receipts = ledger.getReceipts();
@@ -4984,7 +5784,7 @@ ${receipts.map((r) => `- [${r.id}] ${r.title} (headings: ${r.headings.join(", ")
4984
5784
  const prompt = [
4985
5785
  `You are a Principal Research Synthesizer. Synthesize the verified EvidenceLedger sources below to fulfill the Research Contract.`,
4986
5786
  `Objective: "${contract.objective}"`,
4987
- `Profile: ${profile}`,
5787
+ `Mode: ${mode} | Profile: ${profile}`,
4988
5788
  contract.context?.ageBand ? `Learner Age Band: ${contract.context.ageBand[0]}-${contract.context.ageBand[1]}` : "",
4989
5789
  contract.context?.hardwarePlatform ? `Hardware Platform: ${contract.context.hardwarePlatform}` : "",
4990
5790
  contract.context?.softwareEnv ? `Software/Tools: ${contract.context.softwareEnv}` : "",
@@ -5073,6 +5873,7 @@ Return ONLY a valid JSON object with the exact envelope:`,
5073
5873
  if (synthesizedData === null && !contract.outputSchema) {
5074
5874
  synthesizedData = {
5075
5875
  objective: contract.objective,
5876
+ mode,
5076
5877
  profile,
5077
5878
  sources: receipts,
5078
5879
  codeSnippets: items.flatMap((i) => i.codeBlocks).slice(0, 4),
@@ -5101,7 +5902,10 @@ ${JSON.stringify(synthesizedData || {})}`;
5101
5902
  }
5102
5903
  }
5103
5904
  const claimsToVerify = keyClaims.length > 0 ? keyClaims : items.slice(0, 4).map((i) => i.keyExcerpts[0]).filter((e) => Boolean(e && e.length > 25));
5104
- const claimVerification = claimsToVerify.length > 0 ? this.claimVerifier.verifyClaimsDeterministic(claimsToVerify, ledger.buildFullRawCorpus()) : void 0;
5905
+ const claimVerification = claimsToVerify.length > 0 ? shouldVerifyClaims ? await this.verifyClaimsWithDecisionOrLlm(claimsToVerify, ledger.buildFullRawCorpus(), {
5906
+ decision,
5907
+ llm
5908
+ }) : this.claimVerifier.verifyClaimsDeterministic(claimsToVerify, ledger.buildFullRawCorpus()) : void 0;
5105
5909
  let status = "success";
5106
5910
  if (!isLlmSynthesized && llm) {
5107
5911
  status = "degraded";
@@ -5113,129 +5917,149 @@ ${JSON.stringify(synthesizedData || {})}`;
5113
5917
  return {
5114
5918
  status,
5115
5919
  objective: contract.objective,
5920
+ mode,
5116
5921
  profile,
5117
5922
  roundsExecuted: roundTraces.length,
5118
5923
  data: synthesizedData,
5119
5924
  markdownReport,
5120
- tier1Summary: tier1Summary.slice(0, 1800),
5121
- tier2TechnicalDigest: tier2TechnicalDigest.slice(0, 4e3),
5925
+ tier1Summary,
5926
+ tier2TechnicalDigest,
5122
5927
  ledgerItems: items,
5123
5928
  receipts,
5124
5929
  validCitationIds,
5125
5930
  invalidCitationIds,
5126
- missingGaps: Array.from(new Set(missingGaps)),
5931
+ missingGaps,
5127
5932
  roundTraces,
5933
+ modeClassificationTrace,
5934
+ channelTraces,
5128
5935
  claimVerification,
5129
5936
  provenanceMd
5130
5937
  };
5131
5938
  }
5132
5939
  buildDeterministicMarkdownReport(objective, profile, items, requiredSections) {
5940
+ const sections = requiredSections && requiredSections.length > 0 ? requiredSections : [
5941
+ "Executive Summary",
5942
+ "Verified Technical & Domain Findings",
5943
+ "Code Exemplars & Specifications",
5944
+ "Verified Source Ledger"
5945
+ ];
5133
5946
  const lines = [
5134
- `# \u{1F52C} Autonomous Research Dossier: ${objective}`,
5135
- `> **Profile:** \`${profile.toUpperCase()}\` | **Verified Ledger Sources:** \`${items.length}\``
5947
+ `# Research Synthesis Report: ${objective}`,
5948
+ `> **Profile:** \`${profile}\` | **Verified Sources:** \`${items.length}\``,
5949
+ ""
5136
5950
  ];
5137
- if (requiredSections && requiredSections.length > 0) {
5138
- for (const section of requiredSections) {
5139
- lines.push(`
5140
- ## ${section}`);
5141
- for (const item of items.slice(0, 4)) {
5142
- if (item.keyExcerpts[0]) {
5143
- lines.push(`- **[${item.id}] ${item.title}**: ${item.keyExcerpts[0]}`);
5951
+ for (const sec of sections) {
5952
+ lines.push(`## ${sec}`);
5953
+ const lower = sec.toLowerCase();
5954
+ if (lower.includes("code") || lower.includes("spec") || lower.includes("table") || lower.includes("exemplar")) {
5955
+ const blocks = items.flatMap((i) => i.codeBlocks.map((cb) => ({ id: i.id, cb }))).slice(0, 3);
5956
+ const tables = items.flatMap((i) => i.tables.map((tb) => ({ id: i.id, tb }))).slice(0, 2);
5957
+ if (blocks.length === 0 && tables.length === 0) {
5958
+ lines.push(
5959
+ ...items.slice(0, 3).map((i) => `- **[${i.id}] ${i.title}**: ${i.keyExcerpts[0] || ""}`)
5960
+ );
5961
+ } else {
5962
+ for (const b of blocks) {
5963
+ lines.push(`From **[${b.id}]**:
5964
+ \`\`\`${b.cb.language || "text"}
5965
+ ${b.cb.code.slice(0, 500)}
5966
+ \`\`\``);
5967
+ }
5968
+ for (const t of tables) {
5969
+ lines.push(`From **[${t.id}]**:
5970
+
5971
+ ${t.tb}`);
5144
5972
  }
5145
5973
  }
5974
+ } else if (lower.includes("source") || lower.includes("reference") || lower.includes("ledger")) {
5975
+ for (const item of items) {
5976
+ lines.push(`- **[${item.id}]** [${item.title}](${item.url}) (${item.sourceType}, Score: ${item.relevanceScore}/10)`);
5977
+ }
5978
+ } else {
5979
+ for (const item of items.slice(0, 6)) {
5980
+ const excerpt = item.keyExcerpts[0] || item.title;
5981
+ lines.push(`- **[${item.id}] ${item.title}**: ${excerpt}`);
5982
+ }
5146
5983
  }
5147
- } else {
5148
- lines.push(`
5149
- ## 1. Executive Summary & Verified Findings`);
5150
- for (const item of items) {
5151
- lines.push(
5152
- `### [${item.id}] ${item.title} (${item.sourceType.toUpperCase()} \xB7 Score \`${item.relevanceScore}/10\`)`,
5153
- `- **URL:** ${item.url}`,
5154
- ...item.keyExcerpts.slice(0, 3).map((ex) => `- ${ex}`)
5155
- );
5156
- }
5984
+ lines.push("");
5157
5985
  }
5158
- const allCode = items.flatMap((i) => i.codeBlocks.map((cb) => ({ id: i.id, ...cb }))).slice(0, 4);
5159
- if (allCode.length > 0) {
5160
- lines.push(
5161
- `
5162
- ## Extracted Code Examples`,
5163
- ...allCode.map((c) => `From **[${c.id}]**:
5164
- \`\`\`${c.language || "text"}
5165
- ${c.code}
5166
- \`\`\``)
5167
- );
5168
- }
5169
- const allTables = items.flatMap((i) => i.tables.map((t) => ({ id: i.id, table: t }))).slice(0, 4);
5170
- if (allTables.length > 0) {
5171
- lines.push(
5172
- `
5173
- ## Extracted Specification Tables`,
5174
- ...allTables.map((t) => `From **[${t.id}]**:
5175
-
5176
- ${t.table}`)
5177
- );
5178
- }
5179
- lines.push(
5180
- `
5181
- ## Evidence Ledger Citations`,
5182
- ...items.map((i) => `- **[${i.id}]** [${i.title}](${i.url}) \u2014 *${i.sourceType}, score ${i.relevanceScore}/10*`)
5183
- );
5184
5986
  return lines.join("\n");
5185
5987
  }
5186
5988
  };
5989
+ var ResearchAgentToolInputSchema = zod.z.object({
5990
+ objective: zod.z.string().min(3).describe("Core research question or objective to investigate"),
5991
+ mode: zod.z.enum(["auto", "search", "research", "deep-research"]).optional().describe("Execution mode: auto, search (<=8s), research (<=90s, 2 channels), or deep-research (<=300s, 5 channels)"),
5992
+ preferredChannels: zod.z.array(zod.z.enum(["web_docs", "academic", "social_pulse", "stem_oer", "video_media"])).optional().describe("Optional preferred source channels to prioritize"),
5993
+ profile: zod.z.enum([
5994
+ "auto",
5995
+ "fast_grounded",
5996
+ "deep_autonomous",
5997
+ "technical",
5998
+ "academic",
5999
+ "social_pulse",
6000
+ "curriculum_oer",
6001
+ "general"
6002
+ ]).optional().describe("Legacy domain profile"),
6003
+ requiredAttributes: zod.z.array(zod.z.string()).optional().describe("Specific technical attributes, specs, or sub-questions that must be covered"),
6004
+ requiredSections: zod.z.array(zod.z.string()).optional().describe("Required Markdown sections in the synthesized report"),
6005
+ requireCodeExamples: zod.z.boolean().optional().describe("Whether verified code snippets are required"),
6006
+ requireTables: zod.z.boolean().optional().describe("Whether markdown specification/pinout tables are required"),
6007
+ verifyClaims: zod.z.boolean().optional().describe("Whether to run semantic NLI claim verification"),
6008
+ minSources: zod.z.number().int().min(1).max(10).optional().describe("Minimum number of verified sources (default: 2)"),
6009
+ maxChannels: zod.z.number().int().min(1).max(5).optional().describe("Maximum number of ok channels to harvest"),
6010
+ maxRounds: zod.z.number().int().min(1).max(4).optional().describe("Maximum Plan-Harvest-Evaluate rounds"),
6011
+ recencyDays: zod.z.number().int().min(1).max(365).optional().describe("Recency window in days for social pulse signals"),
6012
+ hardwarePlatform: zod.z.string().optional().describe("Optional hardware context (e.g., Arduino Uno, ESP32)"),
6013
+ softwareEnv: zod.z.string().optional().describe("Optional software/IDE context (e.g., mBlock 5, Roblox Studio, Swift 6)")
6014
+ });
5187
6015
  async function runResearchSubAgent(contract, config = {}) {
5188
6016
  const agent = new ResearchSubAgent(config);
5189
- return agent.run(contract, { llm: config.llm });
6017
+ return agent.run(contract);
5190
6018
  }
5191
- var ResearchAgentToolInputSchema = zod.z.object({
5192
- objective: zod.z.string().min(3).describe("The specific research question, topic, or technical requirement to investigate."),
5193
- profile: zod.z.enum(["auto", "fast_grounded", "deep_autonomous", "technical", "academic", "social_pulse", "curriculum_oer", "general"]).optional().default("auto").describe("Execution profile selecting the appropriate multi-source harvesters and loop budget."),
5194
- requiredSections: zod.z.array(zod.z.string()).optional().describe("Optional list of required Markdown sections in the synthesized report."),
5195
- requiredAttributes: zod.z.array(zod.z.string()).optional().describe("Optional list of specific technical attributes, specs, or sub-questions that must be verified."),
5196
- requireCodeExamples: zod.z.boolean().optional().describe("Set true if verified code examples are mandatory."),
5197
- requireTables: zod.z.boolean().optional().describe("Set true if pinout or specification tables are mandatory."),
5198
- recencyDays: zod.z.number().int().min(1).max(365).optional().describe("Recency window in days for social/community pulse."),
5199
- maxRounds: zod.z.number().int().min(1).max(4).optional().describe("Maximum Plan-Harvest-Evaluate rounds (1-4).")
5200
- });
5201
6019
  function createResearchAgentTool(config = {}) {
5202
- const subAgent = new ResearchSubAgent(config);
6020
+ const agent = new ResearchSubAgent(config);
5203
6021
  return {
5204
- name: "research_subagent",
5205
- description: "Autonomous Plan-and-Execute Research Sub-Agent. Plans multi-source queries (Web, Official Docs, Semantic Scholar, OpenAlex, HackerNews/GitHub 30-day Pulse, STEM OER), verifies sources into an immutable EvidenceLedger [RES-xx], checks for coverage gaps, and returns a citation-grounded report.",
6022
+ name: "run_research_subagent",
6023
+ description: "Delegate a research objective to the autonomous Plan-and-Execute Research Sub-Agent (supports mode: auto | search | research | deep-research).",
5206
6024
  parameters: ResearchAgentToolInputSchema,
5207
- inputSchema: ResearchAgentToolInputSchema,
5208
6025
  execute: async (input) => {
5209
- const result = await subAgent.run({
6026
+ const result = await agent.run({
5210
6027
  objective: input.objective,
5211
- profile: input.profile,
6028
+ mode: input.mode ?? "auto",
6029
+ preferredChannels: input.preferredChannels,
6030
+ profile: input.profile ?? "auto",
5212
6031
  requiredSections: input.requiredSections,
5213
6032
  acceptanceCriteria: {
5214
- requiredAttributes: input.requiredAttributes,
6033
+ minSources: input.minSources ?? 2,
5215
6034
  requireCodeExamples: input.requireCodeExamples,
5216
6035
  requireTables: input.requireTables,
5217
- recencyDays: input.recencyDays
6036
+ verifyClaims: input.verifyClaims,
6037
+ recencyDays: input.recencyDays ?? 30,
6038
+ requiredAttributes: input.requiredAttributes
5218
6039
  },
5219
6040
  budget: {
5220
- maxRounds: input.maxRounds
5221
- }
6041
+ maxRounds: input.maxRounds,
6042
+ maxChannels: input.maxChannels
6043
+ },
6044
+ context: input.hardwarePlatform || input.softwareEnv ? {
6045
+ ...config.defaultCourseContext,
6046
+ hardwarePlatform: input.hardwarePlatform ?? config.defaultCourseContext?.hardwarePlatform,
6047
+ softwareEnv: input.softwareEnv ?? config.defaultCourseContext?.softwareEnv
6048
+ } : config.defaultCourseContext
5222
6049
  });
5223
6050
  return {
5224
6051
  status: result.status,
5225
- objective: result.objective,
6052
+ mode: result.mode,
5226
6053
  profile: result.profile,
5227
6054
  roundsExecuted: result.roundsExecuted,
5228
6055
  tier1Summary: result.tier1Summary,
5229
6056
  tier2TechnicalDigest: result.tier2TechnicalDigest,
5230
- citations: result.receipts.map((r) => ({
5231
- id: r.id,
5232
- title: r.title,
5233
- url: r.url,
5234
- sourceType: r.sourceType,
5235
- score: r.relevanceScore
5236
- })),
6057
+ markdownReport: result.markdownReport,
6058
+ citations: result.receipts,
6059
+ validCitationIds: result.validCitationIds,
5237
6060
  missingGaps: result.missingGaps,
5238
- fullResult: result
6061
+ modeClassificationTrace: result.modeClassificationTrace,
6062
+ channelTraces: result.channelTraces
5239
6063
  };
5240
6064
  }
5241
6065
  };
@@ -5497,8 +6321,15 @@ var ResearchKitClient = class {
5497
6321
  orchestrator;
5498
6322
  /** Service 6: Technical Grounding, Hardware/Software Compatibility & Empirical Exemplars */
5499
6323
  grounding;
5500
- /** Service 7: Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent (v1.3.0) */
6324
+ /** Service 7: Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent (v1.4.0) */
5501
6325
  agent;
6326
+ /**
6327
+ * Unified Tri-Mode entrypoint (`'auto' | 'search' | 'research' | 'deep-research'`).
6328
+ */
6329
+ async execute(mode, input) {
6330
+ const contract = typeof input === "string" ? { objective: input, mode } : { ...input, mode };
6331
+ return this.agent.run(contract);
6332
+ }
5502
6333
  };
5503
6334
 
5504
6335
  exports.AcademicPaperSchema = AcademicPaperSchema;
@@ -5526,15 +6357,19 @@ exports.MultiSourceSearchEngine = MultiSourceSearchEngine;
5526
6357
  exports.NasaMediaClient = NasaMediaClient;
5527
6358
  exports.OpenAlexClient = OpenAlexClient;
5528
6359
  exports.OpenverseClient = OpenverseClient;
6360
+ exports.PRIOR_MATRIX = PRIOR_MATRIX;
5529
6361
  exports.PedagogicalSynthesisService = PedagogicalSynthesisService;
5530
6362
  exports.PedagogicalTermExtractor = PedagogicalTermExtractor;
5531
6363
  exports.ProvenanceTracker = ProvenanceTracker;
6364
+ exports.QUESTION_FACETS = QUESTION_FACETS;
6365
+ exports.RESEARCH_MODE_PRESETS = RESEARCH_MODE_PRESETS;
5532
6366
  exports.RESEARCH_PROFILE_PRESETS = RESEARCH_PROFILE_PRESETS;
5533
6367
  exports.ReferencePackBuilder = ReferencePackBuilder;
5534
6368
  exports.ResearchAgentToolInputSchema = ResearchAgentToolInputSchema;
5535
6369
  exports.ResearchConfigSchema = ResearchConfigSchema;
5536
6370
  exports.ResearchKitClient = ResearchKitClient;
5537
6371
  exports.ResearchSubAgent = ResearchSubAgent;
6372
+ exports.SOURCE_CHANNELS = SOURCE_CHANNELS;
5538
6373
  exports.SocialPulseHarvester = SocialPulseHarvester;
5539
6374
  exports.StemResourceResearcher = StemResourceResearcher;
5540
6375
  exports.TechnicalGroundingEngine = TechnicalGroundingEngine;
@@ -5542,22 +6377,30 @@ exports.TechnicalGroundingService = TechnicalGroundingService;
5542
6377
  exports.TerminologyGraphService = TerminologyGraphService;
5543
6378
  exports.WebScraper = WebScraper;
5544
6379
  exports.YouTubeIngestionService = YouTubeIngestionService;
6380
+ exports.classifyChannelStatus = classifyChannelStatus;
6381
+ exports.classifyModeAndPrior = classifyModeAndPrior;
5545
6382
  exports.classifyTechnicalDomain = classifyTechnicalDomain;
5546
6383
  exports.cleanCrossrefAbstract = cleanCrossrefAbstract;
6384
+ exports.computeContractComplexityScore = computeContractComplexityScore;
5547
6385
  exports.createResearchAgentTool = createResearchAgentTool;
6386
+ exports.evaluateAttributeCoverageWithDecision = evaluateAttributeCoverageWithDecision;
5548
6387
  exports.evaluateTechnicalDensity = evaluateTechnicalDensity;
5549
6388
  exports.extractSubstantiveExcerpts = extractSubstantiveExcerpts;
5550
6389
  exports.extractTopSentences = extractTopSentences;
5551
6390
  exports.extractYouTubeVideoId = extractYouTubeVideoId;
5552
6391
  exports.formatTimestamp = formatTimestamp;
6392
+ exports.inferFallbackFacetProbabilities = inferFallbackFacetProbabilities;
5553
6393
  exports.inferPrimaryCodeLanguage = inferPrimaryCodeLanguage;
5554
6394
  exports.isCommercialOrNoise = isCommercialOrNoise;
6395
+ exports.isSemanticRankedHit = isSemanticRankedHit;
5555
6396
  exports.isYouTubeUrl = isYouTubeUrl;
5556
6397
  exports.kahnTopologicalSort = kahnTopologicalSort;
5557
6398
  exports.mapTopicToCS2023 = mapTopicToCS2023;
5558
6399
  exports.normalizeUrlForDedup = normalizeUrlForDedup;
6400
+ exports.rankChannelsByExpectedPrior = rankChannelsByExpectedPrior;
5559
6401
  exports.reconstructOpenAlexAbstract = reconstructOpenAlexAbstract;
5560
6402
  exports.resolveResearchProfile = resolveResearchProfile;
6403
+ exports.runConcurrentRefillScheduler = runConcurrentRefillScheduler;
5561
6404
  exports.runResearchSubAgent = runResearchSubAgent;
5562
6405
  exports.stitchCaptionSegments = stitchCaptionSegments;
5563
6406
  exports.transitiveReduction = transitiveReduction;