@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

package/dist/index.d.ts

@@ -14,9 +14,39 @@ export interface RagPipelineConfig {
   llm?: string | LLMPlugin;
   reranker?: string | RerankerPlugin;
   registry?: PluginRegistry;
+  /**
+   * Cache query embeddings, retrieval results and answers. `true` caches
+   * all three in memory; a CacheBackend (MemoryCache, RedisCache, your own)
+   * caches all three in it; or configure each layer.
+   */
+  cache?: boolean | CacheBackend | CacheOptions;
   [key: string]: any;
 }
 
+/** A cache store: get / set / delete, optionally stats. */
+export interface CacheBackend {
+  get(key: string): Promise<unknown | undefined>;
+  set(key: string, value: unknown, options?: { ttlSeconds?: number }): Promise<void>;
+  delete?(key: string): Promise<void>;
+  stats?(): Promise<Record<string, number>>;
+}
+
+export interface CacheOptions {
+  embeddings?: boolean | CacheBackend;
+  retrieval?: boolean | CacheBackend;
+  generation?: boolean | CacheBackend;
+  /** Defaults: embeddings 30 days, retrieval 1 hour, generation 24 hours. */
+  ttlSeconds?: { embeddings?: number; retrieval?: number; generation?: number };
+}
+
+export type CacheOutcome = "hit" | "miss" | "skip";
+
+export interface CacheLayerStats {
+  hits: number;
+  misses: number;
+  skipped: number;
+}
+
 export interface PipelineRunOptions {
   query?: string;
   queryVector?: number[];
@@ -33,11 +63,23 @@ export interface PipelineRunResult {
   query?: string;
   results?: any;
   error?: string;
+  /** Per-layer cache outcome; present when the pipeline has a cache. */
+  cache?: {
+    embeddings?: CacheOutcome;
+    retrieval?: CacheOutcome;
+    generation?: CacheOutcome;
+  };
 }
 
 export interface Pipeline {
   run(options: PipelineRunOptions): Promise<PipelineRunResult>;
   cleanup(): void;
+  /** Hits, misses and skips per cache layer; null without a cache. */
+  cacheStats(): {
+    embeddings?: CacheLayerStats;
+    retrieval?: CacheLayerStats;
+    generation?: CacheLayerStats;
+  } | null;
 }
 
 export interface LoadConfigOptions {
@@ -258,6 +300,7 @@ export class JWTValidator {
   verify(token: string, options?: any): any;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import PluginSandbox from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class PluginSandbox {
   constructor(options?: {
     memoryLimit?: number;
@@ -283,6 +326,7 @@ export function validateInput(input: string, options?: any): { valid: boolean; e
 // AI/ML
 // =============================================================================
 
+/** @deprecated Experimental (simulated or incomplete). Import MultiModalProcessor from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class MultiModalProcessor {
   constructor(options?: any);
   processContent(tenantId: string, content: any): Promise<any>;
@@ -290,12 +334,14 @@ export class MultiModalProcessor {
   crossModalSearch(tenantId: string, query: any): Promise<any>;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import AdaptiveRetrievalEngine from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class AdaptiveRetrievalEngine {
   constructor(options?: any);
   retrieveDocuments(tenantId: string, query: string, options?: any): Promise<any>;
   optimizeRetrieval(tenantId: string, performanceData: any): Promise<any>;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import FederatedLearningCoordinator from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class FederatedLearningCoordinator {
   constructor(options?: any);
   createSession(config: any): Promise<any>;
@@ -303,6 +349,7 @@ export class FederatedLearningCoordinator {
   aggregate(sessionId: string): Promise<any>;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import ModelTrainingOrchestrator from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class ModelTrainingOrchestrator {
   constructor(options?: any);
   createTrainingJob(tenantId: string, config: any): Promise<any>;
@@ -370,14 +417,19 @@ export class AuditLogger {
   logDataModification(event: any): Promise<void>;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import DataGovernance from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class DataGovernance {
   constructor(options?: any);
   classifyData(data: any): any;
   enforceRetention(policy: any): Promise<void>;
 }
 
-export { DataGovernance as DataGovernanceManager };
+/** @deprecated Experimental (simulated or incomplete). Import DataGovernanceManager from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
+export declare const DataGovernanceManager: typeof DataGovernance;
+/** @deprecated Experimental (simulated or incomplete). Import DataGovernanceManager from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
+export type DataGovernanceManager = DataGovernance;
 
+/** @deprecated Experimental (simulated or incomplete). Import TenantManager from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class TenantManager {
   constructor(options?: any);
   createTenant(config: any): Promise<any>;
@@ -385,33 +437,39 @@ export class TenantManager {
   deleteTenant(tenantId: string): Promise<void>;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import ResourceMonitor from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class ResourceMonitor {
   constructor(options?: any);
   getUsage(tenantId: string): any;
   checkQuota(tenantId: string): boolean;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import SSOManager from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class SSOManager {
   constructor(options?: any);
   authenticate(provider: string, credentials: any): Promise<any>;
   getSession(sessionId: string): any;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import SAMLProvider from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class SAMLProvider {
   constructor(options?: any);
   authenticate(request: any): Promise<any>;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import OAuth2Provider from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class OAuth2Provider {
   constructor(options?: any);
   authenticate(request: any): Promise<any>;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import ActiveDirectoryProvider from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class ActiveDirectoryProvider {
   constructor(options?: any);
   authenticate(request: any): Promise<any>;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import OIDCProvider from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class OIDCProvider {
   constructor(options?: any);
   authenticate(request: any): Promise<any>;
@@ -434,6 +492,7 @@ export class PluginAnalytics {
   getStats(pluginName: string): any;
 }
 
+/** @deprecated Experimental (simulated or incomplete). Import PluginCertification from "@devilsdev/rag-pipeline-utils/experimental"; it will be removed from the main entry in the next major release. */
 export class PluginCertification {
   constructor(options?: any);
   certify(pluginName: string): Promise<any>;
@@ -464,4 +523,72 @@ export class DevServer {
   stop(): Promise<void>;
 }
 
-export function createDevServer(options?: any): DevServer;
+export function createDevServer(options?: any): DevServer;
+
+// =============================================================================
+// Declarations generated from JSDoc (scripts/generate-types.js)
+// =============================================================================
+export { validatePlugin } from "./types/core/validate-plugin";
+export { checkNumericConsistency } from "./types/evaluate/scoring";
+export { extractNumbers } from "./types/evaluate/scoring";
+export { computeFaithfulness } from "./types/evaluate/faithfulness";
+export { computeSemanticSimilarity } from "./types/evaluate/semantic-similarity";
+export { computeAnswerRelevance } from "./types/evaluate/relevance";
+export { computeContextPrecision } from "./types/evaluate/context-metrics";
+export { computeContextRecall } from "./types/evaluate/context-metrics";
+export { computeGroundedness } from "./types/evaluate/groundedness";
+export { PipelineEvaluator } from "./types/evaluate/pipeline-evaluator";
+export { ChunkingEngine } from "./types/chunking/chunking-engine";
+export { CitationTracker } from "./types/citation/citation-tracker";
+export { checkAnswer } from "./types/grounding/check-answer";
+export { normalizeSources } from "./types/grounding/check-answer";
+export { createAiSdkAdapter } from "./types/adapters/ai-sdk";
+export { MemoryCache } from "./types/cache/memory-cache";
+export { RedisCache } from "./types/cache/redis-cache";
+export { mapSentenceToSources } from "./types/citation/source-mapper";
+export { buildIDFWeights } from "./types/citation/source-mapper";
+export { detectHallucinations } from "./types/citation/hallucination-detector";
+export { BM25Search } from "./types/retrieval/bm25-search";
+export { reciprocalRankFusion } from "./types/retrieval/rank-fusion";
+export { HybridRetriever } from "./types/retrieval/hybrid-retriever";
+export { FileVectorStore } from "./types/retrieval/file-vector-store";
+export { PreRetrievalGuard } from "./types/guardrails/pre-retrieval-guard";
+export { detectInjection } from "./types/guardrails/injection-detector";
+export { RetrievalGuard } from "./types/guardrails/retrieval-guard";
+export { PostGenerationGuard } from "./types/guardrails/post-generation-guard";
+export { GuardrailsPipeline } from "./types/guardrails/guardrails-pipeline";
+export { QueryPlanner } from "./types/agentic/query-planner";
+export { IterativeRetriever } from "./types/agentic/iterative-retriever";
+export { SelfCritiqueChecker } from "./types/agentic/self-critique";
+export { AgenticPipeline } from "./types/agentic/agentic-pipeline";
+export { CostCalculator } from "./types/cost/cost-calculator";
+export { PRICING_METADATA } from "./types/cost/cost-calculator";
+export { CostTracker } from "./types/cost/cost-tracker";
+export { TokenBudget } from "./types/cost/token-budget";
+export { ExecutionTracer } from "./types/debug/execution-tracer";
+export { TraceInspector } from "./types/debug/trace-inspector";
+export { MCPServer } from "./types/mcp/mcp-server";
+export { MCPToolBuilder } from "./types/mcp/mcp-tool-builder";
+export { ProjectScaffolder } from "./types/templates/scaffold";
+export { TemplateRegistry } from "./types/templates/template-registry";
+export { SSEAdapter } from "./types/streaming/sse-adapter";
+export { WebSocketAdapter } from "./types/streaming/websocket-adapter";
+export { StreamRouter } from "./types/streaming/stream-router";
+export { BaseConnector } from "./types/connectors/base-connector";
+export { OllamaConnector } from "./types/connectors/ollama-connector";
+export { LocalEmbedder } from "./types/connectors/local-embedder";
+export { MemoryRetriever } from "./types/connectors/memory-retriever";
+export { OpenAIConnector } from "./types/connectors/openai-connector";
+export { AnthropicConnector } from "./types/connectors/anthropic-connector";
+export { CohereConnector } from "./types/connectors/cohere-connector";
+export { StreamingEmbedder } from "./types/streaming/streaming-embedder";
+export { createEmbeddingStream } from "./types/streaming/embedding-stream";
+export { ScoringReranker } from "./types/reranker/scoring-reranker";
+export { EmbeddingReranker } from "./types/reranker/embedding-reranker";
+export { CascadeReranker } from "./types/reranker/cascade-reranker";
+export { KnowledgeGraph } from "./types/graph/knowledge-graph";
+export { EntityExtractor } from "./types/graph/entity-extractor";
+export { GraphRetriever } from "./types/graph/graph-retriever";
+export { GraphIndex } from "./types/graph/graph-index";
+export { DashboardGenerator } from "./types/dashboard/dashboard-generator";
+export { MetricsAggregator } from "./types/dashboard/metrics-aggregator";

package/dist/index.mjs

@@ -8,6 +8,6 @@ const require = createRequire(import.meta.url);
 
 const mod = require('./index.cjs');
 
-export const { createRagPipeline, createPipeline, loadConfig, loadRagConfig, validateRagrc, normalizeConfig, pluginRegistry, logger, errorFormatter, createError, wrapError, ERROR_CODES, BatchProcessor, RateLimiter, retry, withRetry, ConnectionPoolManager, JWTValidator, PluginSandbox, PluginSignatureVerifier, validateInput, MultiModalProcessor, AdaptiveRetrievalEngine, FederatedLearningCoordinator, ModelTrainingOrchestrator, DAGEngine, DAG, evaluateRagDataset, scoreAnswer, computeBLEU, computeROUGE, computeFaithfulness, computeAnswerRelevance, computeContextPrecision, computeContextRecall, computeGroundedness, PipelineEvaluator, ChunkingEngine, CitationTracker, mapSentenceToSources, buildIDFWeights, detectHallucinations, BM25Search, reciprocalRankFusion, HybridRetriever, PreRetrievalGuard, RetrievalGuard, PostGenerationGuard, GuardrailsPipeline, QueryPlanner, IterativeRetriever, SelfCritiqueChecker, AgenticPipeline, CostCalculator, CostTracker, TokenBudget, ExecutionTracer, TraceInspector, MCPServer, MCPToolBuilder, ProjectScaffolder, TemplateRegistry, SSEAdapter, WebSocketAdapter, StreamRouter, BaseConnector, OllamaConnector, LocalEmbedder, MemoryRetriever, OpenAIConnector, AnthropicConnector, CohereConnector, StreamingEmbedder, createEmbeddingStream, ScoringReranker, EmbeddingReranker, CascadeReranker, KnowledgeGraph, EntityExtractor, GraphRetriever, GraphIndex, DashboardGenerator, MetricsAggregator, ParallelProcessor, eventLogger, metrics, AuditLogger, DataGovernance, DataGovernanceManager, TenantManager, ResourceMonitor, SSOManager, SAMLProvider, OAuth2Provider, ActiveDirectoryProvider, OIDCProvider, PluginHub, PluginAnalytics, PluginCertification, PluginAnalyticsDashboard, HotReloadManager, createHotReloadManager, DevServer, createDevServer } = mod;
+export const { createRagPipeline, createPipeline, loadConfig, loadRagConfig, validateRagrc, normalizeConfig, pluginRegistry, validatePlugin, logger, errorFormatter, createError, wrapError, ERROR_CODES, BatchProcessor, RateLimiter, retry, withRetry, ConnectionPoolManager, JWTValidator, PluginSandbox, PluginSignatureVerifier, validateInput, MultiModalProcessor, AdaptiveRetrievalEngine, FederatedLearningCoordinator, ModelTrainingOrchestrator, DAGEngine, DAG, evaluateRagDataset, scoreAnswer, computeBLEU, computeROUGE, checkNumericConsistency, extractNumbers, computeFaithfulness, computeSemanticSimilarity, computeAnswerRelevance, computeContextPrecision, computeContextRecall, computeGroundedness, PipelineEvaluator, ChunkingEngine, CitationTracker, checkAnswer, normalizeSources, createAiSdkAdapter, MemoryCache, RedisCache, mapSentenceToSources, buildIDFWeights, detectHallucinations, BM25Search, reciprocalRankFusion, HybridRetriever, FileVectorStore, PreRetrievalGuard, detectInjection, RetrievalGuard, PostGenerationGuard, GuardrailsPipeline, QueryPlanner, IterativeRetriever, SelfCritiqueChecker, AgenticPipeline, CostCalculator, PRICING_METADATA, CostTracker, TokenBudget, ExecutionTracer, TraceInspector, MCPServer, MCPToolBuilder, ProjectScaffolder, TemplateRegistry, SSEAdapter, WebSocketAdapter, StreamRouter, BaseConnector, OllamaConnector, LocalEmbedder, MemoryRetriever, OpenAIConnector, AnthropicConnector, CohereConnector, StreamingEmbedder, createEmbeddingStream, ScoringReranker, EmbeddingReranker, CascadeReranker, KnowledgeGraph, EntityExtractor, GraphRetriever, GraphIndex, DashboardGenerator, MetricsAggregator, ParallelProcessor, eventLogger, metrics, AuditLogger, DataGovernance, DataGovernanceManager, TenantManager, ResourceMonitor, SSOManager, SAMLProvider, OAuth2Provider, ActiveDirectoryProvider, OIDCProvider, PluginHub, PluginAnalytics, PluginCertification, PluginAnalyticsDashboard, HotReloadManager, createHotReloadManager, DevServer, createDevServer } = mod;
 
 export default mod;

package/dist/testing.cjs

@@ -0,0 +1,2 @@
+'use strict';
+module.exports = require('./index.cjs')[Symbol.for('@devilsdev/rag-pipeline-utils/testing')];

package/dist/testing.d.ts

@@ -0,0 +1 @@
+export * from "./types/testing";

package/dist/testing.mjs

@@ -0,0 +1,5 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const mod = require('./testing.cjs');
+export const { HashEmbedder, EchoLLM, fixtures, createTestPipeline } = mod;
+export default mod;

package/dist/types/adapters/ai-sdk.d.ts

@@ -0,0 +1,53 @@
+export type AiSdkFunctions = {
+    /**
+     * - `embed` from 'ai' (needed for an embedder)
+     */
+    embed?: Function;
+    /**
+     * - `embedMany` from 'ai' (batch embedding)
+     */
+    embedMany?: Function;
+    /**
+     * - `generateText` from 'ai' (needed for an llm)
+     */
+    generateText?: Function;
+    /**
+     * - `streamText` from 'ai' (streaming)
+     */
+    streamText?: Function;
+};
+/**
+ * Wrap AI SDK models as an embedder and an llm for createRagPipeline().
+ *
+ * @example
+ * import { embed, embedMany, generateText, streamText } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ * import { createAiSdkAdapter, createRagPipeline } from "@devilsdev/rag-pipeline-utils";
+ *
+ * const { embedder, llm } = createAiSdkAdapter({
+ *   ai: { embed, embedMany, generateText, streamText },
+ *   embeddingModel: openai.embedding("text-embedding-3-small"),
+ *   languageModel: openai("gpt-4o-mini"),
+ * });
+ * const pipeline = createRagPipeline({ embedder, retriever, llm });
+ *
+ * @param {Object} options
+ * @param {AiSdkFunctions} options.ai - Functions imported from 'ai'
+ * @param {Object} [options.embeddingModel] - AI SDK embedding model
+ * @param {Object} [options.languageModel] - AI SDK language model
+ * @param {Object} [options.settings] - Defaults for every text call, e.g.
+ *   `{ temperature: 0, maxOutputTokens: 512 }`
+ * @param {string} [options.systemPrompt] - Replaces the built-in RAG system
+ *   prompt
+ * @returns {{ embedder: Object|null, llm: Object|null }}
+ */
+export function createAiSdkAdapter(options?: {
+    ai: AiSdkFunctions;
+    embeddingModel?: any;
+    languageModel?: any;
+    settings?: any;
+    systemPrompt?: string;
+}): {
+    embedder: any | null;
+    llm: any | null;
+};

package/dist/types/agentic/agentic-pipeline.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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
+ */
+export class AgenticPipeline extends EventEmitter<[never]> {
+    /**
+     * @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.enableLlmPlanning=false] - Ask the llm for the
+     *   sub-queries (strictly validated, heuristic fallback); costs one extra
+     *   llm.generate() call per run
+     * @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?: {
+        maxConcurrency?: number;
+        timeout?: number;
+        enablePlanning?: boolean;
+        enableLlmPlanning?: boolean;
+        enableCritique?: boolean;
+        enableIterativeRetrieval?: boolean;
+        maxIterations?: number;
+        critiqueThreshold?: number;
+        plannerOptions?: object;
+        iterativeOptions?: object;
+    });
+    config: any;
+    planner: QueryPlanner;
+    critiqueChecker: SelfCritiqueChecker;
+    iterativeRetriever: IterativeRetriever;
+    /**
+     * 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.embedder] - Optional embedder; when given, each
+     *   sub-query is embedded on its own instead of reusing queryVector
+     * @param {object} [params.options={}] - Extra options passed to llm.generate()
+     * @param {AbortSignal} [params.options.signal] - Cancels the run. The run
+     *   has its own AbortController (also aborted after `timeout`); its signal
+     *   is passed to retriever.retrieve({ ..., signal }), embedder.embedQuery /
+     *   embed(text, { signal }) and llm.generate(query, docs, { ...options,
+     *   signal }), and no later stage starts once it aborts. The returned
+     *   promise then rejects with Error('Execution timeout') or
+     *   Error('Execution aborted').
+     * @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
+     */
+    run({ query, retriever, llm, queryVector, embedder, options }: {
+        query: string;
+        retriever: object;
+        llm: object;
+        queryVector?: Array<number>;
+        embedder?: object;
+        options?: {
+            signal?: AbortSignal;
+        };
+    }): Promise<{
+        success: boolean;
+        query: string;
+        answer: string;
+        results: Array<object>;
+        critique: object | null;
+        subQueries: Array<object>;
+        metadata: object;
+    }>;
+    /**
+     * @param {object} params - Validated run() parameters
+     * @param {object} runAbort - Per-run cancellation (see utils/run-abort)
+     * @returns {Promise<object>}
+     * @private
+     */
+    private _execute;
+}
+/**
+ * Default configuration for the AgenticPipeline.
+ * @type {object}
+ */
+export const DEFAULT_CONFIG: object;
+import { EventEmitter } from "events";
+import { QueryPlanner } from "./query-planner";
+import { SelfCritiqueChecker } from "./self-critique";
+import { IterativeRetriever } from "./iterative-retriever";

package/dist/types/agentic/iterative-retriever.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Iterative retriever that loops: retrieve -> check coverage -> refine -> re-retrieve.
+ * Continues until coverage threshold is met or maxIterations is reached.
+ *
+ * @extends EventEmitter
+ */
+export class IterativeRetriever extends EventEmitter<[never]> {
+    /**
+     * @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?: {
+        maxIterations?: number;
+        coverageThreshold?: number;
+        retryOptions?: object;
+    });
+    config: any;
+    /**
+     * 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
+     */
+    private _mergeResults;
+    /**
+     * 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
+     */
+    private _computeCoverage;
+    /**
+     * 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
+     */
+    private _heuristicRefine;
+    /**
+     * 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
+     * @param {object} [params.embedder] - Optional embedder; when given, each
+     *   refined query is re-embedded instead of reusing queryVector
+     * @param {AbortSignal} [params.signal] - Cancels the loop: passed to
+     *   retriever.retrieve({ ..., signal }), the embedder and llm.generate(...,
+     *   { signal }); no further iteration, retry or refinement starts once it
+     *   has aborted, and the call rejects with the signal's reason
+     * @returns {Promise<{results: Array<object>, iterations: number, converged: boolean, coverage: number}>}
+     * @throws {Error} If query or retriever is missing
+     */
+    retrieve({ query, retriever, llm, queryVector, embedder, signal }: {
+        query: string;
+        retriever: object;
+        llm?: object;
+        queryVector?: Array<number>;
+        embedder?: object;
+        signal?: AbortSignal;
+    }): Promise<{
+        results: Array<object>;
+        iterations: number;
+        converged: boolean;
+        coverage: number;
+    }>;
+}
+/**
+ * Default configuration for the IterativeRetriever.
+ * @type {object}
+ */
+export const DEFAULT_CONFIG: object;
+import { EventEmitter } from "events";

package/dist/types/agentic/query-planner.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Query decomposition planner. The default heuristic needs no LLM:
+ *
+ * - splits only at clause/question boundaries: "?" / "." followed by more
+ *   text, ";", and "and" / "or" / "as well as" (optionally after a comma)
+ *   when a question word, auxiliary verb or imperative follows;
+ * - keeps noun-phrase conjunctions intact ("salt and pepper", "A or B");
+ * - expands comparisons ("X vs Y", "compare X and Y", "difference between X
+ *   and Y") into one sub-query per entity plus the comparison itself.
+ *
+ * `plan(query, { llm })` can instead ask an LLM for a JSON array of
+ * sub-queries (strictly validated, heuristic fallback).
+ *
+ * @extends EventEmitter
+ */
+export class QueryPlanner extends EventEmitter<[never]> {
+    /**
+     * @param {object} [options] - Override default configuration
+     * @param {number} [options.minComplexityToSplit=2] - Minimum complexity
+     *   score before splitting at conjunctions; punctuation boundaries and
+     *   comparisons are always split
+     * @param {number} [options.maxSubQueries=5] - Maximum number of sub-queries to produce
+     */
+    constructor(options?: {
+        minComplexityToSplit?: number;
+        maxSubQueries?: number;
+    });
+    config: any;
+    /**
+     * 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)
+     *   +1 per conjunction followed by a question word, auxiliary or
+     *      imperative ("... and how ...", "... and explain ...")
+     *
+     * @param {string} query
+     * @returns {number}
+     * @private
+     */
+    private _computeComplexity;
+    /**
+     * Detect the retrieval strategy for a query fragment.
+     *
+     * @param {string} text
+     * @returns {'factual'|'analytical'|'comparative'|'general'}
+     * @private
+     */
+    private _detectStrategy;
+    /**
+     * Split a clause describing a comparison into its entities.
+     *
+     * @param {string} clause
+     * @returns {{ entities: string[], aspect: string|null }|null}
+     * @private
+     */
+    private _parseComparison;
+    /**
+     * Heuristic decomposition into sub-query strings.
+     *
+     * @param {string} query - Trimmed query
+     * @param {number} complexity
+     * @returns {Array<{subQuery: string, strategy: string}>}
+     * @private
+     */
+    private _decompose;
+    /**
+     * Turn sub-query texts into the plan result (dedupe, limit, priorities).
+     *
+     * @param {Array<{subQuery: string, strategy: string}>} items
+     * @param {number} complexity
+     * @param {string} originalQuery
+     * @param {'heuristic'|'llm'} source
+     * @returns {object}
+     * @private
+     */
+    private _finalize;
+    /**
+     * Heuristic plan for a trimmed query.
+     * @private
+     */
+    private _heuristicPlan;
+    /**
+     * Strictly validate an LLM's sub-query proposal: a JSON array (optionally
+     * in a ```json fence) of 1..maxSubQueries non-empty, single-line strings of
+     * at most 500 characters. Anything else is rejected.
+     *
+     * @param {*} raw - Value returned by llm.generate()
+     * @returns {string[]|null}
+     * @private
+     */
+    private _parseLlmSubQueries;
+    /**
+     * Ask the LLM for sub-queries; fall back to the heuristic plan.
+     * @private
+     */
+    private _planWithLlm;
+    /**
+     * Plan query decomposition.
+     *
+     * Without `options.llm` this is synchronous and returns the plan. With
+     * `options.llm` (an object with `generate()`), it returns a Promise of the
+     * plan: the LLM is asked for a JSON array of sub-queries, which is strictly
+     * validated (see _parseLlmSubQueries); on any failure the heuristic plan is
+     * used. `result.source` says which one was used.
+     *
+     * @param {string} query - The user query to decompose
+     * @param {object} [options]
+     * @param {{ generate: Function }} [options.llm] - Optional LLM planner
+     * @param {AbortSignal} [options.signal] - Passed to llm.generate()
+     * @returns {{
+     *   subQueries: Array<{subQuery: string, strategy: string, priority: number}>,
+     *   complexity: number,
+     *   originalQuery: string,
+     *   source: 'heuristic'|'llm'
+     * }|Promise<object>}
+     * @throws {Error} If query is not a non-empty string
+     * @fires QueryPlanner#planned
+     */
+    plan(query: string, options?: {
+        llm?: {
+            generate: Function;
+        };
+        signal?: AbortSignal;
+    }): {
+        subQueries: Array<{
+            subQuery: string;
+            strategy: string;
+            priority: number;
+        }>;
+        complexity: number;
+        originalQuery: string;
+        source: "heuristic" | "llm";
+    } | Promise<object>;
+}
+/**
+ * Default configuration for the QueryPlanner.
+ * @type {object}
+ */
+export const DEFAULT_CONFIG: object;
+import { EventEmitter } from "events";