@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.
- package/LICENSE +21 -0
- package/README.md +213 -0
- package/dist/academic/index.cjs +332 -127
- package/dist/academic/index.cjs.map +1 -1
- package/dist/academic/index.d.cts +3 -3
- package/dist/academic/index.d.ts +3 -3
- package/dist/academic/index.js +2 -2
- package/dist/{catalogBuilder-8A-Dg_A-.d.ts → catalogBuilder-CmmQzUnf.d.ts} +11 -3
- package/dist/{catalogBuilder-feU79wQQ.d.cts → catalogBuilder-DgXYxL2F.d.cts} +11 -3
- package/dist/chunk-2JEVBCIF.js +3 -0
- package/dist/{chunk-KGCDYFFD.js.map → chunk-2JEVBCIF.js.map} +1 -1
- package/dist/chunk-2XIEWCUE.js +244 -0
- package/dist/chunk-2XIEWCUE.js.map +1 -0
- package/dist/chunk-AUGVVZTL.js +514 -0
- package/dist/chunk-AUGVVZTL.js.map +1 -0
- package/dist/chunk-DOXSPRSP.js +559 -0
- package/dist/chunk-DOXSPRSP.js.map +1 -0
- package/dist/chunk-GKF3NDEX.js +162 -0
- package/dist/chunk-GKF3NDEX.js.map +1 -0
- package/dist/chunk-J3VCGH7Z.js +3 -0
- package/dist/chunk-J3VCGH7Z.js.map +1 -0
- package/dist/{chunk-67V2GJGK.js → chunk-J7XKDMGL.js} +7 -5
- package/dist/chunk-J7XKDMGL.js.map +1 -0
- package/dist/chunk-KAFQVI2R.js +333 -0
- package/dist/chunk-KAFQVI2R.js.map +1 -0
- package/dist/chunk-XIF5YNI7.js +799 -0
- package/dist/chunk-XIF5YNI7.js.map +1 -0
- package/dist/config/index.cjs +5 -3
- package/dist/config/index.cjs.map +1 -1
- package/dist/config/index.d.cts +1 -1
- package/dist/config/index.d.ts +1 -1
- package/dist/config/index.js +1 -1
- package/dist/evidence/index.cjs +337 -21
- package/dist/evidence/index.cjs.map +1 -1
- package/dist/evidence/index.d.cts +44 -7
- package/dist/evidence/index.d.ts +44 -7
- package/dist/evidence/index.js +3 -2
- package/dist/harvester/index.cjs +805 -64
- package/dist/harvester/index.cjs.map +1 -1
- package/dist/harvester/index.d.cts +79 -8
- package/dist/harvester/index.d.ts +79 -8
- package/dist/harvester/index.js +3 -2
- package/dist/{index-BU5n1ip_.d.ts → index-t8pahlJ4.d.cts} +104 -15
- package/dist/{index-BU5n1ip_.d.cts → index-t8pahlJ4.d.ts} +104 -15
- package/dist/index.cjs +2001 -252
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +156 -8
- package/dist/index.d.ts +156 -8
- package/dist/index.js +237 -8
- package/dist/index.js.map +1 -1
- package/dist/literatureReview-BTPFe7eb.d.cts +64 -0
- package/dist/literatureReview-hGbfrBmw.d.ts +64 -0
- package/dist/pipeline/index.cjs +1570 -241
- package/dist/pipeline/index.cjs.map +1 -1
- package/dist/pipeline/index.d.cts +49 -9
- package/dist/pipeline/index.d.ts +49 -9
- package/dist/pipeline/index.js +5 -4
- package/dist/webScraper-BhiQ8s9x.d.ts +68 -0
- package/dist/webScraper-D9Ldus9p.d.cts +68 -0
- package/package.json +8 -9
- package/dist/chunk-47L7ZHMY.js +0 -316
- package/dist/chunk-47L7ZHMY.js.map +0 -1
- package/dist/chunk-63X2HPCI.js +0 -47
- package/dist/chunk-63X2HPCI.js.map +0 -1
- package/dist/chunk-67V2GJGK.js.map +0 -1
- package/dist/chunk-6Q2XCUG7.js +0 -40
- package/dist/chunk-6Q2XCUG7.js.map +0 -1
- package/dist/chunk-KGCDYFFD.js +0 -3
- package/dist/chunk-MHAYD555.js +0 -239
- package/dist/chunk-MHAYD555.js.map +0 -1
- package/dist/chunk-MPLDSHFM.js +0 -396
- package/dist/chunk-MPLDSHFM.js.map +0 -1
- package/dist/chunk-QZNLB5X4.js +0 -65
- package/dist/chunk-QZNLB5X4.js.map +0 -1
- package/dist/literatureReview-C4AgVljZ.d.ts +0 -43
- package/dist/literatureReview-Dlods4Aw.d.cts +0 -43
- package/dist/webScraper-pKzdXhfI.d.ts +0 -46
- 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
|
+
[](https://www.npmjs.com/package/@thanh01.pmt/research-kit)
|
|
7
|
+
[](https://github.com/thanh01pmt/learnwell-platform)
|
|
8
|
+
[](https://www.typescriptlang.org/)
|
|
9
|
+
[](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.
|