@devilsdev/rag-pipeline-utils 1.0.0 → 2.0.0

package/src/loader/html-loader.js

@@ -1,57 +1,57 @@
-/**
- * Version: 0.1.0
- * Path: /src/loader/html-loader.js
- * Description: Loader for HTML (.html) documents
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import { JSDOM } from 'jsdom';
-
-/**
- * HTMLLoader reads HTML files and extracts visible text.
- * Implements the Loader interface.
- */
-export class HTMLLoader {
-  /**
-   * Load and extract text from an HTML file
-   * @param {string} filePath - Path to .html file
-   * @returns {Promise<Array<{ chunk(): string[] }>>}
-   */
-  async load(filePath) {
-    const absPath = path.resolve(filePath);
-    const raw = await fs.readFile(absPath, 'utf-8');
-    const dom = new JSDOM(raw);
-    const text = dom.window.document.body.textContent || '';
-
-    return [
-      {
-        chunk: () => this._chunkText(text)
-      }
-    ];
-  }
-
-  /**
-   * Chunk HTML text content by sentence
-   * @param {string} input
-   * @param {number} maxLen
-   * @returns {string[]}
-   */
-  _chunkText(input, maxLen = 500) {
-    const sentences = input.split(/(?<=[.!?])\s+/);
-    const chunks = [];
-    let buffer = '';
-
-    for (const sentence of sentences) {
-      if ((buffer + sentence).length <= maxLen) {
-        buffer += sentence + ' ';
-      } else {
-        chunks.push(buffer.trim());
-        buffer = sentence + ' ';
-      }
-    }
-    if (buffer.trim()) chunks.push(buffer.trim());
-    return chunks;
-  }
-}
+/**
+ * Version: 0.1.0
+ * Path: /src/loader/html-loader.js
+ * Description: Loader for HTML (.html) documents
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { JSDOM } from 'jsdom';
+
+/**
+ * HTMLLoader reads HTML files and extracts visible text.
+ * Implements the Loader interface.
+ */
+export class HTMLLoader {
+  /**
+   * Load and extract text from an HTML file
+   * @param {string} filePath - Path to .html file
+   * @returns {Promise<Array<{ chunk(): string[] }>>}
+   */
+  async load(filePath) {
+    const absPath = path.resolve(filePath);
+    const raw = await fs.readFile(absPath, 'utf-8');
+    const dom = new JSDOM(raw);
+    const text = dom.window.document.body.textContent || '';
+
+    return [
+      {
+        chunk: () => this._chunkText(text)
+      }
+    ];
+  }
+
+  /**
+   * Chunk HTML text content by sentence
+   * @param {string} input
+   * @param {number} maxLen
+   * @returns {string[]}
+   */
+  _chunkText(input, maxLen = 500) {
+    const sentences = input.split(/(?<=[.!?])\s+/);
+    const chunks = [];
+    let buffer = '';
+
+    for (const sentence of sentences) {
+      if ((buffer + sentence).length <= maxLen) {
+        buffer += sentence + ' ';
+      } else {
+        chunks.push(buffer.trim());
+        buffer = sentence + ' ';
+      }
+    }
+    if (buffer.trim()) chunks.push(buffer.trim());
+    return chunks;
+  }
+}

package/src/loader/markdown-loader.js

