@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/workflow/workflows/fallbackWorkflow.js

@@ -0,0 +1,225 @@
+/**
+ * Fallback Workflow
+ * =================
+ *
+ * Sequential fallback chain using layer-based execution:
+ * - Try fast model first
+ * - Fall back to mid-tier if needed
+ * - Final fallback to premium model
+ *
+ * Ideal for: Cost-optimization with quality guarantee
+ *
+ * @module workflow/workflows/fallbackWorkflow
+ */
+import { AIProviderName } from "../../constants/enums.js";
+import { WORKFLOW_CREATION_DATE } from "../config.js";
+/**
+ * Fast-Fallback Workflow Configuration
+ *
+ * Uses layer-based execution with sequential groups:
+ * 1. Fast tier: GPT-4o-mini (try first)
+ * 2. Mid tier: Gemini 2.0 Flash (if fast fails)
+ * 3. Premium tier: GPT-4o or Claude 3.5 Sonnet (last resort)
+ *
+ * Each group runs sequentially - only proceeds if previous fails
+ *
+ * @example
+ * ```typescript
+ * import { runWorkflow } from '../core/workflowRunner.js';
+ * import { FAST_FALLBACK_WORKFLOW } from './fallbackWorkflow.js';
+ *
+ * const result = await runWorkflow(FAST_FALLBACK_WORKFLOW, {
+ *   prompt: 'What is 2+2?',
+ *   verbose: true,
+ * });
+ *
+ * // Usually completes with fast tier, saving cost
+ * console.log('Executed models:', result.ensembleResponses.length);
+ * ```
+ */
+export const FAST_FALLBACK_WORKFLOW = {
+    id: "fast-fallback",
+    name: "Fast-Fallback Chain",
+    description: "Sequential fallback: fast → mid → premium",
+    version: "1.0.0",
+    type: "chain",
+    // Placeholder (required by schema, but modelGroups takes precedence)
+    models: [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o-mini",
+        },
+    ],
+    // Layer-based execution: groups run sequentially
+    modelGroups: [
+        {
+            id: "fast-tier",
+            name: "Fast Tier",
+            description: "Try fast model first (lowest cost)",
+            models: [
+                {
+                    provider: AIProviderName.OPENAI,
+                    model: "gpt-4o-mini",
+                    label: "GPT-4o-mini",
+                    temperature: 0.7,
+                    timeout: 10000, // 10 second timeout
+                },
+            ],
+            executionStrategy: "sequential", // Only one model
+            continueOnFailure: true, // Always try next tier
+            minSuccessful: 1,
+        },
+        {
+            id: "mid-tier",
+            name: "Mid Tier",
+            description: "Mid-tier model (balanced cost/quality)",
+            models: [
+                {
+                    provider: AIProviderName.GOOGLE_AI,
+                    model: "gemini-2.0-flash",
+                    label: "Gemini 2.0 Flash",
+                    temperature: 0.7,
+                    timeout: 15000, // 15 second timeout
+                },
+            ],
+            executionStrategy: "sequential",
+            continueOnFailure: true,
+            minSuccessful: 1,
+        },
+        {
+            id: "premium-tier",
+            name: "Premium Tier",
+            description: "Premium models (last resort, highest quality)",
+            models: [
+                {
+                    provider: AIProviderName.OPENAI,
+                    model: "gpt-4o",
+                    label: "GPT-4o",
+                    temperature: 0.7,
+                    timeout: 20000, // 20 second timeout
+                },
+            ],
+            executionStrategy: "sequential",
+            continueOnFailure: false, // Stop if this fails
+            minSuccessful: 1,
+        },
+    ],
+    // Judge: Select best response if multiple tiers executed
+    judge: {
+        provider: AIProviderName.OPENAI,
+        model: "gpt-4o-mini", // Fast judge is fine for simple selection
+        criteria: ["quality", "response_time"],
+        outputFormat: "best",
+        includeReasoning: true,
+        temperature: 0.1,
+        scoreScale: {
+            min: 0,
+            max: 100,
+        },
+    },
+    // Execution configuration
+    execution: {
+        timeout: 50000, // 50 second total timeout
+        minResponses: 1, // Only need 1 successful response
+        costThreshold: 0.05,
+    },
+    // Metadata
+    tags: ["chain", "fallback", "cost-optimized", "reliable"],
+    metadata: {
+        useCase: "Cost-optimized with quality guarantee",
+        recommendedFor: [
+            "variable complexity queries",
+            "cost-sensitive applications",
+        ],
+        averageCost: 0.01, // Usually completes in fast tier
+        averageLatency: 2000,
+    },
+    createdAt: WORKFLOW_CREATION_DATE,
+};
+/**
+ * Aggressive Fallback Workflow
+ *
+ * More aggressive fallback with parallel premium tier:
+ * 1. Fast tier: GPT-4o-mini (sequential)
+ * 2. Premium tier: GPT-4o + Claude 3.5 (parallel, both execute)
+ *
+ * Guarantees high quality if fast tier fails
+ */
+export const AGGRESSIVE_FALLBACK_WORKFLOW = {
+    id: "aggressive-fallback",
+    name: "Aggressive Fallback",
+    description: "Fast first, then both premium models in parallel",
+    version: "1.0.0",
+    type: "chain",
+    models: [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o-mini",
+        },
+    ],
+    modelGroups: [
+        {
+            id: "fast-tier",
+            name: "Fast Tier",
+            models: [
+                {
+                    provider: AIProviderName.OPENAI,
+                    model: "gpt-4o-mini",
+                    temperature: 0.7,
+                    timeout: 8000,
+                },
+            ],
+            executionStrategy: "sequential",
+            continueOnFailure: true,
+            minSuccessful: 1,
+        },
+        {
+            id: "premium-tier",
+            name: "Premium Tier (Both)",
+            description: "Run both premium models in parallel for guaranteed quality",
+            models: [
+                {
+                    provider: AIProviderName.OPENAI,
+                    model: "gpt-4o",
+                    label: "GPT-4o",
+                    temperature: 0.7,
+                },
+                {
+                    provider: AIProviderName.ANTHROPIC,
+                    model: "claude-3-5-sonnet-20241022",
+                    label: "Claude 3.5 Sonnet",
+                    temperature: 0.7,
+                },
+            ],
+            executionStrategy: "parallel", // Both run simultaneously
+            continueOnFailure: false,
+            minSuccessful: 1,
+            parallelism: 2,
+        },
+    ],
+    judge: {
+        provider: AIProviderName.OPENAI,
+        model: "gpt-4o",
+        criteria: ["quality", "completeness"],
+        outputFormat: "detailed",
+        includeReasoning: true,
+        temperature: 0.1,
+        scoreScale: {
+            min: 0,
+            max: 100,
+        },
+    },
+    execution: {
+        timeout: 40000,
+        minResponses: 1,
+        costThreshold: 0.08,
+    },
+    tags: ["chain", "fallback", "high-quality", "reliable"],
+    metadata: {
+        useCase: "High quality guarantee with cost optimization attempt",
+        recommendedFor: ["important queries", "when quality matters most"],
+        averageCost: 0.03,
+        averageLatency: 2500,
+    },
+    createdAt: WORKFLOW_CREATION_DATE,
+};

