@memberjunction/ai-prompts 3.4.0 → 4.1.0

package/dist/ParallelExecutionCoordinator.js

@@ -1,33 +1,10 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ParallelExecutionCoordinator = void 0;
-const core_1 = require("@memberjunction/core");
-const global_1 = require("@memberjunction/global");
-const ai_1 = require("@memberjunction/ai");
-const aiengine_1 = require("@memberjunction/aiengine");
+import { LogError, LogStatus, Metadata } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+import { BaseLLM, ChatParams, ChatMessageRole, GetAIAPIKey } from '@memberjunction/ai';
+import { AIEngine } from '@memberjunction/aiengine';
+/**
+ * Helper class for tracking parallel execution progress
+ */
 class ParallelProgressTracker {
     constructor(totalTasks, totalGroups, progressCallbacks) {
         this.completedTasks = 0;
@@ -72,6 +49,7 @@ class ParallelProgressTracker {
         else {
             this.failedTasks++;
         }
+        // Send task completion update if enabled
         if (this.progressCallbacks?.getStreamingConfig()?.enabled) {
             const config = this.progressCallbacks.getStreamingConfig();
             if (config.callbacks?.OnTaskComplete) {
@@ -103,23 +81,53 @@ class ParallelProgressTracker {
         }
     }
 }
-class ParallelExecutionCoordinator {
+/**
+ * Coordinates parallel execution of AI prompt tasks across multiple models and execution groups.
+ *
+ * This class manages the complex orchestration of:
+ * - Grouping tasks by execution group
+ * - Sequential execution of groups with parallel execution within groups
+ * - Result aggregation and selection
+ * - Error handling and partial result collection
+ * - Performance monitoring and metrics collection
+ * - Real-time progress tracking and streaming updates
+ */
+export class ParallelExecutionCoordinator {
+    /**
+     * Creates a new parallel execution coordinator with default configuration.
+     */
     constructor() {
-        this._metadata = new core_1.Metadata();
+        this._metadata = new Metadata();
         this._defaultConfig = {
             maxConcurrentExecutions: 5,
-            taskTimeoutMS: 30000,
+            taskTimeoutMS: 30000, // 30 seconds
             failFast: false,
             collectPartialResults: true,
             maxRetries: 3,
             retryDelayMS: 1000,
         };
     }
-    async executeTasksInParallel(params, tasks, config, parentPromptRunId, cancellationToken, progressCallbacks, agentRunId) {
+    /**
+     * Executes multiple tasks in parallel according to their execution groups.
+     *
+     * Tasks are grouped by their executionGroup property and executed sequentially by group.
+     * Within each group, tasks are executed in parallel up to the concurrency limit.
+     *
+     * @param tasks - Array of execution tasks to process
+     * @param config - Optional configuration to override defaults
+     * @param parentPromptRunId - Optional parent prompt run ID for hierarchical logging
+     * @param cancellationToken - Optional cancellation token to abort execution
+     * @param progressCallbacks - Optional callbacks for progress tracking
+     * @param agentRunId - Optional agent run ID to link prompt executions to parent agent run
+     * @returns Promise<ParallelExecutionResult> - Aggregated results from all executions
+     */
+    async executeTasksInParallel(params, tasks, config, parentPromptRunId, cancellationToken, progressCallbacks, // Using interface to avoid circular dependency
+    agentRunId) {
         const startTime = new Date();
         const executionConfig = { ...this._defaultConfig, ...config };
+        // Check for cancellation at the start
         if (cancellationToken?.aborted) {
-            (0, core_1.LogStatus)('Parallel execution cancelled before starting');
+            LogStatus('Parallel execution cancelled before starting');
             return {
                 success: false,
                 taskResults: [],
@@ -134,22 +142,27 @@ class ParallelExecutionCoordinator {
                 endTime: new Date(),
             };
         }
-        (0, core_1.LogStatus)(`Starting parallel execution of ${tasks.length} tasks with config: ${JSON.stringify(executionConfig)}`);
+        LogStatus(`Starting parallel execution of ${tasks.length} tasks with config: ${JSON.stringify(executionConfig)}`);
         try {
+            // Propagate cancellation token to all tasks
             if (cancellationToken) {
                 tasks.forEach((task) => {
                     task.cancellationToken = cancellationToken;
                 });
             }
+            // Group tasks by execution group
             const executionGroups = this.groupTasksByExecutionGroup(tasks);
+            // Initialize progress tracker
             const progressTracker = new ParallelProgressTracker(tasks.length, executionGroups.length, progressCallbacks);
+            // Execute groups sequentially, tasks within groups in parallel
             const allResults = await this.executeGroupsSequentially(params, executionGroups, executionConfig, parentPromptRunId, cancellationToken, progressTracker, agentRunId);
+            // Aggregate results and calculate metrics
             const result = this.aggregateResults(allResults, startTime, new Date());
-            (0, core_1.LogStatus)(`Parallel execution completed: ${result.successCount}/${tasks.length} tasks successful, ${result.failureCount} failed, ${result.cancelledCount} cancelled`);
+            LogStatus(`Parallel execution completed: ${result.successCount}/${tasks.length} tasks successful, ${result.failureCount} failed, ${result.cancelledCount} cancelled`);
             return result;
         }
         catch (error) {
-            (0, core_1.LogError)(`Parallel execution failed: ${error.message}`);
+            LogError(`Parallel execution failed: ${error.message}`);
             return {
                 success: false,
                 taskResults: [],
@@ -165,6 +178,17 @@ class ParallelExecutionCoordinator {
             };
         }
     }
+    /**
+     * Selects the best result from multiple parallel execution results.
+     *
+     * Uses various strategies to determine which result should be considered
+     * the "best" output from the parallel executions.
+     *
+     * @param results - Array of successful execution results to choose from
+     * @param config - Configuration for result selection method
+     * @param parentPromptRunId - Optional parent prompt run ID for hierarchical logging
+     * @returns Promise<ExecutionTaskResult | null> - The selected best result, or null if none suitable
+     */
     async selectBestResult(results, config, parentPromptRunId, cancellationToken) {
         if (results.length === 0) {
             return null;
@@ -172,7 +196,7 @@ class ParallelExecutionCoordinator {
         if (results.length === 1) {
             return results[0];
         }
-        (0, core_1.LogStatus)(`Selecting best result from ${results.length} candidates using method: ${config.method}`);
+        LogStatus(`Selecting best result from ${results.length} candidates using method: ${config.method}`);
         switch (config.method) {
             case 'First':
                 return this.selectFirstResult(results);
@@ -183,12 +207,20 @@ class ParallelExecutionCoordinator {
             case 'Consensus':
                 return this.selectConsensusResult(results);
             default:
-                (0, core_1.LogError)(`Unknown result selection method: ${config.method}`);
+                LogError(`Unknown result selection method: ${config.method}`);
                 return results[0];
         }
     }
+    /**
+     * Groups execution tasks by their execution group number.
+     * Tasks with the same group number will be executed in parallel.
+     *
+     * @param tasks - Array of tasks to group
+     * @returns ExecutionGroup[] - Sorted array of execution groups
+     */
     groupTasksByExecutionGroup(tasks) {
         const groupMap = new Map();
+        // Group tasks by execution group number
         for (const task of tasks) {
             const groupNumber = task.executionGroup;
             if (!groupMap.has(groupNumber)) {
@@ -196,23 +228,39 @@ class ParallelExecutionCoordinator {
             }
             groupMap.get(groupNumber).push(task);
         }
+        // Convert to ExecutionGroup array and sort by group number
         const groups = [];
         for (const [groupNumber, groupTasks] of groupMap) {
+            // Sort tasks within group by priority (higher priority first)
             groupTasks.sort((a, b) => b.priority - a.priority);
             groups.push({
                 groupNumber,
                 tasks: groupTasks,
             });
         }
+        // Sort groups by group number (execute in ascending order)
         groups.sort((a, b) => a.groupNumber - b.groupNumber);
-        (0, core_1.LogStatus)(`Grouped ${tasks.length} tasks into ${groups.length} execution groups`);
+        LogStatus(`Grouped ${tasks.length} tasks into ${groups.length} execution groups`);
         return groups;
     }
+    /**
+     * Executes execution groups sequentially, with parallel execution within each group.
+     *
+     * @param groups - Array of execution groups to process
+     * @param config - Execution configuration
+     * @param parentPromptRunId - Optional parent prompt run ID for tracking
+     * @param cancellationToken - Optional cancellation token to abort execution
+     * @param progressTracker - Progress tracker for monitoring execution
+     * @param agentRunId - Optional agent run ID to link prompt executions to parent agent run
+     * @returns Promise<ExecutionTaskResult[]> - All task results from all groups
+     */
     async executeGroupsSequentially(params, groups, config, parentPromptRunId, cancellationToken, progressTracker, agentRunId) {
         const allResults = [];
         for (const group of groups) {
+            // Check for cancellation before each group
             if (cancellationToken?.aborted) {
-                (0, core_1.LogStatus)(`Group execution cancelled at group ${group.groupNumber}`);
+                LogStatus(`Group execution cancelled at group ${group.groupNumber}`);
+                // Create cancelled results for remaining tasks
                 const cancelledResults = group.tasks.map((task) => ({
                     task,
                     success: false,
@@ -225,27 +273,43 @@ class ParallelExecutionCoordinator {
                 allResults.push(...cancelledResults);
                 break;
             }
-            (0, core_1.LogStatus)(`Executing group ${group.groupNumber} with ${group.tasks.length} tasks`);
+            LogStatus(`Executing group ${group.groupNumber} with ${group.tasks.length} tasks`);
+            // Update progress tracker for current group
             progressTracker?.updateProgress(group.groupNumber);
             const groupResults = await this.executeGroupInParallel(params, group, config, parentPromptRunId, cancellationToken, progressTracker, agentRunId);
             allResults.push(...groupResults);
+            // Check if we should fail fast
             if (config.failFast && groupResults.some((r) => !r.success)) {
                 const failedTasks = groupResults.filter((r) => !r.success);
-                (0, core_1.LogError)(`Failing fast due to ${failedTasks.length} failed tasks in group ${group.groupNumber}`);
+                LogError(`Failing fast due to ${failedTasks.length} failed tasks in group ${group.groupNumber}`);
                 break;
             }
         }
         return allResults;
     }
+    /**
+     * Executes all tasks within a single execution group in parallel.
+     *
+     * @param group - The execution group to process
+     * @param config - Execution configuration
+     * @param parentPromptRunId - Optional parent prompt run ID for tracking
+     * @param cancellationToken - Optional cancellation token to abort execution
+     * @param progressTracker - Progress tracker for monitoring execution
+     * @param agentRunId - Optional agent run ID to link prompt executions to parent agent run
+     * @returns Promise<ExecutionTaskResult[]> - Results from all tasks in the group
+     */
     async executeGroupInParallel(params, group, config, parentPromptRunId, cancellationToken, progressTracker, agentRunId) {
         const maxConcurrent = Math.min(config.maxConcurrentExecutions, group.tasks.length);
         const results = [];
         const executing = [];
         let taskIndex = 0;
         let executionOrder = 0;
+        // Process tasks with concurrency limit
         while (taskIndex < group.tasks.length || executing.length > 0) {
+            // Check for cancellation
             if (cancellationToken?.aborted) {
-                (0, core_1.LogStatus)(`Task execution cancelled in group ${group.groupNumber}`);
+                LogStatus(`Task execution cancelled in group ${group.groupNumber}`);
+                // Cancel remaining tasks
                 while (taskIndex < group.tasks.length) {
                     const task = group.tasks[taskIndex++];
                     results.push({
@@ -260,16 +324,20 @@ class ParallelExecutionCoordinator {
                 }
                 break;
             }
+            // Start new tasks up to concurrency limit
             while (executing.length < maxConcurrent && taskIndex < group.tasks.length) {
                 const task = group.tasks[taskIndex++];
                 progressTracker?.addActiveTask(task.taskId);
                 const execution = this.executeTask(params, task, config, parentPromptRunId, executionOrder++, agentRunId);
                 executing.push(execution);
             }
+            // Wait for at least one task to complete
             if (executing.length > 0) {
                 const result = await Promise.race(executing);
                 results.push(result);
+                // Notify progress tracker of task completion
                 progressTracker?.taskCompleted(result);
+                // Remove completed task from executing array
                 const completedIndex = executing.findIndex((p) => p === Promise.resolve(result));
                 if (completedIndex !== -1) {
                     executing.splice(completedIndex, 1);
@@ -278,17 +346,29 @@ class ParallelExecutionCoordinator {
         }
         const successfulResults = results.filter((r) => r.success);
         const cancelledResults = results.filter((r) => r.cancelled);
-        (0, core_1.LogStatus)(`Group ${group.groupNumber} completed: ${successfulResults.length}/${results.length} successful, ${cancelledResults.length} cancelled`);
+        LogStatus(`Group ${group.groupNumber} completed: ${successfulResults.length}/${results.length} successful, ${cancelledResults.length} cancelled`);
         return results;
     }
+    /**
+     * Executes a single task with retry logic and timeout handling.
+     *
+     * @param task - The execution task to process
+     * @param config - Execution configuration
+     * @param parentPromptRunId - Optional parent prompt run ID for hierarchical logging
+     * @param executionOrder - Execution order for this task
+     * @param agentRunId - Optional agent run ID to link prompt executions to parent agent run
+     * @returns Promise<ExecutionTaskResult> - Result of the task execution
+     */
     async executeTask(params, task, config, parentPromptRunId, executionOrder, agentRunId) {
         const startTime = new Date();
         let lastError = null;
+        // Attempt execution with retries
         for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
             try {
+                // Check for cancellation before each attempt
                 if (task.cancellationToken?.aborted) {
                     const endTime = new Date();
-                    (0, core_1.LogStatus)(`Task ${task.taskId} cancelled before attempt ${attempt + 1}`);
+                    LogStatus(`Task ${task.taskId} cancelled before attempt ${attempt + 1}`);
                     return {
                         task,
                         success: false,
@@ -300,8 +380,9 @@ class ParallelExecutionCoordinator {
                     };
                 }
                 if (attempt > 0) {
+                    // Apply retry delay
                     await this.delay(config.retryDelayMS * attempt);
-                    (0, core_1.LogStatus)(`Retrying task ${task.taskId}, attempt ${attempt + 1}/${config.maxRetries + 1}`);
+                    LogStatus(`Retrying task ${task.taskId}, attempt ${attempt + 1}/${config.maxRetries + 1}`);
                 }
                 const result = await this.executeSingleTask(params, task, config.taskTimeoutMS, parentPromptRunId, executionOrder, agentRunId);
                 result.startTime = startTime;
@@ -310,12 +391,14 @@ class ParallelExecutionCoordinator {
             }
             catch (error) {
                 lastError = error;
-                (0, core_1.LogError)(`Task ${task.taskId} attempt ${attempt + 1} failed: ${error.message}`);
+                LogError(`Task ${task.taskId} attempt ${attempt + 1} failed: ${error.message}`);
+                // Don't retry if this was the last attempt
                 if (attempt === config.maxRetries) {
                     break;
                 }
             }
         }
+        // All attempts failed
         const endTime = new Date();
         return {
             task,
@@ -326,23 +409,39 @@ class ParallelExecutionCoordinator {
             endTime,
         };
     }
+    /**
+     * Executes a single task without retry logic.
+     *
+     * @param task - The execution task to process
+     * @param timeoutMS - Timeout for the execution in milliseconds
+     * @param parentPromptRunId - Optional parent prompt run ID for hierarchical logging
+     * @param executionOrder - Execution order for this task
+     * @param agentRunId - Optional agent run ID to link prompt executions to parent agent run
+     * @returns Promise<ExecutionTaskResult> - Result of the task execution
+     */
     async executeSingleTask(params, task, timeoutMS, parentPromptRunId, executionOrder, agentRunId) {
+        // TODO: This will need to integrate with AIPromptRunner's execution logic
+        // For now, implementing a simplified version
         const startTime = new Date();
         let childPromptRun = null;
         try {
+            // Create child prompt run log if parent ID is provided
             if (parentPromptRunId) {
                 childPromptRun = await this.createChildPromptRun(task, startTime, parentPromptRunId, executionOrder, agentRunId);
             }
+            // Create LLM instance using vendor-specific driver class if available
             const driverClass = task.vendorDriverClass || task.model.DriverClass;
             const apiName = task.vendorApiName || task.model.APIName;
             if (!driverClass) {
                 throw new Error(`No driver class available for model ${task.model.Name}. Vendor selection may have failed.`);
             }
-            const apiKey = (0, ai_1.GetAIAPIKey)(driverClass, params.apiKeys, params.verbose);
-            const llm = global_1.MJGlobal.Instance.ClassFactory.CreateInstance(ai_1.BaseLLM, driverClass, apiKey);
-            const innerParams = new ai_1.ChatParams();
+            const apiKey = GetAIAPIKey(driverClass, params.apiKeys, params.verbose);
+            const llm = MJGlobal.Instance.ClassFactory.CreateInstance(BaseLLM, driverClass, apiKey);
+            // Prepare chat parameters
+            const innerParams = new ChatParams();
             innerParams.model = apiName;
             innerParams.cancellationToken = task.cancellationToken;
+            // Configure streaming if enabled in task
             if (task.streamingConfig?.enabled && task.streamingConfig.callbacks?.OnContent) {
                 innerParams.streaming = true;
                 innerParams.streamingCallbacks = {
@@ -351,12 +450,17 @@ class ParallelExecutionCoordinator {
                     OnError: task.streamingConfig.callbacks.OnError,
                 };
             }
+            // Build message array with rendered prompt and conversation messages
             innerParams.messages = this.buildMessageArray(task.renderedPrompt, task.conversationMessages, task.templateMessageRole || 'system');
+            // Apply model-specific parameters if available
             if (task.modelParameters) {
                 Object.assign(params, task.modelParameters);
             }
+            // Execute with timeout and cancellation support
             const racePromises = [llm.ChatCompletion(innerParams)];
+            // Add timeout promise
             racePromises.push(new Promise((_, reject) => setTimeout(() => reject(new Error('Task execution timeout')), timeoutMS)));
+            // Add cancellation promise if cancellation token is available
             if (task.cancellationToken) {
                 racePromises.push(new Promise((_, reject) => {
                     if (task.cancellationToken.aborted) {
@@ -372,6 +476,7 @@ class ParallelExecutionCoordinator {
             const modelResult = (await Promise.race(racePromises));
             const endTime = new Date();
             const executionTimeMS = endTime.getTime() - startTime.getTime();
+            // Update child prompt run with results
             if (childPromptRun) {
                 await this.updateChildPromptRun(childPromptRun, modelResult, endTime, executionTimeMS);
             }
@@ -384,13 +489,15 @@ class ParallelExecutionCoordinator {
                 modelResult,
                 startTime,
                 endTime,
-                promptRun: childPromptRun,
+                promptRun: childPromptRun, // Include the child prompt run in the result
             };
         }
         catch (error) {
             const endTime = new Date();
             const executionTimeMS = endTime.getTime() - startTime.getTime();
+            // Check if this was a cancellation error
             const isCancelled = error.message.includes('cancelled');
+            // Update child prompt run with error if it exists
             if (childPromptRun) {
                 childPromptRun.CompletedAt = endTime;
                 childPromptRun.ExecutionTimeMS = executionTimeMS;
@@ -399,6 +506,7 @@ class ParallelExecutionCoordinator {
                 childPromptRun.Result = `ERROR: ${error.message}`;
                 await childPromptRun.Save();
             }
+            // Return cancelled result instead of throwing if this was a cancellation
             if (isCancelled) {
                 return {
                     task,
@@ -414,12 +522,21 @@ class ParallelExecutionCoordinator {
             throw new Error(`Task execution failed: ${error.message}`);
         }
     }
+    /**
+     * Aggregates individual task results into a comprehensive parallel execution result.
+     *
+     * @param taskResults - Array of all task execution results
+     * @param startTime - Start time of the parallel execution
+     * @param endTime - End time of the parallel execution
+     * @returns ParallelExecutionResult - Aggregated results with metrics
+     */
     aggregateResults(taskResults, startTime, endTime) {
         const groupResults = new Map();
         const errors = [];
         let totalTokensUsed = 0;
         let successCount = 0;
         let cancelledCount = 0;
+        // Group results and calculate metrics
         for (const result of taskResults) {
             const groupNumber = result.task.executionGroup;
             if (!groupResults.has(groupNumber)) {
@@ -453,37 +570,63 @@ class ParallelExecutionCoordinator {
             endTime,
         };
     }
+    /**
+     * Selects the first successful result from the array.
+     *
+     * @param results - Array of successful results to choose from
+     * @returns ExecutionTaskResult - The first result in the array
+     */
     selectFirstResult(results) {
         return results[0];
     }
+    /**
+     * Selects a random result from the array.
+     *
+     * @param results - Array of successful results to choose from
+     * @returns ExecutionTaskResult - A randomly selected result
+     */
     selectRandomResult(results) {
         const randomIndex = Math.floor(Math.random() * results.length);
         return results[randomIndex];
     }
+    /**
+     * Uses an AI prompt to select the best result from multiple options.
+     *
+     * @param results - Array of successful results to choose from
+     * @param selectorPromptId - ID of the prompt to use for selection
+     * @param parentPromptRunId - Optional parent prompt run ID for hierarchical logging
+     * @returns Promise<ExecutionTaskResult> - The AI-selected best result with all results ranked
+     */
     async selectResultWithPrompt(results, selectorPromptId, parentPromptRunId, _cancellationToken) {
         try {
-            const { AIPromptRunner } = await Promise.resolve().then(() => __importStar(require('./AIPromptRunner')));
-            await aiengine_1.AIEngine.Instance.Config(false);
-            const judgePrompt = aiengine_1.AIEngine.Instance.Prompts.find((p) => p.ID === selectorPromptId);
+            // Import AIPromptRunner here to avoid circular dependency
+            const { AIPromptRunner } = await import('./AIPromptRunner.js');
+            // Load the judge prompt from AIEngine
+            await AIEngine.Instance.Config(false);
+            const judgePrompt = AIEngine.Instance.Prompts.find((p) => p.ID === selectorPromptId);
             if (!judgePrompt) {
-                (0, core_1.LogError)(`Judge prompt with ID ${selectorPromptId} not found`);
-                return results[0];
+                LogError(`Judge prompt with ID ${selectorPromptId} not found`);
+                return results[0]; // Fallback to first result
             }
+            // Prepare the data for the judge prompt
             const judgeData = this.formatResultsForJudge(results);
+            // Create conversation messages for the judge
             const conversationMessages = [
                 {
-                    role: ai_1.ChatMessageRole.system,
+                    role: ChatMessageRole.system,
                     content: 'You are an expert AI judge tasked with ranking multiple AI responses to determine the best one. Analyze each response for quality, accuracy, completeness, and relevance to the original prompt.',
                 },
                 {
-                    role: ai_1.ChatMessageRole.user,
+                    role: ChatMessageRole.user,
                     content: JSON.stringify(judgeData, null, 2),
                 },
             ];
+            // Create a ResultSelector prompt run log entry if parent ID is provided
             let resultSelectorPromptRun = null;
             if (parentPromptRunId) {
                 resultSelectorPromptRun = await this.createResultSelectorPromptRun(judgePrompt, judgeData, parentPromptRunId, results.length);
             }
+            // Execute the judge prompt
             const judgeRunner = new AIPromptRunner();
             const judgeStartTime = Date.now();
             const judgeResult = await judgeRunner.ExecutePrompt({
@@ -493,6 +636,7 @@ class ParallelExecutionCoordinator {
             });
             const judgeEndTime = Date.now();
             const judgeExecutionTimeMS = judgeEndTime - judgeStartTime;
+            // Update the result selector prompt run with the result
             if (resultSelectorPromptRun && judgeResult.promptRun) {
                 resultSelectorPromptRun.CompletedAt = new Date(judgeEndTime);
                 resultSelectorPromptRun.ExecutionTimeMS = judgeExecutionTimeMS;
@@ -504,31 +648,41 @@ class ParallelExecutionCoordinator {
                 await resultSelectorPromptRun.Save();
             }
             if (!judgeResult.success || !judgeResult.rawResult) {
-                (0, core_1.LogError)(`Judge prompt execution failed: ${judgeResult.errorMessage}`);
-                return results[0];
+                LogError(`Judge prompt execution failed: ${judgeResult.errorMessage}`);
+                return results[0]; // Fallback to first result
             }
+            // Parse the judge's decision
             const rankings = this.parseJudgeResult(judgeResult.rawResult);
             if (!rankings || rankings.length === 0) {
-                (0, core_1.LogError)('Failed to parse judge rankings');
-                return results[0];
+                LogError('Failed to parse judge rankings');
+                return results[0]; // Fallback to first result
             }
+            // Apply rankings to results
             this.applyRankingsToResults(results, rankings);
+            // Store judge metadata for later use
             const bestCandidateId = rankings.find((r) => r.rank === 1)?.candidateId;
             const bestResultIndex = results.findIndex((r) => r.task.taskId === bestCandidateId);
             const bestResult = bestResultIndex >= 0 ? results[bestResultIndex] : results[0];
+            // Add judge metadata to the best result
             bestResult.judgeMetadata = {
                 judgePromptId: selectorPromptId,
                 judgeExecutionTimeMS,
                 judgeTokensUsed: judgeResult.tokensUsed,
             };
-            (0, core_1.LogStatus)(`Judge selected candidate ${bestCandidateId} as the best result`);
+            LogStatus(`Judge selected candidate ${bestCandidateId} as the best result`);
             return bestResult;
         }
         catch (error) {
-            (0, core_1.LogError)(`Error in AI judge selection: ${error.message}`);
-            return results[0];
+            LogError(`Error in AI judge selection: ${error.message}`);
+            return results[0]; // Fallback to first result
         }
     }
+    /**
+     * Formats execution results for the judge prompt.
+     *
+     * @param results - Array of execution results to format
+     * @returns Structured data for judge evaluation
+     */
     formatResultsForJudge(results) {
         return {
             originalPrompt: results[0]?.task.renderedPrompt || 'Original prompt not available',
@@ -547,8 +701,15 @@ class ParallelExecutionCoordinator {
             },
         };
     }
+    /**
+     * Parses the judge's result to extract rankings.
+     *
+     * @param judgeResult - Raw result from the judge prompt
+     * @returns Array of ranking objects or null if parsing fails
+     */
     parseJudgeResult(judgeResult) {
         try {
+            // Try to extract JSON from the result (in case there's extra text)
             const jsonMatch = judgeResult.match(/\{[\s\S]*\}/);
             const jsonString = jsonMatch ? jsonMatch[0] : judgeResult;
             const parsed = JSON.parse(jsonString);
@@ -559,14 +720,20 @@ class ParallelExecutionCoordinator {
                     rationale: ranking.rationale || 'No rationale provided',
                 }));
             }
-            (0, core_1.LogError)('Judge result does not contain valid rankings array');
+            LogError('Judge result does not contain valid rankings array');
             return null;
         }
         catch (error) {
-            (0, core_1.LogError)(`Failed to parse judge result: ${error.message}`);
+            LogError(`Failed to parse judge result: ${error.message}`);
             return null;
         }
     }
+    /**
+     * Applies rankings to execution task results.
+     *
+     * @param results - Array of execution results to rank
+     * @param rankings - Rankings from the judge
+     */
     applyRankingsToResults(results, rankings) {
         for (const result of results) {
             const ranking = rankings.find((r) => r.candidateId === result.task.taskId);
@@ -576,7 +743,14 @@ class ParallelExecutionCoordinator {
             }
         }
     }
+    /**
+     * Selects the result that appears most frequently (consensus).
+     *
+     * @param results - Array of successful results to choose from
+     * @returns ExecutionTaskResult - The most common result
+     */
     selectConsensusResult(results) {
+        // Group results by their content
         const resultGroups = new Map();
         for (const result of results) {
             const key = result.rawResult || '';
@@ -585,41 +759,62 @@ class ParallelExecutionCoordinator {
             }
             resultGroups.get(key).push(result);
         }
+        // Find the group with the most results
         let largestGroup = [];
         for (const group of resultGroups.values()) {
             if (group.length > largestGroup.length) {
                 largestGroup = group;
             }
         }
+        // Return the first result from the largest group
         return largestGroup[0];
     }
+    /**
+     * Builds the message array combining rendered prompt with conversation messages
+     */
     buildMessageArray(renderedPrompt, conversationMessages, templateMessageRole = 'system') {
         const messages = [];
+        // Add rendered template as system or user message if not 'none'
         if (renderedPrompt && templateMessageRole !== 'none') {
             messages.push({
-                role: templateMessageRole === 'system' ? ai_1.ChatMessageRole.system : ai_1.ChatMessageRole.user,
+                role: templateMessageRole === 'system' ? ChatMessageRole.system : ChatMessageRole.user,
                 content: renderedPrompt,
             });
         }
+        // Add conversation messages if provided
         if (conversationMessages && conversationMessages.length > 0) {
             messages.push(...conversationMessages);
         }
+        // If no conversation messages and no rendered prompt as user message,
+        // add a default user message to ensure we have at least one user message
         if ((!conversationMessages || conversationMessages.length === 0) && templateMessageRole !== 'user' && renderedPrompt) {
+            // If we only have a system message, we need a user message too
             if (templateMessageRole === 'system') {
                 messages.push({
-                    role: ai_1.ChatMessageRole.user,
+                    role: ChatMessageRole.user,
                     content: 'Please proceed with the above instructions.',
                 });
             }
         }
         else if ((!conversationMessages || conversationMessages.length === 0) && !renderedPrompt) {
+            // Fallback: if no conversation and no rendered prompt, add a basic user message
             messages.push({
-                role: ai_1.ChatMessageRole.user,
+                role: ChatMessageRole.user,
                 content: 'Hello',
             });
         }
         return messages;
     }
+    /**
+     * Creates a child AIPromptRun entity for individual parallel execution tracking.
+     *
+     * @param task - The execution task
+     * @param startTime - When the execution started
+     * @param parentPromptRunId - ID of the parent prompt run
+     * @param executionOrder - Execution order within the parallel group
+     * @param agentRunId - Optional agent run ID to link prompt executions to parent agent run
+     * @returns Promise<AIPromptRunEntityExtended> - The created child prompt run
+     */
     async createChildPromptRun(task, startTime, parentPromptRunId, executionOrder, agentRunId) {
         try {
             const promptRun = await this._metadata.GetEntityObject('MJ: AI Prompt Runs', task.contextUser);
@@ -632,18 +827,23 @@ class ParallelExecutionCoordinator {
             if (executionOrder !== undefined) {
                 promptRun.ExecutionOrder = executionOrder;
             }
+            // Set AgentRunID if provided for agent-prompt execution tracking
             if (agentRunId) {
                 promptRun.AgentRunID = agentRunId;
             }
+            // Set vendor ID from task if available (use task vendor ID which comes from vendor selection)
             if (task.vendorId) {
                 promptRun.VendorID = task.vendorId;
             }
             else if (task.promptModel?.VendorID) {
+                // Fallback to prompt model vendor if task vendor not set
                 promptRun.VendorID = task.promptModel.VendorID;
             }
+            // Set configuration ID from task if available
             if (task.configurationId) {
                 promptRun.ConfigurationID = task.configurationId;
             }
+            // Store the input data/context as JSON in Messages field
             const messagesData = {
                 renderedPrompt: task.renderedPrompt,
                 conversationMessages: task.conversationMessages,
@@ -654,16 +854,24 @@ class ParallelExecutionCoordinator {
             const saveResult = await promptRun.Save();
             if (!saveResult) {
                 const error = `Failed to save child AIPromptRun: ${promptRun.LatestResult?.Message || 'Unknown error'}`;
-                (0, core_1.LogError)(error);
+                LogError(error);
                 throw new Error(error);
             }
             return promptRun;
         }
         catch (error) {
-            (0, core_1.LogError)(`Error creating child prompt run record: ${error.message}`);
+            LogError(`Error creating child prompt run record: ${error.message}`);
             throw error;
         }
     }
+    /**
+     * Updates a child AIPromptRun entity with execution results.
+     *
+     * @param promptRun - The child prompt run entity to update
+     * @param modelResult - The result from the AI model
+     * @param endTime - When the execution completed
+     * @param executionTimeMS - Total execution time in milliseconds
+     */
     async updateChildPromptRun(promptRun, modelResult, endTime, executionTimeMS) {
         try {
             promptRun.CompletedAt = endTime;
@@ -671,6 +879,7 @@ class ParallelExecutionCoordinator {
             promptRun.Success = modelResult.success;
             if (modelResult.success) {
                 promptRun.Result = modelResult.data?.choices?.[0]?.message?.content || '';
+                // Extract token usage if available
                 if (modelResult.data?.usage) {
                     promptRun.TokensUsed = modelResult.data.usage.totalTokens;
                     promptRun.TokensPrompt = modelResult.data.usage.promptTokens;
@@ -683,22 +892,33 @@ class ParallelExecutionCoordinator {
             }
             const saveResult = await promptRun.Save();
             if (!saveResult) {
-                (0, core_1.LogError)(`Failed to update child AIPromptRun with results: ${promptRun.LatestResult?.Message || 'Unknown error'}`);
+                LogError(`Failed to update child AIPromptRun with results: ${promptRun.LatestResult?.Message || 'Unknown error'}`);
             }
         }
         catch (error) {
-            (0, core_1.LogError)(`Error updating child prompt run: ${error.message}`);
+            LogError(`Error updating child prompt run: ${error.message}`);
         }
     }
+    /**
+     * Creates a ResultSelector AIPromptRun entity for judge execution tracking.
+     *
+     * @param judgePrompt - The judge prompt being executed
+     * @param judgeData - The data being sent to the judge
+     * @param parentPromptRunId - ID of the parent prompt run
+     * @param executionOrder - Execution order within the parallel group
+     * @returns Promise<AIPromptRunEntityExtended> - The created result selector prompt run
+     */
     async createResultSelectorPromptRun(judgePrompt, judgeData, parentPromptRunId, executionOrder) {
         try {
             const promptRun = await this._metadata.GetEntityObject('MJ: AI Prompt Runs');
             promptRun.NewRecord();
             promptRun.PromptID = judgePrompt.ID;
+            // We don't have a specific model ID for the judge yet, it will be set by AIPromptRunner
             promptRun.RunAt = new Date();
             promptRun.RunType = 'ResultSelector';
             promptRun.ParentID = parentPromptRunId;
             promptRun.ExecutionOrder = executionOrder;
+            // Store the judge data as JSON in Messages field
             promptRun.Messages = JSON.stringify({
                 judgeData,
                 candidateCount: Array.isArray(judgeData.candidates)
@@ -708,19 +928,24 @@ class ParallelExecutionCoordinator {
             const saveResult = await promptRun.Save();
             if (!saveResult) {
                 const error = `Failed to save ResultSelector AIPromptRun: ${promptRun.LatestResult?.Message || 'Unknown error'}`;
-                (0, core_1.LogError)(error);
+                LogError(error);
                 throw new Error(error);
             }
             return promptRun;
         }
         catch (error) {
-            (0, core_1.LogError)(`Error creating result selector prompt run record: ${error.message}`);
+            LogError(`Error creating result selector prompt run record: ${error.message}`);
             throw error;
         }
     }
+    /**
+     * Creates a delay for the specified number of milliseconds.
+     *
+     * @param ms - Number of milliseconds to delay
+     * @returns Promise<void> - Promise that resolves after the delay
+     */
     delay(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
 }
-exports.ParallelExecutionCoordinator = ParallelExecutionCoordinator;
 //# sourceMappingURL=ParallelExecutionCoordinator.js.map