@devilsdev/rag-pipeline-utils 2.3.0 → 2.4.0

package/src/agentic/agentic-pipeline.js

@@ -0,0 +1,235 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const { DAG } = require('../dag/dag-engine');
+const { QueryPlanner } = require('./query-planner');
+const { IterativeRetriever } = require('./iterative-retriever');
+const { SelfCritiqueChecker } = require('./self-critique');
+
+/**
+ * Default configuration for the AgenticPipeline.
+ * @type {object}
+ */
+const DEFAULT_CONFIG = {
+  maxConcurrency: 3,
+  timeout: 60000,
+  enablePlanning: true,
+  enableCritique: true,
+  enableIterativeRetrieval: false,
+  maxIterations: 3,
+  critiqueThreshold: 0.5,
+};
+
+/**
+ * DAG-based agentic RAG orchestrator with two-phase execution:
+ *   Phase 1 - Plan: decompose query into sub-queries
+ *   Phase 2 - Execute: build DAG of retrieve -> merge -> (critique ->) generate
+ *
+ * @extends EventEmitter
+ */
+class AgenticPipeline extends EventEmitter {
+  /**
+   * @param {object} [options] - Override default configuration
+   * @param {number} [options.maxConcurrency=3] - Max concurrent DAG node execution
+   * @param {number} [options.timeout=60000] - Global timeout in ms
+   * @param {boolean} [options.enablePlanning=true] - Whether to decompose queries
+   * @param {boolean} [options.enableCritique=true] - Whether to self-critique answers
+   * @param {boolean} [options.enableIterativeRetrieval=false] - Whether to use iterative retrieval
+   * @param {number} [options.maxIterations=3] - Max iterations for iterative retrieval
+   * @param {number} [options.critiqueThreshold=0.5] - Groundedness threshold for approval
+   * @param {object} [options.plannerOptions] - Options forwarded to QueryPlanner
+   * @param {object} [options.iterativeOptions] - Options forwarded to IterativeRetriever
+   */
+  constructor(options = {}) {
+    super();
+    this.config = { ...DEFAULT_CONFIG, ...options };
+    this.planner = new QueryPlanner(options.plannerOptions);
+    this.critiqueChecker = new SelfCritiqueChecker({
+      approvalThreshold: this.config.critiqueThreshold,
+    });
+    if (this.config.enableIterativeRetrieval) {
+      this.iterativeRetriever = new IterativeRetriever(
+        options.iterativeOptions,
+      );
+    }
+  }
+
+  /**
+   * Run the full agentic pipeline: plan -> retrieve -> merge -> (critique ->) generate.
+   *
+   * @param {object} params
+   * @param {string} params.query - The user query
+   * @param {object} params.retriever - Retriever instance with .retrieve() method
+   * @param {object} params.llm - LLM instance with .generate() method
+   * @param {Array<number>} [params.queryVector] - Optional pre-computed query vector
+   * @param {object} [params.options={}] - Extra options passed to llm.generate()
+   * @returns {Promise<{
+   *   success: boolean,
+   *   query: string,
+   *   answer: string,
+   *   results: Array<object>,
+   *   critique: object|null,
+   *   subQueries: Array<object>,
+   *   metadata: object
+   * }>}
+   * @throws {Error} If retriever or llm is missing
+   */
+  async run({ query, retriever, llm, queryVector, options = {} }) {
+    // 1. Validate inputs
+    if (!retriever || typeof retriever.retrieve !== 'function') {
+      throw new Error(
+        'AgenticPipeline.run(): retriever with .retrieve() method is required',
+      );
+    }
+    if (!llm || typeof llm.generate !== 'function') {
+      throw new Error(
+        'AgenticPipeline.run(): llm with .generate() method is required',
+      );
+    }
+    if (!query || typeof query !== 'string' || !query.trim()) {
+      throw new Error(
+        'AgenticPipeline.run(): query must be a non-empty string',
+      );
+    }
+
+    // Phase 1: Plan
+    let subQueries;
+    if (this.config.enablePlanning) {
+      const plan = this.planner.plan(query);
+      subQueries = plan.subQueries;
+      this.emit('planned', plan);
+    } else {
+      subQueries = [{ subQuery: query, strategy: 'general', priority: 0 }];
+    }
+
+    // Phase 2: Build and execute DAG
+    const dag = new DAG();
+
+    // Add retrieve nodes (one per sub-query)
+    for (let i = 0; i < subQueries.length; i++) {
+      const sq = subQueries[i];
+      dag.addNode(
+        `retrieve-${i}`,
+        async () => {
+          if (this.iterativeRetriever) {
+            const result = await this.iterativeRetriever.retrieve({
+              query: sq.subQuery,
+              retriever,
+              llm,
+              queryVector,
+            });
+            return result.results;
+          }
+          return await retriever.retrieve({
+            query: sq.subQuery,
+            queryVector,
+            topK: 10,
+          });
+        },
+        { timeout: this.config.timeout / 2, priority: sq.priority },
+      );
+    }
+
+    // Add merge node
+    dag.addNode('merge', async (inputs) => {
+      const allResults = Array.isArray(inputs)
+        ? inputs.flat()
+        : [inputs].flat();
+      // Deduplicate by id
+      const seen = new Map();
+      for (const r of allResults) {
+        if (r == null) continue;
+        const id = r?.id || JSON.stringify(r);
+        if (!seen.has(id) || (r.score && r.score > (seen.get(id).score || 0))) {
+          seen.set(id, r);
+        }
+      }
+      return Array.from(seen.values());
+    });
+
+    // Connect retrieve nodes to merge
+    for (let i = 0; i < subQueries.length; i++) {
+      dag.connect(`retrieve-${i}`, 'merge');
+    }
+
+    // Add critique + generate nodes
+    if (this.config.enableCritique) {
+      dag.addNode('pre-generate', async (mergedResults) => {
+        // Generate initial answer for critique
+        const answer = await llm.generate(query, mergedResults, options);
+        const critique = this.critiqueChecker.check(
+          String(answer),
+          mergedResults,
+        );
+        this.emit('critiqued', critique);
+        return { answer: String(answer), mergedResults, critique };
+      });
+      dag.connect('merge', 'pre-generate');
+
+      dag.addNode('generate', async ({ answer, mergedResults, critique }) => {
+        if (critique.approved) {
+          return { answer, results: mergedResults, critique };
+        }
+        // Re-generate with critique feedback
+        const issueTexts = critique.issues.map(
+          (i) => i.sentence || i.text || String(i),
+        );
+        const refinedPrompt = `${query}\n\nPrevious answer had issues: ${issueTexts.join('; ')}. Please provide a more grounded answer.`;
+        const refinedAnswer = await llm.generate(
+          refinedPrompt,
+          mergedResults,
+          options,
+        );
+        return {
+          answer: String(refinedAnswer),
+          results: mergedResults,
+          critique,
+        };
+      });
+      dag.connect('pre-generate', 'generate');
+    } else {
+      dag.addNode('generate', async (mergedResults) => {
+        const answer = await llm.generate(query, mergedResults, options);
+        return { answer: String(answer), results: mergedResults };
+      });
+      dag.connect('merge', 'generate');
+    }
+
+    // Execute DAG
+    const nodeCount =
+      subQueries.length + 2 + (this.config.enableCritique ? 1 : 0);
+    this.emit('executing', { nodeCount });
+
+    const dagResult = await dag.execute(query, {
+      concurrency: this.config.maxConcurrency,
+      timeout: this.config.timeout,
+      continueOnError: true,
+      gracefulDegradation: true,
+    });
+
+    // Extract final result from generate node
+    const output = dagResult?.answer
+      ? dagResult
+      : dagResult?.get
+        ? dagResult.get('generate')
+        : dagResult;
+
+    this.emit('completed', output);
+
+    return {
+      success: true,
+      query,
+      answer: output?.answer || '',
+      results: output?.results || [],
+      critique: output?.critique || null,
+      subQueries,
+      metadata: {
+        subQueryCount: subQueries.length,
+        enabledCritique: this.config.enableCritique,
+        enabledIterative: this.config.enableIterativeRetrieval,
+      },
+    };
+  }
+}
+
+module.exports = { AgenticPipeline, DEFAULT_CONFIG };

