@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

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

@@ -0,0 +1,152 @@
+/**
+ * Maps token counts to cost estimates by provider and model.
+ *
+ * @example
+ * const calc = new CostCalculator();
+ * const cost = calc.estimate('gpt-4o', 1500, 500);
+ * console.log(cost.totalCost); // 0.015
+ */
+export class CostCalculator extends EventEmitter<[never]> {
+    /**
+     * Provenance of the built-in pricing table.
+     * @returns {typeof PRICING_METADATA}
+     */
+    static getPricingMetadata(): typeof PRICING_METADATA;
+    /**
+     * @param {object} [options]
+     * @param {Record<string, {input: number, output: number, unit?: number, source?: string, asOf?: string}>} [options.pricing]
+     *   Replaces the built-in pricing table entirely (only these models are known).
+     * @param {Record<string, {input: number, output: number, unit: number}>} [options.customPricing]
+     *   Additional or override model pricing entries, merged over the base table.
+     */
+    constructor(options?: {
+        pricing?: Record<string, {
+            input: number;
+            output: number;
+            unit?: number;
+            source?: string;
+            asOf?: string;
+        }>;
+        customPricing?: Record<string, {
+            input: number;
+            output: number;
+            unit: number;
+        }>;
+    });
+    pricing: {
+        [x: string]: {
+            input: number;
+            output: number;
+            unit: number;
+            source: string;
+            asOf: string;
+        };
+    };
+    /** @private Models already warned about as unknown */
+    private _warnedModels;
+    /**
+     * Resolve a model key from the pricing table.
+     * Tries an exact match (case-insensitive, '.' and '-' equivalent), then the
+     * longest known key contained in the model name (so dated snapshots such
+     * as "gpt-4o-mini-2024-07-18" resolve to "gpt-4o-mini", not "gpt-4"), then
+     * a known key that contains the model name.
+     * @param {string} model
+     * @returns {string|null} The matched pricing key or null.
+     * @private
+     */
+    private _resolveModel;
+    /**
+     * Emit a one-time warning for a model with no known price.
+     * Listeners on 'warning' receive `{ type: 'unknown-model', model, message }`;
+     * without a listener the warning goes to process.emitWarning.
+     * @param {string} model
+     * @private
+     */
+    private _warnUnknownModel;
+    /**
+     * Estimate the cost for a given token count.
+     *
+     * @param {string} model - Model identifier (case-insensitive, partial match supported).
+     * @param {number} inputTokens - Number of input / prompt tokens.
+     * @param {number} [outputTokens=0] - Number of output / completion tokens.
+     * @returns {{inputCost: number, outputCost: number, totalCost: number, model: string,
+     *            inputTokens: number, outputTokens: number, currency: string,
+     *            pricingSource?: string, pricingAsOf?: string|null, warning?: string}}
+     */
+    estimate(model: string, inputTokens: number, outputTokens?: number): {
+        inputCost: number;
+        outputCost: number;
+        totalCost: number;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        currency: string;
+        pricingSource?: string;
+        pricingAsOf?: string | null;
+        warning?: string;
+    };
+    /**
+     * Register custom model pricing.
+     *
+     * @param {string} model - Model identifier.
+     * @param {{input: number, output: number, unit?: number, source?: string, asOf?: string}} pricing - Pricing definition.
+     */
+    addModel(model: string, pricing: {
+        input: number;
+        output: number;
+        unit?: number;
+        source?: string;
+        asOf?: string;
+    }): void;
+    /**
+     * List all known model names.
+     * @returns {string[]}
+     */
+    listModels(): string[];
+    /**
+     * Retrieve pricing for a specific model.
+     *
+     * @param {string} model - Model identifier (supports fuzzy resolution).
+     * @returns {{input: number, output: number, unit: number, source?: string, asOf?: string|null}|null}
+     */
+    getModelPricing(model: string): {
+        input: number;
+        output: number;
+        unit: number;
+        source?: string;
+        asOf?: string | null;
+    } | null;
+}
+/**
+ * Built-in pricing table for common LLM and embedding models.
+ * Prices are in USD per `unit` tokens. Each entry records its `source`
+ * (provider pricing page) and `asOf` date.
+ * @type {Record<string, {input: number, output: number, unit: number, source: string, asOf: string}>}
+ */
+export const PRICING: Record<string, {
+    input: number;
+    output: number;
+    unit: number;
+    source: string;
+    asOf: string;
+}>;
+/**
+ * Where the built-in prices come from and when they were recorded.
+ *
+ * The values are the providers' published list prices as copied into this
+ * library on `asOf`; they have not been re-verified since and providers
+ * change prices often. Pass `pricing` or `customPricing` to CostCalculator
+ * to use current or negotiated prices.
+ */
+export const PRICING_METADATA: Readonly<{
+    asOf: "2026-04-07";
+    verified: false;
+    currency: "USD";
+    sources: Readonly<{
+        openai: "https://openai.com/api/pricing/";
+        anthropic: "https://www.anthropic.com/pricing#api";
+        cohere: "https://cohere.com/pricing";
+    }>;
+    note: "Built-in list prices, not re-verified since asOf. Override with the `pricing` or `customPricing` option.";
+}>;
+import { EventEmitter } from "events";

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

@@ -0,0 +1,126 @@
+/**
+ * Wraps pipeline execution to automatically track token usage and costs.
+ *
+ * @example
+ * const tracker = new CostTracker({ model: 'gpt-4o', enableBudget: true, budgetOptions: { maxCost: 10 } });
+ * const wrapped = tracker.wrap(pipeline);
+ * const result = await wrapped.run(input);
+ * console.log(result.cost); // { inputTokens, outputTokens, estimatedCost, model }
+ * console.log(tracker.getSummary());
+ */
+export class CostTracker extends EventEmitter<[never]> {
+    /**
+     * @param {object} [options]
+     * @param {string} [options.model='gpt-3.5-turbo'] - Default LLM model for cost estimation.
+     * @param {string} [options.embeddingModel='text-embedding-3-small'] - Default embedding model.
+     * @param {boolean} [options.enableBudget=false] - Whether to enforce a token/cost budget.
+     * @param {object} [options.budgetOptions] - Options forwarded to {@link TokenBudget}.
+     * @param {object} [options.calculatorOptions] - Options forwarded to {@link CostCalculator}.
+     */
+    constructor(options?: {
+        model?: string;
+        embeddingModel?: string;
+        enableBudget?: boolean;
+        budgetOptions?: object;
+        calculatorOptions?: object;
+    });
+    config: {
+        model: string;
+        embeddingModel: string;
+        enableBudget: boolean;
+        budgetOptions: object;
+        calculatorOptions?: object;
+    };
+    calculator: CostCalculator;
+    budget: TokenBudget;
+    sessions: any[];
+    currentSession: {
+        id: string;
+        startTime: number;
+        endTime: any;
+        metadata: any;
+        entries: any[];
+        totalTokens: number;
+        totalCost: number;
+    };
+    /**
+     * Extract token usage from a pipeline result.
+     * Checks common locations: result.usage, result.evaluation, or estimates from content length.
+     * @param {object} result
+     * @returns {{inputTokens: number, outputTokens: number}}
+     * @private
+     */
+    private _extractUsage;
+    /**
+     * Wrap a pipeline so that every `.run()` call is cost-tracked.
+     *
+     * @param {object} pipeline - Object with a `.run()` method.
+     * @returns {object} A proxy pipeline whose `.run()` enriches results with cost data.
+     */
+    wrap(pipeline: object): object;
+    /**
+     * Start a new tracking session.
+     *
+     * @param {object} [metadata={}] - Arbitrary metadata to attach to the session.
+     * @returns {{id: string, startTime: number, metadata: object, entries: Array,
+     *            totalTokens: number, totalCost: number}}
+     */
+    startSession(metadata?: object): {
+        id: string;
+        startTime: number;
+        metadata: object;
+        entries: any[];
+        totalTokens: number;
+        totalCost: number;
+    };
+    /**
+     * End the current tracking session and compute totals.
+     *
+     * @returns {object|null} The closed session, or null if no session was active.
+     */
+    endSession(): object | null;
+    /**
+     * Return an aggregate summary across all sessions.
+     *
+     * @returns {{totalTokens: number, totalCost: number, sessionCount: number,
+     *            avgCostPerQuery: number, breakdown: Record<string, {tokens: number, cost: number, count: number}>}}
+     */
+    getSummary(): {
+        totalTokens: number;
+        totalCost: number;
+        sessionCount: number;
+        avgCostPerQuery: number;
+        breakdown: Record<string, {
+            tokens: number;
+            cost: number;
+            count: number;
+        }>;
+    };
+    /**
+     * Return the full history of tracked operations across all sessions.
+     *
+     * @returns {Array<{timestamp: number, inputTokens: number, outputTokens: number,
+     *                   cost: number, model: string, sessionId: string}>}
+     */
+    getHistory(): Array<{
+        timestamp: number;
+        inputTokens: number;
+        outputTokens: number;
+        cost: number;
+        model: string;
+        sessionId: string;
+    }>;
+}
+/**
+ * Default tracker configuration.
+ * @type {{model: string, embeddingModel: string, enableBudget: boolean, budgetOptions: object}}
+ */
+export const DEFAULT_CONFIG: {
+    model: string;
+    embeddingModel: string;
+    enableBudget: boolean;
+    budgetOptions: object;
+};
+import { EventEmitter } from "events";
+import { CostCalculator } from "./cost-calculator";
+import { TokenBudget } from "./token-budget";

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

@@ -0,0 +1,110 @@
+/**
+ * Configurable token and cost budgets with hard and soft limits.
+ *
+ * Emits:
+ * - `usage`    — after every {@link record} call with the recorded entry.
+ * - `warning`  — when usage crosses the soft limit threshold.
+ * - `exceeded` — when usage crosses a hard limit.
+ *
+ * @example
+ * const budget = new TokenBudget({ maxTokens: 100000, maxCost: 5.0 });
+ * budget.on('warning', (msg) => console.warn(msg));
+ * const status = budget.check(2000, 0.10);
+ * if (status.allowed) budget.record(2000, 0.10);
+ */
+export class TokenBudget extends EventEmitter<[never]> {
+    /**
+     * @param {object} [options]
+     * @param {number} [options.maxTokens=Infinity] - Hard token limit.
+     * @param {number} [options.maxCost=Infinity] - Hard cost limit (USD).
+     * @param {number} [options.softLimitPercent=0.8] - Fraction (0-1) at which soft-limit warnings fire.
+     * @param {number} [options.trackingWindow=0] - Sliding window in ms (0 disables).
+     */
+    constructor(options?: {
+        maxTokens?: number;
+        maxCost?: number;
+        softLimitPercent?: number;
+        trackingWindow?: number;
+    });
+    config: {
+        maxTokens: number;
+        maxCost: number;
+        softLimitPercent: number;
+        trackingWindow: number;
+    };
+    usage: {
+        tokens: number;
+        cost: number;
+        operations: number;
+        history: any[];
+    };
+    /**
+     * Prune history entries outside the sliding window.
+     * @private
+     */
+    private _pruneWindow;
+    /**
+     * Check whether a prospective usage fits within the budget.
+     *
+     * @param {number} [tokens=0] - Tokens about to be consumed.
+     * @param {number} [cost=0] - Cost about to be incurred.
+     * @returns {{allowed: boolean, reason?: string, remaining: {tokens: number, cost: number},
+     *            warnings: string[], usage: {tokens: number, cost: number, operations: number}}}
+     */
+    check(tokens?: number, cost?: number): {
+        allowed: boolean;
+        reason?: string;
+        remaining: {
+            tokens: number;
+            cost: number;
+        };
+        warnings: string[];
+        usage: {
+            tokens: number;
+            cost: number;
+            operations: number;
+        };
+    };
+    /**
+     * Record actual token and cost usage.
+     *
+     * @param {number} tokens - Tokens consumed.
+     * @param {number} [cost=0] - Cost incurred (USD).
+     */
+    record(tokens: number, cost?: number): void;
+    /**
+     * Reset all usage counters to zero.
+     */
+    reset(): void;
+    /**
+     * Return current usage summary.
+     *
+     * @returns {{tokens: number, cost: number, operations: number,
+     *            limits: {maxTokens: number, maxCost: number},
+     *            remaining: {tokens: number, cost: number}}}
+     */
+    getUsage(): {
+        tokens: number;
+        cost: number;
+        operations: number;
+        limits: {
+            maxTokens: number;
+            maxCost: number;
+        };
+        remaining: {
+            tokens: number;
+            cost: number;
+        };
+    };
+}
+/**
+ * Default budget configuration.
+ * @type {{maxTokens: number, maxCost: number, softLimitPercent: number, trackingWindow: number}}
+ */
+export const DEFAULT_CONFIG: {
+    maxTokens: number;
+    maxCost: number;
+    softLimitPercent: number;
+    trackingWindow: number;
+};
+import { EventEmitter } from "events";

