@devilsdev/rag-pipeline-utils 1.0.1 → 2.0.0

package/src/config/load-plugin-config.js

@@ -0,0 +1,56 @@
+/**
+ * Version: 1.1.1
+ * Description: Dynamic plugin loader with direct type:name registry mapping
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import registry from '../core/plugin-registry.js';
+import { validatePluginSchema } from './validate-schema.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Loads plugins from validated config path and registers them.
+ * @param {string} configPath
+ */
+export async function loadPluginsFromJson(configPath) {
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Plugin config missing: ${configPath}`);
+  }
+
+  const raw = fs.readFileSync(configPath, 'utf-8');
+  const config = JSON.parse(raw);
+
+  const validation = validatePluginSchema(config);
+  if (!validation.valid) {
+    logger.error({ errors: validation.errors }, 'Invalid plugin config');
+    throw new Error('Plugin config validation failed');
+  }
+
+  for (const [type, namedPlugins] of Object.entries(config)) {
+    if (!['loader', 'embedder', 'retriever', 'llm'].includes(type)) continue;
+
+    for (const [name, relPath] of Object.entries(namedPlugins)) {
+      const absPath = path.resolve(path.dirname(configPath), relPath);
+      const fileUrl = pathToFileURL(absPath).href;
+
+      try {
+        const mod = await import(fileUrl);
+        const PluginClass = mod?.default;
+        if (typeof PluginClass !== 'function') {
+          throw new Error(`Invalid export in plugin [${type}:${name}] at ${absPath}`);
+        }
+
+        const instance = new PluginClass();
+        registry.register(type, name, instance);
+
+        logger.info({ type, name }, `Registered plugin: ${type}:${name}`);
+      } catch (err) {
+        logger.error({ type, name, err }, `Failed to register plugin [${type}:${name}]`);
+        throw err;
+      }
+    }
+  }
+}

package/src/config/validate-plugin-schema.js

@@ -0,0 +1,28 @@
+/**
+ * Version: 0.1.0
+ * Description: Schema validator for plugin.config.json
+ * Author: Ali Kahwaji
+ */
+
+export function validatePluginSchema(config) {
+    const validTypes = ['loader', 'embedder', 'retriever', 'llm'];
+    const errors = [];
+  
+    for (const type of Object.keys(config)) {
+      if (!validTypes.includes(type)) {
+        errors.push(`Unknown plugin type: ${type}`);
+        continue;
+      }
+      for (const [name, modulePath] of Object.entries(config[type])) {
+        if (typeof name !== 'string' || typeof modulePath !== 'string') {
+          errors.push(`Invalid plugin definition for type "${type}" and name "${name}"`);
+        }
+      }
+    }
+  
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+  

package/src/config/validate-schema.js

@@ -1,49 +1,107 @@
 /**
- * Version: 0.1.0
- * Path: /src/config/validate-schema.js
- * Description: JSON schema validation for `.ragrc.json` config using AJV
+ * 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';
 
-// Define allowed config structure
-const schema = {
+/**
+ * Full .ragrc.json schema (used in load-config.js)
+ */
+const ragrcSchema = {
   type: 'object',
+  required: ['loader', 'embedder', 'retriever', 'llm', 'namespace', 'pipeline'],
   properties: {
-    loader: { type: 'string' },
-    embedder: { type: 'string' },
-    retriever: { type: 'string' },
-    llm: { type: 'string' },
-    chunk: {
-      type: 'object',
-      properties: {
-        strategy: { type: 'string' },
-        size: { type: 'number' }
+    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']
       },
-      required: ['strategy', 'size'],
-      additionalProperties: false
+      minItems: 1,
+      uniqueItems: true
     }
   },
-  required: ['loader', 'embedder', 'retriever', 'llm'],
   additionalProperties: false
 };
 
-const ajv = new Ajv();
-const validateSchema = ajv.compile(schema);
+/**
+ * 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 a given config object against the `.ragrc.json` schema.
- * Throws if the schema is invalid.
- *
- * @param {object} config - Configuration object
- * @throws {Error} - Validation errors, if any
+ * Validates the full .ragrc.json config structure
+ * @param {object} config
+ * @returns {{ valid: boolean, errors?: any[] }}
  */
-export function validate(config) {
-  const valid = validateSchema(config);
-  if (!valid) {
-    const messages = validateSchema.errors.map(e => `${e.instancePath} ${e.message}`).join(', ');
-    throw new Error(`Invalid config: ${messages}`);
-  }
+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,73 +1,88 @@
 /**
- * Version: 0.1.3
+ * Version: 0.2.0
  * Path: /src/core/create-pipeline.js
- * Description: RAG pipeline factory with optional LLM reranker integration
+ * Description: RAG pipeline factory with modular retry, logging, and reranker middleware
  * Author: Ali Kahwaji
  */
 
-import { PluginRegistry } from './plugin-registry.js';
+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';
 
-const registry = new PluginRegistry();
+/**
+ * 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.
+ */
 
 /**
- * Create a RAG pipeline instance using registered plugin components
- * @param {object} config
+ * 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 {boolean} [config.useReranker=false]
+ * @param {PipelineOptions} [options]
  * @returns {object} RAG pipeline instance
  */
-export function createRagPipeline({ loader, embedder, retriever, llm, useReranker = false }) {
-  const rerankerInstance = useReranker ? new LLMReranker({ llm: registry.get('llm', llm) }) : null;
+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(path) {
-      logger.info({ loader, embedder, retriever }, 'Pipeline ingest start');
-      const loaderInstance = registry.get('loader', loader);
-      const embedderInstance = registry.get('embedder', embedder);
-      const retrieverInstance = registry.get('retriever', retriever);
+    async ingest(docPath) {
+      log('info', 'Pipeline ingest start', { loader, embedder, retriever });
 
-      const documents = await loaderInstance.load(path);
+      const documents = await loaderInstance.load(docPath);
       const chunks = documents.flatMap(doc => doc.chunk());
       const vectors = await embedderInstance.embed(chunks);
 
-      await withRetry(() => retrieverInstance.store(vectors), {
+      await wrap(() => retrieverInstance.store(vectors), {
         label: 'vector-store',
         retries: 3,
         initialDelay: 500
       });
 
-      logger.info('Ingestion pipeline completed');
+      log('info', 'Ingestion pipeline completed');
     },
 
     async query(prompt) {
-      logger.info({ prompt, embedder, retriever, llm, useReranker }, 'Pipeline query start');
-      const embedderInstance = registry.get('embedder', embedder);
-      const retrieverInstance = registry.get('retriever', retriever);
-      const llmInstance = registry.get('llm', llm);
+      log('info', 'Pipeline query start', { prompt, embedder, retriever, llm, useReranker });
 
       const queryVector = await embedderInstance.embedQuery(prompt);
-      let retrieved = await withRetry(() => retrieverInstance.retrieve(queryVector), {
+      let retrieved = await wrap(() => retrieverInstance.retrieve(queryVector), {
         label: 'vector-retrieve',
         retries: 3,
         initialDelay: 500
       });
 
       if (rerankerInstance) {
-        logger.info('Applying LLM reranker to retrieved chunks');
-        retrieved = await withRetry(() => rerankerInstance.rerank(prompt, retrieved), {
+        log('info', 'Applying LLM reranker to retrieved chunks');
+        retrieved = await wrap(() => rerankerInstance.rerank(prompt, retrieved), {
           label: 'rerank',
           retries: 2,
           initialDelay: 400
         });
       }
 
-      const result = await withRetry(() => llmInstance.generate(prompt, retrieved), {
+      const result = await wrap(() => llmInstance.generate(prompt, retrieved), {
         label: 'llm-generate',
         retries: 3,
         initialDelay: 500
@@ -79,4 +94,3 @@ export function createRagPipeline({ loader, embedder, retriever, llm, useReranke
 }
 
 export { registry };
-

package/src/core/plugin-contracts.js

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

@@ -14,12 +14,6 @@ export class PluginRegistry {
     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) {
@@ -28,12 +22,6 @@ export class PluginRegistry {
     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) {
@@ -46,11 +34,6 @@ export class PluginRegistry {
     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) {
@@ -59,3 +42,7 @@ export class PluginRegistry {
     return [...group.keys()];
   }
 }
+
+const registry = new PluginRegistry();
+
+export default registry;

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
+ * Version: 1.0.4
+ * Description: LLM reranker using LLM to reorder documents based on relevance
+ * Author: devilsdev
+ * File: src/reranker/llm-reranker.js
  */
 
-/**
- * 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);
+  /**
+   * @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/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)
+ */