package/src/agentic/iterative-retriever.js

@@ -0,0 +1,213 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const { retry } = require('../utils/retry');
+const { tokenize, computeJaccardSimilarity } = require('../evaluate/scoring');
+
+/**
+ * Default configuration for the IterativeRetriever.
+ * @type {object}
+ */
+const DEFAULT_CONFIG = {
+  maxIterations: 3,
+  coverageThreshold: 0.6,
+  retryOptions: { retries: 2, baseDelay: 100 },
+};
+
+/**
+ * Iterative retriever that loops: retrieve -> check coverage -> refine -> re-retrieve.
+ * Continues until coverage threshold is met or maxIterations is reached.
+ *
+ * @extends EventEmitter
+ */
+class IterativeRetriever extends EventEmitter {
+  /**
+   * @param {object} [options] - Override default configuration
+   * @param {number} [options.maxIterations=3] - Maximum retrieval iterations
+   * @param {number} [options.coverageThreshold=0.6] - Jaccard similarity threshold for convergence
+   * @param {object} [options.retryOptions] - Options passed to retry() on each retrieval call
+   */
+  constructor(options = {}) {
+    super();
+    this.config = { ...DEFAULT_CONFIG, ...options };
+  }
+
+  /**
+   * Merge new results into accumulated results, deduplicating by id.
+   * When duplicates exist, keep the one with the higher score.
+   *
+   * @param {Array<object>} accumulated - Existing accumulated results
+   * @param {Array<object>} newResults - Newly retrieved results
+   * @returns {Array<object>}
+   * @private
+   */
+  _mergeResults(accumulated, newResults) {
+    const seen = new Map();
+
+    for (const r of accumulated) {
+      const id = r?.id || JSON.stringify(r);
+      seen.set(id, r);
+    }
+
+    for (const r of newResults) {
+      const id = r?.id || JSON.stringify(r);
+      if (!seen.has(id) || (r.score && r.score > (seen.get(id).score || 0))) {
+        seen.set(id, r);
+      }
+    }
+
+    return Array.from(seen.values());
+  }
+
+  /**
+   * Compute query coverage against accumulated result contents using Jaccard similarity.
+   *
+   * @param {string} query - Original query
+   * @param {Array<object>} results - Accumulated results
+   * @returns {number} Coverage score between 0 and 1
+   * @private
+   */
+  _computeCoverage(query, results) {
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0) return 0;
+
+    // Combine all result content into a single token set
+    const resultText = results
+      .map((r) => r?.content || r?.text || r?.chunk || '')
+      .join(' ');
+    const resultTokens = tokenize(resultText);
+
+    return computeJaccardSimilarity(queryTokens, resultTokens);
+  }
+
+  /**
+   * Heuristic query refinement: find query tokens missing from results
+   * and append them to the original query.
+   *
+   * @param {string} originalQuery - The original user query
+   * @param {Array<object>} results - Accumulated results
+   * @returns {string} Refined query
+   * @private
+   */
+  _heuristicRefine(originalQuery, results) {
+    const queryTokens = tokenize(originalQuery);
+    const resultText = results
+      .map((r) => r?.content || r?.text || r?.chunk || '')
+      .join(' ');
+    const resultTokenSet = new Set(tokenize(resultText));
+
+    const missing = queryTokens.filter((t) => !resultTokenSet.has(t));
+
+    if (missing.length === 0) return originalQuery;
+    return `${originalQuery} more about ${missing.join(' ')}`;
+  }
+
+  /**
+   * Perform iterative retrieval with coverage checking and query refinement.
+   *
+   * @param {object} params
+   * @param {string} params.query - The search query
+   * @param {object} params.retriever - Retriever instance with .retrieve() method
+   * @param {object} [params.llm] - Optional LLM for query refinement
+   * @param {Array<number>} [params.queryVector] - Optional pre-computed query vector
+   * @returns {Promise<{results: Array<object>, iterations: number, converged: boolean, coverage: number}>}
+   * @throws {Error} If query or retriever is missing
+   */
+  async retrieve({ query, retriever, llm, queryVector }) {
+    // 1. Validate inputs
+    if (!query || typeof query !== 'string' || !query.trim()) {
+      throw new Error(
+        'IterativeRetriever.retrieve(): query must be a non-empty string',
+      );
+    }
+    if (!retriever || typeof retriever.retrieve !== 'function') {
+      throw new Error(
+        'IterativeRetriever.retrieve(): retriever with .retrieve() method is required',
+      );
+    }
+
+    // 2. Initialize
+    let accumulatedResults = [];
+    let currentQuery = query;
+    let iterations = 0;
+    let coverage = 0;
+    let converged = false;
+
+    // 3. Retrieval loop
+    while (iterations < this.config.maxIterations) {
+      // a. Retrieve with retry
+      const retrieveQuery = currentQuery;
+      const newResults = await retry(
+        () =>
+          retriever.retrieve({ query: retrieveQuery, queryVector, topK: 10 }),
+        this.config.retryOptions,
+      );
+
+      // b. Merge and deduplicate
+      const resultsArray = Array.isArray(newResults) ? newResults : [];
+      accumulatedResults = this._mergeResults(accumulatedResults, resultsArray);
+
+      // c. Compute coverage
+      coverage = this._computeCoverage(query, accumulatedResults);
+
+      // d. Emit 'iteration' event
+      this.emit('iteration', {
+        iteration: iterations,
+        coverage,
+        resultCount: accumulatedResults.length,
+        query: currentQuery,
+      });
+
+      iterations += 1;
+
+      // e. Check convergence
+      if (coverage >= this.config.coverageThreshold) {
+        converged = true;
+        break;
+      }
+
+      // f. Refine query (skip on last iteration since we won't retrieve again)
+      if (iterations < this.config.maxIterations) {
+        let refined = null;
+
+        // Try LLM-based refinement first
+        if (llm && typeof llm.generate === 'function') {
+          try {
+            refined = await llm.generate(
+              `Given the query "${query}" and that current results don't fully cover the topic, generate a refined search query to find missing information.`,
+              accumulatedResults,
+            );
+            if (refined && typeof refined === 'string' && refined.trim()) {
+              refined = refined.trim();
+            } else {
+              refined = null;
+            }
+          } catch (_err) {
+            // LLM failed -- fall through to heuristic
+            refined = null;
+          }
+        }
+
+        // Heuristic fallback
+        if (!refined) {
+          refined = this._heuristicRefine(query, accumulatedResults);
+        }
+
+        currentQuery = refined;
+      }
+    }
+
+    // 4. Emit 'completed' event
+    this.emit('completed', {
+      results: accumulatedResults,
+      iterations,
+      converged,
+      coverage,
+    });
+
+    // 5. Return
+    return { results: accumulatedResults, iterations, converged, coverage };
+  }
+}
+
+module.exports = { IterativeRetriever, DEFAULT_CONFIG };

