@devilsdev/rag-pipeline-utils 2.4.4 → 2.5.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/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/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";

package/dist/types/guardrails/injection-detector.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Detect prompt-injection attempts in text.
+ *
+ * Built-in rules run on the folded text. Custom patterns run on the
+ * normalised text (case preserved) and on the folded text.
+ *
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {Array<RegExp|string>} [opts.patterns=[]] - Extra patterns
+ * @param {boolean} [opts.useDefaults=true] - Include the built-in rules
+ * @returns {{ detected: boolean, matches: Array<{ id: string, pattern: string, match: string }>, normalized: string }}
+ */
+export function detectInjection(text: string, opts?: {
+    patterns?: Array<RegExp | string>;
+    useDefaults?: boolean;
+}): {
+    detected: boolean;
+    matches: Array<{
+        id: string;
+        pattern: string;
+        match: string;
+    }>;
+    normalized: string;
+};
+/**
+ * Normalise text for matching, without leetspeak/homoglyph folding.
+ * Case is preserved so case-sensitive custom patterns still work.
+ * @param {string} text
+ * @returns {string}
+ */
+export function normalizeText(text: string): string;
+/**
+ * Fully folded, lower-case form used by the built-in patterns.
+ * @param {string} text
+ * @returns {string}
+ */
+export function foldText(text: string): string;
+/**
+ * Built-in injection patterns. They run against the folded, lower-case text,
+ * so they are written in lower case and must stay narrow enough not to flag
+ * ordinary questions (e.g. "How does Redis act as a cache?").
+ * @type {Array<{ id: string, pattern: RegExp }>}
+ */
+export const DEFAULT_RULES: Array<{
+    id: string;
+    pattern: RegExp;
+}>;

package/dist/types/guardrails/post-generation-guard.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Post-generation guard that checks LLM output for PII leakage,
+ * groundedness against source documents, and length constraints.
+ * Sanitizes output by redacting detected PII.
+ *
+ * @extends EventEmitter
+ */
+export class PostGenerationGuard extends EventEmitter<[never]> {
+    /**
+     * @param {object} [options] - Override default configuration
+     * @param {boolean} [options.enablePIIDetection=true] - Whether to detect PII in output
+     * @param {boolean} [options.enableGroundednessCheck=true] - Whether to check groundedness
+     * @param {number} [options.groundednessThreshold=0.3] - Minimum groundedness score
+     * @param {number} [options.maxResponseLength=50000] - Maximum allowed response length
+     * @param {number} [options.minResponseLength=0] - Minimum response length
+     * @param {object} [options.piiPatterns] - Custom PII regex patterns (merged with defaults)
+     */
+    constructor(options?: {
+        enablePIIDetection?: boolean;
+        enableGroundednessCheck?: boolean;
+        groundednessThreshold?: number;
+        maxResponseLength?: number;
+        minResponseLength?: number;
+        piiPatterns?: object;
+    });
+    config: any;
+    /**
+     * Check generated output for safety issues, PII, and groundedness.
+     *
+     * @param {string} output - The LLM-generated output text
+     * @param {Array<object>} [retrievedDocs=[]] - Source documents for groundedness checking
+     * @returns {{
+     *   safe: boolean,
+     *   issues: string[],
+     *   sanitizedOutput: string,
+     *   groundednessScore?: number
+     * }}
+     * @fires PostGenerationGuard#checked
+     */
+    check(output: string, retrievedDocs?: Array<object>): {
+        safe: boolean;
+        issues: string[];
+        sanitizedOutput: string;
+        groundednessScore?: number;
+    };
+    /**
+     * Replace PII matches in arbitrary text with [REDACTED], using the same
+     * patterns as check(). Used to scrub text derived from the answer, such as
+     * citation sentences.
+     *
+     * @param {string} text
+     * @returns {string}
+     */
+    redact(text: string): string;
+}
+/**
+ * Default configuration for the PostGenerationGuard.
+ * @type {object}
+ */
+export const DEFAULT_CONFIG: object;
+import { EventEmitter } from "events";