@thanh01.pmt/research-kit 1.0.0 → 1.1.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 (78) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +213 -0
  3. package/dist/academic/index.cjs +332 -127
  4. package/dist/academic/index.cjs.map +1 -1
  5. package/dist/academic/index.d.cts +3 -3
  6. package/dist/academic/index.d.ts +3 -3
  7. package/dist/academic/index.js +2 -2
  8. package/dist/{catalogBuilder-8A-Dg_A-.d.ts → catalogBuilder-CmmQzUnf.d.ts} +11 -3
  9. package/dist/{catalogBuilder-feU79wQQ.d.cts → catalogBuilder-DgXYxL2F.d.cts} +11 -3
  10. package/dist/chunk-2JEVBCIF.js +3 -0
  11. package/dist/{chunk-KGCDYFFD.js.map → chunk-2JEVBCIF.js.map} +1 -1
  12. package/dist/chunk-2XIEWCUE.js +244 -0
  13. package/dist/chunk-2XIEWCUE.js.map +1 -0
  14. package/dist/chunk-AUGVVZTL.js +514 -0
  15. package/dist/chunk-AUGVVZTL.js.map +1 -0
  16. package/dist/chunk-DOXSPRSP.js +559 -0
  17. package/dist/chunk-DOXSPRSP.js.map +1 -0
  18. package/dist/chunk-GKF3NDEX.js +162 -0
  19. package/dist/chunk-GKF3NDEX.js.map +1 -0
  20. package/dist/chunk-J3VCGH7Z.js +3 -0
  21. package/dist/chunk-J3VCGH7Z.js.map +1 -0
  22. package/dist/{chunk-67V2GJGK.js → chunk-J7XKDMGL.js} +7 -5
  23. package/dist/chunk-J7XKDMGL.js.map +1 -0
  24. package/dist/chunk-KAFQVI2R.js +333 -0
  25. package/dist/chunk-KAFQVI2R.js.map +1 -0
  26. package/dist/chunk-XIF5YNI7.js +799 -0
  27. package/dist/chunk-XIF5YNI7.js.map +1 -0
  28. package/dist/config/index.cjs +5 -3
  29. package/dist/config/index.cjs.map +1 -1
  30. package/dist/config/index.d.cts +1 -1
  31. package/dist/config/index.d.ts +1 -1
  32. package/dist/config/index.js +1 -1
  33. package/dist/evidence/index.cjs +337 -21
  34. package/dist/evidence/index.cjs.map +1 -1
  35. package/dist/evidence/index.d.cts +44 -7
  36. package/dist/evidence/index.d.ts +44 -7
  37. package/dist/evidence/index.js +3 -2
  38. package/dist/harvester/index.cjs +805 -64
  39. package/dist/harvester/index.cjs.map +1 -1
  40. package/dist/harvester/index.d.cts +79 -8
  41. package/dist/harvester/index.d.ts +79 -8
  42. package/dist/harvester/index.js +3 -2
  43. package/dist/{index-BU5n1ip_.d.ts → index-t8pahlJ4.d.cts} +104 -15
  44. package/dist/{index-BU5n1ip_.d.cts → index-t8pahlJ4.d.ts} +104 -15
  45. package/dist/index.cjs +2001 -252
  46. package/dist/index.cjs.map +1 -1
  47. package/dist/index.d.cts +156 -8
  48. package/dist/index.d.ts +156 -8
  49. package/dist/index.js +237 -8
  50. package/dist/index.js.map +1 -1
  51. package/dist/literatureReview-BTPFe7eb.d.cts +64 -0
  52. package/dist/literatureReview-hGbfrBmw.d.ts +64 -0
  53. package/dist/pipeline/index.cjs +1570 -241
  54. package/dist/pipeline/index.cjs.map +1 -1
  55. package/dist/pipeline/index.d.cts +49 -9
  56. package/dist/pipeline/index.d.ts +49 -9
  57. package/dist/pipeline/index.js +5 -4
  58. package/dist/webScraper-BhiQ8s9x.d.ts +68 -0
  59. package/dist/webScraper-D9Ldus9p.d.cts +68 -0
  60. package/package.json +8 -9
  61. package/dist/chunk-47L7ZHMY.js +0 -316
  62. package/dist/chunk-47L7ZHMY.js.map +0 -1
  63. package/dist/chunk-63X2HPCI.js +0 -47
  64. package/dist/chunk-63X2HPCI.js.map +0 -1
  65. package/dist/chunk-67V2GJGK.js.map +0 -1
  66. package/dist/chunk-6Q2XCUG7.js +0 -40
  67. package/dist/chunk-6Q2XCUG7.js.map +0 -1
  68. package/dist/chunk-KGCDYFFD.js +0 -3
  69. package/dist/chunk-MHAYD555.js +0 -239
  70. package/dist/chunk-MHAYD555.js.map +0 -1
  71. package/dist/chunk-MPLDSHFM.js +0 -396
  72. package/dist/chunk-MPLDSHFM.js.map +0 -1
  73. package/dist/chunk-QZNLB5X4.js +0 -65
  74. package/dist/chunk-QZNLB5X4.js.map +0 -1
  75. package/dist/literatureReview-C4AgVljZ.d.ts +0 -43
  76. package/dist/literatureReview-Dlods4Aw.d.cts +0 -43
  77. package/dist/webScraper-pKzdXhfI.d.ts +0 -46
  78. package/dist/webScraper-yBcYOHoL.d.cts +0 -46
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Tony Pham
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,213 @@
1
+ # @thanh01.pmt/research-kit
2
+
3
+ > **Autonomous Deep Research, Multimodal Academic Harvester & Pedagogical Evidence Verification Engine**
4
+ > Designed for Curriculum OS, AI Agents, and Intelligent Educational Authoring Platforms.
5
+
6
+ [![npm version](https://img.shields.io/npm/v/@thanh01.pmt/research-kit.svg?style=flat-square)](https://www.npmjs.com/package/@thanh01.pmt/research-kit)
7
+ [![license](https://img.shields.io/npm/l/@thanh01.pmt/research-kit.svg?style=flat-square)](https://github.com/thanh01pmt/learnwell-platform)
8
+ [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
9
+ [![Zero LLM Lock-in](https://img.shields.io/badge/Zero--LLM--Lock--in-Pluggable-green.svg?style=flat-square)](https://github.com/thanh01pmt/learnwell-platform)
10
+
11
+ ---
12
+
13
+ ## 🎯 Overview
14
+
15
+ `@thanh01.pmt/research-kit` is an enterprise-grade research engine engineered to provide **ground truth technical and pedagogical evidence** before generating curricula, lesson plans, or coding projects.
16
+
17
+ It solves the fundamental problems of hallucinations, obsolete technical syntax, and lack of real-world curriculum grounding by orchestrating **multi-engine web search, video transcript extraction, peer-reviewed academic literature discovery, bilingual terminology extraction, and natural language inference (NLI) claim verification**.
18
+
19
+ ### Key Architectural Invariants
20
+ * **Zero LLM Lock-in**: Works 100% offline or with zero-token deterministic fallbacks by default. Accepts any injected LLM completion callback (`llm: LlmTextFn`) from your host app (e.g. OpenAI, Anthropic, Gemini, OpenRouter, NineRouter, local vLLM).
21
+ * **Host Application API Key Injection**: Host apps pass their own user/vault API keys (`tavily`, `exa`, `jina`, `serper`, `semanticScholar`) without forcing keys into local package `.env` files.
22
+ * **Bilingual English & Vietnamese First-Class Support**: Accurately extracts multi-syllable Vietnamese compound technical nouns (*cảm biến siêu âm*, *điều biến độ rộng xung*, *mạch phân áp*) paired with international canonical English terms.
23
+ * **Dual Taxonomy Grounding**: Maps topics simultaneously to **ACM/IEEE CS2023** knowledge areas and **CSTA K-12 Computer Science** strands.
24
+
25
+ ---
26
+
27
+ ## 📦 The 5 Core Services
28
+
29
+ `@thanh01.pmt/research-kit` exposes a unified facade (`ResearchKitClient`) or standalone service classes:
30
+
31
+ ```
32
+ ┌───────────────────────────┐
33
+ │ ResearchKitClient │
34
+ └─────────────┬─────────────┘
35
+ │
36
+ ┌───────────────────┬───────────────┼───────────────┬───────────────────┐
37
+ ▼ ▼ ▼ ▼ ▼
38
+ ┌───────────────┐ ┌───────────┐ ┌───────────────┐ ┌───────────┐ ┌───────────────────────┐
39
+ │ Service 1 │ │ Service 2 │ │ Service 3 │ │ Service 4 │ │ Service 5 │
40
+ │ Discovery & │ │ Term & │ │ Academic & │ │ Evidence │ │ Pedagogical Synthesis │
41
+ │ Multimodal │ │ DAG Graph │ │ Curricular │ │ & NLI │ │ & Reference Pack │
42
+ │ Harvest │ │ Extraction│ │ Standards │ │ Auditor │ │ Orchestrator │
43
+ └───────────────┘ └───────────┘ └───────────────┘ └───────────┘ └───────────────────────┘
44
+ ```
45
+
46
+ ### 1. `KnowledgeDiscoveryService` (Discovery & Multimodal Ingestion)
47
+ * **Multi-Engine Search**: Auto-routes queries across Tavily, Exa, Serper, SearXNG, DuckDuckGo, and custom adapters.
48
+ * **High-Fidelity Scraper**: Jina Reader API / Crawl4AI / Direct Fetch extracting clean Markdown, formatted code snippets with correct language tags (`lua`, `cpp`, `python`, `swift`), and tabular structures.
49
+ * **YouTube Transcript Ingestion**: Parses video transcripts, stitches caption fragments into timestamped paragraphs (every ~30–45s), and filters out sponsor segments and subscribe filler noise.
50
+
51
+ ### 2. `TerminologyGraphService` (2-Tier Hybrid Concept & DAG Extraction)
52
+ * **Tier 1 (Deterministic Candidate Harvester)**: Rapidly mines candidate terms from markdown headings, inline code blocks, bold markers, bilingual parenthetical pairs `Thuật ngữ (English)`, and Vietnamese technical head nouns.
53
+ * **Tier 2 (LLM Semantic Curator & Ontologist)**: Deduplicates synonyms (e.g., subsumes *LDR*, *Quang trở*, *Cảm biến ánh sáng* into `C_PHOTORESISTOR`), assigns Marr cognitive layers (`ULO`/`CIO`/`SIO`) and Bloom taxonomy levels, and constructs genuine pedagogical prerequisite DAG edges (`CONCEPT_DAG.tsv`).
54
+
55
+ ### 3. `AcademicStandardsService` (Academic Literature & Curricular Standards)
56
+ * **Academic Search**: Queries Semantic Scholar, OpenAlex (with automatic inverted index abstract reconstruction), and ArXiv.
57
+ * **Dual Standards Mapping**: Aligns computing topics with IEEE/ACM CS2023 (e.g. `PDC`, `AI`, `AR`, `HCI`, `GIT`, `SPD`, `FPL`) and CSTA K-12 Strands (`CS`, `NI`, `DA`, `AP`, `IC`).
58
+ * **SOTA Comparison Matrix**: Generates literature reviews and dynamic BibTeX citations (`REFERENCES.bib`).
59
+
60
+ ### 4. `EvidenceVerificationService` (Evidence Scoring, Fact-Checking & Provenance)
61
+ * **Health Auditor**: Rejects HTTP error pages, Cloudflare CAPTCHAs, paywalls, and low-substance spam.
62
+ * **Structural & Pedagogical Scoring**: Evaluates format richness, code presence, and noise factors (with optional LLM pedagogical scoring).
63
+ * **Semantic Claim Verifier (Natural Language Inference)**: Evaluates whether claims are strictly `supported`, directly `refuted`, or have `not_enough_evidence` against source text, detecting negation and contradictions.
64
+ * **Provenance Audit Trail**: Emits immutable `PROVENANCE.md` and `PROVENANCE.json` tracking source URLs, byte sizes, and access timestamps.
65
+
66
+ ### 5. `PedagogicalSynthesisService` (Master Plan & Reference Pack Orchestration)
67
+ * **Master Campaign Planner**: Generates multi-angle search queries tailored to learner age band, hardware platform, and toolchains.
68
+ * **URL Normalization & Deduplication**: Strips tracking parameters (`utm_*`, `fbclid`, `gclid`, `#hash`) to eliminate redundant crawling.
69
+ * **Canonical Reference Pack**: Bundles all verified evidence into `REFERENCE_PACK.md`, `RESOURCE_CATALOG.md`, `KNOWLEDGE_GRAPH.md`, and `RESOURCE_INDEX.json`.
70
+
71
+ ---
72
+
73
+ ## 🚀 Quick Start
74
+
75
+ ### Installation
76
+
77
+ ```bash
78
+ pnpm add @thanh01.pmt/research-kit
79
+ # or
80
+ npm install @thanh01.pmt/research-kit
81
+ ```
82
+
83
+ ### Basic Usage with Host-Injected Keys & LLM
84
+
85
+ ```typescript
86
+ import { ResearchKitClient } from '@thanh01.pmt/research-kit';
87
+
88
+ // 1. Initialize client with host application settings
89
+ const client = new ResearchKitClient({
90
+ apiKeys: {
91
+ tavily: process.env.TAVILY_API_KEY,
92
+ jina: process.env.JINA_API_KEY,
93
+ exa: process.env.EXA_API_KEY,
94
+ serper: process.env.SERPER_API_KEY,
95
+ semanticScholar: process.env.SEMANTIC_SCHOLAR_KEY,
96
+ },
97
+ // Set to false in strict multi-tenant apps to prevent reading process.env
98
+ allowEnvFallback: false,
99
+
100
+ // Course context anchors search queries and cognitive age bands
101
+ defaultCourseContext: {
102
+ ageBand: [10, 14],
103
+ hardwarePlatform: 'Arduino Uno',
104
+ softwareEnv: 'mBlock 5 & Arduino IDE',
105
+ inScopeTopics: ['Cảm biến ánh sáng LDR', 'Mạch phân áp', 'Đèn LED PWM'],
106
+ },
107
+
108
+ // Pluggable LLM completion callback from your app runtime
109
+ llm: async (prompt, options) => {
110
+ const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
111
+ method: 'POST',
112
+ headers: {
113
+ 'Authorization': `Bearer ${process.env.OPENROUTER_API_KEY}`,
114
+ 'Content-Type': 'application/json',
115
+ },
116
+ body: JSON.stringify({
117
+ model: 'google/gemini-2.0-flash-001',
118
+ temperature: options?.temperature ?? 0.2,
119
+ messages: [
120
+ ...(options?.system ? [{ role: 'system', content: options.system }] : []),
121
+ { role: 'user', content: prompt },
122
+ ],
123
+ }),
124
+ });
125
+ const data = await response.json();
126
+ return data.choices[0].message.content;
127
+ },
128
+ });
129
+
130
+ // 2. Execute Full Autonomous Research & Harvest
131
+ const result = await client.orchestrator.runFullHarvest('Nhà Thông Minh với Arduino', {
132
+ isDeep: true,
133
+ onProgress: (stage, message) => console.log(`[${stage}] ${message}`),
134
+ });
135
+
136
+ console.log('Distilled Concepts:', result.concepts.length);
137
+ console.log('Concept DAG (TSV):\n', result.catalog.conceptDagTsv);
138
+ console.log('Reference Pack:\n', result.referencePack.referencePackMd);
139
+ ```
140
+
141
+ ---
142
+
143
+ ## 🛠️ Specialized Service Examples
144
+
145
+ ### 1. Bilingual Terminology & Prerequisite DAG Extraction
146
+
147
+ ```typescript
148
+ // Deterministic Tier 1 + LLM Tier 2 Semantic Curation
149
+ const termBundle = await client.terminology.extractConcepts(
150
+ 'Cảm biến ánh sáng LDR với Arduino',
151
+ scrapedMarkdownText
152
+ );
153
+
154
+ for (const c of termBundle.concepts) {
155
+ console.log(`[${c.id}] ${c.termVi} (${c.termEn})`);
156
+ console.log(` Marr Layer: ${c.marrLayer} | Bloom: ${c.bloomLevel}`);
157
+ console.log(` Prerequisites: [${c.prerequisites.join(', ')}]`);
158
+ }
159
+ ```
160
+
161
+ ### 2. Semantic Claim Verification (NLI Fact-Checking)
162
+
163
+ ```typescript
164
+ const claims = [
165
+ 'Cảm biến ánh sáng LDR thay đổi điện trở khi cường độ ánh sáng thay đổi.',
166
+ 'Cảm biến LDR tạo ra tín hiệu số truyền thẳng qua Bluetooth mà không cần điện áp phân áp.',
167
+ ];
168
+
169
+ const report = await client.verification.verifyClaims(claims, referenceDocumentMarkdown);
170
+
171
+ for (const c of report.claims) {
172
+ console.log(`Claim: "${c.claimText}"`);
173
+ console.log(`Verdict: ${c.verdict.toUpperCase()} (${c.confidenceScore}%)`);
174
+ console.log(`Evidence Quote: "${c.extractedQuote}"`);
175
+ console.log(`Explanation: ${c.explanation}`);
176
+ }
177
+ ```
178
+
179
+ ### 3. YouTube Transcript Ingestion
180
+
181
+ ```typescript
182
+ const ytResult = await client.discovery.ingestYouTube(
183
+ 'https://www.youtube.com/watch?v=VIDEO_ID',
184
+ ['vi', 'en']
185
+ );
186
+
187
+ console.log('Video Title:', ytResult.title);
188
+ console.log('Clean Transcript Paragraphs:\n', ytResult.stitchedMarkdown);
189
+ ```
190
+
191
+ ---
192
+
193
+ ## 🧪 Testing & Verification
194
+
195
+ Run the comprehensive unit test suite:
196
+
197
+ ```bash
198
+ pnpm test
199
+ ```
200
+
201
+ Typecheck and build package distributions:
202
+
203
+ ```bash
204
+ pnpm typecheck
205
+ pnpm build
206
+ ```
207
+
208
+ ---
209
+
210
+ ## 📄 License
211
+
212
+ MIT © [Thanh Pham](https://github.com/thanh01pmt)
213
+ Part of the **LearnWell Platform** & **Curriculum OS** initiative.