@@ -1,58 +1,58 @@
-/**
- * Version: 0.1.0
- * Path: /src/loader/markdown-loader.js
- * Description: Loader for Markdown (.md) documents
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import { marked } from 'marked';
-
-/**
- * MarkdownLoader reads and parses .md files into plain text chunks.
- * Implements the Loader interface.
- */
-export class MarkdownLoader {
-  /**
-   * Load and parse Markdown file
-   * @param {string} filePath - Path to .md file
-   * @returns {Promise<Array<{ chunk(): string[] }>>}
-   */
-  async load(filePath) {
-    const absPath = path.resolve(filePath);
-    const raw = await fs.readFile(absPath, 'utf-8');
-    const html = marked(raw);
-    const text = html.replace(/<[^>]+>/g, ''); // strip tags
-
-    return [
-      {
-        chunk: () => this._chunkText(text)
-      }
-    ];
-  }
-
-  /**
-   * Simple sentence-based chunking strategy
-   * @param {string} input
-   * @param {number} maxLen
-   * @returns {string[]}
-   */
-  _chunkText(input, maxLen = 500) {
-    const sentences = input.split(/(?<=[.!?])\s+/);
-    const chunks = [];
-    let buffer = '';
-
-    for (const sentence of sentences) {
-      if ((buffer + sentence).length <= maxLen) {
-        buffer += sentence + ' ';
-      } else {
-        chunks.push(buffer.trim());
-        buffer = sentence + ' ';
-      }
-    }
-    if (buffer.trim()) chunks.push(buffer.trim());
-    return chunks;
-  }
-}
-
+/**
+ * Version: 0.1.0
+ * Path: /src/loader/markdown-loader.js
+ * Description: Loader for Markdown (.md) documents
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { marked } from 'marked';
+
+/**
+ * MarkdownLoader reads and parses .md files into plain text chunks.
+ * Implements the Loader interface.
+ */
+export class MarkdownLoader {
+  /**
+   * Load and parse Markdown file
+   * @param {string} filePath - Path to .md file
+   * @returns {Promise<Array<{ chunk(): string[] }>>}
+   */
+  async load(filePath) {
+    const absPath = path.resolve(filePath);
+    const raw = await fs.readFile(absPath, 'utf-8');
+    const html = marked(raw);
+    const text = html.replace(/<[^>]+>/g, ''); // strip tags
+
+    return [
+      {
+        chunk: () => this._chunkText(text)
+      }
+    ];
+  }
+
+  /**
+   * Simple sentence-based chunking strategy
+   * @param {string} input
+   * @param {number} maxLen
+   * @returns {string[]}
+   */
+  _chunkText(input, maxLen = 500) {
+    const sentences = input.split(/(?<=[.!?])\s+/);
+    const chunks = [];
+    let buffer = '';
+
+    for (const sentence of sentences) {
+      if ((buffer + sentence).length <= maxLen) {
+        buffer += sentence + ' ';
+      } else {
+        chunks.push(buffer.trim());
+        buffer = sentence + ' ';
+      }
+    }
+    if (buffer.trim()) chunks.push(buffer.trim());
+    return chunks;
+  }
+}
+

package/src/mocks/openai-embedder.js

@@ -0,0 +1,30 @@
+/**
+ * Version: 0.1.0
+ * File: /src/mocks/openai-embedder.js
+ * Description: Mock implementation of an OpenAI embedder
+ * Author: Ali Kahwaji
+ */
+
+export default class OpenAIEmbedder {
+  /**
+   * Returns static vector embeddings for input chunks
+   * @param {string[]} chunks
+   * @returns {Promise<Array<{ id: string, values: number[], metadata: { text: string } }>>}
+   */
+  async embed(chunks) {
+    return chunks.map((text, i) => ({
+      id: `v${i}`,
+      values: [0.1, 0.2, 0.3],
+      metadata: { text },
+    }));
+  }
+
+  /**
+   * Returns a static vector for the given query prompt
+   * @param {string} prompt
+   * @returns {Promise<number[]>}
+   */
+  async embedQuery(prompt) {
+    return [0.1, 0.2, 0.3];
+  }
+}

package/src/mocks/openai-llm.js

@@ -0,0 +1,18 @@
+/**
+ * Version: 0.1.0
+ * File: /src/mocks/openai-llm.js
+ * Description: Mock implementation of an OpenAI LLM
+ * Author: Ali Kahwaji
+ */
+
+export default class OpenAILLM {
+    /**
+     * Generates a static answer from input prompt and context
+     * @param {string} prompt
+     * @param {Array<{ text: string }>} context
+     * @returns {Promise<string>}
+     */
+    async generate(prompt, context) {
+      return `Generated answer using: ${context.map(d => d.text).join(', ')}`;
+    }
+  }

package/src/mocks/pdf-loader.js

@@ -0,0 +1,17 @@
+/**
+ * Version: 0.1.0
+ * File: /src/mocks/pdf-loader.js
+ * Description: Mock implementation of a PDF document loader
+ * Author: Ali Kahwaji
+ */
+
+export default class PDFLoader {
+  /**
+   * Loads a mock PDF file and returns an array of chunked content.
+   * @param {string} filePath - Path to the PDF file
+   * @returns {Promise<Array<{ chunk: () => string[] }>>}
+   */
+  async load(filePath) {
+    return [{ chunk: () => [`Test loaded: ${filePath}`] }];
+  }
+}

package/src/mocks/pinecone-retriever.js

@@ -0,0 +1,25 @@
+/**
+ * Version: 0.1.0
+ * File: /src/mocks/pinecone-retriever.js
+ * Description: Mock implementation of a Pinecone retriever
+ * Author: Ali Kahwaji
+ */
+
+export default class PineconeRetriever {
+    /**
+     * Mocks vector storage (no-op).
+     */
+    async store() {}
+  
+    /**
+     * Returns mock retrieved documents
+     * @returns {Promise<Array<{ id: string, text: string, metadata: object }>>}
+     */
+    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: {} },
+      ];
+    }
+  }

package/src/reranker/llm-reranker.js

@@ -1,49 +1,34 @@
-/**
- * Version: 0.1.0
- * Path: /src/reranker/llm-reranker.js
- * Description: LLM-based reranker that reorders retrieved context for relevance
- * Author: Ali Kahwaji
- */
-
-/**
- * LLMReranker ranks context chunks by relevance to a given prompt.
- * @interface
- */
-export class LLMReranker {
-    constructor({ llm }) {
-      if (!llm || typeof llm.generate !== 'function') {
-        throw new Error('LLM instance must implement generate(prompt, context)');
-      }
-      this.llm = llm;
-    }
-  
-    /**
-     * Reranks retrieved context chunks using the LLM.
-     * @param {string} prompt - The user's question or query
-     * @param {Array<{ text: string, metadata?: object }>} documents - Retrieved context chunks
-     * @param {number} [topK=5] - Number of top-ranked documents to return
-     * @returns {Promise<Array>} - Reranked top K chunks
-     */
-    async rerank(prompt, documents, topK = 5) {
-      const contextText = documents.map((d, i) => `Chunk ${i + 1}: ${d.text}`).join('\n');
-  
-      const instruction = `Rank the following document chunks by how well they answer the prompt.\n
-  Prompt: ${prompt}\n
-  Chunks:\n${contextText}\n
-  Respond with a JSON array of chunk indexes in descending order of relevance.`;
-  
-      const result = await this.llm.generate(instruction, []);
-  
-      let indexOrder = [];
-      try {
-        indexOrder = JSON.parse(result.match(/\[.*\]/s)?.[0] || '[]');
-      } catch (err) {
-        console.warn('Failed to parse reranker output:', result);
-        return documents.slice(0, topK); // fallback
-      }
-  
-      const ranked = indexOrder.map(i => documents[i]).filter(Boolean);
-      return ranked.slice(0, topK);
-    }
-  }
-  
+/**
+ * Version: 1.0.4
+ * Description: LLM reranker using LLM to reorder documents based on relevance
+ * Author: devilsdev
+ * File: src/reranker/llm-reranker.js
+ */
+
+export class LLMReranker {
+  /**
+   * @param {Object} options
+   * @param {{ generate(prompt: string): Promise<string> }} options.llm - An LLM client with a `generate` method
+   */
+  constructor({ llm }) {
+    this.llm = llm;
+  }
+
+  /**
+   * Rerank documents based on the LLM output
+   * @param {string} query
+   * @param {Array<{ text: string }>} docs
+   * @returns {Promise<Array<{ text: string }>>}
+   */
+  async rerank(query, docs) {
+    const prompt = `Given the query: "${query}", rank the following documents by relevance: \n${docs.map((d, i) => `[${i}]: ${d.text}`).join('\n')}\nReturn an array of indices like [2, 0, 1]`;
+
+    try {
+      const json = await this.llm.generate(prompt);
+      const indices = JSON.parse(json);
+      return indices.map(i => docs[i]).filter(Boolean);
+    } catch (err) {
+      return docs; // Fallback if LLM response is not parsable
+    }
+  }
+}

