@devilsdev/rag-pipeline-utils 1.0.1 → 2.0.1

package/scripts/repair-fixtures.js

@@ -0,0 +1,30 @@
+/**
+ * Version: 1.0.0
+ * Description: Auto-repairs mock plugin fixtures for integration tests
+ * Author: Ali Kahwaji
+ */
+
+import { mkdirSync, copyFileSync, existsSync } from 'fs';
+import { resolve, join } from 'path';
+
+const MOCKS = [
+  'pdf-loader.js',
+  'openai-embedder.js',
+  'pinecone-retriever.js',
+  'openai-llm.js'
+];
+
+const SRC_FIXTURES = resolve('__tests__/fixtures/src/mocks');
+const DEST_FIXTURES = resolve('__tests__/__temp__/cli-config-fallback/src/mocks');
+
+mkdirSync(DEST_FIXTURES, { recursive: true });
+
+MOCKS.forEach((file) => {
+  const src = join(SRC_FIXTURES, file);
+  const dest = join(DEST_FIXTURES, file);
+  if (!existsSync(src)) throw new Error(`[FIXTURE MISSING] ${src}`);
+  copyFileSync(src, dest);
+  console.log(`[COPIED] ${file}`);
+});
+
+console.log('✅ Fixture mocks successfully repaired.');

package/scripts/setup.js

@@ -1,7 +1,31 @@
+/**
+ * Version: 1.1.0
+ * Description: Test setup script to ensure fixtures exist and validate mocks before running tests.
+ * Author: Ali Kahwaji
+ */
+
 import fs from 'fs';
-const fixturePath = './__tests__/fixtures/sample.pdf';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+// Resolve __dirname in ES module scope
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const fixturePath = path.resolve(__dirname, '../__tests__/fixtures/sample.pdf');
 
+// Ensure PDF test fixture
 if (!fs.existsSync(fixturePath)) {
-  fs.mkdirSync('./__tests__/fixtures', { recursive: true });
+  fs.mkdirSync(path.dirname(fixturePath), { recursive: true });
   fs.writeFileSync(fixturePath, 'Dummy PDF content for test');
+  console.log('[setup] Created sample.pdf fixture');
+}
+
+// Validate plugin fixture presence
+try {
+  execSync('node ./scripts/verify-fixtures.js', { stdio: 'inherit' });
+} catch (err) {
+  console.error('[setup] Fixture verification failed. Please check missing mocks.');
+  process.exit(1);
 }

package/scripts/validate-changelog-version.js

@@ -0,0 +1,48 @@
+/**
+ * Version: 1.1.0
+ * Description: Ensures CHANGELOG.md contains the current version and auto-corrects format if needed.
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json')));
+const version = pkg.version;
+const changelogPath = path.resolve(__dirname, '../CHANGELOG.md');
+
+let changelog = fs.readFileSync(changelogPath, 'utf-8');
+
+// Step 1: Normalize invalid headings like "# [2.0.0](...)"
+const normalized = changelog.replace(/^# \[([0-9]+\.[0-9]+\.[0-9]+)\]\([^)]+\)/gm, (match, v) => {
+  const today = new Date().toISOString().split('T')[0];
+  return `## [${v}] - ${today}`;
+});
+
+// Step 2: Update file if normalization occurred
+if (normalized !== changelog) {
+  fs.writeFileSync(changelogPath, normalized);
+  console.log(`🛠️  CHANGELOG.md heading normalized for version ${version}`);
+  changelog = normalized;
+
+  // Auto-stage if in git project (Husky compatibility)
+  try {
+    execSync(`git add ${changelogPath}`);
+    console.log('CHANGELOG.md staged after correction');
+  } catch {
+    // Non-fatal
+  }
+}
+
+// Step 3: Validate presence of correct heading
+const headingPattern = new RegExp(`^## \\[${version}\\]`, 'm');
+if (!headingPattern.test(changelog)) {
+  throw new Error(`❌ CHANGELOG.md does not contain a properly formatted entry for version ${version}`);
+}
+
+console.log(`✅ CHANGELOG.md contains a valid entry for version ${version}`);

package/scripts/verify-fixture-mocks.js

@@ -0,0 +1,45 @@
+/**
+ * Version: 1.0.0
+ * Description: Verifies that plugin mock implementations expose required methods
+ * Author: Ali Kahwaji
+ */
+
+import { readdirSync, statSync } from 'fs';
+import { resolve, join, extname } from 'path';
+import { pathToFileURL } from 'url';
+
+const MOCKS_DIR = resolve('__tests__/fixtures/src/mocks');
+
+const pluginContracts = {
+  'openai-embedder.js': ['embed', 'embedQuery'],
+  'openai-llm.js': ['ask'],
+  'pdf-loader.js': ['load'],
+  'pinecone-retriever.js': ['store', 'search'],
+};
+
+const failures = [];
+
+for (const file of readdirSync(MOCKS_DIR)) {
+  const fullPath = join(MOCKS_DIR, file);
+  const isFile = statSync(fullPath).isFile();
+  if (!isFile || extname(file) !== '.js') continue;
+
+  const expectedMethods = pluginContracts[file];
+  if (!expectedMethods) continue;
+
+  const mod = await import(pathToFileURL(fullPath).href);
+  const plugin = new mod.default();
+
+  for (const method of expectedMethods) {
+    if (typeof plugin[method] !== 'function') {
+      failures.push(`❌ ${file} failed: [${file}] missing method: ${method}`);
+    }
+  }
+}
+
+if (failures.length > 0) {
+  failures.forEach(msg => console.error(msg));
+  process.exit(1);
+} else {
+  console.log('✅ All plugin mocks verified.');
+}

package/scripts/verify-fixtures.js

@@ -0,0 +1,36 @@
+/**
+ * Version: 1.0.0
+ * Description: Script to verify presence of all expected fixture plugins before running integration tests.
+ * Author: Ali Kahwaji
+ * File: scripts/verify-fixtures.js
+ */
+
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+
+const REQUIRED_FIXTURES = [
+  '__tests__/fixtures/sample.pdf',
+  '__tests__/fixtures/.ragrc.json',
+  '__tests__/fixtures/src/mocks/pdf-loader.js',
+  '__tests__/fixtures/src/mocks/openai-embedder.js',
+  '__tests__/fixtures/src/mocks/pinecone-retriever.js',
+  '__tests__/fixtures/src/mocks/openai-llm.js'
+];
+
+let missing = [];
+for (const file of REQUIRED_FIXTURES) {
+  const fullPath = resolve(file);
+  if (!existsSync(fullPath)) {
+    missing.push(fullPath);
+  }
+}
+
+if (missing.length) {
+  console.error('[ERROR] Missing test fixture files:');
+  for (const f of missing) {
+    console.error(' -', f);
+  }
+  process.exit(1);
+} else {
+  console.log('[OK] All fixture files are present.');
+}

package/src/config/load-config.js

@@ -1,35 +1,33 @@
 /**
- * Version: 0.1.0
- * Path: /src/config/load-config.js
- * Description: Loader and validator for `.ragrc.json` configuration files
+ * Version: 1.1.0
+ * Description: Loads validated .ragrc.json config from disk
  * Author: Ali Kahwaji
  */
 
 import fs from 'fs';
 import path from 'path';
-import { validate } from './validate-schema.js';
-
-const DEFAULT_CONFIG_FILE = '.ragrc.json';
+import { validateRagrcSchema } from './validate-schema.js';
+import { logger } from '../utils/logger.js';
 
 /**
- * Load and validate the RAG configuration from a file.
- *
- * @param {string} [configPath] - Optional custom config path
- * @returns {object} - Validated config object
- * @throws {Error} - If file not found or validation fails
+ * Loads and validates a RAG config file.
+ * @param {string} configPath - Absolute path to .ragrc.json
+ * @returns {object} Parsed config object
+ * @throws {Error} If file is missing or invalid
  */
-export function loadRagConfig(configPath = DEFAULT_CONFIG_FILE) {
-  const fullPath = path.resolve(process.cwd(), configPath);
-
-  if (!fs.existsSync(fullPath)) {
-    throw new Error(`Config file not found: ${fullPath}`);
+export function loadRagConfig(configPath) {
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Config file not found: ${configPath}`);
   }
 
-  const raw = fs.readFileSync(fullPath, 'utf-8');
-  const config = JSON.parse(raw);
+  const raw = fs.readFileSync(configPath, 'utf-8');
+  const parsed = JSON.parse(raw);
 
-  validate(config); // Throws if invalid
+  const result = validateRagrcSchema(parsed);
+  if (!result.valid) {
+    logger.error({ errors: result.errors }, 'Invalid .ragrc.json schema');
+    throw new Error('Config validation failed');
+  }
 
-  return config;
+  return parsed;
 }
-

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;