@devilsdev/rag-pipeline-utils 1.0.0 → 2.0.0

package/README.md

@@ -1,116 +1,117 @@
-# @DevilsDev/rag-pipeline-utils
-
-[![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)
-
-**A modular Node.js toolkit for building RAG (Retrieval-Augmented Generation) pipelines with clean abstractions, pluggable components, and scalable architecture.**
-
----
-
-## 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
-
----
-
-## Installation
-
-```bash
-npm install @yourorg/rag-pipeline-utils
-```
-
----
-
-## Usage
-
-```js
-import { createRagPipeline } from '@yourorg/rag-pipeline-utils';
-
-const rag = createRagPipeline({
-  loader: 'markdown',
-  embedder: 'openai',
-  retriever: 'pinecone',
-  llm: 'openai-gpt-4',
-  useReranker: true
-});
-
-const answer = await rag.query('What is a vector database?');
-console.log(answer);
-```
-
----
-
-## Testing
-
-```bash
-npm test
-```
-
----
-
-## 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:
-
-```json
-{
-  "loader": "directory",
-  "embedder": "openai",
-  "retriever": "pinecone",
-  "llm": "openai-gpt-4",
-  "useReranker": true
-}
-```
-
----
-
-## 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
-```
-
----
-
-## Evaluation Dashboard
-
-```bash
-node server.js
-```
-
-Visit: [http://localhost:3000](http://localhost:3000) → Visualizes metrics, BLEU/ROUGE, pass rate.
-
----
-
-## License
-
-Apache-2.0
-
----
-
-## 👤 Author
-
-Ali Kahwaji — [@DevilsDev](https://github.com/DevilsDev)
+# @DevilsDev/rag-pipeline-utils
+
+[![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)
+
+**A modular Node.js toolkit for building RAG (Retrieval-Augmented Generation) pipelines with clean abstractions, pluggable components, and scalable architecture.**
+
+---
+
+## 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
+
+---
+
+## Installation
+
+```bash
+npm install @yourorg/rag-pipeline-utils
+```
+
+---
+
+## Usage
+
+```js
+import { createRagPipeline } from '@yourorg/rag-pipeline-utils';
+
+const rag = createRagPipeline({
+  loader: 'markdown',
+  embedder: 'openai',
+  retriever: 'pinecone',
+  llm: 'openai-gpt-4',
+  useReranker: true
+});
+
+const answer = await rag.query('What is a vector database?');
+console.log(answer);
+```
+
+---
+
+## Testing
+
+```bash
+npm test
+```
+
+---
+
+## 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:
+
+```json
+{
+  "loader": "directory",
+  "embedder": "openai",
+  "retriever": "pinecone",
+  "llm": "openai-gpt-4",
+  "useReranker": true
+}
+```
+
+---
+
+## 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
+```
+
+---
+
+## Evaluation Dashboard
+
+```bash
+node server.js
+```
+
+Visit: [http://localhost:3000](http://localhost:3000) → Visualizes metrics, BLEU/ROUGE, pass rate.
+
+---
+
+## License
+
+Apache-2.0
+
+---
+
+## 👤 Author
+
+Ali Kahwaji — [@DevilsDev](https://github.com/DevilsDev)

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/sample-eval-dataset.json

@@ -1,15 +1,15 @@
-[
-    {
-      "prompt": "What is a vector database?",
-      "expected": "A vector database is a system optimized for storing and retrieving data represented as vectors, often used in similarity search."
-    },
-    {
-      "prompt": "Explain what chunking means in RAG.",
-      "expected": "Chunking is the process of splitting documents into smaller, manageable pieces for embedding and retrieval in a RAG pipeline."
-    },
-    {
-      "prompt": "What is the role of embedding in a RAG pipeline?",
-      "expected": "Embeddings convert text into numerical vector form so they can be compared in a vector database during retrieval."
-    }
-  ]
+[
+    {
+      "prompt": "What is a vector database?",
+      "expected": "A vector database is a system optimized for storing and retrieving data represented as vectors, often used in similarity search."
+    },
+    {
+      "prompt": "Explain what chunking means in RAG.",
+      "expected": "Chunking is the process of splitting documents into smaller, manageable pieces for embedding and retrieval in a RAG pipeline."
+    },
+    {
+      "prompt": "What is the role of embedding in a RAG pipeline?",
+      "expected": "Embeddings convert text into numerical vector form so they can be compared in a vector database during retrieval."
+    }
+  ]
   

package/__tests__/fixtures/sample.pdf

@@ -0,0 +1 @@
+%PDF-1.4\n%âãÏÓ\n1 0 obj\n<<>>\nendobj\nxref\n0 2\n0000000000 65535 f\n0000000010 00000 n\ntrailer\n<<>>\nstartxref\n9\n%%EOF

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"]
+}

package/__tests__/integration/cli/config-flow.test.js

@@ -1,44 +1,98 @@
-/**
- * Version: 0.1.0
- * Path: /__tests__/integration/cli/config-flow.test.js
- * Description: Integration tests for CLI fallback to .ragrc.json and full flow execution
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs';
-import path from 'path';
-import { execSync } from 'child_process';
-
-const CONFIG_PATH = path.resolve(process.cwd(), '.ragrc.json');
-const CLI_PATH = path.resolve('./bin/cli.js');
-
-const validConfig = {
-  loader: 'pdf',
-  embedder: 'openai',
-  retriever: 'pinecone',
-  llm: 'openai-gpt-4',
-  chunk: {
-    strategy: 'semantic',
-    size: 256
-  }
-};
-
-describe('CLI integration with .ragrc.json config fallback', () => {
-  beforeEach(() => {
-    fs.writeFileSync(CONFIG_PATH, JSON.stringify(validConfig, null, 2));
-  });
-
-  afterEach(() => {
-    if (fs.existsSync(CONFIG_PATH)) fs.unlinkSync(CONFIG_PATH);
-  });
-
-  test('executes CLI ingest using config fallback', () => {
-    const result = execSync(`node ${CLI_PATH} ingest ./sample.pdf`, { encoding: 'utf-8' });
-    expect(result).toContain('Ingestion complete');
-  });
-
-  test('executes CLI query using config fallback', () => {
-    const output = execSync(`node ${CLI_PATH} query "What is a vector?"`, { encoding: 'utf-8' });
-    expect(output).toContain('Answer:');
-  });
-});
+/**
+ * Version: 1.1.0
+ * Description: Final CLI config fallback integration test with fixture mock copying and validation
+ * Author: Ali Kahwaji
+ */
+
+import { execSync } from 'child_process';
+import {
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  copyFileSync,
+  existsSync,
+  readdirSync,
+  readFileSync
+} from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = resolve(__filename, '..');
+
+const CLI_PATH = resolve('bin/cli.js');
+const TEMP_TEST_DIR = resolve('__tests__/__temp__/cli-config-fallback');
+const FIXTURE_CONFIG = join(TEMP_TEST_DIR, '.ragrc.json');
+const FIXTURE_PDF = resolve('__tests__/fixtures/sample.pdf');
+
+// Fixture sources
+const FIXTURE_SRC = resolve('__tests__/fixtures/src/mocks');
+const PDF_LOADER_SRC = join(FIXTURE_SRC, 'pdf-loader.js');
+const EMBEDDER_SRC = join(FIXTURE_SRC, 'openai-embedder.js');
+const RETRIEVER_SRC = join(FIXTURE_SRC, 'pinecone-retriever.js');
+const LLM_SRC = join(FIXTURE_SRC, 'openai-llm.js');
+
+const FIXTURE_CONFIG_OBJECT = {
+  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']
+};
+
+describe('CLI integration with .ragrc.json config fallback', () => {
+  beforeAll(() => {
+    rmSync(TEMP_TEST_DIR, { recursive: true, force: true });
+    mkdirSync(join(TEMP_TEST_DIR, 'src/mocks'), { recursive: true });
+
+    // Assert existence
+    [FIXTURE_PDF, PDF_LOADER_SRC, EMBEDDER_SRC, RETRIEVER_SRC, LLM_SRC].forEach(file => {
+      if (!existsSync(file)) throw new Error(`[FATAL] Missing required fixture: ${file}`);
+    });
+
+    // Copy fixture PDF
+    copyFileSync(FIXTURE_PDF, join(TEMP_TEST_DIR, 'sample.pdf'));
+
+    // Copy mock plugins into temp dir
+    copyFileSync(PDF_LOADER_SRC, join(TEMP_TEST_DIR, 'src/mocks/pdf-loader.js'));
+    copyFileSync(EMBEDDER_SRC, join(TEMP_TEST_DIR, 'src/mocks/openai-embedder.js'));
+    copyFileSync(RETRIEVER_SRC, join(TEMP_TEST_DIR, 'src/mocks/pinecone-retriever.js'));
+    copyFileSync(LLM_SRC, join(TEMP_TEST_DIR, 'src/mocks/openai-llm.js'));
+
+    // Write valid .ragrc.json
+    writeFileSync(FIXTURE_CONFIG, JSON.stringify(FIXTURE_CONFIG_OBJECT, null, 2));
+
+    console.debug('[DEBUG] .ragrc.json contents:\n', JSON.stringify(FIXTURE_CONFIG_OBJECT, null, 2));
+    console.debug('[SETUP] Temp dir:', TEMP_TEST_DIR);
+    console.debug('[SETUP] Contents:', readdirSync(TEMP_TEST_DIR));
+  });
+
+  afterAll(() => {
+    rmSync(TEMP_TEST_DIR, { recursive: true, force: true });
+  });
+
+  test('validates plugin sections contain resolvable names', () => {
+    const config = JSON.parse(readFileSync(FIXTURE_CONFIG, 'utf-8'));
+    ['loader', 'embedder', 'retriever', 'llm'].forEach(type => {
+      expect(typeof config[type]).toBe('object');
+      expect(Object.keys(config[type]).length).toBeGreaterThan(0);
+    });
+  });
+
+  test('executes CLI ingest using config fallback', () => {
+    const result = execSync(`node ${CLI_PATH} ingest sample.pdf`, {
+      cwd: TEMP_TEST_DIR,
+      encoding: 'utf-8'
+    });
+    expect(result).toMatch(/Ingestion complete/);
+  });
+
+  test('executes CLI query using config fallback', () => {
+    const result = execSync(`node ${CLI_PATH} query "What is this test about?"`, {
+      cwd: TEMP_TEST_DIR,
+      encoding: 'utf-8'
+    });
+    expect(result).toMatch(/Answer:/);
+  });
+});

package/__tests__/integration/config/load-config.test.js

@@ -1,52 +1,67 @@
-/**
- * Version: 0.1.0
- * Path: /__tests__/integration/config/load-config.test.js
- * Description: Integration tests for loading and validating .ragrc.json config
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs';
-import path from 'path';
-import { loadRagConfig } from '../../../src/config/load-config.js';
-
-const FIXTURE_PATH = path.resolve(process.cwd(), '.ragrc.json');
-
-const validConfig = {
-  loader: 'pdf',
-  embedder: 'openai',
-  retriever: 'pinecone',
-  llm: 'openai-gpt-4',
-  chunk: {
-    strategy: 'semantic',
-    size: 500
-  }
-};
-
-const invalidConfig = {
-  loader: 'pdf',
-  chunk: { size: 'large' } // Missing required keys + invalid type
-};
-
-describe('loadRagConfig()', () => {
-  afterEach(() => {
-    if (fs.existsSync(FIXTURE_PATH)) {
-      fs.unlinkSync(FIXTURE_PATH);
-    }
-  });
-
-  test('loads a valid .ragrc.json config file successfully', () => {
-    fs.writeFileSync(FIXTURE_PATH, JSON.stringify(validConfig, null, 2));
-    const result = loadRagConfig();
-    expect(result).toMatchObject(validConfig);
-  });
-
-  test('throws validation error for invalid .ragrc.json config', () => {
-    fs.writeFileSync(FIXTURE_PATH, JSON.stringify(invalidConfig, null, 2));
-    expect(() => loadRagConfig()).toThrow(/Invalid config/);
-  });
-
-  test('throws error if config file does not exist', () => {
-    expect(() => loadRagConfig()).toThrow(/Config file not found/);
-  });
-});
-
+/**
+ * Version: 1.1.1
+ * Description: Integration tests for loading and validating .ragrc.json via loadRagConfig()
+ * Author: Ali Kahwaji
+ * File: __tests__/integration/config/load-config.test.js
+ */
+
+import fs from 'fs';
+import { copyFileSync, mkdirSync, rmSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { loadRagConfig } from '../../../src/config/load-config.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = resolve(__filename, '..');
+
+// Fixture paths
+const FIXTURE_DIR = resolve(__dirname, '../../fixtures');
+const VALID_FIXTURE = join(FIXTURE_DIR, 'valid-ragrc.json');
+const INVALID_FIXTURE = join(FIXTURE_DIR, 'invalid-ragrc.json');
+
+// Temp directory used during tests
+const TEMP_DIR = resolve('__tests__', '__temp__', 'load-config');
+const TEMP_CONFIG = join(TEMP_DIR, '.ragrc.json');
+
+// Ensure fixtures are available before copying
+function assertFixturesExist() {
+  const required = [VALID_FIXTURE, INVALID_FIXTURE];
+  required.forEach(file => {
+    if (!existsSync(file)) {
+      throw new Error(`❌ Required test fixture missing: ${file}`);
+    }
+  });
+}
+
+describe('loadRagConfig()', () => {
+  beforeAll(() => {
+    rmSync(TEMP_DIR, { recursive: true, force: true });
+    mkdirSync(TEMP_DIR, { recursive: true });
+
+    assertFixturesExist();
+  });
+
+  afterAll(() => {
+    rmSync(TEMP_DIR, { recursive: true, force: true });
+  });
+
+  test('loads a valid .ragrc.json config file successfully', () => {
+    copyFileSync(VALID_FIXTURE, TEMP_CONFIG);
+
+    const config = loadRagConfig(TEMP_CONFIG);
+    expect(config).toBeDefined();
+    expect(config.namespace).toBe('cli-config-test');
+    expect(config.loader?.pdf).toBe('./src/mocks/pdf-loader.js');
+    expect(config.pipeline).toEqual(expect.arrayContaining(['loader', 'embedder', 'retriever']));
+  });
+
+  test('throws validation error for invalid .ragrc.json config', () => {
+    copyFileSync(INVALID_FIXTURE, TEMP_CONFIG);
+    expect(() => loadRagConfig(TEMP_CONFIG)).toThrow(/Config validation failed/);
+  });
+
+  test('throws error if config file does not exist', () => {
+    const NON_EXISTENT = join(TEMP_DIR, 'missing.json');
+    expect(() => loadRagConfig(NON_EXISTENT)).toThrow(/Config file not found/);
+  });
+});