@devilsdev/rag-pipeline-utils 2.5.0 → 2.6.0

package/src/cache/memory-cache.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * In-process cache with least-recently-used eviction and per-entry time to
+ * live. Implements the CacheBackend contract:
+ *
+ *   get(key) -> Promise<value | undefined>
+ *   set(key, value, { ttlSeconds }) -> Promise<void>
+ *   delete(key) -> Promise<void>
+ *   stats() -> Promise<{ hits, misses, size }>
+ *
+ * Values are stored as JSON copies, so later changes to a returned value do
+ * not change the cache (the same behaviour as RedisCache).
+ */
+class MemoryCache {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.maxEntries=1000] - Entries kept before the least
+   *   recently used is evicted
+   * @param {number} [options.ttlSeconds] - Default time to live; none means
+   *   entries never expire on their own
+   */
+  constructor({ maxEntries = 1000, ttlSeconds } = {}) {
+    if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+      throw new Error('maxEntries must be a positive integer');
+    }
+    this.maxEntries = maxEntries;
+    this.ttlSeconds = ttlSeconds;
+    this._entries = new Map(); // insertion order = recency order
+    this._hits = 0;
+    this._misses = 0;
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<unknown|undefined>}
+   */
+  async get(key) {
+    const entry = this._entries.get(key);
+    if (!entry || (entry.expiresAt !== null && entry.expiresAt <= Date.now())) {
+      if (entry) this._entries.delete(key);
+      this._misses += 1;
+      return undefined;
+    }
+    // Move to the most recently used position.
+    this._entries.delete(key);
+    this._entries.set(key, entry);
+    this._hits += 1;
+    return JSON.parse(entry.json);
+  }
+
+  /**
+   * @param {string} key
+   * @param {unknown} value - JSON-serialisable value
+   * @param {{ ttlSeconds?: number }} [options]
+   * @returns {Promise<void>}
+   */
+  async set(key, value, { ttlSeconds = this.ttlSeconds } = {}) {
+    const json = JSON.stringify(value);
+    if (json === undefined) return;
+    this._entries.delete(key);
+    this._entries.set(key, {
+      json,
+      expiresAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : null,
+    });
+    while (this._entries.size > this.maxEntries) {
+      this._entries.delete(this._entries.keys().next().value);
+    }
+  }
+
+  /** @param {string} key */
+  async delete(key) {
+    this._entries.delete(key);
+  }
+
+  /** Remove every entry. */
+  async clear() {
+    this._entries.clear();
+  }
+
+  /** @returns {Promise<{ hits: number, misses: number, size: number }>} */
+  async stats() {
+    return { hits: this._hits, misses: this._misses, size: this._entries.size };
+  }
+}
+
+module.exports = { MemoryCache };

package/src/cache/pipeline-cache.js

