@devilsdev/rag-pipeline-utils 1.0.1 → 2.0.1

package/.codecov.yml

@@ -0,0 +1,21 @@
+# .codecov.yml
+
+codecov:
+  notify:
+    after_n_builds: 1
+
+coverage:
+  status:
+    project:
+      default:
+        target: 90%
+        threshold: 5%
+    patch:
+      default:
+        target: 90%
+        threshold: 5%
+
+comment:
+  layout: "reach, diff, flags, files"
+  behavior: default
+  require_changes: false

package/.github/workflows/ci.yml

@@ -44,3 +44,21 @@ jobs:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # 👈 critical for npm publi
         run: npx semantic-release
+
+      - name: 🧪 Run Tests with Coverage
+        run: npm test
+
+      - name: Validate Fixtures
+        run: npm run validate-fixtures
+      
+      - name: Lint code
+        run: npm run lint
+      
+      
+      - name: 📊 Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: DevilsDev/rag-pipeline-utils
+
+      

package/.github/workflows/docs-deploy.yml

@@ -0,0 +1,36 @@
+name: Deploy Docusaurus to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+                - 'docs-site/**'
+                - 'blog/**'
+                - 'sidebars.js'
+                - 'docusaurus.config.js'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v4
+
+      - name: ⚙️ Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: 🛠️ Build static site
+        run: npm run build:docs
+
+      - name: 🚀 Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs-site/build
+              
+          

package/.github/workflows/publish-release-blog.yml

@@ -0,0 +1,51 @@
+# .github/workflows/publish-release-blog.yml
+# Version: 1.0.0
+# Description: Auto-publish blog post from CHANGELOG or prepared .md after NPM release
+# Author: Ali Kahwaji
+
+name: ✨ Publish Release Blog Post
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-blog-post:
+    name: Generate & Commit Blog Post
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: ⬇️ Checkout code
+        uses: actions/checkout@v4
+
+      - name: 🔧 Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: ✏️ Generate blog post
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/}
+          DATE=$(date +'%Y-%m-%d')
+          FILE="docs-site/blog/${DATE}-release-${VERSION}.md"
+
+          echo "---" > $FILE
+          echo "slug: release-${VERSION}" >> $FILE
+          echo "title: ✨ Version ${VERSION} Released" >> $FILE
+          echo "authors: [ali]" >> $FILE
+          echo "tags: [release, changelog]" >> $FILE
+          echo "---" >> $FILE
+          echo >> $FILE
+
+          echo "RAG Pipeline Utils v${VERSION} is now available on NPM!" >> $FILE
+          echo >> $FILE
+          echo "#### Highlights" >> $FILE
+          echo "- Automated blog generation on GitHub releases" >> $FILE
+          echo "- Version bump: ${VERSION}" >> $FILE
+          echo "- Ensure CHANGELOG.md is synced" >> $FILE
+
+      - name: 📋 Commit blog post
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs(blog): add release post for ${{ github.ref_name }}"
+          file_pattern: "docs-site/blog/*.md"

