@devilsdev/rag-core 3.4.0 → 3.5.0

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/llm-judge.d.ts

@@ -41,15 +41,18 @@ export function parseJudgeVerdicts(raw: any, claimCount: number): {
  *
  * @param {Array<{text: string, classification: string}>} sentences - From
  *   CitationTracker's hallucination report
- * @param {Array<{content: string}>} docs
+ * @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;
-}>): 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.
@@ -63,9 +66,12 @@ export function lexicalReasons(sentences: Array<{
  * @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 }: {
+export function runJudge({ judge, sentences, docs, allowed }: {
     judge: {
         generate: Function;
     };
@@ -78,6 +84,7 @@ export function runJudge({ judge, sentences, docs }: {
         id: string;
         content: string;
     }>;
+    allowed?: Array<string[]>;
 }): Promise<{
     verdicts: Array<any>;
     calls: number;

package/dist/types/grounding/provider-citations.d.ts

@@ -0,0 +1,244 @@
+/**
+ * One citation of a claim, normalised.
+ */
+export type ProviderCitation = {
+    /**
+     * - Your document id, the document title or index, a search result's source, a URL or an OpenAI file id
+     */
+    sourceId: string;
+    title: string | null;
+    /**
+     * - Where the passage is; `type` is the provider's citation type
+     */
+    location: any;
+    /**
+     * - The cited text; empty when the response doesn't carry it
+     */
+    passages: string[];
+};
+/**
+ * A claim of the answer and the citations attached to it.
+ */
+export type CitedClaim = {
+    text: string;
+    /**
+     * - Offset in `answer`
+     */
+    start: number;
+    end: number;
+    citations: ProviderCitation[];
+};
+/**
+ * What fromAnthropicCitations() and fromOpenAIFileCitations() return.
+ */
+export type ProviderCitations = {
+    provider: "anthropic" | "openai";
+    /**
+     * - The answer text
+     */
+    answer: string;
+    claims: CitedClaim[];
+    /**
+     * - Citations of other kinds, by type
+     */
+    skipped: {
+        [x: string]: number;
+    };
+    /**
+     * - OpenAI: whether the response had file search results
+     */
+    results?: boolean;
+    /**
+     * - Claude: the message's stop_reason ("refusal" when Claude declined)
+     */
+    stopReason?: string | null;
+};
+/**
+ * A claim's verdict from verifyCitations().
+ */
+export type VerifiedClaim = {
+    text: string;
+    start: number;
+    end: number;
+    verdict: "supported" | "unsupported" | "unverifiable";
+    lexicalReason: "supported" | "low_overlap" | "number_mismatch" | "polarity_mismatch" | "unverifiable";
+    /**
+     * - Why, in words
+     */
+    reason: string;
+    decidedBy: "lexical" | "judge";
+    /**
+     * - Support of the claim by all its cited passages together, 0..1
+     */
+    score: number | null;
+    /**
+     *   - Each citation's own support; null when it had no cited text
+     */
+    citations: Array<{
+        sourceId: string;
+        title: string | null;
+        location: any;
+        score: number | null;
+        supports: boolean | null;
+    }>;
+};
+/**
+ * What verifyCitations() resolves to.
+ */
+export type CitationVerification = {
+    /**
+     * - Not a refusal, at least one claim, every claim supported and every citation checkable; uncited sentences don't count against it (see `uncited`)
+     */
+    verified: boolean;
+    provider: "anthropic" | "openai";
+    claims: VerifiedClaim[];
+    /**
+     * - Sentences with content that no citation covers
+     */
+    uncited: Array<{
+        text: string;
+        start: number;
+        end: number;
+    }>;
+    summary: {
+        claims: number;
+        supported: number;
+        unsupported: number;
+        unverifiable: number;
+        citations: number;
+        unverifiableCitations: number;
+        uncitedSentences: number;
+    };
+    skipped: {
+        [x: string]: number;
+    };
+    /**
+     * - Claude declined to answer (stop_reason "refusal"); never verified
+     */
+    refused: boolean;
+    /**
+     * - Only with the `judge` option
+     */
+    judge?: {
+        calls: number;
+        usage?: any;
+        error?: string;
+    };
+};
+/**
+ * Normalise the citations of a Claude Messages API response.
+ *
+ * Each text block that carries citations is a claim. Pass a stream's
+ * final message (`stream.finalMessage()`).
+ *
+ * @param {object} message - The Message, as the SDK returns it or as JSON
+ * @param {object} [options]
+ * @param {Array<object>} [options.documents] - The request's document blocks
+ *   in order (`document_index` counts them), as your own `{ id }` records,
+ *   so citations name your ids; otherwise a citation is named by the
+ *   document's title, or its index
+ * @returns {ProviderCitations}
+ */
+export function fromAnthropicCitations(message: object, { documents }?: {
+    documents?: Array<object>;
+}): ProviderCitations;
+/**
+ * Normalise the file citations of an OpenAI Responses API response.
+ *
+ * A `file_citation` carries only `file_id`, `filename` and an `index` into
+ * the text, not the passage: the passages come from the file search
+ * results, which the request must ask for with
+ * `include: ["file_search_call.results"]`. Without them every citation is
+ * unverifiable. OpenAI gives a position, not a span, and puts it after the
+ * text it cites, a sentence or a paragraph (several citations can share
+ * it): each sentence from the previous citation's position up to this one
+ * is a claim carrying its citations. The boundary is inferred.
+ * Web and container citations are counted in `skipped`. Pass a stream's
+ * completed response.
+ *
+ * @param {object} response - The Response, as the SDK returns it or as JSON
+ * @returns {ProviderCitations}
+ */
+export function fromOpenAIFileCitations(response: object): ProviderCitations;
+/**
+ * Check every claim against the passages it cites: together, so a claim
+ * that takes one fact from each of two passages is supported. Each
+ * citation's own score is reported too.
+ *
+ * @param {ProviderCitations} input - From fromAnthropicCitations() or fromOpenAIFileCitations()
+ * @param {object} [options]
+ * @param {{generate: Function}} [options.judge] - Opt-in LLM judge for claims
+ *   that failed for lack of word overlap (paraphrases), as in checkAnswer();
+ *   it may only name a passage the claim cites, and never overturns a
+ *   number or negation mismatch. One call at most. Errors from
+ *   `judge.generate` are not caught.
+ * @returns {Promise<CitationVerification>}
+ */
+export function verifyCitations(input: ProviderCitations, { judge }?: {
+    judge?: {
+        generate: Function;
+    };
+}): Promise<CitationVerification>;
+/**
+ * One citation of a claim, normalised.
+ *
+ * @typedef {Object} ProviderCitation
+ * @property {string} sourceId - Your document id, the document title or index, a search result's source, a URL or an OpenAI file id
+ * @property {string|null} title
+ * @property {Object} location - Where the passage is; `type` is the provider's citation type
+ * @property {string[]} passages - The cited text; empty when the response doesn't carry it
+ */
+/**
+ * A claim of the answer and the citations attached to it.
+ *
+ * @typedef {Object} CitedClaim
+ * @property {string} text
+ * @property {number} start - Offset in `answer`
+ * @property {number} end
+ * @property {ProviderCitation[]} citations
+ */
+/**
+ * What fromAnthropicCitations() and fromOpenAIFileCitations() return.
+ *
+ * @typedef {Object} ProviderCitations
+ * @property {'anthropic'|'openai'} provider
+ * @property {string} answer - The answer text
+ * @property {CitedClaim[]} claims
+ * @property {Object<string, number>} skipped - Citations of other kinds, by type
+ * @property {boolean} [results] - OpenAI: whether the response had file search results
+ * @property {string|null} [stopReason] - Claude: the message's stop_reason ("refusal" when Claude declined)
+ */
+/**
+ * A claim's verdict from verifyCitations().
+ *
+ * @typedef {Object} VerifiedClaim
+ * @property {string} text
+ * @property {number} start
+ * @property {number} end
+ * @property {'supported'|'unsupported'|'unverifiable'} verdict
+ * @property {'supported'|'low_overlap'|'number_mismatch'|'polarity_mismatch'|'unverifiable'} lexicalReason
+ * @property {string} reason - Why, in words
+ * @property {'lexical'|'judge'} decidedBy
+ * @property {number|null} score - Support of the claim by all its cited passages together, 0..1
+ * @property {Array<{sourceId: string, title: string|null, location: Object, score: number|null, supports: boolean|null}>} citations
+ *   - Each citation's own support; null when it had no cited text
+ */
+/**
+ * What verifyCitations() resolves to.
+ *
+ * @typedef {Object} CitationVerification
+ * @property {boolean} verified - Not a refusal, at least one claim, every claim supported and every citation checkable; uncited sentences don't count against it (see `uncited`)
+ * @property {'anthropic'|'openai'} provider
+ * @property {VerifiedClaim[]} claims
+ * @property {Array<{text: string, start: number, end: number}>} uncited - Sentences with content that no citation covers
+ * @property {{claims: number, supported: number, unsupported: number, unverifiable: number, citations: number, unverifiableCitations: number, uncitedSentences: number}} summary
+ * @property {Object<string, number>} skipped
+ * @property {boolean} refused - Claude declined to answer (stop_reason "refusal"); never verified
+ * @property {{calls: number, usage?: Object, error?: string}} [judge] - Only with the `judge` option
+ */
+/** Sentences of `text` with their offsets (the splitSentences rule). */
+export function sentencesWithOffsets(text: any): {
+    text: string;
+    start: number;
+    end: number;
+}[];