@devilsdev/rag-pipeline-utils 2.1.7 → 2.1.8

package/src/config/validate-schema.js

@@ -1,107 +0,0 @@
-/**
- * Version: 1.3.0
- * Description: AJV-powered validators for .ragrc.json full config and plugin-only structure
- * Author: Ali Kahwaji
- * File: /src/config/validate-schema.js
- */
-
-import Ajv from 'ajv';
-
-/**
- * Full .ragrc.json schema (used in load-config.js)
- */
-const ragrcSchema = {
-  type: 'object',
-  required: ['loader', 'embedder', 'retriever', 'llm', 'namespace', 'pipeline'],
-  properties: {
-    loader: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    embedder: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    retriever: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    llm: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    namespace: {
-      type: 'string',
-      minLength: 1
-    },
-    pipeline: {
-      type: 'array',
-      items: {
-        type: 'string',
-        enum: ['loader', 'embedder', 'retriever']
-      },
-      minItems: 1,
-      uniqueItems: true
-    }
-  },
-  additionalProperties: false
-};
-
-/**
- * Minimal plugin-only schema (used in load-plugin-config.js)
- */
-const pluginSchema = {
-  type: 'object',
-  required: ['loader', 'embedder', 'retriever', 'llm'],
-  properties: {
-    loader: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    embedder: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    retriever: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    llm: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    }
-  },
-  additionalProperties: true // allow namespace, pipeline, etc.
-};
-
-/**
- * Validates the full .ragrc.json config structure
- * @param {object} config
- * @returns {{ valid: boolean, errors?: any[] }}
- */
-export function validateRagrcSchema(config) {
-  const ajv = new Ajv({ allErrors: true });
-  const validate = ajv.compile(ragrcSchema);
-  const valid = validate(config);
-  return valid ? { valid: true } : { valid: false, errors: validate.errors };
-}
-
-/**
- * Validates a plugin-only structure (for runtime plugin loading)
- * @param {object} config
- * @returns {{ valid: boolean, errors?: any[] }}
- */
-export function validatePluginSchema(config) {
-  const ajv = new Ajv({ allErrors: true });
-  const validate = ajv.compile(pluginSchema);
-  const valid = validate(config);
-  return valid ? { valid: true } : { valid: false, errors: validate.errors };
-}

package/src/core/create-pipeline.js

@@ -1,96 +0,0 @@
-/**
- * Version: 0.2.0
- * Path: /src/core/create-pipeline.js
- * Description: RAG pipeline factory with modular retry, logging, and reranker middleware
- * Author: Ali Kahwaji
- */
-
-import registry from './plugin-registry.js'; 
-import { logger } from '../utils/logger.js';
-import { withRetry } from '../utils/retry.js';
-import { LLMReranker } from '../reranker/llm-reranker.js';
-
-/**
- * Pipeline options to toggle middleware.
- * @typedef {Object} PipelineOptions
- * @property {boolean} [useRetry=true] - Enable retry logic on network/storage.
- * @property {boolean} [useLogging=true] - Enable structured logging.
- * @property {boolean} [useReranker=false] - Use reranker for query refinement.
- */
-
-/**
- * Creates a RAG pipeline instance.
- * @param {object} config - Pipeline configuration.
- * @param {string} config.loader
- * @param {string} config.embedder
- * @param {string} config.retriever
- * @param {string} config.llm
- * @param {PipelineOptions} [options]
- * @returns {object} RAG pipeline instance
- */
-export function createRagPipeline(
-  { loader, embedder, retriever, llm },
-  { useRetry = true, useLogging = true, useReranker = false } = {}
-) {
-  const loaderInstance = registry.get('loader', loader);
-  const embedderInstance = registry.get('embedder', embedder);
-  const retrieverInstance = registry.get('retriever', retriever);
-  const llmInstance = registry.get('llm', llm);
-  const rerankerInstance = useReranker ? new LLMReranker({ llm: llmInstance }) : null;
-
-  const log = (level, msg, data = {}) => {
-    if (useLogging) logger[level](data, msg);
-  };
-
-  const wrap = async (fn, context) => {
-    return useRetry ? withRetry(fn, context) : fn();
-  };
-
-  return {
-    async ingest(docPath) {
-      log('info', 'Pipeline ingest start', { loader, embedder, retriever });
-
-      const documents = await loaderInstance.load(docPath);
-      const chunks = documents.flatMap(doc => doc.chunk());
-      const vectors = await embedderInstance.embed(chunks);
-
-      await wrap(() => retrieverInstance.store(vectors), {
-        label: 'vector-store',
-        retries: 3,
-        initialDelay: 500
-      });
-
-      log('info', 'Ingestion pipeline completed');
-    },
-
-    async query(prompt) {
-      log('info', 'Pipeline query start', { prompt, embedder, retriever, llm, useReranker });
-
-      const queryVector = await embedderInstance.embedQuery(prompt);
-      let retrieved = await wrap(() => retrieverInstance.retrieve(queryVector), {
-        label: 'vector-retrieve',
-        retries: 3,
-        initialDelay: 500
-      });
-
-      if (rerankerInstance) {
-        log('info', 'Applying LLM reranker to retrieved chunks');
-        retrieved = await wrap(() => rerankerInstance.rerank(prompt, retrieved), {
-          label: 'rerank',
-          retries: 2,
-          initialDelay: 400
-        });
-      }
-
-      const result = await wrap(() => llmInstance.generate(prompt, retrieved), {
-        label: 'llm-generate',
-        retries: 3,
-        initialDelay: 500
-      });
-
-      return result;
-    }
-  };
-}
-
-export { registry };

package/src/core/plugin-contracts.js

@@ -1,21 +0,0 @@
-/**
- * Version: 1.0.0
- * Description: Shared plugin interface contracts for runtime + CI mock validation
- * Author: Ali Kahwaji
- */
-
-export const pluginContracts = {
-    loader: {
-      requiredMethods: ['load'],
-    },
-    embedder: {
-      requiredMethods: ['embed', 'embedQuery'],
-    },
-    retriever: {
-      requiredMethods: ['store', 'search'],
-    },
-    llm: {
-      requiredMethods: ['ask'],
-    },
-  };
-  

package/src/core/plugin-registry.js

@@ -1,48 +0,0 @@
-/**
- * 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 +0,0 @@
-/**
- * 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 +0,0 @@
-/**
- * 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 +0,0 @@
-/**
- * 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 +0,0 @@
-/**
- * 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 +0,0 @@
-/**
- * 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;
-  }
-}

package/src/loader/html-loader.js

@@ -1,57 +0,0 @@
-/**
- * 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 +0,0 @@
-/**
- * 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

@@ -1,30 +0,0 @@
-/**
- * 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

@@ -1,18 +0,0 @@
-/**
- * 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(', ')}`;
-    }
-  }