package/dist/client/workflow/workflows/multiJudgeWorkflow.js

@@ -0,0 +1,351 @@
+/**
+ * Multi-Judge Workflow
+ * ====================
+ *
+ * 5-model ensemble with 3-judge voting for maximum reliability:
+ * - 5 diverse models generate responses
+ * - 3 judges independently evaluate (voting consensus)
+ * - Best response selected by aggregate scoring
+ *
+ * Ideal for: Critical decisions requiring high confidence
+ *
+ * @module workflow/workflows/multiJudgeWorkflow
+ */
+import { AIProviderName } from "../../constants/enums.js";
+import { WORKFLOW_CREATION_DATE } from "../config.js";
+/**
+ * Multi-Judge-5 Workflow Configuration
+ *
+ * Uses 5 models across different providers:
+ * - GPT-4o (OpenAI)
+ * - GPT-4o-mini (OpenAI)
+ * - Claude 3.5 Sonnet (Anthropic)
+ * - Claude 3 Haiku (Anthropic)
+ * - Gemini 2.0 Flash (Google)
+ *
+ * 3 independent judges vote:
+ * - GPT-4o evaluates accuracy & clarity
+ * - Claude 3.5 Sonnet evaluates reasoning & depth
+ * - Gemini 2.0 Flash evaluates completeness & coherence
+ *
+ * Scores are averaged across all judges for final selection
+ *
+ * @example
+ * ```typescript
+ * import { runWorkflow } from '../core/workflowRunner.js';
+ * import { MULTI_JUDGE_5_WORKFLOW } from './multiJudgeWorkflow.js';
+ *
+ * const result = await runWorkflow(MULTI_JUDGE_5_WORKFLOW, {
+ *   prompt: 'Should we invest in renewable energy?',
+ *   verbose: true,
+ * });
+ *
+ * console.log('Consensus score:', result.score);
+ * console.log('Agreement level:', result.consensus);
+ * ```
+ */
+export const MULTI_JUDGE_5_WORKFLOW = {
+    id: "multi-judge-5",
+    name: "Multi-Judge-5 Ensemble",
+    description: "5-model ensemble with 3-judge voting for high confidence",
+    version: "1.0.0",
+    type: "ensemble",
+    // 5 diverse models for comprehensive coverage
+    models: [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o",
+            label: "GPT-4o",
+            weight: 1.0,
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o-mini",
+            label: "GPT-4o-mini",
+            weight: 0.8, // Slightly lower weight
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.ANTHROPIC,
+            model: "claude-3-5-sonnet-20241022",
+            label: "Claude 3.5 Sonnet",
+            weight: 1.0,
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.ANTHROPIC,
+            model: "claude-3-haiku-20240307",
+            label: "Claude 3 Haiku",
+            weight: 0.7, // Lower weight for faster model
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.GOOGLE_AI,
+            model: "gemini-2.0-flash",
+            label: "Gemini 2 Flash",
+            weight: 0.9,
+            temperature: 0.7,
+        },
+    ],
+    // 3 independent judges with different criteria focus
+    judges: [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o",
+            criteria: ["accuracy", "clarity", "factual_correctness"],
+            outputFormat: "detailed",
+            includeReasoning: true,
+            temperature: 0.1,
+            scoreScale: { min: 0, max: 100 },
+            label: "Accuracy Judge",
+        },
+        {
+            provider: AIProviderName.ANTHROPIC,
+            model: "claude-3-5-sonnet-20241022",
+            criteria: ["reasoning_quality", "depth", "nuance"],
+            outputFormat: "detailed",
+            includeReasoning: true,
+            temperature: 0.1,
+            scoreScale: { min: 0, max: 100 },
+            label: "Reasoning Judge",
+        },
+        {
+            provider: AIProviderName.GOOGLE_AI,
+            model: "gemini-2.0-flash",
+            criteria: ["completeness", "coherence", "relevance"],
+            outputFormat: "detailed",
+            includeReasoning: true,
+            temperature: 0.1,
+            scoreScale: { min: 0, max: 100 },
+            label: "Completeness Judge",
+        },
+    ],
+    // Execution configuration
+    execution: {
+        parallelism: 5, // All 5 models run simultaneously
+        timeout: 45000, // 45 second total timeout
+        modelTimeout: 30000, // 30 second per-model timeout
+        minResponses: 3, // Need at least 3 successful responses
+        costThreshold: 0.15, // Warn if cost exceeds $0.15
+    },
+    // Metadata
+    tags: ["ensemble", "multi-judge", "voting", "high-confidence", "critical"],
+    metadata: {
+        useCase: "Critical decisions requiring high confidence",
+        recommendedFor: [
+            "important business decisions",
+            "technical evaluations",
+            "complex analysis",
+            "fact-checking",
+        ],
+        averageCost: 0.1,
+        averageLatency: 5000,
+        consensusThreshold: 0.7, // Expect 70%+ agreement
+    },
+    createdAt: WORKFLOW_CREATION_DATE,
+};
+/**
+ * Multi-Judge-3 Workflow (Lighter Version)
+ *
+ * 3 models with 2 judges (more cost-effective):
+ * - GPT-4o, Claude 3.5, Gemini 2.0
+ * - Judged by GPT-4o and Claude 3.5
+ */
+export const MULTI_JUDGE_3_WORKFLOW = {
+    id: "multi-judge-3",
+    name: "Multi-Judge-3 Ensemble",
+    description: "3-model ensemble with 2-judge voting",
+    version: "1.0.0",
+    type: "ensemble",
+    models: [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o",
+            label: "GPT-4o",
+            weight: 1.0,
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.ANTHROPIC,
+            model: "claude-3-5-sonnet-20241022",
+            label: "Claude 3.5 Sonnet",
+            weight: 1.0,
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.GOOGLE_AI,
+            model: "gemini-2.0-flash",
+            label: "Gemini 2.0 Flash",
+            weight: 1.0,
+            temperature: 0.7,
+        },
+    ],
+    judges: [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o",
+            criteria: ["accuracy", "clarity", "completeness"],
+            outputFormat: "detailed",
+            includeReasoning: true,
+            temperature: 0.1,
+            scoreScale: { min: 0, max: 100 },
+            label: "Primary Judge",
+        },
+        {
+            provider: AIProviderName.ANTHROPIC,
+            model: "claude-3-5-sonnet-20241022",
+            criteria: ["reasoning", "depth", "coherence"],
+            outputFormat: "detailed",
+            includeReasoning: true,
+            temperature: 0.1,
+            scoreScale: { min: 0, max: 100 },
+            label: "Secondary Judge",
+        },
+    ],
+    execution: {
+        parallelism: 3,
+        timeout: 35000,
+        modelTimeout: 25000,
+        minResponses: 2,
+        costThreshold: 0.08,
+    },
+    tags: ["ensemble", "multi-judge", "voting", "balanced"],
+    metadata: {
+        useCase: "Balanced multi-judge evaluation",
+        recommendedFor: ["important queries", "quality verification"],
+        averageCost: 0.04,
+        averageLatency: 3500,
+    },
+    createdAt: WORKFLOW_CREATION_DATE,
+};
+/**
+ * Create custom multi-judge workflow
+ *
+ * @param modelCount - Number of models (3, 5, or 7)
+ * @param judgeCount - Number of judges (2 or 3)
+ * @returns Configured workflow
+ *
+ * @example
+ * ```typescript
+ * const workflow = createMultiJudgeWorkflow(7, 3);
+ * const result = await runWorkflow(workflow, {
+ *   prompt: 'Complex analysis task',
+ * });
+ * ```
+ */
+export function createMultiJudgeWorkflow(modelCount, judgeCount) {
+    // Base models (always include these)
+    const baseModels = [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o",
+            label: "GPT-4o",
+            weight: 1.0,
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.ANTHROPIC,
+            model: "claude-3-5-sonnet-20241022",
+            label: "Claude 3.5 Sonnet",
+            weight: 1.0,
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.GOOGLE_AI,
+            model: "gemini-2.0-flash",
+            label: "Gemini 2.0 Flash",
+            weight: 1.0,
+            temperature: 0.7,
+        },
+    ];
+    // Additional models for larger ensembles
+    const additionalModels = [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o-mini",
+            label: "GPT-4o-mini",
+            weight: 0.8,
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.ANTHROPIC,
+            model: "claude-3-haiku-20240307",
+            label: "Claude 3 Haiku",
+            weight: 0.7,
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.GOOGLE_AI,
+            model: "gemini-1.5-flash",
+            label: "Gemini 1.5 Flash",
+            weight: 0.8,
+            temperature: 0.7,
+        },
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-3.5-turbo",
+            label: "GPT-3.5 Turbo",
+            weight: 0.6,
+            temperature: 0.7,
+        },
+    ];
+    const models = [...baseModels, ...additionalModels.slice(0, modelCount - 3)];
+    // Base judges
+    const baseJudges = [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o",
+            criteria: ["accuracy", "clarity", "completeness"],
+            outputFormat: "detailed",
+            includeReasoning: true,
+            temperature: 0.1,
+            scoreScale: { min: 0, max: 100 },
+            label: "Primary Judge",
+        },
+        {
+            provider: AIProviderName.ANTHROPIC,
+            model: "claude-3-5-sonnet-20241022",
+            criteria: ["reasoning", "depth", "coherence"],
+            outputFormat: "detailed",
+            includeReasoning: true,
+            temperature: 0.1,
+            scoreScale: { min: 0, max: 100 },
+            label: "Secondary Judge",
+        },
+    ];
+    const thirdJudge = {
+        provider: AIProviderName.GOOGLE_AI,
+        model: "gemini-2.0-flash",
+        criteria: ["relevance", "factual_accuracy", "structure"],
+        outputFormat: "detailed",
+        includeReasoning: true,
+        temperature: 0.1,
+        scoreScale: { min: 0, max: 100 },
+        label: "Tertiary Judge",
+    };
+    const judges = judgeCount === 3 ? [...baseJudges, thirdJudge] : baseJudges;
+    return {
+        id: `multi-judge-${modelCount}-${judgeCount}`,
+        name: `Multi-Judge ${modelCount}x${judgeCount}`,
+        description: `${modelCount}-model ensemble with ${judgeCount}-judge voting`,
+        version: "1.0.0",
+        type: "ensemble",
+        models,
+        judges,
+        execution: {
+            parallelism: modelCount,
+            timeout: 45000,
+            modelTimeout: 30000,
+            minResponses: Math.ceil(modelCount / 2),
+            costThreshold: 0.2,
+        },
+        tags: ["ensemble", "multi-judge", "custom"],
+        metadata: {
+            useCase: "Custom multi-judge evaluation",
+            modelCount,
+            judgeCount,
+        },
+        createdAt: WORKFLOW_CREATION_DATE,
+    };
+}

