@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
@@ -8,16 +8,117 @@ import { o as SocialPulseItem, Y as YouTubeTranscriptResult, k as StemResearchOp
8
8
  import { T as TaxonomyMappingResult, L as LiteratureReviewReport } from './literatureReview-Bn2iEGRO.js';
9
9
  import { ResearchPlan, HarvestPipelineOptions, HarvestPipelineResult, TechnicalFactsheet } from './pipeline/index.js';
10
10
 
11
+ /**
12
+ * Primary execution mode (ADR-0019):
13
+ * - `'auto'`: Evaluated via Decision Model (System One) English rubric + deterministic script into `'search' | 'research' | 'deep-research'`.
14
+ * - `'search'`: Fast retrieval (<= 8s, 0 Generative LLM calls, returns verified EvidenceLedger items).
15
+ * - `'research'`: Standard multi-channel synthesis (<= 90s, up to 2 `'ok'` channels via Concurrent Refill Scheduler, 1 pass).
16
+ * - `'deep-research'`: Exhaustive multi-round synthesis (<= 300s, up to 5 `'ok'` channels, up to 3 gap-filling rounds + claim verification).
17
+ */
18
+ type ResearchMode = 'auto' | 'search' | 'research' | 'deep-research';
19
+ /**
20
+ * Five independent knowledge modalities scheduled by `PriorRouter` & `ConcurrentRefillScheduler`.
21
+ */
22
+ type SourceChannel = 'web_docs' | 'academic' | 'social_pulse' | 'stem_oer' | 'video_media';
23
+ /**
24
+ * Post-harvest channel status used by `ConcurrentRefillScheduler` to decide whether a channel counts
25
+ * toward `maxChannels` (`'ok'`) or triggers an immediate refill from the queue (`'weak' | 'empty' | 'error'`).
26
+ */
27
+ type ChannelStatus = 'ok' | 'weak' | 'empty' | 'error';
28
+ /**
29
+ * Seven English question facets evaluated by the Decision Model (`choice` probabilities).
30
+ */
31
+ type QuestionFacet = 'official_spec' | 'how_to_example' | 'pitfalls' | 'pedagogy_theory' | 'standards_policy' | 'emerging_trend' | 'learning_resources';
11
32
  type ResearchProfile = 'auto' | 'fast_grounded' | 'deep_autonomous' | 'technical' | 'academic' | 'social_pulse' | 'curriculum_oer' | 'general';
33
+ interface ResearchScoreQuestion {
34
+ id: string;
35
+ type: 'score';
36
+ criteria: string;
37
+ context?: string;
38
+ }
39
+ interface ResearchChoiceQuestion {
40
+ id: string;
41
+ type: 'choice';
42
+ criteria: string;
43
+ options: string[];
44
+ context?: string;
45
+ }
46
+ interface ResearchNoulQuestion {
47
+ id: string;
48
+ type: 'noul';
49
+ criteria: string;
50
+ context?: string;
51
+ }
52
+ type ResearchDecisionQuestion = ResearchScoreQuestion | ResearchChoiceQuestion | ResearchNoulQuestion;
53
+ interface ResearchScoreAnswer {
54
+ id: string;
55
+ type: 'score';
56
+ score: number;
57
+ probabilities?: Record<string, number>;
58
+ }
59
+ interface ResearchChoiceAnswer {
60
+ id: string;
61
+ type: 'choice';
62
+ choice: string;
63
+ probabilities?: Record<string, number>;
64
+ }
65
+ interface ResearchNoulAnswer {
66
+ id: string;
67
+ type: 'noul';
68
+ probability: number;
69
+ }
70
+ type ResearchDecisionAnswer = ResearchScoreAnswer | ResearchChoiceAnswer | ResearchNoulAnswer;
71
+ interface ResearchDecisionRequest {
72
+ context?: string;
73
+ questions: ResearchDecisionQuestion[];
74
+ }
75
+ interface ResearchDecisionResult {
76
+ answers: Record<string, ResearchDecisionAnswer>;
77
+ }
78
+ /**
79
+ * Host-injected Decision Model adapter (e.g., `OpenRouterDecisionClient` in `smart-curriculum`).
80
+ */
81
+ type ResearchDecisionFn = (request: ResearchDecisionRequest) => Promise<ResearchDecisionResult>;
82
+ interface ModeClassificationTrace {
83
+ requestedMode: ResearchMode;
84
+ resolvedMode: Exclude<ResearchMode, 'auto'>;
85
+ decisionEvaluated: boolean;
86
+ hardEscalated: boolean;
87
+ rubricBreakdown: {
88
+ readingDepth: number;
89
+ sourceDiversity: number;
90
+ decomposition: number;
91
+ verificationStakes: number;
92
+ contractScore: number;
93
+ totalScore: number;
94
+ };
95
+ facetProbabilities: Record<QuestionFacet, number>;
96
+ channelPriors: Array<{
97
+ channel: SourceChannel;
98
+ score: number;
99
+ }>;
100
+ }
101
+ interface ChannelExecutionTrace {
102
+ channel: SourceChannel;
103
+ status: ChannelStatus;
104
+ priorScore: number;
105
+ itemsAdded: number;
106
+ durationMs: number;
107
+ errorMessage?: string;
108
+ }
12
109
  interface ResearchAcceptanceCriteria {
13
110
  /** Minimum number of distinct approved sources in EvidenceLedger (default: 2) */
14
111
  minSources?: number;
112
+ /** Minimum number of peer-reviewed academic papers required */
113
+ minPeerReviewedSources?: number;
15
114
  /** Minimum relevance score (1-10) for a source to count as approved (default: 6) */
16
115
  minRelevanceScore?: number;
17
116
  /** Require at least 1 extracted code block across ledger items */
18
117
  requireCodeExamples?: boolean;
19
118
  /** Require at least 1 extracted markdown specification/pinout table */
20
119
  requireTables?: boolean;
120
+ /** Whether to run semantic claim verification (NLI / Decision choice) */
121
+ verifyClaims?: boolean;
21
122
  /** Recency window in days for social/emerging tech queries (default: 30) */
22
123
  recencyDays?: number;
23
124
  /** Specific attributes, fields, or sub-questions that must be covered in the findings */
@@ -26,19 +127,27 @@ interface ResearchAcceptanceCriteria {
26
127
  forbiddenTerms?: string[];
27
128
  }
28
129
  interface ResearchBudget {
29
- /** Maximum Plan-Harvest-Evaluate rounds (default depends on profile: 2 for fast_grounded, 3 for deep_autonomous) */
130
+ /** Maximum Plan-Harvest-Evaluate rounds (0 for search, 1 for research, 3 for deep-research) */
30
131
  maxRounds?: number;
132
+ /** Maximum number of 'ok' source channels to harvest per round (1 for search, 2 for research, 5 for deep-research) */
133
+ maxChannels?: number;
134
+ /** Maximum concurrent source channels executing in parallel (default: 2) */
135
+ channelConcurrency?: number;
31
136
  /** Maximum search queries executed per round (default: 3) */
32
137
  maxQueriesPerRound?: number;
33
138
  /** Maximum URLs scraped in full per round (default: 3) */
34
139
  maxScrapePerRound?: number;
35
- /** Overall execution timeout in milliseconds (default: 45000) */
140
+ /** Overall execution timeout in milliseconds (15000 for search, 180000 for research, 600000 for deep-research) */
36
141
  timeoutMs?: number;
37
142
  }
38
143
  interface ResearchContract<T = Record<string, unknown>> {
39
144
  /** Core research objective or question */
40
145
  objective: string;
41
- /** Execution profile controlling harvesters and loop budget */
146
+ /** Tri-mode execution selector ('auto' | 'search' | 'research' | 'deep-research') */
147
+ mode?: ResearchMode;
148
+ /** Optional preferred source channels to prioritize in the Concurrent Refill Scheduler */
149
+ preferredChannels?: SourceChannel[];
150
+ /** Legacy/domain execution profile controlling harvesters and loop budget */
42
151
  profile?: ResearchProfile;
43
152
  /** Optional Zod schema for structured JSON output */
44
153
  outputSchema?: z.ZodType<T>;
@@ -52,6 +161,8 @@ interface ResearchContract<T = Record<string, unknown>> {
52
161
  budget?: ResearchBudget;
53
162
  /** Optional course/domain context (hardware, software, age band, language) */
54
163
  context?: CourseResearchContext;
164
+ /** Optional AbortSignal from caller */
165
+ signal?: AbortSignal;
55
166
  }
56
167
  interface LedgerItem {
57
168
  /** Immutable monotonic citation ID, e.g. "RES-01", "RES-02" */
@@ -91,10 +202,12 @@ interface ResearchRoundTrace {
91
202
  newReceiptsAdded: number;
92
203
  satisfiedAttributes: string[];
93
204
  missingGaps: string[];
205
+ channelTraces?: ChannelExecutionTrace[];
94
206
  }
95
207
  interface ResearchAgentResult<T = Record<string, unknown>> {
96
208
  status: ResearchAgentStatus;
97
209
  objective: string;
210
+ mode: Exclude<ResearchMode, 'auto'>;
98
211
  profile: ResearchProfile;
99
212
  roundsExecuted: number;
100
213
  data: T | null;
@@ -107,9 +220,22 @@ interface ResearchAgentResult<T = Record<string, unknown>> {
107
220
  invalidCitationIds: string[];
108
221
  missingGaps: string[];
109
222
  roundTraces: ResearchRoundTrace[];
223
+ modeClassificationTrace?: ModeClassificationTrace;
224
+ channelTraces?: ChannelExecutionTrace[];
110
225
  claimVerification?: ClaimSweepReport;
111
226
  provenanceMd: string;
112
227
  }
228
+ interface ModePreset {
229
+ mode: Exclude<ResearchMode, 'auto'>;
230
+ timeoutMs: number;
231
+ maxChannels: number;
232
+ channelConcurrency: number;
233
+ maxRounds: number;
234
+ maxQueriesPerRound: number;
235
+ maxScrapePerRound: number;
236
+ verifyClaims: boolean;
237
+ }
238
+ declare const RESEARCH_MODE_PRESETS: Record<Exclude<ResearchMode, 'auto'>, ModePreset>;
113
239
  interface ProfilePreset {
114
240
  maxRounds: number;
115
241
  maxQueriesPerRound: number;
@@ -191,6 +317,84 @@ declare class EvidenceLedger {
191
317
  toProvenanceRecords(defaultDomain?: string): ProvenanceRecord[];
192
318
  }
193
319
 
320
+ declare const QUESTION_FACETS: QuestionFacet[];
321
+ declare const SOURCE_CHANNELS: SourceChannel[];
322
+ /**
323
+ * Expected channel utility matrix P(channel | facet) in [0, 1].
324
+ * Multiplied by the Decision Model's facet probability distribution to rank the 5 channels.
325
+ */
326
+ declare const PRIOR_MATRIX: Record<QuestionFacet, Record<SourceChannel, number>>;
327
+ /**
328
+ * Computes the deterministic structural complexity score (0..4) from `ResearchContract`.
329
+ */
330
+ declare function computeContractComplexityScore(contract: ResearchContract<any>): number;
331
+ /**
332
+ * Fallback deterministic facet distribution when no Decision Model is configured or reachable.
333
+ */
334
+ declare function inferFallbackFacetProbabilities(contract: ResearchContract<any>): Record<QuestionFacet, number>;
335
+ /**
336
+ * Computes expected prior scores E[Prior(c)] = sum_f P(facet=f) * PriorMatrix[f, c]
337
+ * plus deterministic contract modifiers, and returns channels sorted descending.
338
+ */
339
+ declare function rankChannelsByExpectedPrior(facetProbabilities: Record<QuestionFacet, number>, contract: ResearchContract<any>): Array<{
340
+ channel: SourceChannel;
341
+ score: number;
342
+ }>;
343
+ /**
344
+ * Classifies `mode: 'auto'` into `'search' | 'research' | 'deep-research'` and computes
345
+ * expected channel priors in a single Decision Model call using an English rubric + deterministic script.
346
+ */
347
+ declare function classifyModeAndPrior(contract: ResearchContract<any>, decision?: ResearchDecisionFn): Promise<ModeClassificationTrace>;
348
+ /**
349
+ * Evaluates whether required attributes/sections are covered by the collected Citation Receipts
350
+ * using English `noul` binary probability checks on the Decision Model (System One).
351
+ */
352
+ declare function evaluateAttributeCoverageWithDecision(params: {
353
+ objective: string;
354
+ targetCheckList: string[];
355
+ receiptsText: string;
356
+ decision: ResearchDecisionFn;
357
+ }): Promise<{
358
+ satisfied: string[];
359
+ missing: string[];
360
+ } | null>;
361
+
362
+ /**
363
+ * Deterministic post-harvest channel status evaluator.
364
+ * - `'error'`: Channel threw an unhandled exception or network error.
365
+ * - `'empty'`: Zero valid items survived hard filters (`isCommercialOrNoise`, `HealthAuditor`).
366
+ * - `'weak'`: Only 1 thin snippet (< 450 bytes) survived when full scraping was expected — kept in `EvidenceLedger`,
367
+ * but does NOT count toward `okChannels` quota so the scheduler refills the next channel.
368
+ * - `'ok'`: At least 2 verified items OR at least 1 substantive document/paper/snippet (>= 450 bytes) survived.
369
+ */
370
+ declare function classifyChannelStatus(itemsAdded: number, substantiveBytes: number, error?: unknown): ChannelStatus;
371
+ interface ConcurrentRefillSchedulerParams {
372
+ /** Prior-sorted queue of source channels */
373
+ channelQueue: Array<{
374
+ channel: SourceChannel;
375
+ score: number;
376
+ }>;
377
+ /** Target number of `'ok'` channels before stopping (e.g. 1 for search, 2 for research, 5 for deep-research) */
378
+ maxChannels: number;
379
+ /** Number of channels to execute concurrently (default: 2) */
380
+ concurrency?: number;
381
+ /** Optional stage-level AbortSignal (e.g. 75% Harvest budget deadline) */
382
+ signal?: AbortSignal;
383
+ /** Callback that harvests a single channel and returns its trace */
384
+ executeChannel: (channel: SourceChannel, priorScore: number, channelSignal: AbortSignal) => Promise<ChannelExecutionTrace>;
385
+ }
386
+ interface ConcurrentRefillSchedulerResult {
387
+ traces: ChannelExecutionTrace[];
388
+ okChannels: number;
389
+ }
390
+ /**
391
+ * Executes source channels with bounded concurrency (`concurrency = 2`) and automatic refill:
392
+ * - Maintains active in-flight bound: `inFlight <= Math.min(concurrency, maxChannels - okChannels)`.
393
+ * - If a channel returns `'error'`, `'empty'`, or `'weak'`, immediately refills from the Prior-ordered queue.
394
+ * - As soon as `okChannels >= maxChannels` (or `signal` aborts), cancels any remaining in-flight channels.
395
+ */
396
+ declare function runConcurrentRefillScheduler(params: ConcurrentRefillSchedulerParams): Promise<ConcurrentRefillSchedulerResult>;
397
+
194
398
  interface ResearchKitClientConfig {
195
399
  /**
196
400
  * API keys configured in the host application (e.g., Settings UI / DB / Vault).
@@ -211,6 +415,12 @@ interface ResearchKitClientConfig {
211
415
  * (e.g., NineRouter / OpenRouter / AI SDK in smart-curriculum).
212
416
  */
213
417
  llm?: LlmTextFn;
418
+ /**
419
+ * Optional Decision Model callback (System One — ADR-0001 / ADR-0016 / ADR-0019)
420
+ * injected from the host application for English rubric mode classification,
421
+ * expected channel prior routing, and `noul` attribute coverage checks.
422
+ */
423
+ decision?: ResearchDecisionFn;
214
424
  /**
215
425
  * Default course context (age band, hardware/software tools, language) applied across services.
216
426
  */
@@ -345,9 +555,13 @@ declare class ResearchKitClient {
345
555
  readonly orchestrator: PedagogicalSynthesisService;
346
556
  /** Service 6: Technical Grounding, Hardware/Software Compatibility & Empirical Exemplars */
347
557
  readonly grounding: TechnicalGroundingService;
348
- /** Service 7: Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent (v1.3.0) */
558
+ /** Service 7: Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent (v1.4.0) */
349
559
  readonly agent: ResearchSubAgent;
350
560
  constructor(config?: ResearchKitClientConfig);
561
+ /**
562
+ * Unified Tri-Mode entrypoint (`'auto' | 'search' | 'research' | 'deep-research'`).
563
+ */
564
+ execute<T = Record<string, unknown>>(mode: ResearchMode, input: ResearchContract<T> | string): Promise<ResearchAgentResult<T>>;
351
565
  }
352
566
 
353
567
  /**
@@ -355,10 +569,20 @@ declare class ResearchKitClient {
355
569
  */
356
570
  declare function resolveResearchProfile(contract: ResearchContract<any>): Exclude<ResearchProfile, 'auto'>;
357
571
  /**
358
- * Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent.
359
- * Implements a 2-Stage Architecture:
360
- * - Stage A: Multi-Hop Harvester Loop with Out-of-Band `EvidenceLedger` & Compact `CitationReceipt` gap analysis.
361
- * - Stage B: Evidence-Grounded Contract Synthesis & Deterministic Verification Gate.
572
+ * Checks whether a search hit already carries semantic/neural relevance ranking
573
+ * (ADR-0019: Non-Redundant Evidence Gating).
574
+ */
575
+ declare function isSemanticRankedHit(hit: {
576
+ engine?: string;
577
+ score?: number;
578
+ }): boolean;
579
+ /**
580
+ * Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent (v1.4.0).
581
+ * Implements:
582
+ * - Tri-Mode Execution (`'search' | 'research' | 'deep-research'`) + Decision-Model `'auto'` router.
583
+ * - Expected Prior Channel Routing (`Facet Probabilities x PriorMatrix`) + `ConcurrentRefillScheduler`.
584
+ * - Two-Stage Timeout Preemption (75% Stage A Harvest / 25% Stage B Synthesis).
585
+ * - Non-Redundant Evidence Gating for semantic search engines (`exa`, `tavily`, `openalex`, `semantic_scholar`).
362
586
  */
363
587
  declare class ResearchSubAgent {
364
588
  private config;
@@ -368,6 +592,7 @@ declare class ResearchSubAgent {
368
592
  private openAlexClient;
369
593
  private socialPulseHarvester;
370
594
  private stemResearcher;
595
+ private youtubeService;
371
596
  private healthAuditor;
372
597
  private evidenceScorer;
373
598
  private claimVerifier;
@@ -378,20 +603,32 @@ declare class ResearchSubAgent {
378
603
  */
379
604
  run<T = Record<string, unknown>>(contract: ResearchContract<T>, options?: {
380
605
  llm?: ResearchKitClientConfig['llm'];
606
+ decision?: ResearchDecisionFn;
381
607
  }): Promise<ResearchAgentResult<T>>;
382
608
  /**
383
- * Plans targeted search queries for Round 1 (initial coverage) or Round > 1 (surgical gap filling).
609
+ * Builds the Prior-sorted channel queue for a specific round.
384
610
  */
385
- private planQueriesForRound;
611
+ private buildRoundChannelQueue;
386
612
  /**
387
- * Executes active harvesters in parallel and stores results in the Out-of-Band `EvidenceLedger`.
613
+ * Executes a single source channel and classifies its outcome (`'ok' | 'weak' | 'empty' | 'error'`)
614
+ * using Non-Redundant Evidence Gating (ADR-0019).
388
615
  */
389
- private executeHarvestRound;
616
+ private executeSingleChannel;
617
+ /**
618
+ * Plans targeted search queries for Round 1 (initial coverage) or Round > 1 (surgical gap filling).
619
+ */
620
+ private planQueriesForRound;
390
621
  /**
391
622
  * Evaluates whether the current `EvidenceLedger` satisfies `acceptanceCriteria`,
392
623
  * `requiredAttributes`, and `requiredSections`.
624
+ * Prioritizes Decision Model (`noul`) over Generative LLM when available (ADR-0019).
393
625
  */
394
626
  private evaluateRoundGaps;
627
+ /**
628
+ * Verifies claims using Decision Model `choice` (`supported | refuted | not_enough_evidence`)
629
+ * or Generative LLM NLI (`ClaimVerifier.verifyClaims`) when `shouldVerifyClaims` is enabled (e.g., `deep-research`).
630
+ */
631
+ private verifyClaimsWithDecisionOrLlm;
395
632
  /**
396
633
  * Stage B: Synthesizes `EvidenceLedger` excerpts into `outputSchema<T>` + `markdownReport`
397
634
  * and runs deterministic schema, citation, and claim verification gates.
@@ -399,120 +636,129 @@ declare class ResearchSubAgent {
399
636
  private synthesizeAndVerify;
400
637
  private buildDeterministicMarkdownReport;
401
638
  }
402
- /**
403
- * Convenience helper to run the Research Sub-Agent in one call.
404
- */
405
- declare function runResearchSubAgent<T = Record<string, unknown>>(contract: ResearchContract<T>, config?: ResearchKitClientConfig): Promise<ResearchAgentResult<T>>;
406
639
  declare const ResearchAgentToolInputSchema: z.ZodObject<{
407
640
  objective: z.ZodString;
408
- profile: z.ZodDefault<z.ZodOptional<z.ZodEnum<["auto", "fast_grounded", "deep_autonomous", "technical", "academic", "social_pulse", "curriculum_oer", "general"]>>>;
409
- requiredSections: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
641
+ mode: z.ZodOptional<z.ZodEnum<["auto", "search", "research", "deep-research"]>>;
642
+ preferredChannels: z.ZodOptional<z.ZodArray<z.ZodEnum<["web_docs", "academic", "social_pulse", "stem_oer", "video_media"]>, "many">>;
643
+ profile: z.ZodOptional<z.ZodEnum<["auto", "fast_grounded", "deep_autonomous", "technical", "academic", "social_pulse", "curriculum_oer", "general"]>>;
410
644
  requiredAttributes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
645
+ requiredSections: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
411
646
  requireCodeExamples: z.ZodOptional<z.ZodBoolean>;
412
647
  requireTables: z.ZodOptional<z.ZodBoolean>;
413
- recencyDays: z.ZodOptional<z.ZodNumber>;
648
+ verifyClaims: z.ZodOptional<z.ZodBoolean>;
649
+ minSources: z.ZodOptional<z.ZodNumber>;
650
+ maxChannels: z.ZodOptional<z.ZodNumber>;
414
651
  maxRounds: z.ZodOptional<z.ZodNumber>;
652
+ recencyDays: z.ZodOptional<z.ZodNumber>;
653
+ hardwarePlatform: z.ZodOptional<z.ZodString>;
654
+ softwareEnv: z.ZodOptional<z.ZodString>;
415
655
  }, "strip", z.ZodTypeAny, {
416
656
  objective: string;
417
- profile: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general";
657
+ hardwarePlatform?: string | undefined;
658
+ softwareEnv?: string | undefined;
418
659
  recencyDays?: number | undefined;
419
660
  maxRounds?: number | undefined;
420
- requiredAttributes?: string[] | undefined;
421
661
  requireCodeExamples?: boolean | undefined;
422
662
  requireTables?: boolean | undefined;
663
+ verifyClaims?: boolean | undefined;
664
+ requiredAttributes?: string[] | undefined;
665
+ maxChannels?: number | undefined;
666
+ mode?: "search" | "auto" | "research" | "deep-research" | undefined;
667
+ profile?: "academic" | "auto" | "social_pulse" | "fast_grounded" | "deep_autonomous" | "technical" | "curriculum_oer" | "general" | undefined;
668
+ minSources?: number | undefined;
669
+ preferredChannels?: ("academic" | "web_docs" | "social_pulse" | "stem_oer" | "video_media")[] | undefined;
423
670
  requiredSections?: string[] | undefined;
424
671
  }, {
425
672
  objective: string;
673
+ hardwarePlatform?: string | undefined;
674
+ softwareEnv?: string | undefined;
426
675
  recencyDays?: number | undefined;
427
676
  maxRounds?: number | undefined;
428
- profile?: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general" | undefined;
429
- requiredAttributes?: string[] | undefined;
430
677
  requireCodeExamples?: boolean | undefined;
431
678
  requireTables?: boolean | undefined;
679
+ verifyClaims?: boolean | undefined;
680
+ requiredAttributes?: string[] | undefined;
681
+ maxChannels?: number | undefined;
682
+ mode?: "search" | "auto" | "research" | "deep-research" | undefined;
683
+ profile?: "academic" | "auto" | "social_pulse" | "fast_grounded" | "deep_autonomous" | "technical" | "curriculum_oer" | "general" | undefined;
684
+ minSources?: number | undefined;
685
+ preferredChannels?: ("academic" | "web_docs" | "social_pulse" | "stem_oer" | "video_media")[] | undefined;
432
686
  requiredSections?: string[] | undefined;
433
687
  }>;
434
688
  type ResearchAgentToolInput = z.infer<typeof ResearchAgentToolInputSchema>;
435
689
  /**
436
- * Portable Agent-as-Tool descriptor compatible with Vercel AI SDK `tool()`, MCP servers,
437
- * and host assistant registries. Projects compact Tier-1/Tier-2 digests for the parent agent's
438
- * context window while returning the full `ResearchAgentResult` for dossier persistence.
690
+ * Standalone helper to run a `ResearchSubAgent` campaign in one call.
691
+ */
692
+ declare function runResearchSubAgent<T = Record<string, unknown>>(contract: ResearchContract<T>, config?: ResearchKitClientConfig): Promise<ResearchAgentResult<T>>;
693
+ /**
694
+ * Helper factory that wraps `ResearchSubAgent` as an AI SDK / Copilot tool definition.
439
695
  */
440
696
  declare function createResearchAgentTool(config?: ResearchKitClientConfig): {
441
- name: "research_subagent";
697
+ name: string;
442
698
  description: string;
443
699
  parameters: z.ZodObject<{
444
700
  objective: z.ZodString;
445
- profile: z.ZodDefault<z.ZodOptional<z.ZodEnum<["auto", "fast_grounded", "deep_autonomous", "technical", "academic", "social_pulse", "curriculum_oer", "general"]>>>;
446
- requiredSections: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
701
+ mode: z.ZodOptional<z.ZodEnum<["auto", "search", "research", "deep-research"]>>;
702
+ preferredChannels: z.ZodOptional<z.ZodArray<z.ZodEnum<["web_docs", "academic", "social_pulse", "stem_oer", "video_media"]>, "many">>;
703
+ profile: z.ZodOptional<z.ZodEnum<["auto", "fast_grounded", "deep_autonomous", "technical", "academic", "social_pulse", "curriculum_oer", "general"]>>;
447
704
  requiredAttributes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
448
- requireCodeExamples: z.ZodOptional<z.ZodBoolean>;
449
- requireTables: z.ZodOptional<z.ZodBoolean>;
450
- recencyDays: z.ZodOptional<z.ZodNumber>;
451
- maxRounds: z.ZodOptional<z.ZodNumber>;
452
- }, "strip", z.ZodTypeAny, {
453
- objective: string;
454
- profile: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general";
455
- recencyDays?: number | undefined;
456
- maxRounds?: number | undefined;
457
- requiredAttributes?: string[] | undefined;
458
- requireCodeExamples?: boolean | undefined;
459
- requireTables?: boolean | undefined;
460
- requiredSections?: string[] | undefined;
461
- }, {
462
- objective: string;
463
- recencyDays?: number | undefined;
464
- maxRounds?: number | undefined;
465
- profile?: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general" | undefined;
466
- requiredAttributes?: string[] | undefined;
467
- requireCodeExamples?: boolean | undefined;
468
- requireTables?: boolean | undefined;
469
- requiredSections?: string[] | undefined;
470
- }>;
471
- inputSchema: z.ZodObject<{
472
- objective: z.ZodString;
473
- profile: z.ZodDefault<z.ZodOptional<z.ZodEnum<["auto", "fast_grounded", "deep_autonomous", "technical", "academic", "social_pulse", "curriculum_oer", "general"]>>>;
474
705
  requiredSections: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
475
- requiredAttributes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
476
706
  requireCodeExamples: z.ZodOptional<z.ZodBoolean>;
477
707
  requireTables: z.ZodOptional<z.ZodBoolean>;
478
- recencyDays: z.ZodOptional<z.ZodNumber>;
708
+ verifyClaims: z.ZodOptional<z.ZodBoolean>;
709
+ minSources: z.ZodOptional<z.ZodNumber>;
710
+ maxChannels: z.ZodOptional<z.ZodNumber>;
479
711
  maxRounds: z.ZodOptional<z.ZodNumber>;
712
+ recencyDays: z.ZodOptional<z.ZodNumber>;
713
+ hardwarePlatform: z.ZodOptional<z.ZodString>;
714
+ softwareEnv: z.ZodOptional<z.ZodString>;
480
715
  }, "strip", z.ZodTypeAny, {
481
716
  objective: string;
482
- profile: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general";
717
+ hardwarePlatform?: string | undefined;
718
+ softwareEnv?: string | undefined;
483
719
  recencyDays?: number | undefined;
484
720
  maxRounds?: number | undefined;
485
- requiredAttributes?: string[] | undefined;
486
721
  requireCodeExamples?: boolean | undefined;
487
722
  requireTables?: boolean | undefined;
723
+ verifyClaims?: boolean | undefined;
724
+ requiredAttributes?: string[] | undefined;
725
+ maxChannels?: number | undefined;
726
+ mode?: "search" | "auto" | "research" | "deep-research" | undefined;
727
+ profile?: "academic" | "auto" | "social_pulse" | "fast_grounded" | "deep_autonomous" | "technical" | "curriculum_oer" | "general" | undefined;
728
+ minSources?: number | undefined;
729
+ preferredChannels?: ("academic" | "web_docs" | "social_pulse" | "stem_oer" | "video_media")[] | undefined;
488
730
  requiredSections?: string[] | undefined;
489
731
  }, {
490
732
  objective: string;
733
+ hardwarePlatform?: string | undefined;
734
+ softwareEnv?: string | undefined;
491
735
  recencyDays?: number | undefined;
492
736
  maxRounds?: number | undefined;
493
- profile?: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general" | undefined;
494
- requiredAttributes?: string[] | undefined;
495
737
  requireCodeExamples?: boolean | undefined;
496
738
  requireTables?: boolean | undefined;
739
+ verifyClaims?: boolean | undefined;
740
+ requiredAttributes?: string[] | undefined;
741
+ maxChannels?: number | undefined;
742
+ mode?: "search" | "auto" | "research" | "deep-research" | undefined;
743
+ profile?: "academic" | "auto" | "social_pulse" | "fast_grounded" | "deep_autonomous" | "technical" | "curriculum_oer" | "general" | undefined;
744
+ minSources?: number | undefined;
745
+ preferredChannels?: ("academic" | "web_docs" | "social_pulse" | "stem_oer" | "video_media")[] | undefined;
497
746
  requiredSections?: string[] | undefined;
498
747
  }>;
499
748
  execute: (input: ResearchAgentToolInput) => Promise<{
500
749
  status: ResearchAgentStatus;
501
- objective: string;
750
+ mode: "search" | "research" | "deep-research";
502
751
  profile: ResearchProfile;
503
752
  roundsExecuted: number;
504
753
  tier1Summary: string;
505
754
  tier2TechnicalDigest: string;
506
- citations: {
507
- id: string;
508
- title: string;
509
- url: string;
510
- sourceType: "youtube" | "academic" | "web" | "social_pulse" | "stem_oer";
511
- score: number;
512
- }[];
755
+ markdownReport: string;
756
+ citations: CitationReceipt[];
757
+ validCitationIds: string[];
513
758
  missingGaps: string[];
514
- fullResult: ResearchAgentResult<Record<string, unknown>>;
759
+ modeClassificationTrace: ModeClassificationTrace | undefined;
760
+ channelTraces: ChannelExecutionTrace[] | undefined;
515
761
  }>;
516
762
  };
517
763
 
518
- export { AcademicStandardsService as A, type CitationReceipt as C, EvidenceLedger as E, KnowledgeDiscoveryService as K, type LedgerItem as L, type ProfilePreset as P, type ResearchProfile as R, TerminologyGraphService as T, type ResearchAcceptanceCriteria as a, type ResearchBudget as b, type ResearchContract as c, type ResearchAgentStatus as d, type ResearchRoundTrace as e, type ResearchAgentResult as f, RESEARCH_PROFILE_PRESETS as g, ResearchSubAgent as h, runResearchSubAgent as i, ResearchAgentToolInputSchema as j, type ResearchAgentToolInput as k, createResearchAgentTool as l, type ResearchKitClientConfig as m, EvidenceVerificationService as n, PedagogicalSynthesisService as o, TechnicalGroundingService as p, ResearchKitClient as q, resolveResearchProfile as r };
764
+ export { AcademicStandardsService as $, computeContractComplexityScore as A, inferFallbackFacetProbabilities as B, type ChannelStatus as C, rankChannelsByExpectedPrior as D, EvidenceLedger as E, classifyModeAndPrior as F, evaluateAttributeCoverageWithDecision as G, classifyChannelStatus as H, type ConcurrentRefillSchedulerParams as I, type ConcurrentRefillSchedulerResult as J, runConcurrentRefillScheduler as K, type LedgerItem as L, type ModeClassificationTrace as M, resolveResearchProfile as N, isSemanticRankedHit as O, type ProfilePreset as P, type QuestionFacet as Q, type ResearchMode as R, type SourceChannel as S, ResearchSubAgent as T, ResearchAgentToolInputSchema as U, type ResearchAgentToolInput as V, runResearchSubAgent as W, createResearchAgentTool as X, type ResearchKitClientConfig as Y, KnowledgeDiscoveryService as Z, TerminologyGraphService as _, type ResearchProfile as a, EvidenceVerificationService as a0, PedagogicalSynthesisService as a1, TechnicalGroundingService as a2, ResearchKitClient as a3, type ResearchScoreQuestion as b, type ResearchChoiceQuestion as c, type ResearchNoulQuestion as d, type ResearchDecisionQuestion as e, type ResearchScoreAnswer as f, type ResearchChoiceAnswer as g, type ResearchNoulAnswer as h, type ResearchDecisionAnswer as i, type ResearchDecisionRequest as j, type ResearchDecisionResult as k, type ResearchDecisionFn as l, type ChannelExecutionTrace as m, type ResearchAcceptanceCriteria as n, type ResearchBudget as o, type ResearchContract as p, type CitationReceipt as q, type ResearchAgentStatus as r, type ResearchRoundTrace as s, type ResearchAgentResult as t, type ModePreset as u, RESEARCH_MODE_PRESETS as v, RESEARCH_PROFILE_PRESETS as w, QUESTION_FACETS as x, SOURCE_CHANNELS as y, PRIOR_MATRIX as z };