@devilsdev/rag-pipeline-utils 1.0.0 → 2.0.0

package/src/core/plugin-registry.js

@@ -1,61 +1,48 @@
-/**
- * Version: 1.0.0
- * Path: /src/core/plugin-registry.js
- * Description: Registry for managing pluggable components (loader, embedder, retriever, llm)
- * Author: Ali Kahwaji
- */
-
-export class PluginRegistry {
-  #registry = {
-    loader: new Map(),
-    embedder: new Map(),
-    retriever: new Map(),
-    llm: new Map(),
-    reranker: new Map(),
-  };
-
-  /**
-   * Registers a plugin instance under a specific type and name.
-   * @param {'loader' | 'embedder' | 'retriever' | 'llm' | 'reranker'} type - Plugin type category.
-   * @param {string} name - Unique name/key for this plugin.
-   * @param {object} plugin - Plugin implementation (e.g., instance or factory).
-   */
-  register(type, name, plugin) {
-    const group = this.#registry[type];
-    if (!group) {
-      throw new Error(`Unknown plugin type: '${type}'`);
-    }
-    group.set(name, plugin);
-  }
-
-  /**
-   * Retrieves a plugin by type and name.
-   * @param {'loader' | 'embedder' | 'retriever' | 'llm' | 'reranker'} type - Plugin type.
-   * @param {string} name - Plugin name/key.
-   * @returns {object} - The plugin instance.
-   */
-  get(type, name) {
-    const group = this.#registry[type];
-    if (!group) {
-      throw new Error(`Unknown plugin type: '${type}'`);
-    }
-    const plugin = group.get(name);
-    if (!plugin) {
-      throw new Error(`Plugin not found: [${type}:${name}]`);
-    }
-    return plugin;
-  }
-
-  /**
-   * Lists all registered plugin names for a type.
-   * @param {'loader' | 'embedder' | 'retriever' | 'llm' | 'reranker'} type - Plugin category.
-   * @returns {string[]} - Array of registered plugin names.
-   */
-  list(type) {
-    const group = this.#registry[type];
-    if (!group) {
-      throw new Error(`Unknown plugin type: '${type}'`);
-    }
-    return [...group.keys()];
-  }
-}
+/**
+ * Version: 1.0.0
+ * Path: /src/core/plugin-registry.js
+ * Description: Registry for managing pluggable components (loader, embedder, retriever, llm)
+ * Author: Ali Kahwaji
+ */
+
+export class PluginRegistry {
+  #registry = {
+    loader: new Map(),
+    embedder: new Map(),
+    retriever: new Map(),
+    llm: new Map(),
+    reranker: new Map(),
+  };
+
+  register(type, name, plugin) {
+    const group = this.#registry[type];
+    if (!group) {
+      throw new Error(`Unknown plugin type: '${type}'`);
+    }
+    group.set(name, plugin);
+  }
+
+  get(type, name) {
+    const group = this.#registry[type];
+    if (!group) {
+      throw new Error(`Unknown plugin type: '${type}'`);
+    }
+    const plugin = group.get(name);
+    if (!plugin) {
+      throw new Error(`Plugin not found: [${type}:${name}]`);
+    }
+    return plugin;
+  }
+
+  list(type) {
+    const group = this.#registry[type];
+    if (!group) {
+      throw new Error(`Unknown plugin type: '${type}'`);
+    }
+    return [...group.keys()];
+  }
+}
+
+const registry = new PluginRegistry();
+
+export default registry;

package/src/dag/dag-engine.js

@@ -1,70 +1,70 @@
-/**
- * Version: 0.1.0
- * Path: /src/dag/dag-engine.js
- * Description: DAG executor for chained RAG pipelines
- * Author: Ali Kahwaji
- */
-
-export class DAGNode {
-    constructor(id, run) {
-      this.id = id;
-      this.run = run; // async (input) => output
-      this.inputs = [];
-      this.outputs = [];
-    }
-  }
-  
-  export class DAG {
-    constructor() {
-      this.nodes = new Map();
-    }
-  
-    addNode(id, fn) {
-      const node = new DAGNode(id, fn);
-      this.nodes.set(id, node);
-      return node;
-    }
-  
-    connect(fromId, toId) {
-      const from = this.nodes.get(fromId);
-      const to = this.nodes.get(toId);
-      if (!from || !to) throw new Error(`Invalid edge: ${fromId} → ${toId}`);
-      from.outputs.push(to);
-      to.inputs.push(from);
-    }
-  
-    /**
-     * Executes DAG from source nodes to sinks using topological order
-     * @param {any} seed - Initial input to the graph
-     * @returns {Promise<any>} - Final output from sink(s)
-     */
-    async execute(seed) {
-      const visited = new Set();
-      const order = this.topoSort();
-      const results = new Map();
-  
-      for (const node of order) {
-        const inputValues = node.inputs.map(n => results.get(n.id));
-        const input = inputValues.length === 1 ? inputValues[0] : inputValues;
-        const output = await node.run(input ?? seed);
-        results.set(node.id, output);
-      }
-  
-      const last = order.at(-1);
-      return results.get(last.id);
-    }
-  
-    topoSort() {
-      const order = [];
-      const visited = new Set();
-      const visit = (node) => {
-        if (visited.has(node.id)) return;
-        visited.add(node.id);
-        node.inputs.forEach(visit);
-        order.push(node);
-      };
-      for (const node of this.nodes.values()) visit(node);
-      return order;
-    }
-  }
+/**
+ * Version: 0.1.0
+ * Path: /src/dag/dag-engine.js
+ * Description: DAG executor for chained RAG pipelines
+ * Author: Ali Kahwaji
+ */
+
+export class DAGNode {
+    constructor(id, run) {
+      this.id = id;
+      this.run = run; // async (input) => output
+      this.inputs = [];
+      this.outputs = [];
+    }
+  }
+  
+  export class DAG {
+    constructor() {
+      this.nodes = new Map();
+    }
+  
+    addNode(id, fn) {
+      const node = new DAGNode(id, fn);
+      this.nodes.set(id, node);
+      return node;
+    }
+  
+    connect(fromId, toId) {
+      const from = this.nodes.get(fromId);
+      const to = this.nodes.get(toId);
+      if (!from || !to) throw new Error(`Invalid edge: ${fromId} → ${toId}`);
+      from.outputs.push(to);
+      to.inputs.push(from);
+    }
+  
+    /**
+     * Executes DAG from source nodes to sinks using topological order
+     * @param {any} seed - Initial input to the graph
+     * @returns {Promise<any>} - Final output from sink(s)
+     */
+    async execute(seed) {
+      // const visited = new Set();
+      const order = this.topoSort();
+      const results = new Map();
+  
+      for (const node of order) {
+        const inputValues = node.inputs.map(n => results.get(n.id));
+        const input = inputValues.length === 1 ? inputValues[0] : inputValues;
+        const output = await node.run(input ?? seed);
+        results.set(node.id, output);
+      }
+  
+      const last = order.at(-1);
+      return results.get(last.id);
+    }
+  
+    topoSort() {
+      const order = [];
+      const visited = new Set();
+      const visit = (node) => {
+        if (visited.has(node.id)) return;
+        visited.add(node.id);
+        node.inputs.forEach(visit);
+        order.push(node);
+      };
+      for (const node of this.nodes.values()) visit(node);
+      return order;
+    }
+  }
   

package/src/evaluate/evaluator.js

