@devilsdev/rag-pipeline-utils 1.0.1 → 2.0.1

package/bin/cli.js

@@ -1,168 +1,62 @@
-#!/usr/bin/env node
-
 /**
- * Version: 0.1.8
- * Path: /bin/cli.js
- * Description: CLI interface for rag-pipeline utilities with loaders, reranker, and evaluation
+ * Version: 1.1.0
+ * Description: Final CLI entrypoint with dynamic plugin loading and full config validation
  * Author: Ali Kahwaji
  */
 
-import { Command } from 'commander';
-import { createRagPipeline, registry } from '../src/core/create-pipeline.js';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
 import { loadRagConfig } from '../src/config/load-config.js';
-import { logger } from '../src/utils/logger.js';
-import { evaluateRagDataset } from '../src/evaluate/evaluator.js';
-import { LLMReranker } from '../src/reranker/llm-reranker.js';
+import { loadPluginsFromJson } from '../src/config/load-plugin-config.js';
+import registry from '../src/core/plugin-registry.js';
 
-import { MarkdownLoader } from '../src/loader/markdown-loader.js';
-import { HTMLLoader } from '../src/loader/html-loader.js';
-import { CSVLoader } from '../src/loader/csv-loader.js';
-import { DirectoryLoader } from '../src/loader/directory-loader.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = resolve(__filename, '..');
+const CONFIG_PATH = resolve('.ragrc.json');
 
-// Minimal test plugin implementations
-class PDFLoader {
-  async load(filePath) {
-    return [{ chunk: () => [`Test loaded: ${filePath}`] }];
-  }
-}
-class OpenAIEmbedder {
-  async embed(chunks) {
-    return chunks.map((text, i) => ({ id: `v${i}`, values: [0.1, 0.2, 0.3], metadata: { text } }));
-  }
-  async embedQuery(prompt) {
-    return [0.1, 0.2, 0.3];
-  }
-}
-class PineconeRetriever {
-  async store() {}
-  async retrieve() {
-    return [
-      { id: 'a', text: 'Chunk about pine trees', metadata: {} },
-      { id: 'b', text: 'Chunk about vectors', metadata: {} },
-      { id: 'c', text: 'Chunk about databases', metadata: {} }
-    ];
-  }
-}
-class OpenAILLM {
-  async generate(prompt, context) {
-    return `Generated answer using: ${context.map(d => d.text).join(', ')}`;
-  }
-}
+const args = process.argv.slice(2);
+const command = args[0];
 
