@thanh01.pmt/research-kit 1.2.3 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/dist/academic/index.cjs +122 -0
  2. package/dist/academic/index.cjs.map +1 -1
  3. package/dist/academic/index.d.cts +27 -4
  4. package/dist/academic/index.d.ts +27 -4
  5. package/dist/academic/index.js +2 -1
  6. package/dist/agent/index.cjs +3441 -0
  7. package/dist/agent/index.cjs.map +1 -0
  8. package/dist/agent/index.d.cts +10 -0
  9. package/dist/agent/index.d.ts +10 -0
  10. package/dist/agent/index.js +10 -0
  11. package/dist/agent/index.js.map +1 -0
  12. package/dist/{catalogBuilder-B4eiLS_S.d.cts → catalogBuilder-BBCa9jqI.d.cts} +2 -2
  13. package/dist/{catalogBuilder-BNB_gaWP.d.ts → catalogBuilder-D-UiM37y.d.ts} +2 -2
  14. package/dist/chunk-2GBXVPOQ.js +3 -0
  15. package/dist/{chunk-J3VCGH7Z.js.map → chunk-2GBXVPOQ.js.map} +1 -1
  16. package/dist/chunk-2RMBLKP5.js +581 -0
  17. package/dist/chunk-2RMBLKP5.js.map +1 -0
  18. package/dist/{chunk-2XIEWCUE.js → chunk-32B5PVTQ.js} +2 -2
  19. package/dist/{chunk-2XIEWCUE.js.map → chunk-32B5PVTQ.js.map} +1 -1
  20. package/dist/chunk-LDCZ33AC.js +3 -0
  21. package/dist/chunk-LDCZ33AC.js.map +1 -0
  22. package/dist/chunk-NSY6KU4G.js +125 -0
  23. package/dist/chunk-NSY6KU4G.js.map +1 -0
  24. package/dist/{chunk-SAHBBO3U.js → chunk-RYLZYZRF.js} +4 -580
  25. package/dist/chunk-RYLZYZRF.js.map +1 -0
  26. package/dist/{chunk-P6RHBJY2.js → chunk-S3JUCDKD.js} +62 -40
  27. package/dist/chunk-S3JUCDKD.js.map +1 -0
  28. package/dist/chunk-TYQEC24G.js +3 -0
  29. package/dist/chunk-TYQEC24G.js.map +1 -0
  30. package/dist/chunk-WWQ45RQK.js +1114 -0
  31. package/dist/chunk-WWQ45RQK.js.map +1 -0
  32. package/dist/{chunk-YICMTZS5.js → chunk-ZNGU4ZYX.js} +171 -3
  33. package/dist/chunk-ZNGU4ZYX.js.map +1 -0
  34. package/dist/config/index.d.cts +1 -1
  35. package/dist/config/index.d.ts +1 -1
  36. package/dist/evidence/index.d.cts +2 -2
  37. package/dist/evidence/index.d.ts +2 -2
  38. package/dist/evidence/index.js +2 -1
  39. package/dist/harvester/index.cjs +168 -1
  40. package/dist/harvester/index.cjs.map +1 -1
  41. package/dist/harvester/index.d.cts +5 -161
  42. package/dist/harvester/index.d.ts +5 -161
  43. package/dist/harvester/index.js +4 -2
  44. package/dist/index-CN8gei7k.d.ts +518 -0
  45. package/dist/{index-9rDiFuR4.d.ts → index-CxoD81QN.d.cts} +1 -1
  46. package/dist/{index-9rDiFuR4.d.cts → index-CxoD81QN.d.ts} +1 -1
  47. package/dist/index-onQDKDNo.d.cts +518 -0
  48. package/dist/index.cjs +1463 -36
  49. package/dist/index.cjs.map +1 -1
  50. package/dist/index.d.cts +11 -174
  51. package/dist/index.d.ts +11 -174
  52. package/dist/index.js +25 -10
  53. package/dist/index.js.map +1 -1
  54. package/dist/{literatureReview-DOzgm9Q2.d.ts → literatureReview-Bn2iEGRO.d.ts} +1 -1
  55. package/dist/{literatureReview-BwidpYJo.d.cts → literatureReview-Bvlqk4DB.d.cts} +1 -1
  56. package/dist/pipeline/index.cjs +59 -38
  57. package/dist/pipeline/index.cjs.map +1 -1
  58. package/dist/pipeline/index.d.cts +5 -4
  59. package/dist/pipeline/index.d.ts +5 -4
  60. package/dist/pipeline/index.js +3 -2
  61. package/dist/socialPulseHarvester-CN4MwrpY.d.cts +204 -0
  62. package/dist/socialPulseHarvester-IbdT3zD1.d.ts +204 -0
  63. package/dist/{webScraper-CAQjE46m.d.cts → webScraper-BVvNW4yj.d.cts} +1 -1
  64. package/dist/{webScraper-CXIpvyA6.d.ts → webScraper-C9pB5Rgd.d.ts} +1 -1
  65. package/package.json +6 -1
  66. package/dist/chunk-J3VCGH7Z.js +0 -3
  67. package/dist/chunk-P6RHBJY2.js.map +0 -1
  68. package/dist/chunk-SAHBBO3U.js.map +0 -1
  69. package/dist/chunk-YICMTZS5.js.map +0 -1
