@juspay/neurolink 3.0.1 → 4.1.0

package/dist/lib/utils/streaming-utils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Phase 2: Enhanced Streaming Infrastructure
+ * Streaming utilities for progress tracking and metadata enhancement
+ */
+import type { StreamingProgressData, StreamingMetadata, ProgressCallback, EnhancedStreamTextOptions } from "../core/types.js";
+export interface UIProgressHandler {
+    onProgress: (progress: StreamingProgressData) => void;
+    onComplete: (metadata: StreamingMetadata) => void;
+    onError: (error: Error) => void;
+}
+export interface StreamingStats {
+    totalChunks: number;
+    totalBytes: number;
+    duration: number;
+    averageChunkSize: number;
+    provider: string;
+    model: string;
+}
+/**
+ * Enhanced streaming utilities for progress tracking and metadata
+ */
+export declare class StreamingEnhancer {
+    /**
+     * Add progress tracking to a readable stream
+     */
+    static addProgressTracking(stream: ReadableStream, callback?: ProgressCallback, options?: {
+        streamId?: string;
+        bufferSize?: number;
+    }): ReadableStream;
+    /**
+     * Add metadata headers to streaming response
+     */
+    static addMetadataHeaders(response: Response, stats: StreamingStats): Response;
+    /**
+     * Create progress callback for UI integration
+     */
+    static createProgressCallback(ui: UIProgressHandler): ProgressCallback;
+    /**
+     * Estimate remaining time based on current progress
+     */
+    static estimateRemainingTime(totalBytes: number, elapsedTime: number, chunkCount: number): number | undefined;
+    /**
+     * Create enhanced streaming configuration
+     */
+    static createStreamingConfig(options: EnhancedStreamTextOptions): {
+        progressTracking: boolean;
+        callback?: ProgressCallback;
+        metadata: boolean;
+        bufferSize: number;
+        headers: boolean;
+    };
+}
+/**
+ * Streaming performance monitor for debugging and optimization
+ */
+export declare class StreamingMonitor {
+    private static activeStreams;
+    static registerStream(streamId: string): void;
+    static updateStream(streamId: string, progress: StreamingProgressData): void;
+    static completeStream(streamId: string): void;
+    static getActiveStreams(): StreamingProgressData[];
+    static getStreamStats(): {
+        activeCount: number;
+        totalBytesActive: number;
+        averageProgress: number;
+    };
+}

package/dist/lib/utils/streaming-utils.js