@@ -1,44 +1,44 @@
-/**
- * Version: 0.1.1
- * Path: /src/evaluate/evaluator.js
- * Description: Evaluation runner with scoring metrics for batch RAG QA
- * Author: Ali Kahwaji
- */
-
-import { createRagPipeline } from '../core/create-pipeline.js';
-import { logger } from '../utils/logger.js';
-import fs from 'fs/promises';
-import path from 'path';
-import { scoreAnswer } from './scoring.js';
-
-/**
- * Evaluate a list of prompt/answer pairs using the RAG pipeline and compute scores
- * @param {string} datasetPath - Path to JSON file with { prompt, expected }[]
- * @param {object} config - RAG plugin config (loader optional)
- * @returns {Promise<Array<{ prompt: string, expected: string, actual: string, success: boolean, scores: object }>>}
- */
-export async function evaluateRagDataset(datasetPath, config) {
-  const file = await fs.readFile(path.resolve(datasetPath), 'utf-8');
-  const cases = JSON.parse(file);
-  const pipeline = createRagPipeline(config);
-
-  const results = [];
-  for (const { prompt, expected } of cases) {
-    try {
-      logger.info({ prompt }, 'Evaluating case');
-      const actual = await pipeline.query(prompt);
-      const success = normalizeText(actual) === normalizeText(expected);
-      const scores = scoreAnswer(actual, expected);
-      results.push({ prompt, expected, actual, success, scores });
-    } catch (err) {
-      logger.error({ prompt, error: err.message }, 'Evaluation failed');
-      results.push({ prompt, expected, actual: '', success: false, scores: { bleu: 0, rouge: 0 } });
-    }
-  }
-  return results;
-}
-
-function normalizeText(txt) {
-  return txt.trim().toLowerCase().replace(/[^a-z0-9 ]/g, '').replace(/\s+/g, ' ');
-}
-
+/**
+ * Version: 0.1.1
+ * Path: /src/evaluate/evaluator.js
+ * Description: Evaluation runner with scoring metrics for batch RAG QA
+ * Author: Ali Kahwaji
+ */
+
+import { createRagPipeline } from '../core/create-pipeline.js';
+import { logger } from '../utils/logger.js';
+import fs from 'fs/promises';
+import path from 'path';
+import { scoreAnswer } from './scoring.js';
+
+/**
+ * Evaluate a list of prompt/answer pairs using the RAG pipeline and compute scores
+ * @param {string} datasetPath - Path to JSON file with { prompt, expected }[]
+ * @param {object} config - RAG plugin config (loader optional)
+ * @returns {Promise<Array<{ prompt: string, expected: string, actual: string, success: boolean, scores: object }>>}
+ */
+export async function evaluateRagDataset(datasetPath, config) {
+  const file = await fs.readFile(path.resolve(datasetPath), 'utf-8');
+  const cases = JSON.parse(file);
+  const pipeline = createRagPipeline(config);
+
+  const results = [];
+  for (const { prompt, expected } of cases) {
+    try {
+      logger.info({ prompt }, 'Evaluating case');
+      const actual = await pipeline.query(prompt);
+      const success = normalizeText(actual) === normalizeText(expected);
+      const scores = scoreAnswer(actual, expected);
+      results.push({ prompt, expected, actual, success, scores });
+    } catch (err) {
+      logger.error({ prompt, error: err.message }, 'Evaluation failed');
+      results.push({ prompt, expected, actual: '', success: false, scores: { bleu: 0, rouge: 0 } });
+    }
+  }
+  return results;
+}
+
+function normalizeText(txt) {
+  return txt.trim().toLowerCase().replace(/[^a-z0-9 ]/g, '').replace(/\s+/g, ' ');
+}
+

package/src/evaluate/scoring.js

