@devilsdev/rag-core 3.3.0 → 3.5.0

package/dist/types/adapters/mastra.d.ts

@@ -38,11 +38,13 @@ export function createMastraScorer(options?: {
  * const guardrails = createMastraGuardrails({ injection: true, pii: "redact" });
  *
  * @param {Object} [options]
- * @param {boolean|Object} [options.injection=true] - Check the last user message; PreRetrievalGuard options
+ * @param {boolean|Object} [options.injection=true] - Check the last user message; PreRetrievalGuard options, including `detectors`
  * @param {'redact'|'block'|false} [options.pii='redact'] - Redact PII in the answer, or abort the run
  * @param {Object<string, RegExp>} [options.piiPatterns] - Extra PII patterns by name
+ * @param {Array<Object>} [options.piiDetectors] - PII detectors to run on the answer too; their matches are redacted
+ * @param {boolean} [options.piiBuiltIn=true] - false: use only piiDetectors, not the built-in PII patterns
  * @param {string} [options.id='rag-pipeline-guardrails']
- * @returns {Object} A Mastra processor
+ * @returns {Object} A Mastra processor. With detectors, its methods return promises (Mastra awaits them)
  */
 export function createMastraGuardrails(options?: {
     injection?: boolean | any;
@@ -50,6 +52,8 @@ export function createMastraGuardrails(options?: {
     piiPatterns?: {
         [x: string]: RegExp;
     };
+    piiDetectors?: Array<any>;
+    piiBuiltIn?: boolean;
     id?: string;
 }): any;
 export declare let MASTRA_METRICS: string[];

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

@@ -5,7 +5,7 @@
  *
  * @extends EventEmitter
  */
-export class AgenticPipeline extends EventEmitter<[never]> {
+export class AgenticPipeline extends EventEmitter {
     /**
      * @param {object} [options] - Override default configuration
      * @param {number} [options.maxConcurrency=3] - Max concurrent DAG node execution

package/dist/types/agentic/iterative-retriever.d.ts

@@ -4,7 +4,7 @@
  *
  * @extends EventEmitter
  */
-export class IterativeRetriever extends EventEmitter<[never]> {
+export class IterativeRetriever extends EventEmitter {
     /**
      * @param {object} [options] - Override default configuration
      * @param {number} [options.maxIterations=3] - Maximum retrieval iterations

package/dist/types/agentic/query-planner.d.ts

@@ -13,7 +13,7 @@
  *
  * @extends EventEmitter
  */
-export class QueryPlanner extends EventEmitter<[never]> {
+export class QueryPlanner extends EventEmitter {
     /**
      * @param {object} [options] - Override default configuration
      * @param {number} [options.minComplexityToSplit=2] - Minimum complexity

package/dist/types/agentic/self-critique.d.ts

@@ -4,7 +4,7 @@
  *
  * @extends EventEmitter
  */
-export class SelfCritiqueChecker extends EventEmitter<[never]> {
+export class SelfCritiqueChecker extends EventEmitter {
     /**
      * @param {object} [options] - Override default configuration
      * @param {number} [options.approvalThreshold=0.5] - Minimum groundedness score to approve an answer

package/dist/types/ai/federation/federated-learning-coordinator.d.ts

@@ -1,4 +1,4 @@
-export class FederatedLearningCoordinator extends EventEmitter<[never]> {
+export class FederatedLearningCoordinator extends EventEmitter {
     constructor(options?: {});
     config: {
         minParticipants: any;

package/dist/types/ai/training/model-training-orchestrator.d.ts

@@ -1,4 +1,4 @@
-export class ModelTrainingOrchestrator extends EventEmitter<[never]> {
+export class ModelTrainingOrchestrator extends EventEmitter {
     constructor(options?: {});
     config: {
         batchSize: any;

package/dist/types/chunking/chunking-engine.d.ts

@@ -4,7 +4,7 @@
  *
  * @extends EventEmitter
  */
-export class ChunkingEngine extends EventEmitter<[never]> {
+export class ChunkingEngine extends EventEmitter {
     /**
      * Create a ChunkingEngine instance.
      *

package/dist/types/citation/citation-tracker.d.ts

@@ -4,7 +4,7 @@
  *
  * @extends EventEmitter
  */
-export class CitationTracker extends EventEmitter<[never]> {
+export class CitationTracker extends EventEmitter {
     /**
      * @param {object} [options] - Override default configuration
      * @param {number} [options.similarityThreshold=0.5] - Minimum similarity for a citation match

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

@@ -66,11 +66,37 @@ export class AnthropicConnector extends BaseConnector {
      * @param {Array<Object|string>} [context=[]] - Retrieved documents for RAG
      * @param {Object} [options={}] - Override model, temperature, maxTokens per-call
      * @param {AbortSignal} [options.signal] - Cancels the request
-     * @returns {Promise<string>} The generated text
+     * @returns {Promise<string>} The answer: every text block of the reply,
+     *   joined. Rejects (code MODEL_REFUSED or NO_TEXT) when the reply has no
+     *   text, such as a refusal or a reply that ran out of maxTokens while
+     *   thinking.
      */
     generate(query: string, context?: Array<any | string>, options?: {
         signal?: AbortSignal;
     }): Promise<string>;
+    /**
+     * Like generate(), with the reply's token usage. The LLM judge uses it so
+     * `check.judge.usage` reports what the judge cost.
+     *
+     * @param {string} query
+     * @param {Array<Object|string>} [context=[]]
+     * @param {Object} [options={}] - As for generate()
+     * @returns {Promise<{text: string, usage: {inputTokens: number, outputTokens: number, totalTokens: number}}>}
+     */
+    generateWithUsage(query: string, context?: Array<any | string>, options?: any): Promise<{
+        text: string;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+            totalTokens: number;
+        };
+    }>;
+    /**
+     * POST a Messages request with retries; a model that rejects
+     * `temperature` gets the request again without it.
+     * @private
+     */
+    private _post;
     /**
      * Stream a response from Claude token-by-token via SSE.
      *
@@ -108,6 +134,14 @@ export namespace DEFAULT_CONFIG {
     export let retryDelay: number;
     export const apiKey: string;
 }
+/**
+ * The answer text of a Messages API response: every `text` block, joined.
+ * Models that think reply with `thinking` blocks before the text, so the
+ * first block is not always the answer.
+ * @param {Object} data - The response body
+ * @returns {string}
+ */
+export function responseText(data: any): string;
 import { BaseConnector } from "./base-connector";
 /**
  * Default configuration for the Anthropic connector.

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

@@ -3,7 +3,7 @@
  * Provides connection lifecycle, health checking, and retry logic.
  * @extends EventEmitter
  */
-export class BaseConnector extends EventEmitter<[never]> {
+export class BaseConnector extends EventEmitter {
     /**
      * @param {Object} options
      * @param {string} [options.name] - Connector display name

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

@@ -1,3 +1,23 @@
+/**
+ * An axios error without what it carries from the request. axios errors
+ * keep the request config, headers included, so logging or serializing one
+ * prints the API key. This copies what callers and the retry logic use
+ * (the response status, headers and body, and the network error code)
+ * into a plain Error, and puts the API's own explanation in the message:
+ * "Anthropic API error 401: authentication_error: invalid x-api-key".
+ *
+ * @param {*} err
+ * @param {string} provider - Name for the message, e.g. "Anthropic"
+ * @returns {*} A clean Error for an axios error; anything else unchanged
+ */
+export function toConnectorError(err: any, provider: string): any;
+/**
+ * Make every error from an axios client a toConnectorError() one.
+ * @param {Object} client - From axios.create()
+ * @param {string} provider
+ * @returns {Object} The client
+ */
+export function cleanAxiosErrors(client: any, provider: string): any;
 /**
  * The text of a streamed response body, chunk by chunk. Handles what axios
  * returns for `responseType: 'stream'` on each runtime: a Node stream of

package/dist/types/cost/cost-calculator.d.ts

@@ -6,7 +6,7 @@
  * const cost = calc.estimate('gpt-4o', 1500, 500);
  * console.log(cost.totalCost); // 0.015
  */
-export class CostCalculator extends EventEmitter<[never]> {
+export class CostCalculator extends EventEmitter {
     /**
      * Provenance of the built-in pricing table.
      * @returns {typeof PRICING_METADATA}

package/dist/types/cost/cost-tracker.d.ts

@@ -8,7 +8,7 @@
  * console.log(result.cost); // { inputTokens, outputTokens, estimatedCost, model }
  * console.log(tracker.getSummary());
  */
-export class CostTracker extends EventEmitter<[never]> {
+export class CostTracker extends EventEmitter {
     /**
      * @param {object} [options]
      * @param {string} [options.model='gpt-3.5-turbo'] - Default LLM model for cost estimation.

package/dist/types/cost/token-budget.d.ts

@@ -12,7 +12,7 @@
  * const status = budget.check(2000, 0.10);
  * if (status.allowed) budget.record(2000, 0.10);
  */
-export class TokenBudget extends EventEmitter<[never]> {
+export class TokenBudget extends EventEmitter {
     /**
      * @param {object} [options]
      * @param {number} [options.maxTokens=Infinity] - Hard token limit.

package/dist/types/dashboard/dashboard-generator.d.ts

@@ -16,7 +16,7 @@ export type DashboardGeneratorConfig = {
  * Generates standalone HTML dashboards from pipeline metrics snapshots.
  * @extends EventEmitter
  */
-export class DashboardGenerator extends EventEmitter<[never]> {
+export class DashboardGenerator extends EventEmitter {
     /**
      * @param {Partial<DashboardGeneratorConfig>} options
      */

package/dist/types/dashboard/metrics-aggregator.d.ts

@@ -71,7 +71,7 @@ export type ErrorData = {
  * Collects and aggregates pipeline metrics into dashboard-ready snapshots.
  * @extends EventEmitter
  */
-export class MetricsAggregator extends EventEmitter<[never]> {
+export class MetricsAggregator extends EventEmitter {
     /**
      * @param {Partial<MetricsAggregatorConfig>} options
      */

package/dist/types/debug/execution-tracer.d.ts

@@ -2,7 +2,7 @@
  * Execution tracer that wraps pipelines to capture run traces
  * @extends EventEmitter
  */
-export class ExecutionTracer extends EventEmitter<[never]> {
+export class ExecutionTracer extends EventEmitter {
     /**
      * Create a new ExecutionTracer
      * @param {object} [options] - Tracer configuration

package/dist/types/debug/trace-inspector.d.ts

@@ -2,7 +2,7 @@
  * Trace inspector that analyzes execution traces produced by ExecutionTracer
  * @extends EventEmitter
  */
-export class TraceInspector extends EventEmitter<[never]> {
+export class TraceInspector extends EventEmitter {
     /**
      * Create a new TraceInspector
      * @param {object} [options] - Inspector configuration

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

@@ -3,7 +3,7 @@
  *
  * Integrates hot reloading with a development workflow
  */
-export class DevServer extends EventEmitter<[never]> {
+export class DevServer extends EventEmitter {
     constructor(options?: {});
     options: {
         port: any;

package/dist/types/dev/hot-reload.d.ts

@@ -11,7 +11,7 @@ export function toIgnoreMatcher(patterns: Array<string | RegExp | Function>): (f
  *
  * Manages file watching and hot reloading of plugins and configuration.
  */
-export class HotReloadManager extends EventEmitter<[never]> {
+export class HotReloadManager extends EventEmitter {
     constructor(options?: {});
     options: {
         enabled: boolean;

package/dist/types/ecosystem/plugin-analytics-dashboard.d.ts

@@ -1,4 +1,4 @@
-export class PluginAnalyticsDashboard extends EventEmitter<[never]> {
+export class PluginAnalyticsDashboard extends EventEmitter {
     constructor(_options?: {});
     _config: {
         port: any;

package/dist/types/ecosystem/plugin-certification.d.ts

@@ -1,4 +1,4 @@
-export class PluginCertification extends EventEmitter<[never]> {
+export class PluginCertification extends EventEmitter {
     constructor(_options?: {});
     _config: {
         registryUrl: any;

package/dist/types/ecosystem/plugin-hub.d.ts

@@ -2,7 +2,7 @@
  * Client for a plugin hub registry: search, inspect, install, publish and
  * rate plugins.
  */
-export class PluginHub extends EventEmitter<[never]> {
+export class PluginHub extends EventEmitter {
     constructor(_options?: {});
     _config: {
         registryUrl: any;

package/dist/types/enterprise/audit-logging.d.ts

@@ -3,7 +3,7 @@
  * in hash-chained logs, with querying, compliance reports and an integrity
  * check.
  */
-export class AuditLogger extends EventEmitter<[never]> {
+export class AuditLogger extends EventEmitter {
     constructor(_options?: {});
     _config: {
         logDir: any;

package/dist/types/enterprise/data-governance.d.ts

@@ -1,4 +1,4 @@
-export class DataGovernanceManager extends EventEmitter<[never]> {
+export class DataGovernanceManager extends EventEmitter {
     constructor(_options?: {});
     _config: {
         policies: {

package/dist/types/enterprise/multi-tenancy.d.ts

@@ -1,4 +1,4 @@
-export class TenantManager extends EventEmitter<[never]> {
+export class TenantManager extends EventEmitter {
     constructor(_options?: {});
     _config: {
         dataDir: any;

package/dist/types/enterprise/sso-integration.d.ts

@@ -1,4 +1,4 @@
-export class SSOManager extends EventEmitter<[never]> {
+export class SSOManager extends EventEmitter {
     constructor(_options?: {});
     _config: any;
     sessions: Map<any, any>;

package/dist/types/evaluate/pipeline-evaluator.d.ts

@@ -9,7 +9,7 @@
  * evaluator.on('evaluated', (result) => console.log(result.scores));
  * const result = evaluator.evaluate({ query: 'What is RAG?', answer: '...', results: [...] });
  */
-export class PipelineEvaluator extends EventEmitter<[never]> {
+export class PipelineEvaluator extends EventEmitter {
     /**
      * Create a new PipelineEvaluator.
      * @param {object} [options={}] - Configuration options

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

@@ -4,7 +4,7 @@
  * Uses configurable regex patterns to identify named entities,
  * dates, measurements, URLs, emails, and technical terms.
  */
-export class EntityExtractor extends EventEmitter<[never]> {
+export class EntityExtractor extends EventEmitter {
     /**
      * @param {Object} [options={}] - Extractor options
      * @param {Object<string, RegExp>} [options.patterns] - Custom patterns to merge with defaults

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

@@ -4,7 +4,7 @@
  * 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]> {
+export class GraphRetriever extends EventEmitter {
     /**
      * @param {Object} [options={}] - Retriever options
      * @param {number} [options.traversalDepth=2] - Graph traversal depth

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

@@ -4,7 +4,7 @@
  * Stores typed entities and directed relationships between them,
  * supporting traversal, pattern-based querying, and adjacency lookups.
  */
-export class KnowledgeGraph extends EventEmitter<[never]> {
+export class KnowledgeGraph extends EventEmitter {
     /**
      * @param {Object} [options={}] - Graph configuration options
      */

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

@@ -37,6 +37,74 @@ export type AnswerCheck = {
         content: string;
         metadata: any;
     }>;
+    /**
+     * - Only when the `judge` option is given
+     */
+    judge?: JudgeReport;
+};
+/**
+ * Any LLM for the `judge` option: this library's LLM plugin contract.
+ * `generate` may return the text, or an object with `text` or `content`
+ * (and optionally `usage`).
+ */
+export type JudgeLLM = {
+    generate: (prompt: string, context: Array<any>, options?: any) => (string | {
+        text?: string;
+        content?: string;
+        usage?: any;
+    } | Promise<string | {
+        text?: string;
+        content?: string;
+        usage?: any;
+    }>);
+};
+/**
+ * The verdict on one sentence when a judge is used.
+ */
+export type JudgeVerdict = {
+    sentence: string;
+    /**
+     * - The combined verdict
+     */
+    verdict: "supported" | "unsupported";
+    /**
+     * - Id of the supporting source, when supported
+     */
+    sourceId: string | null;
+    /**
+     * - Why, in words (the judge's reason when it decided)
+     */
+    reason: string;
+    /**
+     *   - What the lexical check found. Only `low_overlap` sentences go to the judge
+     */
+    lexicalReason: "supported" | "low_overlap" | "number_mismatch" | "polarity_mismatch" | "no_sources";
+    decidedBy: "lexical" | "judge";
+};
+/**
+ * What the judge did.
+ */
+export type JudgeReport = {
+    /**
+     * - One per sentence, in order
+     */
+    verdicts: JudgeVerdict[];
+    /**
+     * - Calls made to `judge.generate` (0 or 1)
+     */
+    calls: number;
+    /**
+     * - Token usage summed over the calls, when the LLM result carries `usage`
+     */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    /**
+     * - Why the judge's reply could not be parsed
+     */
+    error?: string;
 };
 /**
  * @typedef {Object} AnswerCheck
@@ -51,6 +119,37 @@ export type AnswerCheck = {
  *   referenceAnswer is given); only when `evaluate` is not false
  * @property {Array<{id: string, content: string, metadata: Object}>} sources
  *   - The sources as they were checked
+ * @property {JudgeReport} [judge] - Only when the `judge` option is given
+ */
+/**
+ * Any LLM for the `judge` option: this library's LLM plugin contract.
+ * `generate` may return the text, or an object with `text` or `content`
+ * (and optionally `usage`).
+ *
+ * @typedef {Object} JudgeLLM
+ * @property {(prompt: string, context: Array<any>, options?: Object) => (string|{text?: string, content?: string, usage?: Object}|Promise<string|{text?: string, content?: string, usage?: Object}>)} generate
+ */
+/**
+ * The verdict on one sentence when a judge is used.
+ *
+ * @typedef {Object} JudgeVerdict
+ * @property {string} sentence
+ * @property {'supported'|'unsupported'} verdict - The combined verdict
+ * @property {string|null} sourceId - Id of the supporting source, when supported
+ * @property {string} reason - Why, in words (the judge's reason when it decided)
+ * @property {'supported'|'low_overlap'|'number_mismatch'|'polarity_mismatch'|'no_sources'} lexicalReason
+ *   - What the lexical check found. Only `low_overlap` sentences go to the judge
+ * @property {'lexical'|'judge'} decidedBy
+ */
+/**
+ * What the judge did.
+ *
+ * @typedef {Object} JudgeReport
+ * @property {JudgeVerdict[]} verdicts - One per sentence, in order
+ * @property {number} calls - Calls made to `judge.generate` (0 or 1)
+ * @property {{inputTokens: number, outputTokens: number, totalTokens: number}} [usage]
+ *   - Token usage summed over the calls, when the LLM result carries `usage`
+ * @property {string} [error] - Why the judge's reply could not be parsed
  */
 /**
  * Check an answer against the sources it was generated from.
@@ -74,15 +173,24 @@ export type AnswerCheck = {
  * @param {Object} [params.embedder] - With a referenceAnswer, adds
  *   `evaluation.scores.semanticSimilarity` (computeSemanticSimilarity)
  * @param {boolean} [params.evaluate=true] - Also compute evaluation scores
+ * @param {JudgeLLM} [params.judge] - Opt-in LLM judge for sentences the
+ *   lexical check failed for lack of word overlap (correct paraphrases).
+ *   It never overturns a sentence that failed the number or negation check,
+ *   and a "supported" verdict must name a source whose numbers and negation
+ *   match the sentence. Unparseable output keeps a sentence unsupported.
+ *   With a judge, `grounded`, `groundedness` and `unsupported` combine both
+ *   checks and `judge` reports the verdicts; `citations` and `evaluation`
+ *   stay lexical. Errors thrown by `judge.generate` are not caught.
  * @returns {Promise<AnswerCheck>}
  */
-export function checkAnswer({ answer, sources, question, referenceAnswer, embedder, evaluate, }?: {
+export function checkAnswer({ answer, sources, question, referenceAnswer, embedder, evaluate, judge, }?: {
     answer: string;
     sources: Array<string | any>;
     question?: string;
     referenceAnswer?: string;
     embedder?: any;
     evaluate?: boolean;
+    judge?: JudgeLLM;
 }): Promise<AnswerCheck>;
 /**
  * Normalize sources to `{ id, content, metadata }`.

package/dist/types/grounding/llm-judge.d.ts

@@ -0,0 +1,93 @@
+export namespace REASONS {
+    let supported: string;
+    let lowOverlap: string;
+    let numberMismatch: string;
+    let polarityMismatch: string;
+    let noSources: string;
+}
+/** Instructions at the top of every judge prompt. */
+export const JUDGE_INSTRUCTIONS: string;
+/**
+ * Build the judge prompt for the given claims.
+ *
+ * @param {string[]} claims - Sentences to rule on
+ * @param {Array<{id: string, content: string}>} docs
+ * @returns {string}
+ */
+export function buildJudgePrompt(claims: string[], docs: Array<{
+    id: string;
+    content: string;
+}>): string;
+/**
+ * Parse the judge's reply into one verdict per claim. Tolerates a code fence
+ * around the JSON; anything else that is not the expected array leaves every
+ * claim without a verdict.
+ *
+ * @param {*} raw - What llm.generate() returned
+ * @param {number} claimCount
+ * @returns {{ verdicts: Array<{verdict: string, source: string|null, reason: string}|null>, error: string|null }}
+ *   verdicts[i] is null when claim i+1 got no well-formed verdict
+ */
+export function parseJudgeVerdicts(raw: any, claimCount: number): {
+    verdicts: Array<{
+        verdict: string;
+        source: string | null;
+        reason: string;
+    } | null>;
+    error: string | null;
+};
+/**
+ * The lexical reason for every sentence, in order.
+ *
+ * @param {Array<{text: string, classification: string}>} sentences - From
+ *   CitationTracker's hallucination report
+ * @param {Array<{id?: string, content: string}>} docs
+ * @param {Array<string[]>} [allowed] - Per sentence, the ids of the only
+ *   docs that may support it (verifyCitations: the passages it cites)
+ * @returns {string[]}
+ */
+export function lexicalReasons(sentences: Array<{
+    text: string;
+    classification: string;
+}>, docs: Array<{
+    id?: string;
+    content: string;
+}>, allowed?: Array<string[]>): string[];
+/**
+ * Run the judge on the sentences that failed for lack of overlap and
+ * combine its verdicts with the lexical result.
+ *
+ * Overturn rule: a judge "supported" counts only when the sentence failed
+ * for lack of overlap, the verdict is well formed, it names a source that
+ * exists, and that source passes the numeric and polarity checks against
+ * the sentence. Everything else keeps the lexical verdict.
+ *
+ * @param {Object} params
+ * @param {{generate: Function}} params.judge
+ * @param {Array<{text: string, classification: string, bestSource: Object|null}>} params.sentences
+ * @param {Array<{id: string, content: string}>} params.docs
+ * @param {Array<string[]>} [params.allowed] - Per sentence, the ids of the
+ *   only docs that may support it; a verdict naming another doc is kept
+ *   unsupported. Default: any doc.
+ * @returns {Promise<{verdicts: Array<Object>, calls: number, usage?: Object, error?: string}>}
+ */
+export function runJudge({ judge, sentences, docs, allowed }: {
+    judge: {
+        generate: Function;
+    };
+    sentences: Array<{
+        text: string;
+        classification: string;
+        bestSource: any | null;
+    }>;
+    docs: Array<{
+        id: string;
+        content: string;
+    }>;
+    allowed?: Array<string[]>;
+}): Promise<{
+    verdicts: Array<any>;
+    calls: number;
+    usage?: any;
+    error?: string;
+}>;