package/dist/client/wsClient.d.ts

@@ -0,0 +1,130 @@
+/**
+ * WebSocket Client for NeuroLink SDK
+ *
+ * Provides a dedicated WebSocket client for real-time streaming connections
+ * to NeuroLink servers. Supports bidirectional communication, automatic
+ * reconnection, and message queuing.
+ *
+ * @module @neurolink/client/wsClient
+ */
+import type { StreamCallbacks, StreamEvent, StreamResult, ApiError, WSClientState, WSClientConfig, WSClientMessage, WSClientEventHandlers } from "../types/clientTypes.js";
+/** @see WSClientState */
+export type WebSocketState = WSClientState;
+/** @see WSClientConfig */
+export type WebSocketConfig = WSClientConfig;
+/** @see WSClientMessage */
+export type WebSocketMessage = WSClientMessage;
+/** @see WSClientEventHandlers */
+export type WebSocketEventHandlers = WSClientEventHandlers;
+/**
+ * WebSocket streaming client for NeuroLink
+ *
+ * Provides real-time bidirectional communication with NeuroLink servers.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const wsClient = new NeuroLinkWebSocket({
+ *   baseUrl: 'wss://api.neurolink.example.com/ws',
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * wsClient.connect({
+ *   onMessage: (event) => console.log('Received:', event),
+ *   onError: (error) => console.error('Error:', error),
+ * });
+ *
+ * // Send a message
+ * wsClient.send({
+ *   type: 'message',
+ *   channel: 'chat',
+ *   payload: { prompt: 'Hello!' },
+ * });
+ * ```
+ */
+export declare class NeuroLinkWebSocket {
+    private ws;
+    private config;
+    private state;
+    private reconnectAttempts;
+    private heartbeatTimer;
+    private messageQueue;
+    private eventHandlers;
+    private subscriptions;
+    private pendingAuth;
+    /**
+     * Local flag to suppress reconnection during an explicit disconnect().
+     * Unlike mutating config.autoReconnect, this preserves the user's
+     * original configuration so that a subsequent connect() still honours it.
+     */
+    private disconnectRequested;
+    constructor(config: WebSocketConfig);
+    /**
+     * Get current connection state
+     */
+    getState(): WebSocketState;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Connect to WebSocket server
+     */
+    connect(handlers?: WebSocketEventHandlers): void;
+    /**
+     * Disconnect from WebSocket server
+     *
+     * Sets a local flag to prevent the onclose handler from triggering
+     * reconnection, without mutating the shared config.
+     */
+    disconnect(): void;
+    /**
+     * Send a message through WebSocket
+     */
+    send(message: WebSocketMessage): void;
+    /**
+     * Subscribe to a channel with streaming callbacks
+     */
+    subscribe(channel: string, callbacks: StreamCallbacks): void;
+    /**
+     * Unsubscribe from a channel
+     */
+    unsubscribe(channel: string): void;
+    /**
+     * Stream a prompt with callbacks
+     */
+    stream(prompt: string, options?: {
+        channel?: string;
+    } & StreamCallbacks): void;
+    private setupEventListeners;
+    private handleMessage;
+    private dispatchToCallbacks;
+    private setState;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private attemptReconnect;
+    private flushMessageQueue;
+    /**
+     * Re-send subscribe messages for every active subscription.
+     * Called after a successful reconnect so that channel listeners
+     * resume working without the caller needing to re-subscribe manually.
+     */
+    private replaySubscriptions;
+}
+/**
+ * Create a WebSocket client instance
+ *
+ * @example
+ * ```typescript
+ * const client = createWebSocketClient({
+ *   baseUrl: 'wss://api.neurolink.example.com/ws',
+ *   apiKey: 'your-api-key',
+ *   autoReconnect: true,
+ * });
+ *
+ * client.connect({
+ *   onMessage: (event) => console.log('Received:', event),
+ * });
+ * ```
+ */
+export declare function createWebSocketClient(config: WebSocketConfig): NeuroLinkWebSocket;
+export type { StreamCallbacks, StreamEvent, StreamResult, ApiError };