@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

package/dist/types/citation/citation-tracker.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Tracks citations between an LLM-generated answer and retrieved source documents.
+ * Emits a 'tracked' event when citation analysis completes.
+ *
+ * @extends EventEmitter
+ */
+export class CitationTracker extends EventEmitter<[never]> {
+    /**
+     * @param {object} [options] - Override default configuration
+     * @param {number} [options.similarityThreshold=0.5] - Minimum similarity for a citation match
+     * @param {number} [options.maxCitationsPerSentence=3] - Max citations per sentence
+     * @param {boolean} [options.useIDFWeighting=true] - Whether to apply IDF weighting
+     */
+    constructor(options?: {
+        similarityThreshold?: number;
+        maxCitationsPerSentence?: number;
+        useIDFWeighting?: boolean;
+    });
+    config: any;
+    /**
+     * Normalize a document object to ensure it has a usable text content string.
+     * Looks for .content, .text, or .chunk fields. If .chunk is a function, calls it and joins the result.
+     * @param {object} doc
+     * @returns {object} Normalized doc with .content field
+     * @private
+     */
+    private _normalizeDoc;
+    /**
+     * Track citations for an answer against retrieved documents.
+     *
+     * @param {string} answer - The LLM-generated answer text
+     * @param {Array<object>} retrievedDocs - Array of source documents (each should have .content, .text, or .chunk)
+     * @returns {{
+     *   citations: Array<{sentence: string, sources: Array<{docId: string|undefined, docIndex: number, score: number}>}>,
+     *   groundednessScore: number,
+     *   hallucinationReport: object,
+     *   metadata: {sentenceCount: number, docCount: number, config: object}
+     * }}
+     * @fires CitationTracker#tracked
+     */
+    track(answer: string, retrievedDocs: Array<object>): {
+        citations: Array<{
+            sentence: string;
+            sources: Array<{
+                docId: string | undefined;
+                docIndex: number;
+                score: number;
+            }>;
+        }>;
+        groundednessScore: number;
+        hallucinationReport: object;
+        metadata: {
+            sentenceCount: number;
+            docCount: number;
+            config: object;
+        };
+    };
+}
+/**
+ * Default configuration for the CitationTracker.
+ * @type {object}
+ */
+export const DEFAULT_CONFIG: object;
+import { EventEmitter } from "events";

package/dist/types/citation/hallucination-detector.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Detect hallucinations by analyzing citation results and classifying each sentence.
+ *
+ * Classification:
+ * - 'definite_hallucination': bestScore === 0 (no overlap with any source)
+ * - 'likely_hallucination': bestScore > 0 but below threshold
+ * - 'grounded': bestScore >= threshold
+ *
+ * @param {Array<{sentence: string, sources: Array<{docId: string|undefined, docIndex: number, score: number}>}>} citationResults
+ * @param {object} [options]
+ * @param {number} [options.threshold=0.5] - Score threshold for grounded classification
+ * @returns {{
+ *   hallucinationRate: number,
+ *   sentences: Array<{text: string, classification: string, bestScore: number, bestSource: object|null}>,
+ *   summary: {grounded: number, likely_hallucination: number, definite_hallucination: number}
+ * }}
+ */
+export function detectHallucinations(citationResults: Array<{
+    sentence: string;
+    sources: Array<{
+        docId: string | undefined;
+        docIndex: number;
+        score: number;
+    }>;
+}>, options?: {
+    threshold?: number;
+}): {
+    hallucinationRate: number;
+    sentences: Array<{
+        text: string;
+        classification: string;
+        bestScore: number;
+        bestSource: object | null;
+    }>;
+    summary: {
+        grounded: number;
+        likely_hallucination: number;
+        definite_hallucination: number;
+    };
+};

