@devilsdev/rag-pipeline-utils 2.5.0 → 2.6.0

package/dist/index.d.ts

@@ -14,9 +14,39 @@ export interface RagPipelineConfig {
   llm?: string | LLMPlugin;
   reranker?: string | RerankerPlugin;
   registry?: PluginRegistry;
+  /**
+   * Cache query embeddings, retrieval results and answers. `true` caches
+   * all three in memory; a CacheBackend (MemoryCache, RedisCache, your own)
+   * caches all three in it; or configure each layer.
+   */
+  cache?: boolean | CacheBackend | CacheOptions;
   [key: string]: any;
 }
 
+/** A cache store: get / set / delete, optionally stats. */
+export interface CacheBackend {
+  get(key: string): Promise<unknown | undefined>;
+  set(key: string, value: unknown, options?: { ttlSeconds?: number }): Promise<void>;
+  delete?(key: string): Promise<void>;
+  stats?(): Promise<Record<string, number>>;
+}
+
+export interface CacheOptions {
+  embeddings?: boolean | CacheBackend;
+  retrieval?: boolean | CacheBackend;
+  generation?: boolean | CacheBackend;
+  /** Defaults: embeddings 30 days, retrieval 1 hour, generation 24 hours. */
+  ttlSeconds?: { embeddings?: number; retrieval?: number; generation?: number };
+}
+
+export type CacheOutcome = "hit" | "miss" | "skip";
+
+export interface CacheLayerStats {
+  hits: number;
+  misses: number;
+  skipped: number;
+}
+
 export interface PipelineRunOptions {
   query?: string;
   queryVector?: number[];
@@ -33,11 +63,23 @@ export interface PipelineRunResult {
   query?: string;
   results?: any;
   error?: string;
+  /** Per-layer cache outcome; present when the pipeline has a cache. */
+  cache?: {
+    embeddings?: CacheOutcome;
+    retrieval?: CacheOutcome;
+    generation?: CacheOutcome;
+  };
 }
 
 export interface Pipeline {
   run(options: PipelineRunOptions): Promise<PipelineRunResult>;
   cleanup(): void;
+  /** Hits, misses and skips per cache layer; null without a cache. */
+  cacheStats(): {
+    embeddings?: CacheLayerStats;
+    retrieval?: CacheLayerStats;
+    generation?: CacheLayerStats;
+  } | null;
 }
 
 export interface LoadConfigOptions {
@@ -486,9 +528,11 @@ export function createDevServer(options?: any): DevServer;
 // =============================================================================
 // Declarations generated from JSDoc (scripts/generate-types.js)
 // =============================================================================
+export { validatePlugin } from "./types/core/validate-plugin";
 export { checkNumericConsistency } from "./types/evaluate/scoring";
 export { extractNumbers } from "./types/evaluate/scoring";
 export { computeFaithfulness } from "./types/evaluate/faithfulness";
+export { computeSemanticSimilarity } from "./types/evaluate/semantic-similarity";
 export { computeAnswerRelevance } from "./types/evaluate/relevance";
 export { computeContextPrecision } from "./types/evaluate/context-metrics";
 export { computeContextRecall } from "./types/evaluate/context-metrics";
@@ -496,6 +540,11 @@ export { computeGroundedness } from "./types/evaluate/groundedness";
 export { PipelineEvaluator } from "./types/evaluate/pipeline-evaluator";
 export { ChunkingEngine } from "./types/chunking/chunking-engine";
 export { CitationTracker } from "./types/citation/citation-tracker";
+export { checkAnswer } from "./types/grounding/check-answer";
+export { normalizeSources } from "./types/grounding/check-answer";
+export { createAiSdkAdapter } from "./types/adapters/ai-sdk";
+export { MemoryCache } from "./types/cache/memory-cache";
+export { RedisCache } from "./types/cache/redis-cache";
 export { mapSentenceToSources } from "./types/citation/source-mapper";
 export { buildIDFWeights } from "./types/citation/source-mapper";
 export { detectHallucinations } from "./types/citation/hallucination-detector";

package/dist/index.mjs

@@ -8,6 +8,6 @@ const require = createRequire(import.meta.url);
 
 const mod = require('./index.cjs');
 
-export const { createRagPipeline, createPipeline, loadConfig, loadRagConfig, validateRagrc, normalizeConfig, pluginRegistry, logger, errorFormatter, createError, wrapError, ERROR_CODES, BatchProcessor, RateLimiter, retry, withRetry, ConnectionPoolManager, JWTValidator, PluginSandbox, PluginSignatureVerifier, validateInput, MultiModalProcessor, AdaptiveRetrievalEngine, FederatedLearningCoordinator, ModelTrainingOrchestrator, DAGEngine, DAG, evaluateRagDataset, scoreAnswer, computeBLEU, computeROUGE, checkNumericConsistency, extractNumbers, computeFaithfulness, computeAnswerRelevance, computeContextPrecision, computeContextRecall, computeGroundedness, PipelineEvaluator, ChunkingEngine, CitationTracker, mapSentenceToSources, buildIDFWeights, detectHallucinations, BM25Search, reciprocalRankFusion, HybridRetriever, FileVectorStore, PreRetrievalGuard, detectInjection, RetrievalGuard, PostGenerationGuard, GuardrailsPipeline, QueryPlanner, IterativeRetriever, SelfCritiqueChecker, AgenticPipeline, CostCalculator, PRICING_METADATA, CostTracker, TokenBudget, ExecutionTracer, TraceInspector, MCPServer, MCPToolBuilder, ProjectScaffolder, TemplateRegistry, SSEAdapter, WebSocketAdapter, StreamRouter, BaseConnector, OllamaConnector, LocalEmbedder, MemoryRetriever, OpenAIConnector, AnthropicConnector, CohereConnector, StreamingEmbedder, createEmbeddingStream, ScoringReranker, EmbeddingReranker, CascadeReranker, KnowledgeGraph, EntityExtractor, GraphRetriever, GraphIndex, DashboardGenerator, MetricsAggregator, ParallelProcessor, eventLogger, metrics, AuditLogger, DataGovernance, DataGovernanceManager, TenantManager, ResourceMonitor, SSOManager, SAMLProvider, OAuth2Provider, ActiveDirectoryProvider, OIDCProvider, PluginHub, PluginAnalytics, PluginCertification, PluginAnalyticsDashboard, HotReloadManager, createHotReloadManager, DevServer, createDevServer } = mod;
+export const { createRagPipeline, createPipeline, loadConfig, loadRagConfig, validateRagrc, normalizeConfig, pluginRegistry, validatePlugin, logger, errorFormatter, createError, wrapError, ERROR_CODES, BatchProcessor, RateLimiter, retry, withRetry, ConnectionPoolManager, JWTValidator, PluginSandbox, PluginSignatureVerifier, validateInput, MultiModalProcessor, AdaptiveRetrievalEngine, FederatedLearningCoordinator, ModelTrainingOrchestrator, DAGEngine, DAG, evaluateRagDataset, scoreAnswer, computeBLEU, computeROUGE, checkNumericConsistency, extractNumbers, computeFaithfulness, computeSemanticSimilarity, computeAnswerRelevance, computeContextPrecision, computeContextRecall, computeGroundedness, PipelineEvaluator, ChunkingEngine, CitationTracker, checkAnswer, normalizeSources, createAiSdkAdapter, MemoryCache, RedisCache, mapSentenceToSources, buildIDFWeights, detectHallucinations, BM25Search, reciprocalRankFusion, HybridRetriever, FileVectorStore, PreRetrievalGuard, detectInjection, RetrievalGuard, PostGenerationGuard, GuardrailsPipeline, QueryPlanner, IterativeRetriever, SelfCritiqueChecker, AgenticPipeline, CostCalculator, PRICING_METADATA, CostTracker, TokenBudget, ExecutionTracer, TraceInspector, MCPServer, MCPToolBuilder, ProjectScaffolder, TemplateRegistry, SSEAdapter, WebSocketAdapter, StreamRouter, BaseConnector, OllamaConnector, LocalEmbedder, MemoryRetriever, OpenAIConnector, AnthropicConnector, CohereConnector, StreamingEmbedder, createEmbeddingStream, ScoringReranker, EmbeddingReranker, CascadeReranker, KnowledgeGraph, EntityExtractor, GraphRetriever, GraphIndex, DashboardGenerator, MetricsAggregator, ParallelProcessor, eventLogger, metrics, AuditLogger, DataGovernance, DataGovernanceManager, TenantManager, ResourceMonitor, SSOManager, SAMLProvider, OAuth2Provider, ActiveDirectoryProvider, OIDCProvider, PluginHub, PluginAnalytics, PluginCertification, PluginAnalyticsDashboard, HotReloadManager, createHotReloadManager, DevServer, createDevServer } = mod;
 
 export default mod;

package/dist/testing.cjs

@@ -0,0 +1,2 @@
+'use strict';
+module.exports = require('./index.cjs')[Symbol.for('@devilsdev/rag-pipeline-utils/testing')];

package/dist/testing.d.ts

@@ -0,0 +1 @@
+export * from "./types/testing";

package/dist/testing.mjs

@@ -0,0 +1,5 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const mod = require('./testing.cjs');
+export const { HashEmbedder, EchoLLM, fixtures, createTestPipeline } = mod;
+export default mod;

package/dist/types/adapters/ai-sdk.d.ts

@@ -0,0 +1,53 @@
+export type AiSdkFunctions = {
+    /**
+     * - `embed` from 'ai' (needed for an embedder)
+     */
+    embed?: Function;
+    /**
+     * - `embedMany` from 'ai' (batch embedding)
+     */
+    embedMany?: Function;
+    /**
+     * - `generateText` from 'ai' (needed for an llm)
+     */
+    generateText?: Function;
+    /**
+     * - `streamText` from 'ai' (streaming)
+     */
+    streamText?: Function;
+};
+/**
+ * Wrap AI SDK models as an embedder and an llm for createRagPipeline().
+ *
+ * @example
+ * import { embed, embedMany, generateText, streamText } from "ai";
+ * import { openai } from "@ai-sdk/openai";
+ * import { createAiSdkAdapter, createRagPipeline } from "@devilsdev/rag-pipeline-utils";
+ *
+ * const { embedder, llm } = createAiSdkAdapter({
+ *   ai: { embed, embedMany, generateText, streamText },
+ *   embeddingModel: openai.embedding("text-embedding-3-small"),
+ *   languageModel: openai("gpt-4o-mini"),
+ * });
+ * const pipeline = createRagPipeline({ embedder, retriever, llm });
+ *
+ * @param {Object} options
+ * @param {AiSdkFunctions} options.ai - Functions imported from 'ai'
+ * @param {Object} [options.embeddingModel] - AI SDK embedding model
+ * @param {Object} [options.languageModel] - AI SDK language model
+ * @param {Object} [options.settings] - Defaults for every text call, e.g.
+ *   `{ temperature: 0, maxOutputTokens: 512 }`
+ * @param {string} [options.systemPrompt] - Replaces the built-in RAG system
+ *   prompt
+ * @returns {{ embedder: Object|null, llm: Object|null }}
+ */
+export function createAiSdkAdapter(options?: {
+    ai: AiSdkFunctions;
+    embeddingModel?: any;
+    languageModel?: any;
+    settings?: any;
+    systemPrompt?: string;
+}): {
+    embedder: any | null;
+    llm: any | null;
+};

package/dist/types/cache/component-keys.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {string} kind - e.g. 'openai'
+ * @param {Object} fields - Settings that change the output
+ * @returns {string}
+ */
+export function componentCacheKey(kind: string, fields: any): string;
+export function digest(value: any): string;

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

@@ -0,0 +1,54 @@
+/**
+ * In-process cache with least-recently-used eviction and per-entry time to
+ * live. Implements the CacheBackend contract:
+ *
+ *   get(key) -> Promise<value | undefined>
+ *   set(key, value, { ttlSeconds }) -> Promise<void>
+ *   delete(key) -> Promise<void>
+ *   stats() -> Promise<{ hits, misses, size }>
+ *
+ * Values are stored as JSON copies, so later changes to a returned value do
+ * not change the cache (the same behaviour as RedisCache).
+ */
+export class MemoryCache {
+    /**
+     * @param {Object} [options]
+     * @param {number} [options.maxEntries=1000] - Entries kept before the least
+     *   recently used is evicted
+     * @param {number} [options.ttlSeconds] - Default time to live; none means
+     *   entries never expire on their own
+     */
+    constructor({ maxEntries, ttlSeconds }?: {
+        maxEntries?: number;
+        ttlSeconds?: number;
+    });
+    maxEntries: number;
+    ttlSeconds: number;
+    _entries: Map<any, any>;
+    _hits: number;
+    _misses: number;
+    /**
+     * @param {string} key
+     * @returns {Promise<unknown|undefined>}
+     */
+    get(key: string): Promise<unknown | undefined>;
+    /**
+     * @param {string} key
+     * @param {unknown} value - JSON-serialisable value
+     * @param {{ ttlSeconds?: number }} [options]
+     * @returns {Promise<void>}
+     */
+    set(key: string, value: unknown, { ttlSeconds }?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    /** @param {string} key */
+    delete(key: string): Promise<void>;
+    /** Remove every entry. */
+    clear(): Promise<void>;
+    /** @returns {Promise<{ hits: number, misses: number, size: number }>} */
+    stats(): Promise<{
+        hits: number;
+        misses: number;
+        size: number;
+    }>;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Normalise the `cache` option of createRagPipeline.
+ *
+ * - `true`: all three layers in one in-memory cache
+ * - a CacheBackend: all three layers in it
+ * - `{ embeddings, retrieval, generation, ttlSeconds }`: per layer, each
+ *   `true` (in-memory), `false`/absent (off) or a CacheBackend;
+ *   `ttlSeconds: { embeddings, retrieval, generation }` overrides the
+ *   defaults (30 days, 1 hour, 24 hours)
+ *
+ * @returns {Object|null} Layer config, or null when caching is off
+ */
+export function normalizeCacheOption(option: any): any | null;
+/**
+ * Per-pipeline cache. Every method returns undefined and does nothing for a
+ * layer that is off or whose component has no cache key.
+ */
+export class PipelineCache {
+    /**
+     * @param {Object} layers - normalizeCacheOption() output
+     * @param {{ embedder?: Object, retriever?: Object, llm?: Object }} components
+     */
+    constructor(layers: any, components: {
+        embedder?: any;
+        retriever?: any;
+        llm?: any;
+    });
+    layers: any;
+    components: {
+        embedder?: any;
+        retriever?: any;
+        llm?: any;
+    };
+    /** @private */
+    private _key;
+    /** @private */
+    private _get;
+    /** @private */
+    private _set;
+    embeddingKey(query: any): string;
+    retrievalKey({ query, queryVector, topK }: {
+        query: any;
+        queryVector: any;
+        topK: any;
+    }): string;
+    /**
+     * @returns {string|null} The key, or null to skip (temperature above 0,
+     *   or no llm cache key)
+     */
+    generationKey({ query, docs, options }: {
+        query: any;
+        docs: any;
+        options: any;
+    }): string | null;
+    get(layer: any, key: any, status: any): Promise<any>;
+    set(layer: any, key: any, value: any): Promise<void>;
+    /** Hits, misses and skips per layer since the pipeline was created. */
+    stats(): {};
+}
+/** A component's identity for a role, or null when it has none. */
+export function componentKey(component: any, role: any): any;
+export namespace DEFAULT_TTL_SECONDS {
+    let embeddings: number;
+    let retrieval: number;
+    let generation: number;
+}

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

@@ -0,0 +1,46 @@
+/**
+ * CacheBackend on Redis. Pass a connected client from `redis` (node-redis 4
+ * and later) or `ioredis`; neither is a dependency of this package.
+ *
+ * Values are stored as JSON under `prefix + key`, with a millisecond expiry
+ * when a time to live applies.
+ */
+export class RedisCache {
+    /**
+     * @param {Object} options
+     * @param {Object} options.client - Connected node-redis or ioredis client
+     * @param {string} [options.prefix='rag:'] - Key prefix
+     * @param {number} [options.ttlSeconds] - Default time to live
+     */
+    constructor({ client, prefix, ttlSeconds }?: {
+        client: any;
+        prefix?: string;
+        ttlSeconds?: number;
+    });
+    client: any;
+    prefix: string;
+    ttlSeconds: number;
+    _nodeRedis: boolean;
+    _hits: number;
+    _misses: number;
+    /**
+     * @param {string} key
+     * @returns {Promise<unknown|undefined>}
+     */
+    get(key: string): Promise<unknown | undefined>;
+    /**
+     * @param {string} key
+     * @param {unknown} value - JSON-serialisable value
+     * @param {{ ttlSeconds?: number }} [options]
+     */
+    set(key: string, value: unknown, { ttlSeconds }?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    /** @param {string} key */
+    delete(key: string): Promise<void>;
+    /** Hits and misses seen by this instance (size is not tracked). */
+    stats(): Promise<{
+        hits: number;
+        misses: number;
+    }>;
+}

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

@@ -28,8 +28,14 @@ export class AnthropicConnector extends BaseConnector {
         retryDelay?: number;
         systemPrompt?: string;
     });
+    /**
+     * Cache identity for createRagPipeline({ cache }).
+     * @param {'llm'} role
+     * @returns {string|null}
+     */
+    getCacheKey(role: "llm"): string | null;
     config: any;
-    client: axios.AxiosInstance;
+    client: import("axios").AxiosInstance;
     /**
      * @throws {Error} code MISSING_API_KEY when no key is configured
      * @private
@@ -89,4 +95,3 @@ export class AnthropicConnector extends BaseConnector {
  */
 export const DEFAULT_CONFIG: any;
 import { BaseConnector } from "./base-connector";
-import axios = require("axios");

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

@@ -23,8 +23,14 @@ export class CohereConnector extends BaseConnector {
         inputType?: string;
         queryInputType?: string;
     });
+    /**
+     * Cache identity for createRagPipeline({ cache }).
+     * @param {'embedder'} role
+     * @returns {string|null}
+     */
+    getCacheKey(role: "embedder"): string | null;
     config: any;
-    client: axios.AxiosInstance;
+    client: import("axios").AxiosInstance;
     /**
      * @throws {Error} code MISSING_API_KEY when no key is configured
      * @private
@@ -86,4 +92,3 @@ export class CohereConnector extends BaseConnector {
  */
 export const DEFAULT_CONFIG: any;
 import { BaseConnector } from "./base-connector";
-import axios = require("axios");

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

@@ -29,6 +29,7 @@ export class LocalEmbedder extends BaseConnector {
         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
@@ -70,6 +71,14 @@ export class LocalEmbedder extends BaseConnector {
         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;
     /**

package/dist/types/connectors/memory-retriever.d.ts

@@ -24,6 +24,14 @@ export class MemoryRetriever extends BaseConnector {
     }>;
     /** @type {number|null} Vector dimension, fixed by the first stored vector */
     dimensions: number | null;
+    _cacheId: string;
+    _revision: number;
+    /**
+     * Cache identity for createRagPipeline({ cache }).
+     * @param {'retriever'} role
+     * @returns {string|null}
+     */
+    getCacheKey(role: "retriever"): string | null;
     /**
      * Store one or more vector documents. The batch is validated before
      * anything is inserted, so a rejected call leaves the store unchanged.

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

@@ -26,8 +26,14 @@ export class OllamaConnector extends BaseConnector {
         retryDelay?: number;
         systemPrompt?: string;
     });
+    /**
+     * Cache identity for createRagPipeline({ cache }).
+     * @param {'embedder'|'llm'} role
+     * @returns {string|null}
+     */
+    getCacheKey(role: "embedder" | "llm"): string | null;
     config: any;
-    client: axios.AxiosInstance;
+    client: import("axios").AxiosInstance;
     /**
      * POST with the connector's retry policy and cancellation.
      * @private
@@ -107,4 +113,3 @@ export class OllamaConnector extends BaseConnector {
  */
 export const DEFAULT_CONFIG: any;
 import { BaseConnector } from "./base-connector";
-import axios = require("axios");

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

@@ -11,7 +11,14 @@ export class OpenAIConnector extends BaseConnector {
      * @param {string} [options.embeddingModel='text-embedding-3-small'] - Embedding model
      * @param {number} [options.temperature=0.7] - Sampling temperature
      * @param {number} [options.maxTokens=4096] - Max tokens in completion
-     * @param {string} [options.apiKey] - OpenAI API key (defaults to OPENAI_API_KEY at construction)
+     * @param {string} [options.apiKey] - API key. Defaults to OPENAI_API_KEY at
+     *   construction, except when `baseURL` is set (see below)
+     * @param {string} [options.baseURL] - Base URL of an OpenAI-compatible API,
+     *   e.g. Groq, Together, the Hugging Face router, vLLM, LM Studio or
+     *   Ollama's `/v1` endpoint. With a custom base URL the key is never read
+     *   from OPENAI_API_KEY (that would send your OpenAI key to another
+     *   provider): pass `apiKey` explicitly, or omit it for servers that need
+     *   none
      * @param {number} [options.maxRetries=3] - Retries for transient failures (the SDK's own retries are disabled)
      * @param {number} [options.retryDelay=1000] - Base backoff delay in ms
      * @param {string} [options.systemPrompt] - System prompt used when RAG context is supplied
@@ -22,10 +29,18 @@ export class OpenAIConnector extends BaseConnector {
         temperature?: number;
         maxTokens?: number;
         apiKey?: string;
+        baseURL?: string;
         maxRetries?: number;
         retryDelay?: number;
         systemPrompt?: string;
     });
+    /**
+     * Cache identity for createRagPipeline({ cache }): the settings that
+     * change this connector's output in the given role.
+     * @param {'embedder'|'llm'} role
+     * @returns {string|null}
+     */
+    getCacheKey(role: "embedder" | "llm"): string | null;
     config: any;
     _client: any;
     /**

package/dist/types/core/create-pipeline.d.ts

@@ -0,0 +1,8 @@
+export function createRagPipeline({ registry, loader, embedder, retriever, llm, reranker, cache, }?: {}): {
+    run: ({ query, queryVector, options }?: {
+        options?: {};
+    }) => Promise<any>;
+    cleanup(): void;
+    /** Cache hits, misses and skips per layer; null when caching is off. */
+    cacheStats(): {};
+};

package/dist/types/core/plugin-registry.d.ts

@@ -0,0 +1,136 @@
+export = registry;
+declare const registry: PluginRegistry;
+declare class PluginRegistry {
+    constructor(options?: {});
+    _plugins: Map<any, any>;
+    _validTypes: Set<string>;
+    _contracts: Map<any, any>;
+    _contractWarningsShown: Set<any>;
+    _disableContractWarnings: any;
+    _validateContractSchema: any;
+    _signatureVerifier: import("../security/plugin-signature-verifier.js").PluginSignatureVerifier;
+    _requireSignedPlugins: boolean;
+    _contractsLoaded: boolean;
+    /**
+     * Load the contract schema and the stage contracts once.
+     * @private
+     */
+    private _ensureContracts;
+    _ajv: any;
+    _contractSchema: any;
+    _contractSchemaValidator: any;
+    /**
+     * Load contract schema for validation
+     *
+     * @private
+     * @returns {Object|null} Contract schema or null if not found
+     *
+     * @since 2.2.4
+     */
+    private _loadContractSchema;
+    /**
+     * Validate contract against schema
+     *
+     * @private
+     * @param {Object} contract - Contract to validate
+     * @param {string} type - Contract type
+     * @returns {Object} Validation result { valid: boolean, errors: Array }
+     *
+     * @since 2.2.4
+     */
+    private _validateContractAgainstSchema;
+    /**
+     * Format schema validation errors for display
+     *
+     * @private
+     * @param {Array} errors - Ajv validation errors
+     * @returns {string} Formatted error message
+     *
+     * @since 2.2.4
+     */
+    private _formatSchemaErrors;
+    /**
+     * Check if a contract exists for the given plugin type
+     *
+     * @param {string} type - Plugin type (loader, embedder, etc.)
+     * @returns {boolean} True if contract exists, false otherwise
+     *
+     * @example
+     * const hasContract = registry.checkContractExists('loader');
+     * if (!hasContract) {
+     *   console.warn('No contract for loader plugins');
+     * }
+     *
+     * @since 2.2.4
+     */
+    checkContractExists(type: string): boolean;
+    /**
+     * Log one-time warning for missing contract
+     *
+     * Logs a helpful warning message about the benefits of contracts
+     * and how to add them. Only logs once per contract type and only
+     * in non-production environments.
+     *
+     * @private
+     * @param {string} type - Plugin type
+     * @param {string} context - Context where warning is generated (e.g., 'load', 'register')
+     *
+     * @since 2.2.4
+     */
+    private _warnMissingContract;
+    _loadContracts(): void;
+    _validatePluginContract(category: any, impl: any): void;
+    _getRequiredMethodsFromContract(contract: any): any[];
+    /**
+     * Register a plugin.
+     *
+     * @param {string} category - Plugin type
+     * @param {string} name - Plugin name
+     * @param {object} impl - Plugin implementation
+     * @param {object|null} [manifest] - Signed manifest; when given, its
+     *   signature is verified before registration
+     * @param {object} [options]
+     * @param {object} [options.content] - Plugin content checked against the
+     *   manifest's contentDigest: `{ files, baseDir, contents }`
+     * @returns {Promise<PluginRegistry>}
+     */
+    register(category: string, name: string, impl: object, manifest?: object | null, options?: {
+        content?: object;
+    }): Promise<PluginRegistry>;
+    /**
+     * Verify plugin signature
+     * @param {object} manifest - Plugin manifest
+     * @param {string} pluginName - Plugin name
+     */
+    _verifyPluginSignature(manifest: object, pluginName: string, content?: any): Promise<void>;
+    /**
+     * Whether plugin signature verification is enabled for this registry.
+     * @returns {boolean}
+     */
+    isSignatureVerificationEnabled(): boolean;
+    /**
+     * Whether plugins without a signed manifest are rejected.
+     * @returns {boolean}
+     */
+    requiresSignedPlugins(): boolean;
+    /**
+     * Verify a plugin's signed manifest and code before it is loaded (use this
+     * before importing plugin files, since importing executes them).
+     *
+     * @param {string} pluginName - Plugin name (for audit entries)
+     * @param {object} manifest - Signed manifest
+     * @param {object} content - `{ files, baseDir, contents }`
+     * @returns {Promise<void>} Rejects if verification fails
+     */
+    verifyPluginContent(pluginName: string, manifest: object, content: object): Promise<void>;
+    /**
+     * Emit audit entry
+     * @param {string} action - Audit action
+     * @param {object} details - Audit details
+     */
+    _emitAuditEntry(action: string, details: object): void;
+    get(category: any, name: any): any;
+    resolve(category: any, name: any): any;
+    list(category: any): any[];
+    clear(): void;
+}

package/dist/types/core/stage-contracts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What each pipeline stage must provide, as createRagPipeline and the CLI
+ * use it. A plugin needs at least one of `anyOf`; a missing `recommended`
+ * method only matters for the command named in its note.
+ *
+ * Shared by validatePlugin() and the `rag-pipeline init` wizard. The
+ * stricter rules pluginRegistry.register() applies (metadata, and the
+ * methods in contracts/*.json) are checked by validatePlugin(..., {
+ * registry: true }).
+ */
+export const STAGE_CONTRACTS: Readonly<{
+    loader: {
+        anyOf: string[];
+        recommended: {};
+    };
+    embedder: {
+        anyOf: string[];
+        recommended: {
+            embed: string;
+        };
+    };
+    retriever: {
+        anyOf: string[];
+        recommended: {
+            store: string;
+        };
+    };
+    reranker: {
+        anyOf: string[];
+        recommended: {};
+    };
+    llm: {
+        anyOf: string[];
+        recommended: {};
+    };
+}>;