@@ -0,0 +1,518 @@
1
+ import { z } from 'zod';
2
+ import { a as CourseResearchContext, j as AcademicPaper, R as ResearchApiKeys, L as LlmTextFn, b as CustomSearchAdapter, c as CustomCrawlerAdapter, d as CustomAcademicSearchAdapter, g as CustomSynthesizerAdapter, E as ExtractedConceptNode } from './index-CxoD81QN.cjs';
3
+ import { E as ExtractedCodeBlock, S as ScrapedDocument, T as TechnicalDomain } from './webScraper-BVvNW4yj.cjs';
4
+ import { ClaimSweepReport, ScoredEvidence } from './evidence/index.cjs';
5
+ import { P as ProvenanceRecord, a as ProvenanceSidecar } from './provenanceTracker-ct4s5lJV.cjs';
6
+ import { S as SearchHit } from './catalogBuilder-BBCa9jqI.cjs';
7
+ import { o as SocialPulseItem, Y as YouTubeTranscriptResult, k as StemResearchOptions, l as StemResourceCatalog, p as SocialPulseOptions, q as SocialPulseReport, b as TermExtractionBundle, H as HealthAuditResult } from './socialPulseHarvester-CN4MwrpY.cjs';
8
+ import { T as TaxonomyMappingResult, L as LiteratureReviewReport } from './literatureReview-Bvlqk4DB.cjs';
9
+ import { ResearchPlan, HarvestPipelineOptions, HarvestPipelineResult, TechnicalFactsheet } from './pipeline/index.cjs';
10
+
11
+ type ResearchProfile = 'auto' | 'fast_grounded' | 'deep_autonomous' | 'technical' | 'academic' | 'social_pulse' | 'curriculum_oer' | 'general';
12
+ interface ResearchAcceptanceCriteria {
13
+ /** Minimum number of distinct approved sources in EvidenceLedger (default: 2) */
14
+ minSources?: number;
15
+ /** Minimum relevance score (1-10) for a source to count as approved (default: 6) */
16
+ minRelevanceScore?: number;
17
+ /** Require at least 1 extracted code block across ledger items */
18
+ requireCodeExamples?: boolean;
19
+ /** Require at least 1 extracted markdown specification/pinout table */
20
+ requireTables?: boolean;
21
+ /** Recency window in days for social/emerging tech queries (default: 30) */
22
+ recencyDays?: number;
23
+ /** Specific attributes, fields, or sub-questions that must be covered in the findings */
24
+ requiredAttributes?: string[];
25
+ /** Terms that must not appear in synthesized claims */
26
+ forbiddenTerms?: string[];
27
+ }
28
+ interface ResearchBudget {
29
+ /** Maximum Plan-Harvest-Evaluate rounds (default depends on profile: 2 for fast_grounded, 3 for deep_autonomous) */
30
+ maxRounds?: number;
31
+ /** Maximum search queries executed per round (default: 3) */
32
+ maxQueriesPerRound?: number;
33
+ /** Maximum URLs scraped in full per round (default: 3) */
34
+ maxScrapePerRound?: number;
35
+ /** Overall execution timeout in milliseconds (default: 45000) */
36
+ timeoutMs?: number;
37
+ }
38
+ interface ResearchContract<T = Record<string, unknown>> {
39
+ /** Core research objective or question */
40
+ objective: string;
41
+ /** Execution profile controlling harvesters and loop budget */
42
+ profile?: ResearchProfile;
43
+ /** Optional Zod schema for structured JSON output */
44
+ outputSchema?: z.ZodType<T>;
45
+ /** Optional human-readable JSON schema description to guide LLM synthesis */
46
+ outputSchemaDescription?: string;
47
+ /** Required Markdown heading sections in the synthesized report */
48
+ requiredSections?: string[];
49
+ /** Quality and coverage criteria that the Evaluator Gate checks after each round */
50
+ acceptanceCriteria?: ResearchAcceptanceCriteria;
51
+ /** Execution budget overrides */
52
+ budget?: ResearchBudget;
53
+ /** Optional course/domain context (hardware, software, age band, language) */
54
+ context?: CourseResearchContext;
55
+ }
56
+ interface LedgerItem {
57
+ /** Immutable monotonic citation ID, e.g. "RES-01", "RES-02" */
58
+ id: string;
59
+ sourceType: 'web' | 'academic' | 'social_pulse' | 'stem_oer' | 'youtube';
60
+ title: string;
61
+ url: string;
62
+ authorOrVenue?: string;
63
+ publishedDate?: string;
64
+ relevanceScore: number;
65
+ headings: string[];
66
+ keyExcerpts: string[];
67
+ codeBlocks: ExtractedCodeBlock[];
68
+ tables: string[];
69
+ rawByteSize: number;
70
+ accessedAt: string;
71
+ }
72
+ /**
73
+ * Compact Citation Receipt (<= 150 tokens) returned to the planning/gap-analysis loop
74
+ * so raw scraped documents never bloat the LLM context window.
75
+ */
76
+ interface CitationReceipt {
77
+ id: string;
78
+ sourceType: LedgerItem['sourceType'];
79
+ title: string;
80
+ url: string;
81
+ relevanceScore: number;
82
+ headings: string[];
83
+ codeBlockCount: number;
84
+ tableCount: number;
85
+ briefExcerpt: string;
86
+ }
87
+ type ResearchAgentStatus = 'success' | 'partial' | 'degraded' | 'failed';
88
+ interface ResearchRoundTrace {
89
+ round: number;
90
+ plannedQueries: string[];
91
+ newReceiptsAdded: number;
92
+ satisfiedAttributes: string[];
93
+ missingGaps: string[];
94
+ }
95
+ interface ResearchAgentResult<T = Record<string, unknown>> {
96
+ status: ResearchAgentStatus;
97
+ objective: string;
98
+ profile: ResearchProfile;
99
+ roundsExecuted: number;
100
+ data: T | null;
101
+ markdownReport: string;
102
+ tier1Summary: string;
103
+ tier2TechnicalDigest: string;
104
+ ledgerItems: LedgerItem[];
105
+ receipts: CitationReceipt[];
106
+ validCitationIds: string[];
107
+ invalidCitationIds: string[];
108
+ missingGaps: string[];
109
+ roundTraces: ResearchRoundTrace[];
110
+ claimVerification?: ClaimSweepReport;
111
+ provenanceMd: string;
112
+ }
113
+ interface ProfilePreset {
114
+ maxRounds: number;
115
+ maxQueriesPerRound: number;
116
+ maxScrapePerRound: number;
117
+ timeoutMs: number;
118
+ enableWeb: boolean;
119
+ enableAcademic: boolean;
120
+ enableSocialPulse: boolean;
121
+ enableStemOer: boolean;
122
+ }
123
+ declare const RESEARCH_PROFILE_PRESETS: Record<Exclude<ResearchProfile, 'auto'>, ProfilePreset>;
124
+
125
+ /**
126
+ * Out-of-Band Immutable Evidence Ledger (`[RES-01]` .. `[RES-N]`).
127
+ * Stores full scraped excerpts, code blocks, and specification tables in memory while
128
+ * emitting compact `CitationReceipt` objects (<= 150 tokens) to keep multi-round agent prompts lean.
129
+ */
130
+ declare class EvidenceLedger {
131
+ private items;
132
+ private urlIndex;
133
+ private idIndex;
134
+ private allocateId;
135
+ /**
136
+ * Records or upgrades a ledger entry from a full `ScrapedDocument`.
137
+ */
138
+ addScrapedDocument(doc: ScrapedDocument, relevanceScore: number, extraTakeaways?: string[]): CitationReceipt;
139
+ /**
140
+ * Records a lightweight search hit when full scraping is skipped or pending.
141
+ */
142
+ addSearchHit(hit: SearchHit, relevanceScore?: number): CitationReceipt;
143
+ /**
144
+ * Records a peer-reviewed or preprint paper from Semantic Scholar, OpenAlex, Crossref, or arXiv.
145
+ */
146
+ addAcademicPaper(paper: AcademicPaper): CitationReceipt;
147
+ /**
148
+ * Records a 30-day social/developer pulse signal (HackerNews, GitHub, Reddit).
149
+ */
150
+ addSocialPulseItem(pulse: SocialPulseItem): CitationReceipt;
151
+ /**
152
+ * Records a verified STEM OER simulation/resource (PhET, OpenStax, NASA, CS Unplugged).
153
+ */
154
+ addStemResource(resource: {
155
+ title: string;
156
+ url: string;
157
+ description: string;
158
+ provider: string;
159
+ license?: string;
160
+ }): CitationReceipt;
161
+ /**
162
+ * Projects a full `LedgerItem` into a compact receipt (<= 150 tokens) for Stage A planning & gap analysis.
163
+ */
164
+ toCompactReceipt(item: LedgerItem): CitationReceipt;
165
+ getItems(): LedgerItem[];
166
+ getApprovedItems(minScore?: number): LedgerItem[];
167
+ getReceipts(): CitationReceipt[];
168
+ getById(id: string): LedgerItem | undefined;
169
+ getTotalCodeBlocks(): number;
170
+ getTotalTables(): number;
171
+ /**
172
+ * Formats the top verified items with `[RES-xx]` tags, substantive excerpts, code blocks,
173
+ * and tables for Stage B Contract Synthesis.
174
+ */
175
+ buildSynthesisCorpus(maxItems?: number): string;
176
+ /**
177
+ * Returns concatenated plain text of all ledger items for deterministic/LLM `ClaimVerifier` checks.
178
+ */
179
+ buildFullRawCorpus(): string;
180
+ /**
181
+ * Scans any synthesized report or JSON string for `[RES-xx]` citation markers
182
+ * and verifies every marker against the ledger.
183
+ */
184
+ verifyCitationTags(synthesizedText: string): {
185
+ validCitationIds: string[];
186
+ invalidCitationIds: string[];
187
+ };
188
+ /**
189
+ * Maps ledger items into `ProvenanceRecord[]` for `ProvenanceTracker`.
190
+ */
191
+ toProvenanceRecords(defaultDomain?: string): ProvenanceRecord[];
192
+ }
193
+
194
+ interface ResearchKitClientConfig {
195
+ /**
196
+ * API keys configured in the host application (e.g., Settings UI / DB / Vault).
197
+ */
198
+ apiKeys?: ResearchApiKeys;
199
+ /**
200
+ * Whether to fall back to `process.env.*` if a key is not provided in `apiKeys`.
201
+ * Set to `false` in strict multi-tenant or desktop apps where only app-configured keys are allowed.
202
+ * Defaults to `true`.
203
+ */
204
+ allowEnvFallback?: boolean;
205
+ /**
206
+ * Optional Crawl4AI self-hosted endpoint.
207
+ */
208
+ crawl4aiHost?: string;
209
+ /**
210
+ * Optional LLM text completion callback injected from the host application
211
+ * (e.g., NineRouter / OpenRouter / AI SDK in smart-curriculum).
212
+ */
213
+ llm?: LlmTextFn;
214
+ /**
215
+ * Default course context (age band, hardware/software tools, language) applied across services.
216
+ */
217
+ defaultCourseContext?: CourseResearchContext;
218
+ /**
219
+ * Optional custom adapters.
220
+ */
221
+ customSearchAdapter?: CustomSearchAdapter;
222
+ customCrawlerAdapter?: CustomCrawlerAdapter;
223
+ customAcademicSearchAdapter?: CustomAcademicSearchAdapter;
224
+ customSynthesizerAdapter?: CustomSynthesizerAdapter;
225
+ }
226
+ /**
227
+ * Service 1: Crawl, Search & Multimodal Knowledge Discovery
228
+ */
229
+ declare class KnowledgeDiscoveryService {
230
+ private config;
231
+ private searchEngine;
232
+ private webScraper;
233
+ private youtubeService;
234
+ private stemResearcher;
235
+ private socialPulseHarvester;
236
+ constructor(config: ResearchKitClientConfig);
237
+ search(query: string, limit?: number): Promise<SearchHit[]>;
238
+ scrapeUrl(url: string): Promise<ScrapedDocument>;
239
+ ingestYouTube(urlOrVideoId: string, preferredLanguages?: string[]): Promise<YouTubeTranscriptResult>;
240
+ findStemResources(query: string, options?: StemResearchOptions): Promise<StemResourceCatalog>;
241
+ searchSocialPulse(topic: string, options?: SocialPulseOptions): Promise<SocialPulseReport>;
242
+ }
243
+ /**
244
+ * Service 2: Bilingual Term Extraction & Prerequisite Concept Graph (DAG)
245
+ */
246
+ declare class TerminologyGraphService {
247
+ private config;
248
+ private extractor;
249
+ constructor(config: ResearchKitClientConfig);
250
+ extractConceptsDeterministic(topic: string, docs: Array<{
251
+ resourceId: string;
252
+ doc: ScrapedDocument;
253
+ }> | string, domain?: TechnicalDomain): TermExtractionBundle;
254
+ extractConcepts(topic: string, docs: Array<{
255
+ resourceId: string;
256
+ doc: ScrapedDocument;
257
+ }> | string, options?: {
258
+ domain?: TechnicalDomain;
259
+ context?: CourseResearchContext;
260
+ llm?: LlmTextFn;
261
+ maxTerms?: number;
262
+ }): Promise<TermExtractionBundle>;
263
+ formatConceptDagTsv(concepts: ExtractedConceptNode[]): string;
264
+ }
265
+ /**
266
+ * Service 3: Academic Literature & Curricular Standards Alignment (ACM/IEEE CS2023 + CSTA K-12)
267
+ */
268
+ declare class AcademicStandardsService {
269
+ private config;
270
+ private academicSearch;
271
+ private litSynthesizer;
272
+ constructor(config: ResearchKitClientConfig);
273
+ alignStandards(topic: string, context?: CourseResearchContext): TaxonomyMappingResult;
274
+ searchPapers(query: string, limit?: number): Promise<AcademicPaper[]>;
275
+ synthesizeLiteratureReview(topic: string, papers: AcademicPaper[], context?: CourseResearchContext): LiteratureReviewReport;
276
+ synthesizeLiteratureReviewWithLlm(topic: string, papers: AcademicPaper[], context?: CourseResearchContext, options?: {
277
+ llm?: LlmTextFn;
278
+ }): Promise<LiteratureReviewReport>;
279
+ }
280
+ /**
281
+ * Service 4: Document Health Audit, Evidence Scoring, Claim Verification & Provenance
282
+ */
283
+ declare class EvidenceVerificationService {
284
+ private config;
285
+ private healthAuditor;
286
+ private evidenceScorer;
287
+ private claimVerifier;
288
+ private provenanceTracker;
289
+ constructor(config?: ResearchKitClientConfig);
290
+ auditDocument(doc: ScrapedDocument): HealthAuditResult;
291
+ scoreDocument(doc: ScrapedDocument, domain: TechnicalDomain, topic: string): ScoredEvidence;
292
+ scoreDocumentWithLlm(doc: ScrapedDocument, domain: TechnicalDomain, topic: string, options?: {
293
+ llm?: LlmTextFn;
294
+ context?: CourseResearchContext;
295
+ }): Promise<ScoredEvidence>;
296
+ verifyClaimsDeterministic(claimsToVerify: string[], sourceCorpusText: string): ClaimSweepReport;
297
+ verifyClaims(claimsToVerify: string[], sourceCorpusText: string, options?: {
298
+ llm?: LlmTextFn;
299
+ }): Promise<ClaimSweepReport>;
300
+ buildProvenance(topic: string, records: ProvenanceRecord[]): ProvenanceSidecar;
301
+ }
302
+ /**
303
+ * Service 5: Pedagogical Synthesis & Ground Truth Reference Pack Orchestration
304
+ */
305
+ declare class PedagogicalSynthesisService {
306
+ private config;
307
+ private planner;
308
+ private pipeline;
309
+ constructor(config: ResearchKitClientConfig);
310
+ planCampaign(topic: string, options?: {
311
+ domain?: TechnicalDomain;
312
+ isDeep?: boolean;
313
+ maxRounds?: number;
314
+ context?: CourseResearchContext;
315
+ }): Promise<ResearchPlan>;
316
+ runFullHarvest(topic: string, overrides?: Partial<HarvestPipelineOptions>): Promise<HarvestPipelineResult>;
317
+ }
318
+ /**
319
+ * Service 6: Empirical Factsheet & Hardware/Software Technical Grounding (v1.2.0)
320
+ */
321
+ declare class TechnicalGroundingService {
322
+ private config;
323
+ private engine;
324
+ constructor(config: ResearchKitClientConfig);
325
+ buildFactsheet(topic: string, options?: {
326
+ domain?: TechnicalDomain;
327
+ context?: CourseResearchContext;
328
+ }): Promise<TechnicalFactsheet>;
329
+ }
330
+ /**
331
+ * Unified facade exposing all 7 core services of `@thanh01.pmt/research-kit`
332
+ * configured with host-application API keys and LLM callbacks.
333
+ */
334
+ declare class ResearchKitClient {
335
+ private readonly config;
336
+ /** Service 1: Multi-Engine Web Search, Scraper, YouTube Transcript & 30-Day Social Pulse */
337
+ readonly discovery: KnowledgeDiscoveryService;
338
+ /** Service 2: Bilingual Pedagogical Term Extraction & Prerequisite Concept Graph (DAG) */
339
+ readonly terminology: TerminologyGraphService;
340
+ /** Service 3: Academic Literature Search, BibTeX Citations & CS2023/CSTA K-12 Alignment */
341
+ readonly academic: AcademicStandardsService;
342
+ /** Service 4: Health Audit, Evidence Scoring, Claim Verification & Provenance Tracking */
343
+ readonly verification: EvidenceVerificationService;
344
+ /** Service 5: Campaign Planning, Semantic Synthesis & Canonical Reference Pack Orchestration */
345
+ readonly orchestrator: PedagogicalSynthesisService;
346
+ /** Service 6: Technical Grounding, Hardware/Software Compatibility & Empirical Exemplars */
347
+ readonly grounding: TechnicalGroundingService;
348
+ /** Service 7: Autonomous Contract-Driven Plan-and-Execute Research Sub-Agent (v1.3.0) */
349
+ readonly agent: ResearchSubAgent;
350
+ constructor(config?: ResearchKitClientConfig);
351
+ }
352
+
353
+ /**
354
+ * Resolves `'auto'` profile into a concrete `ResearchProfile` based on objective & context signals.
355
+ */
356
+ declare function resolveResearchProfile(contract: ResearchContract<any>): Exclude<ResearchProfile, 'auto'>;
357
+ /**
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.
362
+ */
363
+ declare class ResearchSubAgent {
364
+ private config;
365
+ private searchEngine;
366
+ private webScraper;
367
+ private academicEngine;
368
+ private openAlexClient;
369
+ private socialPulseHarvester;
370
+ private stemResearcher;
371
+ private healthAuditor;
372
+ private evidenceScorer;
373
+ private claimVerifier;
374
+ private provenanceTracker;
375
+ constructor(config?: ResearchKitClientConfig);
376
+ /**
377
+ * Executes a complete Plan-and-Execute research campaign governed by `contract`.
378
+ */
379
+ run<T = Record<string, unknown>>(contract: ResearchContract<T>, options?: {
380
+ llm?: ResearchKitClientConfig['llm'];
381
+ }): Promise<ResearchAgentResult<T>>;
382
+ /**
383
+ * Plans targeted search queries for Round 1 (initial coverage) or Round > 1 (surgical gap filling).
384
+ */
385
+ private planQueriesForRound;
386
+ /**
387
+ * Executes active harvesters in parallel and stores results in the Out-of-Band `EvidenceLedger`.
388
+ */
389
+ private executeHarvestRound;
390
+ /**
391
+ * Evaluates whether the current `EvidenceLedger` satisfies `acceptanceCriteria`,
392
+ * `requiredAttributes`, and `requiredSections`.
393
+ */
394
+ private evaluateRoundGaps;
395
+ /**
396
+ * Stage B: Synthesizes `EvidenceLedger` excerpts into `outputSchema<T>` + `markdownReport`
397
+ * and runs deterministic schema, citation, and claim verification gates.
398
+ */
399
+ private synthesizeAndVerify;
400
+ private buildDeterministicMarkdownReport;
401
+ }
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
+ declare const ResearchAgentToolInputSchema: z.ZodObject<{
407
+ 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">>;
410
+ requiredAttributes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
411
+ requireCodeExamples: z.ZodOptional<z.ZodBoolean>;
412
+ requireTables: z.ZodOptional<z.ZodBoolean>;
413
+ recencyDays: z.ZodOptional<z.ZodNumber>;
414
+ maxRounds: z.ZodOptional<z.ZodNumber>;
415
+ }, "strip", z.ZodTypeAny, {
416
+ objective: string;
417
+ profile: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general";
418
+ recencyDays?: number | undefined;
419
+ maxRounds?: number | undefined;
420
+ requiredAttributes?: string[] | undefined;
421
+ requireCodeExamples?: boolean | undefined;
422
+ requireTables?: boolean | undefined;
423
+ requiredSections?: string[] | undefined;
424
+ }, {
425
+ objective: string;
426
+ recencyDays?: number | undefined;
427
+ maxRounds?: number | undefined;
428
+ profile?: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general" | undefined;
429
+ requiredAttributes?: string[] | undefined;
430
+ requireCodeExamples?: boolean | undefined;
431
+ requireTables?: boolean | undefined;
432
+ requiredSections?: string[] | undefined;
433
+ }>;
434
+ type ResearchAgentToolInput = z.infer<typeof ResearchAgentToolInputSchema>;
435
+ /**
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.
439
+ */
440
+ declare function createResearchAgentTool(config?: ResearchKitClientConfig): {
441
+ name: "research_subagent";
442
+ description: string;
443
+ parameters: z.ZodObject<{
444
+ 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">>;
447
+ 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
+ requiredSections: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
475
+ requiredAttributes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
476
+ requireCodeExamples: z.ZodOptional<z.ZodBoolean>;
477
+ requireTables: z.ZodOptional<z.ZodBoolean>;
478
+ recencyDays: z.ZodOptional<z.ZodNumber>;
479
+ maxRounds: z.ZodOptional<z.ZodNumber>;
480
+ }, "strip", z.ZodTypeAny, {
481
+ objective: string;
482
+ profile: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general";
483
+ recencyDays?: number | undefined;
484
+ maxRounds?: number | undefined;
485
+ requiredAttributes?: string[] | undefined;
486
+ requireCodeExamples?: boolean | undefined;
487
+ requireTables?: boolean | undefined;
488
+ requiredSections?: string[] | undefined;
489
+ }, {
490
+ objective: string;
491
+ recencyDays?: number | undefined;
492
+ maxRounds?: number | undefined;
493
+ profile?: "academic" | "auto" | "fast_grounded" | "deep_autonomous" | "technical" | "social_pulse" | "curriculum_oer" | "general" | undefined;
494
+ requiredAttributes?: string[] | undefined;
495
+ requireCodeExamples?: boolean | undefined;
496
+ requireTables?: boolean | undefined;
497
+ requiredSections?: string[] | undefined;
498
+ }>;
499
+ execute: (input: ResearchAgentToolInput) => Promise<{
500
+ status: ResearchAgentStatus;
501
+ objective: string;
502
+ profile: ResearchProfile;
503
+ roundsExecuted: number;
504
+ tier1Summary: string;
505
+ 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
+ }[];
513
+ missingGaps: string[];
514
+ fullResult: ResearchAgentResult<Record<string, unknown>>;
515
+ }>;
516
+ };
517
+
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 };