@@ -1,74 +1,74 @@
-/**
- * Version: 0.1.0
- * Path: /src/evaluate/scoring.js
- * Description: Basic scoring metrics (BLEU, ROUGE-L) for RAG output evaluation
- * Author: Ali Kahwaji
- */
-
-/**
- * Tokenize a string by words
- * @param {string} text
- * @returns {string[]}
- */
-function tokenize(text) {
-    return text.toLowerCase().replace(/[^a-z0-9 ]/g, '').split(/\s+/).filter(Boolean);
-  }
-  
-  /**
-   * Compute BLEU-1 score: unigram precision
-   * @param {string[]} candidate - Generated tokens
-   * @param {string[]} reference - Reference tokens
-   * @returns {number}
-   */
-  export function computeBLEU(candidate, reference) {
-    const candCounts = candidate.reduce((acc, t) => (acc[t] = (acc[t] || 0) + 1, acc), {});
-    const refCounts = reference.reduce((acc, t) => (acc[t] = (acc[t] || 0) + 1, acc), {});
-  
-    let match = 0;
-    for (const token of Object.keys(candCounts)) {
-      match += Math.min(candCounts[token], refCounts[token] || 0);
-    }
-    return candidate.length ? match / candidate.length : 0;
-  }
-  
-  /**
-   * Compute ROUGE-L (Longest Common Subsequence) recall
-   * @param {string[]} candidate
-   * @param {string[]} reference
-   * @returns {number}
-   */
-  export function computeROUGE(candidate, reference) {
-    const m = candidate.length;
-    const n = reference.length;
-    const dp = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));
-  
-    for (let i = 1; i <= m; i++) {
-      for (let j = 1; j <= n; j++) {
-        if (candidate[i - 1] === reference[j - 1]) {
-          dp[i][j] = dp[i - 1][j - 1] + 1;
-        } else {
-          dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
-        }
-      }
-    }
-  
-    const lcs = dp[m][n];
-    return reference.length ? lcs / reference.length : 0;
-  }
-  
-  /**
-   * Score a prompt-answer pair using multiple metrics
-   * @param {string} actual - LLM response
-   * @param {string} expected - Reference answer
-   * @returns {{ bleu: number, rouge: number }}
-   */
-  export function scoreAnswer(actual, expected) {
-    const candTokens = tokenize(actual);
-    const refTokens = tokenize(expected);
-    return {
-      bleu: computeBLEU(candTokens, refTokens),
-      rouge: computeROUGE(candTokens, refTokens)
-    };
-  }
-  
+/**
+ * Version: 0.1.0
+ * Path: /src/evaluate/scoring.js
+ * Description: Basic scoring metrics (BLEU, ROUGE-L) for RAG output evaluation
+ * Author: Ali Kahwaji
+ */
+
+/**
+ * Tokenize a string by words
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenize(text) {
+    return text.toLowerCase().replace(/[^a-z0-9 ]/g, '').split(/\s+/).filter(Boolean);
+  }
+  
+  /**
+   * Compute BLEU-1 score: unigram precision
+   * @param {string[]} candidate - Generated tokens
+   * @param {string[]} reference - Reference tokens
+   * @returns {number}
+   */
+  export function computeBLEU(candidate, reference) {
+    const candCounts = candidate.reduce((acc, t) => (acc[t] = (acc[t] || 0) + 1, acc), {});
+    const refCounts = reference.reduce((acc, t) => (acc[t] = (acc[t] || 0) + 1, acc), {});
+  
+    let match = 0;
+    for (const token of Object.keys(candCounts)) {
+      match += Math.min(candCounts[token], refCounts[token] || 0);
+    }
+    return candidate.length ? match / candidate.length : 0;
+  }
+  
+  /**
+   * Compute ROUGE-L (Longest Common Subsequence) recall
+   * @param {string[]} candidate
+   * @param {string[]} reference
+   * @returns {number}
+   */
+  export function computeROUGE(candidate, reference) {
+    const m = candidate.length;
+    const n = reference.length;
+    const dp = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));
+  
+    for (let i = 1; i <= m; i++) {
+      for (let j = 1; j <= n; j++) {
+        if (candidate[i - 1] === reference[j - 1]) {
+          dp[i][j] = dp[i - 1][j - 1] + 1;
+        } else {
+          dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+        }
+      }
+    }
+  
+    const lcs = dp[m][n];
+    return reference.length ? lcs / reference.length : 0;
+  }
+  
+  /**
+   * Score a prompt-answer pair using multiple metrics
+   * @param {string} actual - LLM response
+   * @param {string} expected - Reference answer
+   * @returns {{ bleu: number, rouge: number }}
+   */
+  export function scoreAnswer(actual, expected) {
+    const candTokens = tokenize(actual);
+    const refTokens = tokenize(expected);
+    return {
+      bleu: computeBLEU(candTokens, refTokens),
+      rouge: computeROUGE(candTokens, refTokens)
+    };
+  }
+  
   

