@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

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

@@ -0,0 +1,127 @@
+export type DashboardGeneratorConfig = {
+    /**
+     * - Dashboard title (default: 'RAG Pipeline Dashboard')
+     */
+    title: string;
+    /**
+     * - Auto-refresh interval in ms (default: 5000)
+     */
+    refreshInterval: number;
+    /**
+     * - Color theme (default: 'dark')
+     */
+    theme: "dark" | "light";
+};
+/**
+ * Generates standalone HTML dashboards from pipeline metrics snapshots.
+ * @extends EventEmitter
+ */
+export class DashboardGenerator extends EventEmitter<[never]> {
+    /**
+     * @param {Partial<DashboardGeneratorConfig>} options
+     */
+    constructor(options?: Partial<DashboardGeneratorConfig>);
+    config: {
+        /**
+         * - Dashboard title (default: 'RAG Pipeline Dashboard')
+         */
+        title: string;
+        /**
+         * - Auto-refresh interval in ms (default: 5000)
+         */
+        refreshInterval: number;
+        /**
+         * - Color theme (default: 'dark')
+         */
+        theme: string;
+    };
+    /**
+     * Generate a complete standalone HTML dashboard page.
+     * @param {Object} metricsSnapshot - Snapshot from MetricsAggregator.getSnapshot()
+     * @returns {string} Complete HTML document string
+     */
+    generate(metricsSnapshot: any): string;
+    /**
+     * Generate a single metric card HTML snippet.
+     * @param {string} title - Card title
+     * @param {string} value - Primary display value
+     * @param {string} subtitle - Secondary info line
+     * @param {string} color - Accent color (CSS value)
+     * @returns {string} HTML string
+     */
+    _generateCard(title: string, value: string, subtitle: string, color: string): string;
+    /**
+     * Generate an inline SVG bar chart.
+     * @param {Array<{label: string, value: number}>} data - Chart data points
+     * @param {number} width - SVG width in pixels
+     * @param {number} height - SVG height in pixels
+     * @returns {string} SVG markup string
+     */
+    _generateBarChart(data: Array<{
+        label: string;
+        value: number;
+    }>, width: number, height: number): string;
+    /**
+     * Generate CSS styles for the specified theme.
+     * @param {'dark'|'light'} theme
+     * @returns {string} CSS string
+     */
+    _generateStyles(theme: "dark" | "light"): string;
+    /**
+     * Generate an HTML table for detailed metrics.
+     * @param {Array<{label: string, value: string|number, unit: string}>} rows
+     * @returns {string} HTML table string
+     */
+    _generateTable(rows: Array<{
+        label: string;
+        value: string | number;
+        unit: string;
+    }>): string;
+    /**
+     * Generate a plain-text summary report (for CLI/logs).
+     * @param {Object} metricsSnapshot - Snapshot from MetricsAggregator.getSnapshot()
+     * @returns {string} Formatted text report
+     */
+    generateReport(metricsSnapshot: any): string;
+    /**
+     * Return an empty metrics snapshot with zeroed values.
+     * @returns {Object}
+     * @private
+     */
+    private _emptySnapshot;
+    /**
+     * Escape HTML special characters.
+     * @param {string} str
+     * @returns {string}
+     * @private
+     */
+    private _escapeHtml;
+    /**
+     * Format a number with locale-aware separators.
+     * @param {number} n
+     * @returns {string}
+     * @private
+     */
+    private _formatNumber;
+    /**
+     * Format uptime duration to human-readable string.
+     * @param {number} ms - Uptime in milliseconds
+     * @returns {string}
+     * @private
+     */
+    private _formatUptime;
+    /**
+     * Right-align a value within a given width.
+     * @param {string|number} val
+     * @param {number} width
+     * @returns {string}
+     * @private
+     */
+    private _padLeft;
+}
+export namespace DEFAULT_CONFIG {
+    let title: string;
+    let refreshInterval: number;
+    let theme: string;
+}
+import { EventEmitter } from "events";

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

