@juspay/neurolink 9.3.0 → 9.5.0

package/dist/lib/workflow/LAYER-EXAMPLES.js

@@ -0,0 +1,312 @@
+/**
+ * LAYER-BASED EXECUTION - USAGE EXAMPLES
+ * ======================================
+ *
+ * Demonstrates ModelGroup-based execution with sequential and parallel strategies
+ */
+import { AIProviderName } from "../constants/enums.js";
+// ============================================================================
+// EXAMPLE 1: Simple Parallel (Backward Compatible - Flat Models Array)
+// ============================================================================
+const simpleParallelWorkflow = {
+    id: "simple-parallel",
+    name: "Simple Parallel Workflow",
+    type: "ensemble",
+    // Traditional flat array - all execute in parallel
+    models: [
+        { provider: AIProviderName.OPENAI, model: "gpt-4o" },
+        { provider: AIProviderName.ANTHROPIC, model: "claude-3-5-sonnet-20241022" },
+        { provider: AIProviderName.GOOGLE_AI, model: "gemini-2.0-flash" },
+    ],
+    judge: {
+        provider: AIProviderName.OPENAI,
+        model: "gpt-4o",
+        criteria: ["accuracy", "clarity"],
+        outputFormat: "detailed",
+        includeReasoning: true,
+        scoreScale: { min: 0, max: 100 },
+    },
+};
+// ============================================================================
+// EXAMPLE 2: Fast-then-Premium (Sequential Groups)
+// ============================================================================
+const fastThenPremiumWorkflow = {
+    id: "fast-then-premium",
+    name: "Fast Models First, Premium If Needed",
+    type: "adaptive",
+    // Define execution layers
+    modelGroups: [
+        {
+            id: "fast-tier",
+            name: "Fast Models",
+            description: "Quick, cost-effective models",
+            models: [
+                { provider: AIProviderName.OPENAI, model: "gpt-4o-mini" },
+                { provider: AIProviderName.GOOGLE_AI, model: "gemini-2.0-flash" },
+            ],
+            executionStrategy: "parallel", // Both run simultaneously
+            continueOnFailure: true, // Always proceed to next group
+            minSuccessful: 1, // Need at least 1 success
+        },
+        {
+            id: "premium-tier",
+            name: "Premium Models",
+            description: "High-quality, more expensive models",
+            models: [
+                { provider: AIProviderName.OPENAI, model: "gpt-4o" },
+                {
+                    provider: AIProviderName.ANTHROPIC,
+                    model: "claude-3-5-sonnet-20241022",
+                },
+            ],
+            executionStrategy: "parallel", // Both run simultaneously
+            continueOnFailure: true,
+            minSuccessful: 1,
+        },
+    ],
+    // When using modelGroups, flat models array is ignored
+    models: [{ provider: AIProviderName.OPENAI, model: "gpt-4o-mini" }], // Placeholder for backward compat
+    judge: {
+        provider: AIProviderName.OPENAI,
+        model: "gpt-4o",
+        criteria: ["quality", "cost-effectiveness"],
+        outputFormat: "detailed",
+        includeReasoning: true,
+        scoreScale: { min: 0, max: 100 },
+    },
+};
+// ============================================================================
+// EXAMPLE 3: Fallback Chain (Sequential Models, Sequential Groups)
+// ============================================================================
+const fallbackChainWorkflow = {
+    id: "fallback-chain",
+    name: "Sequential Fallback Chain",
+    type: "chain",
+    modelGroups: [
+        {
+            id: "primary",
+            name: "Primary Model",
+            models: [
+                { provider: AIProviderName.OPENAI, model: "gpt-4o", timeout: 5000 },
+            ],
+            executionStrategy: "sequential", // Only one model
+            continueOnFailure: true, // Continue to fallback if fails
+            minSuccessful: 1,
+        },
+        {
+            id: "fallback-1",
+            name: "First Fallback",
+            models: [
+                {
+                    provider: AIProviderName.ANTHROPIC,
+                    model: "claude-3-5-sonnet-20241022",
+                    timeout: 8000,
+                },
+            ],
+            executionStrategy: "sequential",
+            continueOnFailure: true,
+            minSuccessful: 1,
+        },
+        {
+            id: "fallback-2",
+            name: "Second Fallback",
+            models: [
+                {
+                    provider: AIProviderName.GOOGLE_AI,
+                    model: "gemini-2.0-flash",
+                    timeout: 10000,
+                },
+            ],
+            executionStrategy: "sequential",
+            continueOnFailure: false, // Stop here if this fails
+            minSuccessful: 1,
+        },
+    ],
+    models: [{ provider: AIProviderName.OPENAI, model: "gpt-4o" }], // Placeholder
+    judge: {
+        provider: AIProviderName.OPENAI,
+        model: "gpt-4o-mini",
+        criteria: ["availability", "response_time"],
+        outputFormat: "best",
+        includeReasoning: true,
+        scoreScale: { min: 0, max: 100 },
+    },
+};
+// ============================================================================
+// EXAMPLE 4: Mixed Strategy (Parallel within groups, Sequential between)
+// ============================================================================
+const mixedStrategyWorkflow = {
+    id: "mixed-strategy",
+    name: "Mixed Parallel and Sequential",
+    type: "ensemble",
+    modelGroups: [
+        {
+            id: "quick-validation",
+            name: "Quick Validation Layer",
+            description: "Fast models to validate prompt feasibility",
+            models: [
+                { provider: AIProviderName.OPENAI, model: "gpt-4o-mini" },
+                { provider: AIProviderName.GOOGLE_AI, model: "gemini-2.0-flash" },
+                { provider: AIProviderName.ANTHROPIC, model: "claude-3-haiku" },
+            ],
+            executionStrategy: "parallel", // All 3 run simultaneously
+            continueOnFailure: true,
+            minSuccessful: 2, // Need at least 2 successful responses
+            parallelism: 3, // Allow all 3 to run at once
+        },
+        {
+            id: "deep-analysis",
+            name: "Deep Analysis Layer",
+            description: "Sequential premium models for thorough analysis",
+            models: [
+                {
+                    provider: AIProviderName.OPENAI,
+                    model: "gpt-4o",
+                    systemPrompt: "Provide deep, analytical responses with step-by-step reasoning.",
+                },
+                {
+                    provider: AIProviderName.ANTHROPIC,
+                    model: "claude-3-5-sonnet-20241022",
+                    systemPrompt: "Think carefully and provide nuanced, thoughtful analysis.",
+                },
+            ],
+            executionStrategy: "sequential", // Run one after another
+            continueOnFailure: false, // Stop if this layer fails
+            minSuccessful: 2, // Both must succeed
+            timeout: 30000, // 30 second timeout for this group
+        },
+    ],
+    models: [{ provider: AIProviderName.OPENAI, model: "gpt-4o-mini" }], // Placeholder
+    judges: [
+        {
+            provider: AIProviderName.OPENAI,
+            model: "gpt-4o",
+            criteria: ["depth", "accuracy"],
+            outputFormat: "detailed",
+            includeReasoning: true,
+            scoreScale: { min: 0, max: 100 },
+        },
+        {
+            provider: AIProviderName.ANTHROPIC,
+            model: "claude-3-5-sonnet-20241022",
+            criteria: ["reasoning_quality", "clarity"],
+            outputFormat: "detailed",
+            includeReasoning: true,
+            scoreScale: { min: 0, max: 100 },
+        },
+    ],
+};
+// ============================================================================
+// EXAMPLE 5: Cost-Optimized (Try cheap first, escalate if needed)
+// ============================================================================
+const costOptimizedWorkflow = {
+    id: "cost-optimized",
+    name: "Cost-Optimized Escalation",
+    type: "adaptive",
+    modelGroups: [
+        {
+            id: "budget-tier",
+            name: "Budget Models",
+            models: [
+                { provider: AIProviderName.OPENAI, model: "gpt-4o-mini", weight: 0.3 },
+            ],
+            executionStrategy: "sequential",
+            continueOnFailure: true, // Always try next tier
+            minSuccessful: 1,
+        },
+        {
+            id: "standard-tier",
+            name: "Standard Models",
+            models: [
+                {
+                    provider: AIProviderName.GOOGLE_AI,
+                    model: "gemini-2.0-flash",
+                    weight: 0.5,
+                },
+                {
+                    provider: AIProviderName.ANTHROPIC,
+                    model: "claude-3-haiku",
+                    weight: 0.5,
+                },
+            ],
+            executionStrategy: "parallel",
+            continueOnFailure: true,
+            minSuccessful: 1,
+        },
+        {
+            id: "premium-tier",
+            name: "Premium Models",
+            models: [
+                { provider: AIProviderName.OPENAI, model: "gpt-4o", weight: 1.0 },
+                {
+                    provider: AIProviderName.ANTHROPIC,
+                    model: "claude-3-5-sonnet-20241022",
+                    weight: 1.0,
+                },
+            ],
+            executionStrategy: "parallel",
+            continueOnFailure: false,
+            minSuccessful: 1,
+        },
+    ],
+    models: [{ provider: AIProviderName.OPENAI, model: "gpt-4o-mini" }], // Placeholder
+    execution: {
+        maxCost: 0.5, // Stop if cost exceeds $0.50
+        costThreshold: 0.25, // Warn at $0.25
+    },
+    judge: {
+        provider: AIProviderName.OPENAI,
+        model: "gpt-4o",
+        criteria: ["quality", "value_for_cost"],
+        outputFormat: "detailed",
+        includeReasoning: true,
+        scoreScale: { min: 0, max: 100 },
+    },
+};
+// ============================================================================
+// EXECUTION BEHAVIOR
+// ============================================================================
+/*
+ * Sequential Groups Execution:
+ * ---------------------------
+ * Group 1 → Wait for completion → Evaluate success → Group 2 → etc.
+ *
+ * continueOnFailure=true:  Proceed to next group even if current fails
+ * continueOnFailure=false: Stop execution if current group fails minSuccessful check
+ * minSuccessful: Number of successful models required to consider group successful
+ *
+ * Within Group Execution:
+ * ----------------------
+ * executionStrategy='parallel':   All models run simultaneously (respects parallelism limit)
+ * executionStrategy='sequential': Models run one after another
+ *
+ * Example Timeline (Fast-then-Premium):
+ *
+ * Time 0s:    Start Group 1 (fast-tier)
+ *   0.5s:       gpt-4o-mini executing (parallel)
+ *   0.5s:       gemini-flash executing (parallel)
+ *   1.2s:     Group 1 complete (both succeed)
+ *   1.2s:     Check minSuccessful=1 ✓
+ *   1.2s:   Start Group 2 (premium-tier)
+ *   1.7s:       gpt-4o executing (parallel)
+ *   1.7s:       claude-3.5 executing (parallel)
+ *   4.5s:     Group 2 complete
+ *   4.5s:   All groups complete
+ *   4.5s: Send all 4 responses to judge
+ */
+// ============================================================================
+// BACKWARD COMPATIBILITY
+// ============================================================================
+/*
+ * If workflow has ONLY `models` array (no modelGroups):
+ * - Internally converted to single ModelGroup with executionStrategy='parallel'
+ * - Behaves exactly like before
+ * - No breaking changes
+ *
+ * If workflow has `modelGroups`:
+ * - modelGroups takes precedence
+ * - models array is ignored (kept for schema validation only)
+ * - Layer-based execution is used
+ */
+export { simpleParallelWorkflow, fastThenPremiumWorkflow, fallbackChainWorkflow, mixedStrategyWorkflow, costOptimizedWorkflow, };
+//# sourceMappingURL=LAYER-EXAMPLES.js.map

package/dist/lib/workflow/PROMPT-EXAMPLES.d.ts

@@ -0,0 +1,117 @@
+/**
+ * HIERARCHICAL PROMPT SYSTEM - USAGE EXAMPLES
+ * ============================================
+ *
+ * Demonstrates the 3-level prompt resolution with fallback mechanism
+ */
+declare const simpleWorkflow: {
+    id: string;
+    name: string;
+    type: string;
+    defaultSystemPrompt: string;
+    defaultJudgePrompt: string;
+    models: {
+        provider: string;
+        model: string;
+    }[];
+    judge: {
+        provider: string;
+        model: string;
+        criteria: string[];
+        outputFormat: string;
+        includeReasoning: boolean;
+        scoreScale: {
+            min: number;
+            max: number;
+        };
+    };
+};
+declare const mixedWorkflow: {
+    id: string;
+    name: string;
+    type: string;
+    defaultSystemPrompt: string;
+    defaultJudgePrompt: string;
+    models: ({
+        provider: string;
+        model: string;
+        systemPrompt?: undefined;
+    } | {
+        provider: string;
+        model: string;
+        systemPrompt: string;
+    })[];
+    judge: {
+        provider: string;
+        model: string;
+        criteria: string[];
+        outputFormat: string;
+        includeReasoning: boolean;
+        scoreScale: {
+            min: number;
+            max: number;
+        };
+    };
+};
+declare const advancedWorkflow: {
+    id: string;
+    name: string;
+    type: string;
+    defaultSystemPrompt: string;
+    defaultJudgePrompt: string;
+    models: {
+        provider: string;
+        model: string;
+        systemPrompt: string;
+    }[];
+    judge: {
+        provider: string;
+        model: string;
+        criteria: string[];
+        outputFormat: string;
+        customPrompt: string;
+        systemPrompt: string;
+        includeReasoning: boolean;
+        scoreScale: {
+            min: number;
+            max: number;
+        };
+    };
+};
+declare const multiJudgeWorkflow: {
+    id: string;
+    name: string;
+    type: string;
+    defaultSystemPrompt: string;
+    defaultJudgePrompt: string;
+    models: {
+        provider: string;
+        model: string;
+    }[];
+    judges: ({
+        provider: string;
+        model: string;
+        criteria: string[];
+        outputFormat: string;
+        customPrompt: string;
+        systemPrompt: string;
+        includeReasoning: boolean;
+        scoreScale: {
+            min: number;
+            max: number;
+        };
+    } | {
+        provider: string;
+        model: string;
+        criteria: string[];
+        outputFormat: string;
+        includeReasoning: boolean;
+        scoreScale: {
+            min: number;
+            max: number;
+        };
+        customPrompt?: undefined;
+        systemPrompt?: undefined;
+    })[];
+};
+export { simpleWorkflow, mixedWorkflow, advancedWorkflow, multiJudgeWorkflow };

package/dist/lib/workflow/PROMPT-EXAMPLES.js

@@ -0,0 +1,246 @@
+/**
+ * HIERARCHICAL PROMPT SYSTEM - USAGE EXAMPLES
+ * ============================================
+ *
+ * Demonstrates the 3-level prompt resolution with fallback mechanism
+ */
+// ============================================================================
+// EXAMPLE 1: Simple - Use workflow-level defaults for all models
+// ============================================================================
+const simpleWorkflow = {
+    id: "simple-ensemble",
+    name: "Simple Ensemble with Workflow Defaults",
+    type: "ensemble",
+    // Workflow-level defaults (used by all models/judges)
+    defaultSystemPrompt: "You are a helpful assistant specialized in technical documentation.",
+    defaultJudgePrompt: "Evaluate responses for technical accuracy and clarity.",
+    models: [
+        { provider: "openai", model: "gpt-4o" }, // Uses workflow default
+        { provider: "anthropic", model: "claude-3-5-sonnet-20241022" }, // Uses workflow default
+        { provider: "google", model: "gemini-2.0-flash" }, // Uses workflow default
+    ],
+    judge: {
+        provider: "openai",
+        model: "gpt-4o",
+        criteria: ["accuracy", "clarity", "completeness"],
+        outputFormat: "detailed",
+        includeReasoning: true,
+        scoreScale: { min: 0, max: 100 },
+        // Uses workflow defaultJudgePrompt
+    },
+};
+// ============================================================================
+// EXAMPLE 2: Mixed - Some models override workflow defaults
+// ============================================================================
+const mixedWorkflow = {
+    id: "mixed-ensemble",
+    name: "Mixed Ensemble with Overrides",
+    type: "ensemble",
+    // Workflow-level defaults
+    defaultSystemPrompt: "You are a helpful assistant.",
+    defaultJudgePrompt: "Evaluate responses objectively.",
+    models: [
+        // Model 1: Uses workflow default
+        {
+            provider: "openai",
+            model: "gpt-4o",
+        },
+        // Model 2: Overrides with model-specific prompt
+        {
+            provider: "anthropic",
+            model: "claude-3-5-sonnet-20241022",
+            systemPrompt: "You are Claude, an AI assistant by Anthropic. Be thoughtful and nuanced.",
+        },
+        // Model 3: Uses workflow default
+        {
+            provider: "google",
+            model: "gemini-2.0-flash",
+        },
+    ],
+    judge: {
+        provider: "openai",
+        model: "gpt-4o",
+        criteria: ["helpfulness", "harmlessness", "honesty"],
+        outputFormat: "detailed",
+        includeReasoning: true,
+        scoreScale: { min: 0, max: 100 },
+        // Uses workflow defaultJudgePrompt
+    },
+};
+// ============================================================================
+// EXAMPLE 3: Advanced - Full customization per model and judge
+// ============================================================================
+const advancedWorkflow = {
+    id: "advanced-ensemble",
+    name: "Advanced Ensemble with Full Customization",
+    type: "ensemble",
+    // Workflow-level defaults (fallbacks)
+    defaultSystemPrompt: "You are a helpful assistant.",
+    defaultJudgePrompt: "Evaluate responses based on quality.",
+    models: [
+        // GPT-4: Optimized prompt for OpenAI
+        {
+            provider: "openai",
+            model: "gpt-4o",
+            systemPrompt: `You are GPT-4, a large language model by OpenAI.
+- Provide clear, structured responses
+- Use markdown formatting when helpful
+- Be concise yet comprehensive`,
+        },
+        // Claude: Optimized prompt for Anthropic
+        {
+            provider: "anthropic",
+            model: "claude-3-5-sonnet-20241022",
+            systemPrompt: `You are Claude, created by Anthropic.
+- Think step-by-step through complex problems
+- Acknowledge uncertainty when appropriate
+- Provide balanced, thoughtful responses`,
+        },
+        // Gemini: Optimized prompt for Google
+        {
+            provider: "google",
+            model: "gemini-2.0-flash",
+            systemPrompt: `You are Gemini, Google's advanced AI model.
+- Leverage multimodal understanding
+- Provide factual, grounded responses
+- Use clear explanations with examples`,
+        },
+    ],
+    judge: {
+        provider: "openai",
+        model: "gpt-4o",
+        criteria: [
+            "Factual accuracy",
+            "Reasoning quality",
+            "Clarity of explanation",
+            "Practical usefulness",
+        ],
+        outputFormat: "detailed",
+        // Custom judge evaluation prompt
+        customPrompt: `You are an expert AI evaluator specializing in technical content.
+
+Your task: Compare multiple AI responses and score them on a 0-100 scale.
+
+Evaluation Framework:
+- Factual Accuracy (30%): Correctness of information
+- Reasoning Quality (30%): Logic and depth of analysis
+- Clarity (20%): Easy to understand and well-structured
+- Practical Usefulness (20%): Actionable and helpful
+
+For each response:
+1. Assign a score 0-100
+2. Provide brief reasoning (max 200 chars)
+3. Rank responses from best to worst
+4. Identify the single best response
+
+Output JSON format:
+{
+  "scores": { "response-0": 85, "response-1": 92 },
+  "ranking": ["response-1", "response-0"],
+  "bestResponse": "response-1",
+  "reasoning": "Response 1 excels in depth and practical examples",
+  "confidenceInJudgment": 0.9
+}`,
+        // System instructions for judge personality
+        systemPrompt: "You are an impartial, expert evaluator. Be objective and thorough.",
+        includeReasoning: true,
+        scoreScale: { min: 0, max: 100 },
+    },
+};
+// ============================================================================
+// EXAMPLE 4: Multi-judge with different evaluation prompts
+// ============================================================================
+const multiJudgeWorkflow = {
+    id: "multi-judge-ensemble",
+    name: "Multi-Judge Ensemble",
+    type: "ensemble",
+    defaultSystemPrompt: "You are a helpful assistant.",
+    defaultJudgePrompt: "Evaluate responses for quality and accuracy.",
+    models: [
+        { provider: "openai", model: "gpt-4o" },
+        { provider: "anthropic", model: "claude-3-5-sonnet-20241022" },
+        { provider: "google", model: "gemini-2.0-flash" },
+    ],
+    judges: [
+        // Judge 1: Technical accuracy focus
+        {
+            provider: "openai",
+            model: "gpt-4o",
+            criteria: ["technical_accuracy", "completeness"],
+            outputFormat: "detailed",
+            customPrompt: "Evaluate responses focusing on technical accuracy and completeness. Score 0-100.",
+            systemPrompt: "You are a technical expert. Be rigorous in your evaluation.",
+            includeReasoning: true,
+            scoreScale: { min: 0, max: 100 },
+        },
+        // Judge 2: User experience focus
+        {
+            provider: "anthropic",
+            model: "claude-3-5-sonnet-20241022",
+            criteria: ["clarity", "helpfulness", "user_friendliness"],
+            outputFormat: "detailed",
+            customPrompt: "Evaluate responses focusing on clarity, helpfulness, and user-friendliness. Score 0-100.",
+            systemPrompt: "You are a UX expert. Focus on user experience quality.",
+            includeReasoning: true,
+            scoreScale: { min: 0, max: 100 },
+        },
+        // Judge 3: Overall quality (uses workflow default)
+        {
+            provider: "google",
+            model: "gemini-2.0-flash",
+            criteria: ["overall_quality"],
+            outputFormat: "detailed",
+            // Uses workflow defaultJudgePrompt
+            includeReasoning: true,
+            scoreScale: { min: 0, max: 100 },
+        },
+    ],
+};
+// ============================================================================
+// PROMPT RESOLUTION LOGIC
+// ============================================================================
+/*
+ * For Models (ensemble execution):
+ * --------------------------------
+ * 1. Direct parameter in executeEnsemble({ systemPrompt: "..." })  [Highest priority]
+ * 2. ModelConfig.systemPrompt
+ * 3. WorkflowConfig.defaultSystemPrompt
+ * 4. undefined (provider uses its default)
+ *
+ * For Judges (scoring):
+ * ---------------------
+ * 1. JudgeConfig.customPrompt  [Evaluation prompt body - Highest priority]
+ * 2. WorkflowConfig.defaultJudgePrompt
+ * 3. Built-in template (createJudgePrompt function)
+ *
+ * Judge System Prompt:
+ * -------------------
+ * 1. Direct parameter in scoreEnsemble({ systemPrompt: "..." })  [Highest priority]
+ * 2. JudgeConfig.systemPrompt
+ * 3. undefined (judge personality uses provider default)
+ */
+// ============================================================================
+// USAGE IN CODE
+// ============================================================================
+/*
+// Execute with workflow defaults
+await executeEnsemble({
+  prompt: "Explain quantum computing",
+  models: workflow.models,
+  workflowDefaults: {
+    systemPrompt: workflow.defaultSystemPrompt,
+  },
+});
+
+// Score with workflow defaults
+await scoreEnsemble({
+  judges: workflow.judges,
+  responses: ensembleResponses,
+  originalPrompt: "Explain quantum computing",
+  workflowDefaults: {
+    judgePrompt: workflow.defaultJudgePrompt,
+  },
+});
+*/
+export { simpleWorkflow, mixedWorkflow, advancedWorkflow, multiJudgeWorkflow };
+//# sourceMappingURL=PROMPT-EXAMPLES.js.map