@devilsdev/rag-pipeline-utils 2.6.1 → 2.7.0

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, 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 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, validateDataset, generateSyntheticDataset, runEvaluation, compareConfigurations, evaluationVerdict, renderEvaluationReport, 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, PgVectorRetriever, QdrantRetriever, 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/cache/memory-cache.d.ts

@@ -41,7 +41,10 @@ export class MemoryCache {
     set(key: string, value: unknown, { ttlSeconds }?: {
         ttlSeconds?: number;
     }): Promise<void>;
-    /** @param {string} key */
+    /**
+     * Removes a key.
+     * @param {string} key
+     */
     delete(key: string): Promise<void>;
     /** Remove every entry. */
     clear(): Promise<void>;

package/dist/types/cache/redis-cache.d.ts

@@ -36,7 +36,10 @@ export class RedisCache {
     set(key: string, value: unknown, { ttlSeconds }?: {
         ttlSeconds?: number;
     }): Promise<void>;
-    /** @param {string} key */
+    /**
+     * Removes a key.
+     * @param {string} key
+     */
     delete(key: string): Promise<void>;
     /** Hits and misses seen by this instance (size is not tracked). */
     stats(): Promise<{

package/dist/types/cli/services/instrument.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @param {Object} components - { embedder, retriever, reranker, llm }
+ * @returns {{ components: Object, timings: Array<{stage: string, ms: number}>, captured: { results: Array|null } }}
+ */
+export function instrumentComponents(components: any): {
+    components: any;
+    timings: Array<{
+        stage: string;
+        ms: number;
+    }>;
+    captured: {
+        results: any[] | null;
+    };
+};

package/dist/types/cli/services/rag-service.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Load documents from a file or directory, embed their chunks and store them.
+ * Re-ingesting a source replaces its previous chunks.
+ *
+ * @param {object} params
+ * @param {object} params.config - Normalized config
+ * @param {string} params.configDir - Directory of the config file
+ * @param {string} params.inputPath - File or directory to ingest
+ * @param {boolean} [params.rebuild=false] - Discard the existing index first
+ * @returns {Promise<{files: number, chunks: number, totalChunks: number, sources: string[]}>}
+ */
+export function ingest({ config, configDir, inputPath, rebuild }: {
+    config: object;
+    configDir: string;
+    inputPath: string;
+    rebuild?: boolean;
+}): Promise<{
+    files: number;
+    chunks: number;
+    totalChunks: number;
+    sources: string[];
+}>;
+/**
+ * Refit a corpus-trained embedder (only the built-in `local` TF-IDF embedder)
+ * and re-embed every stored chunk with the new model.
+ *
+ * Without `inputPath` the embedder is fitted on the indexed chunks. With it,
+ * the embedder is fitted on the documents read from that path only (they are
+ * not added to the index); indexed chunks that share no term with the new
+ * vocabulary embed to all-zero vectors and are counted in `zeroVectors`.
+ *
+ * @param {object} params
+ * @param {object} params.config
+ * @param {string} params.configDir
+ * @param {string} [params.inputPath] - Optional training corpus
+ * @returns {Promise<{trainedOn: string, trainingDocuments: number, vocabularySize: number,
+ *   previousVocabularySize: number|null, reembedded: number, zeroVectors: number}>}
+ */
+export function retrain({ config, configDir, inputPath }: {
+    config: object;
+    configDir: string;
+    inputPath?: string;
+}): Promise<{
+    trainedOn: string;
+    trainingDocuments: number;
+    vocabularySize: number;
+    previousVocabularySize: number | null;
+    reembedded: number;
+    zeroVectors: number;
+}>;
+/**
+ * Answer a question from the index. Without an llm stage this returns the
+ * retrieved passages only (answer: null) instead of a placeholder answer.
+ *
+ * @param {object} params
+ * @param {object} params.config
+ * @param {string} params.configDir
+ * @param {string} params.question
+ * @param {number} [params.topK=3]
+ * @param {object} [params.components] - Prebuilt components (loadComponents)
+ * @param {number} [params.timeout] - Abort the run after this many ms
+ * @param {function(string): void} [params.onToken] - Stream the answer: called
+ *   with each token (only with an llm stage)
+ * @returns {Promise<{answer: string|null, results: Array, citations?: object,
+ *   timings: Array<{stage: string, ms: number}>, durationMs: number}>}
+ */
+export function query({ config, configDir, question, topK, components, timeout, onToken, }: {
+    config: object;
+    configDir: string;
+    question: string;
+    topK?: number;
+    components?: object;
+    timeout?: number;
+    onToken?: (arg0: string) => void;
+}): Promise<{
+    answer: string | null;
+    results: any[];
+    citations?: object;
+    timings: Array<{
+        stage: string;
+        ms: number;
+    }>;
+    durationMs: number;
+}>;
+/**
+ * A createRagPipeline() pipeline over the configured components and index,
+ * for running many questions (rag-pipeline eval).
+ *
+ * @param {object} params
+ * @param {object} params.config
+ * @param {string} params.configDir
+ * @returns {{ pipeline: object, hasLlm: boolean }}
+ */
+export function createPipeline({ config, configDir }: {
+    config: object;
+    configDir: string;
+}): {
+    pipeline: object;
+    hasLlm: boolean;
+};
+/**
+ * Retrieval only (no llm): embed the question, retrieve and, if configured,
+ * rerank.
+ *
+ * @param {object} params
+ * @param {object} [params.components] - Prebuilt components (loadComponents)
+ * @param {object} [params.config]
+ * @param {string} [params.configDir]
+ * @param {string} params.question
+ * @param {number} [params.topK=3]
+ * @returns {Promise<Array<{id: string, score: number, content: string, metadata: object}>>}
+ */
+export function retrieve({ components, config, configDir, question, topK }: {
+    components?: object;
+    config?: object;
+    configDir?: string;
+    question: string;
+    topK?: number;
+}): Promise<Array<{
+    id: string;
+    score: number;
+    content: string;
+    metadata: object;
+}>>;
+/**
+ * Build the configured components once and restore the embedder state saved
+ * with the index, so they can be reused across several retrieve()/query()
+ * calls (e.g. by `ai benchmark`).
+ *
+ * @returns {object} Components as returned by buildComponents()
+ */
+export function loadComponents({ config, configDir }: {
+    config: any;
+    configDir: any;
+}): object;
+/**
+ * Restore embedder state saved with the index (e.g. LocalEmbedder's
+ * vocabulary), so queries embed into the same vector space as ingestion.
+ */
+export function restoreEmbedder(embedder: any, retriever: any): void;

package/dist/types/cli/shared/config-context.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @param {object} globalOptions - program.opts(); uses globalOptions.config
+ * @returns {{config: object, configPath: string, configDir: string}}
+ */
+export function loadCliConfig(globalOptions?: object): {
+    config: object;
+    configPath: string;
+    configDir: string;
+};

package/dist/types/config/component-factory.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Turn a normalized .ragrc.json config into component instances.
+ *
+ * Each `pipeline` entry `{ stage, name, config }` is resolved in order:
+ *   1. a built-in name (see BUILT_INS),
+ *   2. a custom module path under `plugins.<stage>.<name>`,
+ *   3. a plugin registered on the shared pluginRegistry.
+ *
+ * @param {object} config - Output of loadRagConfig()/validateRagrc().normalized
+ * @param {object} [options]
+ * @param {string} [options.configDir=process.cwd()] - Paths resolve relative to this
+ * @returns {{embedder?: object, retriever?: object, llm?: object, reranker?: object, loader?: object, names: object}}
+ */
+export function buildComponents(config: object, options?: {
+    configDir?: string;
+}): {
+    embedder?: object;
+    retriever?: object;
+    llm?: object;
+    reranker?: object;
+    loader?: object;
+    names: object;
+};
+/**
+ * Instantiate a custom plugin from `plugins.<stage>.<name>` in the config.
+ * The module may export a class (constructed with the entry config), an
+ * instance, or either of those as `default`.
+ */
+export function loadPluginModule(modulePath: any, entryConfig: any, configDir: any): any;
+export namespace BUILT_INS {
+    namespace loader {
+        function auto(): typeof import("../loader/document-reader");
+    }
+    namespace embedder {
+        function local(cfg: any): import("../connectors/local-embedder").LocalEmbedder;
+        function openai(cfg: any): import("../connectors/openai-connector").OpenAIConnector;
+        function ollama(cfg: any): import("../connectors/ollama-connector").OllamaConnector;
+        function cohere(cfg: any): import("../connectors/cohere-connector").CohereConnector;
+    }
+    let retriever: {
+        "file-store": (cfg: any, configDir: any) => import("../retrieval/file-vector-store").FileVectorStore;
+        memory: (cfg: any) => import("../connectors/memory-retriever").MemoryRetriever;
+        pgvector: (cfg: any) => import("../retrieval/pgvector-retriever").PgVectorRetriever;
+        qdrant: (cfg: any) => import("../retrieval/qdrant-retriever").QdrantRetriever;
+    };
+    namespace llm {
+        export function openai_1(cfg: any): import("../connectors/openai-connector").OpenAIConnector;
+        export { openai_1 as openai };
+        export function anthropic(cfg: any): import("../connectors/anthropic-connector").AnthropicConnector;
+        export function ollama_1(cfg: any): import("../connectors/ollama-connector").OllamaConnector;
+        export { ollama_1 as ollama };
+    }
+    namespace reranker {
+        function scoring(cfg: any): import("../reranker/scoring-reranker").ScoringReranker;
+    }
+}
+export const STAGES: string[];