package/.husky/pre-commit

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run validate-fixtures && npm run lint
+npx lint-staged
+node scripts/validate-changelog-version.js

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [2.0.1](https://github.com/DevilsDev/rag-pipeline-utils/compare/v2.0.0...v2.0.1) (2025-04-17)
+
+
+### Bug Fixes
+
+* add @docusaurus/preset-classic to enable CI builds ([ed5e771](https://github.com/DevilsDev/rag-pipeline-utils/commit/ed5e771f919face4693a6a7abfed4cf0fe1325ca))
+
+## [2.0.0] - 2025-04-17 (2025-04-17)
+
+
+### Bug Fixes
+
+* **ci:** correct .ragrc.json plugin paths and CLI test cwd to resolve plugin loading in CI ([911c23b](https://github.com/DevilsDev/rag-pipeline-utils/commit/911c23b1d3ddb9e2d938b37f4422a5d81995e97f))
+* **ci:** resolve plugin path error in .ragrc.json for GitHub Actions compatibility ([affc739](https://github.com/DevilsDev/rag-pipeline-utils/commit/affc739d5c4ff2070b1a1ca0ccf3f9137d6cee5a))
+* **ci:** resolve plugin path failures in .ragrc.json during CLI integration tests ([04b977b](https://github.com/DevilsDev/rag-pipeline-utils/commit/04b977b3b745fa3d3ab47c84b2aeee3285896068))
+* **cli:** correct path to load-plugin-config.js after moving to /src/config ([f743498](https://github.com/DevilsDev/rag-pipeline-utils/commit/f743498ec32e03151eda9ba7fe5886bda8da792f))
+* **config:** use default export when importing plugin registry ([ef8dce1](https://github.com/DevilsDev/rag-pipeline-utils/commit/ef8dce12bfab62bc9faec764198b98c0c356472e))
+* **test:** ensure .ragrc.json copied to project root for CLI fallback in CI ([31bd2b8](https://github.com/DevilsDev/rag-pipeline-utils/commit/31bd2b844279fb0404056d9929e5f28f9127eb12))
+* **tests:** define __dirname manually for ESM compatibility in CLI integration test ([18b8dad](https://github.com/DevilsDev/rag-pipeline-utils/commit/18b8dadabb852243dda2b78de048c71106a759fc))
+
+
+### Features
+
+* **ci:** integrate full fixture validation, schema contracts, and CLI test flow ([2b57fe9](https://github.com/DevilsDev/rag-pipeline-utils/commit/2b57fe90e64a806815c1f66f5e2a745780270ce6))
+* **cli:** dynamic plugin registration with config fallback and middleware injection ([cc24b7e](https://github.com/DevilsDev/rag-pipeline-utils/commit/cc24b7e74d0a2630eb1c6d2def69b370329dcc2b))
+* **plugins:** enable dynamic plugin registration from JSON config ([d81d6d7](https://github.com/DevilsDev/rag-pipeline-utils/commit/d81d6d7d5f2d21b5a46b379b530c162ba9c30398))
+* **testing:** integrate full fixture and validation setup for CLI + reranker ([ab96037](https://github.com/DevilsDev/rag-pipeline-utils/commit/ab9603765594e7718e2688b80797e1f5e8afe86f))
+
+
+### BREAKING CHANGES
+
+* **cli:**  now requires named options for middleware injection; existing usage must be updated.
+
+## [1.0.2] - 2025-04-15
+### Fixed
+- Corrected plugin path resolution in `.ragrc.json` fixture for CI compatibility.
+- Resolved `ERR_MODULE_NOT_FOUND` during CLI integration tests in GitHub Actions.
+- Ensured consistent module resolution across environments (Windows, Linux, CI).
+
+
 ## [1.0.1](https://github.com/DevilsDev/rag-pipeline-utils/compare/v1.0.0...v1.0.1) (2025-04-14)
 
 

package/README.md

@@ -1,117 +1,146 @@
 # @DevilsDev/rag-pipeline-utils
 
+
+
+# RAG Pipeline Utils
+
+> Modular utilities for building Retrieval-Augmented Generation (RAG) pipelines, with CI-verified plugin contracts and mockable interfaces.
+
 [![CI](https://github.com/DevilsDev/rag-pipeline-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/DevilsDev/rag-pipeline-utils/actions)
 [![codecov](https://codecov.io/gh/DevilsDev/rag-pipeline-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/DevilsDev/rag-pipeline-utils)
 ![Release](https://img.shields.io/github/v/release/DevilsDev/rag-pipeline-utils?label=release)
+![License](https://img.shields.io/github/license/devilsdev/rag-pipeline-utils)
 
-**A modular Node.js toolkit for building RAG (Retrieval-Augmented Generation) pipelines with clean abstractions, pluggable components, and scalable architecture.**
+## Description
 
----
+`@devilsdev/rag-pipeline-utils` provides a clean, extensible, and test-friendly foundation for constructing robust RAG pipelines using a plugin-based architecture. It enables developers to plug in their own document loaders, embedders, retrievers, and LLMs via configuration, and includes a CLI, mock contract verification, schema validation, and test harnesses to ensure production-readiness.
 
-## Features
+## Key Features
 
-- ✅ Plugin-based architecture for RAG pipelines
-- ✅ Embedding + retrieval abstraction
-- ✅ Vector DB integrations (e.g., Pinecone)
-- ✅ Modular document loaders (PDF, HTML, Markdown, CSV, Directory)
-- ✅ CLI with `.ragrc.json` config fallback
-- ✅ Retry, backoff, and logging built-in
-- ✅ Reranker support and evaluation tooling
-- ✅ React dashboard for evaluation results
+- **Plugin Contracts**: Runtime and CI verification of plugin interfaces (loader, embedder, retriever, llm).
+- **CLI Support**: Easily run `ingest` and `query` commands using `.ragrc.json` configuration.
+- **Test Fixtures**: Snapshot, fallback, and structured reranker validation.
+- **Schema Enforcement**: `.ragrc.json` schema validation to catch config issues early.
+- **Mock Repair Utilities**: Auto-fix for missing or broken mock implementations.
+- **Modular Design**: Drop-in plugin support using custom class-based implementations.
 
----
+## Benefits of This Modular Design
+
+- **Extensibility**: Developers can inject their own loader, retriever, or LLM logic without modifying the core.
+- **Testability**: Mocks and CI tools validate contract adherence for reliable test coverage.
+- **Decoupling**: Each plugin can be independently implemented and swapped in via `.ragrc.json`.
+- **CI Resilience**: The CI pipeline includes linting, contract verification, and test coverage enforcement.
 
 ## Installation
 
 ```bash
-npm install @yourorg/rag-pipeline-utils
+npm install @devilsdev/rag-pipeline-utils
 ```
 
----
+## Basic Usage
 
-## Usage
+1. Create a `.ragrc.json` config:
 
-```js
-import { createRagPipeline } from '@yourorg/rag-pipeline-utils';
+```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": "demo-namespace",
+  "pipeline": ["loader", "embedder", "retriever"]
+}
+```
 
-const rag = createRagPipeline({
-  loader: 'markdown',
-  embedder: 'openai',
-  retriever: 'pinecone',
-  llm: 'openai-gpt-4',
-  useReranker: true
-});
+2. Run an ingestion:
 
-const answer = await rag.query('What is a vector database?');
-console.log(answer);
+```bash
+node bin/cli.js ingest ./docs/sample.pdf
 ```
 
----
-
-## Testing
+3. Run a query:
 
 ```bash
-npm test
+node bin/cli.js query "What is in the document?"
 ```
 
----
+## Plugin Contracts
+
+Each plugin must implement the following interface:
+
+| Type      | Required Methods                            |
+| --------- | ------------------------------------------- |
+| loader    | `load(filePath)`                          |
+| embedder  | `embed(documents)`, `embedQuery(query)` |
+| retriever | `store(vectors)`, `search(queryVector)` |
+| llm       | `ask(prompt)`                             |
+
+## Folder Structure
+
+```text
+/project-root
+├── /src
+│   ├── /routes
+│   ├── /services
+│   ├── /utils
+│   └── app.js
+├── /scripts
+│   ├── setup.js
+│   ├── ci-runner.js
+│   └── repair-fixtures.js
+├── /__tests__
+│   ├── /fixtures
+│   ├── /unit
+│   ├── /integration
+├── /public
+├── README.md
+├── USE_CASES.md
+├── CHANGELOG.md
+└── .env.example
+```
 
-## CLI
 
-```bash
-rag-pipeline ingest ./docs/my.pdf --loader pdf
-rag-pipeline query "Explain RAG pipelines" --llm openai-gpt-4
-rag-pipeline evaluate ./fixtures/sample-eval-dataset.json
-rag-pipeline rerank "Explain embeddings" --retriever pinecone
-```
 
-Supports `.ragrc.json` fallback configuration:
+## Why Use This?
 
-```json
-{
-  "loader": "directory",
-  "embedder": "openai",
-  "retriever": "pinecone",
-  "llm": "openai-gpt-4",
-  "useReranker": true
-}
-```
+- **Developer Experience**: Fast iteration, full contract CI
+- **Pluggable Design**: Swap in your stack (OpenAI, Pinecone, Langchain, etc.)
+- **Minimal & Modular**: Clean separation of concerns
+- **Prod-ready**: 100% test coverage, schema validation, CLI control
 
----
 
-## Project Structure
 
-```
-/src
-  ├── core/           # Pipeline + registry
-  ├── loader/         # Loaders for md, html, csv, dir
-  ├── reranker/       # LLM-based context reranker
-  ├── evaluate/       # Scoring, batch QA evaluation
-  ├── utils/          # Logger, retry, schema
-/bin/cli.js           # CLI entrypoint
-/__tests__/           # Unit, integration, snapshot tests
-/public/              # Evaluation dashboard (React)
-.github/workflows/ci.yml # CI config
-```
+## Use Cases
 
----
+Explore real-world DevX-focused examples in [USE_CASES.md](./USE_CASES.md), including:
 
-## Evaluation Dashboard
+- Mock-driven plugin TDD
+- CI-based interface validation
+- Multivendor ingestion and search
+- Runtime swap of LLM, retrievers, or embedders
+- Bootstrap pipelines with auto-repairable defaults
 
-```bash
-node server.js
-```
 
-Visit: [http://localhost:3000](http://localhost:3000) → Visualizes metrics, BLEU/ROUGE, pass rate.
 
----
+## Contributing
+
+We welcome contributions via PRs, especially new mock providers, validation helpers, and runtime extensions. Please follow the test + CI conventions before submitting.
+
+
 
 ## License
 
-Apache-2.0
+This project is licensed under the **GNU GPL v3.0** License - see the [LICENSE](./LICENSE) file for details.
 
 ---
 
-## 👤 Author
+Built with ❤️ by [Ali Kahwaji].
 
-Ali Kahwaji — [@DevilsDev](https://github.com/DevilsDev)

package/USE_CASES.md

@@ -0,0 +1,134 @@
+# RAG Pipeline Utils — Developer-Focused Use Cases
+
+> Modular, composable, and CI-verified RAG orchestration for modern AI applications.
+
+---
+
+##  Use Case 1: Pluggable Local RAG Stack for Prototyping
+
+**Problem:** Traditional RAG tools force tight vendor dependencies.
+
+**Solution:** Use mockable local plugin implementations to simulate loaders, embedders, retrievers, and LLMs.
+
+```bash
+npm install @devilsdev/rag-pipeline-utils
+```
+
+```js
+// cli.js or app.js
+import { PluginRegistry } from './src/core/plugin-registry.js';
+import { loadRagConfig } from './src/config/load-config.js';
+
+const config = loadRagConfig('.ragrc.json');
+const loader = PluginRegistry.getPlugin('loader', 'pdf');
+const docs = loader.load('./test.pdf');
+```
+
+**Benefits**
+- Local plugin mocks with expected method contracts
+- Reusable plugin templates (`pdf-loader.js`, `openai-embedder.js`)
+- Dev-first DX: debug, snapshot, iterate without cloud costs
+
+---
+
+##  Use Case 2: Declarative CLI RAG Pipelines (CI-Ready)
+
+**Problem:** Hardcoded pipeline steps can't be validated or changed by non-engineers.
+
+**Solution:** Define `.ragrc.json` once and reuse across environments.
+
+```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-poc",
+  "pipeline": ["loader", "embedder", "retriever"]
+}
+```
+
+```bash
+node ./bin/cli.js ingest ./docs/whitepaper.pdf
+node ./bin/cli.js query "What’s the goal of this architecture?"
+```
+
+**Benefits**
+- Teams can standardize pipelines in source control
+- Tests fail fast if structure or mocks drift
+- Non-devs can operate pipelines via CLI
+
+---
+
+## Use Case 3: Mock-First TDD for Plugin Development
+
+**Problem:** LLM, vector, and loader logic are often developed without tests.
+
+**Solution:** Define contract-compliant mocks and CI-validate their structure before connecting to APIs.
+
+```js
+export default class CustomEmbedder {
+  embed(docs) { return docs.map(...); }
+  embedQuery(q) { return [...]; }
+}
+```
+
+Run full contract verification:
+
+```bash
+npm run ci
+```
+
+**Benefits**
+- Every plugin is CI-verified for method presence
+- Shared contracts enforce required interfaces
+- Onboarding new devs? Just follow `pluginContracts.js`
+
+---
+
+##  Use Case 4: Vendor-Neutral AI Data Pipelines
+
+**Problem:** Every RAG stack is locked to OpenAI + Pinecone + Langchain.
+
+**Solution:** Use this project to mix, match, or mock vector/LLM pairs:
+
+```js
+"retriever": { "localstore": "./src/plugins/local-retriever.js" },
+"llm": { "cohere": "./src/plugins/cohere-llm.js" }
+```
+
+**Benefits**
+- Run multiple RAG pipelines in parallel (A/B testing, evals)
+- Lower infra cost with offline/local plugin support
+- Integrate with tools outside Langchain ecosystem
+
+---
+
+## 🛠 Use Case 5: Plugin Engineering with Guardrails
+
+**Problem:** Complex plugin systems break silently.
+
+**Solution:** This framework has:
+- Plugin method contract enforcement
+- CLI test runner (`scripts/ci-runner.js`)
+- Auto repair tool (`scripts/repair-fixtures.js`)
+
+**DX Boost**
+- One-line plugin repairs
+- Validated schema structure
+- Aligned to real-world developer workflows
+
+---
+
+## Cross References
+
+- [README](./README.md) — Project overview, architecture, CLI and configuration details
+- [pluginContracts.js](./src/core/plugin-contracts.js) — Interface contracts for loader, embedder, retriever, LLM
+- [diagnostic-reporter.js](./src/utils/ci/diagnostic-reporter.js) — CI error helper
+- [repair-fixtures.js](./scripts/repair-fixtures.js) — Auto-regeneration of mocks
+
+---
+
+## License
+
+Licensed under the **GPL-3.0 License** — see [LICENSE](./LICENSE) for full terms.

package/__tests__/fixtures/.ragrc.json

@@ -0,0 +1,8 @@
+{
+  "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": "cli-config-test",
+  "pipeline": ["loader", "embedder", "retriever"]
+}

package/__tests__/fixtures/invalid-ragrc.json

@@ -0,0 +1,4 @@
+{
+  "loader": "./src/mocks/pdf-loader.js",
+  "namespace": 12345
+}

package/__tests__/fixtures/src/mocks/openai-embedder.js

@@ -0,0 +1,16 @@
+/**
+ * Mock OpenAI Embedder Plugin
+ * Implements: embedder.embed(docs), embedder.embedQuery(query)
+ */
+export default class OpenAIEmbedder {
+  embed(documents) {
+    return documents.map(doc => ({
+      id: doc.id,
+      values: [0.1, 0.2, 0.3],
+    }));
+  }
+
+  embedQuery(query) {
+    return [0.1, 0.2, 0.3];
+  }
+}

package/__tests__/fixtures/src/mocks/openai-llm.js

@@ -0,0 +1,9 @@
+/**
+ * Mock OpenAI LLM Plugin
+ * Implements: llm.ask(prompt)
+ */
+export default class OpenAILLM {
+  ask(prompt) {
+    return `Answer: Mocked response to "${prompt}"`;
+  }
+}

package/__tests__/fixtures/src/mocks/pdf-loader.js

@@ -0,0 +1,17 @@
+/**
+ * Mock PDF Loader Plugin
+ * Implements: loader.load(filePath)
+ */
+export default class PdfLoader {
+  /**
+   * Loads a file and returns mock document chunks.
+   * @param {string} filePath
+   * @returns {Array<{ id: string, content: string }>}
+   */
+  load(filePath) {
+    return [
+      { id: 'doc1', content: `Loaded content from ${filePath}` },
+      { id: 'doc2', content: 'Second document content' },
+    ];
+  }
+}

package/__tests__/fixtures/src/mocks/pinecone-retriever.js

@@ -0,0 +1,26 @@
+/**
+ * Mock Pinecone Retriever Plugin
+ * Implements: retriever.store(vectors), retriever.search(queryVector)
+ */
+export default class PineconeRetriever {
+  constructor() {
+    this._store = [];
+  }
+
+  /**
+   * Stores embedded vectors.
+   * @param {Array<{ id: string, values: number[] }>} vectors
+   */
+  store(vectors) {
+    this._store = vectors;
+  }
+
+  /**
+   * Searches mock memory and returns matching docs.
+   * @param {number[]} queryVector
+   * @returns {Array<{ id: string, score: number }>}
+   */
+  search(queryVector) {
+    return this._store.map(v => ({ id: v.id, score: 0.99 }));
+  }
+}

package/__tests__/fixtures/valid-ragrc.json

@@ -0,0 +1,16 @@
+{
+  "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": "cli-config-test",
+  "pipeline": ["loader", "embedder", "retriever"]
+}