@devilsdev/rag-pipeline-utils 2.4.5 → 2.5.0

package/dist/index.d.ts

@@ -258,6 +258,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 +284,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 +292,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 +307,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 +375,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 +395,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 +450,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 +481,65 @@ 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 { checkNumericConsistency } from "./types/evaluate/scoring";
+export { extractNumbers } from "./types/evaluate/scoring";
+export { computeFaithfulness } from "./types/evaluate/faithfulness";
+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 { 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, 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, computeAnswerRelevance, computeContextPrecision, computeContextRecall, computeGroundedness, PipelineEvaluator, ChunkingEngine, CitationTracker, 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/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";

package/dist/types/agentic/self-critique.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Answer verification against retrieved source documents.
+ * Uses CitationTracker (lazy-loaded) to compute groundedness and detect hallucinations.
+ *
+ * @extends EventEmitter
+ */
+export class SelfCritiqueChecker extends EventEmitter<[never]> {
+    /**
+     * @param {object} [options] - Override default configuration
+     * @param {number} [options.approvalThreshold=0.5] - Minimum groundedness score to approve an answer
+     */
+    constructor(options?: {
+        approvalThreshold?: number;
+    });
+    config: any;
+    /**
+     * Check an answer against retrieved documents for groundedness.
+     *
+     * @param {string} answer - The LLM-generated answer to verify
+     * @param {Array<object>} retrievedDocs - Source documents to check against
+     * @returns {{
+     *   approved: boolean,
+     *   score: number,
+     *   issues: Array<{sentence: string, classification: string}>,
+     *   citationResult: object
+     * }}
+     * @throws {Error} If answer or retrievedDocs are invalid
+     * @fires SelfCritiqueChecker#checked
+     */
+    check(answer: string, retrievedDocs: Array<object>): {
+        approved: boolean;
+        score: number;
+        issues: Array<{
+            sentence: string;
+            classification: string;
+        }>;
+        citationResult: object;
+    };
+}
+/**
+ * Default configuration for the SelfCritiqueChecker.
+ * @type {object}
+ */
+export const DEFAULT_CONFIG: object;
+import { EventEmitter } from "events";

package/dist/types/ai/adaptive-retrieval.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Initialize or update user profile
+ * @param {string} userId - User identifier
+ * @param {object} profile - Profile data
+ * @returns {Promise<object>} Created/updated profile
+ */
+export function initializeUserProfile(userId: string, profile?: object): Promise<object>;
+/**
+ * Record feedback for a query/item pair
+ * @param {string} userId - User identifier
+ * @param {object} feedback - Feedback object with query, results, ratings, etc.
+ * @returns {Promise<void>}
+ */
+export function recordFeedback(userId: string, feedback: object): Promise<void>;
+/**
+ * Perform adaptive retrieval with deterministic scoring
+ * @param {string} userId - User identifier
+ * @param {string} query - Search query
+ * @param {object} options - Retrieval options
+ * @returns {Promise<object>} Object with documents array and adaptationMetadata
+ */
+export function adaptiveRetrieve(userId: string, query: string, options?: object): Promise<object>;
+/**
+ * Get user profile
+ * @param {string} userId - User identifier
+ * @returns {Promise<object|null>} User profile or null if not found
+ */
+export function getUserProfile(userId: string): Promise<object | null>;
+/**
+ * Personalize ranking for a set of documents
+ * @param {string} userId - User ID
+ * @param {array} documents - Array of documents to personalize
+ * @returns {array} Documents with personalized scores and ranking factors
+ */
+export function personalizeRanking(userId: string, documents: any[]): any[];
+/**
+ * Get statistics about users and feedback
+ * @returns {object} Stats object with users and interactions
+ */
+export function getStats(): object;
+/**
+ * Clear all stored data
+ */
+export function clear(): void;

package/dist/types/ai/federation/federated-learning-coordinator.d.ts

@@ -0,0 +1,62 @@
+export class FederatedLearningCoordinator extends EventEmitter<[never]> {
+    constructor(options?: {});
+    config: {
+        minParticipants: any;
+        maxParticipants: any;
+        roundDuration: any;
+        convergenceThreshold: any;
+        maxRounds: any;
+    };
+    federations: Map<any, any>;
+    participants: Map<any, any>;
+    globalModels: Map<any, any>;
+    createFederation(tenantId: any, modelConfig: any, federationConfig?: {}): Promise<`${string}-${string}-${string}-${string}-${string}`>;
+    registerParticipant(federationId: any, participantInfo: any): Promise<`${string}-${string}-${string}-${string}-${string}`>;
+    startFederatedTraining(federationId: any): Promise<{
+        federationId: any;
+        status: any;
+        rounds: any;
+        participants: any;
+    }>;
+    getFederationStatus(federationId: any): Promise<{
+        id: any;
+        status: any;
+        currentRound: any;
+        participantCount: any;
+        convergenceHistory: any;
+        createdAt: any;
+        startedAt: any;
+        completedAt: any;
+    }>;
+    getParticipantStatus(participantId: any): Promise<any>;
+    updateParticipantModel(participantId: any, modelUpdate: any): Promise<{
+        participantId: any;
+        updateAccepted: boolean;
+        newPerformance: any;
+    }>;
+    aggregateModels(federationId: any, participantUpdates: any): Promise<{
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        federationId: any;
+        round: any;
+        participantCount: any;
+        aggregationMethod: string;
+        weights: number[];
+        performance: {
+            accuracy: number;
+            loss: number;
+            convergence: number;
+        };
+        createdAt: number;
+    }>;
+    _executeTrainingRound(federation: any, roundNumber: any): Promise<{
+        round: any;
+        accuracy: number;
+        loss: number;
+        convergence: number;
+        participantCount: any;
+        timestamp: number;
+    }>;
+    getGlobalModel(federationId: any): Promise<any>;
+    removeParticipant(participantId: any): Promise<boolean>;
+}
+import { EventEmitter } from "events";