package/src/utils/ci/diagnostic-reporter.js

@@ -0,0 +1,36 @@
+/**
+ * Version: 1.0.0
+ * Description: Enhanced CI diagnostics for plugin mock verification
+ * Author: Ali Kahwaji
+ */
+
+import path from 'path';
+import chalk from 'chalk';
+
+/**
+ * Pretty prints CI validation errors and guidance
+ * @param {Array<{ file: string, missing: string[] }>} failures
+ */
+export function reportPluginValidationFailures(failures) {
+  if (!failures.length) return;
+
+  console.log(`\n${chalk.redBright.bold('❌ Plugin Mock Validation Failed')}`);
+
+  failures.forEach(({ file, missing }) => {
+    const fileName = path.basename(file);
+    console.log(
+      `${chalk.red(`  ✖ ${fileName}`)} ${chalk.gray(`missing: ${missing.join(', ')}`)}`
+    );
+
+    // Add method-level fix hints
+    missing.forEach(method => {
+      const pluginType = fileName.split('.')[0].split('-')[1] || 'unknown';
+      console.error(`    → Fix: implement method ${chalk.cyan(`${method}()`)} for plugin type ${chalk.yellow(pluginType)}`);
+    });
+  });
+
+  console.log(`\n${chalk.yellowBright('Recommended Fixes:')}`);
+  console.log('  • Implement all required methods defined in /src/core/plugin-contracts.js');
+  console.log(`  • Re-run: ${chalk.cyan('npm run ci')} to confirm validation`);
+  console.log(`  • Optionally use: ${chalk.cyan('scripts/repair-fixtures.js')} to auto-repair mocks\n`);
+}

package/src/utils/logger.js

@@ -1,29 +1,29 @@
-/**
- * Version: 0.1.0
- * Path: /src/utils/logger.js
- * Description: Centralized structured logger using Pino
- * Author: Ali Kahwaji
- */
-
-import pino from 'pino';
-
-/**
- * Create a structured JSON logger instance with sensible defaults.
- * Output can be redirected or formatted in dev/prod contexts.
- */
-const logger = pino({
-  name: 'rag-pipeline-utils',
-  level: process.env.LOG_LEVEL || 'info',
-  transport: process.env.NODE_ENV === 'development' ? {
-    target: 'pino-pretty',
-    options: {
-      colorize: true,
-      translateTime: 'SYS:standard',
-      ignore: 'pid,hostname'
-    }
-  } : undefined
-});
-
-export { logger };
-
-
+/**
+ * Version: 0.1.0
+ * Path: /src/utils/logger.js
+ * Description: Centralized structured logger using Pino
+ * Author: Ali Kahwaji
+ */
+
+import pino from 'pino';
+
+/**
+ * Create a structured JSON logger instance with sensible defaults.
+ * Output can be redirected or formatted in dev/prod contexts.
+ */
+const logger = pino({
+  name: 'rag-pipeline-utils',
+  level: process.env.LOG_LEVEL || 'info',
+  transport: process.env.NODE_ENV === 'development' ? {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+      translateTime: 'SYS:standard',
+      ignore: 'pid,hostname'
+    }
+  } : undefined
+});
+
+export { logger };
+
+

package/src/utils/retry.js