-// Register mock/default plugins
-registry.register('loader', 'pdf', new PDFLoader());
-registry.register('loader', 'markdown', new MarkdownLoader());
-registry.register('loader', 'html', new HTMLLoader());
-registry.register('loader', 'csv', new CSVLoader());
-registry.register('loader', 'directory', new DirectoryLoader());
-registry.register('embedder', 'openai', new OpenAIEmbedder());
-registry.register('retriever', 'pinecone', new PineconeRetriever());
-registry.register('llm', 'openai-gpt-4', new OpenAILLM());
-
-const program = new Command();
-program
-  .name('rag-pipeline')
-  .description('CLI for RAG pipeline utilities')
-  .version('0.1.8');
-
-function resolveConfig(cliOpts) {
+async function runCLI() {
   try {
-    const fileConfig = loadRagConfig();
-    return { ...fileConfig, ...cliOpts };
+    const config = loadRagConfig(CONFIG_PATH);
+    await loadPluginsFromJson(CONFIG_PATH);
+
+    switch (command) {
+      case 'ingest': {
+        const input = args[1];
+        const loader = registry.get('loader', Object.keys(config.loader)[0]);
+        const embedder = registry.get('embedder', Object.keys(config.embedder)[0]);
+        const retriever = registry.get('retriever', Object.keys(config.retriever)[0]);
+
+        const docs = await loader.load(input);
+        const vectors = await embedder.embed(docs);
+        await retriever.store(vectors, config.namespace);
+
+        console.log('Ingestion complete');
+        break;
+      }
+      case 'query': {
+        const question = args.slice(1).join(' ');
+        const embedder = registry.get('embedder', Object.keys(config.embedder)[0]);
+        const retriever = registry.get('retriever', Object.keys(config.retriever)[0]);
+        const llm = registry.get('llm', Object.keys(config.llm)[0]);
+
+        const queryVec = await embedder.embedQuery(question);
+        const docs = await retriever.search(queryVec, config.namespace);
+        const answer = await llm.ask(question, docs);
+
+        console.log('Answer:', answer);
+        break;
+      }
+      default:
+        console.error('Unknown command:', command);
+        process.exit(1);
+    }
   } catch (err) {
-    logger.warn({ error: err.message }, 'Config file fallback failed');
-    return cliOpts;
+    console.error('Error during execution:', err.message);
+    process.exit(1);
   }
 }
 
-program
-  .command('ingest')
-  .argument('<path>', 'Path to document(s)')
-  .option('--loader <type>', 'Document loader type')
-  .option('--embedder <type>', 'Embedder type')
-  .option('--retriever <type>', 'Vector store retriever type')
-  .action(async (docPath, opts) => {
-    try {
-      const config = resolveConfig(opts);
-      const pipeline = createRagPipeline(config);
-      await pipeline.ingest(docPath);
-      console.log('Ingestion complete'); // required by test assertion
-    } catch (err) {
-      logger.error({ error: err.message }, 'Ingestion failed');
-      console.error('Error during ingestion:', err.message);
-      process.exit(1);
-    }
-  });
-
-program
-  .command('query')
-  .argument('<prompt>', 'Prompt to submit')
-  .option('--embedder <type>', 'Embedder type')
-  .option('--retriever <type>', 'Retriever type')
-  .option('--llm <type>', 'LLM type')
-  .action(async (prompt, opts) => {
-    try {
-      const config = resolveConfig(opts);
-      const pipeline = createRagPipeline(config);
-      const answer = await pipeline.query(prompt);
-      console.log('\n Answer:\n', answer);
-    } catch (err) {
-      logger.error({ error: err.message }, 'Query failed');
-      process.exit(1);
-    }
-  });
-
-program
-  .command('evaluate')
-  .argument('<dataset>', 'Path to JSON file of evaluation cases')
-  .option('--embedder <type>', 'Embedder type')
-  .option('--retriever <type>', 'Retriever type')
-  .option('--llm <type>', 'LLM type')
-  .action(async (dataset, opts) => {
-    try {
-      const config = resolveConfig(opts);
-      const results = await evaluateRagDataset(dataset, config);
-      const passRate = results.filter(r => r.success).length / results.length;
-      const avgBLEU = results.reduce((sum, r) => sum + r.scores.bleu, 0) / results.length;
-      const avgROUGE = results.reduce((sum, r) => sum + r.scores.rouge, 0) / results.length;
-
-      results.forEach((r, i) => {
-        console.log(`\nCase ${i + 1}:\nPrompt: ${r.prompt}\nPass: ${r.success}\nBLEU: ${r.scores.bleu.toFixed(2)}\nROUGE: ${r.scores.rouge.toFixed(2)}`);
-      });
-
-      console.log(`\n Summary:\nPassed: ${Math.round(passRate * 100)}%\nAvg BLEU: ${avgBLEU.toFixed(2)}\nAvg ROUGE: ${avgROUGE.toFixed(2)}`);
-    } catch (err) {
-      logger.error({ error: err.message }, 'Evaluation failed');
-      process.exit(1);
-    }
-  });
-
-program
-  .command('rerank')
-  .argument('<prompt>', 'Prompt to rerank context for')
-  .option('--retriever <type>', 'Retriever type')
-  .option('--llm <type>', 'LLM type')
-  .action(async (prompt, opts) => {
-    try {
-      const config = resolveConfig(opts);
-      const retriever = registry.get('retriever', config.retriever);
-      const llm = registry.get('llm', config.llm);
-      const embedder = registry.get('embedder', config.embedder);
-
-      const queryVector = await embedder.embedQuery(prompt);
-      const docs = await retriever.retrieve(queryVector);
-
-      const reranker = new LLMReranker({ llm });
-      const reranked = await reranker.rerank(prompt, docs);
-
-      console.log('\n Reranked Results:');
-      reranked.forEach((doc, i) => {
-        console.log(`\n#${i + 1}: ${doc.text}`);
-      });
-    } catch (err) {
-      logger.error({ error: err.message }, 'Rerank failed');
-      process.exit(1);
-    }
-  });
-
-program.parse();
+await runCLI();

package/docs-site/blog/2021-08-26-welcome/index.md

@@ -1,7 +1,6 @@
 ---
 slug: welcome
 title: Welcome
-authors: [slorber, yangshun]
 tags: [facebook, hello, docusaurus]
 ---
 

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-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/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 of RAG Pipeline Utils
+  url: https://github.com/DevilsDev
+  image_url: /img/authors/ali.jpg

package/docs-site/blog/tags.yml

@@ -17,3 +17,12 @@ hola:
   label: Hola
   permalink: /hola
   description: Hola tag description
+
+release:
+  label: Release
+  permalink: /blog/tags/release
+
+changelog:
+  label: Changelog
+  permalink: /blog/tags/changelog
+

package/docs-site/docusaurus.config.js

@@ -18,6 +18,13 @@ export default {
   // ✅ Final favicon and social card for branding
   favicon: 'img/favicon.ico',
   themeConfig: {
+    
+    // algolia: {
+    //   appId: 'YOUR_APP_ID',
+    //   apiKey: 'YOUR_PUBLIC_API_KEY',
+    //   indexName: 'rag_pipeline_utils',
+    //   contextualSearch: true,
+    // },
     image: 'img/social-card.jpg',
     navbar: {
       title: 'RAG Utils',
@@ -48,6 +55,12 @@ export default {
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl: 'https://github.com/DevilsDev/rag-pipeline-utils/edit/main/docs-site/'
         },
+
+        blog: {
+          showReadingTime: true,
+          editUrl: 'https://github.com/DevilsDev/rag-pipeline-utils/edit/main/docs-site/blog/',
+        },
+        
         theme: {
           customCss: require.resolve('./src/css/custom.css')
         }

package/docs-site/sidebars.js

@@ -2,21 +2,33 @@
 
 /**
  * Sidebar configuration for RAG Pipeline Utils documentation site
- * Generated manually for ordered navigation
+ * Version: 2.0.0
  * Author: Ali Kahwaji
+ * Updated: Structured for modular clarity and DX
  * @type {import('@docusaurus/plugin-content-docs').SidebarsConfig}
  */
 
 const sidebars = {
   tutorialSidebar: [
-    'Introduction',
-    'Usage',
-    'CLI',
-    'Architecture',
-    'Evaluation',
-    'Plugins',
-    'FAQ'
-  ]
+    {
+      type: 'category',
+      label: 'Overview',
+      collapsed: false,
+      items: ['Introduction', 'Architecture', 'USE_CASES'],
+    },
+    {
+      type: 'category',
+      label: 'Developer Guide',
+      collapsed: false,
+      items: ['Usage', 'CLI', 'Plugins'],
+    },
+    {
+      type: 'category',
+      label: 'Advanced',
+      collapsed: true,
+      items: ['Evaluation', 'FAQ'],
+    },
+  ],
 };
 
 export default sidebars;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-pipeline-utils",
-  "version": "1.0.1",
+  "version": "2.0.1",
   "description": "A modular toolkit for building RAG (Retrieval-Augmented Generation) pipelines in Node.js",
   "main": "src/core/create-pipeline.js",
   "bin": {
@@ -8,10 +8,27 @@
   },
   "type": "module",
   "scripts": {
+    "validate-fixtures": "node ./scripts/verify-fixtures.js",
+    "setup": "node ./scripts/setup.js",
     "test": "node ./scripts/setup.js && cross-env NODE_OPTIONS=--experimental-vm-modules jest --coverage",
     "test:watch": "jest --watch",
     "lint": "eslint .",
-    "prepare": "husky install"
+    "prepare": "husky install",
+    "lint-staged": "lint-staged",
+    "postinstall": "husky install",
+    "verify:mocks": "node scripts/verify-fixture-mocks.js",
+    "build:docs": "npx docusaurus build docs-site",
+    "ci": "node scripts/ci-runner.js",
+    "docs:dev": "npx docusaurus start docs-site",
+    "docs:build": "npx docusaurus build docs-site",
+    "docs:deploy": "npx docusaurus deploy docs-site",
+    "docs:version": "npx docusaurus docs:version"
+  },
+  "lint-staged": {
+    "**/*.{js,ts}": [
+      "npm run lint",
+      "npm run validate-fixtures"
+    ]
   },
   "repository": {
     "type": "git",
@@ -36,6 +53,8 @@
     "access": "public"
   },
   "devDependencies": {
+    "@docusaurus/core": "^3.7.0",
+    "@docusaurus/preset-classic": "^3.7.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
@@ -43,17 +62,21 @@
     "@semantic-release/npm": "^11.0.3",
     "@semantic-release/release-notes-generator": "^14.0.3",
     "@types/jest": "^29.5.14",
+    "codecov": "^3.8.2",
     "cross-env": "^7.0.3",
+    "docusaurus": "^1.14.7",
     "esbuild": "^0.25.2",
     "eslint": "^8.57.1",
     "husky": "^8.0.3",
     "jest": "^29.7.0",
+    "lint-staged": "^15.5.1",
     "prettier": "^3.5.3",
     "rimraf": "^6.0.1",
     "semantic-release": "^21.1.2",
     "ts-jest": "^29.3.2"
   },
   "dependencies": {
+    "ajv": "^8.17.1",
     "axios": "^1.8.4",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",

package/plugin.config.json

@@ -0,0 +1,14 @@
+{
+  "loader": {
+    "pdf": "./src/mocks/pdf-loader.js"
+  },
+  "embedder": {
+    "openai": "./src/mocks/openai-embedder.js"
+  },
+  "retriever": {
+    "pinecone": "./src/mocks/pinecone-retriever.js"
+  },
+  "llm": {
+    "openai-gpt-4": "./src/mocks/openai-llm.js"
+  }
+}

package/scripts/banner-injector.js

@@ -0,0 +1,89 @@
+/**
+ * File: scripts/banner-injector.js
+ * Description: Script to programmatically inject file-level banners into specified project files
+ * Author: Ali Kahwaji
+ * Version: 1.0.0
+ */
+
+import fs from 'fs';
+import path from 'path';
+import glob from 'glob';
+
+const banners = {
+  '__tests__/unit/reranker/llm-reranker.test.js': `/**
+ * File: __tests__/unit/reranker/llm-reranker.test.js
+ * Description: Unit and integration tests with mocks for RAG pipeline
+ * Author: Ali Kahwaji
+ * Version: 1.0.4
+ */\n\n`,
+
+  '__tests__/unit/reranker/reranker.snapshot.test.js': `/**
+ * File: __tests__/unit/reranker/reranker.snapshot.test.js
+ * Description: Snapshot tests for LLM reranker
+ * Author: Ali Kahwaji
+ * Version: 1.0.4
+ */\n\n`,
+
+  '__tests__/unit/core/plugin-registry.test.js': `/**
+ * File: __tests__/unit/core/plugin-registry.test.js
+ * Description: Unit and integration tests with mocks for RAG pipeline
+ * Author: Ali Kahwaji
+ * Version: 1.0.4
+ */\n\n`,
+
+  '__tests__/integration/config/load-config.test.js': `/**
+ * File: __tests__/integration/config/load-config.test.js
+ * Description: Unit and integration tests with mocks for RAG pipeline
+ * Author: Ali Kahwaji
+ * Version: 1.0.4
+ */\n\n`,
+
+  '__tests__/integration/cli/config-flow.test.js': `/**
+ * File: __tests__/integration/cli/config-flow.test.js
+ * Description: Unit and integration tests with mocks for RAG pipeline
+ * Author: Ali Kahwaji
+ * Version: 1.0.4
+ */\n\n`,
+
+  'src/mocks/pdf-loader.js': `/**
+ * File: src/mocks/pdf-loader.js
+ * Description: Unit and integration tests with mocks for RAG pipeline
+ * Author: Ali Kahwaji
+ * Version: 1.0.4
+ */\n\n`,
+
+  'src/mocks/openai-embedder.js': `/**
+ * File: src/mocks/openai-embedder.js
+ * Description: Unit and integration tests with mocks for RAG pipeline
+ * Author: Ali Kahwaji
+ * Version: 1.0.4
+ */\n\n`,
+
+  'src/mocks/pinecone-retriever.js': `/**
+ * File: src/mocks/pinecone-retriever.js
+ * Description: Unit and integration tests with mocks for RAG pipeline
+ * Author: Ali Kahwaji
+ * Version: 1.0.4
+ */\n\n`
+};
+
+Object.entries(banners).forEach(([filePath, banner]) => {
+  const resolvedPath = path.resolve(filePath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    console.warn(`[SKIPPED] ${filePath} does not exist.`);
+    return;
+  }
+
+  const originalContent = fs.readFileSync(resolvedPath, 'utf-8');
+
+  // Skip if banner already present
+  if (originalContent.startsWith('/**')) {
+    console.log(`[SKIPPED] ${filePath} already contains a banner.`);
+    return;
+  }
+
+  const newContent = banner + originalContent;
+  fs.writeFileSync(resolvedPath, newContent, 'utf-8');
+  console.log(`[INJECTED] Banner added to ${filePath}`);
+});

package/scripts/ci-runner.js

@@ -0,0 +1,51 @@
+/**
+ * Version: 1.1.0
+ * Description: CI runner for linting, mock validation, testing and coverage
+ * Author: Ali Kahwaji
+ * File: scripts/ci-runner.js
+ */
+
+import { execSync } from 'child_process';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import fs from 'fs';
+
+// Entry helpers
+const ROOT = path.resolve();
+const resolveScript = (relPath) => pathToFileURL(path.resolve(ROOT, relPath)).href;
+
+const run = (label, command) => {
+  console.log(`\n🔧 Running: ${label}`);
+  try {
+    execSync(command, { stdio: 'inherit', cwd: ROOT });
+    console.log(`✅ ${label} passed`);
+  } catch (err) {
+    console.error(`❌ ${label} failed`);
+    process.exit(1);
+  }
+};
+
+const runDynamicModule = async (label, modulePath) => {
+  console.log(`\n🔍 Validating: ${label}`);
+  try {
+    const mod = await import(resolveScript(modulePath));
+    if (typeof mod.default === 'function') await mod.default();
+    console.log(`✅ ${label} passed`);
+  } catch (err) {
+    console.error(`❌ ${label} failed:\n${err.message}`);
+    process.exit(1);
+  }
+};
+
+(async () => {
+  // Step 1: Lint
+  run('Lint', 'npx eslint . --ext .js,.ts');
+
+  // Step 2: Verify mocks for required interface methods
+  await runDynamicModule('Fixture Mock Interface Validation', 'scripts/verify-fixture-mocks.js');
+
+  // Step 3: Test and coverage
+  run('Unit + Integration Tests w/ Coverage', 'cross-env NODE_OPTIONS=--experimental-vm-modules jest --coverage');
+
+  console.log('\n🎉 CI runner completed successfully.\n');
+})();