@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

package/dist/types/evaluate/scoring.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Common English function words. Ignored when measuring how much of a
+ * sentence a document supports, so "the" and "is" cannot ground a claim.
+ */
+export const STOPWORDS: Set<string>;
+/**
+ * Content tokens of a sentence: tokens minus stopwords. Falls back to all
+ * tokens when nothing is left (e.g. "Yes."), so short sentences are still
+ * scored rather than skipped.
+ *
+ * @param {string[]} tokens
+ * @returns {string[]}
+ */
+export function contentTokens(tokens: string[]): string[];
+/**
+ * How much of a claim is supported by a document: the (optionally
+ * IDF-weighted) fraction of the claim's unique content tokens that appear in
+ * the document. Unlike Jaccard against the whole document, this does not
+ * shrink as the document gets longer, so a sentence copied verbatim from a
+ * long chunk scores 1.
+ *
+ * Numeric consistency: when `options.claimText` and `options.docText` are
+ * given and the claim states a number the document does not contain (see
+ * checkNumericConsistency), the score becomes
+ *   lexicalScore * NUMERIC_MISMATCH_FACTOR (0.4) * matchedNumbers / claimNumbers
+ * which is always below 0.4, so the claim fails the default 0.5 threshold.
+ *
+ * @param {string[]} claimTokens - Tokens of the sentence/claim/query
+ * @param {string[]|Set<string>} docTokens - Tokens of the document
+ * @param {Map<string, number>|null} [idfWeights] - Optional token weights
+ * @param {{ claimText?: string, docText?: string }} [options] - Raw texts
+ *   enabling the numeric consistency check
+ * @returns {number} Support score between 0 and 1
+ */
+export function computeSupportScore(claimTokens: string[], docTokens: string[] | Set<string>, idfWeights?: Map<string, number> | null, options?: {
+    claimText?: string;
+    docText?: string;
+}): number;
+/**
+ * Numeric consistency between a claim and a document: every number the claim
+ * states (digits, decimals, percentages or number words) must also appear in
+ * the document. Lexical overlap alone would ground "thirty days" against a
+ * source that says "twenty days".
+ *
+ * @param {string} claimText
+ * @param {string} docText
+ * @returns {{ consistent: boolean, claimNumbers: string[], missing: string[] }}
+ */
+export function checkNumericConsistency(claimText: string, docText: string): {
+    consistent: boolean;
+    claimNumbers: string[];
+    missing: string[];
+};
+/**
+ * Extract the numbers stated in a text, as normalised value strings, so
+ * "20", "20%", "twenty" and "Twenty" all yield "20", "1,000" yields "1000"
+ * and "2.5" yields "2.5".
+ *
+ * @param {string} text
+ * @returns {{ values: string[], parts: string[] }} values: one entry per
+ *   number as written; parts: values plus each number word on its own
+ *   (used on the document side so "twenty-five" also supports "20" and "5"
+ *   is not required)
+ */
+export function extractNumbers(text: string): {
+    values: string[];
+    parts: string[];
+};
+/**
+ * Multiplier applied to the support score when a claim states numbers the
+ * document does not contain. Together with the share of matching numbers it
+ * keeps the score below 0.4, i.e. under the default 0.5 support threshold.
+ */
+export const NUMERIC_MISMATCH_FACTOR: 0.4;
+/**
+ * Score a prompt-answer pair using multiple metrics
+ * @param {string} actual - LLM response
+ * @param {string} expected - Reference answer
+ * @returns {{ bleu: number, rouge: number }}
+ */
+export function scoreAnswer(_actual: any, _expected: any): {
+    bleu: number;
+    rouge: number;
+};
+/**
+ * Version: 0.1.0
+ * Path: /src/evaluate/scoring.js
+ * Description: Basic scoring metrics (BLEU, ROUGE-L) for RAG output evaluation
+ * Author: Ali Kahwaji
+ */
+/**
+ * Tokenize a string by words
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function tokenize(text: string): string[];
+/**
+ * Compute BLEU-1 score: unigram precision
+ * @param {string[]} candidate - Generated tokens
+ * @param {string[]} reference - Reference tokens
+ * @returns {number}
+ */
+export function computeBLEU(_candidate: any, _reference: any): number;
+/**
+ * Compute ROUGE-L (Longest Common Subsequence) recall
+ * @param {string[]} candidate
+ * @param {string[]} reference
+ * @returns {number}
+ */
+export function computeROUGE(_candidate: any, _reference: any): number;
+/**
+ * Split text into sentences on sentence-ending punctuation
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function splitSentences(text: string): string[];
+/**
+ * Compute Jaccard similarity between two token arrays
+ * @param {string[]} tokensA
+ * @param {string[]} tokensB
+ * @returns {number} Similarity score between 0 and 1
+ */
+export function computeJaccardSimilarity(tokensA: string[], tokensB: string[]): number;

