@devilsdev/rag-core 3.4.0 → 3.5.0

package/dist/types/guardrails/detectors.d.ts

@@ -0,0 +1,88 @@
+export namespace DEFAULT_PII_PATTERNS {
+    let email: RegExp;
+    let phone: RegExp;
+    let ssn: RegExp;
+    let creditCard: RegExp;
+}
+/**
+ * The built-in prompt-injection check as a detector.
+ *
+ * @param {object} [options]
+ * @param {RegExp[]} [options.patterns] - Extra patterns, added to the built-in rules
+ * @returns {{name: string, kind: 'injection', detect: (text: string) => {flagged: boolean, labels: string[], matches: Array<{label: string, text: string}>}}}
+ */
+export function patternInjectionDetector({ patterns }?: {
+    patterns?: RegExp[];
+}): {
+    name: string;
+    kind: "injection";
+    detect: (text: string) => {
+        flagged: boolean;
+        labels: string[];
+        matches: Array<{
+            label: string;
+            text: string;
+        }>;
+    };
+};
+/**
+ * The built-in PII check as a detector: emails, phone numbers, US social
+ * security numbers and card numbers, by pattern.
+ *
+ * @param {object} [options]
+ * @param {Object<string, RegExp>} [options.patterns] - Extra patterns by label, merged with the defaults
+ * @returns {{name: string, kind: 'pii', detect: (text: string) => {flagged: boolean, labels: string[], matches: Array<{label: string, text: string, start: number, end: number}>}}}
+ */
+export function patternPIIDetector({ patterns }?: {
+    patterns?: {
+        [x: string]: RegExp;
+    };
+}): {
+    name: string;
+    kind: "pii";
+    detect: (text: string) => {
+        flagged: boolean;
+        labels: string[];
+        matches: Array<{
+            label: string;
+            text: string;
+            start: number;
+            end: number;
+        }>;
+    };
+};
+/**
+ * Check a guard's `detectors` and `builtIn` options.
+ *
+ * @param {string} guard - Guard name, for messages
+ * @param {'injection'|'pii'} kind - The kind of detector this guard runs
+ * @param {object} options - The guard's options
+ * @returns {object[]} The detectors
+ */
+export function resolveDetectors(guard: string, kind: "injection" | "pii", options?: object): object[];
+/**
+ * Run detectors synchronously. A detector that returns a promise throws a
+ * TypeError naming the async method to use, rather than being ignored (an
+ * ignored promise is a check that never fires).
+ *
+ * @returns {object[]} One detection per detector
+ */
+export function runDetectorsSync(detectors: any, text: any, context: any, { guard, asyncMethod }: {
+    guard: any;
+    asyncMethod: any;
+}): object[];
+/**
+ * Run detectors concurrently, sync or async.
+ *
+ * @returns {Promise<object[]>} One detection per detector
+ */
+export function runDetectorsAsync(detectors: any, text: any, context: any): Promise<object[]>;
+/**
+ * The strings PII detectors found in a PostGenerationGuard result, for
+ * `PostGenerationGuard.redact(text, matches)`. The result keeps them in a
+ * non-enumerable `matchedText`, so they don't appear in its JSON.
+ *
+ * @param {object} result - A PostGenerationGuard check() or checkAsync() result
+ * @returns {string[]}
+ */
+export function detectedText(result: object): string[];