package/dist/types/dag/core/error-context.d.ts

@@ -0,0 +1,239 @@
+export = ErrorContext;
+/**
+ * ErrorContext class for managing DAG execution errors
+ *
+ * Provides comprehensive error management with:
+ * - Rich error context creation with node metadata
+ * - Error aggregation for multiple failures
+ * - Property preservation across error transformations
+ * - Error serialization for logging and monitoring
+ * - Cycle path tracking and reporting
+ * - Downstream impact analysis
+ *
+ * @class
+ * @since 2.2.4
+ *
+ * @example
+ * const errorContext = new ErrorContext();
+ *
+ * // Create error with context
+ * const nodeError = errorContext.createErrorContext('nodeA', new Error('Failed'), {
+ *   downstream: ['nodeB', 'nodeC'],
+ *   timestamp: Date.now()
+ * });
+ *
+ * // Aggregate multiple errors
+ * const errorsMap = new Map([['nodeA', error1], ['nodeB', error2]]);
+ * const aggregated = errorContext.aggregateErrors(errorsMap);
+ *
+ * // Serialize for logging
+ * console.log(errorContext.serializeError(nodeError));
+ */
+declare class ErrorContext {
+    /**
+     * Create error context with node information and downstream impact
+     *
+     * Creates a new Error object enriched with:
+     * - Node ID for tracing execution path
+     * - Timestamp for temporal analysis
+     * - Original error as cause (for stack trace preservation)
+     * - Downstream node impact message
+     *
+     * @param {string} nodeId - ID of the node that failed
+     * @param {Error} error - Original error that occurred
+     * @param {Object} [options={}] - Additional context options
+     * @param {string[]} [options.downstream=[]] - Array of downstream node IDs affected
+     * @param {number} [options.timestamp=Date.now()] - Error timestamp
+     * @returns {Error} Enhanced error object with context
+     *
+     * @example
+     * const error = errorContext.createErrorContext(
+     *   'processData',
+     *   new Error('Invalid input'),
+     *   {
+     *     downstream: ['saveResults', 'sendNotification'],
+     *     timestamp: Date.now()
+     *   }
+     * );
+     * // Error message: "Node processData execution failed: Invalid input.
+     * //                 This affects downstream nodes: saveResults, sendNotification"
+     * // error.nodeId === 'processData'
+     * // error.cause === original Error object
+     *
+     * @since 2.2.4
+     */
+    createErrorContext(nodeId: string, error: Error, options?: {
+        downstream?: string[];
+        timestamp?: number;
+    }): Error;
+    /**
+     * Aggregate multiple errors into a single error object
+     *
+     * Creates a consolidated error when multiple nodes fail during execution.
+     * The aggregated error maintains references to all original errors for
+     * comprehensive debugging.
+     *
+     * @param {Map<string, Error>} errorsMap - Map of node ID to error object
+     * @returns {Error|null} Aggregated error, single error, or null if no errors
+     *
+     * @example
+     * const errors = new Map([
+     *   ['nodeA', new Error('A failed')],
+     *   ['nodeB', new Error('B failed')]
+     * ]);
+     * const aggregated = errorContext.aggregateErrors(errors);
+     * // aggregated.message === 'Multiple execution errors'
+     * // aggregated.errors === [Error('A failed'), Error('B failed')]
+     *
+     * @since 2.2.4
+     */
+    aggregateErrors(errorsMap: Map<string, Error>): Error | null;
+    /**
+     * Preserve node context when wrapping or transforming errors
+     *
+     * Ensures all error metadata (nodeId, timestamp, cause, cycle, errors)
+     * is preserved when creating wrapped errors. This is critical for
+     * maintaining debugging information through error propagation.
+     *
+     * @param {Error} error - Original error to preserve
+     * @param {Object} [context={}] - Additional context to add
+     * @returns {Error} New error with preserved properties
+     *
+     * @example
+     * const originalError = new Error('Original');
+     * originalError.nodeId = 'nodeA';
+     * originalError.timestamp = Date.now();
+     *
+     * const wrapped = errorContext.preserveNodeContext(originalError, {
+     *   retryCount: 3
+     * });
+     * // wrapped.nodeId === 'nodeA'
+     * // wrapped.timestamp === original timestamp
+     * // wrapped.retryCount === 3
+     *
+     * @since 2.2.4
+     */
+    preserveNodeContext(error: Error, context?: any): Error;
+    /**
+     * Format error report for debugging and monitoring
+     *
+     * Creates a structured representation of an error suitable for logging,
+     * monitoring systems, or debugging tools. Includes all metadata and
+     * nested error information.
+     *
+     * @param {Error} error - Error to format
+     * @returns {Object} Structured error report
+     *
+     * @example
+     * const report = errorContext.formatErrorReport(nodeError);
+     * // {
+     * //   message: "Node A execution failed: ...",
+     * //   nodeId: "A",
+     * //   timestamp: 1234567890,
+     * //   cause: { message: "...", stack: "..." },
+     * //   cycle: null,
+     * //   errors: null
+     * // }
+     *
+     * @since 2.2.4
+     */
+    formatErrorReport(error: Error): any;
+    /**
+     * Serialize error for logging and monitoring systems
+     *
+     * Converts error to JSON string with formatting for readability.
+     * Safe for logging systems that require string representation.
+     *
+     * @param {Error} error - Error to serialize
+     * @param {number} [indent=2] - JSON indentation spaces
+     * @returns {string} JSON string representation of error
+     *
+     * @example
+     * const json = errorContext.serializeError(nodeError);
+     * console.log(json);
+     * // {
+     * //   "message": "Node A execution failed: ...",
+     * //   "nodeId": "A",
+     * //   "timestamp": 1234567890,
+     * //   ...
+     * // }
+     *
+     * @since 2.2.4
+     */
+    serializeError(error: Error, indent?: number): string;
+    /**
+     * Wrap execution errors with appropriate context
+     *
+     * Implements error wrapping policy:
+     * - Node errors (with nodeId or starting with "Node ") are rethrown unchanged
+     * - Validation/cycle errors are wrapped once with "DAG execution failed"
+     * - Timeout and "no sink nodes" errors are not wrapped
+     * - All other errors are wrapped with "DAG execution failed"
+     *
+     * All error properties are preserved during wrapping.
+     *
+     * @param {Error} error - Error to wrap
+     * @returns {Error} Appropriately wrapped error
+     *
+     * @example
+     * const nodeError = new Error('Node A failed');
+     * nodeError.nodeId = 'A';
+     * const wrapped = errorContext.wrapExecutionError(nodeError);
+     * // Returns same error unchanged (node error policy)
+     *
+     * @example
+     * const validationError = new Error('DAG validation failed: cycle detected');
+     * validationError.cycle = ['A', 'B', 'A'];
+     * const wrapped = errorContext.wrapExecutionError(validationError);
+     * // Returns: Error('DAG execution failed: DAG validation failed: cycle detected')
+     * // with cycle property preserved
+     *
+     * @since 2.2.4
+     */
+    wrapExecutionError(error: Error): Error;
+    /**
+     * Create cycle error with path information
+     *
+     * Creates a specialized error for cycle detection with the cycle path
+     * embedded for debugging and error reporting.
+     *
+     * @param {string[]} cyclePath - Array of node IDs forming the cycle
+     * @returns {Error} Cycle error with path information
+     *
+     * @example
+     * const cycleError = errorContext.createCycleError(['A', 'B', 'C', 'A']);
+     * // cycleError.message === 'Cycle detected involving node: A -> B -> C -> A'
+     * // cycleError.cycle === ['A', 'B', 'C', 'A']
+     *
+     * @since 2.2.4
+     */
+    createCycleError(cyclePath: string[]): Error;
+    /**
+     * Check if error should halt execution
+     *
+     * Determines if an error is critical enough to stop DAG execution
+     * based on error type and execution options.
+     *
+     * @param {Error} error - Error to evaluate
+     * @param {Object} options - Execution options
+     * @param {boolean} [options.continueOnError=false] - Continue on non-critical errors
+     * @param {boolean} [options.isNonCritical=false] - Whether node is non-critical
+     * @returns {boolean} True if execution should halt
+     *
+     * @example
+     * const shouldHalt = errorContext.shouldHaltExecution(error, {
+     *   continueOnError: true,
+     *   isNonCritical: true
+     * });
+     * // Returns false - execution continues
+     *
+     * @since 2.2.4
+     */
+    shouldHaltExecution(error: Error, options?: {
+        continueOnError?: boolean;
+        isNonCritical?: boolean;
+    }): boolean;
+}
+declare namespace ErrorContext {
+    export { ErrorContext as default };
+}