package/dist/types/evaluate/semantic-similarity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @param {string} answer - The generated answer
+ * @param {string} reference - The reference (ground-truth) answer
+ * @param {Object} options
+ * @param {Object} options.embedder - Any embedder with embed() or embedQuery()
+ *   (a built-in connector, LocalEmbedder fitted to your corpus, an AI SDK
+ *   adapter, HashEmbedder from /testing)
+ * @param {AbortSignal} [options.signal]
+ * @returns {Promise<number>} Cosine similarity clamped to 0..1
+ */
+export function computeSemanticSimilarity(answer: string, reference: string, { embedder, signal }?: {
+    embedder: any;
+    signal?: AbortSignal;
+}): Promise<number>;

package/dist/types/experimental.d.ts

@@ -0,0 +1,15 @@
+import { MultiModalProcessor } from "./ai/multimodal";
+import { AdaptiveRetrievalEngine } from "./ai/retrieval-engine";
+import { FederatedLearningCoordinator } from "./ai/federation/federated-learning-coordinator";
+import { ModelTrainingOrchestrator } from "./ai/training/model-training-orchestrator";
+import { DataGovernanceManager } from "./enterprise/data-governance";
+import { TenantManager } from "./enterprise/multi-tenancy";
+import { ResourceMonitor } from "./enterprise/multi-tenancy";
+import { SSOManager } from "./enterprise/sso-integration";
+import { SAMLProvider } from "./enterprise/sso-integration";
+import { OAuth2Provider } from "./enterprise/sso-integration";
+import { ActiveDirectoryProvider } from "./enterprise/sso-integration";
+import { OIDCProvider } from "./enterprise/sso-integration";
+import { PluginSandbox } from "./security/plugin-sandbox";
+import { PluginCertification } from "./ecosystem/plugin-certification";
+export { MultiModalProcessor, AdaptiveRetrievalEngine, FederatedLearningCoordinator, ModelTrainingOrchestrator, DataGovernanceManager, DataGovernanceManager as DataGovernance, TenantManager, ResourceMonitor, SSOManager, SAMLProvider, OAuth2Provider, ActiveDirectoryProvider, OIDCProvider, PluginSandbox, PluginCertification };

package/dist/types/graph/entity-extractor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Heuristic entity extraction from text — no LLM required.
+ *
+ * Uses configurable regex patterns to identify named entities,
+ * dates, measurements, URLs, emails, and technical terms.
+ */
+export class EntityExtractor extends EventEmitter<[never]> {
+    /**
+     * @param {Object} [options={}] - Extractor options
+     * @param {Object<string, RegExp>} [options.patterns] - Custom patterns to merge with defaults
+     */
+    constructor(options?: {
+        patterns?: {
+            [x: string]: RegExp;
+        };
+    });
+    patterns: {
+        [x: string]: RegExp;
+    };
+    config: {
+        patterns?: {
+            [x: string]: RegExp;
+        };
+    };
+    /**
+     * Extract entities from a single text string.
+     *
+     * For each configured pattern type, finds all matches, deduplicates
+     * by normalized name, and returns an array of entity descriptors.
+     *
+     * @param {string} text - Input text to extract entities from
+     * @returns {Array<{name: string, type: string, positions: Array<{start: number, end: number}>, frequency: number}>}
+     */
+    extract(text: string): Array<{
+        name: string;
+        type: string;
+        positions: Array<{
+            start: number;
+            end: number;
+        }>;
+        frequency: number;
+    }>;
+    /**
+     * Extract relationships between entities that co-occur in the same sentence.
+     *
+     * @param {string} text - Input text
+     * @param {Array<{name: string, type: string}>} entities - Previously extracted entities
+     * @returns {Array<{from: string, to: string, type: string, context: string}>}
+     */
+    extractRelationships(text: string, entities: Array<{
+        name: string;
+        type: string;
+    }>): Array<{
+        from: string;
+        to: string;
+        type: string;
+        context: string;
+    }>;
+    /**
+     * Extract entities and relationships from multiple documents.
+     *
+     * Combines entities across documents and tracks which source
+     * document(s) each entity originates from.
+     *
+     * @param {Array<{id: string, content: string, metadata?: Object}>} documents
+     * @returns {{entities: Array, relationships: Array}}
+     */
+    extractFromDocuments(documents: Array<{
+        id: string;
+        content: string;
+        metadata?: any;
+    }>): {
+        entities: any[];
+        relationships: any[];
+    };
+}
+/**
+ * Default regex patterns for heuristic entity extraction.
+ * @type {Object<string, RegExp>}
+ */
+export const DEFAULT_PATTERNS: {
+    [x: string]: RegExp;
+};
+import { EventEmitter } from "events";