package/dist/types/guardrails/evaluate-detectors.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Run detectors over labelled cases and score them.
+ *
+ * @param {Array<object>} cases - Labelled cases (see the module comment)
+ * @param {Array<{name: string, kind: 'injection'|'pii', detect: Function}>} detectors
+ * @param {object} [options]
+ * @param {number} [options.concurrency=4] - Cases in flight per detector
+ * @param {string[]|Object<string, string[]>} [options.coveredLabels] - Span labels each PII detector is meant to find, for the headline span recall; an array applies to every PII detector
+ * @param {AbortSignal} [options.signal] - Stops the run
+ * @returns {Promise<object>} The report: `{ createdAt, cases, detectors: { [name]: metrics } }`
+ */
+export function evaluateDetectors(cases: Array<object>, detectors: Array<{
+    name: string;
+    kind: "injection" | "pii";
+    detect: Function;
+}>, options?: {
+    concurrency?: number;
+    coveredLabels?: string[] | {
+        [x: string]: string[];
+    };
+    signal?: AbortSignal;
+}): Promise<object>;
+/**
+ * Check labelled cases and fill in their ids.
+ *
+ * @param {Array<object>} cases
+ * @returns {Array<object>} The cases, each with an `id`
+ */
+export function validateDetectorCases(cases: Array<object>): Array<object>;
+/**
+ * Check minimums such as `{ 'pattern-injection.recall': 0.5 }` against a
+ * report. A key is `<detector>.<metric>`, where metric is precision,
+ * recall, f1 or accuracy, or spans.precision / spans.recall.
+ *
+ * @param {object} report - An evaluateDetectors() report
+ * @param {Object<string, number>} [min]
+ * @returns {{passed: boolean, reasons: string[]}}
+ */
+export function detectorVerdict(report: object, min?: {
+    [x: string]: number;
+}): {
+    passed: boolean;
+    reasons: string[];
+};
+/**
+ * Render an evaluateDetectors() report as Markdown or a standalone HTML page.
+ *
+ * @param {object} report
+ * @param {object} [options]
+ * @param {'markdown'|'html'} [options.format='markdown']
+ * @param {string} [options.title='Guardrail detectors']
+ * @param {Object<string, number>} [options.min] - Minimums, as for detectorVerdict()
+ * @returns {string}
+ */
+export function renderDetectorReport(report: object, options?: {
+    format?: "markdown" | "html";
+    title?: string;
+    min?: {
+        [x: string]: number;
+    };
+}): string;

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

@@ -1,12 +1,4 @@
-/**
- * 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]> {
+export class GuardrailsPipeline extends EventEmitter {
     /**
      * @param {object} pipeline - The underlying RAG pipeline (must have a .run() method)
      * @param {object} [options] - Override default configuration
@@ -47,6 +39,7 @@ export class GuardrailsPipeline extends EventEmitter<[never]> {
      * scrub every string in them with the same PII patterns as the answer.
      *
      * @param {*} value - Object, array or string to redact in place
+     * @param {string[]} [matches=[]] - Strings found by PII detectors, redacted too
      * @returns {*} The redacted value
      * @private
      */

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

@@ -5,7 +5,7 @@
  *
  * @extends EventEmitter
  */