package/dist/types/citation/source-mapper.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Map a sentence to its most relevant source documents by how much of the
+ * sentence each document supports (see computeSupportScore).
+ * @param {string} sentence - The sentence to map
+ * @param {Array<{content?: string, text?: string, id?: string}>} docs - Source documents
+ * @param {object} [options] - Configuration options
+ * @param {number} [options.maxCitations=3] - Maximum number of citations to return
+ * @param {number} [options.threshold=0.5] - Minimum similarity threshold
+ * @param {Map<string, number>|null} [options.idfWeights=null] - Optional IDF weights for weighted similarity
+ * @returns {Array<{docIndex: number, docId: string|undefined, score: number, matchedTokens: string[]}>}
+ */
+export function mapSentenceToSources(sentence: string, docs: Array<{
+    content?: string;
+    text?: string;
+    id?: string;
+}>, options?: {
+    maxCitations?: number;
+    threshold?: number;
+    idfWeights?: Map<string, number> | null;
+}): Array<{
+    docIndex: number;
+    docId: string | undefined;
+    score: number;
+    matchedTokens: string[];
+}>;
+/**
+ * Build IDF (Inverse Document Frequency) weights from a collection of documents.
+ * IDF = log(1 + totalDocs / docsContainingToken). The +1 keeps weights
+ * positive, so tokens found in every document (and every token when only one
+ * document was retrieved) still count instead of weighing zero.
+ * @param {Array<{content?: string, text?: string}>} docs - Array of document objects
+ * @returns {Map<string, number>} Map of token to IDF weight
+ */
+export function buildIDFWeights(docs: Array<{
+    content?: string;
+    text?: string;
+}>): Map<string, number>;

package/dist/types/connectors/anthropic-connector.d.ts