package/dist/types/graph/graph-index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Fast entity lookup index for the knowledge graph.
+ *
+ * Maintains secondary indexes by type, name, and arbitrary properties
+ * for efficient querying without full graph traversal.
+ */
+export class GraphIndex {
+    /** @type {Map<string, Set<string>>} type -> Set of entity IDs */
+    byType: Map<string, Set<string>>;
+    /** @type {Map<string, string>} normalized name -> entity ID */
+    byName: Map<string, string>;
+    /** @type {Map<string, Map<*, Set<string>>>} propertyKey -> Map of value -> Set of entity IDs */
+    byProperty: Map<string, Map<any, Set<string>>>;
+    /**
+     * Index an entity by type, name, and each of its properties.
+     * @param {{id: string, type: string, properties: Object}} entity
+     */
+    indexEntity(entity: {
+        id: string;
+        type: string;
+        properties: any;
+    }): void;
+    /**
+     * Fuzzy search for entities whose name contains the query (case-insensitive).
+     *
+     * Results are sorted by relevance: exact matches first, then partial matches.
+     *
+     * @param {string} query - Search query
+     * @returns {string[]} Array of matching entity IDs
+     */
+    searchByName(query: string): string[];
+    /**
+     * Return all entity IDs of a given type.
+     * @param {string} type - Entity type
+     * @returns {string[]} Array of entity IDs
+     */
+    searchByType(type: string): string[];
+    /**
+     * Return entity IDs matching a property key-value pair.
+     * @param {string} key - Property key
+     * @param {*} value - Property value
+     * @returns {string[]} Array of entity IDs
+     */
+    searchByProperty(key: string, value: any): string[];
+    /**
+     * Clear all indexes.
+     */
+    clear(): void;
+}