@@ -0,0 +1,260 @@
+'use strict';
+
+/**
+ * Caching for createRagPipeline({ cache }): three opt-in layers.
+ *
+ * - embeddings: the query vector, keyed by the embedder's identity and the
+ *   query text.
+ * - retrieval: the retriever's raw results, keyed by the retriever's state,
+ *   the query and topK. Cached before `filterResults` (guardrail ACLs) and
+ *   the reranker, so those still run on every request and one user's
+ *   permissions can never shape another user's results.
+ * - generation: the answer, keyed by the llm's identity, the query, the
+ *   exact documents it was given and the generation options. Skipped when
+ *   the temperature is above 0.
+ *
+ * A layer caches only when its component identifies itself through
+ * `getCacheKey(role)` or a `cacheKey` string (the built-ins do), so a cache
+ * can never return results for a different model, index or configuration.
+ * Only successful, completed work is stored: nothing from an aborted or
+ * timed-out run.
+ */
+
+const crypto = require('crypto');
+const { MemoryCache } = require('./memory-cache');
+
+const LAYERS = ['embeddings', 'retrieval', 'generation'];
+const DEFAULT_TTL_SECONDS = {
+  embeddings: 30 * 24 * 3600,
+  retrieval: 3600,
+  generation: 24 * 3600,
+};
+const ROLE = {
+  embeddings: 'embedder',
+  retrieval: 'retriever',
+  generation: 'llm',
+};
+
+/** Generation options that change the answer and so belong in its key. */
+const GENERATION_OPTIONS = [
+  'temperature',
+  'maxTokens',
+  'maxOutputTokens',
+  'topP',
+  'model',
+  'systemPrompt',
+  'seed',
+  'stopSequences',
+];
+
+function hash(value) {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(value))
+    .digest('hex');
+}
+
+function isBackend(value) {
+  return (
+    value && typeof value.get === 'function' && typeof value.set === 'function'
+  );
+}
+
+/** A component's identity for a role, or null when it has none. */
+function componentKey(component, role) {
+  if (!component) return null;
+  if (typeof component.getCacheKey === 'function') {
+    const key = component.getCacheKey(role);
+    return typeof key === 'string' && key ? key : null;
+  }
+  return typeof component.cacheKey === 'string' && component.cacheKey
+    ? component.cacheKey
+    : null;
+}
+
+const warned = new Set();
+function warnOnce(code, message) {
+  if (warned.has(code)) return;
+  warned.add(code);
+  process.emitWarning(message, { type: 'RagCacheWarning', code });
+}
+
+/**
+ * Normalise the `cache` option of createRagPipeline.
+ *
+ * - `true`: all three layers in one in-memory cache
+ * - a CacheBackend: all three layers in it
+ * - `{ embeddings, retrieval, generation, ttlSeconds }`: per layer, each
+ *   `true` (in-memory), `false`/absent (off) or a CacheBackend;
+ *   `ttlSeconds: { embeddings, retrieval, generation }` overrides the
+ *   defaults (30 days, 1 hour, 24 hours)
+ *
+ * @returns {Object|null} Layer config, or null when caching is off
+ */
+function normalizeCacheOption(option) {
+  if (!option) return null;
+  const shared =
+    option === true ? new MemoryCache() : isBackend(option) ? option : null;
+  const layers = {};
+  for (const layer of LAYERS) {
+    let backend = null;
+    if (shared) {
+      backend = shared;
+    } else if (option[layer] === true) {
+      backend = new MemoryCache();
+    } else if (isBackend(option[layer])) {
+      backend = option[layer];
+    }
+    if (backend) {
+      layers[layer] = {
+        backend,
+        ttlSeconds:
+          (option.ttlSeconds && option.ttlSeconds[layer]) ??
+          DEFAULT_TTL_SECONDS[layer],
+        hits: 0,
+        misses: 0,
+        skipped: 0,
+      };
+    }
+  }
+  return Object.keys(layers).length ? layers : null;
+}
+
+/**
+ * Per-pipeline cache. Every method returns undefined and does nothing for a
+ * layer that is off or whose component has no cache key.
+ */
+class PipelineCache {
+  /**
+   * @param {Object} layers - normalizeCacheOption() output
+   * @param {{ embedder?: Object, retriever?: Object, llm?: Object }} components
+   */
+  constructor(layers, components) {
+    this.layers = layers;
+    this.components = components;
+  }
+
+  /** @private */
+  _key(layer, parts) {
+    const config = this.layers[layer];
+    if (!config) return null;
+    const component = this.components[ROLE[layer]];
+    const id = componentKey(component, ROLE[layer]);
+    if (!id) {
+      config.skipped += 1;
+      warnOnce(
+        `RAG_CACHE_NO_KEY_${layer.toUpperCase()}`,
+        `The ${layer} cache is off for this ${ROLE[layer]}: it has no getCacheKey(role) method or cacheKey string, so cached results could not be told apart from another configuration's. Add one to enable it.`,
+      );
+      return null;
+    }
+    return `${layer}:${hash([id, parts])}`;
+  }
+
+  /** @private */
+  async _get(layer, key, status) {
+    if (!key) {
+      status[layer] = 'skip';
+      return undefined;
+    }
+    const config = this.layers[layer];
+    let value;
+    try {
+      value = await config.backend.get(key);
+    } catch (error) {
+      // A cache outage must not fail the run.
+      warnOnce('RAG_CACHE_READ_FAILED', `Cache read failed: ${error.message}`);
+      value = undefined;
+    }
+    if (value === undefined) {
+      config.misses += 1;
+      status[layer] = 'miss';
+    } else {
+      config.hits += 1;
+      status[layer] = 'hit';
+    }
+    return value;
+  }
+
+  /** @private */
+  async _set(layer, key, value) {
+    if (!key || value === undefined) return;
+    const config = this.layers[layer];
+    try {
+      await config.backend.set(key, value, { ttlSeconds: config.ttlSeconds });
+    } catch (error) {
+      warnOnce(
+        'RAG_CACHE_WRITE_FAILED',
+        `Cache write failed: ${error.message}`,
+      );
+    }
+  }
+
+  embeddingKey(query) {
+    return this._key('embeddings', { query });
+  }
+
+  retrievalKey({ query, queryVector, topK }) {
+    // Keyed on the query vector, not just the text, so a different embedder
+    // (or a retrained one) never gets another embedder's results; the text
+    // stays in the key for keyword and hybrid retrievers.
+    return this._key('retrieval', {
+      query: query ?? null,
+      vector: queryVector ? hash(queryVector) : null,
+      topK,
+    });
+  }
+
+  /**
+   * @returns {string|null} The key, or null to skip (temperature above 0,
+   *   or no llm cache key)
+   */
+  generationKey({ query, docs, options }) {
+    if (!this.layers.generation) return null;
+    const llm = this.components.llm;
+    const temperature =
+      options.temperature ?? (llm && llm.config && llm.config.temperature);
+    if (typeof temperature === 'number' && temperature > 0) {
+      this.layers.generation.skipped += 1;
+      return null;
+    }
+    const generationOptions = {};
+    for (const name of GENERATION_OPTIONS) {
+      if (options[name] !== undefined) generationOptions[name] = options[name];
+    }
+    const context = (docs || []).map((d) =>
+      typeof d === 'string' ? d : [d.id ?? null, d.content ?? d.text ?? ''],
+    );
+    return this._key('generation', {
+      query,
+      context: hash(context),
+      options: generationOptions,
+    });
+  }
+
+  get(layer, key, status) {
+    if (!this.layers[layer]) return Promise.resolve(undefined);
+    return this._get(layer, key, status);
+  }
+
+  set(layer, key, value) {
+    if (!this.layers[layer]) return Promise.resolve();
+    return this._set(layer, key, value);
+  }
+
+  /** Hits, misses and skips per layer since the pipeline was created. */
+  stats() {
+    const out = {};
+    for (const [layer, c] of Object.entries(this.layers)) {
+      out[layer] = { hits: c.hits, misses: c.misses, skipped: c.skipped };
+    }
+    return out;
+  }
+}
+
+module.exports = {
+  normalizeCacheOption,
+  PipelineCache,
+  componentKey,
+  DEFAULT_TTL_SECONDS,
+};