@@ -0,0 +1,201 @@
+/**
+ * Phase 2: Enhanced Streaming Infrastructure
+ * Streaming utilities for progress tracking and metadata enhancement
+ */
+/**
+ * Enhanced streaming utilities for progress tracking and metadata
+ */
+export class StreamingEnhancer {
+    /**
+     * Add progress tracking to a readable stream
+     */
+    static addProgressTracking(stream, callback, options) {
+        const streamId = options?.streamId || `stream_${Date.now()}`;
+        const startTime = Date.now();
+        let chunkCount = 0;
+        let totalBytes = 0;
+        let lastProgressTime = startTime;
+        return new ReadableStream({
+            start(controller) {
+                if (callback) {
+                    callback({
+                        chunkCount: 0,
+                        totalBytes: 0,
+                        chunkSize: 0,
+                        elapsedTime: 0,
+                        streamId,
+                        phase: "initializing",
+                    });
+                }
+            },
+            async pull(controller) {
+                const reader = stream.getReader();
+                try {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        controller.close();
+                        if (callback) {
+                            const elapsedTime = Date.now() - startTime;
+                            callback({
+                                chunkCount,
+                                totalBytes,
+                                chunkSize: totalBytes > 0 ? Math.round(totalBytes / chunkCount) : 0,
+                                elapsedTime,
+                                streamId,
+                                phase: "complete",
+                            });
+                        }
+                        return;
+                    }
+                    // Track progress
+                    chunkCount++;
+                    const chunkSize = value
+                        ? new TextEncoder().encode(value.toString()).length
+                        : 0;
+                    totalBytes += chunkSize;
+                    const currentTime = Date.now();
+                    const elapsedTime = currentTime - startTime;
+                    const timeSinceLastProgress = currentTime - lastProgressTime;
+                    // Call progress callback
+                    if (callback && (timeSinceLastProgress > 100 || chunkCount === 1)) {
+                        // Throttle to max 10 calls/second
+                        const estimatedRemaining = StreamingEnhancer.estimateRemainingTime(totalBytes, elapsedTime, chunkCount);
+                        callback({
+                            chunkCount,
+                            totalBytes,
+                            chunkSize,
+                            elapsedTime,
+                            estimatedRemaining,
+                            streamId,
+                            phase: "streaming",
+                        });
+                        lastProgressTime = currentTime;
+                    }
+                    controller.enqueue(value);
+                }
+                catch (error) {
+                    controller.error(error);
+                    if (callback) {
+                        callback({
+                            chunkCount,
+                            totalBytes,
+                            chunkSize: 0,
+                            elapsedTime: Date.now() - startTime,
+                            streamId,
+                            phase: "error",
+                        });
+                    }
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            },
+        });
+    }
+    /**
+     * Add metadata headers to streaming response
+     */
+    static addMetadataHeaders(response, stats) {
+        const headers = new Headers(response.headers);
+        headers.set("X-Streaming-Chunks", stats.totalChunks.toString());
+        headers.set("X-Streaming-Bytes", stats.totalBytes.toString());
+        headers.set("X-Streaming-Duration", stats.duration.toString());
+        headers.set("X-Streaming-Avg-Chunk-Size", stats.averageChunkSize.toString());
+        headers.set("X-Streaming-Provider", stats.provider);
+        headers.set("X-Streaming-Model", stats.model);
+        headers.set("X-Streaming-Throughput", Math.round(stats.totalBytes / (stats.duration / 1000)).toString());
+        return new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers,
+        });
+    }
+    /**
+     * Create progress callback for UI integration
+     */
+    static createProgressCallback(ui) {
+        return (progress) => {
+            try {
+                ui.onProgress(progress);
+                if (progress.phase === "complete") {
+                    ui.onComplete({
+                        startTime: Date.now() - progress.elapsedTime,
+                        endTime: Date.now(),
+                        totalDuration: progress.elapsedTime,
+                        averageChunkSize: Math.round(progress.totalBytes / progress.chunkCount),
+                        maxChunkSize: progress.chunkSize, // This would need to be tracked better in real implementation
+                        minChunkSize: progress.chunkSize, // This would need to be tracked better in real implementation
+                        throughputBytesPerSecond: Math.round(progress.totalBytes / (progress.elapsedTime / 1000)),
+                        streamingProvider: "unknown", // Would be passed from provider
+                        modelUsed: "unknown", // Would be passed from provider
+                    });
+                }
+            }
+            catch (error) {
+                ui.onError(error);
+            }
+        };
+    }
+    /**
+     * Estimate remaining time based on current progress
+     */
+    static estimateRemainingTime(totalBytes, elapsedTime, chunkCount) {
+        if (elapsedTime < 1000 || chunkCount < 3) {
+            return undefined; // Not enough data for estimation
+        }
+        const bytesPerMs = totalBytes / elapsedTime;
+        const avgChunkSize = totalBytes / chunkCount;
+        // Rough estimation assuming similar chunk sizes going forward
+        // This is a simple heuristic - real implementation might be more sophisticated
+        const estimatedTotalBytes = avgChunkSize * (chunkCount + 10); // Assume 10 more chunks
+        const remainingBytes = estimatedTotalBytes - totalBytes;
+        return Math.max(0, remainingBytes / bytesPerMs);
+    }
+    /**
+     * Create enhanced streaming configuration
+     */
+    static createStreamingConfig(options) {
+        return {
+            progressTracking: options.enableProgressTracking ?? false,
+            callback: options.progressCallback,
+            metadata: options.includeStreamingMetadata ?? false,
+            bufferSize: options.streamingBufferSize ?? 8192,
+            headers: options.enableStreamingHeaders ?? false,
+        };
+    }
+}
+/**
+ * Streaming performance monitor for debugging and optimization
+ */
+export class StreamingMonitor {
+    static activeStreams = new Map();
+    static registerStream(streamId) {
+        this.activeStreams.set(streamId, {
+            chunkCount: 0,
+            totalBytes: 0,
+            chunkSize: 0,
+            elapsedTime: 0,
+            streamId,
+            phase: "initializing",
+        });
+    }
+    static updateStream(streamId, progress) {
+        this.activeStreams.set(streamId, progress);
+    }
+    static completeStream(streamId) {
+        this.activeStreams.delete(streamId);
+    }
+    static getActiveStreams() {
+        return Array.from(this.activeStreams.values());
+    }
+    static getStreamStats() {
+        const streams = this.getActiveStreams();
+        return {
+            activeCount: streams.length,
+            totalBytesActive: streams.reduce((sum, s) => sum + s.totalBytes, 0),
+            averageProgress: streams.length > 0
+                ? streams.reduce((sum, s) => sum + s.elapsedTime, 0) / streams.length
+                : 0,
+        };
+    }
+}

package/dist/mcp/contracts/mcpContract.d.ts