package/dist/types/graph/graph-retriever.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Retriever that uses a knowledge graph for document retrieval.
+ *
+ * Combines entity-based graph traversal with token-overlap text scoring
+ * to rank and retrieve relevant documents from a corpus.
+ */
+export class GraphRetriever extends EventEmitter<[never]> {
+    /**
+     * @param {Object} [options={}] - Retriever options
+     * @param {number} [options.traversalDepth=2] - Graph traversal depth
+     * @param {number} [options.maxResults=10] - Maximum results to return
+     * @param {number} [options.entityWeight=0.6] - Weight for entity-graph score
+     * @param {number} [options.textWeight=0.4] - Weight for text-overlap score
+     * @param {Object} [options.extractorOptions] - Options for the EntityExtractor
+     */
+    constructor(options?: {
+        traversalDepth?: number;
+        maxResults?: number;
+        entityWeight?: number;
+        textWeight?: number;
+        extractorOptions?: any;
+    });
+    config: any;
+    graph: KnowledgeGraph;
+    extractor: EntityExtractor;
+    index: GraphIndex;
+    /** @type {Map<string, {id: string, content: string, metadata: Object}>} */
+    documents: Map<string, {
+        id: string;
+        content: string;
+        metadata: any;
+    }>;
+    /**
+     * Store documents, extract entities and relationships, and build the graph.
+     *
+     * @param {Array<{id: string, content: string, metadata?: Object}>} documents
+     * @returns {Promise<void>}
+     */
+    store(documents: Array<{
+        id: string;
+        content: string;
+        metadata?: any;
+    }>): Promise<void>;
+    /**
+     * Retrieve documents relevant to a query using graph + text scoring.
+     *
+     * @param {string|{query: string, topK?: number}} queryOrObj - Query string or options object
+     * @param {number} [k] - Number of results (overrides config.maxResults)
+     * @returns {Promise<Array<{id: string, score: number, content: string, metadata: Object}>>}
+     */
+    retrieve(queryOrObj: string | {
+        query: string;
+        topK?: number;
+    }, k?: number): Promise<Array<{
+        id: string;
+        score: number;
+        content: string;
+        metadata: any;
+    }>>;
+    /**
+     * Return basic graph statistics.
+     * @returns {{entityCount: number, relationshipCount: number}}
+     */
+    getGraphStats(): {
+        entityCount: number;
+        relationshipCount: number;
+    };
+    /**
+     * Clear all stored data, the graph, and indexes.
+     */
+    clear(): void;
+}
+/**
+ * Default configuration for the GraphRetriever.
+ * @type {Object}
+ */
+export const DEFAULT_CONFIG: any;
+import { EventEmitter } from "events";
+import { KnowledgeGraph } from "./knowledge-graph";
+import { EntityExtractor } from "./entity-extractor";
+import { GraphIndex } from "./graph-index";

package/dist/types/graph/knowledge-graph.d.ts

@@ -0,0 +1,129 @@
+/**
+ * In-memory knowledge graph with entities and relationships.
+ *
+ * Stores typed entities and directed relationships between them,
+ * supporting traversal, pattern-based querying, and adjacency lookups.
+ */
+export class KnowledgeGraph extends EventEmitter<[never]> {
+    /**
+     * @param {Object} [options={}] - Graph configuration options
+     */
+    constructor(options?: any);
+    /** @type {Map<string, {id: string, type: string, properties: Object, labels: string[]}>} */
+    entities: Map<string, {
+        id: string;
+        type: string;
+        properties: any;
+        labels: string[];
+    }>;
+    /** @type {Map<string, {id: string, from: string, to: string, type: string, properties: Object}>} */
+    relationships: Map<string, {
+        id: string;
+        from: string;
+        to: string;
+        type: string;
+        properties: any;
+    }>;
+    /** @type {Map<string, Set<string>>} */
+    adjacency: Map<string, Set<string>>;
+    options: any;
+    _relationshipCounter: number;
+    /**
+     * Add an entity to the graph.
+     * @param {string} id - Unique entity identifier
+     * @param {string} type - Entity type (e.g. 'person', 'date', 'url')
+     * @param {Object} [properties={}] - Arbitrary key-value properties
+     * @returns {{id: string, type: string, properties: Object, labels: string[]}}
+     */
+    addEntity(id: string, type: string, properties?: any): {
+        id: string;
+        type: string;
+        properties: any;
+        labels: string[];
+    };
+    /**
+     * Add a directed relationship between two entities.
+     * @param {string} fromId - Source entity ID
+     * @param {string} toId - Target entity ID
+     * @param {string} type - Relationship type (e.g. 'co-occurs', 'references')
+     * @param {Object} [properties={}] - Arbitrary key-value properties
+     * @returns {{id: string, from: string, to: string, type: string, properties: Object}}
+     * @throws {Error} If either entity does not exist
+     */
+    addRelationship(fromId: string, toId: string, type: string, properties?: any): {
+        id: string;
+        from: string;
+        to: string;
+        type: string;
+        properties: any;
+    };
+    /**
+     * Retrieve an entity by ID.
+     * @param {string} id - Entity ID
+     * @returns {{id: string, type: string, properties: Object, labels: string[]}|null}
+     */
+    getEntity(id: string): {
+        id: string;
+        type: string;
+        properties: any;
+        labels: string[];
+    } | null;
+    /**
+     * Get relationships for an entity, optionally filtered.
+     * @param {string} entityId - Entity ID
+     * @param {Object} [options={}] - Filter options
+     * @param {string} [options.type] - Filter by relationship type
+     * @param {'outgoing'|'incoming'|'both'} [options.direction='both'] - Direction filter
+     * @returns {Array<{id: string, from: string, to: string, type: string, properties: Object}>}
+     */
+    getRelationships(entityId: string, options?: {
+        type?: string;
+        direction?: "outgoing" | "incoming" | "both";
+    }): Array<{
+        id: string;
+        from: string;
+        to: string;
+        type: string;
+        properties: any;
+    }>;
+    /**
+     * BFS traversal from startId up to a given depth.
+     * @param {string} startId - Starting entity ID
+     * @param {number} [depth=2] - Maximum traversal depth
+     * @returns {{entities: Array, relationships: Array, paths: Array<string[]>}}
+     */
+    traverse(startId: string, depth?: number): {
+        entities: any[];
+        relationships: any[];
+        paths: Array<string[]>;
+    };
+    /**
+     * Query the graph by pattern matching.
+     * @param {Object} pattern - Query pattern
+     * @param {string} [pattern.entityType] - Filter entities by type
+     * @param {string} [pattern.relationshipType] - Filter relationships by type
+     * @param {Object} [pattern.properties] - Filter by property key-value pairs
+     * @returns {{entities: Array, relationships: Array}}
+     */
+    query(pattern: {
+        entityType?: string;
+        relationshipType?: string;
+        properties?: any;
+    }): {
+        entities: any[];
+        relationships: any[];
+    };
+    /**
+     * Return basic graph statistics.
+     * @returns {{entityCount: number, relationshipCount: number}}
+     */
+    getStats(): {
+        entityCount: number;
+        relationshipCount: number;
+    };
+    /**
+     * Clear all graph data.
+     */
+    clear(): void;
+}
+import { EventEmitter } from "events";

