@devilsdev/rag-pipeline-utils 1.0.0 → 2.0.0

package/docs-site/docs/Usage.md

@@ -1,72 +1,72 @@
-# Usage
-
-This guide covers how to use `@yourorg/rag-pipeline-utils` programmatically via API and through the CLI.
-
----
-
-## 📦 Installation
-
-```bash
-npm install @yourorg/rag-pipeline-utils
-```
-
----
-
-## 🔧 Programmatic API
-
-Import and instantiate a RAG pipeline:
-
-```js
-import { createRagPipeline } from '@yourorg/rag-pipeline-utils';
-
-const pipeline = createRagPipeline({
-  loader: 'markdown',
-  embedder: 'openai',
-  retriever: 'pinecone',
-  llm: 'openai-gpt-4',
-  useReranker: true
-});
-
-const answer = await pipeline.query("What is retrieval-augmented generation?");
-console.log(answer);
-```
-
----
-
-## 🔁 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
-
-You can customize the pipeline by registering plugins:
-
-```js
-registry.register('loader', 'custom', new MyCustomLoader());
-registry.register('retriever', 'opensearch', new MyOpenSearchRetriever());
-```
-
----
-
-## ⚙️ Configuration via `.ragrc.json`
-
-Create a JSON file at your root:
-
-```json
-{
-  "loader": "directory",
-  "embedder": "openai",
-  "retriever": "pinecone",
-  "llm": "openai-gpt-4",
-  "useReranker": true
-}
-```
-
-Used automatically when no CLI args are passed.
-
----
-
-Next → [CLI](./CLI.md)
+# Usage
+
+This guide covers how to use `@yourorg/rag-pipeline-utils` programmatically via API and through the CLI.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @yourorg/rag-pipeline-utils
+```
+
+---
+
+## 🔧 Programmatic API
+
+Import and instantiate a RAG pipeline:
+
+```js
+import { createRagPipeline } from '@yourorg/rag-pipeline-utils';
+
+const pipeline = createRagPipeline({
+  loader: 'markdown',
+  embedder: 'openai',
+  retriever: 'pinecone',
+  llm: 'openai-gpt-4',
+  useReranker: true
+});
+
+const answer = await pipeline.query("What is retrieval-augmented generation?");
+console.log(answer);
+```
+
+---
+
+## 🔁 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
+
+You can customize the pipeline by registering plugins:
+
+```js
+registry.register('loader', 'custom', new MyCustomLoader());
+registry.register('retriever', 'opensearch', new MyOpenSearchRetriever());
+```
+
+---
+
+## ⚙️ Configuration via `.ragrc.json`
+
+Create a JSON file at your root:
+
+```json
+{
+  "loader": "directory",
+  "embedder": "openai",
+  "retriever": "pinecone",
+  "llm": "openai-gpt-4",
+  "useReranker": true
+}
+```
+
+Used automatically when no CLI args are passed.
+
+---
+
+Next → [CLI](./CLI.md)

package/jest.config.js

@@ -1,14 +1,21 @@
-/**
- * Version: 0.1.0
- * Path: /jest.config.js
- * Description: Jest configuration for native ESM test support
- * Author: Ali Kahwaji
- */
-
-export default {
-    testEnvironment: 'node',
-    transform: {}, // Native ESM — no Babel used
-    roots: ['<rootDir>/__tests__'],
-    verbose: true
-  };
+/**
+ * Version: 0.1.0
+ * Path: /jest.config.js
+ * Description: Jest configuration for native ESM test support
+ * Author: Ali Kahwaji
+ */
+
+// jest.config.js
+
+export default {
+  verbose: true,
+  testEnvironment: 'node',
+  transform: {},
+  collectCoverage: true,
+  coverageDirectory: 'coverage',
+  moduleFileExtensions: ['js', 'json'],
+  testMatch: ['**/__tests__/**/*.test.js'],
+  roots: ['<rootDir>/__tests__'],
+};
+
   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-pipeline-utils",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "A modular toolkit for building RAG (Retrieval-Augmented Generation) pipelines in Node.js",
   "main": "src/core/create-pipeline.js",
   "bin": {
@@ -8,10 +8,22 @@
   },
   "type": "module",
   "scripts": {
-    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "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",
+    "ci": "node scripts/ci-runner.js"
+  },
+  "lint-staged": {
+    "**/*.{js,ts}": [
+      "npm run lint",
+      "npm run validate-fixtures"
+    ]
   },
   "repository": {
     "type": "git",
@@ -37,21 +49,26 @@
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^9.2.6",
     "@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",
     "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/public/src/App.jsx

@@ -1,57 +1,57 @@
-/**
- * Version: 0.1.0
- * Path: /public/src/App.jsx
- * Description: Evaluation results dashboard UI
- * Author: Ali Kahwaji
- */
-
-import { useEffect, useState } from 'react';
-
-export default function App() {
-  const [results, setResults] = useState([]);
-  const [summary, setSummary] = useState({ passRate: 0, avgBLEU: 0, avgROUGE: 0 });
-
-  useEffect(() => {
-    fetch('/results/sample-eval.json')
-      .then(res => res.json())
-      .then(data => {
-        setResults(data);
-
-        const total = data.length;
-        const passCount = data.filter(r => r.success).length;
-        const avgBLEU = data.reduce((s, r) => s + r.scores.bleu, 0) / total;
-        const avgROUGE = data.reduce((s, r) => s + r.scores.rouge, 0) / total;
-
-        setSummary({
-          passRate: (passCount / total * 100).toFixed(1),
-          avgBLEU: avgBLEU.toFixed(2),
-          avgROUGE: avgROUGE.toFixed(2)
-        });
-      });
-  }, []);
-
-  return (
-    <main className="max-w-6xl mx-auto p-6">
-      <h1 className="text-3xl font-bold mb-4">RAG Evaluation Dashboard</h1>
-
-      <div className="mb-6 p-4 border rounded shadow bg-white">
-        <h2 className="text-xl font-semibold mb-2">Summary</h2>
-        <p> Pass Rate: <strong>{summary.passRate}%</strong></p>
-        <p> Avg BLEU: <strong>{summary.avgBLEU}</strong></p>
-        <p> Avg ROUGE: <strong>{summary.avgROUGE}</strong></p>
-      </div>
-
-      {results.map((res, i) => (
-        <div key={i} className="mb-4 p-4 border-l-4 rounded bg-white shadow border-l-gray-300">
-          <h3 className="font-bold text-lg">Prompt {i + 1}</h3>
-          <p className="mt-2"><strong>Prompt:</strong> {res.prompt}</p>
-          <p><strong>Expected:</strong> {res.expected}</p>
-          <p><strong>Actual:</strong> {res.actual}</p>
-          <p> BLEU: <strong>{res.scores.bleu.toFixed(2)}</strong></p>
-          <p> ROUGE: <strong>{res.scores.rouge.toFixed(2)}</strong></p>
-          <p>Pass: <strong className={res.success ? 'text-green-600' : 'text-red-600'}>{res.success ? 'Yes' : 'No'}</strong></p>
-        </div>
-      ))}
-    </main>
-  );
-}
+/**
+ * Version: 0.1.0
+ * Path: /public/src/App.jsx
+ * Description: Evaluation results dashboard UI
+ * Author: Ali Kahwaji
+ */
+
+import { useEffect, useState } from 'react';
+
+export default function App() {
+  const [results, setResults] = useState([]);
+  const [summary, setSummary] = useState({ passRate: 0, avgBLEU: 0, avgROUGE: 0 });
+
+  useEffect(() => {
+    fetch('/results/sample-eval.json')
+      .then(res => res.json())
+      .then(data => {
+        setResults(data);
+
+        const total = data.length;
+        const passCount = data.filter(r => r.success).length;
+        const avgBLEU = data.reduce((s, r) => s + r.scores.bleu, 0) / total;
+        const avgROUGE = data.reduce((s, r) => s + r.scores.rouge, 0) / total;
+
+        setSummary({
+          passRate: (passCount / total * 100).toFixed(1),
+          avgBLEU: avgBLEU.toFixed(2),
+          avgROUGE: avgROUGE.toFixed(2)
+        });
+      });
+  }, []);
+
+  return (
+    <main className="max-w-6xl mx-auto p-6">
+      <h1 className="text-3xl font-bold mb-4">RAG Evaluation Dashboard</h1>
+
+      <div className="mb-6 p-4 border rounded shadow bg-white">
+        <h2 className="text-xl font-semibold mb-2">Summary</h2>
+        <p> Pass Rate: <strong>{summary.passRate}%</strong></p>
+        <p> Avg BLEU: <strong>{summary.avgBLEU}</strong></p>
+        <p> Avg ROUGE: <strong>{summary.avgROUGE}</strong></p>
+      </div>
+
+      {results.map((res, i) => (
+        <div key={i} className="mb-4 p-4 border-l-4 rounded bg-white shadow border-l-gray-300">
+          <h3 className="font-bold text-lg">Prompt {i + 1}</h3>
+          <p className="mt-2"><strong>Prompt:</strong> {res.prompt}</p>
+          <p><strong>Expected:</strong> {res.expected}</p>
+          <p><strong>Actual:</strong> {res.actual}</p>
+          <p> BLEU: <strong>{res.scores.bleu.toFixed(2)}</strong></p>
+          <p> ROUGE: <strong>{res.scores.rouge.toFixed(2)}</strong></p>
+          <p>Pass: <strong className={res.success ? 'text-green-600' : 'text-red-600'}>{res.success ? 'Yes' : 'No'}</strong></p>
+        </div>
+      ))}
+    </main>
+  );
+}

package/release.config.js

@@ -1,23 +1,36 @@
-/**
- * Version: 0.1.0
- * Path: /release.config.js
- * Description: Semantic release configuration for automated changelog, versioning, GitHub and npm publishing
- * Author: Ali Kahwaji
- */
-
-export default {
-  branches: ['main'],
-  plugins: [
-    '@semantic-release/commit-analyzer',
-    '@semantic-release/release-notes-generator',
-    ['@semantic-release/changelog', {
-      changelogFile: 'CHANGELOG.md'
-    }],
-    '@semantic-release/npm',
-    ['@semantic-release/git', {
-      assets: ['CHANGELOG.md', 'package.json'],
-      message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}'
-    }],
-    '@semantic-release/github'
-  ]
-};
+/**
+ * Version: 0.1.0
+ * Description: Semantic Release configuration for CI/CD automation with changelog, versioning, GitHub releases, and npm publishing.
+ * Author: Ali Kahwaji
+ */
+
+export default {
+  branches: ['main'],
+  repositoryUrl: 'https://github.com/DevilsDev/rag-pipeline-utils',
+
+  plugins: [
+    '@semantic-release/commit-analyzer',
+    '@semantic-release/release-notes-generator',
+    [
+      '@semantic-release/changelog',
+      {
+        changelogFile: 'CHANGELOG.md',
+        changelogTitle: '# Changelog',
+      },
+    ],
+    [
+      '@semantic-release/npm',
+      {
+        npmPublish: true,
+      },
+    ],
+    [
+      '@semantic-release/git',
+      {
+        assets: ['package.json', 'package-lock.json', 'CHANGELOG.md'],
+        message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
+      },
+    ],
+    '@semantic-release/github',
+  ],
+};

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');
+})();

package/scripts/repair-fixtures.js

@@ -0,0 +1,30 @@
+/**
+ * Version: 1.0.0
+ * Description: Auto-repairs mock plugin fixtures for integration tests
+ * Author: Ali Kahwaji
+ */
+
+import { mkdirSync, copyFileSync, existsSync } from 'fs';
+import { resolve, join } from 'path';
+
+const MOCKS = [
+  'pdf-loader.js',
+  'openai-embedder.js',
+  'pinecone-retriever.js',
+  'openai-llm.js'
+];
+
+const SRC_FIXTURES = resolve('__tests__/fixtures/src/mocks');
+const DEST_FIXTURES = resolve('__tests__/__temp__/cli-config-fallback/src/mocks');
+
+mkdirSync(DEST_FIXTURES, { recursive: true });
+
+MOCKS.forEach((file) => {
+  const src = join(SRC_FIXTURES, file);
+  const dest = join(DEST_FIXTURES, file);
+  if (!existsSync(src)) throw new Error(`[FIXTURE MISSING] ${src}`);
+  copyFileSync(src, dest);
+  console.log(`[COPIED] ${file}`);
+});
+
+console.log('✅ Fixture mocks successfully repaired.');

package/scripts/setup.js

@@ -0,0 +1,31 @@
+/**
+ * Version: 1.1.0
+ * Description: Test setup script to ensure fixtures exist and validate mocks before running tests.
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+// Resolve __dirname in ES module scope
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const fixturePath = path.resolve(__dirname, '../__tests__/fixtures/sample.pdf');
+
+// Ensure PDF test fixture
+if (!fs.existsSync(fixturePath)) {
+  fs.mkdirSync(path.dirname(fixturePath), { recursive: true });
+  fs.writeFileSync(fixturePath, 'Dummy PDF content for test');
+  console.log('[setup] Created sample.pdf fixture');
+}
+
+// Validate plugin fixture presence
+try {
+  execSync('node ./scripts/verify-fixtures.js', { stdio: 'inherit' });
+} catch (err) {
+  console.error('[setup] Fixture verification failed. Please check missing mocks.');
+  process.exit(1);
+}

package/scripts/test-global-setup.js

@@ -0,0 +1,18 @@
+// __tests__/setup/global.js
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// __dirname polyfill for ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const pdfPath = path.resolve(__dirname, '../fixtures/sample.pdf');
+
+// Ensure the fixtures directory exists
+fs.mkdirSync(path.dirname(pdfPath), { recursive: true });
+
+// Create a minimal valid PDF file if it doesn't exist
+if (!fs.existsSync(pdfPath)) {
+  fs.writeFileSync(pdfPath, '%PDF-1.4\n%EOF');
+}