@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

package/src/guardrails/injection-detector.js

@@ -0,0 +1,283 @@
+'use strict';
+
+/**
+ * Prompt-injection detection shared by PreRetrievalGuard (user queries) and
+ * RetrievalGuard (retrieved documents, opt-in).
+ *
+ * Text is normalised before matching so trivial obfuscation does not bypass
+ * the patterns: Unicode NFKC, removal of zero-width and format characters,
+ * control characters turned into spaces, diacritics stripped, common
+ * Cyrillic/Greek homoglyphs and leetspeak folded to ASCII letters, and
+ * whitespace collapsed. Detection never rewrites the caller's text.
+ */
+
+/**
+ * Build a character class from code points / [start, end] ranges, so the
+ * source stays ASCII-only.
+ * @param {Array<number|[number, number]>} items
+ * @returns {string}
+ */
+function charClass(items) {
+  const hex = (cp) => '\\u' + cp.toString(16).padStart(4, '0');
+  return items
+    .map((it) => (Array.isArray(it) ? `${hex(it[0])}-${hex(it[1])}` : hex(it)))
+    .join('');
+}
+
+/** Zero-width / invisible format characters removed before matching. */
+const INVISIBLE_RE = new RegExp(
+  `[${charClass([
+    0x00ad, // soft hyphen
+    0x034f, // combining grapheme joiner
+    0x061c, // arabic letter mark
+    0x115f,
+    0x1160, // hangul fillers
+    0x17b4,
+    0x17b5,
+    [0x180b, 0x180f], // mongolian variation selectors / vowel separator
+    [0x200b, 0x200f], // zero-width space/joiners, LRM/RLM
+    [0x202a, 0x202e], // bidi embeddings/overrides
+    [0x2060, 0x206f], // word joiner, invisible operators, bidi isolates
+    0x3164, // hangul filler
+    [0xfe00, 0xfe0f], // variation selectors
+    0xfeff, // BOM / zero-width no-break space
+    0xffa0, // halfwidth hangul filler
+  ])}]`,
+  'g',
+);
+
+/** C0/C1 control characters (other than whitespace), replaced by a space. */
+const CONTROL_RE = new RegExp(
+  `[${charClass([[0x00, 0x08], 0x0b, 0x0c, [0x0e, 0x1f], [0x7f, 0x9f]])}]`,
+  'g',
+);
+
+/** Cyrillic and Greek letters that look like Latin letters (code point -> letter). */
+const HOMOGLYPH_CODEPOINTS = [
+  // Cyrillic
+  [0x0430, 'a'],
+  [0x0432, 'b'],
+  [0x0435, 'e'],
+  [0x0451, 'e'],
+  [0x043a, 'k'],
+  [0x043c, 'm'],
+  [0x043d, 'h'],
+  [0x043e, 'o'],
+  [0x0440, 'p'],
+  [0x0441, 'c'],
+  [0x0442, 't'],
+  [0x0443, 'y'],
+  [0x0445, 'x'],
+  [0x0455, 's'],
+  [0x0456, 'i'],
+  [0x0457, 'i'],
+  [0x0458, 'j'],
+  [0x0501, 'd'],
+  [0x051b, 'q'],
+  [0x051d, 'w'],
+  [0x04cf, 'l'],
+  [0x0261, 'g'],
+  // Greek
+  [0x03b1, 'a'],
+  [0x03b2, 'b'],
+  [0x03b5, 'e'],
+  [0x03b7, 'n'],
+  [0x03b9, 'i'],
+  [0x03ba, 'k'],
+  [0x03bd, 'v'],
+  [0x03bf, 'o'],
+  [0x03c1, 'p'],
+  [0x03c4, 't'],
+  [0x03c5, 'u'],
+  [0x03c7, 'x'],
+  [0x03c9, 'w'],
+  [0x03f2, 'c'],
+];
+const HOMOGLYPHS = Object.fromEntries(
+  HOMOGLYPH_CODEPOINTS.map(([cp, letter]) => [
+    String.fromCodePoint(cp),
+    letter,
+  ]),
+);
+
+/** Leetspeak substitutions folded to letters (only in the folded copy). */
+const LEET = {
+  0: 'o',
+  1: 'i',
+  3: 'e',
+  4: 'a',
+  5: 's',
+  7: 't',
+  8: 'b',
+  '@': 'a',
+  $: 's',
+  '!': 'i',
+  '|': 'l',
+};
+
+/**
+ * Normalise text for matching, without leetspeak/homoglyph folding.
+ * Case is preserved so case-sensitive custom patterns still work.
+ * @param {string} text
+ * @returns {string}
+ */
+function normalizeText(text) {
+  return String(text)
+    .normalize('NFKC')
+    .replace(INVISIBLE_RE, '')
+    .replace(CONTROL_RE, ' ')
+    .normalize('NFD')
+    .replace(/\p{Mn}+/gu, '')
+    .normalize('NFC')
+    .replace(/[^\S\n]+/g, ' ')
+    .replace(/ ?\n\s*/g, '\n')
+    .trim();
+}
+
+/**
+ * Fully folded, lower-case form used by the built-in patterns.
+ * @param {string} text
+ * @returns {string}
+ */
+function foldText(text) {
+  const lower = normalizeText(text).toLowerCase();
+  let out = '';
+  for (const ch of lower) {
+    out += HOMOGLYPHS[ch] || LEET[ch] || ch;
+  }
+  // Separator tricks such as "i.g.n.o.r.e" or "i-g-n-o-r-e": join single
+  // letters separated by one punctuation/space character.
+  return out.replace(/\b(?:[a-z][.\-_* ]){3,}[a-z]\b/g, (m) =>
+    m.replace(/[.\-_* ]/g, ''),
+  );
+}
+
+/**
+ * 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 }>}
+ */
+const DEFAULT_RULES = [
+  {
+    id: 'ignore-instructions',
+    pattern:
+      /\b(?:ignore|disregard|forget|skip|override|bypass)\s+(?:all\s+|any\s+|the\s+|your\s+|my\s+|of\s+)*(?:previous|prior|above|preceding|earlier|former|original|system|initial)\s+(?:instructions?|prompts?|directions?|directives?|rules|guidelines|context|messages?)\b/,
+  },
+  {
+    id: 'forget-everything',
+    pattern:
+      /\bforget\s+(?:everything|all)\s+(?:you(?:'ve|\s+have|\s+were|\s+know|\s+learned)|(?:previous|prior|above|before|that\s+came))/,
+  },
+  {
+    id: 'role-override',
+    pattern:
+      /\byou\s+are\s+now\s+(?:an?\s+|my\s+|the\s+)?(?:[a-z'-]+\s+){0,2}(?:ai|assistant|bot|chatbot|model|llm|dan|hacker|unrestricted|unfiltered|uncensored|jailbroken|evil|persona|character)\b|\byou\s+are\s+now\s+(?:in\s+)?(?:developer|dan|god|admin|jailbreak|unrestricted)\s+mode\b|\byou\s+are\s+no\s+longer\s+(?:an?\s+)?(?:ai|assistant|bound|restricted|limited|chatgpt|claude)\b|\byou\s+are\s+dan\b/,
+  },
+  {
+    // "act as" only in imperative position: start of text/sentence, or after
+    // please/now/you must/will/should. "Redis acts as a cache" is not flagged.
+    id: 'act-as',
+    pattern:
+      /(?:^|[.!?:;\n]\s*|\b(?:please|now|you\s+(?:must|will|should|shall|can|are\s+to)|i\s+want\s+you\s+to)\s+)act\s+as\s+(?:if\s+you\b|an?\s+|my\s+|the\s+|though\b)/,
+  },
+  {
+    id: 'pretend',
+    pattern:
+      /\bpretend\s+(?:that\s+)?(?:you\s+are|you're|youre|you\s+have\s+no|to\s+be\s+(?:an?\s+)?(?:\w+\s+)?(?:ai|assistant|model|bot|chatbot|dan|unrestricted|unfiltered|uncensored|evil|hacker|jailbroken))\b/,
+  },
+  {
+    // Chat-template role markers: "system:" as a line prefix, [system],
+    // <|im_start|>system, [INST], <<SYS>>, "### system".
+    id: 'role-marker',
+    pattern:
+      /(?:^|\n)\s*(?:system|assistant|developer)\s*:|\[\s*(?:system|inst)\s*\]|<\|?\s*(?:im_start|system)\s*\|?>|<<\s*sys\s*>>|#{2,}\s*(?:system|instruction)s?\b/,
+  },
+  {
+    id: 'dan',
+    pattern: /\bdan\s+(?:mode|prompt|jailbreak)\b|\bdo\s+anything\s+now\b/,
+  },
+  {
+    id: 'bypass-restrictions',
+    pattern:
+      /\b(?:bypass|circumvent|evade)\s+(?:all\s+|any\s+|your\s+|the\s+|of\s+)*(?:ai\s+|safety\s+|content\s+|ethical\s+)?(?:restrictions|guardrails|safeguards|safety\s+(?:rules|measures|guidelines|filters?)|content\s+(?:polic(?:y|ies)|filters?)|moderation)\b|\b(?:disable|ignore|remove|turn\s+off|drop)\s+(?:all\s+(?:of\s+)?)?your\s+(?:safety\s+|content\s+|ethical\s+)?(?:restrictions|filters?|guardrails|safeguards|safety|rules|guidelines|programming)\b/,
+  },
+  {
+    id: 'override-safety',
+    pattern:
+      /\boverride\s+(?:your\s+|the\s+|all\s+)?(?:safety|content\s+(?:filters?|polic(?:y|ies))|system\s+(?:prompt|instructions?))\b/,
+  },
+  {
+    id: 'jailbreak',
+    pattern:
+      /\bjailbr(?:ea|o)k(?:ing|en)?\s+(?:the\s+|this\s+|your\s+|an?\s+)?(?:model|ai|assistant|llm|chatbot|gpt|claude|system|prompt|you)\b|\bjailbreak\s+(?:mode|prompt)\b|\byou\s+are\s+jailbroken\b/,
+  },
+  {
+    id: 'prompt-exfiltration',
+    pattern:
+      /\b(?:reveal|show|print|repeat|output|leak|display|tell\s+me)\s+(?:me\s+)?(?:your|the)\s+(?:system\s+prompt|hidden\s+(?:prompt|instructions)|initial\s+(?:prompt|instructions)|original\s+(?:prompt|instructions)|instructions\s+above)\b/,
+  },
+];
+
+/**
+ * Prepare a user-supplied pattern for repeated .test() calls: a global or
+ * sticky flag would keep lastIndex state between calls.
+ * @param {RegExp|string} pattern
+ * @returns {RegExp}
+ */
+function toStatelessRegExp(pattern) {
+  if (pattern instanceof RegExp) {
+    if (!pattern.global && !pattern.sticky) return pattern;
+    return new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''));
+  }
+  return new RegExp(String(pattern), 'i');
+}
+
+/**
+ * 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 }}
+ */
+function detectInjection(text, opts = {}) {
+  const normalized = normalizeText(text == null ? '' : text);
+  const lower = normalized.toLowerCase();
+  const folded = foldText(normalized);
+  const matches = [];
+
+  if (opts.useDefaults !== false) {
+    for (const rule of DEFAULT_RULES) {
+      const m = rule.pattern.exec(lower) || rule.pattern.exec(folded);
+      if (m) {
+        matches.push({
+          id: rule.id,
+          pattern: String(rule.pattern),
+          match: m[0].trim(),
+        });
+      }
+    }
+  }
+
+  for (const raw of opts.patterns || []) {
+    const re = toStatelessRegExp(raw);
+    const m = re.exec(normalized) || re.exec(folded);
+    if (m) {
+      matches.push({ id: 'custom', pattern: String(raw), match: m[0].trim() });
+    }
+  }
+
+  return { detected: matches.length > 0, matches, normalized };
+}
+
+module.exports = {
+  detectInjection,
+  normalizeText,
+  foldText,
+  DEFAULT_RULES,
+};

package/src/guardrails/post-generation-guard.js

@@ -165,6 +165,25 @@ class PostGenerationGuard extends EventEmitter {
     this.emit('checked', result);
     return result;
   }
+
+  /**
+   * 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) {
+    if (typeof text !== 'string' || !this.config.enablePIIDetection) {
+      return text;
+    }
+    let redacted = text;
+    for (const pattern of Object.values(this.config.piiPatterns)) {
+      redacted = redacted.replace(pattern, '[REDACTED]');
+    }
+    return redacted;
+  }
 }
 
 module.exports = { PostGenerationGuard, DEFAULT_CONFIG };

package/src/guardrails/pre-retrieval-guard.js

@@ -3,6 +3,7 @@
 const { EventEmitter } = require('events');
 const { validateInput } = require('../security/validator');
 const { tokenize } = require('../evaluate/scoring');
+const { detectInjection, DEFAULT_RULES } = require('./injection-detector');
 
 /**
  * Default configuration for the PreRetrievalGuard.
@@ -14,18 +15,10 @@ const DEFAULT_CONFIG = {
   enableTopicFiltering: false,
   blockedTopics: [],
   allowedTopics: [],
-  injectionPatterns: [
-    /ignore\s+(all\s+)?previous\s+instructions/i,
-    /you\s+are\s+now/i,
-    /forget\s+everything/i,
-    /act\s+as\s+(a|an)?\s*/i,
-    /pretend\s+(you\s+are|to\s+be)/i,
-    /system\s*:/i,
-    /\bDAN\b/,
-    /bypass\s+(all\s+)?restrictions/i,
-    /override\s+(safety|content|system)/i,
-    /jailbreak/i,
-  ],
+  // Built-in rules (see ./injection-detector). They match against normalised
+  // text (NFKC, zero-width/control characters removed, homoglyph and
+  // leetspeak folding). options.injectionPatterns adds extra patterns.
+  injectionPatterns: DEFAULT_RULES.map((rule) => rule.pattern),
 };
 
 /**
@@ -48,6 +41,10 @@ class PreRetrievalGuard extends EventEmitter {
   constructor(options = {}) {
     super();
     this.config = { ...DEFAULT_CONFIG, ...options };
+    /** @private Extra patterns supplied by the caller */
+    this._customPatterns = options.injectionPatterns
+      ? [...options.injectionPatterns]
+      : [];
     if (options.injectionPatterns) {
       this.config.injectionPatterns = [
         ...DEFAULT_CONFIG.injectionPatterns,
@@ -63,8 +60,13 @@ class PreRetrievalGuard extends EventEmitter {
    * @returns {{
    *   safe: boolean,
    *   issues: string[],
-   *   sanitizedQuery: string
+   *   sanitizedQuery: string,
+   *   injection: { detected: boolean, matches: Array<{id: string, pattern: string, match: string}> }
    * }}
+   * `sanitizedQuery` is the query truncated to maxQueryLength; it is never
+   * rewritten. Injection findings are reported in `issues` and `injection`
+   * and make `safe` false; blocking is up to the caller (GuardrailsPipeline
+   * blocks in strict mode).
    * @fires PreRetrievalGuard#checked
    */
   check(query) {
@@ -77,7 +79,12 @@ class PreRetrievalGuard extends EventEmitter {
       query.trim().length === 0
     ) {
       issues.push('Query must be a non-empty string');
-      const result = { safe: false, issues, sanitizedQuery: '' };
+      const result = {
+        safe: false,
+        issues,
+        sanitizedQuery: '',
+        injection: { detected: false, matches: [] },
+      };
       this.emit('checked', result);
       return result;
     }
@@ -92,16 +99,22 @@ class PreRetrievalGuard extends EventEmitter {
       }
     }
 
-    let sanitizedQuery = validation.sanitized;
+    // The query is passed on unchanged (apart from length truncation).
+    // Deleting only the matched phrase used to leave the rest of an attack
+    // payload in place, so detections are reported instead.
+    const sanitizedQuery = validation.sanitized;
 
-    // 3. Injection detection
-    const matchedPatterns = [];
+    // 3. Injection detection on a normalised copy of the query
+    let injection = { detected: false, matches: [] };
     if (this.config.enableInjectionDetection) {
-      for (const pattern of this.config.injectionPatterns) {
-        if (pattern.test(sanitizedQuery)) {
-          matchedPatterns.push(pattern);
-          issues.push(`Potential prompt injection detected: ${pattern}`);
-        }
+      const found = detectInjection(sanitizedQuery, {
+        patterns: this._customPatterns,
+      });
+      injection = { detected: found.detected, matches: found.matches };
+      for (const m of found.matches) {
+        issues.push(
+          `Potential prompt injection detected: ${m.id} (${JSON.stringify(m.match)})`,
+        );
       }
     }
 
@@ -133,24 +146,11 @@ class PreRetrievalGuard extends EventEmitter {
       }
     }
 
-    // 5. Sanitize: strip matched injection patterns from query
-    if (matchedPatterns.length > 0) {
-      for (const pattern of matchedPatterns) {
-        // Create a global version of the pattern for replacement
-        const flags = pattern.flags.includes('g')
-          ? pattern.flags
-          : pattern.flags + 'g';
-        const globalPattern = new RegExp(pattern.source, flags);
-        sanitizedQuery = sanitizedQuery.replace(globalPattern, '').trim();
-      }
-      // Collapse multiple spaces left after stripping
-      sanitizedQuery = sanitizedQuery.replace(/\s{2,}/g, ' ').trim();
-    }
-
     const result = {
       safe: issues.length === 0,
       issues,
       sanitizedQuery,
+      injection,
     };
 
     this.emit('checked', result);

package/src/guardrails/retrieval-guard.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { EventEmitter } = require('events');
+const { detectInjection } = require('./injection-detector');
 
 /**
  * Default configuration for the RetrievalGuard.
@@ -10,6 +11,12 @@ const DEFAULT_CONFIG = {
   minRelevanceScore: 0,
   maxAgeDays: 0, // 0 = disabled
   enforceACL: false,
+  // Opt-in scan of retrieved document text for prompt injection (indirect
+  // injection). 'remove' drops flagged documents, 'flag' keeps them and
+  // marks them with `injection` details.
+  detectInjection: false,
+  injectionAction: 'remove',
+  injectionPatterns: [],
 };
 
 /**
@@ -25,6 +32,9 @@ class RetrievalGuard extends EventEmitter {
    * @param {number} [options.minRelevanceScore=0] - Minimum relevance score threshold
    * @param {number} [options.maxAgeDays=0] - Maximum document age in days (0 = disabled)
    * @param {boolean} [options.enforceACL=false] - Whether to enforce access control
+   * @param {boolean} [options.detectInjection=false] - Scan document text for prompt injection
+   * @param {'remove'|'flag'} [options.injectionAction='remove'] - Remove flagged documents or keep and mark them
+   * @param {RegExp[]} [options.injectionPatterns=[]] - Extra injection patterns for the scan
    */
   constructor(options = {}) {
     super();
@@ -86,17 +96,19 @@ class RetrievalGuard extends EventEmitter {
         }
       }
 
-      // 3. ACL filter
-      if (!dominated && this.config.enforceACL && context.userPermissions) {
-        const requiredRoles = doc.requiredRole
-          ? [].concat(doc.requiredRole)
-          : doc.acl
-            ? [].concat(doc.acl)
-            : null;
+      // 3. ACL filter. Missing userPermissions fails closed: the user is
+      // treated as having no roles, so restricted documents are removed.
+      if (!dominated && this.config.enforceACL) {
+        const userPermissions = context.userPermissions || [];
+        // Read the restriction from the result itself or its metadata, so a
+        // top-level `acl` is not ignored when the result also has metadata.
+        const restriction =
+          result.requiredRole ?? result.acl ?? doc.requiredRole ?? doc.acl;
+        const requiredRoles = restriction ? [].concat(restriction) : null;
 
         if (requiredRoles && requiredRoles.length > 0) {
           const hasAccess = requiredRoles.some((role) =>
-            context.userPermissions.includes(role),
+            userPermissions.includes(role),
           );
           if (!hasAccess) {
             dominated = true;
@@ -105,6 +117,25 @@ class RetrievalGuard extends EventEmitter {
         }
       }
 
+      // 4. Indirect prompt injection in document text (opt-in)
+      if (!dominated && this.config.detectInjection) {
+        const text = documentText(result);
+        const found = detectInjection(text, {
+          patterns: this.config.injectionPatterns,
+        });
+        if (found.detected) {
+          reasons.injection = (reasons.injection || 0) + 1;
+          if (this.config.injectionAction === 'flag') {
+            kept.push({
+              ...result,
+              injection: { detected: true, matches: found.matches },
+            });
+            continue;
+          }
+          dominated = true;
+        }
+      }
+
       if (dominated) {
         removed.push(result);
       } else {
@@ -123,4 +154,23 @@ class RetrievalGuard extends EventEmitter {
   }
 }
 
+/**
+ * Text of a retrieval result for injection scanning.
+ * @param {object|string} result
+ * @returns {string}
+ */
+function documentText(result) {
+  if (typeof result === 'string') return result;
+  if (!result || typeof result !== 'object') return '';
+  const doc = result.doc && typeof result.doc === 'object' ? result.doc : {};
+  return String(
+    result.content ||
+      result.text ||
+      result.pageContent ||
+      doc.content ||
+      doc.text ||
+      '',
+  );
+}
+
 module.exports = { RetrievalGuard, DEFAULT_CONFIG };

package/src/index.js

@@ -13,6 +13,7 @@ const { normalizeConfig } = require('./config/normalize-config');
 
 // Plugin system
 const pluginRegistry = require('./core/plugin-registry');
+const { validatePlugin } = require('./core/validate-plugin');
 
 // Utilities
 const logger = require('./utils/logger');
@@ -49,6 +50,8 @@ const {
   scoreAnswer,
   computeBLEU,
   computeROUGE,
+  checkNumericConsistency,
+  extractNumbers,
 } = require('./evaluate/scoring');
 const { computeFaithfulness } = require('./evaluate/faithfulness');
 const { computeAnswerRelevance } = require('./evaluate/relevance');
@@ -57,6 +60,7 @@ const {
   computeContextRecall,
 } = require('./evaluate/context-metrics');
 const { computeGroundedness } = require('./evaluate/groundedness');
+const { computeSemanticSimilarity } = require('./evaluate/semantic-similarity');
 const { PipelineEvaluator } = require('./evaluate/pipeline-evaluator');
 
 // Chunking
@@ -64,6 +68,10 @@ const { ChunkingEngine } = require('./chunking/chunking-engine');
 
 // Citation & Grounding
 const { CitationTracker } = require('./citation/citation-tracker');
+const { checkAnswer, normalizeSources } = require('./grounding/check-answer');
+const { createAiSdkAdapter } = require('./adapters/ai-sdk');
+const { MemoryCache } = require('./cache/memory-cache');
+const { RedisCache } = require('./cache/redis-cache');
 const {
   mapSentenceToSources,
   buildIDFWeights,
@@ -74,9 +82,11 @@ const { detectHallucinations } = require('./citation/hallucination-detector');
 const { BM25Search } = require('./retrieval/bm25-search');
 const { reciprocalRankFusion } = require('./retrieval/rank-fusion');
 const { HybridRetriever } = require('./retrieval/hybrid-retriever');
+const { FileVectorStore } = require('./retrieval/file-vector-store');
 
 // Guardrails
 const { PreRetrievalGuard } = require('./guardrails/pre-retrieval-guard');
+const { detectInjection } = require('./guardrails/injection-detector');
 const { RetrievalGuard } = require('./guardrails/retrieval-guard');
 const { PostGenerationGuard } = require('./guardrails/post-generation-guard');
 const { GuardrailsPipeline } = require('./guardrails/guardrails-pipeline');
@@ -88,7 +98,7 @@ const { SelfCritiqueChecker } = require('./agentic/self-critique');
 const { AgenticPipeline } = require('./agentic/agentic-pipeline');
 
 // Cost Management
-const { CostCalculator } = require('./cost/cost-calculator');
+const { CostCalculator, PRICING_METADATA } = require('./cost/cost-calculator');
 const { CostTracker } = require('./cost/cost-tracker');
 const { TokenBudget } = require('./cost/token-budget');
 
@@ -184,6 +194,7 @@ module.exports = {
 
   // Plugin system
   pluginRegistry,
+  validatePlugin,
 
   // Utilities
   logger,
@@ -218,7 +229,10 @@ module.exports = {
   scoreAnswer,
   computeBLEU,
   computeROUGE,
+  checkNumericConsistency,
+  extractNumbers,
   computeFaithfulness,
+  computeSemanticSimilarity,
   computeAnswerRelevance,
   computeContextPrecision,
   computeContextRecall,
@@ -230,6 +244,11 @@ module.exports = {
 
   // Citation & Grounding
   CitationTracker,
+  checkAnswer,
+  normalizeSources,
+  createAiSdkAdapter,
+  MemoryCache,
+  RedisCache,
   mapSentenceToSources,
   buildIDFWeights,
   detectHallucinations,
@@ -238,9 +257,11 @@ module.exports = {
   BM25Search,
   reciprocalRankFusion,
   HybridRetriever,
+  FileVectorStore,
 
   // Guardrails
   PreRetrievalGuard,
+  detectInjection,
   RetrievalGuard,
   PostGenerationGuard,
   GuardrailsPipeline,
@@ -253,6 +274,7 @@ module.exports = {
 
   // Cost Management
   CostCalculator,
+  PRICING_METADATA,
   CostTracker,
   TokenBudget,
 
@@ -330,3 +352,38 @@ module.exports = {
   DevServer,
   createDevServer,
 };
+
+// Simulated or incomplete modules now live in the ./experimental entry
+// (src/experimental.js). Their main-entry exports keep working but emit a
+// one-time DeprecationWarning when used, and will be removed from the main
+// entry in the next major release (SEMVER.md, "Deprecation process").
+const experimental = require('./experimental');
+const { deprecateClass } = require('./utils/deprecate');
+
+for (const name of Object.keys(experimental)) {
+  if (!(name in module.exports)) continue;
+  module.exports[name] = deprecateClass(experimental[name], {
+    name,
+    message:
+      `${name} is experimental (simulated or incomplete) and is deprecated in ` +
+      `the main entry. Import it from "@devilsdev/rag-pipeline-utils/experimental"; ` +
+      'it will be removed from the main entry in the next major release.',
+  });
+}
+
+// The ./testing build entry reads its module from here, so it shares the
+// main bundle's classes (MemoryRetriever, createRagPipeline). A getter, so
+// importing the package does not load the testing helpers.
+Object.defineProperty(
+  module.exports,
+  Symbol.for('@devilsdev/rag-pipeline-utils/testing'),
+  { get: () => require('./testing'), enumerable: false }, // eslint-disable-line global-require
+);
+
+// The ./experimental build entry reads the unwrapped classes from here, so
+// both entries share one copy of each class (non-enumerable: not a named export).
+Object.defineProperty(
+  module.exports,
+  Symbol.for('@devilsdev/rag-pipeline-utils/experimental'),
+  { value: experimental, enumerable: false },
+);