package/dist/types/grounding/check-answer.d.ts

@@ -0,0 +1,101 @@
+export type AnswerCheck = {
+    /**
+     * - Every sentence is supported by a source
+     */
+    grounded: boolean;
+    /**
+     * - Share of supported sentences, 0..1
+     */
+    groundedness: number;
+    /**
+     * - Sentences no source supports (this
+     * includes a sentence whose numbers do not match its source)
+     */
+    unsupported: string[];
+    /**
+     * - Sources
+     * supporting each sentence
+     */
+    citations: Array<{
+        sentence: string;
+        sources: any[];
+    }>;
+    /**
+     *   - Faithfulness, relevance, context precision (and context recall when a
+     *   referenceAnswer is given); only when `evaluate` is not false
+     */
+    evaluation: {
+        scores: any;
+        details: any;
+        metadata: any;
+    } | undefined;
+    /**
+     *   - The sources as they were checked
+     */
+    sources: Array<{
+        id: string;
+        content: string;
+        metadata: any;
+    }>;
+};
+/**
+ * @typedef {Object} AnswerCheck
+ * @property {boolean} grounded - Every sentence is supported by a source
+ * @property {number} groundedness - Share of supported sentences, 0..1
+ * @property {string[]} unsupported - Sentences no source supports (this
+ *   includes a sentence whose numbers do not match its source)
+ * @property {Array<{sentence: string, sources: Array}>} citations - Sources
+ *   supporting each sentence
+ * @property {{scores: Object, details: Object, metadata: Object}|undefined} evaluation
+ *   - Faithfulness, relevance, context precision (and context recall when a
+ *   referenceAnswer is given); only when `evaluate` is not false
+ * @property {Array<{id: string, content: string, metadata: Object}>} sources
+ *   - The sources as they were checked
+ */
+/**
+ * Check an answer against the sources it was generated from.
+ *
+ * @example
+ * // A LangChain chain's output
+ * const check = await checkAnswer({
+ *   question: input,
+ *   answer: result.answer,
+ *   sources: result.context, // LangChain Documents
+ * });
+ * if (!check.grounded) console.warn(check.unsupported);
+ *
+ * @param {Object} params
+ * @param {string} params.answer - The generated answer
+ * @param {Array<string|Object>} params.sources - Documents the answer was
+ *   generated from (see normalizeSources for accepted shapes)
+ * @param {string} [params.question] - The question; needed for relevance
+ * @param {string} [params.referenceAnswer] - Ground truth, for context recall
+ *   (and semantic similarity when an embedder is given)
+ * @param {Object} [params.embedder] - With a referenceAnswer, adds
+ *   `evaluation.scores.semanticSimilarity` (computeSemanticSimilarity)
+ * @param {boolean} [params.evaluate=true] - Also compute evaluation scores
+ * @returns {Promise<AnswerCheck>}
+ */
+export function checkAnswer({ answer, sources, question, referenceAnswer, embedder, evaluate, }?: {
+    answer: string;
+    sources: Array<string | any>;
+    question?: string;
+    referenceAnswer?: string;
+    embedder?: any;
+    evaluate?: boolean;
+}): Promise<AnswerCheck>;
+/**
+ * Normalize sources to `{ id, content, metadata }`.
+ *
+ * Accepts strings, `{ id, content }` (this library), LangChain Documents
+ * (`{ pageContent, metadata }`), LlamaIndex nodes (`{ text }`) and
+ * `NodeWithScore` (`{ node, score }`).
+ *
+ * @param {Array<string|Object>} sources
+ * @returns {Array<{id: string, content: string, metadata: Object}>}
+ */
+export function normalizeSources(sources: Array<string | any>): Array<{
+    id: string;
+    content: string;
+    metadata: any;
+}>;

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

@@ -0,0 +1,63 @@
+/**
+ * Pipeline wrapper that applies all three guardrail layers (pre-retrieval,
+ * retrieval, and post-generation) around an existing RAG pipeline. In strict
+ * mode, any guard failure aborts the pipeline; otherwise issues are collected
+ * as warnings and execution continues.
+ *
+ * @extends EventEmitter
+ */
+export class GuardrailsPipeline extends EventEmitter<[never]> {
+    /**
+     * @param {object} pipeline - The underlying RAG pipeline (must have a .run() method)
+     * @param {object} [options] - Override default configuration
+     * @param {object|false} [options.preRetrieval={}] - PreRetrievalGuard options, or false to disable
+     * @param {object|false} [options.retrieval={}] - RetrievalGuard options, or false to disable
+     * @param {object|false} [options.postGeneration={}] - PostGenerationGuard options, or false to disable
+     * @param {boolean} [options.strict=false] - Whether to block on any guard failure
+     */
+    constructor(pipeline: object, options?: {
+        preRetrieval?: object | false;
+        retrieval?: object | false;
+        postGeneration?: object | false;
+        strict?: boolean;
+    });
+    pipeline: any;
+    config: any;
+    preGuard: PreRetrievalGuard;
+    retrievalGuard: RetrievalGuard;
+    postGuard: PostGenerationGuard;
+    /**
+     * Run the full guarded pipeline.
+     *
+     * @param {object} input - Pipeline input
+     * @param {string} input.query - The user query
+     * @param {Float32Array} [input.queryVector] - Optional precomputed query vector
+     * @param {object} [input.options] - Additional pipeline options
+     * @param {object} [input.context] - Request context (e.g. userPermissions for ACL)
+     * @returns {Promise<object>} Pipeline result with guardrails metadata attached
+     */
+    run(input: {
+        query: string;
+        queryVector?: Float32Array;
+        options?: object;
+        context?: object;
+    }): Promise<object>;
+    /**
+     * Citations and evaluation details copy sentences from the raw answer, so
+     * scrub every string in them with the same PII patterns as the answer.
+     *
+     * @param {*} value - Object, array or string to redact in place
+     * @returns {*} The redacted value
+     * @private
+     */
+    private _redactDeep;
+}
+/**
+ * Default configuration for the GuardrailsPipeline.
+ * @type {object}
+ */
+export const DEFAULT_CONFIG: object;
+import { EventEmitter } from "events";
+import { PreRetrievalGuard } from "./pre-retrieval-guard";
+import { RetrievalGuard } from "./retrieval-guard";
+import { PostGenerationGuard } from "./post-generation-guard";