@@ -0,0 +1,97 @@
+/**
+ * LLM connector for the Anthropic Claude API.
+ * Uses axios for HTTP calls and supports streaming via SSE.
+ *
+ * @extends BaseConnector
+ */
+export class AnthropicConnector extends BaseConnector {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.model='claude-3-5-sonnet-20241022'] - Claude model to use
+     * @param {string} [options.apiKey] - Anthropic API key (defaults to ANTHROPIC_API_KEY at construction)
+     * @param {string} [options.baseURL='https://api.anthropic.com'] - API base URL
+     * @param {string} [options.apiVersion='2023-06-01'] - API version header
+     * @param {number} [options.maxTokens=4096] - Max tokens in response
+     * @param {number} [options.temperature=0.7] - Sampling temperature
+     * @param {number} [options.maxRetries=3] - Retries for transient failures
+     * @param {number} [options.retryDelay=1000] - Base backoff delay in ms
+     * @param {string} [options.systemPrompt] - System prompt used when RAG context is supplied
+     */
+    constructor(options?: {
+        model?: string;
+        apiKey?: string;
+        baseURL?: string;
+        apiVersion?: string;
+        maxTokens?: number;
+        temperature?: number;
+        maxRetries?: number;
+        retryDelay?: number;
+        systemPrompt?: string;
+    });
+    /**
+     * Cache identity for createRagPipeline({ cache }).
+     * @param {'llm'} role
+     * @returns {string|null}
+     */
+    getCacheKey(role: "llm"): string | null;
+    config: any;
+    client: import("axios").AxiosInstance;
+    /**
+     * @throws {Error} code MISSING_API_KEY when no key is configured
+     * @private
+     */
+    private _requireApiKey;
+    /**
+     * Build the Messages API request body. Retrieved context goes into the
+     * user message as delimited, untrusted reference data; the system prompt
+     * only carries instructions.
+     * @private
+     */
+    private _buildBody;
+    /**
+     * Generate a response from Claude using the provided query and optional RAG context.
+     *
+     * @param {string} query - The user query / prompt
+     * @param {Array<Object|string>} [context=[]] - Retrieved documents for RAG
+     * @param {Object} [options={}] - Override model, temperature, maxTokens per-call
+     * @param {AbortSignal} [options.signal] - Cancels the request
+     * @returns {Promise<string>} The generated text
+     */
+    generate(query: string, context?: Array<any | string>, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /**
+     * Stream a response from Claude token-by-token via SSE.
+     *
+     * @param {string} query - The user query / prompt
+     * @param {Array<Object|string>} [context=[]] - Retrieved documents for RAG
+     * @param {Object} [options={}] - Override model, temperature, maxTokens per-call
+     * @param {AbortSignal} [options.signal] - Cancels the stream
+     * @yields {{ token: string, done: boolean }}
+     */
+    generateStream(query: string, context?: Array<any | string>, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<{
+        token: any;
+        done: boolean;
+    }, void, unknown>;
+    /**
+     * Build a single prompt string that includes RAG context when available.
+     * Kept for backward compatibility; the context is delimited and labelled
+     * as untrusted reference data.
+     *
+     * @param {string} query - User query
+     * @param {Array<Object|string>} context - RAG context documents
+     * @returns {string} Combined prompt
+     * @private
+     */
+    private _buildPrompt;
+}
+/**
+ * Default configuration for the Anthropic connector.
+ * `apiKey` is a getter so the environment is read when a connector is
+ * constructed, not when this module is first required.
+ * @type {Object}
+ */
+export const DEFAULT_CONFIG: any;
+import { BaseConnector } from "./base-connector";

package/dist/types/connectors/base-connector.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Abstract base class for all connectors.
+ * Provides connection lifecycle, health checking, and retry logic.
+ * @extends EventEmitter
+ */
+export class BaseConnector extends EventEmitter<[never]> {
+    /**
+     * @param {Object} options
+     * @param {string} [options.name] - Connector display name
+     */
+    constructor(options?: {
+        name?: string;
+    });
+    options: {
+        name?: string;
+    };
+    connected: boolean;
+    name: string;
+    /**
+     * Establish the connection.
+     * Override in subclass for custom connection logic.
+     * @returns {Promise<void>}
+     */
+    connect(): Promise<void>;
+    /**
+     * Tear down the connection.
+     * Override in subclass for custom disconnection logic.
+     * @returns {Promise<void>}
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check whether the connector is healthy and operational.
+     * Override in subclass for custom health checks.
+     * @returns {Promise<boolean>}
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Retry wrapper for transient failures.
+     *
+     * Only retryable errors are retried: network errors and HTTP
+     * 408/409/425/429/5xx (see {@link isRetryableError}). Other errors
+     * (400, 401, 403, 404, aborts, errors with no status or network code) are
+     * thrown immediately. Backoff is exponential with full jitter, starting at
+     * `delay` and capped at `opts.maxDelay`; a Retry-After header on the error
+     * is honoured (capped at `opts.maxDelay`). Emits a 'retry' event before
+     * each retry.
+     *
+     * @param {Function} fn - Async function to execute; receives the attempt number
+     * @param {number} [retries=3] - Maximum number of retry attempts
+     * @param {number} [delay=1000] - Base backoff delay in ms
+     * @param {object} [opts]
+     * @param {AbortSignal} [opts.signal] - Aborts the call and any pending backoff
+     * @param {number} [opts.maxDelay=30000] - Upper bound for a single backoff delay
+     * @param {(err: *) => boolean} [opts.shouldRetry] - Override retry classification
+     * @returns {Promise<*>} Result of the function
+     * @throws {Error} The first non-retryable error, or the last error once retries are exhausted
+     */
+    withRetry(fn: Function, retries?: number, delay?: number, opts?: {
+        signal?: AbortSignal;
+        maxDelay?: number;
+        shouldRetry?: (err: any) => boolean;
+    }): Promise<any>;
+    /**
+     * Wait between retries. Overridable in tests.
+     * @param {number} ms
+     * @param {AbortSignal} [signal]
+     * @returns {Promise<void>}
+     * @protected
+     */
+    protected _sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * Jitter source for retry backoff. Overridable in tests.
+     * @returns {number} Value in [0, 1)
+     * @protected
+     */
+    protected _random(): number;
+    /**
+     * Return basic information about the connector.
+     * @returns {{ name: string, connected: boolean, type: string }}
+     */
+    getInfo(): {
+        name: string;
+        connected: boolean;
+        type: string;
+    };
+}
+import { EventEmitter } from "events";

package/dist/types/connectors/cohere-connector.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Embedder + reranker connector for the Cohere API.
+ * Provides text embeddings (with separate document/query input types) and
+ * document reranking capabilities.
+ *
+ * @extends BaseConnector
+ */
+export class CohereConnector extends BaseConnector {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.apiKey] - Cohere API key
+     * @param {string} [options.baseURL='https://api.cohere.ai/v1'] - API base URL
+     * @param {string} [options.embeddingModel='embed-english-v3.0'] - Embedding model
+     * @param {string} [options.rerankModel='rerank-english-v3.0'] - Reranking model
+     * @param {string} [options.inputType='search_document'] - Input type for document embeddings
+     * @param {string} [options.queryInputType='search_query'] - Input type for query embeddings
+     */
+    constructor(options?: {
+        apiKey?: string;
+        baseURL?: string;
+        embeddingModel?: string;
+        rerankModel?: string;
+        inputType?: string;
+        queryInputType?: string;
+    });
+    /**
+     * Cache identity for createRagPipeline({ cache }).
+     * @param {'embedder'} role
+     * @returns {string|null}
+     */
+    getCacheKey(role: "embedder"): string | null;
+    config: any;
+    client: import("axios").AxiosInstance;
+    /**
+     * @throws {Error} code MISSING_API_KEY when no key is configured
+     * @private
+     */
+    private _requireApiKey;
+    /**
+     * POST with the connector's retry policy and cancellation.
+     * @param {string} path
+     * @param {object} body
+     * @param {AbortSignal} [signal]
+     * @returns {Promise<object>} Response data
+     * @private
+     */
+    private _post;
+    /**
+     * Generate an embedding vector for document text.
+     * Uses the document input type by default.
+     *
+     * @param {string} text - Input text to embed
+     * @param {Object} [options={}]
+     * @param {AbortSignal} [options.signal] - Cancels the request
+     * @returns {Promise<number[]>} Embedding vector
+     */
+    embed(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<number[]>;
+    /**
+     * Generate an embedding vector for a search query.
+     * Uses the query input type for better retrieval accuracy.
+     *
+     * @param {string} query - Query text to embed
+     * @param {Object} [options={}]
+     * @param {AbortSignal} [options.signal] - Cancels the request
+     * @returns {Promise<number[]>} Embedding vector
+     */
+    embedQuery(query: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<number[]>;
+    /**
+     * Rerank documents by relevance to a query using Cohere's reranker.
+     *
+     * @param {string} query - The search query
+     * @param {Array<Object|string>} documents - Documents to rerank
+     * @param {Object} [options={}]
+     * @param {number} [options.topK] - Number of top results to return (defaults to all)
+     * @param {AbortSignal} [options.signal] - Cancels the request
+     * @returns {Promise<Array<Object>>} Reranked documents with relevance scores
+     */
+    rerank(query: string, documents: Array<any | string>, options?: {
+        topK?: number;
+        signal?: AbortSignal;
+    }): Promise<Array<any>>;
+}
+/**
+ * Default configuration for the Cohere connector.
+ * `apiKey` is a getter so the environment is read when a connector is
+ * constructed, not when this module is first required.
+ * @type {Object}
+ */
+export const DEFAULT_CONFIG: any;
+import { BaseConnector } from "./base-connector";

package/dist/types/connectors/connector-utils.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Create an AbortError for the given signal.
+ * Reuses signal.reason when it already is an AbortError.
+ *
+ * @param {AbortSignal} [signal]
+ * @returns {Error} Error with name 'AbortError' and code 'ABORT_ERR'
+ */
+export function createAbortError(signal?: AbortSignal): Error;
+/**
+ * @param {*} err
+ * @returns {boolean} True when err represents a cancellation.
+ */
+export function isAbortError(err: any): boolean;
+/**
+ * Throw an AbortError when the signal is already aborted.
+ * @param {AbortSignal} [signal]
+ */
+export function throwIfAborted(signal?: AbortSignal): void;
+/**
+ * Race a promise against an AbortSignal so callers reject promptly even when
+ * the underlying SDK or HTTP client ignores the signal. The abort listener is
+ * removed once the promise settles.
+ *
+ * @template T
+ * @param {Promise<T>|(() => Promise<T>)} work - Promise or function returning one
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<T>}
+ */
+export function raceAbort<T>(work: Promise<T> | (() => Promise<T>), signal?: AbortSignal): Promise<T>;
+/**
+ * Sleep that rejects with AbortError as soon as the signal aborts.
+ * @param {number} ms
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<void>}
+ */
+export function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Extract the HTTP status from an openai SDK error or an axios error.
+ * @param {*} err
+ * @returns {number|undefined}
+ */
+export function getErrorStatus(err: any): number | undefined;
+/**
+ * Parse Retry-After / retry-after-ms from an error's response headers.
+ *
+ * @param {*} err
+ * @param {number} [now=Date.now()]
+ * @returns {number|undefined} Delay in milliseconds, or undefined when absent
+ */
+export function getRetryAfterMs(err: any, now?: number): number | undefined;
+/**
+ * Default retry classification: network failures and HTTP
+ * 408/409/425/429/5xx are retried; aborts, other 4xx (400, 401, 403, 404,
+ * 422, ...) and errors without a status or network code are not.
+ *
+ * @param {*} err
+ * @returns {boolean}
+ */
+export function isRetryableError(err: any): boolean;
+/**
+ * Compute the delay before the next retry attempt.
+ * Honours Retry-After (capped at maxDelay); otherwise uses exponential backoff
+ * with full jitter: random() * min(maxDelay, baseDelay * 2^attempt).
+ *
+ * @param {*} err - The error that triggered the retry
+ * @param {number} attempt - Zero-based retry attempt
+ * @param {object} [opts]
+ * @param {number} [opts.baseDelay=1000]
+ * @param {number} [opts.maxDelay=30000]
+ * @param {() => number} [opts.random=Math.random]
+ * @returns {number} Delay in milliseconds
+ */
+export function computeRetryDelay(err: any, attempt: number, opts?: {
+    baseDelay?: number;
+    maxDelay?: number;
+    random?: () => number;
+}): number;
+/**
+ * Resolve an API key at construction time. An explicit option (even '')
+ * wins over the environment variable.
+ *
+ * @param {object} options - Connector options
+ * @param {string} envVar - Environment variable name
+ * @returns {string}
+ */
+export function resolveApiKey(options: object, envVar: string): string;
+/**
+ * Error thrown when a provider call is attempted without an API key.
+ * @param {string} provider - Display name, e.g. 'OpenAI'
+ * @param {string} envVar - Environment variable name
+ * @returns {Error}
+ */
+export function missingApiKeyError(provider: string, envVar: string): Error;
+/**
+ * Build request options carrying the signal only when one was supplied, so
+ * calls without a signal look exactly as before.
+ * @param {AbortSignal} [signal]
+ * @returns {object}
+ */
+export function signalOptions(signal?: AbortSignal): object;
+/**
+ * Shared helpers for the built-in connectors: AbortSignal handling, retry
+ * classification and backoff, and API key resolution.
+ *
+ * Everything here must run on Node 18 (no AbortSignal.any, no crypto.hash).
+ */
+/** HTTP status codes that are worth retrying. */
+export const RETRYABLE_STATUS: Set<number>;
+/** Error codes produced by Node, axios and undici for transient network failures. */
+export const RETRYABLE_CODES: Set<string>;

package/dist/types/connectors/local-embedder.d.ts

@@ -0,0 +1,95 @@
+/**
+ * TF-IDF based embedder for fully offline use.
+ * No external API required -- builds a vocabulary from training documents
+ * and produces sparse TF-IDF vectors.
+ * @extends BaseConnector
+ */
+export class LocalEmbedder extends BaseConnector {
+    /**
+     * @param {Object} options
+     * @param {number} [options.maxVocabularySize=10000] - Maximum vocabulary size
+     * @param {number} [options.minDocFrequency=1] - Minimum document frequency for a token to be included
+     */
+    constructor(options?: {
+        maxVocabularySize?: number;
+        minDocFrequency?: number;
+    });
+    config: any;
+    /** @type {Map<string, number>} token -> vocabulary index */
+    vocabulary: Map<string, number>;
+    /** @type {Map<string, number>} token -> IDF weight */
+    idf: Map<string, number>;
+    /** @type {number} */
+    docCount: number;
+    /**
+     * Build vocabulary and IDF weights from a corpus of documents.
+     * @param {Array<string|{ content?: string, text?: string }>} documents - Training documents
+     */
+    train(documents: Array<string | {
+        content?: string;
+        text?: string;
+    }>): void;
+    _fingerprint: string;
+    /**
+     * Compute a TF-IDF vector for the given text.
+     * The vector length equals the vocabulary size. Synchronous; when
+     * options.signal is already aborted it throws an AbortError (which an
+     * awaiting caller sees as a rejection).
+     * @param {string} text - Text to embed
+     * @param {Object} [options={}]
+     * @param {AbortSignal} [options.signal] - Cancellation signal
+     * @returns {number[]} L2-normalized TF-IDF vector
+     */
+    embed(text: string, options?: {
+        signal?: AbortSignal;
+    }): number[];
+    /**
+     * Compute a TF-IDF vector for a query string.
+     * Alias for {@link embed}.
+     * @param {string} query - Query text to embed
+     * @param {Object} [options={}] - Same as embed()
+     * @returns {number[]} L2-normalized TF-IDF vector
+     */
+    embedQuery(query: string, options?: any): number[];
+    /**
+     * Serializable vocabulary and IDF weights, so a trained embedder can be
+     * restored in another process (e.g. by FileVectorStore-backed CLI queries).
+     *
+     * @returns {{docCount: number, vocabulary: Array<[string, number]>, idf: Array<[string, number]>}}
+     */
+    getState(): {
+        docCount: number;
+        vocabulary: Array<[string, number]>;
+        idf: Array<[string, number]>;
+    };
+    /**
+     * Restore state produced by getState().
+     * @param {{docCount: number, vocabulary: Array<[string, number]>, idf: Array<[string, number]>}} state
+     */
+    setState(state: {
+        docCount: number;
+        vocabulary: Array<[string, number]>;
+        idf: Array<[string, number]>;
+    }): void;
+    /**
+     * Cache identity for createRagPipeline({ cache }): a fingerprint of the
+     * trained vocabulary and IDF weights, so retraining invalidates cached
+     * query vectors (also across processes sharing a Redis cache).
+     * @param {'embedder'} role
+     * @returns {string|null}
+     */
+    getCacheKey(role: "embedder"): string | null;
+    /** @returns {number} Vector length produced by embed() once trained */
+    get dimensions(): number;
+    /**
+     * Get the current vocabulary size.
+     * @returns {number}
+     */
+    getVocabularySize(): number;
+}
+/**
+ * Default configuration for the local TF-IDF embedder.
+ * @type {Object}
+ */
+export const DEFAULT_CONFIG: any;
+import { BaseConnector } from "./base-connector";