@devilsdev/rag-pipeline-utils 2.0.0 → 2.1.0

package/docs-site/blog/2025-04-17-release-2.0.md

@@ -0,0 +1,67 @@
+---
+slug: release-2-0
+title: Release 2.0.0 – Plugin Contracts, CI Automation, Docs
+authors: [ali]
+tags: [release, changelog]
+description: RAG Pipeline Utils v2.0.0 introduces plugin contract validation, full CI coverage, fixture repairs, and professional Docusaurus docs.
+---
+
+We’re thrilled to announce the release of **RAG Pipeline Utils v2.0.0** — a fully modular and developer-focused toolkit for constructing, validating, and managing RAG (Retrieval-Augmented Generation) pipelines.
+
+---
+
+## 🚀 Highlights in v2.0.0
+
+### 🔌 Contract-Based Plugin Validation
+
+- Enforces strict interfaces for all core plugin types:
+  - `loader.load()`
+  - `embedder.embed()` and `embedQuery()`
+  - `retriever.store()` and `search()`
+  - `llm.ask()`
+- Includes auto-verification and CLI validation via `scripts/verify-fixture-mocks.js`
+
+### 🧪 Enhanced CI & Git Hooks
+
+- Full GitHub Actions integration:
+  - Lint, test, mock validation, release automation
+- Local enforcement using **Husky** + **validate-changelog-version.js**
+
+### 🧰 Fixture Repair & Auto-Mock Utilities
+
+- Self-healing script: `scripts/repair-fixtures.js`
+- Support for regenerating mocks that align with runtime requirements and CLI tests
+
+### 📘 Developer Documentation
+
+- Professionally published Docusaurus site:
+  - 📚 [Visit Docs](https://devilsdev.github.io/rag-pipeline-utils)
+  - 🧭 Usage, architecture, CLI, plugin extension, and release notes
+- Blog support enabled for continuous release announcements
+
+---
+
+## ✨ Why This Matters
+
+This release marks a shift from traditional monolithic RAG stacks to a **fully composable, testable, and CI-validated** toolkit. It was built with long-term developer experience (DX) in mind, emphasizing:
+
+- 📦 **Modularity**: Swap or add plugins without rewriting pipeline logic
+- 🧪 **Test Confidence**: Never publish broken mocks or CI regressions again
+- 🧠 **Scalability**: Suitable for both small prototypes and production pipelines
+- 🛠 **Tooling First**: Includes everything from config loading to evaluation dashboards
+
+---
+
+## 📦 Install Now
+
+```bash
+npm install @devilsdev/rag-pipeline-utils
+```
+
+---
+
+For upgrade guides, contract schemas, and real-world examples, check out the [official docs](https://devilsdev.github.io/rag-pipeline-utils/docs/Introduction).
+
+🧠 Built for engineers who want **control, clarity, and composability** in their LLM workflows.
+
+— *Ali Kahwaji & RAG Pipeline Utils Contributors*

package/docs-site/blog/2025-04-17-release-v2.0.2.md

@@ -0,0 +1,13 @@
+---
+slug: release-v2.0.2
+title: ✨ Version v2.0.2 Released
+authors: [ali]
+tags: [release, changelog]
+---
+
+RAG Pipeline Utils vv2.0.2 is now available on NPM!
+
+#### Highlights
+- 🚀 Auto-published blog from GitHub release
+- 📦 Version bump: v2.0.2
+- 📘 See CHANGELOG.md for full details

package/docs-site/blog/2025-04-18-architecture-overview.md

@@ -0,0 +1,34 @@
+---
+slug: architecture-overview
+title: RAG Pipeline Architecture Overview
+authors: [ali]
+tags: [architecture, design, modular]
+description: A deep dive into the architecture powering RAG Pipeline Utils — from plugin interfaces to flexible pipeline composition.
+---
+
+Welcome to the first post in our deep dive blog series on **RAG Pipeline Utils** — a fully modular, testable, and production-grade framework for building retrieval-augmented generation pipelines.
+
+## Why Modular RAG?
+
+Most RAG tools are tightly coupled or opinionated. We built this utility to empower dev teams with:
+
+-  Swappable plugins for loaders, embedders, retrievers, LLMs
+-  CLI tools for evaluation & schema validation
+-  Docusaurus-based docs with versioned releases
+-  Full CI/CD and automated NPM releases
+
+## Architecture Highlights
+
+- `PluginRegistry`: Registers and resolves all components.
+- `validateSchema`: Enforces `.ragrc.json` format across all pipelines.
+- `mocks/`: Local test doubles for every plugin interface.
+- `__tests__/`: Dual-layer coverage — unit + integration.
+
+## Try It Now
+
+```bash
+npm install @devilsdev/rag-pipeline-utils
+npx rag-utils run --config .ragrc.json
+```
+
+Stay tuned for future posts including CI validation, RAG evaluation tooling, and how to build your own dashboard for prompt scoring.

package/docs-site/blog/2025-04-18-release-2.0.0.md

@@ -0,0 +1,21 @@
+---
+slug: release-2-0-0
+title: Release 2.0.0 — Modular RAG Toolkit
+authors: ali
+tags: [release, changelog, RAG, developer-tools]
+---
+
+🚀 **Version 2.0.0** is now live on [npm](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils)!
+
+This release introduces:
+
+- ✅ Plugin contracts for loaders, embedders, retrievers, LLMs
+- 🧪 Fixture mock verification + CLI validation
+- 🧰 Auto-repair tooling for broken test mocks
+- 📦 Seamless integration with `.ragrc.json` config fallback
+- 📄 Docusaurus documentation & blog support
+- 💡 Modern DX with versioned docs, coverage, CI hooks, changelogs
+
+Explore docs → [devilsdev.github.io/rag-pipeline-utils](https://devilsdev.github.io/rag-pipeline-utils)
+
+📌 Run `npm install @devilsdev/rag-pipeline-utils` to get started.

package/docs-site/blog/2025-04-19-prompt-engineering-best-practices.md

@@ -0,0 +1,31 @@
+---
+title: "Prompt Engineering Best Practices for RAG"
+slug: prompt-engineering-best-practices
+authors: [ali]
+tags: [prompt-engineering, design]
+image: /img/social/prompt-engineering-card.png
+description: "A deep dive into prompt optimization strategies for RAG pipelines using modular design."
+---
+Prompt engineering is a critical lever in maximizing the effectiveness of Retrieval-Augmented Generation (RAG) systems. In this article, we explore:
+
+## Prompting in Modular RAG Pipelines
+
+Your `rag-pipeline-utils` system allows swappable LLM backends and encourages prompt templates as part of the reranker or query orchestrator.
+
+- Always define clear input/output expectations
+- Leverage JSON or YAML-based structured prompts where applicable
+- Evaluate with real examples using the CLI + evaluation framework
+
+## What to Include in Prompts
+
+- **Context injection**: retrieved chunks, metadata, source provenance
+- **Task framing**: instruction-oriented for LLM consistency
+- **Scoring heuristics**: if doing ranking, consider scoring guidelines
+
+## Prompt as Plugin (Future Feature)
+
+Eventually, we plan to support `promptTemplate` as a plugin type – enabling reusable prompt logic alongside `loader`, `retriever`, etc.
+
+---
+
+Stay tuned for our upcoming prompt debugger dashboard, and follow [releases](/blog/tags/release) for versioned updates.

package/docs-site/blog/2025-04-20-image-showcase.md

@@ -0,0 +1,23 @@
+---
+slug: image-showcase
+title: Blog Image Component Showcase
+authors: [ali]
+tags: [tutorials, design, image]
+description: Demonstrating LQIP-powered blog images using the BlogImage component.
+---
+
+import BlogImage from '@site/src/components/BlogImage';
+
+This post demonstrates the reusable **`<BlogImage />`** component, which displays optimized blurred placeholders (LQIPs) for faster rendering.
+
+## Example
+
+<BlogImage srcKey="img_hero" alt="Hero demonstration" />
+
+---
+
+## Benefits Recap
+
+- Blurred placeholder loading for faster perception
+- Fallback to default cache when missing
+- Ready for automation via `watch-images.js`

package/docs-site/blog/authors.yml

@@ -1,23 +1,5 @@
-yangshun:
-  name: Yangshun Tay
-  title: Front End Engineer @ Facebook
-  url: https://github.com/yangshun
-  image_url: https://github.com/yangshun.png
-  page: true
-  socials:
-    x: yangshunz
-    github: yangshun
-
-slorber:
-  name: Sébastien Lorber
-  title: Docusaurus maintainer
-  url: https://sebastienlorber.com
-  image_url: https://github.com/slorber.png
-  page:
-    # customize the url of the author page at /blog/authors/<permalink>
-    permalink: '/all-sebastien-lorber-articles'
-  socials:
-    x: sebastienlorber
-    linkedin: sebastienlorber
-    github: slorber
-    newsletter: https://thisweekinreact.com
+ali:
+  name: Ali Kahwaji
+  title: Creator & Maintainer of RAG Pipeline Utils
+  url: https://github.com/alikahwaji
+  image_url: /img/authors/ali.jpg

package/docs-site/blog/tags.yml

@@ -1,19 +1,30 @@
-facebook:
-  label: Facebook
-  permalink: /facebook
-  description: Facebook tag description
+# docs-site/blog/tags.yml
+# Description: Central tag definitions for Docusaurus blog filtering and grouping
 
-hello:
-  label: Hello
-  permalink: /hello
-  description: Hello tag description
+- label: Release
+  slug: release
+  permalink: /blog/tags/release
 
-docusaurus:
-  label: Docusaurus
-  permalink: /docusaurus
-  description: Docusaurus tag description
+- label: Architecture
+  slug: architecture
+  permalink: /blog/tags/architecture
 
-hola:
-  label: Hola
-  permalink: /hola
-  description: Hola tag description
+- label: Prompt Engineering
+  slug: prompt-engineering
+  permalink: /blog/tags/prompt-engineering
+
+- label: Evaluation
+  slug: evaluation
+  permalink: /blog/tags/evaluation
+
+- label: Tutorials
+  slug: tutorials
+  permalink: /blog/tags/tutorials
+
+- label: Changelog
+  slug: changelog
+  permalink: /blog/tags/changelog
+
+- label: Design
+  slug: design
+  permalink: /blog/tags/design

package/docs-site/docs/Architecture.md

@@ -4,7 +4,7 @@ This page outlines the internal architecture of the RAG pipeline utilities, emph
 
 ---
 
-## 🧩 Core Design Philosophy
+## Core Design Philosophy
 
 The architecture adheres to enterprise-grade practices:
 
@@ -16,7 +16,7 @@ The architecture adheres to enterprise-grade practices:
 
 ---
 
-## 🏗️ Layered Components
+## Layered Components
 
 ```
 +-------------------------+
@@ -36,7 +36,7 @@ The architecture adheres to enterprise-grade practices:
 
 ---
 
-## 📦 Core Interfaces
+## Core Interfaces
 
 Each plugin is registered via the `PluginRegistry` and looked up by key.
 
@@ -65,7 +65,7 @@ interface Retriever {
 
 ---
 
-## 🔁 DAG Support
+## DAG Support
 
 The `dag-engine.js` module supports chaining multiple components:
 - Example: Summarize → Retrieve → Rerank → LLM

package/docs-site/docs/CLI.md

@@ -14,7 +14,7 @@ npx rag-pipeline <command>
 
 ---
 
-## 🔧 Commands
+## Commands
 
 ### `ingest`
 ```bash
@@ -42,7 +42,7 @@ rag-pipeline rerank "What is RAG?" --retriever pinecone
 
 ---
 
-## ⚙️ `.ragrc.json` Config
+## `.ragrc.json` Config
 
 Defaults can be set in a file:
 ```json
@@ -57,7 +57,7 @@ Defaults can be set in a file:
 
 ---
 
-## 🐳 Docker Usage
+##  Docker Usage
 
 ```bash
 docker build -t rag-pipeline .

package/docs-site/docs/Evaluation.md

@@ -4,7 +4,7 @@ This module allows you to evaluate the quality of generated LLM responses in a R
 
 ---
 
-## 🎯 Objective
+## Objective
 
 Quantify how well the pipeline performs on question-answer pairs using:
 - **BLEU**: Precision on matching tokens
@@ -13,7 +13,7 @@ Quantify how well the pipeline performs on question-answer pairs using:
 
 ---
 
-## 📄 Dataset Format
+## Dataset Format
 
 Each entry in your JSON dataset should include:
 
@@ -28,20 +28,20 @@ Saved as: `sample-eval-dataset.json`
 
 ---
 
-## 🚀 CLI Evaluation
+## CLI Evaluation
 
 ```bash
 rag-pipeline evaluate ./fixtures/sample-eval-dataset.json
 ```
 
 Outputs:
-- ✅ Pass/fail per item
-- 📊 BLEU/ROUGE scores
-- 📈 Aggregated metrics
+- Pass/fail per item
+- BLEU/ROUGE scores
+- Aggregated metrics
 
 ---
 
-## 📊 Dashboard Visualization
+## Dashboard Visualization
 
 Use the React dashboard under `/public`:
 

package/docs-site/docs/FAQ.md

@@ -1,6 +1,6 @@
 # FAQ
 
-### ❓ Can I use this with my own vector database?
+### Can I use this with my own vector database?
 Yes! You can implement the `Retriever` interface and register it:
 ```ts
 registry.register('retriever', 'mydb', new MyRetriever());
@@ -9,17 +9,17 @@ Then use it via CLI or `.ragrc.json`.
 
 ---
 
-### ❓ Is streaming LLM response supported?
+### Is streaming LLM response supported?
 Yes. LLM runners can yield async output tokens. This is handled internally via `AsyncIterable` in compatible models.
 
 ---
 
-### ❓ How do I evaluate performance?
+### How do I evaluate performance?
 Use `rag-pipeline evaluate dataset.json` or open the dashboard at `http://localhost:3000` to visualize BLEU/ROUGE and pass rates.
 
 ---
 
-### ❓ What file types can I ingest?
+### What file types can I ingest?
 Currently supported:
 - `.pdf` (mocked)
 - `.md`
@@ -29,7 +29,7 @@ Currently supported:
 
 ---
 
-### ❓ Can I rerank results using a local model?
+### Can I rerank results using a local model?
 Yes, as long as your local LLM implements:
 ```ts
 llm.generate(prompt, context): Promise<string>
@@ -38,7 +38,7 @@ Use it to power `LLMReranker`.
 
 ---
 
-### ❓ How do I contribute?
+### How do I contribute?
 Fork the repo → add your plugin or CLI feature → test → submit PR.
 
 ---

package/docs-site/docs/Introduction.md

@@ -4,11 +4,11 @@ sidebar_position: 1
 
 # Introduction
 
-Welcome to **@yourorg/rag-pipeline-utils**, a modular Node.js toolkit for building scalable, pluggable Retrieval-Augmented Generation (RAG) systems.
+Welcome to **@DevilsDev/rag-pipeline-utils**, a modular Node.js toolkit for building scalable, pluggable Retrieval-Augmented Generation (RAG) systems.
 
 ---
 
-## 🚀 What is RAG?
+##  What is RAG?
 
 RAG combines information retrieval with large language models to enhance generation with factual grounding. It typically involves:
 
@@ -19,7 +19,7 @@ This project provides all the composable parts to build your own RAG pipeline.
 
 ---
 
-## 🔧 Why Use This Toolkit?
+##  Why Use This Toolkit?
 
 - **Plugin-based**: Swap in your own loaders, retrievers, LLMs
 - **Streaming-ready**: Async-friendly, token-by-token output
@@ -29,7 +29,7 @@ This project provides all the composable parts to build your own RAG pipeline.
 
 ---
 
-## 🧱 Architecture
+## Architecture
 
 Each RAG pipeline includes:
 
@@ -43,13 +43,13 @@ The pipeline can be used via code or via CLI commands.
 
 ---
 
-## ✅ Status
+## Status
 
 This project is:
-- ✅ Production-ready
-- ✅ Covered by unit/integration tests
-- ✅ Compatible with Node.js `>=18`
-- ✅ Published to npm under `@yourorg`
+- Production-ready
+- Covered by unit/integration tests
+- Compatible with Node.js `>=18`
+- Published to npm under `DevilsDev`
 
 ---
 

package/docs-site/docs/Plugins.md

@@ -4,7 +4,7 @@ The toolkit is fully modular. You can inject your own loaders, retrievers, embed
 
 ---
 
-## 🔌 Plugin Architecture
+## Plugin Architecture
 
 All plugins follow a strict interface pattern. Each is registered under a namespace using the plugin registry:
 
@@ -21,7 +21,7 @@ You can register plugins for:
 
 ---
 
-## 🧱 Loader Example
+## Loader Example
 
 ```ts
 class MyMarkdownLoader {
@@ -39,7 +39,7 @@ registry.register('loader', 'md', new MyMarkdownLoader());
 
 ---
 
-## ⚡ Runtime Override
+## Runtime Override
 
 CLI and API will resolve plugin names from `pluginRegistry`. Use:
 

package/docs-site/docs/Tutorials.md

@@ -0,0 +1,106 @@
+---
+id: Tutorials
+title: Tutorials & Onboarding
+sidebar_label: Tutorials
+---
+
+Welcome to the **RAG Pipeline Utils** tutorial section. These guides will help developers quickly onboard, integrate, and extend the modular RAG system.
+
+---
+
+##  1. Install the Package
+
+```bash
+npm install @devilsdev/rag-pipeline-utils
+```
+
+---
+
+## 2. Ingest Documents Using CLI
+
+This CLI command loads PDFs, embeds them, and stores the vectors.
+
+```bash
+npx rag-utils ingest ./sample.pdf --config .ragrc.json
+```
+
+Ensure you have a valid `.ragrc.json` config:
+
+```json
+{
+  "loader": { "pdf": "./src/mocks/pdf-loader.js" },
+  "embedder": { "openai": "./src/mocks/openai-embedder.js" },
+  "retriever": { "pinecone": "./src/mocks/pinecone-retriever.js" },
+  "llm": { "openai": "./src/mocks/openai-llm.js" },
+  "namespace": "docs-example",
+  "pipeline": ["loader", "embedder", "retriever"]
+}
+```
+
+---
+
+## 3. Run a Query Using CLI
+
+```bash
+npx rag-utils query "What is this document about?" --config .ragrc.json
+```
+
+---
+
+## 4. Register a Custom Plugin
+
+You can create your own loader/retriever/LLM:
+
+```js
+// src/plugins/my-custom-llm.js
+export default class MyCustomLLM {
+  ask(prompt) {
+    return `Custom response to: ${prompt}`;
+  }
+}
+```
+
+Then reference it in `.ragrc.json`:
+
+```json
+"llm": {
+  "custom": "./src/plugins/my-custom-llm.js"
+}
+```
+
+---
+
+## 5. Validate Plugin Mocks
+
+Ensure all mocks meet contract interfaces before commit:
+
+```bash
+npm run validate-fixtures
+```
+
+---
+
+## 6. Run All Tests + Coverage
+
+```bash
+npm run ci
+```
+
+This runs:
+
+-  Linting
+-  Fixture validation
+-  Unit/integration tests
+-  Coverage reporting
+
+---
+
+## Next Steps
+
+- Explore `/src/core/plugin-registry.js` for plugin orchestration
+- Browse `/scripts/` for CI and release utilities
+- View `/__tests__/` for end-to-end RAG validation flows
+
+---
+
+Looking to build on top of this? Check out [Use Cases](./Use-Cases.md) for advanced scenarios.

package/docs-site/docs/Usage.md

@@ -4,7 +4,7 @@ This guide covers how to use `@yourorg/rag-pipeline-utils` programmatically via
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @yourorg/rag-pipeline-utils
@@ -12,7 +12,7 @@ npm install @yourorg/rag-pipeline-utils
 
 ---
 
-## 🔧 Programmatic API
+## Programmatic API
 
 Import and instantiate a RAG pipeline:
 
@@ -33,14 +33,14 @@ console.log(answer);
 
 ---
 
-## 🔁 Pipeline Methods
+##  Pipeline Methods
 
 - `pipeline.ingest(path: string)` → Load, chunk, embed, and store vectors
 - `pipeline.query(prompt: string)` → Retrieve context, rerank (optional), and call LLM
 
 ---
 
-## 🧩 Plugin Configuration
+##  Plugin Configuration
 
 You can customize the pipeline by registering plugins:
 
@@ -51,7 +51,7 @@ registry.register('retriever', 'opensearch', new MyOpenSearchRetriever());
 
 ---
 
-## ⚙️ Configuration via `.ragrc.json`
+## Configuration via `.ragrc.json`
 
 Create a JSON file at your root: