@devilsdev/rag-pipeline-utils 1.0.0 → 2.0.0

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/server.js

@@ -1,31 +1,31 @@
-/**
- * Version: 0.1.0
- * Path: /server.js
- * Description: Local static server for serving evaluation dashboard
- * Author: Ali Kahwaji
- */
-
-import express from 'express';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const app = express();
-const port = process.env.PORT || 3000;
-
-// Serve evaluation results statically
-app.use('/results', express.static(path.join(__dirname, '__tests__/fixtures')));
-
-// Serve public frontend assets
-app.use(express.static(path.join(__dirname, 'public')));
-
-// Fallback to index.html
-app.get('*', (req, res) => {
-  res.sendFile(path.join(__dirname, 'public/index.html'));
-});
-
-app.listen(port, () => {
-  console.log(` Dashboard running at http://localhost:${port}`);
-});
+/**
+ * Version: 0.1.0
+ * Path: /server.js
+ * Description: Local static server for serving evaluation dashboard
+ * Author: Ali Kahwaji
+ */
+
+import express from 'express';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+// Serve evaluation results statically
+app.use('/results', express.static(path.join(__dirname, '__tests__/fixtures')));
+
+// Serve public frontend assets
+app.use(express.static(path.join(__dirname, 'public')));
+
+// Fallback to index.html
+app.get('*', (req, res) => {
+  res.sendFile(path.join(__dirname, 'public/index.html'));
+});
+
+app.listen(port, () => {
+  console.log(` Dashboard running at http://localhost:${port}`);
+});

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
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs';
-import path from 'path';
-import { validate } from './validate-schema.js';
-
-const DEFAULT_CONFIG_FILE = '.ragrc.json';
-
-/**
- * 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
- */
-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}`);
-  }
-
-  const raw = fs.readFileSync(fullPath, 'utf-8');
-  const config = JSON.parse(raw);
-
-  validate(config); // Throws if invalid
-
-  return config;
-}
-
+/**
+ * Version: 1.1.0
+ * Description: Loads validated .ragrc.json config from disk
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { validateRagrcSchema } from './validate-schema.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * 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) {
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Config file not found: ${configPath}`);
+  }
+
+  const raw = fs.readFileSync(configPath, 'utf-8');
+  const parsed = JSON.parse(raw);
+
+  const result = validateRagrcSchema(parsed);
+  if (!result.valid) {
+    logger.error({ errors: result.errors }, 'Invalid .ragrc.json schema');
+    throw new Error('Config validation failed');
+  }
+
+  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
- * Author: Ali Kahwaji
- */
-
-import Ajv from 'ajv';
-
-// Define allowed config structure
-const schema = {
-  type: 'object',
-  properties: {
-    loader: { type: 'string' },
-    embedder: { type: 'string' },
-    retriever: { type: 'string' },
-    llm: { type: 'string' },
-    chunk: {
-      type: 'object',
-      properties: {
-        strategy: { type: 'string' },
-        size: { type: 'number' }
-      },
-      required: ['strategy', 'size'],
-      additionalProperties: false
-    }
-  },
-  required: ['loader', 'embedder', 'retriever', 'llm'],
-  additionalProperties: false
-};
-
-const ajv = new Ajv();
-const validateSchema = ajv.compile(schema);
-
-/**
- * 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
- */
-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}`);
-  }
-}
-
+/**
+ * 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,82 +1,96 @@
-/**
- * Version: 0.1.3
- * Path: /src/core/create-pipeline.js
- * Description: RAG pipeline factory with optional LLM reranker integration
- * Author: Ali Kahwaji
- */
-
-import { PluginRegistry } 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();
-
-/**
- * Create a RAG pipeline instance using registered plugin components
- * @param {object} config
- * @param {string} config.loader
- * @param {string} config.embedder
- * @param {string} config.retriever
- * @param {string} config.llm
- * @param {boolean} [config.useReranker=false]
- * @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;
-
-  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);
-
-      const documents = await loaderInstance.load(path);
-      const chunks = documents.flatMap(doc => doc.chunk());
-      const vectors = await embedderInstance.embed(chunks);
-
-      await withRetry(() => retrieverInstance.store(vectors), {
-        label: 'vector-store',
-        retries: 3,
-        initialDelay: 500
-      });
-
-      logger.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);
-
-      const queryVector = await embedderInstance.embedQuery(prompt);
-      let retrieved = await withRetry(() => 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), {
-          label: 'rerank',
-          retries: 2,
-          initialDelay: 400
-        });
-      }
-
-      const result = await withRetry(() => llmInstance.generate(prompt, retrieved), {
-        label: 'llm-generate',
-        retries: 3,
-        initialDelay: 500
-      });
-
-      return result;
-    }
-  };
-}
-
-export { registry };
-
+/**
+ * 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

@@ -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'],
+    },
+  };
+