@@ -0,0 +1,118 @@
+/**
+ * MCP Contract - Core Type Definitions
+ * Industry standard camelCase interfaces for maximum flexibility
+ */
+/**
+ * Generic execution context for MCP operations
+ * All properties optional for maximum flexibility
+ */
+export interface ExecutionContext<T = Record<string, unknown>> {
+    sessionId?: string;
+    userId?: string;
+    config?: T;
+    metadata?: Record<string, unknown>;
+    cacheOptions?: CacheOptions;
+    fallbackOptions?: FallbackOptions;
+    timeoutMs?: number;
+    startTime?: number;
+}
+/**
+ * Cache configuration options
+ */
+export interface CacheOptions {
+    enabled?: boolean;
+    ttlMs?: number;
+    strategy?: "memory" | "writeThrough" | "cacheAside";
+}
+/**
+ * Fallback configuration options
+ */
+export interface FallbackOptions {
+    enabled?: boolean;
+    maxAttempts?: number;
+    delayMs?: number;
+    circuitBreaker?: boolean;
+}
+/**
+ * Tool information with extensibility
+ */
+export interface ToolInfo {
+    name: string;
+    description?: string;
+    category?: string;
+    serverId?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Discovered MCP server/plugin definition
+ */
+export interface DiscoveredMcp<TTools = Record<string, unknown>> {
+    metadata: McpMetadata;
+    tools?: TTools;
+    capabilities?: string[];
+    version?: string;
+    configuration?: Record<string, string | number | boolean>;
+    [key: string]: unknown;
+}
+/**
+ * MCP server metadata
+ */
+export interface McpMetadata {
+    name: string;
+    description?: string;
+    version?: string;
+    author?: string;
+    homepage?: string;
+    repository?: string;
+}
+/**
+ * Tool definition schema
+ */
+export interface ToolDefinition {
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    category?: string;
+    examples?: Array<{
+        input: Record<string, unknown>;
+        output: Record<string, unknown>;
+        description?: string;
+    }>;
+}
+/**
+ * Tool execution result
+ */
+export interface ToolExecutionResult<T = unknown> {
+    result: T;
+    context?: ExecutionContext;
+    performance?: {
+        duration: number;
+        tokensUsed?: number;
+        cost?: number;
+    };
+    validation?: ValidationResult;
+    cached?: boolean;
+    fallback?: boolean;
+}
+/**
+ * Validation result for runtime checks
+ */
+export interface ValidationResult {
+    valid: boolean;
+    missing: string[];
+    warnings: string[];
+    recommendations: string[];
+}
+/**
+ * Provider status information
+ */
+export interface ProviderStatus {
+    available: boolean;
+    lastCheck: number;
+    reason?: string;
+    model?: string;
+    cost?: number;
+    latencyMs?: number;
+}

package/dist/mcp/contracts/mcpContract.js

@@ -0,0 +1,5 @@
+/**
+ * MCP Contract - Core Type Definitions
+ * Industry standard camelCase interfaces for maximum flexibility
+ */
+export {};

package/dist/mcp/dynamic-chain-executor.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Dynamic AI Tool Chain Executor
+ * Allows AI to dynamically decide tool execution sequences based on context and results
+ */
+import type { MCPOrchestrator } from "./orchestrator.js";
+import type { MCPRegistry } from "./registry.js";
+import type { NeuroLinkExecutionContext } from "./factory.js";
+import { ErrorManager } from "./error-manager.js";
+/**
+ * Tool execution result with metadata
+ */
+export interface ToolExecutionResult {
+    toolName: string;
+    success: boolean;
+    result?: any;
+    error?: Error;
+    timestamp: number;
+    executionTime: number;
+    context?: Record<string, any>;
+}
+/**
+ * Chain execution step
+ */
+export interface ChainStep {
+    stepId: string;
+    toolName: string;
+    parameters: any;
+    reasoning: string;
+    confidence: number;
+    expectedOutcome: string;
+}
+/**
+ * Chain execution context
+ */
+export interface ChainExecutionContext {
+    goal: string;
+    currentStep: number;
+    totalSteps?: number;
+    executionHistory: ToolExecutionResult[];
+    accumulatedContext: Record<string, any>;
+    userContext?: NeuroLinkExecutionContext;
+    maxSteps: number;
+    aiModel?: string;
+}
+/**
+ * Chain execution result
+ */
+export interface ChainExecutionResult {
+    success: boolean;
+    goal: string;
+    totalSteps: number;
+    executionTime: number;
+    results: ToolExecutionResult[];
+    finalResult?: any;
+    reasoning: string;
+    error?: Error;
+    metadata: {
+        toolsUsed: string[];
+        averageConfidence: number;
+        contextEvolution: Record<string, any>[];
+    };
+}
+/**
+ * AI Tool Chain Planner interface
+ */
+export interface AIChainPlanner {
+    name: string;
+    planNextStep(goal: string, availableTools: Array<{
+        name: string;
+        description: string;
+        inputSchema: any;
+    }>, executionHistory: ToolExecutionResult[], accumulatedContext: Record<string, any>): Promise<ChainStep | null>;
+    evaluateResult(step: ChainStep, result: ToolExecutionResult, goal: string): Promise<{
+        goalAchieved: boolean;
+        confidence: number;
+        nextAction: "continue" | "retry" | "abort" | "complete";
+        reasoning: string;
+    }>;
+}
+/**
+ * Simple AI Chain Planner using heuristics
+ */
+export declare class HeuristicChainPlanner implements AIChainPlanner {
+    name: string;
+    planNextStep(goal: string, availableTools: Array<{
+        name: string;
+        description: string;
+        inputSchema: any;
+    }>, executionHistory: ToolExecutionResult[], accumulatedContext: Record<string, any>): Promise<ChainStep | null>;
+    evaluateResult(step: ChainStep, result: ToolExecutionResult, goal: string): Promise<{
+        goalAchieved: boolean;
+        confidence: number;
+        nextAction: "continue" | "retry" | "abort" | "complete";
+        reasoning: string;
+    }>;
+    private generateParameters;
+}
+/**
+ * Advanced AI Chain Planner using actual AI model
+ */
+export declare class AIModelChainPlanner implements AIChainPlanner {
+    name: string;
+    private aiModel;
+    constructor(aiModel?: string);
+    planNextStep(goal: string, availableTools: Array<{
+        name: string;
+        description: string;
+        inputSchema: any;
+    }>, executionHistory: ToolExecutionResult[], accumulatedContext: Record<string, any>): Promise<ChainStep | null>;
+    evaluateResult(step: ChainStep, result: ToolExecutionResult, goal: string): Promise<{
+        goalAchieved: boolean;
+        confidence: number;
+        nextAction: "continue" | "retry" | "abort" | "complete";
+        reasoning: string;
+    }>;
+    private buildPlanningPrompt;
+    private buildEvaluationPrompt;
+    private callAIModel;
+    private parseAIResponse;
+    private parseEvaluationResponse;
+}
+/**
+ * Dynamic Chain Executor
+ */
+export declare class DynamicChainExecutor {
+    private orchestrator;
+    private registry;
+    private errorManager;
+    private planner;
+    constructor(orchestrator: MCPOrchestrator, registry: MCPRegistry, errorManager: ErrorManager, planner?: AIChainPlanner);
+    /**
+     * Execute dynamic tool chain to achieve a goal
+     *
+     * @param goal The goal to achieve
+     * @param initialContext Initial context data
+     * @param userContext User execution context
+     * @param options Execution options
+     * @returns Chain execution result
+     */
+    executeChain(goal: string, initialContext?: Record<string, any>, userContext?: NeuroLinkExecutionContext, options?: {
+        maxSteps?: number;
+        aiModel?: string;
+        timeout?: number;
+    }): Promise<ChainExecutionResult>;
+    /**
+     * Execute chain steps iteratively
+     *
+     * @private
+     */
+    private executeChainSteps;
+    /**
+     * Execute a single step
+     *
+     * @private
+     */
+    private executeStep;
+    /**
+     * Update accumulated context with new result
+     *
+     * @private
+     */
+    private updateAccumulatedContext;
+    /**
+     * Calculate average confidence across execution history
+     *
+     * @private
+     */
+    private calculateAverageConfidence;
+    /**
+     * Track context evolution through execution
+     *
+     * @private
+     */
+    private trackContextEvolution;
+    /**
+     * Set AI planner
+     *
+     * @param planner AI chain planner instance
+     */
+    setPlanner(planner: AIChainPlanner): void;
+    /**
+     * Get current planner
+     *
+     * @returns Current AI chain planner
+     */
+    getPlanner(): AIChainPlanner;
+}
+/**
+ * Default dynamic chain executor instance
+ */
+export declare let defaultDynamicChainExecutor: DynamicChainExecutor | null;
+/**
+ * Initialize default dynamic chain executor
+ *
+ * @param orchestrator MCP orchestrator
+ * @param registry Tool registry
+ * @param errorManager Error manager
+ * @param planner Optional AI planner
+ * @returns Dynamic chain executor instance
+ */
+export declare function initializeDynamicChainExecutor(orchestrator: MCPOrchestrator, registry: MCPRegistry, errorManager: ErrorManager, planner?: AIChainPlanner): DynamicChainExecutor;