package/src/cache/redis-cache.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * CacheBackend on Redis. Pass a connected client from `redis` (node-redis 4
+ * and later) or `ioredis`; neither is a dependency of this package.
+ *
+ * Values are stored as JSON under `prefix + key`, with a millisecond expiry
+ * when a time to live applies.
+ */
+class RedisCache {
+  /**
+   * @param {Object} options
+   * @param {Object} options.client - Connected node-redis or ioredis client
+   * @param {string} [options.prefix='rag:'] - Key prefix
+   * @param {number} [options.ttlSeconds] - Default time to live
+   */
+  constructor({ client, prefix = 'rag:', ttlSeconds } = {}) {
+    if (
+      !client ||
+      typeof client.get !== 'function' ||
+      typeof client.set !== 'function'
+    ) {
+      throw new Error(
+        'RedisCache needs a connected client from "redis" or "ioredis"',
+      );
+    }
+    this.client = client;
+    this.prefix = prefix;
+    this.ttlSeconds = ttlSeconds;
+    // node-redis 4+ exposes isOpen and takes set(key, value, { PX }); ioredis
+    // takes set(key, value, 'PX', ms).
+    this._nodeRedis = typeof client.isOpen === 'boolean';
+    this._hits = 0;
+    this._misses = 0;
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Promise<unknown|undefined>}
+   */
+  async get(key) {
+    const raw = await this.client.get(this.prefix + key);
+    if (raw === null || raw === undefined) {
+      this._misses += 1;
+      return undefined;
+    }
+    this._hits += 1;
+    return JSON.parse(raw);
+  }
+
+  /**
+   * @param {string} key
+   * @param {unknown} value - JSON-serialisable value
+   * @param {{ ttlSeconds?: number }} [options]
+   */
+  async set(key, value, { ttlSeconds = this.ttlSeconds } = {}) {
+    const json = JSON.stringify(value);
+    if (json === undefined) return;
+    const k = this.prefix + key;
+    const ms = ttlSeconds > 0 ? Math.round(ttlSeconds * 1000) : 0;
+    if (!ms) {
+      await this.client.set(k, json);
+    } else if (this._nodeRedis) {
+      await this.client.set(k, json, { PX: ms });
+    } else {
+      await this.client.set(k, json, 'PX', ms);
+    }
+  }
+
+  /** @param {string} key */
+  async delete(key) {
+    const del = this.client.del || this.client.unlink;
+    if (typeof del === 'function')
+      await del.call(this.client, this.prefix + key);
+  }
+
+  /** Hits and misses seen by this instance (size is not tracked). */
+  async stats() {
+    return { hits: this._hits, misses: this._misses };
+  }
+}
+
+module.exports = { RedisCache };