@@ -0,0 +1,218 @@
+export type MetricsAggregatorConfig = {
+    /**
+     * - Rolling window in seconds (default: 60)
+     */
+    windowSize: number;
+    /**
+     * - Milliseconds between samples (default: 1000)
+     */
+    sampleInterval: number;
+    /**
+     * - Maximum data points to keep (default: 3600)
+     */
+    maxHistory: number;
+};
+export type QueryData = {
+    /**
+     * - Duration in milliseconds
+     */
+    duration: number;
+    /**
+     * - Token count
+     */
+    tokens?: number;
+    /**
+     * - Cost in USD
+     */
+    cost?: number;
+    /**
+     * - Whether the operation succeeded
+     */
+    success?: boolean;
+    /**
+     * - Unix timestamp (defaults to Date.now())
+     */
+    timestamp?: number;
+};
+export type ErrorData = {
+    /**
+     * - Error message
+     */
+    message: string;
+    /**
+     * - Error code
+     */
+    code?: string;
+    /**
+     * - Error source component
+     */
+    source?: string;
+    /**
+     * - Unix timestamp
+     */
+    timestamp?: number;
+};
+/**
+ * @typedef {Object} QueryData
+ * @property {number} duration - Duration in milliseconds
+ * @property {number} [tokens] - Token count
+ * @property {number} [cost] - Cost in USD
+ * @property {boolean} [success] - Whether the operation succeeded
+ * @property {number} [timestamp] - Unix timestamp (defaults to Date.now())
+ */
+/**
+ * @typedef {Object} ErrorData
+ * @property {string} message - Error message
+ * @property {string} [code] - Error code
+ * @property {string} [source] - Error source component
+ * @property {number} [timestamp] - Unix timestamp
+ */
+/**
+ * Collects and aggregates pipeline metrics into dashboard-ready snapshots.
+ * @extends EventEmitter
+ */
+export class MetricsAggregator extends EventEmitter<[never]> {
+    /**
+     * @param {Partial<MetricsAggregatorConfig>} options
+     */
+    constructor(options?: Partial<MetricsAggregatorConfig>);
+    config: {
+        /**
+         * - Rolling window in seconds (default: 60)
+         */
+        windowSize: number;
+        /**
+         * - Milliseconds between samples (default: 1000)
+         */
+        sampleInterval: number;
+        /**
+         * - Maximum data points to keep (default: 3600)
+         */
+        maxHistory: number;
+    };
+    startTime: number;
+    /** @type {{ queries: number, embeddings: number, retrievals: number, generations: number, errors: number }} */
+    counters: {
+        queries: number;
+        embeddings: number;
+        retrievals: number;
+        generations: number;
+        errors: number;
+    };
+    /** @type {Array<{ value: number, timestamp: number }>} */
+    latencies: Array<{
+        value: number;
+        timestamp: number;
+    }>;
+    /** @type {Array<{ value: number, timestamp: number }>} */
+    costs: Array<{
+        value: number;
+        timestamp: number;
+    }>;
+    /** @type {Array<{ heapUsed: number, heapTotal: number, rss: number, timestamp: number }>} */
+    memory: Array<{
+        heapUsed: number;
+        heapTotal: number;
+        rss: number;
+        timestamp: number;
+    }>;
+    /** @type {Array<{ message: string, code: string, source: string, timestamp: number }>} */
+    errors: Array<{
+        message: string;
+        code: string;
+        source: string;
+        timestamp: number;
+    }>;
+    /** @type {Array<{ type: string, timestamp: number, duration: number }>} */
+    history: Array<{
+        type: string;
+        timestamp: number;
+        duration: number;
+    }>;
+    /**
+     * Record a query operation metric.
+     * @param {QueryData} data
+     */
+    recordQuery(data: QueryData): void;
+    /**
+     * Record an embedding operation metric.
+     * @param {QueryData} data
+     */
+    recordEmbedding(data: QueryData): void;
+    /**
+     * Record a retrieval operation metric.
+     * @param {QueryData} data
+     */
+    recordRetrieval(data: QueryData): void;
+    /**
+     * Record a generation operation metric.
+     * @param {QueryData} data
+     */
+    recordGeneration(data: QueryData): void;
+    /**
+     * Record an error event.
+     * @param {ErrorData} data
+     */
+    recordError(data: ErrorData): void;
+    /**
+     * Record a memory sample.
+     * @param {{ heapUsed?: number, heapTotal?: number, rss?: number }} [data]
+     */
+    recordMemory(data?: {
+        heapUsed?: number;
+        heapTotal?: number;
+        rss?: number;
+    }): void;
+    /**
+     * Return a complete dashboard snapshot of current metrics.
+     * @returns {Object} Dashboard-ready metrics snapshot
+     */
+    getSnapshot(): any;
+    /**
+     * Return time-bucketed data for charting a given metric.
+     * @param {'latency'|'throughput'|'cost'|'memory'|'errors'} metric
+     * @param {number} [windowSeconds] - Time window in seconds (defaults to config.windowSize)
+     * @returns {Array<{ bucket: number, value: number, label: string }>}
+     */
+    getTimeSeries(metric: "latency" | "throughput" | "cost" | "memory" | "errors", windowSeconds?: number): Array<{
+        bucket: number;
+        value: number;
+        label: string;
+    }>;
+    /**
+     * Reset all counters, history, and collected metrics.
+     */
+    reset(): void;
+    /**
+     * Record a generic pipeline operation.
+     * @param {string} type - Counter key (queries, embeddings, etc.)
+     * @param {QueryData} data
+     * @private
+     */
+    private _recordOperation;
+    /**
+     * Trim an array to maxHistory length, removing oldest entries.
+     * @param {Array} arr
+     * @private
+     */
+    private _trimArray;
+    /**
+     * Compute percentile statistics from a sorted array of values.
+     * @param {number[]} values
+     * @returns {{ avg: number, p50: number, p95: number, p99: number, min: number, max: number }}
+     * @private
+     */
+    private _computePercentiles;
+    /**
+     * Compute memory usage trend (positive = increasing, negative = decreasing).
+     * @returns {'increasing'|'decreasing'|'stable'}
+     * @private
+     */
+    private _computeMemoryTrend;
+}
+export namespace DEFAULT_CONFIG {
+    let windowSize: number;
+    let sampleInterval: number;
+    let maxHistory: number;
+}
+import { EventEmitter } from "events";

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

@@ -0,0 +1,57 @@
+/**
+ * Execution tracer that wraps pipelines to capture run traces
+ * @extends EventEmitter
+ */
+export class ExecutionTracer extends EventEmitter<[never]> {
+    /**
+     * Create a new ExecutionTracer
+     * @param {object} [options] - Tracer configuration
+     * @param {boolean} [options.captureInputs=true] - Whether to capture step inputs
+     * @param {boolean} [options.captureOutputs=true] - Whether to capture step outputs
+     * @param {number} [options.maxPayloadSize=10000] - Max characters before payload truncation
+     */
+    constructor(options?: {
+        captureInputs?: boolean;
+        captureOutputs?: boolean;
+        maxPayloadSize?: number;
+    });
+    config: {
+        captureInputs: boolean;
+        captureOutputs: boolean;
+        maxPayloadSize: number;
+    };
+    traces: any[];
+    /**
+     * Wrap a pipeline to record execution traces on each run
+     * @param {object} pipeline - Pipeline instance with a .run() method
+     * @returns {object} Wrapped pipeline with instrumented .run()
+     */
+    trace(pipeline: object): object;
+    /**
+     * Return all recorded traces
+     * @returns {Array<object>} Array of trace records
+     */
+    getTraces(): Array<object>;
+    /**
+     * Return a specific trace by ID
+     * @param {string} traceId - The trace ID to look up
+     * @returns {object|undefined} The trace record, or undefined if not found
+     */
+    getTrace(traceId: string): object | undefined;
+    /**
+     * Clear all recorded traces
+     */
+    clear(): void;
+    /**
+     * Export traces as a serialized string
+     * @param {string} [format='json'] - Export format (currently only 'json')
+     * @returns {string} Serialized traces
+     */
+    exportTraces(format?: string): string;
+}
+export namespace DEFAULT_CONFIG {
+    let captureInputs: boolean;
+    let captureOutputs: boolean;
+    let maxPayloadSize: number;
+}
+import { EventEmitter } from "events";

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

@@ -0,0 +1,31 @@
+/**
+ * Trace inspector that analyzes execution traces produced by ExecutionTracer
+ * @extends EventEmitter
+ */
+export class TraceInspector extends EventEmitter<[never]> {
+    /**
+     * Create a new TraceInspector
+     * @param {object} [options] - Inspector configuration
+     */
+    constructor(options?: object);
+    config: any;
+    /**
+     * Analyze a single trace for performance and quality insights
+     * @param {object} trace - Trace record from ExecutionTracer
+     * @returns {object} Analysis result with summary, breakdown, bottleneck, quality, and recommendations
+     */
+    analyze(trace: object): object;
+    /**
+     * Compare multiple traces for consistency and trends
+     * @param {Array<object>} traces - Array of trace records
+     * @returns {object} Comparison result with averages, ranges, and quality trend
+     */
+    compare(traces: Array<object>): object;
+    /**
+     * Find anomalous traces that deviate significantly from the norm
+     * @param {Array<object>} traces - Array of trace records
+     * @returns {Array<object>} Array of anomaly descriptors with traceId, anomalyType, details
+     */
+    findAnomalies(traces: Array<object>): Array<object>;
+}
+import { EventEmitter } from "events";

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

@@ -0,0 +1,169 @@
+export class PluginCertification extends EventEmitter<[never]> {
+    constructor(_options?: {});
+    _config: {
+        registryUrl: any;
+        apiKey: any;
+        fetch: any;
+        certificationLevels: {
+            BASIC: {
+                score: number;
+                automated: boolean;
+            };
+            VERIFIED: {
+                score: number;
+                manual: boolean;
+            };
+            ENTERPRISE: {
+                score: number;
+                manual: boolean;
+                audit: boolean;
+            };
+        };
+    };
+    validators: Map<any, any>;
+    /**
+     * Submit plugin for certification
+     */
+    submitForCertification(pluginId: any, level?: string): Promise<{
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        pluginId: any;
+        level: any;
+        score: any;
+        issuedAt: string;
+        expiresAt: string;
+        results: {
+            automated: any;
+            manual: any;
+            audit: any;
+        };
+        badge: any;
+        certificate: {
+            id: any;
+            pluginId: any;
+            level: any;
+            issuedAt: any;
+            issuer: string;
+            signature: string;
+            verificationUrl: string;
+        };
+    }>;
+    /**
+     * Verify plugin certification
+     */
+    verifyCertification(pluginId: any, certificationId: any): Promise<{
+        valid: any;
+        certification: any;
+        expiresAt: any;
+        verifiedAt: string;
+    }>;
+    /**
+     * Get certification requirements for a level
+     */
+    getCertificationRequirements(level: any): any;
+    /**
+     * Get publisher verification status
+     */
+    getPublisherStatus(publisherId: any): Promise<{
+        verified: any;
+        level: any;
+        badges: any;
+        certifiedPlugins: any;
+        reputation: any;
+        joinedAt: any;
+        lastActivity: any;
+    }>;
+    /**
+     * Apply for publisher verification
+     */
+    applyForPublisherVerification(publisherInfo: any): Promise<{
+        applicationId: `${string}-${string}-${string}-${string}-${string}`;
+        status: any;
+        estimatedReviewTime: any;
+        requirements: any;
+    }>;
+    _initializeValidators(): void;
+    _runAutomatedChecks(pluginId: any): Promise<{}>;
+    _calculateScore(results: any): number;
+    _submitForManualReview(pluginId: any, level: any, automatedResults: any): Promise<{
+        reviewId: any;
+        status: any;
+        estimatedCompletion: any;
+        reviewers: any;
+    }>;
+    _performSecurityAudit(pluginId: any): Promise<{
+        auditId: any;
+        status: any;
+        estimatedCompletion: any;
+        auditor: any;
+    }>;
+    _generateCertification(pluginId: any, level: any, results: any): Promise<{
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        pluginId: any;
+        level: any;
+        score: any;
+        issuedAt: string;
+        expiresAt: string;
+        results: {
+            automated: any;
+            manual: any;
+            audit: any;
+        };
+        badge: any;
+        certificate: {
+            id: any;
+            pluginId: any;
+            level: any;
+            issuedAt: any;
+            issuer: string;
+            signature: string;
+            verificationUrl: string;
+        };
+    }>;
+    _generateBadge(level: any, score: any): any;
+    _generateBadgeSVG(badge: any, score: any): string;
+    _generateCertificate(pluginId: any, level: any, certificationId: any, issuedAt: any): {
+        id: any;
+        pluginId: any;
+        level: any;
+        issuedAt: any;
+        issuer: string;
+        signature: string;
+        verificationUrl: string;
+    };
+    _generateSignature(certificationId: any, pluginId: any, level: any, issuedAt: any): string;
+    _analyzeCodeQuality(): Promise<{
+        overallScore: number;
+        details: {
+            complexity: string;
+            maintainability: string;
+            reliability: string;
+        };
+        issues: any[];
+    }>;
+    _scanSecurity(): Promise<{
+        securityScore: number;
+        vulnerabilities: any[];
+        recommendations: any[];
+    }>;
+    _benchmarkPerformance(): Promise<{
+        performanceScore: number;
+        metrics: {
+            avgResponseTime: string;
+            throughput: string;
+            memoryUsage: string;
+        };
+        bottlenecks: any[];
+    }>;
+    _analyzeDocumentation(): Promise<{
+        completenessScore: number;
+        coverage: number;
+        quality: string;
+    }>;
+    _analyzeTests(): Promise<{
+        testScore: number;
+        coverage: number;
+        testQuality: string;
+    }>;
+    _makeRequest(method: any, endpoint: any, data?: {}): Promise<any>;
+}
+import { EventEmitter } from "events";