package/src/agentic/query-planner.js

@@ -0,0 +1,208 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+
+/**
+ * Default configuration for the QueryPlanner.
+ * @type {object}
+ */
+const DEFAULT_CONFIG = {
+  minComplexityToSplit: 2,
+  maxSubQueries: 5,
+};
+
+/** Question words that indicate query complexity */
+const QUESTION_WORDS = ['who', 'what', 'when', 'where', 'why', 'how', 'which'];
+
+/** Conjunctions used for splitting compound queries */
+const CONJUNCTIONS = ['and', 'or', 'also', 'as well as'];
+
+/** Splitter patterns for decomposing compound queries */
+const SPLIT_PATTERNS = [/ and /i, / or /i, /; ?/];
+
+/** Keywords that indicate a comparative strategy */
+const COMPARATIVE_KEYWORDS = [
+  'compare',
+  'contrast',
+  'difference',
+  'versus',
+  'vs',
+];
+
+/**
+ * Heuristic query decomposition planner -- no LLM needed.
+ * Splits compound queries into sub-queries with assigned strategies
+ * based on detected question types.
+ *
+ * @extends EventEmitter
+ */
+class QueryPlanner extends EventEmitter {
+  /**
+   * @param {object} [options] - Override default configuration
+   * @param {number} [options.minComplexityToSplit=2] - Minimum complexity score before splitting
+   * @param {number} [options.maxSubQueries=5] - Maximum number of sub-queries to produce
+   */
+  constructor(options = {}) {
+    super();
+    this.config = { ...DEFAULT_CONFIG, ...options };
+  }
+
+  /**
+   * Compute the complexity score of a query string.
+   *
+   * Scoring rules:
+   *   +1 per question word (who, what, when, where, why, how, which)
+   *   +1 per conjunction (and, or, also, as well as)
+   *   +1 if length > 100 characters
+   *   +1 per semicolon
+   *   +1 per comma-separated clause (commas - 1 if > 0 commas)
+   *
+   * @param {string} query
+   * @returns {number}
+   * @private
+   */
+  _computeComplexity(query) {
+    const lower = query.toLowerCase();
+    const words = lower.split(/\s+/);
+    let score = 0;
+
+    // +1 per question word
+    for (const w of QUESTION_WORDS) {
+      if (words.includes(w)) score += 1;
+    }
+
+    // +1 per conjunction
+    for (const c of CONJUNCTIONS) {
+      // "as well as" is multi-word -- use indexOf on the full string
+      if (c.includes(' ')) {
+        if (lower.includes(c)) score += 1;
+      } else if (words.includes(c)) {
+        score += 1;
+      }
+    }
+
+    // +1 if length > 100 chars
+    if (query.length > 100) score += 1;
+
+    // +1 per semicolon
+    const semicolons = (query.match(/;/g) || []).length;
+    score += semicolons;
+
+    // +1 per comma-separated clause (number of commas)
+    const commas = (query.match(/,/g) || []).length;
+    if (commas > 0) score += commas;
+
+    return score;
+  }
+
+  /**
+   * Detect the retrieval strategy for a query fragment.
+   *
+   * @param {string} text
+   * @returns {'factual'|'analytical'|'comparative'|'general'}
+   * @private
+   */
+  _detectStrategy(text) {
+    const lower = text.toLowerCase();
+    const words = lower.split(/\s+/);
+
+    // Check comparative keywords first (more specific)
+    for (const kw of COMPARATIVE_KEYWORDS) {
+      if (words.includes(kw) || lower.includes(kw)) return 'comparative';
+    }
+
+    // Check question words
+    for (const w of words) {
+      if (['who', 'what', 'where', 'when'].includes(w)) return 'factual';
+      if (['why', 'how'].includes(w)) return 'analytical';
+    }
+
+    return 'general';
+  }
+
+  /**
+   * Plan query decomposition.
+   *
+   * @param {string} query - The user query to decompose
+   * @returns {{
+   *   subQueries: Array<{subQuery: string, strategy: string, priority: number}>,
+   *   complexity: number,
+   *   originalQuery: string
+   * }}
+   * @throws {Error} If query is not a non-empty string
+   * @fires QueryPlanner#planned
+   */
+  plan(query) {
+    // 1. Validate
+    if (!query || typeof query !== 'string' || !query.trim()) {
+      throw new Error('QueryPlanner.plan(): query must be a non-empty string');
+    }
+
+    const trimmed = query.trim();
+
+    // 2. Compute complexity
+    const complexity = this._computeComplexity(trimmed);
+
+    // 3. If complexity below threshold, return single sub-query
+    if (complexity < this.config.minComplexityToSplit) {
+      const result = {
+        subQueries: [
+          {
+            subQuery: trimmed,
+            strategy: this._detectStrategy(trimmed),
+            priority: 0,
+          },
+        ],
+        complexity,
+        originalQuery: trimmed,
+      };
+      this.emit('planned', result);
+      return result;
+    }
+
+    // 4. Split into sub-queries
+    let parts = [trimmed];
+    for (const pattern of SPLIT_PATTERNS) {
+      const newParts = [];
+      for (const part of parts) {
+        const split = part
+          .split(pattern)
+          .map((s) => s.trim())
+          .filter(Boolean);
+        newParts.push(...split);
+      }
+      parts = newParts;
+    }
+
+    // Build sub-queries with strategy and priority
+    let subQueries = parts.map((part, i) => ({
+      subQuery: part,
+      strategy: this._detectStrategy(part),
+      priority: i,
+    }));
+
+    // 5. Deduplicate by subQuery text (case-insensitive)
+    const seen = new Set();
+    subQueries = subQueries.filter((sq) => {
+      const key = sq.subQuery.toLowerCase();
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+
+    // Limit to maxSubQueries
+    subQueries = subQueries.slice(0, this.config.maxSubQueries);
+
+    // 6. Emit 'planned' event
+    const result = {
+      subQueries,
+      complexity,
+      originalQuery: trimmed,
+    };
+
+    this.emit('planned', result);
+    return result;
+  }
+}
+
+module.exports = { QueryPlanner, DEFAULT_CONFIG };