package/src/cli/commands/ai.js

@@ -7,13 +7,9 @@
 
 const { Command, Option } = require("commander");
 const { parsePositiveInteger } = require("../shared/cli-utils.js");
-const {
-  handleTrainEmbedding,
-  handleBenchmark,
-  handleFeedback,
-  handleSearch,
-  handleMultimodalProcess,
-} = require("../handlers/ai-handler.js");
+// The handler (document loaders: jsdom, marked, csv-parse) loads when an
+// ai command runs, not when the CLI starts.
+const aiHandler = () => require("../handlers/ai-handler.js"); // eslint-disable-line global-require
 
 /**
  * @param {() => object} getGlobalOptions - Returns program.opts()
@@ -37,7 +33,7 @@ function createAiCommand(getGlobalOptions) {
       "Train on documents from this file or directory instead",
     )
     .action(async (inputPath) => {
-      await handleTrainEmbedding(getGlobalOptions(), inputPath);
+      await aiHandler().handleTrainEmbedding(getGlobalOptions(), inputPath);
     });
 
   ai.command("benchmark")
@@ -52,7 +48,7 @@ function createAiCommand(getGlobalOptions) {
     .option("--top-k <n>", "Passages to retrieve", parsePositiveInteger, 3)
     .option("--json", "Print the measurements as JSON")
     .action(async (options) => {
-      await handleBenchmark(getGlobalOptions(), options);
+      await aiHandler().handleBenchmark(getGlobalOptions(), options);
     });
 
   ai.command("feedback")
@@ -67,7 +63,12 @@ function createAiCommand(getGlobalOptions) {
         .makeOptionMandatory(),
     )
     .action(async (question, docId, options) => {
-      await handleFeedback(getGlobalOptions(), question, docId, options);
+      await aiHandler().handleFeedback(
+        getGlobalOptions(),
+        question,
+        docId,
+        options,
+      );
     });
 
   ai.command("search")
@@ -78,7 +79,7 @@ function createAiCommand(getGlobalOptions) {
     .option("--top-k <n>", "Passages to return", parsePositiveInteger, 3)
     .option("--json", "Print the results as JSON")
     .action(async (question, options) => {
-      await handleSearch(getGlobalOptions(), question, options);
+      await aiHandler().handleSearch(getGlobalOptions(), question, options);
     });
 
   const multimodal = ai
@@ -92,7 +93,11 @@ function createAiCommand(getGlobalOptions) {
     .argument("<path>", "File or directory")
     .option("--json", "Print the report as JSON")
     .action(async (inputPath, options) => {
-      await handleMultimodalProcess(getGlobalOptions(), inputPath, options);
+      await aiHandler().handleMultimodalProcess(
+        getGlobalOptions(),
+        inputPath,
+        options,
+      );
     });
 
   return ai;

package/src/cli/commands/plugin-hub.js

@@ -7,9 +7,14 @@ const { Command } = require("commander");
 const { PluginHub } = require("../../ecosystem/plugin-hub");
 const { PluginCertification } = require("../../ecosystem/plugin-certification");
 
-const hubCommands = require("./plugin-hub/hub-commands");
-const certificationCommands = require("./plugin-hub/certification-commands");
-const reviewCommands = require("./plugin-hub/review-commands");
+// Command modules (and inquirer, ora, cli-table3) load when a hub command
+// runs, not when the CLI starts.
+/* eslint-disable global-require */
+const hubCommands = () => require("./plugin-hub/hub-commands");
+const certificationCommands = () =>
+  require("./plugin-hub/certification-commands");
+const reviewCommands = () => require("./plugin-hub/review-commands");
+/* eslint-enable global-require */
 const { setupEventListeners } = require("./plugin-hub/event-handlers");
 const {
   installFromSource,
@@ -102,7 +107,7 @@ class PluginHubCLI {
         "relevance",
       )
       .action(async (query, _options) => {
-        await hubCommands.searchPlugins(this.hub, query, _options);
+        await hubCommands().searchPlugins(this.hub, query, _options);
       });
 
     program
@@ -128,7 +133,7 @@ class PluginHubCLI {
       .command("info <plugin>")
       .description("Get detailed information about a plugin")
       .action(async (plugin) => {
-        await hubCommands.getPluginInfo(this.hub, plugin);
+        await hubCommands().getPluginInfo(this.hub, plugin);
       });
 
     // List installed command
@@ -148,7 +153,7 @@ class PluginHubCLI {
       .option("--dry-run", "Validate without publishing")
       .option("--tag <tag>", "Release tag")
       .action(async (pluginPath, _options) => {
-        await hubCommands.publishPlugin(
+        await hubCommands().publishPlugin(
           this.hub,
           pluginPath || process.cwd(),
           _options,
@@ -161,7 +166,7 @@ class PluginHubCLI {
       .description("Rate a plugin (1-5 stars)")
       .option("-r, --review <review>", "Written review")
       .action(async (plugin, rating, _options) => {
-        await reviewCommands.ratePlugin(
+        await reviewCommands().ratePlugin(
           this.hub,
           plugin,
           parseInt(rating),
@@ -176,7 +181,7 @@ class PluginHubCLI {
       .option("-l, --limit <limit>", "Number of reviews", parseInt, 10)
       .option("--sort <sort>", "Sort by: helpful, recent, rating", "helpful")
       .action(async (plugin, _options) => {
-        await reviewCommands.getPluginReviews(this.hub, plugin, _options);
+        await reviewCommands().getPluginReviews(this.hub, plugin, _options);
       });
 
     // Trending command
@@ -187,7 +192,7 @@ class PluginHubCLI {
       .option("-c, --category <category>", "Filter by category")
       .option("-l, --limit <limit>", "Number of results", parseInt, 20)
       .action(async (_options) => {
-        await hubCommands.getTrendingPlugins(this.hub, _options);
+        await hubCommands().getTrendingPlugins(this.hub, _options);
       });
 
     // Certification commands
@@ -210,7 +215,7 @@ class PluginHubCLI {
       .command("verify <plugin> <certificationId>")
       .description("Verify plugin certification")
       .action(async (plugin, certificationId) => {
-        await certificationCommands.verifyCertification(
+        await certificationCommands().verifyCertification(
           this.certification,
           plugin,
           certificationId,
@@ -222,7 +227,7 @@ class PluginHubCLI {
       .description("Show certification requirements")
       .action(async (level) => {
         // Requirements are a static list; no registry is contacted.
-        await certificationCommands.showCertificationRequirements(
+        await certificationCommands().showCertificationRequirements(
           new PluginCertification(),
           level,
         );
@@ -237,7 +242,7 @@ class PluginHubCLI {
       .command("status [publisherId]")
       .description("Check publisher verification status")
       .action(async (publisherId) => {
-        await certificationCommands.getPublisherStatus(
+        await certificationCommands().getPublisherStatus(
           this.certification,
           publisherId,
         );
@@ -247,7 +252,7 @@ class PluginHubCLI {
       .command("apply")
       .description("Apply for publisher verification")
       .action(async () => {
-        await certificationCommands.applyForPublisherVerification(
+        await certificationCommands().applyForPublisherVerification(
           this.certification,
         );
       });