@@ -1,42 +1,42 @@
-/**
- * Version: 0.1.0
- * Path: /src/utils/retry.js
- * Description: Generic retry wrapper with exponential backoff for async operations
- * Author: Ali Kahwaji
- */
-
-import { logger } from './logger.js';
-
-/**
- * Retry wrapper for async functions with exponential backoff
- *
- * @param {Function} fn - The async function to retry
- * @param {Object} options
- * @param {number} [options.retries=3] - Number of retry attempts
- * @param {number} [options.initialDelay=300] - Initial delay in ms
- * @param {string} [options.label] - Optional label for logging context
- * @returns {Promise<*>} - The resolved result of the function
- * @throws {Error} - The final error if all retries fail
- */
-export async function withRetry(fn, { retries = 3, initialDelay = 300, label = 'operation' } = {}) {
-  let attempt = 0;
-  let delay = initialDelay;
-
-  while (attempt <= retries) {
-    try {
-      if (attempt > 0) {
-        logger.warn({ attempt, label }, `Retrying ${label} (attempt ${attempt})`);
-      }
-      return await fn();
-    } catch (err) {
-      attempt++;
-      if (attempt > retries) {
-        logger.error({ label, error: err.message }, `Failed ${label} after ${retries} retries`);
-        throw err;
-      }
-      await new Promise(resolve => setTimeout(resolve, delay));
-      delay *= 2; // Exponential backoff
-    }
-  }
-}
-
+/**
+ * Version: 0.1.0
+ * Path: /src/utils/retry.js
+ * Description: Generic retry wrapper with exponential backoff for async operations
+ * Author: Ali Kahwaji
+ */
+
+import { logger } from './logger.js';
+
+/**
+ * Retry wrapper for async functions with exponential backoff
+ *
+ * @param {Function} fn - The async function to retry
+ * @param {Object} options
+ * @param {number} [options.retries=3] - Number of retry attempts
+ * @param {number} [options.initialDelay=300] - Initial delay in ms
+ * @param {string} [options.label] - Optional label for logging context
+ * @returns {Promise<*>} - The resolved result of the function
+ * @throws {Error} - The final error if all retries fail
+ */
+export async function withRetry(fn, { retries = 3, initialDelay = 300, label = 'operation' } = {}) {
+  let attempt = 0;
+  let delay = initialDelay;
+
+  while (attempt <= retries) {
+    try {
+      if (attempt > 0) {
+        logger.warn({ attempt, label }, `Retrying ${label} (attempt ${attempt})`);
+      }
+      return await fn();
+    } catch (err) {
+      attempt++;
+      if (attempt > retries) {
+        logger.error({ label, error: err.message }, `Failed ${label} after ${retries} retries`);
+        throw err;
+      }
+      await new Promise(resolve => setTimeout(resolve, delay));
+      delay *= 2; // Exponential backoff
+    }
+  }
+}
+

package/src/utils/validate-plugin-contract.js

@@ -0,0 +1,36 @@
+/**
+ * Version: 1.0.0
+ * Description: Type-safe plugin contract validator for runtime safety
+ * Author: Ali Kahwaji
+ * File: /src/utils/validate-plugin-contract.js
+ */
+
+import { pluginContracts } from '../core/plugin-contracts.js';
+
+/**
+ * Validates that a plugin instance implements all required methods.
+ * @param {string} type - Plugin type (e.g. 'loader', 'embedder')
+ * @param {object} instance - Instantiated plugin module
+ * @param {string} filePath - Path to plugin (used in error reporting)
+ * @throws {Error} if any required method is missing or not a function
+ */
+export function validatePluginContract(type, instance, filePath) {
+  const expectedMethods = pluginContracts[type];
+  if (!expectedMethods) {
+    throw new Error(`[validatePluginContract] Unknown plugin type: ${type}`);
+  }
+
+  const missing = expectedMethods.filter(method =>
+    typeof instance[method] !== 'function'
+  );
+
+  if (missing.length > 0) {
+    throw new Error(
+      `[validatePluginContract] Plugin '${filePath}' is missing required methods for '${type}': ${missing.join(', ')}`
+    );
+  }
+}
+
+/**
+ * Optionally wraps plugin instance with a Proxy for method usage auditing (see enforcePluginProxy)
+ */

package/.github/workflows/release.yml

@@ -1,21 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          registry-url: 'https://registry.npmjs.org'
-
-      - run: npm ci
-      - run: npx semantic-release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}