package/src/loader/csv-loader.js

@@ -1,30 +1,30 @@
-/**
- * Version: 0.1.0
- * Path: /src/loader/csv-loader.js
- * Description: CSV document loader with row-wise chunking
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import { parse } from 'csv-parse/sync';
-
-export class CSVLoader {
-  /**
-   * Load and parse a CSV file into chunks
-   * @param {string} filePath
-   * @returns {Promise<Array<{ chunk(): string[] }>>}
-   */
-  async load(filePath) {
-    const absPath = path.resolve(filePath);
-    const raw = await fs.readFile(absPath, 'utf-8');
-    const records = parse(raw, { columns: true });
-
-    return [
-      {
-        chunk: () => records.map(r => Object.values(r).join(' '))
-      }
-    ];
-  }
-}
-
+/**
+ * Version: 0.1.0
+ * Path: /src/loader/csv-loader.js
+ * Description: CSV document loader with row-wise chunking
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { parse } from 'csv-parse/sync';
+
+export class CSVLoader {
+  /**
+   * Load and parse a CSV file into chunks
+   * @param {string} filePath
+   * @returns {Promise<Array<{ chunk(): string[] }>>}
+   */
+  async load(filePath) {
+    const absPath = path.resolve(filePath);
+    const raw = await fs.readFile(absPath, 'utf-8');
+    const records = parse(raw, { columns: true });
+
+    return [
+      {
+        chunk: () => records.map(r => Object.values(r).join(' '))
+      }
+    ];
+  }
+}
+

package/src/loader/directory-loader.js

@@ -1,38 +1,38 @@
-/**
- * Version: 0.1.0
- * Path: /src/loader/directory-loader.js
- * Description: Recursive directory loader with file type routing
- * Author: Ali Kahwaji
- */
-
-import fg from 'fast-glob';
-import { MarkdownLoader } from './markdown-loader.js';
-import { HTMLLoader } from './html-loader.js';
-import { CSVLoader } from './csv-loader.js';
-
-const loaders = {
-  '.md': new MarkdownLoader(),
-  '.html': new HTMLLoader(),
-  '.csv': new CSVLoader()
-};
-
-export class DirectoryLoader {
-  /**
-   * Load and route supported files from a directory
-   * @param {string} dirPath
-   * @returns {Promise<Array<{ chunk(): string[] }>>}
-   */
-  async load(dirPath) {
-    const matches = await fg([`${dirPath}/**/*.{md,html,csv}`]);
-    const all = [];
-    for (const file of matches) {
-      const ext = file.slice(file.lastIndexOf('.'));
-      const loader = loaders[ext];
-      if (loader) {
-        const docs = await loader.load(file);
-        all.push(...docs);
-      }
-    }
-    return all;
-  }
+/**
+ * Version: 0.1.0
+ * Path: /src/loader/directory-loader.js
+ * Description: Recursive directory loader with file type routing
+ * Author: Ali Kahwaji
+ */
+
+import fg from 'fast-glob';
+import { MarkdownLoader } from './markdown-loader.js';
+import { HTMLLoader } from './html-loader.js';
+import { CSVLoader } from './csv-loader.js';
+
+const loaders = {
+  '.md': new MarkdownLoader(),
+  '.html': new HTMLLoader(),
+  '.csv': new CSVLoader()
+};
+
+export class DirectoryLoader {
+  /**
+   * Load and route supported files from a directory
+   * @param {string} dirPath
+   * @returns {Promise<Array<{ chunk(): string[] }>>}
+   */
+  async load(dirPath) {
+    const matches = await fg([`${dirPath}/**/*.{md,html,csv}`]);
+    const all = [];
+    for (const file of matches) {
+      const ext = file.slice(file.lastIndexOf('.'));
+      const loader = loaders[ext];
+      if (loader) {
+        const docs = await loader.load(file);
+        all.push(...docs);
+      }
+    }
+    return all;
+  }
 }