@juspay/neurolink 9.3.0 → 9.5.0

package/dist/lib/types/workflowTypes.d.ts

@@ -0,0 +1,558 @@
+/**
+ * types/workflowTypes.ts
+ * Core type definitions for the Workflow Engine
+ *
+ * Testing Phase: Focuses on original output + evaluation metrics for AB testing
+ */
+import type { AnalyticsData } from "./analytics.js";
+import { AIProviderName } from "../constants/enums.js";
+import type { JsonValue } from "./common.js";
+/**
+ * Workflow type enumeration
+ */
+export type WorkflowType = "ensemble" | "chain" | "adaptive" | "custom";
+/**
+ * Judge output format options
+ */
+export type JudgeOutputFormat = "scores" | "ranking" | "best" | "detailed";
+/**
+ * Tone adjustment strategy (for future conditioning phase)
+ */
+export type ToneAdjustment = "soften" | "strengthen" | "neutral";
+/**
+ * Execution strategy for model groups
+ */
+export type ExecutionStrategy = "parallel" | "sequential";
+/**
+ * Model group for layer-based execution
+ * Enables sequential vs parallel control at group level
+ */
+export type ModelGroup = {
+    id: string;
+    name?: string;
+    description?: string;
+    models: WorkflowModelConfig[];
+    executionStrategy: ExecutionStrategy;
+    continueOnFailure?: boolean;
+    minSuccessful?: number;
+    parallelism?: number;
+    timeout?: number;
+    metadata?: Record<string, JsonValue>;
+};
+/**
+ * Workflow configuration
+ */
+export type WorkflowConfig = {
+    id: string;
+    name: string;
+    description?: string;
+    version?: string;
+    type: WorkflowType;
+    models: WorkflowModelConfig[];
+    modelGroups?: ModelGroup[];
+    defaultSystemPrompt?: string;
+    defaultJudgePrompt?: string;
+    judge?: JudgeConfig;
+    judges?: JudgeConfig[];
+    conditioning?: ConditioningConfig;
+    execution?: ExecutionConfig;
+    tags?: string[];
+    metadata?: Record<string, JsonValue>;
+    createdAt?: string;
+    updatedAt?: string;
+};
+/**
+ * Model configuration for ensemble
+ * Named WorkflowModelConfig to avoid conflict with modelTypes.ModelConfig
+ */
+export type WorkflowModelConfig = {
+    provider: AIProviderName;
+    model: string;
+    weight?: number;
+    temperature?: number;
+    maxTokens?: number;
+    systemPrompt?: string;
+    timeout?: number;
+    topP?: number;
+    topK?: number;
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    label?: string;
+    metadata?: Record<string, JsonValue>;
+};
+/**
+ * Judge model configuration
+ * NOTE: Testing phase uses fixed 0-100 scoring scale
+ */
+export type JudgeConfig = {
+    provider: AIProviderName;
+    model: string;
+    criteria: string[];
+    outputFormat: JudgeOutputFormat;
+    customPrompt?: string;
+    systemPrompt?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeout?: number;
+    blindEvaluation?: boolean;
+    includeReasoning: boolean;
+    synthesizeImprovedResponse?: boolean;
+    scoreScale: {
+        min: 0;
+        max: 100;
+    };
+    label?: string;
+    metadata?: Record<string, JsonValue>;
+};
+/**
+ * Response conditioning configuration
+ * NOTE: Testing phase - stub only, no actual conditioning
+ */
+export type ConditioningConfig = {
+    enabled?: boolean;
+    useConfidence: boolean;
+    confidenceThresholds?: {
+        high: number;
+        medium: number;
+        low: number;
+    };
+    synthesisModel?: {
+        provider: string;
+        model: string;
+        temperature?: number;
+    };
+    toneAdjustment?: ToneAdjustment;
+    includeMetadata?: boolean;
+    metadataFields?: string[];
+    addConfidenceStatement?: boolean;
+    addModelAttribution?: boolean;
+    addExecutionTime?: boolean;
+    metadata?: Record<string, JsonValue>;
+};
+/**
+ * Workflow execution configuration
+ */
+export type ExecutionConfig = {
+    timeout?: number;
+    modelTimeout?: number;
+    judgeTimeout?: number;
+    retries?: number;
+    retryDelay?: number;
+    retryableErrors?: string[];
+    parallelism?: number;
+    earlyTermination?: boolean;
+    minResponses?: number;
+    maxCost?: number;
+    costThreshold?: number;
+    enableMetrics?: boolean;
+    enableTracing?: boolean;
+    metadata?: Record<string, JsonValue>;
+};
+/**
+ * Input for workflow execution
+ */
+export type WorkflowInput = {
+    text: string;
+    context?: Record<string, JsonValue>;
+    metadata?: Record<string, JsonValue>;
+};
+/**
+ * Options for workflow execution
+ */
+export type WorkflowGenerateOptions = {
+    workflowId: string;
+    input: WorkflowInput;
+    overrides?: Partial<WorkflowConfig>;
+    timeout?: number;
+    enableAnalytics?: boolean;
+    enableEvaluation?: boolean;
+    context?: Record<string, JsonValue>;
+};
+/**
+ * Complete workflow execution result
+ * Returns both original and conditioned responses for comparison
+ */
+export type WorkflowResult = {
+    content: string;
+    originalContent?: string;
+    score: number;
+    reasoning: string;
+    ensembleResponses: EnsembleResponse[];
+    judgeScores?: JudgeScores;
+    selectedResponse?: EnsembleResponse;
+    confidence: number;
+    consensus?: number;
+    totalTime: number;
+    ensembleTime: number;
+    judgeTime?: number;
+    conditioningTime?: number;
+    workflow: string;
+    workflowName: string;
+    workflowVersion?: string;
+    usage?: AggregatedUsage;
+    cost?: number;
+    analytics?: WorkflowAnalytics;
+    evaluation?: WorkflowEvaluationData;
+    metadata?: Record<string, JsonValue>;
+    timestamp: string;
+};
+/**
+ * Single ensemble model response
+ */
+export type EnsembleResponse = {
+    provider: string;
+    model: string;
+    modelLabel?: string;
+    content: string;
+    responseTime: number;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    status: "success" | "failure" | "timeout" | "partial";
+    error?: string;
+    metadata?: Record<string, JsonValue>;
+    timestamp: string;
+};
+/**
+ * Judge scoring results
+ * NOTE: Scores are 0-100 for standardized evaluation
+ */
+export type JudgeScores = {
+    judgeProvider: string;
+    judgeModel: string;
+    scores: Record<string, number>;
+    ranking?: string[];
+    bestResponse?: string;
+    criteria: string[];
+    reasoning?: string;
+    synthesizedResponse?: string;
+    confidenceInJudgment?: number;
+    judgeTime: number;
+    metadata?: Record<string, JsonValue>;
+    timestamp: string;
+};
+/**
+ * Multi-judge voting results
+ */
+export type MultiJudgeScores = {
+    judges: JudgeScores[];
+    averageScores: Record<string, number>;
+    aggregatedRanking: string[];
+    consensusLevel: number;
+    bestResponse: string;
+    confidence: number;
+    votingStrategy: "average" | "median" | "majority";
+    metadata?: Record<string, JsonValue>;
+    judgeProvider?: string;
+    judgeModel?: string;
+    scores: Record<string, number>;
+    ranking?: string[];
+    reasoning?: string;
+    confidenceInJudgment?: number;
+    criteria: string[];
+    judgeTime: number;
+    timestamp: string;
+};
+/**
+ * Aggregated token usage across all models
+ */
+export type AggregatedUsage = {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalTokens: number;
+    byModel: Array<{
+        provider: string;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cost?: number;
+    }>;
+    judgeUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cost?: number;
+    };
+};
+/**
+ * Workflow-specific analytics
+ */
+export type WorkflowAnalytics = AnalyticsData & {
+    workflowId: string;
+    workflowType: WorkflowType;
+    modelsExecuted: number;
+    modelsSuccessful: number;
+    modelsFailed: number;
+    averageConfidence: number;
+    consensusLevel?: number;
+    modelResponseTimes: Record<string, number>;
+    fastestModel?: string;
+    slowestModel?: string;
+    totalCost: number;
+    costByModel: Record<string, number>;
+    costEfficiency?: number;
+};
+/**
+ * Evaluation data type for workflows
+ * Named WorkflowEvaluationData to avoid conflict with evaluation.EvaluationData
+ */
+export type WorkflowEvaluationData = {
+    relevance: number;
+    accuracy: number;
+    completeness: number;
+    overall: number;
+    reasoning?: string;
+};
+/**
+ * Workflow validation result
+ */
+export type WorkflowValidationResult = {
+    valid: boolean;
+    errors: WorkflowValidationError[];
+    warnings: WorkflowValidationWarning[];
+};
+/**
+ * Validation error
+ */
+export type WorkflowValidationError = {
+    field: string;
+    message: string;
+    code: string;
+    severity: "error" | "critical";
+};
+/**
+ * Validation warning
+ */
+export type WorkflowValidationWarning = {
+    field: string;
+    message: string;
+    code: string;
+    recommendation?: string;
+};
+/**
+ * Workflow execution error details
+ */
+export type WorkflowErrorDetails = {
+    code: string;
+    workflowId: string;
+    phase: "ensemble" | "judge" | "conditioning" | "validation";
+    details?: Record<string, JsonValue>;
+    retryable: boolean;
+    originalError?: Error;
+};
+/**
+ * Workflow execution error class
+ */
+export declare class WorkflowError extends Error {
+    readonly details: WorkflowErrorDetails;
+    constructor(message: string, details: WorkflowErrorDetails);
+}
+/**
+ * Options for ensemble execution
+ */
+export type ExecuteEnsembleOptions = {
+    prompt: string;
+    models: WorkflowModelConfig[];
+    executionConfig?: ExecutionConfig;
+    systemPrompt?: string;
+    workflowDefaults?: {
+        systemPrompt?: string;
+    };
+};
+/**
+ * Result of ensemble execution
+ */
+export type EnsembleExecutionResult = {
+    responses: EnsembleResponse[];
+    totalTime: number;
+    successCount: number;
+    failureCount: number;
+    errors: WorkflowError[];
+};
+/**
+ * Options for single model execution (internal)
+ */
+export type ExecuteModelOptions = {
+    model: WorkflowModelConfig;
+    prompt: string;
+    systemPrompt?: string;
+    timeout: number;
+};
+/**
+ * Options for judge scoring
+ */
+export type ScoreOptions = {
+    judges: JudgeConfig[];
+    responses: EnsembleResponse[];
+    originalPrompt: string;
+    systemPrompt?: string;
+    timeout?: number;
+    workflowDefaults?: {
+        judgePrompt?: string;
+    };
+};
+/**
+ * Result of judge scoring
+ */
+export type ScoreResult = {
+    scores: JudgeScores | MultiJudgeScores;
+    judgeTime: number;
+    error?: WorkflowError;
+};
+/**
+ * Parsed judge response (internal)
+ */
+export type ParsedJudgeResponse = {
+    scores: Record<string, number>;
+    ranking?: string[];
+    bestResponse?: string;
+    reasoning?: string;
+    synthesizedResponse?: string;
+    confidenceInJudgment?: number;
+};
+/**
+ * Options for response conditioning
+ */
+export type ConditionOptions = {
+    content: string;
+    selectedResponse: EnsembleResponse;
+    allResponses: EnsembleResponse[];
+    judgeScores?: JudgeScores | MultiJudgeScores;
+    config?: ConditioningConfig;
+    originalPrompt?: string;
+};
+/**
+ * Result of response conditioning
+ */
+export type ConditionResult = {
+    content: string;
+    conditioningTime: number;
+    metadata?: {
+        conditioningApplied: boolean;
+        originalLength: number;
+        finalLength: number;
+        confidenceStatementAdded?: boolean;
+        modelAttributionAdded?: boolean;
+        executionTimeAdded?: boolean;
+        synthesisApplied?: boolean;
+    };
+};
+/**
+ * Result of executing a single layer/group
+ */
+export type LayerExecutionResult = {
+    groupId: string;
+    responses: EnsembleResponse[];
+    successCount: number;
+    failureCount: number;
+    executionTime: number;
+    shouldContinue: boolean;
+};
+/**
+ * Options for layer execution
+ */
+export type ExecuteLayerOptions = {
+    group: ModelGroup;
+    prompt: string;
+    systemPrompt?: string;
+    workflowDefaultSystemPrompt?: string;
+};
+/**
+ * Registry entry with metadata (internal)
+ */
+export type RegistryEntry = {
+    config: WorkflowConfig;
+    registeredAt: string;
+    lastUsed?: string;
+    usageCount: number;
+};
+/**
+ * Options for workflow registration
+ */
+export type RegisterOptions = {
+    validateBeforeRegister?: boolean;
+    allowOverwrite?: boolean;
+};
+/**
+ * Result of registration operation
+ */
+export type RegisterResult = {
+    success: boolean;
+    workflowId: string;
+    validation?: WorkflowValidationResult;
+    error?: string;
+};
+/**
+ * Options for workflow listing
+ */
+export type ListOptions = {
+    type?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Workflow metadata
+ */
+export type WorkflowMetadata = {
+    registeredAt: string;
+    lastUsed?: string;
+    usageCount: number;
+};
+/**
+ * Registry statistics
+ */
+export type RegistryStats = {
+    totalWorkflows: number;
+    byType: Record<string, number>;
+    totalUsage: number;
+    mostUsed?: {
+        id: string;
+        name: string;
+        count: number;
+    };
+};
+/**
+ * Workflow execution metrics (internal)
+ */
+export type WorkflowExecutionMetrics = {
+    workflowId: string;
+    executionCount: number;
+    successCount: number;
+    failureCount: number;
+    averageExecutionTime: number;
+    averageScore: number;
+    averageConfidence: number;
+    totalCost: number;
+    lastExecutionTime: string;
+};
+/**
+ * Summary statistics for workflow executions
+ */
+export type SummaryStats = {
+    totalExecutions: number;
+    averageScore: number;
+    averageConfidence: number;
+    averageExecutionTime: number;
+    successRate: number;
+    totalCost: number;
+};
+/**
+ * Result of comparing two workflows
+ */
+export type WorkflowComparison = {
+    workflow1: SummaryStats;
+    workflow2: SummaryStats;
+    winner: "workflow1" | "workflow2" | "tie";
+    reasoning: string;
+};
+/**
+ * Validation result containing errors and warnings
+ */
+export type ValidationIssues = {
+    errors: WorkflowValidationError[];
+    warnings: WorkflowValidationWarning[];
+};

package/dist/lib/types/workflowTypes.js

@@ -0,0 +1,32 @@
+/**
+ * types/workflowTypes.ts
+ * Core type definitions for the Workflow Engine
+ *
+ * Testing Phase: Focuses on original output + evaluation metrics for AB testing
+ */
+import { AIProviderName } from "../constants/enums.js";
+/**
+ * Workflow execution error class
+ */
+export class WorkflowError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.name = "WorkflowError";
+        this.details = details;
+        // Maintain proper stack trace for V8 engines
+        if ("captureStackTrace" in Error &&
+            typeof Error.captureStackTrace === "function") {
+            Error.captureStackTrace(this, WorkflowError);
+        }
+    }
+}
+// ============================================================================
+// TYPE ALIASES FOR BACKWARD COMPATIBILITY (internal to workflow module only)
+// ============================================================================
+// Note: ModelConfig and EvaluationData aliases are NOT exported from this file
+// to avoid conflicts with modelTypes.ModelConfig and evaluation.EvaluationData.
+// Use WorkflowModelConfig and WorkflowEvaluationData when importing from this file.
+// The workflow/types.ts re-exports these aliases for backward compatibility
+// within the workflow module only.
+//# sourceMappingURL=workflowTypes.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * LAYER-BASED EXECUTION - USAGE EXAMPLES
+ * ======================================
+ *
+ * Demonstrates ModelGroup-based execution with sequential and parallel strategies
+ */
+import type { WorkflowConfig } from "./types.js";
+declare const simpleParallelWorkflow: WorkflowConfig;
+declare const fastThenPremiumWorkflow: WorkflowConfig;
+declare const fallbackChainWorkflow: WorkflowConfig;
+declare const mixedStrategyWorkflow: WorkflowConfig;
+declare const costOptimizedWorkflow: WorkflowConfig;
+export { simpleParallelWorkflow, fastThenPremiumWorkflow, fallbackChainWorkflow, mixedStrategyWorkflow, costOptimizedWorkflow, };