@devilsdev/rag-pipeline-utils 2.4.0 → 2.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.
- package/README.md +85 -395
- package/package.json +18 -4
package/README.md
CHANGED
|
@@ -1,451 +1,141 @@
|
|
|
1
1
|
# rag-pipeline-utils
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The complete Node.js toolkit for production-grade RAG — evaluation, citation, agentic reasoning, guardrails, and 7 provider connectors in one package.
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils)
|
|
7
|
-
[](https://codecov.io/gh/DevilsDev/rag-pipeline-utils)
|
|
8
|
-
[](https://opensource.org/licenses/GPL-3.0)
|
|
9
|
-
[](https://nodejs.org/)
|
|
5
|
+
[](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils)
|
|
10
6
|
[](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils)
|
|
7
|
+
[](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils)
|
|
8
|
+
[](https://opensource.org/licenses/GPL-3.0)
|
|
9
|
+
[](https://nodejs.org/)
|
|
11
10
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
## Why This Exists
|
|
15
|
-
|
|
16
|
-
Building RAG systems in Node.js shouldn't require stitching together Python tools or reinventing every component. **rag-pipeline-utils** gives you the complete stack in one package: loaders, embedders, retrievers, LLM connectors, rerankers, evaluation, citation tracking, guardrails, and agentic reasoning.
|
|
17
|
-
|
|
18
|
-
Every component follows clear contracts. Every integration is optional. Every decision is yours.
|
|
19
|
-
|
|
20
|
-
- **Modular** -- swap any component without rewriting your pipeline
|
|
21
|
-
- **Evaluated** -- built-in faithfulness, relevance, and groundedness metrics on every run
|
|
22
|
-
- **Safe** -- 3-layer guardrails with prompt injection detection, PII filtering, and source grounding
|
|
23
|
-
- **Observable** -- OpenTelemetry tracing, Prometheus metrics, and compliance-grade audit logs
|
|
24
|
-
- **Connected** -- OpenAI, Anthropic, Cohere, Ollama, or bring your own
|
|
25
|
-
|
|
26
|
-
---
|
|
27
|
-
|
|
28
|
-
## Quick Start
|
|
11
|
+
## Installation
|
|
29
12
|
|
|
30
13
|
```bash
|
|
31
14
|
npm install @devilsdev/rag-pipeline-utils
|
|
32
15
|
```
|
|
33
16
|
|
|
34
|
-
|
|
17
|
+
## Quick Start
|
|
35
18
|
|
|
36
19
|
```javascript
|
|
37
|
-
|
|
20
|
+
import {
|
|
38
21
|
createRagPipeline,
|
|
39
22
|
OpenAIConnector,
|
|
40
23
|
MemoryRetriever,
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
const llm = new OpenAIConnector({ apiKey: process.env.OPENAI_API_KEY });
|
|
44
|
-
const retriever = new MemoryRetriever();
|
|
24
|
+
} from "@devilsdev/rag-pipeline-utils";
|
|
45
25
|
|
|
46
|
-
const pipeline = createRagPipeline({
|
|
26
|
+
const pipeline = createRagPipeline({
|
|
27
|
+
retriever: new MemoryRetriever(),
|
|
28
|
+
llm: new OpenAIConnector({ apiKey: process.env.OPENAI_API_KEY }),
|
|
29
|
+
});
|
|
47
30
|
|
|
48
31
|
const result = await pipeline.run({
|
|
49
32
|
query: "What is the vacation policy?",
|
|
50
33
|
options: { citations: true, evaluate: true },
|
|
51
34
|
});
|
|
52
35
|
|
|
53
|
-
console.log(result.results);
|
|
54
|
-
//
|
|
55
|
-
console.log(result.
|
|
56
|
-
// 0.85 -- how well the answer is grounded in sources
|
|
57
|
-
console.log(result.evaluation?.scores);
|
|
58
|
-
// { faithfulness: 0.9, relevance: 0.8, contextPrecision: 0.7, ... }
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
**Requirements:** Node.js >= 18.0.0
|
|
62
|
-
|
|
63
|
-
---
|
|
64
|
-
|
|
65
|
-
## Architecture
|
|
66
|
-
|
|
67
|
-
```mermaid
|
|
68
|
-
graph LR
|
|
69
|
-
A[Documents] --> B[Chunking Engine]
|
|
70
|
-
B --> C[Embedder]
|
|
71
|
-
C --> D[Vector Store]
|
|
72
|
-
|
|
73
|
-
F[User Query] --> G{Guardrails}
|
|
74
|
-
G --> H[Query Planner]
|
|
75
|
-
H --> E[Retriever + BM25]
|
|
76
|
-
E --> I[Reranker]
|
|
77
|
-
I --> J[LLM]
|
|
78
|
-
J --> K{Citation Tracker}
|
|
79
|
-
K --> L{Evaluator}
|
|
80
|
-
L --> M[Response]
|
|
81
|
-
|
|
82
|
-
style B fill:#e1f5e1
|
|
83
|
-
style E fill:#e1f5e1
|
|
84
|
-
style G fill:#fff4e1
|
|
85
|
-
style H fill:#fff4e1
|
|
86
|
-
style K fill:#e3f2fd
|
|
87
|
-
style L fill:#e3f2fd
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
**Pipeline stages:** Chunk --> Embed --> Store --> Retrieve --> Rerank --> Generate --> Cite --> Evaluate
|
|
91
|
-
|
|
92
|
-
Each stage is optional, pluggable, and observable. Enable citation tracking and evaluation with a single option flag.
|
|
93
|
-
|
|
94
|
-
---
|
|
95
|
-
|
|
96
|
-
## Features
|
|
97
|
-
|
|
98
|
-
### Plugin Architecture
|
|
99
|
-
|
|
100
|
-
Five plugin types with JSON Schema contracts: **loader**, **embedder**, **retriever**, **llm**, and **reranker**. Register, validate, and swap components at runtime.
|
|
101
|
-
|
|
102
|
-
```javascript
|
|
103
|
-
const { pluginRegistry } = require("@devilsdev/rag-pipeline-utils");
|
|
104
|
-
pluginRegistry.register("llm", "my-model", MyCustomLLM);
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
### Smart Chunking
|
|
108
|
-
|
|
109
|
-
Five built-in strategies for document splitting: `sentence`, `fixed-size`, `recursive` (default, 512 chars), `semantic` (topic-boundary detection), and `structure-aware` (respects Markdown headers, HTML sections, code blocks).
|
|
110
|
-
|
|
111
|
-
```javascript
|
|
112
|
-
const { ChunkingEngine } = require("@devilsdev/rag-pipeline-utils");
|
|
113
|
-
const engine = new ChunkingEngine({
|
|
114
|
-
strategy: "recursive",
|
|
115
|
-
chunkSize: 512,
|
|
116
|
-
chunkOverlap: 50,
|
|
117
|
-
});
|
|
118
|
-
const chunks = engine.chunk(documentText);
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
### Hybrid Retrieval
|
|
122
|
-
|
|
123
|
-
Combine vector similarity with BM25 keyword search using Reciprocal Rank Fusion. Run multiple retrievers in parallel with graceful degradation.
|
|
124
|
-
|
|
125
|
-
```javascript
|
|
126
|
-
const {
|
|
127
|
-
BM25Search,
|
|
128
|
-
HybridRetriever,
|
|
129
|
-
} = require("@devilsdev/rag-pipeline-utils");
|
|
130
|
-
const bm25 = new BM25Search();
|
|
131
|
-
bm25.index(documents);
|
|
132
|
-
|
|
133
|
-
const hybrid = new HybridRetriever([
|
|
134
|
-
{ retriever: vectorRetriever, weight: 0.7, name: "vector" },
|
|
135
|
-
{ retriever: bm25, weight: 0.3, name: "keyword" },
|
|
136
|
-
]);
|
|
137
|
-
const results = await hybrid.retrieve({ query });
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
### RAG Evaluation
|
|
141
|
-
|
|
142
|
-
Measure pipeline quality with five built-in metrics: **faithfulness**, **answer relevance**, **context precision**, **context recall**, and **groundedness**. Run automatically on every pipeline execution or standalone.
|
|
143
|
-
|
|
144
|
-
```javascript
|
|
145
|
-
const { PipelineEvaluator } = require("@devilsdev/rag-pipeline-utils");
|
|
146
|
-
const evaluator = new PipelineEvaluator();
|
|
147
|
-
const metrics = evaluator.evaluate({ query, answer, results: retrievedDocs });
|
|
148
|
-
// metrics.scores.faithfulness, metrics.scores.relevance, etc.
|
|
36
|
+
console.log(result.results); // retrieved documents
|
|
37
|
+
console.log(result.citations.groundednessScore); // 0.85
|
|
38
|
+
console.log(result.evaluation.scores); // { faithfulness, relevance, ... }
|
|
149
39
|
```
|
|
150
40
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
### Citation & Grounding
|
|
41
|
+
**Requirements:** Node.js ≥ 18
|
|
154
42
|
|
|
155
|
-
|
|
43
|
+
## Why
|
|
156
44
|
|
|
157
|
-
|
|
158
|
-
const { CitationTracker } = require("@devilsdev/rag-pipeline-utils");
|
|
159
|
-
const tracker = new CitationTracker();
|
|
160
|
-
const result = tracker.track(answer, retrievedDocs);
|
|
161
|
-
// result.groundednessScore, result.citations, result.hallucinationReport
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
### Agentic RAG
|
|
165
|
-
|
|
166
|
-
Multi-step retrieval with query decomposition, iterative search, and self-critique. The agent splits complex questions into sub-queries, retrieves evidence in parallel via the DAG engine, and validates its own answer before returning.
|
|
167
|
-
|
|
168
|
-
```javascript
|
|
169
|
-
const { AgenticPipeline } = require("@devilsdev/rag-pipeline-utils");
|
|
170
|
-
const agent = new AgenticPipeline({
|
|
171
|
-
enableCritique: true,
|
|
172
|
-
enablePlanning: true,
|
|
173
|
-
});
|
|
174
|
-
const result = await agent.run({
|
|
175
|
-
query: "Compare all three competitors",
|
|
176
|
-
retriever,
|
|
177
|
-
llm,
|
|
178
|
-
});
|
|
179
|
-
// result.subQueries, result.critique, result.answer
|
|
180
|
-
```
|
|
45
|
+
Most RAG solutions force vendor lock-in, opinionated architectures, or sacrifice observability for simplicity. `rag-pipeline-utils` gives you modular building blocks with clear contracts — every component is swappable, every decision is yours.
|
|
181
46
|
|
|
182
|
-
|
|
47
|
+
- **Modular** — swap any component without rewriting your pipeline
|
|
48
|
+
- **Evaluated** — faithfulness, relevance, and groundedness metrics on every run
|
|
49
|
+
- **Safe** — 3-layer guardrails: prompt injection detection, ACL filtering, PII detection
|
|
50
|
+
- **Observable** — OpenTelemetry tracing, Prometheus metrics, audit logs
|
|
51
|
+
- **Connected** — OpenAI, Anthropic, Cohere, Ollama, or bring your own
|
|
183
52
|
|
|
184
|
-
|
|
53
|
+
## Architecture
|
|
185
54
|
|
|
186
|
-
```javascript
|
|
187
|
-
const { GuardrailsPipeline } = require("@devilsdev/rag-pipeline-utils");
|
|
188
|
-
const safePipeline = new GuardrailsPipeline(pipeline, {
|
|
189
|
-
preRetrieval: { enableInjectionDetection: true },
|
|
190
|
-
retrieval: { minRelevanceScore: 0.6 },
|
|
191
|
-
postGeneration: { enablePIIDetection: true, enableGroundednessCheck: true },
|
|
192
|
-
});
|
|
193
|
-
const result = await safePipeline.run({ query });
|
|
194
55
|
```
|
|
56
|
+
Ingestion: Documents → Chunking → Embedder → Vector Store
|
|
195
57
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
58
|
+
Query: User Query
|
|
59
|
+
↓
|
|
60
|
+
Guardrails → prompt injection, topic filtering
|
|
61
|
+
↓
|
|
62
|
+
Query Planner → decomposes complex queries
|
|
63
|
+
↓
|
|
64
|
+
Hybrid Retriever → vector + BM25 with Reciprocal Rank Fusion
|
|
65
|
+
↓
|
|
66
|
+
Reranker → BM25 / embedding / cascade
|
|
67
|
+
↓
|
|
68
|
+
LLM → generates answer from context
|
|
69
|
+
↓
|
|
70
|
+
Citation Tracker → maps sentences to sources
|
|
71
|
+
↓
|
|
72
|
+
Evaluator → scores faithfulness & groundedness
|
|
73
|
+
↓
|
|
74
|
+
Response { answer, citations, evaluation }
|
|
208
75
|
```
|
|
209
76
|
|
|
210
|
-
|
|
77
|
+
Each stage is optional and pluggable.
|
|
211
78
|
|
|
212
|
-
|
|
79
|
+
## Features
|
|
213
80
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
81
|
+
| Category | Capabilities |
|
|
82
|
+
| -------------- | ------------------------------------------------------------------------ |
|
|
83
|
+
| **Chunking** | 5 strategies: sentence, fixed-size, recursive, semantic, structure-aware |
|
|
84
|
+
| **Retrieval** | Hybrid vector + BM25 with Reciprocal Rank Fusion |
|
|
85
|
+
| **Reranking** | LLM, BM25 scoring, embedding similarity, or cascade |
|
|
86
|
+
| **Evaluation** | Faithfulness, relevance, context precision/recall, groundedness |
|
|
87
|
+
| **Citation** | Source attribution per sentence, hallucination detection |
|
|
88
|
+
| **Agentic** | Query planning, iterative retrieval, self-critique via DAG engine |
|
|
89
|
+
| **Guardrails** | Injection detection, PII filtering, ACL-aware access control |
|
|
90
|
+
| **GraphRAG** | Knowledge graph construction with entity extraction |
|
|
91
|
+
| **Streaming** | SSE and WebSocket adapters with backpressure control |
|
|
92
|
+
| **Cost** | Token tracking, budget enforcement, provider pricing models |
|
|
93
|
+
| **Debugging** | Execution tracing, bottleneck detection, replay |
|
|
94
|
+
| **MCP** | Expose pipelines as Model Context Protocol tools |
|
|
95
|
+
| **Security** | JWT replay protection, plugin sandboxing, audit logs |
|
|
96
|
+
| **Enterprise** | Multi-tenancy, SSO (SAML/OAuth2/AD/OIDC), data governance |
|
|
97
|
+
|
|
98
|
+
**104 public exports** across the full RAG lifecycle. See [full documentation](https://devilsdev.github.io/rag-pipeline-utils/) for complete API reference.
|
|
99
|
+
|
|
100
|
+
## Provider Connectors
|
|
101
|
+
|
|
102
|
+
```javascript
|
|
103
|
+
import {
|
|
104
|
+
OpenAIConnector, // GPT-4, text-embedding-3
|
|
217
105
|
AnthropicConnector, // Claude 3 Opus, Sonnet, Haiku
|
|
218
106
|
CohereConnector, // Embed + Rerank
|
|
219
107
|
OllamaConnector, // Llama 3, Mistral (local)
|
|
220
108
|
LocalEmbedder, // TF-IDF (offline, no API)
|
|
221
109
|
MemoryRetriever, // In-memory cosine similarity
|
|
222
|
-
}
|
|
223
|
-
|
|
224
|
-
const ollama = new OllamaConnector({
|
|
225
|
-
model: "llama3",
|
|
226
|
-
baseURL: "http://localhost:11434",
|
|
227
|
-
});
|
|
228
|
-
const openai = new OpenAIConnector({ apiKey: process.env.OPENAI_API_KEY });
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
### Cost Management
|
|
232
|
-
|
|
233
|
-
Track token spend per provider, estimate costs before execution, and enforce budgets with hard and soft limits.
|
|
234
|
-
|
|
235
|
-
```javascript
|
|
236
|
-
const {
|
|
237
|
-
CostCalculator,
|
|
238
|
-
TokenBudget,
|
|
239
|
-
} = require("@devilsdev/rag-pipeline-utils");
|
|
240
|
-
const calc = new CostCalculator();
|
|
241
|
-
const cost = calc.estimate("gpt-4", 2000, 500);
|
|
242
|
-
// cost.totalCost = 0.09 (USD)
|
|
243
|
-
|
|
244
|
-
const budget = new TokenBudget({ maxTokens: 100000 });
|
|
245
|
-
budget.record(2500);
|
|
246
|
-
budget.check(1000); // { allowed: true, remaining: { tokens: 96500 } }
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
### Pipeline Debugging
|
|
250
|
-
|
|
251
|
-
Trace every execution step with timing, bottleneck detection, and optimization recommendations.
|
|
252
|
-
|
|
253
|
-
```javascript
|
|
254
|
-
const {
|
|
255
|
-
ExecutionTracer,
|
|
256
|
-
TraceInspector,
|
|
257
|
-
} = require("@devilsdev/rag-pipeline-utils");
|
|
258
|
-
const tracer = new ExecutionTracer();
|
|
259
|
-
const traced = tracer.trace(pipeline);
|
|
260
|
-
const result = await traced.run({ query });
|
|
261
|
-
|
|
262
|
-
const inspector = new TraceInspector();
|
|
263
|
-
const analysis = inspector.analyze(tracer.getTraces()[0]);
|
|
264
|
-
// analysis.bottleneck, analysis.recommendations
|
|
265
|
-
```
|
|
266
|
-
|
|
267
|
-
### MCP Integration
|
|
268
|
-
|
|
269
|
-
Expose any pipeline as a Model Context Protocol tool, callable from Claude Desktop, IDE extensions, or any MCP-compatible client.
|
|
270
|
-
|
|
271
|
-
```javascript
|
|
272
|
-
const { MCPServer } = require("@devilsdev/rag-pipeline-utils");
|
|
273
|
-
const server = MCPServer.fromPipeline(pipeline, { name: "knowledge-base" });
|
|
274
|
-
const tools = server.getToolDefinitions();
|
|
275
|
-
const result = await server.handleToolUse("knowledge-base", {
|
|
276
|
-
query: "How does auth work?",
|
|
277
|
-
});
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
### Quick Start Templates
|
|
281
|
-
|
|
282
|
-
Scaffold complete projects from four built-in templates: `document-qa`, `chatbot`, `code-search`, and `customer-support`.
|
|
283
|
-
|
|
284
|
-
```javascript
|
|
285
|
-
const { ProjectScaffolder } = require("@devilsdev/rag-pipeline-utils");
|
|
286
|
-
const scaffolder = new ProjectScaffolder();
|
|
287
|
-
scaffolder.create("chatbot", "./my-chatbot");
|
|
288
|
-
// Creates: package.json, index.js, .ragrc.json, README.md
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
### Streaming Embeddings
|
|
292
|
-
|
|
293
|
-
Generate embeddings in real-time with backpressure control and memory management. Process millions of documents without running out of memory.
|
|
294
|
-
|
|
295
|
-
```javascript
|
|
296
|
-
const { StreamingEmbedder } = require("@devilsdev/rag-pipeline-utils");
|
|
297
|
-
const streamer = new StreamingEmbedder(myEmbedder, {
|
|
298
|
-
batchSize: 50,
|
|
299
|
-
maxMemoryMB: 512,
|
|
300
|
-
});
|
|
301
|
-
for await (const { id, vector, progress } of streamer.embedStream(documents)) {
|
|
302
|
-
console.log(`${(progress * 100).toFixed(0)}% — embedded ${id}`);
|
|
303
|
-
}
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
### GraphRAG
|
|
307
|
-
|
|
308
|
-
Build knowledge graphs from documents and retrieve using entity-relationship traversal. Combines graph-based scoring with text matching for superior retrieval on entity-heavy content.
|
|
309
|
-
|
|
310
|
-
```javascript
|
|
311
|
-
const { GraphRetriever } = require("@devilsdev/rag-pipeline-utils");
|
|
312
|
-
const retriever = new GraphRetriever({ traversalDepth: 2 });
|
|
313
|
-
await retriever.store(documents); // Extracts entities + builds graph
|
|
314
|
-
const results = await retriever.retrieve("Who founded OpenAI?", 5);
|
|
315
|
-
// Results ranked by entity graph traversal + text relevance
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
### Advanced Reranking
|
|
319
|
-
|
|
320
|
-
Three reranking strategies beyond LLM-based: BM25 scoring, embedding cosine similarity, and cascaded multi-stage reranking.
|
|
321
|
-
|
|
322
|
-
```javascript
|
|
323
|
-
const {
|
|
324
|
-
ScoringReranker,
|
|
325
|
-
EmbeddingReranker,
|
|
326
|
-
CascadeReranker,
|
|
327
|
-
} = require("@devilsdev/rag-pipeline-utils");
|
|
328
|
-
const cascade = new CascadeReranker([
|
|
329
|
-
new ScoringReranker(), // Stage 1: BM25 keyword scoring
|
|
330
|
-
new EmbeddingReranker(embedder), // Stage 2: semantic similarity
|
|
331
|
-
]);
|
|
332
|
-
const ranked = await cascade.rerank(query, documents);
|
|
333
|
-
```
|
|
334
|
-
|
|
335
|
-
### Performance Dashboard
|
|
336
|
-
|
|
337
|
-
Generate standalone HTML dashboards from pipeline metrics. No external dependencies — open in any browser.
|
|
338
|
-
|
|
339
|
-
```javascript
|
|
340
|
-
const {
|
|
341
|
-
MetricsAggregator,
|
|
342
|
-
DashboardGenerator,
|
|
343
|
-
} = require("@devilsdev/rag-pipeline-utils");
|
|
344
|
-
const aggregator = new MetricsAggregator();
|
|
345
|
-
aggregator.recordQuery({ duration: 250, cost: 0.003, success: true });
|
|
346
|
-
|
|
347
|
-
const dashboard = new DashboardGenerator();
|
|
348
|
-
const html = dashboard.generate(aggregator.getSnapshot());
|
|
349
|
-
// Write to file: fs.writeFileSync('dashboard.html', html);
|
|
350
|
-
```
|
|
351
|
-
|
|
352
|
-
### Enterprise
|
|
353
|
-
|
|
354
|
-
Multi-tenant isolation, SSO integration (SAML, OAuth2, Active Directory, OIDC), compliance-grade audit logging, and data governance with classification and retention policies.
|
|
355
|
-
|
|
356
|
-
### DAG Workflow Engine
|
|
357
|
-
|
|
358
|
-
Chain complex multi-step operations with topological execution, retry logic, parallel processing via semaphore-based concurrency, graceful degradation, and checkpoint/resume.
|
|
359
|
-
|
|
360
|
-
### Security
|
|
361
|
-
|
|
362
|
-
Defense-in-depth: JWT replay protection, algorithm whitelisting, plugin sandboxing with isolated-vm, multi-layer path traversal defense (5-pass iterative URL decoding), input validation, and automatic secret redaction (36+ patterns).
|
|
363
|
-
|
|
364
|
-
### Observability
|
|
365
|
-
|
|
366
|
-
OpenTelemetry distributed tracing, Prometheus metrics export, structured Pino logging, SLO monitoring, and security event tracking.
|
|
367
|
-
|
|
368
|
-
---
|
|
369
|
-
|
|
370
|
-
## Installation
|
|
371
|
-
|
|
372
|
-
```bash
|
|
373
|
-
npm install @devilsdev/rag-pipeline-utils
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
### Development
|
|
377
|
-
|
|
378
|
-
```bash
|
|
379
|
-
git clone https://github.com/DevilsDev/rag-pipeline-utils.git
|
|
380
|
-
cd rag-pipeline-utils
|
|
381
|
-
npm install
|
|
382
|
-
npm test # 92 suites, 2050+ tests
|
|
383
|
-
npm run build # CJS + ESM + TypeScript definitions
|
|
384
|
-
npm run lint # ESLint
|
|
385
|
-
npm run dev # Interactive development tools
|
|
110
|
+
} from "@devilsdev/rag-pipeline-utils";
|
|
386
111
|
```
|
|
387
112
|
|
|
388
|
-
|
|
113
|
+
## Documentation
|
|
389
114
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
npm run docs:validate # Verify README code examples
|
|
395
|
-
npm run verify:esm # Validate ESM build
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
---
|
|
115
|
+
- **[Full documentation](https://devilsdev.github.io/rag-pipeline-utils/)** — guides, API reference, deployment
|
|
116
|
+
- **[Architecture guide](https://devilsdev.github.io/rag-pipeline-utils/docs/Architecture)** — pipeline internals
|
|
117
|
+
- **[API reference](https://devilsdev.github.io/rag-pipeline-utils/docs/API-Reference)** — all 104 exports
|
|
118
|
+
- **[Examples](https://devilsdev.github.io/rag-pipeline-utils/docs/Examples)** — chatbot, Q&A, code search, support
|
|
399
119
|
|
|
400
120
|
## Roadmap
|
|
401
121
|
|
|
402
|
-
|
|
122
|
+
**Current (v2.4):** chunking, citation, evaluation, agentic RAG, hybrid retrieval, 3-layer guardrails, GraphRAG, streaming, cost management, MCP integration, 7 provider connectors.
|
|
403
123
|
|
|
404
|
-
|
|
405
|
-
- Streaming embeddings with backpressure control
|
|
406
|
-
- GraphRAG -- knowledge graph construction, entity extraction, graph-based retrieval
|
|
407
|
-
- Advanced reranking -- BM25 scoring, embedding-based, cascade rerankers
|
|
408
|
-
- Performance dashboard -- HTML dashboard generator, metrics aggregation
|
|
409
|
-
- Smart chunking, citation tracking, RAG evaluation, agentic RAG, hybrid retrieval
|
|
410
|
-
- 3-layer guardrails, cost management, MCP integration, streaming adapters
|
|
411
|
-
- 7 provider connectors (OpenAI, Anthropic, Cohere, Ollama, LocalEmbedder, MemoryRetriever)
|
|
412
|
-
- 92 test suites, 2050+ tests
|
|
124
|
+
**Next (v3.0):** intelligent caching, native Rust bindings, Kubernetes operator, edge deployment (Cloudflare Workers, Deno Deploy).
|
|
413
125
|
|
|
414
|
-
|
|
126
|
+
Vote on features in [GitHub Discussions](https://github.com/DevilsDev/rag-pipeline-utils/discussions/categories/roadmap).
|
|
415
127
|
|
|
416
|
-
|
|
417
|
-
- **Native Rust Bindings** -- performance-critical paths compiled to native code
|
|
418
|
-
- **Kubernetes Operator** -- production deployments with auto-scaling
|
|
419
|
-
- **Edge Deployment** -- Cloudflare Workers, Deno Deploy, Vercel Edge
|
|
420
|
-
- **Real-time Collaboration** -- team-based pipeline editing and sharing
|
|
128
|
+
## Community
|
|
421
129
|
|
|
422
|
-
**
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
## Contributing
|
|
427
|
-
|
|
428
|
-
We welcome contributions of all kinds:
|
|
429
|
-
|
|
430
|
-
- **Code** -- fix bugs, add features, improve performance
|
|
431
|
-
- **Documentation** -- write guides, improve examples, clarify concepts
|
|
432
|
-
- **Testing** -- expand test coverage, add integration tests, report edge cases
|
|
433
|
-
- **Design** -- propose API improvements, suggest architectural patterns
|
|
434
|
-
- **Community** -- answer questions, review pull requests, mentor new contributors
|
|
435
|
-
|
|
436
|
-
**Before you start:**
|
|
437
|
-
|
|
438
|
-
1. Read the [Contributing Guide](https://github.com/DevilsDev/rag-pipeline-utils/blob/main/docs/CONTRIBUTING.md)
|
|
439
|
-
2. Check existing [Issues](https://github.com/DevilsDev/rag-pipeline-utils/issues) and [Discussions](https://github.com/DevilsDev/rag-pipeline-utils/discussions)
|
|
440
|
-
3. Open an issue to discuss major changes before coding
|
|
441
|
-
4. Follow our [Code of Conduct](https://github.com/DevilsDev/rag-pipeline-utils/blob/main/CODE_OF_CONDUCT.md)
|
|
442
|
-
|
|
443
|
-
---
|
|
130
|
+
- **[GitHub Discussions](https://github.com/DevilsDev/rag-pipeline-utils/discussions)** — ask questions, share use cases
|
|
131
|
+
- **[Issues](https://github.com/DevilsDev/rag-pipeline-utils/issues)** — report bugs, request features
|
|
132
|
+
- **[Contributing guide](https://github.com/DevilsDev/rag-pipeline-utils/blob/main/docs/CONTRIBUTING.md)** — submit pull requests
|
|
133
|
+
- **[Code of Conduct](https://github.com/DevilsDev/rag-pipeline-utils/blob/main/CODE_OF_CONDUCT.md)**
|
|
444
134
|
|
|
445
135
|
## License
|
|
446
136
|
|
|
447
|
-
|
|
137
|
+
GPL-3.0 — see [LICENSE](LICENSE) for full terms.
|
|
448
138
|
|
|
449
139
|
---
|
|
450
140
|
|
|
451
|
-
**Star
|
|
141
|
+
**Star the repo** if you find it useful. **Share your use case** in [Discussions](https://github.com/DevilsDev/rag-pipeline-utils/discussions/categories/show-and-tell).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@devilsdev/rag-pipeline-utils",
|
|
3
|
-
"version": "2.4.
|
|
3
|
+
"version": "2.4.1",
|
|
4
4
|
"description": "A comprehensive enterprise-grade toolkit for building RAG (Retrieval-Augmented Generation) pipelines with advanced AI/ML capabilities",
|
|
5
5
|
"main": "dist/index.cjs",
|
|
6
6
|
"type": "commonjs",
|
|
@@ -108,11 +108,25 @@
|
|
|
108
108
|
"keywords": [
|
|
109
109
|
"rag",
|
|
110
110
|
"retrieval-augmented-generation",
|
|
111
|
-
"vectorstore",
|
|
112
111
|
"llm",
|
|
112
|
+
"embeddings",
|
|
113
|
+
"vector-search",
|
|
114
|
+
"semantic-search",
|
|
113
115
|
"pipeline",
|
|
114
|
-
"
|
|
115
|
-
"
|
|
116
|
+
"chunking",
|
|
117
|
+
"agentic",
|
|
118
|
+
"graphrag",
|
|
119
|
+
"guardrails",
|
|
120
|
+
"evaluation",
|
|
121
|
+
"citation",
|
|
122
|
+
"openai",
|
|
123
|
+
"anthropic",
|
|
124
|
+
"cohere",
|
|
125
|
+
"ollama",
|
|
126
|
+
"ai",
|
|
127
|
+
"nodejs",
|
|
128
|
+
"typescript",
|
|
129
|
+
"cli"
|
|
116
130
|
],
|
|
117
131
|
"author": "Ali Kahwaji",
|
|
118
132
|
"license": "GPL-3.0",
|