-export class PostGenerationGuard extends EventEmitter<[never]> {
+export class PostGenerationGuard extends EventEmitter {
     /**
      * @param {object} [options] - Override default configuration
      * @param {boolean} [options.enablePIIDetection=true] - Whether to detect PII in output
@@ -14,6 +14,9 @@ export class PostGenerationGuard extends EventEmitter<[never]> {
      * @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)
+     * @param {Array<object>} [options.detectors=[]] - PII detectors to run on the output too (see ./detectors); their matches are redacted. Async ones need checkAsync()
+     * @param {boolean} [options.builtIn=true] - false: use only `detectors`, not the built-in PII patterns
+     * @param {'block'|'skip'} [options.onDetectorError='block'] - A detector that throws makes the output unsafe ('block'; what it would have found can't be redacted) or is ignored ('skip')
      */
     constructor(options?: {
         enablePIIDetection?: boolean;
@@ -22,7 +25,12 @@ export class PostGenerationGuard extends EventEmitter<[never]> {
         maxResponseLength?: number;
         minResponseLength?: number;
         piiPatterns?: object;
+        detectors?: Array<object>;
+        builtIn?: boolean;
+        onDetectorError?: "block" | "skip";
     });
+    /** @private */
+    private _detectors;
     config: any;
     /**
      * Check generated output for safety issues, PII, and groundedness.
@@ -43,15 +51,37 @@ export class PostGenerationGuard extends EventEmitter<[never]> {
         sanitizedOutput: string;
         groundednessScore?: number;
     };
+    /**
+     * check() for async detectors, such as a model or a PII service.
+     * Detectors run concurrently.
+     *
+     * @param {string} output
+     * @param {Array<object>} [retrievedDocs=[]]
+     * @param {object} [options]
+     * @param {AbortSignal} [options.signal] - Passed to each detector in its context
+     * @returns {Promise<ReturnType<PostGenerationGuard['check']>>}
+     */
+    checkAsync(output: string, retrievedDocs?: Array<object>, { signal }?: {
+        signal?: AbortSignal;
+    }): Promise<ReturnType<PostGenerationGuard["check"]>>;
+    /** @private */
+    private _runDetectors;
+    /** @private 1. The output must be a string. */
+    private _invalid;
+    /** @private */
+    private _check;
     /**
      * 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.
+     * citation sentences. Detectors don't run here (they may be async):
+     * pass the strings a check found, `detectedText(result)`, as `matches`
+     * so they are removed too.
      *
      * @param {string} text
+     * @param {string[]} [matches=[]] - Exact strings to redact as well
      * @returns {string}
      */
-    redact(text: string): string;
+    redact(text: string, matches?: string[]): string;
 }
 /**
  * Default configuration for the PostGenerationGuard.

package/dist/types/guardrails/pre-retrieval-guard.d.ts

@@ -5,7 +5,7 @@
  *
  * @extends EventEmitter
  */
-export class PreRetrievalGuard extends EventEmitter<[never]> {
+export class PreRetrievalGuard extends EventEmitter {
     /**
      * @param {object} [options] - Override default configuration
      * @param {number} [options.maxQueryLength=10000] - Maximum allowed query length
@@ -14,6 +14,9 @@ export class PreRetrievalGuard extends EventEmitter<[never]> {
      * @param {string[]} [options.blockedTopics=[]] - Topics to reject
      * @param {string[]} [options.allowedTopics=[]] - If non-empty, only these topics are permitted
      * @param {RegExp[]} [options.injectionPatterns] - Additional injection patterns (merged with defaults)
+     * @param {Array<object>} [options.detectors=[]] - Injection detectors to run on the query as well (see ./detectors); async ones need checkAsync()
+     * @param {boolean} [options.builtIn=true] - false: use only `detectors`, not the built-in patterns
+     * @param {'block'|'skip'} [options.onDetectorError='block'] - A detector that throws makes the query unsafe ('block') or is ignored ('skip')
      */
     constructor(options?: {
         maxQueryLength?: number;
@@ -22,7 +25,12 @@ export class PreRetrievalGuard extends EventEmitter<[never]> {
         blockedTopics?: string[];
         allowedTopics?: string[];
         injectionPatterns?: RegExp[];
+        detectors?: Array<object>;
+        builtIn?: boolean;
+        onDetectorError?: "block" | "skip";
     });
+    /** @private */
+    private _detectors;
     config: any;
     /** @private Extra patterns supplied by the caller */
     private _customPatterns;
@@ -55,6 +63,26 @@ export class PreRetrievalGuard extends EventEmitter<[never]> {
             }>;
         };
     };
+    /**
+     * check() for async detectors, such as a classifier model or a service.
+     * Detectors run concurrently.
+     *
+     * @param {string} query
+     * @param {object} [options]
+     * @param {AbortSignal} [options.signal] - Passed to each detector in its context
+     * @returns {Promise<ReturnType<PreRetrievalGuard['check']>>}
+     */
+    checkAsync(query: string, { signal }?: {
+        signal?: AbortSignal;
+    }): Promise<ReturnType<PreRetrievalGuard["check"]>>;
+    /** @private */
+    private _runDetectors;
+    /** @private */
+    private _emit;
+    /** @private Validation and the built-in checks, before any detector runs. */
+    private _prepare;
+    /** @private Merge the detectors' findings and emit the result. */
+    private _finish;
 }
 /**
  * Default configuration for the PreRetrievalGuard.

package/dist/types/guardrails/retrieval-guard.d.ts

@@ -5,7 +5,7 @@
  *
  * @extends EventEmitter
  */
-export class RetrievalGuard extends EventEmitter<[never]> {
+export class RetrievalGuard extends EventEmitter {
     /**
      * @param {object} [options] - Override default configuration
      * @param {number} [options.minRelevanceScore=0] - Minimum relevance score threshold
@@ -14,6 +14,9 @@ export class RetrievalGuard extends EventEmitter<[never]> {
      * @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
+     * @param {Array<object>} [options.detectors=[]] - Injection detectors to run on each document's text too, when detectInjection is on (see ./detectors); async ones need filterAsync(), which calls them once per document, concurrently
+     * @param {boolean} [options.builtIn=true] - false: use only `detectors` for the injection scan
+     * @param {'block'|'skip'} [options.onDetectorError='block'] - A detector that throws counts as a finding ('block': the document is removed or flagged) or is ignored ('skip')
      */
     constructor(options?: {
         minRelevanceScore?: number;
@@ -22,8 +25,13 @@ export class RetrievalGuard extends EventEmitter<[never]> {
         detectInjection?: boolean;
         injectionAction?: "remove" | "flag";
         injectionPatterns?: RegExp[];
+        detectors?: Array<object>;
+        builtIn?: boolean;
+        onDetectorError?: "block" | "skip";
     });
     config: any;
+    /** @private */
+    private _detectors;
     /**
      * Filter retrieval results based on configured guards.
      *
@@ -48,6 +56,27 @@ export class RetrievalGuard extends EventEmitter<[never]> {
             };
         };
     };
+    /**
+     * filter() for async detectors, such as a classifier model or a service. Each
+     * document that reaches the injection scan is checked by every detector,
+     * all concurrently.
+     *
+     * @param {Array<object>} results
+     * @param {object} [context={}]
+     * @param {object} [options]
+     * @param {AbortSignal} [options.signal] - Passed to each detector in its context
+     * @returns {Promise<ReturnType<RetrievalGuard['filter']>>}
+     */
+    filterAsync(results: Array<object>, context?: object, { signal }?: {
+        signal?: AbortSignal;
+    }): Promise<ReturnType<RetrievalGuard["filter"]>>;
+    /**
+     * @private Relevance, freshness and ACL, then which documents go on to
+     * the injection scan.
+     */
+    private _screen;
+    /** @private 4. Indirect prompt injection in document text (opt-in). */
+    private _finish;
 }
 /**
  * Default configuration for the RetrievalGuard.

package/dist/types/mcp/mcp-server.d.ts

@@ -9,7 +9,7 @@
  * const tools = server.getToolDefinitions();
  * const result = await server.handleToolUse('my_tool', { query: 'What is X?' });
  */
-export class MCPServer extends EventEmitter<[never]> {
+export class MCPServer extends EventEmitter {
     /**
      * Convenience factory: create an MCPServer with a single pipeline registered.
      *

package/dist/types/observability/otel.d.ts

@@ -1,16 +1,22 @@
 /**
  * Normalise the `telemetry` option of createRagPipeline. `api` is the
- * @opentelemetry/api module, for builds that cannot require() it (/edge).
- * @param {boolean|{tracer?: object, api?: object, recordContent?: boolean}} option
- * @returns {null|{api: object, tracer: object, recordContent: boolean}}
+ * @opentelemetry/api module, for builds that cannot require() it (/edge);
+ * `logs` is @opentelemetry/api-logs, for evaluation events with an SDK that
+ * registers its LoggerProvider there, and `logger` a Logger to emit them with.
+ * @param {boolean|{tracer?: object, api?: object, logs?: object, logger?: object, recordContent?: boolean}} option
+ * @returns {null|{api: object, tracer: object, logger: object|null, runKey: symbol, recordContent: boolean}}
  */
 export function createTelemetry(option: boolean | {
     tracer?: object;
     api?: object;
+    logs?: object;
+    logger?: object;
     recordContent?: boolean;
 }): null | {
     api: object;
     tracer: object;
+    logger: object | null;
+    runKey: symbol;
     recordContent: boolean;
 };
 /** Wrap a component so its stage methods run in spans. */

package/dist/types/observability/scores.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @param {object} result - A pipeline run result (or a stream's done
+ *   chunk) with `evaluation` and/or `citations`, or a checkAnswer() result
+ * @param {object} [options]
+ * @param {boolean} [options.explanations=false] - Include explanations,
+ *   which quote the answer
+ * @returns {Array<{name: string, value: number, target: 'retrieval'|'generation', label?: string, explanation?: string}>}
+ */
+export function evaluationScores(result: object, { explanations }?: {
+    explanations?: boolean;
+}): Array<{
+    name: string;
+    value: number;
+    target: "retrieval" | "generation";
+    label?: string;
+    explanation?: string;
+}>;
+/**
+ * The scores of a run result or answer check as Langfuse scores: the
+ * objects `langfuse.score.create()` takes (from `@langfuse/client`), and,
+ * without a trace id, the evaluations a Langfuse experiment evaluator
+ * returns. Langfuse is not a dependency.
+ *
+ * With `telemetry` on, a run result carries its OpenTelemetry trace and span
+ * ids in `result.telemetry`; Langfuse uses the same ids when it receives the
+ * spans (LangfuseSpanProcessor), so each score is attached to the trace and
+ * to the span it judges: the retrieval for contextPrecision and
+ * contextRecall, the generation for the rest. A score whose stage had no
+ * span (a cache hit) gets the trace only: Langfuse's default span filter
+ * keeps the stage spans (they have gen_ai.* attributes) but not the run
+ * span, so an observation id for it could point at nothing.
+ *
+ * @param {object} result - A pipeline run result, a stream's done chunk, or a checkAnswer() result
+ * @param {object} [options]
+ * @param {string} [options.traceId] - Overrides `result.telemetry.traceId`
+ * @param {string} [options.observationId] - Attach every score to this observation
+ * @param {string} [options.sessionId]
+ * @param {boolean} [options.comments=false] - Add explanations as comments; they quote the answer
+ * @returns {Array<{name: string, value: number, dataType: 'NUMERIC', traceId?: string, observationId?: string, sessionId?: string, comment?: string, metadata?: {label: string}}>}
+ */
+export function toLangfuseScores(result: object, options?: {
+    traceId?: string;
+    observationId?: string;
+    sessionId?: string;
+    comments?: boolean;
+}): Array<{
+    name: string;
+    value: number;
+    dataType: "NUMERIC";
+    traceId?: string;
+    observationId?: string;
+    sessionId?: string;
+    comment?: string;
+    metadata?: {
+        label: string;
+    };
+}>;

package/dist/types/reranker/cascade-reranker.d.ts

@@ -5,7 +5,7 @@
  *
  * @extends EventEmitter
  */
-export class CascadeReranker extends EventEmitter<[never]> {
+export class CascadeReranker extends EventEmitter {
     /**
      * @param {object[]} [rerankers=[]] - Array of objects with .rerank() method
      * @param {object} [options]

package/dist/types/reranker/embedding-reranker.d.ts

@@ -8,7 +8,7 @@
  *
  * @extends EventEmitter
  */
-export class EmbeddingReranker extends EventEmitter<[never]> {
+export class EmbeddingReranker extends EventEmitter {
     /**
      * @param {object} embedder - Must expose .embedQuery(text) or .embed(text)
      * @param {object} [options]

package/dist/types/reranker/scoring-reranker.d.ts

@@ -4,7 +4,7 @@
  *
  * @extends EventEmitter
  */
-export class ScoringReranker extends EventEmitter<[never]> {
+export class ScoringReranker extends EventEmitter {
     /**
      * @param {object} [options]
      * @param {number} [options.k1=1.2] - Term frequency saturation parameter

package/dist/types/retrieval/bm25-search.d.ts

@@ -2,7 +2,7 @@
  * Keyword search with BM25 ranking. Index documents with index(), then
  * search(query) returns them scored by term frequency and rarity.
  */
-export class BM25Search extends EventEmitter<[never]> {
+export class BM25Search extends EventEmitter {
     constructor(options?: {});
     config: {
         k1: number;

package/dist/types/retrieval/hybrid-retriever.d.ts

@@ -2,7 +2,7 @@
  * Runs several retrievers in parallel (for example vector and BM25) and
  * fuses their results with weighted reciprocal rank fusion.
  */
-export class HybridRetriever extends EventEmitter<[never]> {
+export class HybridRetriever extends EventEmitter {
     /**
      * @param {Array<{retriever: object, weight: number, name: string}>} retrievers
      * @param {object} options

package/dist/types/security/jwt-validator.d.ts

@@ -1,7 +1,7 @@
 /**
  * JWT Validator with hardened security
  */
-export class JWTValidator extends EventEmitter<[never]> {
+export class JWTValidator extends EventEmitter {
     constructor(options?: {});
     config: {
         algorithm: any;

package/dist/types/security/plugin-sandbox.d.ts

@@ -12,7 +12,7 @@
  * @class PluginSandbox
  * @extends EventEmitter
  */
-export class PluginSandbox extends EventEmitter<[never]> {
+export class PluginSandbox extends EventEmitter {
     constructor(options?: {});
     config: {
         timeout: any;

package/dist/types/streaming/sse-adapter.d.ts

@@ -11,7 +11,7 @@
  *   adapter.on('token', (t) => console.log('sent', t));
  *   await adapter.stream(asyncTokenGenerator, res);
  */
-export class SSEAdapter extends EventEmitter<[never]> {
+export class SSEAdapter extends EventEmitter {
     /**
      * @param {Object} [options] - Configuration overrides
      * @param {string} [options.eventName='token'] - SSE event name for token frames

package/dist/types/streaming/stream-router.d.ts

@@ -13,7 +13,7 @@
  *   const handler = router.createHandler(pipeline);
  *   app.post('/api/query', handler);
  */
-export class StreamRouter extends EventEmitter<[never]> {
+export class StreamRouter extends EventEmitter {
     /**
      * @param {Object} [options] - Configuration overrides
      * @param {string} [options.defaultTransport='sse'] - Fallback transport type

package/dist/types/streaming/streaming-embedder.d.ts

@@ -16,7 +16,7 @@
  *   se.on('done', (stats) => console.log('finished', stats));
  *   const all = await se.embedAll(documents);
  */
-export class StreamingEmbedder extends EventEmitter<[never]> {
+export class StreamingEmbedder extends EventEmitter {
     /**
      * @param {Object} embedder - Embedder instance with `.embed()` or `.embedQuery()`
      * @param {Object} [options] - Override any key from {@link DEFAULT_CONFIG}

package/dist/types/streaming/websocket-adapter.d.ts

@@ -12,7 +12,7 @@
  *   adapter.on('done', () => console.log('stream complete'));
  *   await adapter.stream(asyncTokenGenerator, ws);
  */
-export class WebSocketAdapter extends EventEmitter<[never]> {
+export class WebSocketAdapter extends EventEmitter {
     /**
      * @param {Object} [options] - Configuration overrides
      * @param {string} [options.messageType='token'] - Type field for token messages

package/dist/types/templates/scaffold.d.ts

@@ -9,7 +9,7 @@
  * const result = scaffolder.create('document-qa', '/path/to/my-project');
  * console.log(result.files); // list of created files
  */
-export class ProjectScaffolder extends EventEmitter<[never]> {
+export class ProjectScaffolder extends EventEmitter {
     /**
      * @param {Object} [options={}] - Scaffolder configuration
      * @param {boolean} [options.installDependencies=false] - Whether to auto-run npm install

package/dist/types/testing/contract-tests.d.ts

@@ -11,20 +11,22 @@
  * import { describe, it } from "vitest"; // or "node:test"
  * runContractTests("llm", () => new MyLLM(), { describe, it });
  *
- * @param {'loader'|'embedder'|'retriever'|'reranker'|'llm'} type - Plugin type
+ * @param {'loader'|'embedder'|'retriever'|'reranker'|'llm'|'detector'} type - Plugin type
  * @param {() => (object|Promise<object>)} factory - Returns a new, empty plugin for each check
  * @param {object} [options]
  * @param {string} [options.name] - Name of the test group (default: "<type> contract")
  * @param {boolean} [options.registry=false] - Also require the `metadata` pluginRegistry.register() needs
  * @param {(retriever: object, documents: object[]) => (void|Promise<void>)} [options.setup] - Retrievers: loads the test documents (default: `retriever.store(documents)`), for retrievers without store()
+ * @param {string} [options.positive] - Detectors: text the detector must flag, instead of the default sample for its kind
  * @param {Function} [options.describe] - Your framework's describe (default: the global one)
  * @param {Function} [options.it] - Your framework's it/test (default: the global it or test)
  * @returns {void}
  */
-export function runContractTests(type: "loader" | "embedder" | "retriever" | "reranker" | "llm", factory: () => (object | Promise<object>), options?: {
+export function runContractTests(type: "loader" | "embedder" | "retriever" | "reranker" | "llm" | "detector", factory: () => (object | Promise<object>), options?: {
     name?: string;
     registry?: boolean;
     setup?: (retriever: object, documents: object[]) => (void | Promise<void>);
+    positive?: string;
     describe?: Function;
     it?: Function;
 }): void;
@@ -35,16 +37,18 @@ export function runContractTests(type: "loader" | "embedder" | "retriever" | "re
  * const report = await checkContract("embedder", () => new MyEmbedder());
  * if (!report.passed) console.log(report.results.filter((r) => !r.passed));
  *
- * @param {'loader'|'embedder'|'retriever'|'reranker'|'llm'} type - Plugin type
+ * @param {'loader'|'embedder'|'retriever'|'reranker'|'llm'|'detector'} type - Plugin type
  * @param {() => (object|Promise<object>)} factory - Returns a new, empty plugin for each check
  * @param {object} [options]
  * @param {boolean} [options.registry=false] - Also require the `metadata` pluginRegistry.register() needs
  * @param {(retriever: object, documents: object[]) => (void|Promise<void>)} [options.setup] - Retrievers: loads the test documents (default: `retriever.store(documents)`), for retrievers without store()
+ * @param {string} [options.positive] - Detectors: text the detector must flag, instead of the default sample for its kind
  * @returns {Promise<{ type: string, passed: boolean, results: Array<{ name: string, passed: boolean, skipped: boolean, error?: string }> }>}
  */
-export function checkContract(type: "loader" | "embedder" | "retriever" | "reranker" | "llm", factory: () => (object | Promise<object>), options?: {
+export function checkContract(type: "loader" | "embedder" | "retriever" | "reranker" | "llm" | "detector", factory: () => (object | Promise<object>), options?: {
     registry?: boolean;
     setup?: (retriever: object, documents: object[]) => (void | Promise<void>);
+    positive?: string;
 }): Promise<{
     type: string;
     passed: boolean;

package/dist/types/utils/batch-processor.d.ts

@@ -1,7 +1,7 @@
 /**
  * Batch Processor Class
  */
-export class BatchProcessor extends EventEmitter<[never]> {
+export class BatchProcessor extends EventEmitter {
     constructor(options?: {});
     config: {
         maxTokensPerBatch: number;

package/dist/types/utils/connection-pool.d.ts

@@ -1,7 +1,7 @@
 /**
  * Connection Pool Manager Class
  */
-export class ConnectionPoolManager extends EventEmitter<[never]> {
+export class ConnectionPoolManager extends EventEmitter {
     constructor(options?: {});
     config: {
         maxSockets: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-core",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "createRagPipeline and its building blocks: retrieval, reranking, caching, cost tracking and model routing.",
   "keywords": [
     "rag",