@juspay/neurolink
Version:
Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applicatio
599 lines (598 loc) • 14.9 kB
TypeScript
/**
* types/workflowTypes.ts
* Core type definitions for the Workflow Engine
*
* Testing Phase: Focuses on original output + evaluation metrics for AB testing
*/
import type { z } from "zod";
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 JudgeScoreResult = {
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[];
};
/**
* Options for workflow execution
*/
export type RunWorkflowOptions = {
/** The user's prompt/query to send to models */
prompt: string;
/** Optional conversation history for context */
conversationHistory?: Array<{
role: "user" | "assistant";
content: string;
}>;
/** Override default timeout (ms) for this execution */
timeout?: number;
/** Override default parallelism for this execution */
parallelism?: number;
/** Enable verbose logging for debugging */
verbose?: boolean;
/** Optional context/metadata to pass through */
metadata?: Record<string, JsonValue>;
/** Enable progressive streaming (yield preliminary response) */
streaming?: boolean;
};
/**
* Generic workflow validation result — replaces three near-identical types
* (WorkflowConfigValidationResult, ModelConfigValidationResult,
* JudgeConfigValidationResult). Named with `Workflow*` prefix to avoid
* collision with `tools.ts#ValidationResult` (Rule 9).
*/
export type WorkflowValidation<T> = {
success: boolean;
data?: T;
error?: z.ZodError;
};
/** Progressive workflow response chunk streamed by runWorkflow(). */
export type WorkflowStreamChunk = {
type: "preliminary" | "final";
content: string;
partialResult?: Partial<WorkflowResult>;
};