@memberjunction/ai-prompts 3.3.0 → 4.0.0

package/dist/AIPromptRunner.js

@@ -1,85 +1,77 @@
-"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.LoadAIPromptRunner = exports.AIPromptRunner = void 0;
-const ai_1 = require("@memberjunction/ai");
-const ai_core_plus_1 = require("@memberjunction/ai-core-plus");
-const core_1 = require("@memberjunction/core");
-const global_1 = require("@memberjunction/global");
-const credentials_1 = require("@memberjunction/credentials");
-const templates_1 = require("@memberjunction/templates");
-const ExecutionPlanner_1 = require("./ExecutionPlanner");
-const ParallelExecutionCoordinator_1 = require("./ParallelExecutionCoordinator");
-const aiengine_1 = require("@memberjunction/aiengine");
-const ai_core_plus_2 = require("@memberjunction/ai-core-plus");
-const JSON5 = __importStar(require("json5"));
-class AIPromptRunner {
+import { BaseLLM, ChatParams, ChatMessageRole, GetAIAPIKey, ErrorAnalyzer } from '@memberjunction/ai';
+import { AIModelSelectionInfo } from '@memberjunction/ai-core-plus';
+import { LogErrorEx, LogStatus, LogStatusEx, IsVerboseLoggingEnabled, Metadata } from '@memberjunction/core';
+import { CleanJSON, MJGlobal, JSONValidator, ValidationResult, ValidationErrorInfo, ValidationErrorType } from '@memberjunction/global';
+import { CredentialEngine } from '@memberjunction/credentials';
+import { TemplateEngineServer } from '@memberjunction/templates';
+import { ExecutionPlanner } from './ExecutionPlanner.js';
+import { ParallelExecutionCoordinator } from './ParallelExecutionCoordinator.js';
+import { AIEngine } from '@memberjunction/aiengine';
+import { SystemPlaceholderManager } from '@memberjunction/ai-core-plus';
+import * as JSON5 from 'json5';
+export class AIPromptRunner {
     constructor() {
-        this._metadata = new core_1.Metadata();
-        this._templateEngine = templates_1.TemplateEngineServer.Instance;
-        this._executionPlanner = new ExecutionPlanner_1.ExecutionPlanner();
-        this._parallelCoordinator = new ParallelExecutionCoordinator_1.ParallelExecutionCoordinator();
-        this._jsonValidator = new global_1.JSONValidator();
-    }
+        this._metadata = new Metadata();
+        this._templateEngine = TemplateEngineServer.Instance;
+        this._executionPlanner = new ExecutionPlanner();
+        this._parallelCoordinator = new ParallelExecutionCoordinator();
+        this._jsonValidator = new JSONValidator();
+    }
+    /**
+     * Performs robust validation of an API key
+     * @returns true if the API key is valid (not null, undefined, or empty/whitespace)
+     */
     isValidAPIKey(apiKey) {
         if (apiKey === undefined || apiKey === null) {
             return false;
         }
+        // Check if it's just whitespace
         const trimmed = apiKey.trim();
         return trimmed.length > 0;
     }
+    /**
+     * Internal logging helper that wraps LogStatusEx with verbose control
+     * @param message The message to log
+     * @param verboseOnly Whether this is a verbose-only message
+     * @param params Optional prompt parameters for custom verbose check
+     */
     logStatus(message, verboseOnly = false, params) {
         if (verboseOnly) {
-            (0, core_1.LogStatusEx)({
+            LogStatusEx({
                 message,
                 verboseOnly: true,
-                isVerboseEnabled: () => params?.verbose === true || (0, core_1.IsVerboseLoggingEnabled)()
+                isVerboseEnabled: () => params?.verbose === true || IsVerboseLoggingEnabled()
             });
         }
         else {
-            (0, core_1.LogStatus)(message);
+            LogStatus(message);
         }
     }
+    /**
+     * Helper method for enhanced error logging with metadata
+     */
     logError(error, options) {
         let errorMessage = error instanceof Error ? error.message : error;
         const errorObj = error instanceof Error ? error : undefined;
+        // Truncate extremely long error messages (like Groq's failed_generation JSON dumps)
+        // Only truncate if maxErrorLength is explicitly set
         if (options?.maxErrorLength !== undefined && errorMessage.length > options.maxErrorLength) {
             errorMessage = errorMessage.substring(0, options.maxErrorLength) + '... [truncated]';
         }
         const metadata = {
             ...options?.metadata
         };
+        // Add prompt information if available
         if (options?.prompt) {
             metadata.promptId = options.prompt.ID;
             metadata.promptName = options.prompt.Name;
         }
+        // Add model information if available
         if (options?.model) {
             metadata.modelId = options.model.ID;
             metadata.modelName = options.model.Name;
         }
-        (0, core_1.LogErrorEx)({
+        LogErrorEx({
             message: errorMessage,
             error: errorObj,
             category: options?.category || 'AIPromptRunner',
@@ -87,46 +79,81 @@ class AIPromptRunner {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined
         });
     }
+    /**
+     * Checks if a model vendor is configured as an inference provider
+     * @param modelVendor The model vendor to check
+     * @returns true if the vendor is an inference provider
+     */
     isInferenceProvider(modelVendor) {
-        const inferenceProviderType = aiengine_1.AIEngine.Instance.VendorTypeDefinitions.find(vt => vt.Name === 'Inference Provider');
+        // Find the inference provider type from cached vendor type definitions
+        const inferenceProviderType = AIEngine.Instance.VendorTypeDefinitions.find(vt => vt.Name === 'Inference Provider');
         if (!inferenceProviderType) {
-            const modelDeveloperType = aiengine_1.AIEngine.Instance.VendorTypeDefinitions.find(vt => vt.Name === 'Model Developer');
+            // Fallback to checking if it's not a model developer (should rarely happen)
+            const modelDeveloperType = AIEngine.Instance.VendorTypeDefinitions.find(vt => vt.Name === 'Model Developer');
             return modelVendor.TypeID !== modelDeveloperType?.ID;
         }
         return modelVendor.TypeID === inferenceProviderType.ID;
     }
+    /**
+     * Resolves credentials for AI model execution using a hierarchical resolution system.
+     *
+     * Resolution priority (highest to lowest):
+     * 1. Per-request override: params.credentialId
+     * 2. Prompt-Model specific: AIPromptModel.CredentialID
+     * 3. Model-Vendor specific: AIModelVendor.CredentialID
+     * 4. Vendor default: AIVendor.CredentialID
+     * 5. Legacy: params.apiKeys[] array
+     * 6. Legacy: AI_VENDOR_API_KEY__<DRIVER> environment variables
+     *
+     * IMPORTANT: When ANY credential ID is found (priorities 1-4), the system uses
+     * the Credentials path and ignores legacy methods (priorities 5-6).
+     *
+     * @param driverClass - The driver class name (e.g., 'OpenAILLM')
+     * @param promptId - The prompt ID for looking up AIPromptModel credentials
+     * @param modelId - The model ID for looking up AIPromptModel and AIModelVendor credentials
+     * @param vendorId - The vendor ID for looking up AIModelVendor and AIVendor credentials
+     * @param params - The prompt execution parameters containing contextUser and optional credentialId
+     * @returns The API key/configuration string to pass to the LLM constructor
+     */
     async resolveCredentialForExecution(driverClass, promptId, modelId, vendorId, params) {
-        const verbose = params.verbose === true || (0, core_1.IsVerboseLoggingEnabled)();
+        const verbose = params.verbose === true || IsVerboseLoggingEnabled();
+        // Priority 1: Per-request override - no failover, explicit choice
         if (params.credentialId) {
             return await this.resolveCredentialById(params.credentialId, 'per-request override', params, verbose);
         }
-        await credentials_1.CredentialEngine.Instance.Config(false, params.contextUser);
+        // Ensure CredentialEngine is configured for binding lookups
+        await CredentialEngine.Instance.Config(false, params.contextUser);
+        // Priority 2: PromptModel bindings (most specific) - with failover
         if (promptId && modelId) {
-            const promptModel = aiengine_1.AIEngine.Instance.PromptModels.find(pm => pm.PromptID === promptId && pm.ModelID === modelId);
+            const promptModel = AIEngine.Instance.PromptModels.find(pm => pm.PromptID === promptId && pm.ModelID === modelId);
             if (promptModel) {
-                const bindings = aiengine_1.AIEngine.Instance.GetCredentialBindingsForTarget('PromptModel', promptModel.ID);
+                const bindings = AIEngine.Instance.GetCredentialBindingsForTarget('PromptModel', promptModel.ID);
                 const result = await this.tryCredentialBindingsWithFailover(bindings, 'AICredentialBinding(PromptModel)', params, verbose);
                 if (result)
                     return result;
             }
         }
+        // Priority 3: ModelVendor bindings - with failover
         if (modelId && vendorId) {
-            const modelVendor = aiengine_1.AIEngine.Instance.ModelVendors.find(mv => mv.ModelID === modelId && mv.VendorID === vendorId && mv.Status === 'Active');
+            const modelVendor = AIEngine.Instance.ModelVendors.find(mv => mv.ModelID === modelId && mv.VendorID === vendorId && mv.Status === 'Active');
             if (modelVendor) {
-                const bindings = aiengine_1.AIEngine.Instance.GetCredentialBindingsForTarget('ModelVendor', modelVendor.ID);
+                const bindings = AIEngine.Instance.GetCredentialBindingsForTarget('ModelVendor', modelVendor.ID);
                 const result = await this.tryCredentialBindingsWithFailover(bindings, 'AICredentialBinding(ModelVendor)', params, verbose);
                 if (result)
                     return result;
             }
         }
+        // Priority 4: Vendor bindings - with failover
         if (vendorId) {
-            const bindings = aiengine_1.AIEngine.Instance.GetCredentialBindingsForTarget('Vendor', vendorId);
+            const bindings = AIEngine.Instance.GetCredentialBindingsForTarget('Vendor', vendorId);
             const result = await this.tryCredentialBindingsWithFailover(bindings, 'AICredentialBinding(Vendor)', params, verbose);
             if (result)
                 return result;
         }
+        // Priority 5: Type-based default credential
+        // If the vendor declares a CredentialTypeID, try to find a default credential of that type
         if (vendorId) {
-            const vendor = aiengine_1.AIEngine.Instance.Vendors.find(v => v.ID === vendorId);
+            const vendor = AIEngine.Instance.Vendors.find(v => v.ID === vendorId);
             if (vendor?.CredentialTypeID) {
                 const defaultCredential = this.findDefaultCredentialByType(vendor.CredentialTypeID);
                 if (defaultCredential) {
@@ -136,31 +163,42 @@ class AIPromptRunner {
                 }
             }
         }
+        // No credential bindings found - fall back to legacy methods
         if (verbose) {
             this.logStatus(`   Using legacy API key resolution for driver ${driverClass}`, true, params);
         }
-        return (0, ai_1.GetAIAPIKey)(driverClass, params.apiKeys, verbose);
+        // Priority 6 & 7: Legacy apiKeys array and environment variables
+        return GetAIAPIKey(driverClass, params.apiKeys, verbose);
     }
+    /**
+     * Attempts to resolve credentials from bindings with priority-based failover.
+     * Tries each binding in priority order until one succeeds.
+     */
     async tryCredentialBindingsWithFailover(bindings, source, params, verbose) {
         if (bindings.length === 0)
             return null;
         for (let i = 0; i < bindings.length; i++) {
             const binding = bindings[i];
-            const credential = credentials_1.CredentialEngine.Instance.getCredentialById(binding.CredentialID);
+            const credential = CredentialEngine.Instance.getCredentialById(binding.CredentialID);
             if (!credential) {
                 if (verbose) {
                     this.logStatus(`   ⚠️ Credential ${binding.CredentialID} not found (priority ${binding.Priority}), trying next...`, true, params);
                 }
                 continue;
             }
-            const result = await this.tryResolveCredential(credential, `${source} priority ${binding.Priority}`, params, verbose, i < bindings.length - 1);
+            const result = await this.tryResolveCredential(credential, `${source} priority ${binding.Priority}`, params, verbose, i < bindings.length - 1 // hasMoreBindings
+            );
             if (result)
                 return result;
         }
         return null;
     }
+    /**
+     * Attempts to resolve a single credential, returning null on failure for failover support.
+     */
     async tryResolveCredential(credential, source, params, verbose, hasMoreBindings = false) {
         try {
+            // Check if credential is active and not expired
             if (!credential.IsActive) {
                 if (verbose) {
                     this.logStatus(`   ⚠️ Credential "${credential.Name}" is inactive, trying next...`, true, params);
@@ -173,7 +211,8 @@ class AIPromptRunner {
                 }
                 return null;
             }
-            const resolved = await credentials_1.CredentialEngine.Instance.getCredential(credential.Name, {
+            // Resolve the credential values
+            const resolved = await CredentialEngine.Instance.getCredential(credential.Name, {
                 credentialId: credential.ID,
                 contextUser: params.contextUser,
                 subsystem: 'AIPromptRunner'
@@ -185,12 +224,14 @@ class AIPromptRunner {
         }
         catch (error) {
             if (hasMoreBindings) {
+                // More bindings to try - log warning and continue
                 if (verbose) {
                     this.logStatus(`   ⚠️ Failed to resolve credential "${credential.Name}" from ${source}: ${error instanceof Error ? error.message : String(error)}, trying next...`, true, params);
                 }
                 return null;
             }
             else {
+                // No more bindings - log error but still return null for legacy fallback
                 this.logError(error instanceof Error ? error : new Error(String(error)), {
                     category: 'CredentialResolution',
                     severity: 'warning',
@@ -205,13 +246,17 @@ class AIPromptRunner {
             }
         }
     }
+    /**
+     * Resolves a credential by its explicit ID (used for per-request override).
+     * This does not support failover since it's an explicit choice.
+     */
     async resolveCredentialById(credentialId, source, params, verbose) {
-        await credentials_1.CredentialEngine.Instance.Config(false, params.contextUser);
-        const credential = credentials_1.CredentialEngine.Instance.getCredentialById(credentialId);
+        await CredentialEngine.Instance.Config(false, params.contextUser);
+        const credential = CredentialEngine.Instance.getCredentialById(credentialId);
         if (!credential) {
             throw new Error(`Credential with ID ${credentialId} not found`);
         }
-        const resolved = await credentials_1.CredentialEngine.Instance.getCredential(credential.Name, {
+        const resolved = await CredentialEngine.Instance.getCredential(credential.Name, {
             credentialId,
             contextUser: params.contextUser,
             subsystem: 'AIPromptRunner'
@@ -221,36 +266,66 @@ class AIPromptRunner {
         }
         return JSON.stringify(resolved.values);
     }
+    /**
+     * Finds a default credential matching a specific credential type.
+     */
     findDefaultCredentialByType(credentialTypeId) {
-        const credentials = credentials_1.CredentialEngine.Instance.Credentials;
+        const credentials = CredentialEngine.Instance.Credentials;
         return credentials.find(c => c.CredentialTypeID === credentialTypeId &&
             c.IsDefault === true &&
             c.IsActive === true &&
             (!c.ExpiresAt || new Date(c.ExpiresAt) > new Date())) || null;
     }
+    /**
+     * Checks if credentials are available for a given model-vendor combination.
+     * This is a pre-flight check used during model selection to determine which
+     * candidates have valid authentication configured.
+     *
+     * Checks the credential hierarchy:
+     * 1. Per-request override: params.credentialId
+     * 2. PromptModel bindings: AICredentialBinding WHERE BindingType='PromptModel'
+     * 3. ModelVendor bindings: AICredentialBinding WHERE BindingType='ModelVendor'
+     * 4. Vendor bindings: AICredentialBinding WHERE BindingType='Vendor'
+     * 5. Type-based default: Credential.IsDefault=1 matching AIVendor.CredentialTypeID
+     * 6. Legacy: params.apiKeys[] array
+     * 7. Legacy: AI_VENDOR_API_KEY__<DRIVER> environment variables
+     *
+     * @param driverClass - The driver class name (e.g., 'OpenAILLM')
+     * @param promptId - The prompt ID for looking up AIPromptModel bindings
+     * @param modelId - The model ID for looking up AIPromptModel and AIModelVendor bindings
+     * @param vendorId - The vendor ID for looking up AIModelVendor and AIVendor bindings
+     * @param params - The prompt execution parameters
+     * @returns true if credentials are available, false otherwise
+     */
     hasCredentialsAvailable(driverClass, promptId, modelId, vendorId, params) {
+        // Priority 1: Per-request override
         if (params?.credentialId) {
+            // Assume valid if credential ID is provided - will be validated at execution time
             return true;
         }
+        // Priority 2: PromptModel bindings
         if (promptId && modelId) {
-            const promptModel = aiengine_1.AIEngine.Instance.PromptModels.find(pm => pm.PromptID === promptId && pm.ModelID === modelId);
-            if (promptModel && aiengine_1.AIEngine.Instance.HasCredentialBindings('PromptModel', promptModel.ID)) {
+            const promptModel = AIEngine.Instance.PromptModels.find(pm => pm.PromptID === promptId && pm.ModelID === modelId);
+            if (promptModel && AIEngine.Instance.HasCredentialBindings('PromptModel', promptModel.ID)) {
                 return true;
             }
         }
+        // Priority 3: ModelVendor bindings
         if (modelId && vendorId) {
-            const modelVendor = aiengine_1.AIEngine.Instance.ModelVendors.find(mv => mv.ModelID === modelId && mv.VendorID === vendorId && mv.Status === 'Active');
-            if (modelVendor && aiengine_1.AIEngine.Instance.HasCredentialBindings('ModelVendor', modelVendor.ID)) {
+            const modelVendor = AIEngine.Instance.ModelVendors.find(mv => mv.ModelID === modelId && mv.VendorID === vendorId && mv.Status === 'Active');
+            if (modelVendor && AIEngine.Instance.HasCredentialBindings('ModelVendor', modelVendor.ID)) {
                 return true;
             }
         }
+        // Priority 4: Vendor bindings
         if (vendorId) {
-            if (aiengine_1.AIEngine.Instance.HasCredentialBindings('Vendor', vendorId)) {
+            if (AIEngine.Instance.HasCredentialBindings('Vendor', vendorId)) {
                 return true;
             }
         }
+        // Priority 5: Type-based default credential
         if (vendorId) {
-            const vendor = aiengine_1.AIEngine.Instance.Vendors.find(v => v.ID === vendorId);
+            const vendor = AIEngine.Instance.Vendors.find(v => v.ID === vendorId);
             if (vendor?.CredentialTypeID) {
                 const defaultCredential = this.findDefaultCredentialByType(vendor.CredentialTypeID);
                 if (defaultCredential) {
@@ -258,12 +333,40 @@ class AIPromptRunner {
                 }
             }
         }
-        const apiKey = (0, ai_1.GetAIAPIKey)(driverClass, params?.apiKeys, params?.verbose);
+        // Priority 6 & 7: Legacy methods - check if API key is available
+        const apiKey = GetAIAPIKey(driverClass, params?.apiKeys, params?.verbose);
         return this.isValidAPIKey(apiKey);
     }
+    /**
+     * Executes an AI prompt with full support for templates, model selection, and validation.
+     *
+     * @param params Parameters for prompt execution
+     * @returns Promise<AIPromptRunResult<T>> The execution result with tracking information
+     *
+     * @example
+     * ```typescript
+     * // Execute with specific result type
+     * interface AnalysisResult {
+     *   sentiment: string;
+     *   score: number;
+     *   keywords: string[];
+     * }
+     *
+     * const result = await promptRunner.ExecutePrompt<AnalysisResult>({
+     *   prompt: sentimentPrompt,
+     *   data: { text: "Customer feedback text" }
+     * });
+     *
+     * if (result.success && result.result) {
+     *   // result.result is typed as AnalysisResult
+     *   console.log(`Sentiment: ${result.result.sentiment}, Score: ${result.result.score}`);
+     * }
+     * ```
+     */
     async ExecutePrompt(params) {
         const startTime = new Date();
         const promptRun = null;
+        // Check for cancellation at the start
         if (params.cancellationToken?.aborted) {
             const result = {
                 success: false,
@@ -279,6 +382,7 @@ class AIPromptRunner {
             return result;
         }
         try {
+            // Use the prompt entity directly from params
             const prompt = params.prompt;
             if (!prompt) {
                 throw new Error(`Prompt entity is required`);
@@ -287,42 +391,60 @@ class AIPromptRunner {
                 throw new Error(`Prompt ${prompt.Name} is not active (Status: ${prompt.Status})`);
             }
             let renderedPromptText = '';
+            // For hierarchical prompts, we need to create the parent prompt run first to get its ID
             let parentPromptRun;
             let selectedModel;
             let childTemplateRenderingResult;
             let modelSelectionInfo;
+            // Handle different prompt execution modes
             if (params.childPrompts && params.childPrompts.length > 0) {
+                // Hierarchical template composition mode - render child templates first, then compose
+                //this.logStatus(`🌳 Composing prompt with ${params.childPrompts.length} child templates in hierarchical mode`, true, params);
+                // Determine which prompt to use for model selection
                 let modelSelectionPrompt = prompt;
                 if (params.modelSelectionPrompt) {
                     modelSelectionPrompt = params.modelSelectionPrompt;
+                    //this.logStatus(`🎯 Using prompt "${modelSelectionPrompt.Name}" for model selection instead of parent prompt`, true, params);
                 }
+                // Select model using the appropriate prompt
                 const modelResult = await this.selectModel(modelSelectionPrompt, params.override?.modelId, params.contextUser, params.configurationId, params.override?.vendorId, params);
                 selectedModel = modelResult.model;
                 modelSelectionInfo = modelResult.selectionInfo;
                 if (!selectedModel) {
                     throw new Error(`No suitable model found for prompt ${modelSelectionPrompt.Name}`);
                 }
+                // Check if we have a system prompt override
                 if (params.systemPromptOverride) {
+                    // Use the override instead of rendering child templates and parent template
                     renderedPromptText = params.systemPromptOverride;
                     this.logStatus(`   Using system prompt override for prompt "${prompt.Name}" (bypassing hierarchical template rendering)`, true, params);
                 }
                 else {
+                    // Render all child prompt templates recursively
                     childTemplateRenderingResult = await this.renderChildPromptTemplates(params.childPrompts, params, params.cancellationToken);
+                    // Render the parent prompt with child templates embedded
                     renderedPromptText = await this.renderPromptWithChildTemplates(prompt, params, childTemplateRenderingResult.renderedTemplates);
                 }
+                // Create parent prompt run for the final composed prompt execution
                 parentPromptRun = await this.createPromptRun(prompt, selectedModel, params, renderedPromptText, startTime, params.override?.vendorId, modelSelectionInfo);
             }
             else if (prompt.TemplateID && (!params.conversationMessages || params.templateMessageRole !== 'none')) {
+                // Check if we have a system prompt override
                 if (params.systemPromptOverride) {
+                    // Use the override instead of rendering the template
                     renderedPromptText = params.systemPromptOverride;
                     this.logStatus(`   Using system prompt override for prompt "${prompt.Name}" (bypassing template rendering)`, true, params);
                 }
                 else {
+                    // Regular template rendering mode
+                    // Initialize template engine
                     await this._templateEngine.Config(false, params.contextUser);
+                    // Load the template for the prompt
                     const template = await this.loadTemplate(prompt.TemplateID, params.contextUser);
                     if (!template) {
                         throw new Error(`Template with ID ${prompt.TemplateID} not found for prompt ${prompt.Name}`);
                     }
+                    // Render the template with full params context
                     const renderedPrompt = await this.renderPromptTemplate(template, params);
                     if (!renderedPrompt.Success) {
                         throw new Error(`Failed to render template for prompt ${prompt.Name}: ${renderedPrompt.Message}`);
@@ -330,9 +452,11 @@ class AIPromptRunner {
                     renderedPromptText = renderedPrompt.Output;
                 }
             }
+            // Check for cancellation after template rendering
             if (params.cancellationToken?.aborted) {
                 throw new Error('Prompt execution was cancelled during template rendering');
             }
+            // If no model was selected yet (no template case), select one now
             if (!selectedModel) {
                 let modelSelectionPrompt = prompt;
                 if (params.modelSelectionPrompt) {
@@ -346,14 +470,20 @@ class AIPromptRunner {
                     throw new Error(`No suitable model found for prompt ${modelSelectionPrompt.Name}`);
                 }
             }
+            // Check if we need parallel execution based on ParallelizationMode
             const shouldUseParallelExecution = prompt.ParallelizationMode && prompt.ParallelizationMode !== 'None';
             let result;
             if (shouldUseParallelExecution) {
+                // Use parallel execution path
                 result = await this.executePromptInParallel(prompt, renderedPromptText, params, startTime, parentPromptRun, selectedModel, modelSelectionInfo);
             }
             else {
+                // Use traditional single execution path
                 result = await this.executeSinglePrompt(prompt, renderedPromptText, params, startTime, parentPromptRun, selectedModel, modelSelectionInfo);
             }
+            // Note: With template composition, we only execute once so no rollup calculations needed
+            // The final composed prompt is executed as a single operation
+            // Model selection info is now included in the result from both execution methods
             return result;
         }
         catch (error) {
@@ -367,10 +497,12 @@ class AIPromptRunner {
             });
             const endTime = new Date();
             const executionTimeMS = endTime.getTime() - startTime.getTime();
+            // Update prompt run with error if it was created
             if (promptRun) {
                 promptRun.CompletedAt = endTime;
                 promptRun.ExecutionTimeMS = executionTimeMS;
                 promptRun.Result = `ERROR: ${error.message}`;
+                // Set Status and Cancelled based on error type
                 if (error.message.includes('cancelled')) {
                     promptRun.Status = 'Cancelled';
                     promptRun.Cancelled = true;
@@ -404,10 +536,21 @@ class AIPromptRunner {
             return errorResult;
         }
     }
+    /**
+     * Executes a single prompt (non-parallel) using traditional model selection.
+     *
+     * @param prompt - The AI prompt to execute
+     * @param renderedPromptText - The rendered prompt text
+     * @param params - Original execution parameters
+     * @param startTime - Execution start time
+     * @returns Promise<AIPromptRunResult<T>> - The execution result
+     */
     async executeSinglePrompt(prompt, renderedPromptText, params, startTime, existingPromptRun, existingModel, existingModelSelectionInfo) {
+        // Check for cancellation before model selection
         if (params.cancellationToken?.aborted) {
             throw new Error('Prompt execution was cancelled before model selection');
         }
+        // Use existing model if provided (hierarchical case) or select one
         let selectedModel = existingModel;
         let modelSelectionInfo = existingModelSelectionInfo;
         let vendorDriverClass;
@@ -416,18 +559,21 @@ class AIPromptRunner {
         let modelEffortLevel;
         let allCandidates = [];
         if (modelSelectionInfo) {
+            // we received model selection info, need to lookup vendor driver class and api name from there
             const vendorID = modelSelectionInfo.vendorSelected?.ID;
             const modelID = modelSelectionInfo.modelSelected.ID;
-            const modelVendor = aiengine_1.AIEngine.Instance.ModelVendors.find(mv => mv.VendorID === vendorID &&
+            const modelVendor = AIEngine.Instance.ModelVendors.find(mv => mv.VendorID === vendorID &&
                 mv.ModelID === modelID);
             if (modelVendor) {
                 vendorDriverClass = modelVendor.DriverClass;
                 vendorApiName = modelVendor.APIName;
                 vendorSupportsEffortLevel = modelVendor.SupportsEffortLevel;
             }
+            // Extract valid candidates from selection info for retry logic
             allCandidates = this.buildCandidatesFromSelectionInfo(modelSelectionInfo);
         }
         if (!selectedModel) {
+            // Determine which prompt to use for model selection
             let modelSelectionPrompt = prompt;
             if (params.modelSelectionPrompt) {
                 modelSelectionPrompt = params.modelSelectionPrompt;
@@ -445,34 +591,46 @@ class AIPromptRunner {
                 throw new Error(`No suitable model found for prompt ${modelSelectionPrompt.Name}`);
             }
         }
+        // Check for cancellation after model selection
         if (params.cancellationToken?.aborted) {
             throw new Error('Prompt execution was cancelled after model selection');
         }
+        // Use existing prompt run if provided (hierarchical case) or create new one
         const promptRun = existingPromptRun || await this.createPromptRun(prompt, selectedModel, params, renderedPromptText, startTime, params.override?.vendorId, modelSelectionInfo);
+        // Check for cancellation before model execution
         if (params.cancellationToken?.aborted) {
             throw new Error('Prompt execution was cancelled before model execution');
         }
-        const { modelResult, parsedResult, validationAttempts, cumulativeTokens } = await this.executeWithValidationRetries(selectedModel, renderedPromptText, prompt, params, promptRun, allCandidates, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel);
+        // Execute with retry logic for validation failures
+        const { modelResult, parsedResult, validationAttempts, cumulativeTokens } = await this.executeWithValidationRetries(selectedModel, renderedPromptText, prompt, params, promptRun, allCandidates, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel // Pass model-specific effort level
+        );
+        // Calculate execution metrics
         const endTime = new Date();
         const executionTimeMS = endTime.getTime() - startTime.getTime();
+        // Update the prompt run with results including validation attempts and cumulative tokens
         await this.updatePromptRun(promptRun, prompt, modelResult, parsedResult, endTime, executionTimeMS, validationAttempts, cumulativeTokens);
         const chatResult = modelResult;
         const usage = chatResult.data?.usage;
+        // CRITICAL: Populate errorMessage field when execution fails
+        // This ensures errors are properly propagated to BaseAgent and visible in AgentRunStep logs
         let errorMessage;
         if (!chatResult.success) {
+            // Model execution failed
             errorMessage = chatResult.errorMessage;
         }
         else if (parsedResult.validationResult?.Success === false) {
+            // Validation failed (Warn or Strict mode)
             errorMessage = `Validation failed: ${parsedResult.validationResult.Errors?.map(e => e.Message).join('; ')}`;
         }
         return {
             success: chatResult.success,
             rawResult: chatResult.data?.choices?.[0]?.message?.content,
             result: parsedResult?.result ? parsedResult.result : parsedResult,
-            errorMessage,
+            errorMessage, // Include error message for proper error propagation
             chatResult,
             promptRun,
             executionTimeMS,
+            // Use cumulative tokens if retries occurred, otherwise use single attempt tokens
             promptTokens: cumulativeTokens.promptTokens || usage?.promptTokens,
             completionTokens: cumulativeTokens.completionTokens || usage?.completionTokens,
             tokensUsed: (cumulativeTokens.promptTokens + cumulativeTokens.completionTokens) || ((usage?.promptTokens || 0) + (usage?.completionTokens || 0)),
@@ -481,21 +639,35 @@ class AIPromptRunner {
             validationResult: parsedResult.validationResult,
             validationAttempts,
             combinedTokensUsed: (cumulativeTokens.promptTokens + cumulativeTokens.completionTokens) || ((usage?.promptTokens || 0) + (usage?.completionTokens || 0)),
-            modelSelectionInfo
+            modelSelectionInfo // Include model selection info if available
         };
     }
+    /**
+     * Executes a prompt using parallel execution with multiple models/tasks.
+     *
+     * @param prompt - The AI prompt to execute
+     * @param renderedPromptText - The rendered prompt text
+     * @param params - Original execution parameters
+     * @param startTime - Execution start time
+     * @returns Promise<AIPromptRunResult<T>> - The aggregated execution result
+     */
     async executePromptInParallel(prompt, renderedPromptText, params, startTime, existingPromptRun, existingModel, existingModelSelectionInfo) {
+        // Check for cancellation before starting parallel execution
         if (params.cancellationToken?.aborted) {
             throw new Error('Parallel execution was cancelled before starting');
         }
-        await aiengine_1.AIEngine.Instance.Config(false, params.contextUser);
+        // Load AI Engine to get models and prompt models
+        await AIEngine.Instance.Config(false, params.contextUser);
         let executionTasks;
+        // If a model is already selected (from hierarchical template composition), 
+        // create a single task with that model instead of using the planner
         if (existingModel) {
+            // Create a single execution task with the pre-selected model
             executionTasks = [{
                     taskId: 'pre-selected',
                     model: existingModel,
-                    vendorDriverClass: undefined,
-                    vendorApiName: existingModel.Vendor,
+                    vendorDriverClass: undefined, // Would need to look up vendor entity for this
+                    vendorApiName: existingModel.Vendor, // Vendor is already the name string
                     messages: params.conversationMessages || [],
                     promptText: renderedPromptText,
                     templateMessageRole: params.templateMessageRole || 'system',
@@ -504,31 +676,39 @@ class AIPromptRunner {
             this.logStatus(`   Using pre-selected model "${existingModel.Name}" for parallel execution`, true, params);
         }
         else {
+            // Normal parallel execution path - let the planner decide
+            // Determine which prompt to use for model selection
             let modelSelectionPrompt = prompt;
             if (params.modelSelectionPrompt) {
                 modelSelectionPrompt = params.modelSelectionPrompt;
                 this.logStatus(`   Using prompt "${modelSelectionPrompt.Name}" for model selection in parallel execution`, true, params);
             }
-            const promptModels = aiengine_1.AIEngine.Instance.PromptModels.filter((pm) => pm.PromptID === modelSelectionPrompt.ID &&
+            // Get prompt-specific model associations using the model selection prompt
+            const promptModels = AIEngine.Instance.PromptModels.filter((pm) => pm.PromptID === modelSelectionPrompt.ID &&
                 (pm.Status === 'Active' || pm.Status === 'Preview') &&
                 (!params.configurationId || !pm.ConfigurationID || pm.ConfigurationID === params.configurationId));
-            executionTasks = this._executionPlanner.createExecutionPlan(modelSelectionPrompt, promptModels, aiengine_1.AIEngine.Instance.Models, renderedPromptText, params.contextUser, params.configurationId, params.conversationMessages, params.templateMessageRole || 'system');
+            // Create execution plan using the modelSelectionPrompt for model configurations
+            executionTasks = this._executionPlanner.createExecutionPlan(modelSelectionPrompt, promptModels, AIEngine.Instance.Models, renderedPromptText, params.contextUser, params.configurationId, params.conversationMessages, params.templateMessageRole || 'system');
         }
         if (executionTasks.length === 0) {
             throw new Error(`No execution tasks created for parallel execution of prompt ${prompt.Name}`);
         }
+        // Check for cancellation before executing tasks
         if (params.cancellationToken?.aborted) {
             throw new Error('Parallel execution was cancelled before task execution');
         }
+        // Execute tasks in parallel
         const parallelResult = await this._parallelCoordinator.executeTasksInParallel(params, executionTasks, undefined, undefined, params.cancellationToken, undefined, params.agentRunId);
         if (!parallelResult.success) {
             throw new Error(`Parallel execution failed: ${parallelResult.errors.join(', ')}`);
         }
+        // Select best result if multiple successful results
         const successfulResults = parallelResult.taskResults.filter((r) => r.success);
         if (successfulResults.length === 0) {
             throw new Error(`No successful results from parallel execution`);
         }
-        let selectedResult = successfulResults[0];
+        let selectedResult = successfulResults[0]; // Default to first
+        // Use result selector if configured
         if (successfulResults.length > 1 && prompt.ResultSelectorPromptID) {
             const selectionConfig = {
                 method: 'PromptSelector',
@@ -539,6 +719,7 @@ class AIPromptRunner {
                 selectedResult = aiSelectedResult;
             }
         }
+        // Calculate total tokens and costs from all parallel executions
         let totalPromptTokens = 0;
         let totalCompletionTokens = 0;
         let totalCost = 0;
@@ -554,12 +735,16 @@ class AIPromptRunner {
                 }
             }
         }
+        // Use existing prompt run if provided (hierarchical case) or create new one
+        // Use the model selection info if provided (from hierarchical execution)
         const consolidatedPromptRun = existingPromptRun || await this.createPromptRun(prompt, selectedResult.task.model, params, renderedPromptText, startTime, params.override?.vendorId, existingModelSelectionInfo);
+        // Update with parallel execution metadata
         const endTime = new Date();
         consolidatedPromptRun.CompletedAt = endTime;
         consolidatedPromptRun.ExecutionTimeMS = parallelResult.totalExecutionTimeMS;
         consolidatedPromptRun.Result = selectedResult.rawResult || '';
         consolidatedPromptRun.TokensUsed = parallelResult.totalTokensUsed;
+        // Extract token and cost info from selected result
         const selectedResultUsage = selectedResult.modelResult?.data?.usage;
         if (selectedResultUsage) {
             consolidatedPromptRun.TokensPrompt = selectedResultUsage.promptTokens;
@@ -571,6 +756,7 @@ class AIPromptRunner {
                 consolidatedPromptRun.CostCurrency = selectedResultUsage.costCurrency;
             }
         }
+        // Add parallel execution metadata to Messages field
         const parallelMetadata = {
             parallelizationMode: prompt.ParallelizationMode,
             totalTasks: executionTasks.length,
@@ -587,14 +773,16 @@ class AIPromptRunner {
                 messages: params.conversationMessages || [],
             });
         }
+        // For parallel execution, set rollup fields to match totals (no child execution to roll up)
         consolidatedPromptRun.TokensPromptRollup = totalPromptTokens;
         consolidatedPromptRun.TokensCompletionRollup = totalCompletionTokens;
         consolidatedPromptRun.TokensUsedRollup = totalPromptTokens + totalCompletionTokens;
         if (hasCost) {
             consolidatedPromptRun.TotalCost = totalCost;
         }
+        // Set Status and WasSelectedResult for parallel execution
         consolidatedPromptRun.Status = parallelResult.successCount > 0 ? 'Completed' : 'Failed';
-        consolidatedPromptRun.WasSelectedResult = true;
+        consolidatedPromptRun.WasSelectedResult = true; // This is the consolidated result chosen by judge
         const saveResult = await consolidatedPromptRun.Save();
         if (!saveResult) {
             this.logError(`Failed to save consolidated AIPromptRun: ${consolidatedPromptRun.LatestResult?.CompleteMessage || 'Unknown error'}`, {
@@ -607,7 +795,9 @@ class AIPromptRunner {
                 maxErrorLength: params.maxErrorLength
             });
         }
+        // Create additional results from all other successful results (excluding the best one)
         const additionalResults = [];
+        // Sort successful results by ranking (if available) or keep original order
         const sortedResults = successfulResults.sort((a, b) => {
             if (a.ranking && b.ranking) {
                 return a.ranking - b.ranking;
@@ -616,6 +806,7 @@ class AIPromptRunner {
         });
         for (const result of sortedResults) {
             if (result.task.taskId !== selectedResult.task.taskId) {
+                // Parse and validate this result
                 const { result: parsedResultData, validationResult } = await this.parseAndValidateResultEnhanced(result.modelResult, prompt, params.skipValidation, params.cleanValidationSyntax, consolidatedPromptRun, params);
                 const parsedResult = { result: parsedResultData, validationResult };
                 const resultUsage = result.modelResult?.data?.usage;
@@ -636,13 +827,14 @@ class AIPromptRunner {
                     modelInfo: {
                         modelId: result.task.model.ID,
                         modelName: result.task.model.Name,
-                        vendorId: undefined,
+                        vendorId: undefined, // VendorID not directly available on AIModel
                         vendorName: result.task.model.Vendor,
                     },
                     combinedTokensUsed: (resultUsage?.promptTokens || 0) + (resultUsage?.completionTokens || 0)
                 });
             }
         }
+        // Parse and validate the selected result
         const { result: selectedResultData, validationResult: selectedValidationResult } = await this.parseAndValidateResultEnhanced(selectedResult.modelResult, prompt, params.skipValidation, params.cleanValidationSyntax, consolidatedPromptRun, params);
         const selectedParsedResult = { result: selectedResultData, validationResult: selectedValidationResult };
         const selectedUsage = selectedResult.modelResult?.data?.usage;
@@ -658,6 +850,7 @@ class AIPromptRunner {
             tokensUsed: (selectedUsage?.promptTokens || 0) + (selectedUsage?.completionTokens || 0),
             cost: selectedUsage?.cost,
             costCurrency: selectedUsage?.costCurrency,
+            // Combined totals for parallel execution
             combinedPromptTokens: totalPromptTokens,
             combinedCompletionTokens: totalCompletionTokens,
             combinedTokensUsed: totalPromptTokens + totalCompletionTokens,
@@ -669,15 +862,19 @@ class AIPromptRunner {
             modelInfo: {
                 modelId: selectedResult.task.model.ID,
                 modelName: selectedResult.task.model.Name,
-                vendorId: existingModelSelectionInfo?.vendorSelected?.ID,
+                vendorId: existingModelSelectionInfo?.vendorSelected?.ID, // VendorID not directly available on AIModel
                 vendorName: selectedResult.task.model.Vendor,
             },
             judgeMetadata: selectedResult.judgeMetadata,
-            modelSelectionInfo: existingModelSelectionInfo,
+            modelSelectionInfo: existingModelSelectionInfo, // Include model selection info if provided
         };
     }
+    /**
+     * Loads a template entity by ID
+     */
     async loadTemplate(templateId, _contextUser) {
         try {
+            // Use the template engine to find the template
             const template = this._templateEngine.Templates.find((t) => t.ID === templateId);
             return template || null;
         }
@@ -692,41 +889,61 @@ class AIPromptRunner {
             return null;
         }
     }
+    /**
+     * Renders child prompt templates in a depth-first manner, composing them into a final template.
+     *
+     * @param childPrompts - Array of child prompts to render templates for
+     * @param params - Original execution parameters for context
+     * @param cancellationToken - Cancellation token for aborting rendering
+     * @returns Promise with rendered templates map
+     */
     async renderChildPromptTemplates(childPrompts, params, cancellationToken) {
         if (!childPrompts || childPrompts.length === 0) {
             return {
                 renderedTemplates: {}
             };
         }
+        // Check for cancellation
         if (cancellationToken?.aborted) {
             throw new Error('Child prompt execution was cancelled');
         }
+        //this.logStatus(`🔄 Rendering ${childPrompts.length} child prompt templates in parallel`, true, params);
+        // Render all child prompt templates in parallel at this level
         const childRenderingPromises = childPrompts.map(async (childParam) => {
             try {
+                // Check for cancellation before each child rendering
                 if (cancellationToken?.aborted) {
                     throw new Error('Child prompt template rendering was cancelled');
                 }
+                // First, recursively render any grandchild prompt templates
                 let childData = { ...childParam.childPrompt.data };
                 if (childParam.childPrompt.childPrompts && childParam.childPrompt.childPrompts.length > 0) {
                     const grandchildResults = await this.renderChildPromptTemplates(childParam.childPrompt.childPrompts, params, cancellationToken);
+                    // Merge grandchild rendered templates into the child's data context
                     childData = { ...childData, ...grandchildResults.renderedTemplates };
                 }
+                // Render the child prompt template with merged data
+                //this.logStatus(`  🔹 Rendering child prompt template: ${childParam.childPrompt.prompt.Name} -> ${childParam.parentPlaceholder}`, true, params);
                 const childPrompt = childParam.childPrompt.prompt;
                 let renderedChildTemplate = '';
                 if (childPrompt.TemplateID) {
+                    // Initialize template engine if not already done
                     await this._templateEngine.Config(false, params.contextUser);
+                    // Load the template for the child prompt
                     const template = await this.loadTemplate(childPrompt.TemplateID, params.contextUser);
                     if (!template) {
                         throw new Error(`Template with ID ${childPrompt.TemplateID} not found for child prompt ${childPrompt.Name}`);
                     }
+                    // Merge child data with original params context
                     const mergedChildData = {
-                        ...params.data,
-                        ...childData,
-                        ...childParam.childPrompt.templateData
+                        ...params.data, // Original context
+                        ...childData, // Child-specific data with grandchildren
+                        ...childParam.childPrompt.templateData // Child template data
                     };
+                    // Render the child template
                     const childRenderResult = await this.renderPromptTemplate(template, {
-                        ...params,
-                        prompt: childPrompt,
+                        ...params, // spread original params
+                        prompt: childPrompt, // THEN, override the prompt for child so we get child related OUTPUT_EXAMPLE and anything else along those lines
                         data: mergedChildData,
                         templateData: childParam.childPrompt.templateData
                     });
@@ -736,8 +953,10 @@ class AIPromptRunner {
                     renderedChildTemplate = childRenderResult.Output;
                 }
                 else {
+                    // If no template, use empty string (child might be using conversation messages)
                     renderedChildTemplate = '';
                 }
+                // Return the placeholder name and rendered template
                 return {
                     placeholder: childParam.parentPlaceholder,
                     renderedTemplate: renderedChildTemplate,
@@ -752,6 +971,7 @@ class AIPromptRunner {
                     },
                     maxErrorLength: params.maxErrorLength
                 });
+                // Return error result but allow other children to continue
                 return {
                     placeholder: childParam.parentPlaceholder,
                     renderedTemplate: `ERROR: ${error.message}`,
@@ -759,7 +979,9 @@ class AIPromptRunner {
                 };
             }
         });
+        // Wait for all child template rendering to complete
         const childResults = await Promise.all(childRenderingPromises);
+        // Check if any critical errors occurred
         const failedChildren = childResults.filter(r => !r.success);
         if (failedChildren.length > 0) {
             this.logError(`${failedChildren.length} out of ${childResults.length} child prompt templates failed to render`, {
@@ -772,37 +994,57 @@ class AIPromptRunner {
                 },
                 maxErrorLength: params.maxErrorLength
             });
+            // any child render failure means we must throw an error
             throw new Error(`Failed to render ${failedChildren.length} child prompt templates: ${failedChildren.map(fc => fc.placeholder).join(', ')}`);
         }
+        // Build rendered templates map
         const renderedTemplatesMap = {};
         for (const childResult of childResults) {
             renderedTemplatesMap[childResult.placeholder] = childResult.renderedTemplate;
         }
+        //this.logStatus(`✅ Completed rendering of ${childResults.length} child prompt templates`, true, params);
         return {
             renderedTemplates: renderedTemplatesMap
         };
     }
+    /**
+     * Renders a prompt template with child prompt templates merged into the data context.
+     *
+     * @param prompt - The AI prompt to render
+     * @param params - Original execution parameters
+     * @param childTemplates - Map of placeholder names to rendered child prompt templates
+     * @returns Promise<string> - The rendered prompt text with child templates embedded
+     */
     async renderPromptWithChildTemplates(prompt, params, childTemplates) {
         if (!prompt.TemplateID) {
+            // If no template, return empty string (will be handled by conversation messages)
             return '';
         }
         try {
+            // Initialize template engine
             await this._templateEngine.Config(false, params.contextUser);
+            // Load the template for the prompt
             const template = await this.loadTemplate(prompt.TemplateID, params.contextUser);
             if (!template) {
                 throw new Error(`Template with ID ${prompt.TemplateID} not found for prompt ${prompt.Name}`);
             }
-            const systemPlaceholders = await ai_core_plus_2.SystemPlaceholderManager.resolveAllPlaceholders(params);
+            // Resolve system placeholders with full prompt context
+            const systemPlaceholders = await SystemPlaceholderManager.resolveAllPlaceholders(params);
+            // Merge all data sources with proper priority order
             const mergedData = {
-                ...systemPlaceholders,
-                ...params.data,
-                ...childTemplates,
-                ...params.templateData
+                ...systemPlaceholders, // System placeholders (lowest priority)
+                ...params.data, // Original data context
+                ...childTemplates, // Child prompt templates with placeholder names as keys
+                ...params.templateData // Additional template data (highest priority)
             };
             this.logStatus(`   🔧 ${prompt.Name} [Rendering Prompt Template]`, true, params);
+            // Log placeholder replacement for debugging
             for (const [placeholder, template] of Object.entries(childTemplates)) {
                 const truncatedTemplate = template.length > 100 ? template.substring(0, 100) + '...' : template;
+                //this.logStatus(`  📝 ${placeholder} -> ${truncatedTemplate}`, true, params);
             }
+            // Render the template with the full params context
+            // We already have system placeholders resolved, so we'll render directly
             const renderedPrompt = await this._templateEngine.RenderTemplate(template, template.GetHighestPriorityContent(), mergedData);
             if (!renderedPrompt.Success) {
                 throw new Error(`Failed to render template for prompt ${prompt.Name}: ${renderedPrompt.Message}`);
@@ -822,11 +1064,19 @@ class AIPromptRunner {
             throw error;
         }
     }
+    /**
+     * Selects the appropriate AI model based on prompt configuration and parameters.
+     * Uses the unified buildModelVendorCandidates method to create an ordered list of candidates,
+     * then selects the first one with an available API key.
+     */
     async selectModel(prompt, explicitModelId, contextUser, configurationId, vendorId, params) {
+        // Declare variables outside try block for catch block access
         let configurationName;
         let configuration;
         try {
-            await aiengine_1.AIEngine.Instance.Config(false, contextUser);
+            // Load AI Engine to access cached models and prompt models
+            await AIEngine.Instance.Config(false, contextUser);
+            // Determine selection strategy
             let selectionStrategy = 'Default';
             if (explicitModelId) {
                 selectionStrategy = 'Specific';
@@ -837,11 +1087,14 @@ class AIPromptRunner {
             else if (prompt.SelectionStrategy === 'ByPower' || prompt.MinPowerRank != null) {
                 selectionStrategy = 'ByPower';
             }
+            // Get configuration info if provided
             if (configurationId) {
-                configuration = aiengine_1.AIEngine.Instance.Configurations.find(c => c.ID === configurationId);
+                configuration = AIEngine.Instance.Configurations.find(c => c.ID === configurationId);
                 configurationName = configuration?.Name;
             }
+            // Build unified list of model-vendor candidates
             const candidates = this.buildModelVendorCandidates(prompt, explicitModelId, configurationId, vendorId, params.verbose);
+            // Track all models considered for selection info
             const modelsConsidered = [];
             if (candidates.length === 0) {
                 this.logError(`No suitable model candidates found for prompt ${prompt.Name}`, {
@@ -859,16 +1112,25 @@ class AIPromptRunner {
                     selectionInfo: this.createSelectionInfo({
                         aiConfiguration: configuration,
                         modelsConsidered: [],
-                        modelSelected: undefined,
+                        modelSelected: undefined, // Type requirement, but null model means no selection
                         selectionReason: 'No suitable model candidates found',
                         fallbackUsed: false,
                         selectionStrategy
                     })
                 };
             }
+            // this.logStatus(`🔍 Found ${candidates.length} model-vendor candidates for prompt ${prompt.Name}`, true, params);
+            // if (candidates.length <= 5) {
+            //   candidates.forEach((c, i) => {
+            //     this.logStatus(`   ${i + 1}. ${c.model.Name} via ${c.vendorName || 'default'} (${c.driverClass}) - Priority: ${c.priority}${c.isPreferredVendor ? ' [PREFERRED]' : ''}`, true, params);
+            //   });
+            // }
+            // Select the first candidate with available credentials and track all attempts
             const { selected, consideredModels } = await this.selectModelWithAPIKeyTracked(candidates, prompt.ID, params);
+            // Merge considered models into our tracking
             modelsConsidered.push(...consideredModels);
             if (!selected) {
+                // No models with API keys found
                 return {
                     model: null,
                     vendorDriverClass: undefined,
@@ -879,13 +1141,14 @@ class AIPromptRunner {
                     selectionInfo: this.createSelectionInfo({
                         aiConfiguration: configuration,
                         modelsConsidered,
-                        modelSelected: undefined,
+                        modelSelected: undefined, // Type requirement, but null model means no selection
                         selectionReason: 'No API keys found for any model-vendor combination',
                         fallbackUsed: false,
                         selectionStrategy
                     })
                 };
             }
+            // Determine selection reason
             let selectionReason = `Selected ${selected.model.Name} via ${selected.vendorName || 'default vendor'}`;
             if (selected.source === 'explicit') {
                 selectionReason = `Explicitly requested model ${selected.model.Name}`;
@@ -902,17 +1165,19 @@ class AIPromptRunner {
             if (selected.isPreferredVendor) {
                 selectionReason += ' using preferred vendor';
             }
+            // Check if fallback was used (not the first candidate)
             const fallbackUsed = candidates.indexOf(selected) > 0;
+            // Get selected vendor entity
             let selectedVendor;
             if (selected.vendorId) {
-                selectedVendor = aiengine_1.AIEngine.Instance.Vendors.find(v => v.ID === selected.vendorId);
+                selectedVendor = AIEngine.Instance.Vendors.find(v => v.ID === selected.vendorId);
             }
             return {
                 model: selected.model,
                 vendorDriverClass: selected.driverClass,
                 vendorApiName: selected.apiName,
                 vendorSupportsEffortLevel: selected.supportsEffortLevel,
-                modelEffortLevel: selected.effortLevel,
+                modelEffortLevel: selected.effortLevel, // Pass through model-specific effort level
                 allCandidates: candidates,
                 selectionInfo: this.createSelectionInfo({
                     aiConfiguration: configuration,
@@ -941,7 +1206,7 @@ class AIPromptRunner {
                 selectionInfo: this.createSelectionInfo({
                     aiConfiguration: configuration,
                     modelsConsidered: [],
-                    modelSelected: undefined,
+                    modelSelected: undefined, // Type requirement, but null model means no selection
                     selectionReason: `Error during model selection: ${error.message}`,
                     fallbackUsed: false,
                     selectionStrategy: 'Default'
@@ -949,20 +1214,43 @@ class AIPromptRunner {
             };
         }
     }
+    /**
+     * Builds a unified, ordered list of model-vendor candidates based on all selection criteria.
+     * Uses a 3-phase approach to properly handle SelectionStrategy='Specific' with AIPromptModel priorities.
+     *
+     * Phase 1: Handle explicit model ID (highest priority)
+     * Phase 2: Check if SelectionStrategy='Specific' with AIPromptModel entries - use ONLY those with AIPromptModel priorities
+     * Phase 3: Use general selection strategy (fallback) - blended priorities from legacy behavior
+     *
+     * @param prompt - The AI prompt with selection criteria
+     * @param explicitModelId - Explicitly specified model ID (highest priority)
+     * @param configurationId - Configuration ID for filtering
+     * @param preferredVendorId - Preferred vendor ID
+     * @returns Ordered array of model-vendor candidates (highest priority first)
+     */
     buildModelVendorCandidates(prompt, explicitModelId, configurationId, preferredVendorId, verbose) {
+        // PHASE 1: Handle explicit model ID (highest priority)
         if (explicitModelId) {
             return this.buildCandidatesForExplicitModel(explicitModelId, prompt, preferredVendorId);
         }
+        // PHASE 2: SelectionStrategy='Specific' - Use explicit AIPromptModel configuration
         if (prompt.SelectionStrategy === 'Specific') {
             return this.buildCandidatesForSpecificStrategy(prompt, configurationId, verbose);
         }
+        // PHASE 3: Build candidates with configuration-aware fallback hierarchy
+        // (SelectionStrategy='Default' or 'ByPower')
         return this.buildCandidatesForGeneralSelection(prompt, configurationId, preferredVendorId, verbose);
     }
+    /**
+     * PHASE 1: Build candidates for explicitly specified model ID.
+     * Returns candidates for the single model if it's active and compatible.
+     */
     buildCandidatesForExplicitModel(explicitModelId, prompt, preferredVendorId) {
-        const model = aiengine_1.AIEngine.Instance.Models.find(m => m.ID === explicitModelId);
+        const model = AIEngine.Instance.Models.find(m => m.ID === explicitModelId);
         if (!model || !model.IsActive) {
             return [];
         }
+        // Check model type compatibility
         if (prompt.AIModelTypeID && model.AIModelTypeID !== prompt.AIModelTypeID) {
             return [];
         }
@@ -970,85 +1258,130 @@ class AIPromptRunner {
         candidates.sort((a, b) => b.priority - a.priority);
         return candidates;
     }
+    /**
+     * PHASE 2: Build candidates for 'Specific' selection strategy.
+     * Uses AIPromptModel configuration with clean ranking:
+     * 1. Config-matching models first (by priority DESC)
+     * 2. Then universal (null config) models (by priority DESC)
+     */
     buildCandidatesForSpecificStrategy(prompt, configurationId, verbose) {
-        const allPromptModels = aiengine_1.AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID && (pm.Status === 'Active' || pm.Status === 'Preview'));
+        // Get all active AIPromptModel records for this prompt
+        const allPromptModels = AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID && (pm.Status === 'Active' || pm.Status === 'Preview'));
+        // Filter by configuration matching rules
         const promptModels = this.filterPromptModelsByConfiguration(allPromptModels, configurationId);
+        // Sort: config-specific before universal, then by priority DESC within each group
         const sortedPromptModels = this.sortPromptModelsForSpecificStrategy(promptModels, configurationId);
+        // Build candidates maintaining order
         const candidates = this.buildCandidatesFromPromptModels(sortedPromptModels);
+        // Strategy='Specific' requires explicit configuration
         if (candidates.length === 0) {
             const configInfo = configurationId ? ` with configuration "${configurationId}"` : '';
             throw new Error(`SelectionStrategy is 'Specific' but no valid AIPromptModel candidates found for prompt "${prompt.Name}"${configInfo}. ` +
                 `Please configure AIPromptModel records for this prompt.`);
         }
         if (verbose) {
-            (0, core_1.LogStatus)(`Using SelectionStrategy='Specific' with ${sortedPromptModels.length} AIPromptModel entries, generated ${candidates.length} candidates`);
+            LogStatus(`Using SelectionStrategy='Specific' with ${sortedPromptModels.length} AIPromptModel entries, generated ${candidates.length} candidates`);
         }
         return candidates;
     }
+    /**
+     * PHASE 3: Build candidates for general selection strategies ('Default' or 'ByPower').
+     * Uses configuration-aware fallback hierarchy with legacy blended priority calculation.
+     */
     buildCandidatesForGeneralSelection(prompt, configurationId, preferredVendorId, verbose) {
         const preferredVendorName = preferredVendorId ?
-            aiengine_1.AIEngine.Instance.Vendors.find(v => v.ID === preferredVendorId)?.Name : undefined;
+            AIEngine.Instance.Vendors.find(v => v.ID === preferredVendorId)?.Name : undefined;
+        // Get prompt models for configuration
         const promptModels = this.getPromptModelsForConfiguration(prompt, configurationId);
         const candidates = [];
         if (promptModels.length > 0) {
+            // Use prompt-specific models with blended priorities
             this.addPromptSpecificCandidates(candidates, promptModels, preferredVendorId);
+            // Add configuration fallback candidates if needed
             if (configurationId) {
                 this.addConfigurationFallbackCandidates(candidates, prompt, configurationId, preferredVendorId, verbose);
             }
         }
         else {
+            // No prompt-specific models, use selection strategy
             this.addStrategyBasedCandidates(candidates, prompt, preferredVendorName);
         }
+        // Sort all candidates by priority (highest first)
         candidates.sort((a, b) => b.priority - a.priority);
         return candidates;
     }
+    /**
+     * Helper: Filter prompt models by configuration matching rules.
+     * Supports configuration inheritance - includes models from the entire inheritance chain.
+     */
     filterPromptModelsByConfiguration(allPromptModels, configurationId) {
         if (configurationId) {
-            const chain = aiengine_1.AIEngine.Instance.GetConfigurationChain(configurationId);
+            // Get the configuration inheritance chain
+            const chain = AIEngine.Instance.GetConfigurationChain(configurationId);
             const chainIds = new Set(chain.map(c => c.ID));
+            // Include models matching any config in the chain, plus null-config (universal fallback)
             return allPromptModels.filter(pm => (pm.ConfigurationID && chainIds.has(pm.ConfigurationID)) ||
                 pm.ConfigurationID === null);
         }
         else {
+            // No config specified - only include null-config models
             return allPromptModels.filter(pm => pm.ConfigurationID === null);
         }
     }
+    /**
+     * Helper: Sort prompt models for 'Specific' strategy.
+     * Respects configuration inheritance chain - child configs first, then parents, then null-config.
+     * Within each config level, sorts by priority DESC.
+     */
     sortPromptModelsForSpecificStrategy(promptModels, configurationId) {
         if (!configurationId) {
+            // No config specified - just sort by priority
             return promptModels.sort((a, b) => (b.Priority || 0) - (a.Priority || 0));
         }
-        const chain = aiengine_1.AIEngine.Instance.GetConfigurationChain(configurationId);
+        // Get the configuration inheritance chain and create position map
+        const chain = AIEngine.Instance.GetConfigurationChain(configurationId);
         const chainOrder = new Map(chain.map((c, index) => [c.ID, index]));
         return promptModels.sort((a, b) => {
+            // Primary: Chain position (lower index = higher priority, null config = last)
             const aChainPos = a.ConfigurationID ? (chainOrder.get(a.ConfigurationID) ?? 999) : 1000;
             const bChainPos = b.ConfigurationID ? (chainOrder.get(b.ConfigurationID) ?? 999) : 1000;
             if (aChainPos !== bChainPos) {
-                return aChainPos - bChainPos;
+                return aChainPos - bChainPos; // Lower chain position first (child before parent)
             }
+            // Secondary: Higher priority first within same config level
             return (b.Priority || 0) - (a.Priority || 0);
         });
     }
+    /**
+     * Helper: Build candidates from sorted AIPromptModel records.
+     * Expands VendorID=null to all vendors for that model.
+     */
     buildCandidatesFromPromptModels(promptModels) {
         const candidates = [];
         for (const pm of promptModels) {
-            const model = aiengine_1.AIEngine.Instance.Models.find(m => m.ID === pm.ModelID);
+            const model = AIEngine.Instance.Models.find(m => m.ID === pm.ModelID);
             if (!model || !model.IsActive)
                 continue;
             if (pm.VendorID) {
+                // Specific vendor specified - create single candidate
                 const candidate = this.createCandidateForSpecificVendor(model, pm);
                 if (candidate) {
                     candidates.push(candidate);
                 }
             }
             else {
+                // No vendor specified - create candidates for all vendors
                 const vendorCandidates = this.createCandidatesForAllVendors(model);
                 candidates.push(...vendorCandidates);
             }
         }
         return candidates;
     }
+    /**
+     * Helper: Create candidate for specific vendor from AIPromptModel.
+     */
     createCandidateForSpecificVendor(model, promptModel) {
-        const modelVendor = aiengine_1.AIEngine.Instance.ModelVendors.find(mv => mv.ModelID === promptModel.ModelID &&
+        const modelVendor = AIEngine.Instance.ModelVendors.find(mv => mv.ModelID === promptModel.ModelID &&
             mv.VendorID === promptModel.VendorID &&
             mv.Status === 'Active' &&
             this.isInferenceProvider(mv));
@@ -1061,14 +1394,17 @@ class AIPromptRunner {
             driverClass: modelVendor.DriverClass || model.DriverClass,
             apiName: modelVendor.APIName || model.APIName,
             supportsEffortLevel: modelVendor.SupportsEffortLevel ?? model.SupportsEffortLevel ?? false,
-            effortLevel: promptModel.EffortLevel ?? undefined,
+            effortLevel: promptModel.EffortLevel ?? undefined, // Model-specific effort level override
             isPreferredVendor: false,
-            priority: 0,
+            priority: 0, // Order is determined by promptModels sort
             source: 'prompt-model'
         };
     }
+    /**
+     * Helper: Create candidates for all vendors of a model, sorted by vendor priority.
+     */
     createCandidatesForAllVendors(model) {
-        const vendors = aiengine_1.AIEngine.Instance.ModelVendors
+        const vendors = AIEngine.Instance.ModelVendors
             .filter(mv => mv.ModelID === model.ID &&
             mv.Status === 'Active' &&
             this.isInferenceProvider(mv))
@@ -1083,10 +1419,11 @@ class AIPromptRunner {
                 apiName: vendor.APIName || model.APIName,
                 supportsEffortLevel: vendor.SupportsEffortLevel ?? model.SupportsEffortLevel ?? false,
                 isPreferredVendor: false,
-                priority: 0,
+                priority: 0, // Order is determined by promptModels sort
                 source: 'prompt-model'
             });
         }
+        // If no vendors found, use model defaults
         if (candidates.length === 0 && model.DriverClass) {
             candidates.push({
                 model,
@@ -1100,94 +1437,128 @@ class AIPromptRunner {
         }
         return candidates;
     }
+    /**
+     * Helper: Get prompt models for configuration with inheritance chain fallback.
+     * Walks the configuration inheritance chain looking for prompt models.
+     * Returns models from the first config in the chain that has any, or falls back to null-config.
+     */
     getPromptModelsForConfiguration(prompt, configurationId) {
         if (configurationId) {
-            const chain = aiengine_1.AIEngine.Instance.GetConfigurationChain(configurationId);
+            // Get the configuration inheritance chain (child -> parent -> grandparent -> ...)
+            const chain = AIEngine.Instance.GetConfigurationChain(configurationId);
+            // Walk the chain looking for prompt models
             for (const config of chain) {
-                const promptModels = aiengine_1.AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID &&
+                const promptModels = AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID &&
                     (pm.Status === 'Active' || pm.Status === 'Preview') &&
                     pm.ConfigurationID === config.ID);
                 if (promptModels.length > 0) {
                     return promptModels;
                 }
             }
-            (0, core_1.LogStatus)(`No models found in configuration chain for "${configurationId}", falling back to default models`);
+            // No match in chain, fall back to NULL config models
+            LogStatus(`No models found in configuration chain for "${configurationId}", falling back to default models`);
         }
-        return aiengine_1.AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID &&
+        // Return null-config (universal) models
+        return AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID &&
             (pm.Status === 'Active' || pm.Status === 'Preview') &&
             !pm.ConfigurationID);
     }
+    /**
+     * Helper: Add prompt-specific candidates with blended priorities (legacy behavior).
+     */
     addPromptSpecificCandidates(candidates, promptModels, preferredVendorId) {
         for (const pm of promptModels) {
-            const model = aiengine_1.AIEngine.Instance.Models.find(m => m.ID === pm.ModelID);
+            const model = AIEngine.Instance.Models.find(m => m.ID === pm.ModelID);
             if (model && model.IsActive) {
                 const modelCandidates = this.createCandidatesForModel(model, 5000, 'prompt-model', preferredVendorId, pm.Priority);
                 candidates.push(...modelCandidates);
             }
         }
     }
+    /**
+     * Helper: Add configuration fallback candidates from the inheritance chain.
+     * Adds models from parent configs (with decreasing priority) and null-config models as final fallback.
+     */
     addConfigurationFallbackCandidates(candidates, prompt, configurationId, preferredVendorId, verbose) {
-        const chain = aiengine_1.AIEngine.Instance.GetConfigurationChain(configurationId);
+        const chain = AIEngine.Instance.GetConfigurationChain(configurationId);
+        // Add models from parent configs (skip index 0 which is the direct config, already handled)
         for (let i = 1; i < chain.length; i++) {
             const parentConfig = chain[i];
-            const parentModels = aiengine_1.AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID &&
+            const parentModels = AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID &&
                 (pm.Status === 'Active' || pm.Status === 'Preview') &&
                 pm.ConfigurationID === parentConfig.ID);
             if (parentModels.length > 0 && verbose) {
-                (0, core_1.LogStatus)(`Adding ${parentModels.length} models from parent config "${parentConfig.Name}" as fallback`);
+                LogStatus(`Adding ${parentModels.length} models from parent config "${parentConfig.Name}" as fallback`);
             }
             for (const pm of parentModels) {
-                const model = aiengine_1.AIEngine.Instance.Models.find(m => m.ID === pm.ModelID);
+                const model = AIEngine.Instance.Models.find(m => m.ID === pm.ModelID);
                 if (model && model.IsActive) {
+                    // Decrease base priority for each level up the chain (3000, 2500, 2000, etc.)
                     const basePriority = 3000 - (i * 500);
                     const modelCandidates = this.createCandidatesForModel(model, basePriority, 'prompt-model', preferredVendorId, pm.Priority);
                     candidates.push(...modelCandidates);
                 }
             }
         }
-        const nullConfigModels = aiengine_1.AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID &&
+        // Finally add NULL config models (universal fallback) with lowest priority
+        const nullConfigModels = AIEngine.Instance.PromptModels.filter(pm => pm.PromptID === prompt.ID &&
             (pm.Status === 'Active' || pm.Status === 'Preview') &&
             !pm.ConfigurationID);
         if (nullConfigModels.length > 0 && verbose) {
-            (0, core_1.LogStatus)(`Adding ${nullConfigModels.length} NULL configuration models as universal fallback`);
+            LogStatus(`Adding ${nullConfigModels.length} NULL configuration models as universal fallback`);
         }
         for (const pm of nullConfigModels) {
-            const model = aiengine_1.AIEngine.Instance.Models.find(m => m.ID === pm.ModelID);
+            const model = AIEngine.Instance.Models.find(m => m.ID === pm.ModelID);
             if (model && model.IsActive) {
-                const modelCandidates = this.createCandidatesForModel(model, 1000, 'prompt-model', preferredVendorId, pm.Priority);
+                const modelCandidates = this.createCandidatesForModel(model, 1000, // Lowest priority tier
+                'prompt-model', preferredVendorId, pm.Priority);
                 candidates.push(...modelCandidates);
             }
         }
     }
+    /**
+     * Helper: Add strategy-based candidates when no prompt models exist.
+     */
     addStrategyBasedCandidates(candidates, prompt, preferredVendorName) {
         let modelPool = this.getModelPoolForStrategy(prompt, preferredVendorName);
         modelPool = this.sortModelPoolByStrategy(modelPool, prompt);
+        // Create candidates for each model in the pool
         modelPool.forEach((model, index) => {
-            const basePriority = 1000 - index * 10;
+            const basePriority = 1000 - index * 10; // Decrease priority by position
             const source = prompt.SelectionStrategy === 'ByPower' ? 'power-rank' : 'model-type';
             candidates.push(...this.createCandidatesForModel(model, basePriority, source));
         });
     }
+    /**
+     * Helper: Get model pool filtered for strategy.
+     */
     getModelPoolForStrategy(prompt, preferredVendorName) {
-        return aiengine_1.AIEngine.Instance.Models.filter(m => m.IsActive &&
+        return AIEngine.Instance.Models.filter(m => m.IsActive &&
             (!prompt.AIModelTypeID || m.AIModelTypeID === prompt.AIModelTypeID) &&
             (!preferredVendorName ||
-                aiengine_1.AIEngine.Instance.ModelVendors.some(mv => mv.ModelID === m.ID &&
+                AIEngine.Instance.ModelVendors.some(mv => mv.ModelID === m.ID &&
                     mv.Status === 'Active' &&
                     mv.Vendor === preferredVendorName &&
                     this.isInferenceProvider(mv))));
     }
+    /**
+     * Helper: Sort model pool by selection strategy.
+     */
     sortModelPoolByStrategy(modelPool, prompt) {
         if (prompt.SelectionStrategy === 'ByPower') {
             return this.sortByPowerPreference(modelPool, prompt.PowerPreference);
         }
         else {
+            // Default strategy
             const minPowerRank = prompt.MinPowerRank || 0;
             return modelPool
                 .filter(m => m.PowerRank >= minPowerRank)
                 .sort((a, b) => b.PowerRank - a.PowerRank);
         }
     }
+    /**
+     * Helper: Sort models by power preference.
+     */
     sortByPowerPreference(modelPool, powerPreference) {
         const pool = [...modelPool];
         switch (powerPreference) {
@@ -1202,11 +1573,16 @@ class AIPromptRunner {
                 return pool.sort((a, b) => b.PowerRank - a.PowerRank);
         }
     }
+    /**
+     * Helper: Create candidates for a model with AIModelVendor priorities (legacy behavior).
+     */
     createCandidatesForModel(model, basePriority, source, preferredVendorId, promptModelPriority) {
         const modelCandidates = [];
-        const modelVendors = aiengine_1.AIEngine.Instance.ModelVendors
+        // Get all vendors for this model - filter for inference providers only
+        const modelVendors = AIEngine.Instance.ModelVendors
             .filter(mv => mv.ModelID === model.ID && mv.Status === 'Active' && this.isInferenceProvider(mv))
             .sort((a, b) => b.Priority - a.Priority);
+        // First, add preferred vendor if it exists
         if (preferredVendorId) {
             const preferredVendor = modelVendors.find(mv => mv.VendorID === preferredVendorId);
             if (preferredVendor) {
@@ -1218,11 +1594,12 @@ class AIPromptRunner {
                     apiName: preferredVendor.APIName || model.APIName,
                     supportsEffortLevel: preferredVendor.SupportsEffortLevel ?? model.SupportsEffortLevel ?? false,
                     isPreferredVendor: true,
-                    priority: basePriority + 1000,
+                    priority: basePriority + 1000, // Boost priority for preferred vendor
                     source
                 });
             }
         }
+        // Then add other vendors in priority order
         for (const vendor of modelVendors) {
             if (vendor.VendorID !== preferredVendorId) {
                 modelCandidates.push({
@@ -1238,6 +1615,7 @@ class AIPromptRunner {
                 });
             }
         }
+        // If no vendors found, add model with its default driver
         if (modelCandidates.length === 0 && model.DriverClass) {
             modelCandidates.push({
                 model,
@@ -1249,21 +1627,34 @@ class AIPromptRunner {
                 source
             });
         }
+        // Apply prompt model priority if provided (legacy blended approach)
         if (promptModelPriority !== undefined) {
             modelCandidates.forEach(c => c.priority += promptModelPriority * 10);
         }
         return modelCandidates;
     }
+    /**
+     * Creates a properly typed AIModelSelectionInfo instance.
+     * TypeScript requires instantiating the class to get the getValidCandidates() method.
+     */
     createSelectionInfo(data) {
-        const info = new ai_core_plus_1.AIModelSelectionInfo();
+        const info = new AIModelSelectionInfo();
         Object.assign(info, data);
         return info;
     }
+    /**
+     * Converts model selection info into ModelVendorCandidate array for retry logic.
+     * Extracts only the valid candidates (those with available API keys) from the selection info.
+     *
+     * @param selectionInfo - Model selection information containing considered models
+     * @returns Array of valid model-vendor candidates sorted by priority
+     */
     buildCandidatesFromSelectionInfo(selectionInfo) {
         const validModels = selectionInfo.extractValidCandidates();
         return validModels.map(considered => {
+            // Find matching model vendor for driver and API info
             const modelVendor = considered.vendor
-                ? aiengine_1.AIEngine.Instance.ModelVendors.find(mv => mv.ModelID === considered.model.ID &&
+                ? AIEngine.Instance.ModelVendors.find(mv => mv.ModelID === considered.model.ID &&
                     mv.VendorID === considered.vendor.ID)
                 : undefined;
             return {
@@ -1273,29 +1664,47 @@ class AIPromptRunner {
                 driverClass: modelVendor?.DriverClass || considered.model.DriverClass,
                 apiName: modelVendor?.APIName || considered.model.APIName,
                 supportsEffortLevel: modelVendor?.SupportsEffortLevel ?? considered.model.SupportsEffortLevel ?? false,
-                isPreferredVendor: false,
+                isPreferredVendor: false, // Can't determine from selection info alone
                 priority: considered.priority,
                 source: (selectionInfo.selectionStrategy === 'ByPower' ? 'power-rank' : 'model-type')
             };
-        }).sort((a, b) => b.priority - a.priority);
-    }
+        }).sort((a, b) => b.priority - a.priority); // Sort by priority descending
+    }
+    /**
+     * Enhanced version of selectModelWithAPIKey that tracks all considered models
+     * for model selection reporting. Uses the hierarchical credential resolution
+     * system to check for available credentials.
+     *
+     * @param candidates - Ordered array of model-vendor candidates
+     * @param promptId - The prompt ID for credential resolution
+     * @param params - Optional prompt parameters for verbose logging and credential override
+     * @returns Object containing selected candidate and all considered models
+     */
     async selectModelWithAPIKeyTracked(candidates, promptId, params) {
+        // Cache for credential availability checks
+        // Key format: "driverClass:modelId:vendorId" to properly cache credential hierarchy
         const credentialCache = new Map();
         const consideredModels = [];
+        // Check ALL candidates to build complete list of valid and invalid options
         for (const candidate of candidates) {
+            // Build cache key including model and vendor for proper credential resolution
             const cacheKey = `${candidate.driverClass}:${candidate.model.ID}:${candidate.vendorId || 'default'}`;
+            // Check cache first
             let hasCredentials;
             if (credentialCache.has(cacheKey)) {
                 hasCredentials = credentialCache.get(cacheKey);
             }
             else {
+                // Check for credentials using hierarchical resolution
                 hasCredentials = this.hasCredentialsAvailable(candidate.driverClass, promptId, candidate.model.ID, candidate.vendorId, params);
                 credentialCache.set(cacheKey, hasCredentials);
             }
+            // Get vendor entity from AIEngine cache if vendorId is available
             let vendorEntity;
             if (candidate.vendorId) {
-                vendorEntity = aiengine_1.AIEngine.Instance.Vendors.find(v => v.ID === candidate.vendorId);
+                vendorEntity = AIEngine.Instance.Vendors.find(v => v.ID === candidate.vendorId);
             }
+            // Track this model as considered with availability status
             consideredModels.push({
                 model: candidate.model,
                 vendor: vendorEntity,
@@ -1304,6 +1713,7 @@ class AIPromptRunner {
                 unavailableReason: hasCredentials ? undefined : `No credentials configured for driver ${candidate.driverClass}`
             });
         }
+        // Select the first available candidate (highest priority with API key)
         const selected = consideredModels.find(m => m.available);
         const selectedCandidate = selected ? candidates.find(c => c.model.ID === selected.model.ID &&
             c.vendorId === selected.vendor?.ID) : null;
@@ -1316,6 +1726,7 @@ class AIPromptRunner {
             this.logStatus(`   Found ${validCount} valid candidate(s) out of ${candidates.length} total`, true, params);
         }
         else {
+            // Log what we tried
             const triedSummary = candidates.slice(0, 5).map(c => `${c.model.Name}/${c.vendorName || 'default'}(${c.driverClass})`).join(', ');
             this.logError(`No credentials found for any model-vendor combination. Tried: ${triedSummary}${candidates.length > 5 ? `... (${candidates.length} total)` : ''}`, {
                 category: 'CredentialValidation',
@@ -1329,18 +1740,24 @@ class AIPromptRunner {
         }
         return { selected: selectedCandidate, consideredModels };
     }
+    /**
+     * Creates an AIPromptRun entity for execution tracking
+     */
     async createPromptRun(prompt, model, params, systemPromptText, startTime, vendorId, modelSelectionInfo) {
         const promptRun = await this._metadata.GetEntityObject('MJ: AI Prompt Runs', params.contextUser);
         try {
             promptRun.NewRecord();
             promptRun.PromptID = prompt.ID;
             promptRun.ModelID = model.ID;
+            // Set initial status and tracking fields
             promptRun.Status = 'Running';
             promptRun.Cancelled = false;
             promptRun.CacheHit = false;
             promptRun.StreamingEnabled = false;
             promptRun.WasSelectedResult = false;
+            // Set model selection tracking fields
             if (modelSelectionInfo) {
+                // Convert the rich entity objects to simple IDs/names for database storage
                 const dbSelectionInfo = {
                     configurationId: modelSelectionInfo.aiConfiguration?.ID,
                     configurationName: modelSelectionInfo.aiConfiguration?.Name,
@@ -1361,28 +1778,35 @@ class AIPromptRunner {
                 };
                 promptRun.ModelSelection = JSON.stringify(dbSelectionInfo);
                 promptRun.SelectionStrategy = modelSelectionInfo.selectionStrategy || 'Default';
+                // Set ModelPowerRank if available
                 if (model.PowerRank != null) {
                     promptRun.ModelPowerRank = model.PowerRank;
                 }
             }
+            // Set original model tracking for failover
             promptRun.OriginalModelID = model.ID;
             promptRun.OriginalRequestStartTime = startTime;
+            // Initialize failover tracking fields
             promptRun.FailoverAttempts = 0;
             promptRun.FailoverErrors = null;
             promptRun.FailoverDurations = null;
             promptRun.TotalFailoverDuration = 0;
+            // Check if model has pre-selected vendor info from selectModel
             const modelWithVendor = model;
             if (modelSelectionInfo) {
                 promptRun.VendorID = modelSelectionInfo.vendorSelected?.ID || vendorId || modelWithVendor._selectedVendorId;
             }
             else if (vendorId) {
+                // Explicit vendor ID provided
                 promptRun.VendorID = vendorId;
             }
             else if (modelWithVendor._selectedVendorId) {
+                // Use vendor selected during model selection (with API key verification)
                 promptRun.VendorID = modelWithVendor._selectedVendorId;
             }
             else {
-                const modelVendors = aiengine_1.AIEngine.Instance.ModelVendors
+                // Fallback: grab the highest priority AI Model Vendor record for this model (inference providers only)
+                const modelVendors = AIEngine.Instance.ModelVendors
                     .filter((mv) => mv.ModelID === model.ID && mv.Status === 'Active' && this.isInferenceProvider(mv))
                     .sort((a, b) => b.Priority - a.Priority);
                 if (modelVendors.length > 0) {
@@ -1391,24 +1815,32 @@ class AIPromptRunner {
             }
             promptRun.ConfigurationID = params.configurationId;
             promptRun.RunAt = startTime;
+            // Set AgentRunID if provided for agent-prompt execution tracking
             if (params.agentRunId) {
                 promptRun.AgentRunID = params.agentRunId;
             }
+            // Resolve and save the effort level used (same precedence as ChatParams resolution)
             if (params.effortLevel !== undefined && params.effortLevel !== null) {
                 promptRun.EffortLevel = params.effortLevel;
             }
             else if (prompt.EffortLevel !== undefined && prompt.EffortLevel !== null) {
                 promptRun.EffortLevel = prompt.EffortLevel;
             }
+            // If neither is set, EffortLevel remains null (provider default was used)
+            // Set ParentID for hierarchical prompt execution tracking
             if (params.parentPromptRunId) {
                 promptRun.ParentID = params.parentPromptRunId;
             }
+            // Set RerunFromPromptRunID if this is a rerun
             if (params.rerunFromPromptRunID) {
                 promptRun.RerunFromPromptRunID = params.rerunFromPromptRunID;
             }
+            // Always save the response format from the prompt if it exists
             if (prompt.ResponseFormat && prompt.ResponseFormat !== 'Any') {
                 promptRun.ResponseFormat = prompt.ResponseFormat;
             }
+            // Save the actual values that will be used (either from prompt defaults or additionalParameters)
+            // First, apply defaults from prompt entity 
             if (prompt.Temperature != null)
                 promptRun.Temperature = prompt.Temperature;
             if (prompt.TopP != null)
@@ -1429,6 +1861,7 @@ class AIPromptRunner {
                 promptRun.LogProbs = prompt.IncludeLogProbs;
             if (prompt.TopLogProbs != null)
                 promptRun.TopLogProbs = prompt.TopLogProbs;
+            // Then override with additionalParameters if provided
             if (params.additionalParameters) {
                 if (params.additionalParameters.temperature !== undefined) {
                     promptRun.Temperature = params.additionalParameters.temperature;
@@ -1461,6 +1894,7 @@ class AIPromptRunner {
                     promptRun.TopLogProbs = params.additionalParameters.topLogProbs;
                 }
             }
+            // Store the input data/context as JSON in Messages field
             if (params.data || params.templateData || systemPromptText) {
                 const messages = [];
                 if (systemPromptText) {
@@ -1476,13 +1910,14 @@ class AIPromptRunner {
                     messages: messages || [],
                 });
             }
+            // Populate new retry tracking columns with initial values
             promptRun.ValidationBehavior = prompt.ValidationBehavior || 'Warn';
             promptRun.RetryStrategy = prompt.RetryStrategy || 'Fixed';
             promptRun.MaxRetriesConfigured = prompt.MaxRetries || 0;
             promptRun.FirstAttemptAt = startTime;
-            promptRun.ValidationAttemptCount = 0;
+            promptRun.ValidationAttemptCount = 0; // Will be updated during execution
             promptRun.SuccessfulValidationCount = 0;
-            promptRun.FinalValidationPassed = false;
+            promptRun.FinalValidationPassed = false; // Will be updated after execution
             const saveResult = await promptRun.Save();
             if (!saveResult) {
                 const error = `Failed to save AIPromptRun: ${promptRun.LatestResult?.CompleteMessage || 'Unknown error'}`;
@@ -1497,12 +1932,14 @@ class AIPromptRunner {
                 });
                 throw new Error(error);
             }
+            // Invoke callback if provided
             if (params.onPromptRunCreated) {
                 try {
                     await params.onPromptRunCreated(promptRun.ID);
                 }
                 catch (callbackError) {
-                    (0, core_1.LogStatus)(`Error in onPromptRunCreated callback: ${callbackError.message}`);
+                    LogStatus(`Error in onPromptRunCreated callback: ${callbackError.message}`);
+                    // Don't fail the execution if callback fails
                 }
             }
             return promptRun;
@@ -1520,18 +1957,26 @@ class AIPromptRunner {
             throw new Error(msg);
         }
     }
+    /**
+     * Renders the prompt template with provided data
+     */
     async renderPromptTemplate(template, params) {
         try {
+            // Get the highest priority content for the template
             const templateContent = template.GetHighestPriorityContent();
             if (!templateContent) {
                 throw new Error(`No content found for template ${template.Name}`);
             }
-            const systemPlaceholders = await ai_core_plus_2.SystemPlaceholderManager.resolveAllPlaceholders(params);
+            // Resolve system placeholders with full params context
+            const systemPlaceholders = await SystemPlaceholderManager.resolveAllPlaceholders(params);
+            // Merge data contexts with system placeholders having lowest priority
             const mergedData = {
-                ...systemPlaceholders,
-                ...params.data,
-                ...params.templateData
+                ...systemPlaceholders, // System placeholders first (lowest priority)
+                ...params.data, // User data overrides system placeholders
+                ...params.templateData // Template data has highest priority
             };
+            //LogStatus(`🔧 Rendering template '${template.Name}' with ${Object.keys(systemPlaceholders).length} system placeholders`);
+            // Render the template
             return await this._templateEngine.RenderTemplate(template, templateContent, mergedData);
         }
         catch (error) {
@@ -1547,20 +1992,40 @@ class AIPromptRunner {
             throw error;
         }
     }
+    /**
+     * Executes the AI model with failover support
+     *
+     * @remarks
+     * This method wraps the core executeModel functionality with intelligent failover
+     * capabilities. It will attempt to execute with different models/vendors according
+     * to the configured failover strategy when errors occur.
+     *
+     * The method calls several smaller, focused helper methods:
+     * - buildFailoverCandidates: Creates candidate models based on type restrictions
+     * - createCandidatesFromModels: Converts models to vendor-specific candidates
+     * - updatePromptRunWithFailoverSuccess: Records successful failover metadata
+     * - updatePromptRunWithFailoverFailure: Records failed failover metadata
+     * - createFailoverErrorResult: Creates standardized error response
+     */
     async executeModelWithFailover(model, renderedPrompt, prompt, params, vendorId, conversationMessages, templateMessageRole = 'system', cancellationToken, allCandidates, promptRun, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel) {
+        // Get failover configuration (used for errorScope filtering)
         const failoverConfig = this.getFailoverConfiguration(prompt);
+        // If no candidates provided or failover disabled, execute normally with first model
         if (!allCandidates || allCandidates.length === 0 || failoverConfig.strategy === 'None') {
             return this.executeModel(model, renderedPrompt, prompt, params, vendorId, conversationMessages, templateMessageRole, cancellationToken, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel);
         }
+        // Track failover attempts
         const failoverAttempts = [];
         let lastError = null;
+        // Iterate through all candidates in priority order with instant failover
         for (let i = 0; i < allCandidates.length; i++) {
             const candidate = allCandidates[i];
             const attemptStartTime = Date.now();
             try {
+                // Log the attempt if not the first one
                 if (i > 0) {
                     const vendorName = candidate.vendorName || 'default';
-                    (0, core_1.LogStatusEx)({
+                    LogStatusEx({
                         message: `🔄 Trying candidate ${i + 1}/${allCandidates.length}: ${candidate.model.Name} via ${vendorName}`,
                         category: 'AI',
                         additionalArgs: [{
@@ -1573,79 +2038,95 @@ class AIPromptRunner {
                             }]
                     });
                 }
+                // Execute the model with this candidate
                 const result = await this.executeModel(candidate.model, renderedPrompt, prompt, params, candidate.vendorId || null, conversationMessages, templateMessageRole, cancellationToken, candidate.driverClass, candidate.apiName, candidate.supportsEffortLevel, candidate.effortLevel);
+                // CRITICAL FIX: Check if result failed but is retriable (network errors, rate limits, etc.)
+                // Provider drivers (GeminiLLM, OpenAILLM, etc.) catch errors internally and return ChatResult{success: false}
+                // instead of throwing, so we must check result.success here.
+                if (!result.success && result.errorInfo?.canFailover) {
+                    lastError = result.exception || new Error(result.errorMessage || 'Model execution failed');
+                    // Use shared failover error handling logic
+                    const decision = await this.processFailoverError(lastError, result.errorInfo, candidate, attemptStartTime, i, allCandidates, failoverAttempts, prompt, failoverConfig);
+                    // Update candidates list (may have been filtered)
+                    allCandidates = decision.updatedCandidates;
+                    if (decision.shouldRetry) {
+                        i--; // Retry same model/vendor
+                        continue;
+                    }
+                    if (decision.shouldContinue) {
+                        continue; // Try next candidate
+                    }
+                    // Otherwise break (fatal error or last candidate)
+                    break;
+                }
+                // If we reach here, the result was successful
+                // Update promptRun with failover information if we had prior failures
                 if (failoverAttempts.length > 0 && promptRun) {
                     this.updatePromptRunWithFailoverSuccess(promptRun, failoverAttempts, candidate.model, candidate.vendorId || null);
                 }
                 return result;
             }
             catch (error) {
-                const attemptDuration = Date.now() - attemptStartTime;
                 lastError = error;
-                const errorAnalysis = ai_1.ErrorAnalyzer.analyzeError(lastError);
-                const failoverAttempt = {
-                    attemptNumber: i + 1,
-                    modelId: candidate.model.ID,
-                    vendorId: candidate.vendorId,
-                    error: lastError,
-                    errorType: errorAnalysis.errorType,
-                    duration: attemptDuration,
-                    timestamp: new Date()
-                };
-                failoverAttempts.push(failoverAttempt);
-                if (errorAnalysis.errorType === 'Authentication' || errorAnalysis.errorType === 'VendorValidationError') {
-                    allCandidates = this.filterVendorCandidates(errorAnalysis.errorType, candidate.vendorId, allCandidates);
-                }
-                const isLastCandidate = i === allCandidates.length - 1;
-                if (errorAnalysis.severity === 'Fatal') {
-                    const errorMessage = error?.message || error?.errorMessage || 'Unknown error';
-                    (0, core_1.LogErrorEx)(`Stopping failover: Fatal error (${errorAnalysis.errorType}): ${errorMessage}`);
-                    this.logFailoverAttempt(prompt.ID, failoverAttempt, false);
-                    break;
+                // Analyze error to get error info
+                const errorInfo = ErrorAnalyzer.analyzeError(lastError);
+                // Use shared failover error handling logic
+                const decision = await this.processFailoverError(lastError, errorInfo, candidate, attemptStartTime, i, allCandidates, failoverAttempts, prompt, failoverConfig);
+                // Update candidates list (may have been filtered)
+                allCandidates = decision.updatedCandidates;
+                if (decision.shouldRetry) {
+                    i--; // Retry same model/vendor
+                    continue;
                 }
-                if (failoverConfig.errorScope && failoverConfig.errorScope !== 'All') {
-                    const matchesScope = this.errorMatchesScope(errorAnalysis.errorType, failoverConfig.errorScope);
-                    if (!matchesScope) {
-                        this.logFailoverAttempt(prompt.ID, failoverAttempt, false);
-                        break;
-                    }
+                if (decision.shouldContinue) {
+                    continue; // Try next candidate
                 }
-                if (isLastCandidate) {
-                    this.logFailoverAttempt(prompt.ID, failoverAttempt, false);
-                    break;
-                }
-                this.logFailoverAttempt(prompt.ID, failoverAttempt, true);
+                // Otherwise break (fatal error or last candidate)
+                break;
             }
         }
+        // All candidates failed
         if (promptRun && failoverAttempts.length > 0) {
             this.updatePromptRunWithFailoverFailure(promptRun, failoverAttempts);
         }
         return this.createFailoverErrorResult(lastError, failoverAttempts);
     }
+    /**
+     * Builds failover candidates for a prompt based on available models and type restrictions
+     */
     async buildFailoverCandidates(prompt) {
-        const aiEngine = aiengine_1.AIEngine.Instance;
+        const aiEngine = AIEngine.Instance;
+        // Get all models, filtered by type if specified
         let allModels;
         if (prompt.AIModelTypeID) {
+            // Find the model type from the prompt
             const modelType = aiEngine.ModelTypes.find(mt => mt.ID === prompt.AIModelTypeID);
             if (!modelType) {
                 throw new Error(`Model type ${prompt.AIModelTypeID} not found`);
             }
+            // Get all models of this specific type
             const targetTypeName = modelType.Name.trim().toLowerCase();
             allModels = aiEngine.Models.filter(m => {
+                // Guard against AIModelType being non-string (defensive coding for data issues)
                 const mType = typeof m.AIModelType === 'string' ? m.AIModelType.trim().toLowerCase() : '';
                 return mType === targetTypeName;
             });
         }
         else {
+            // No type restriction - get all models
             allModels = aiEngine.Models;
         }
         return this.createCandidatesFromModels(allModels);
     }
+    /**
+     * Creates model-vendor candidates from a list of models
+     */
     createCandidatesFromModels(models) {
         const candidates = [];
         for (const model of models) {
             const vendors = model.ModelVendors || [];
             if (vendors.length === 0) {
+                // Model without specific vendors
                 candidates.push({
                     model: model,
                     vendorId: undefined,
@@ -1659,6 +2140,7 @@ class AIPromptRunner {
                 });
             }
             else {
+                // Add each vendor as a separate candidate
                 for (const vendor of vendors) {
                     candidates.push({
                         model: model,
@@ -1676,6 +2158,9 @@ class AIPromptRunner {
         }
         return candidates;
     }
+    /**
+     * Updates prompt run with successful failover tracking data
+     */
     updatePromptRunWithFailoverSuccess(promptRun, failoverAttempts, currentModel, currentVendorId) {
         promptRun.FailoverAttempts = failoverAttempts.length;
         promptRun.FailoverErrors = JSON.stringify(failoverAttempts.map(a => ({
@@ -1686,6 +2171,7 @@ class AIPromptRunner {
         })));
         promptRun.FailoverDurations = JSON.stringify(failoverAttempts.map(a => a.duration));
         promptRun.TotalFailoverDuration = failoverAttempts.reduce((sum, a) => sum + a.duration, 0);
+        // Update ModelID if we ended up using a different model
         if (currentModel.ID !== promptRun.OriginalModelID) {
             promptRun.ModelID = currentModel.ID;
         }
@@ -1693,6 +2179,9 @@ class AIPromptRunner {
             promptRun.VendorID = currentVendorId;
         }
     }
+    /**
+     * Updates prompt run with failover failure tracking data
+     */
     updatePromptRunWithFailoverFailure(promptRun, failoverAttempts) {
         promptRun.FailoverAttempts = failoverAttempts.length;
         promptRun.FailoverErrors = JSON.stringify(failoverAttempts.map(a => ({
@@ -1704,14 +2193,20 @@ class AIPromptRunner {
         promptRun.FailoverDurations = JSON.stringify(failoverAttempts.map(a => a.duration));
         promptRun.TotalFailoverDuration = failoverAttempts.reduce((sum, a) => sum + a.duration, 0);
     }
+    /**
+     * Creates an error result for failed failover attempts
+     */
     createFailoverErrorResult(lastError, failoverAttempts) {
         const startTime = new Date();
         const endTime = new Date();
+        // Check if this is a ContextLengthExceeded error - if so, mark as Fatal
         const hasContextLengthError = failoverAttempts.some(a => a.errorType === 'ContextLengthExceeded' ||
-            ai_1.ErrorAnalyzer.analyzeError(a.error).errorType === 'ContextLengthExceeded');
+            ErrorAnalyzer.analyzeError(a.error).errorType === 'ContextLengthExceeded');
+        // If ContextLengthExceeded and all failover attempts failed, this is fatal
         let errorInfo;
         if (lastError) {
-            errorInfo = ai_1.ErrorAnalyzer.analyzeError(lastError);
+            errorInfo = ErrorAnalyzer.analyzeError(lastError);
+            // Override severity to Fatal if context length exceeded and no larger models exist
             if (hasContextLengthError && errorInfo.errorType === 'ContextLengthExceeded') {
                 errorInfo.severity = 'Fatal';
             }
@@ -1728,43 +2223,63 @@ class AIPromptRunner {
             data: null
         };
     }
+    /**
+     * Executes the AI model with the rendered prompt
+     */
     async executeModel(model, renderedPrompt, prompt, params, vendorId, conversationMessages, templateMessageRole = 'system', cancellationToken, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel) {
+        // define these variables here to ensure they're available in the catch block
         let driverClass;
         let apiName;
         let llm;
         let chatParams;
         try {
-            const verbose = params.verbose === true || (0, core_1.IsVerboseLoggingEnabled)();
+            // Get verbose flag for logging
+            const verbose = params.verbose === true || IsVerboseLoggingEnabled();
+            // Determine if effort level is supported
             let supportsEffortLevel = false;
+            // Get vendor-specific configuration
+            // Use passed vendor info if available, otherwise fall back to vendor lookup
             if (vendorDriverClass && vendorApiName) {
+                // Vendor info was provided by the caller (from model selection)
                 driverClass = vendorDriverClass;
                 apiName = vendorApiName;
+                // Use provided vendorSupportsEffortLevel, or default to false
                 supportsEffortLevel = vendorSupportsEffortLevel ?? false;
             }
             else {
+                // Fallback to model defaults or vendor lookup
                 driverClass = model.DriverClass;
                 apiName = model.APIName;
+                // Start with model's SupportsEffortLevel setting
                 supportsEffortLevel = model.SupportsEffortLevel ?? false;
                 if (vendorId) {
-                    const modelVendor = aiengine_1.AIEngine.Instance.ModelVendors.find((mv) => mv.ModelID === model.ID && mv.VendorID === vendorId && mv.Status === 'Active' && this.isInferenceProvider(mv));
+                    // Find the AIModelVendor record for this specific vendor - must be an inference provider
+                    const modelVendor = AIEngine.Instance.ModelVendors.find((mv) => mv.ModelID === model.ID && mv.VendorID === vendorId && mv.Status === 'Active' && this.isInferenceProvider(mv));
                     if (modelVendor) {
                         driverClass = modelVendor.DriverClass || driverClass;
                         apiName = modelVendor.APIName || apiName;
+                        // Use modelVendor's SupportsEffortLevel if available
                         supportsEffortLevel = modelVendor.SupportsEffortLevel ?? supportsEffortLevel;
                     }
                     else {
+                        // Log warning if vendor was specified but not found or not an inference provider
                         this.logStatus(`⚠️ Vendor ${vendorId} not found or is not an inference provider for model ${model.Name}, using model defaults`, true, params);
                     }
                 }
             }
+            // Resolve credentials using hierarchical resolution (Credentials system with legacy fallback)
             const apiKey = await this.resolveCredentialForExecution(driverClass, prompt.ID, model.ID, vendorId ?? undefined, params);
-            llm = global_1.MJGlobal.Instance.ClassFactory.CreateInstance(ai_1.BaseLLM, driverClass, apiKey);
-            chatParams = new ai_1.ChatParams();
+            // Create LLM instance with vendor-specific driver class
+            llm = MJGlobal.Instance.ClassFactory.CreateInstance(BaseLLM, driverClass, apiKey);
+            // Prepare chat parameters
+            chatParams = new ChatParams();
             if (!apiName) {
                 throw new Error(`No API name found for model ${model.Name}. Please ensure the model or its vendor configuration includes an APIName.`);
             }
             chatParams.model = apiName;
             chatParams.cancellationToken = cancellationToken;
+            // Apply defaults from prompt entity first (if they exist)
+            // These can be overridden by additionalParameters
             if (prompt.Temperature != null)
                 chatParams.temperature = prompt.Temperature;
             if (prompt.TopP != null)
@@ -1780,13 +2295,16 @@ class AIPromptRunner {
             if (prompt.Seed != null)
                 chatParams.seed = prompt.Seed;
             if (prompt.StopSequences) {
+                // Parse comma-delimited stop sequences
                 chatParams.stopSequences = prompt.StopSequences.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
             }
             if (prompt.IncludeLogProbs != null)
                 chatParams.includeLogProbs = prompt.IncludeLogProbs;
             if (prompt.TopLogProbs != null)
                 chatParams.topLogProbs = prompt.TopLogProbs;
+            // Apply additional parameters if provided (these override prompt defaults)
             if (params.additionalParameters) {
+                // Apply chat-specific parameters from additionalParameters
                 if (params.additionalParameters.temperature !== undefined) {
                     chatParams.temperature = params.additionalParameters.temperature;
                 }
@@ -1818,11 +2336,18 @@ class AIPromptRunner {
                     chatParams.topLogProbs = params.additionalParameters.topLogProbs;
                 }
             }
+            // Apply effortLevel with precedence hierarchy
+            // 1. params.effortLevel (runtime override - highest priority)
+            // 2. modelEffortLevel (model-specific override from AIPromptModel - second priority)
+            // 3. Agent DefaultPromptEffortLevel (passed via params.effortLevel by BaseAgent - third priority)
+            // 4. prompt.EffortLevel (prompt default - fourth priority)
+            // 5. No effort level (provider default - lowest priority)
             const hasEffortLevel = (params.effortLevel !== undefined && params.effortLevel !== null) ||
                 (modelEffortLevel !== undefined && modelEffortLevel !== null) ||
                 (prompt.EffortLevel !== undefined && prompt.EffortLevel !== null);
             if (hasEffortLevel) {
                 if (supportsEffortLevel) {
+                    // Vendor/model supports effort level, apply it with precedence
                     if (params.effortLevel !== undefined && params.effortLevel !== null) {
                         chatParams.effortLevel = params.effortLevel.toString();
                     }
@@ -1834,18 +2359,25 @@ class AIPromptRunner {
                     }
                 }
                 else {
+                    // Vendor/model does not support effort level, log warning
                     const effortValue = params.effortLevel ?? modelEffortLevel ?? prompt.EffortLevel;
                     console.log(`⚠️ Effort Level ${effortValue} specified but will be ignored - model ${model.Name} does not support effort levels`);
                 }
             }
+            // If none are set, effortLevel remains undefined and providers use their defaults
+            // Apply response format from prompt settings
             if (prompt.ResponseFormat && prompt.ResponseFormat !== 'Any') {
-                chatParams.responseFormat = prompt.ResponseFormat;
+                chatParams.responseFormat = prompt.ResponseFormat; //as 'Any' | 'Text' | 'Markdown' | 'JSON' | 'ModelSpecific';
             }
             else {
+                // if chatParams.responseFormat is not set or set to Any, stay silent on response format
                 chatParams.responseFormat = undefined;
             }
+            // Build message array with rendered prompt and conversation messages
             chatParams.messages = this.buildMessageArray(renderedPrompt, conversationMessages, templateMessageRole);
+            // Execute the model with cancellation support
             if (cancellationToken) {
+                // If cancellation token is provided, wrap the execution to handle cancellation
                 return await Promise.race([
                     llm.ChatCompletion(chatParams),
                     new Promise((_, reject) => {
@@ -1861,11 +2393,12 @@ class AIPromptRunner {
                 ]);
             }
             else {
+                // No cancellation token, execute normally
                 return await llm.ChatCompletion(chatParams);
             }
         }
         catch (error) {
-            const errorInfo = ai_1.ErrorAnalyzer.analyzeError(error, driverClass);
+            const errorInfo = ErrorAnalyzer.analyzeError(error, driverClass);
             this.logError(error, {
                 category: 'ModelExecution',
                 model: model,
@@ -1878,51 +2411,70 @@ class AIPromptRunner {
             throw error;
         }
     }
+    /**
+     * 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;
     }
+    /**
+     * Executes the model with retry logic for validation failures
+     */
     async executeWithValidationRetries(selectedModel, renderedPromptText, prompt, params, promptRun, allCandidates, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel) {
         const validationAttempts = [];
         const maxRetries = Math.max(0, prompt.MaxRetries || 0);
         let lastError = null;
+        // Track cumulative token usage across all attempts
         let cumulativePromptTokens = 0;
         let cumulativeCompletionTokens = 0;
         let cumulativeCost = 0;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
+                // Check for cancellation before each attempt
                 if (params.cancellationToken?.aborted) {
                     throw new Error('Execution was cancelled during validation retries');
                 }
                 if (attempt > 0) {
-                    (0, core_1.LogStatus)(`   🔄 Retrying execution due to validation failure, attempt ${attempt + 1}/${maxRetries + 1}`);
+                    LogStatus(`   🔄 Retrying execution due to validation failure, attempt ${attempt + 1}/${maxRetries + 1}`);
                     await this.applyRetryDelay(prompt, attempt);
                 }
-                const modelResult = await this.executeModelWithFailover(selectedModel, renderedPromptText, prompt, params, promptRun.VendorID, params.conversationMessages, params.templateMessageRole || 'system', params.cancellationToken, allCandidates, promptRun, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel);
+                // Execute the AI model with failover support
+                const modelResult = await this.executeModelWithFailover(selectedModel, renderedPromptText, prompt, params, promptRun.VendorID, params.conversationMessages, params.templateMessageRole || 'system', params.cancellationToken, allCandidates, // Pass the candidates from initial selection
+                promptRun, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel);
+                // Check for fatal errors - don't attempt validation/retry on these
+                // Fatal errors (like ContextLengthExceeded when all models exhausted) cannot be resolved by retrying
                 if (!modelResult.success && modelResult.errorInfo?.severity === 'Fatal') {
+                    // Record the fatal error attempt
                     const validationAttempt = {
                         attemptNumber: attempt + 1,
                         success: false,
@@ -1931,6 +2483,7 @@ class AIPromptRunner {
                         timestamp: new Date(),
                     };
                     validationAttempts.push(validationAttempt);
+                    // Return immediately - no point in validation or retries for fatal errors
                     return {
                         modelResult,
                         parsedResult: {
@@ -1945,12 +2498,15 @@ class AIPromptRunner {
                         },
                     };
                 }
+                // Accumulate token usage from this attempt
                 if (modelResult.data?.usage) {
                     cumulativePromptTokens += modelResult.data.usage.promptTokens || 0;
                     cumulativeCompletionTokens += modelResult.data.usage.completionTokens || 0;
                     cumulativeCost += modelResult.data.usage.cost || 0;
                 }
+                // Parse and validate the result
                 const { result, validationResult, validationErrors } = await this.parseAndValidateResultEnhanced(modelResult, prompt, params.skipValidation, params.cleanValidationSyntax, promptRun, params);
+                // Record this validation attempt
                 const validationAttempt = {
                     attemptNumber: attempt + 1,
                     success: validationResult?.Success || false,
@@ -1962,6 +2518,7 @@ class AIPromptRunner {
                 };
                 validationAttempts.push(validationAttempt);
                 if (validationResult?.Success !== false) {
+                    // Validation succeeded, return the result
                     return {
                         modelResult,
                         parsedResult: { result, validationResult },
@@ -1973,16 +2530,19 @@ class AIPromptRunner {
                         },
                     };
                 }
+                // Validation failed, check if we should retry
+                // BUG FIX: Only retry in Strict mode, not in Warn or None modes
                 if (prompt.ValidationBehavior === 'Strict' && attempt < maxRetries) {
                     lastError = new Error(`Validation failed: ${validationErrors?.map(e => e.Message).join('; ')}`);
-                    (0, core_1.LogStatus)(`   ⚠️ Validation failed on attempt ${attempt + 1}, will retry (Strict mode)`);
-                    continue;
+                    LogStatus(`   ⚠️ Validation failed on attempt ${attempt + 1}, will retry (Strict mode)`);
+                    continue; // Retry
                 }
                 else {
+                    // Either not strict mode or no more retries, return what we have
                     const reason = prompt.ValidationBehavior !== 'Strict'
                         ? `${prompt.ValidationBehavior || 'None'} mode - continuing with invalid output (no retry)`
                         : 'max retries exceeded';
-                    (0, core_1.LogStatus)(`   ⚠️ Validation failed on attempt ${attempt + 1}, stopping retries (${reason})`);
+                    LogStatus(`   ⚠️ Validation failed on attempt ${attempt + 1}, stopping retries (${reason})`);
                     return {
                         modelResult,
                         parsedResult: { result, validationResult },
@@ -2007,6 +2567,7 @@ class AIPromptRunner {
                     },
                     maxErrorLength: params.maxErrorLength
                 });
+                // Record failed attempt
                 const validationAttempt = {
                     attemptNumber: attempt + 1,
                     success: false,
@@ -2016,17 +2577,26 @@ class AIPromptRunner {
                 };
                 validationAttempts.push(validationAttempt);
                 if (attempt === maxRetries) {
-                    throw error;
+                    throw error; // Last attempt, propagate error
                 }
             }
         }
+        // Should not reach here, but just in case
         throw lastError || new Error('Execution failed after all retry attempts');
     }
+    /**
+     * Applies retry delay based on the prompt's retry strategy
+     */
+    /**
+     * Calculates retry delay for rate limit and other retriable errors.
+     * Uses the prompt's RetryStrategy and can respect suggested delays from provider.
+     */
     calculateRetryDelay(prompt, attemptNumber, suggestedDelaySeconds) {
+        // Use provider's suggested delay if available
         if (suggestedDelaySeconds && suggestedDelaySeconds > 0) {
-            return suggestedDelaySeconds * 1000;
+            return suggestedDelaySeconds * 1000; // Convert to milliseconds
         }
-        const baseDelay = prompt.RetryDelayMS || 1000;
+        const baseDelay = prompt.RetryDelayMS || 1000; // Default 1 second
         let delay = baseDelay;
         switch (prompt.RetryStrategy) {
             case 'Fixed':
@@ -2046,20 +2616,28 @@ class AIPromptRunner {
     async applyRetryDelay(prompt, attemptNumber, suggestedDelaySeconds) {
         const delay = this.calculateRetryDelay(prompt, attemptNumber, suggestedDelaySeconds);
         const delaySeconds = (delay / 1000).toFixed(1);
-        (0, core_1.LogStatus)(`   Waiting ${delaySeconds}s before retry (strategy: ${prompt.RetryStrategy || 'Fixed'})...`);
+        LogStatus(`   Waiting ${delaySeconds}s before retry (strategy: ${prompt.RetryStrategy || 'Fixed'})...`);
         await new Promise(resolve => setTimeout(resolve, delay));
     }
+    /**
+     * Filters out all candidates from a vendor when a vendor-level error occurs.
+     * Vendor-level errors affect all models from that vendor:
+     * - Authentication: Invalid API key
+     * - VendorValidationError: API schema/validation requirements
+     */
     filterVendorCandidates(errorType, currentVendorId, allCandidates) {
         if (errorType !== 'Authentication' && errorType !== 'VendorValidationError') {
-            return allCandidates;
+            return allCandidates; // No filtering needed for non-vendor-level errors
         }
         const failedVendorId = currentVendorId || 'default';
         const beforeCount = allCandidates.length;
+        // Filter out ALL candidates from this vendor
         const filteredCandidates = allCandidates.filter(c => (c.vendorId || 'default') !== failedVendorId);
         const removedCount = beforeCount - filteredCandidates.length;
         if (removedCount > 0) {
-            const vendorName = aiengine_1.AIEngine.Instance.Vendors.find(v => v.ID === failedVendorId)?.Name || failedVendorId;
+            const vendorName = AIEngine.Instance.Vendors.find(v => v.ID === failedVendorId)?.Name || failedVendorId;
             const remainingCount = filteredCandidates.length;
+            // Log appropriate message based on error type
             let reason;
             let icon;
             if (errorType === 'Authentication') {
@@ -2078,38 +2656,110 @@ class AIPromptRunner {
         }
         return filteredCandidates;
     }
+    /**
+     * Handles rate limit errors by retrying the same model/vendor with backoff.
+     * Returns true if the caller should continue (retry), false if should proceed to failover.
+     */
     async handleRateLimitRetry(errorAnalysis, currentModel, currentVendorId, failoverAttempts, prompt, attemptNumber, maxAttempts, failoverAttempt) {
         const isRateLimit = errorAnalysis.errorType === 'RateLimit';
         if (!isRateLimit) {
-            return false;
+            return false; // Not a rate limit error
         }
+        // Count how many times we've retried this specific model/vendor for rate limits
         const rateLimitRetryCount = failoverAttempts.filter(a => a.modelId === currentModel.ID &&
             a.vendorId === currentVendorId &&
             a.errorType === 'RateLimit').length;
+        // Use MaxRetries from prompt configuration, default to 3 if not set
         const maxRetries = prompt.MaxRetries ?? 3;
+        // Retry up to MaxRetries times before giving up and failing over
         const shouldRetry = rateLimitRetryCount <= maxRetries;
         if (shouldRetry) {
             const modelName = currentModel.Name;
             const vendorName = currentVendorId
-                ? aiengine_1.AIEngine.Instance.Vendors.find(v => v.ID === currentVendorId)?.Name || 'default'
+                ? AIEngine.Instance.Vendors.find(v => v.ID === currentVendorId)?.Name || 'default'
                 : 'default';
             this.logStatus(`   ⏳ Rate limit hit - retrying ${modelName} (${vendorName}) with backoff (attempt ${rateLimitRetryCount}/${maxRetries})`, true);
             this.logFailoverAttempt(prompt.ID, failoverAttempt, true);
+            // Apply backoff delay before retry
             if (attemptNumber < maxAttempts) {
                 await this.applyRetryDelay(prompt, rateLimitRetryCount, errorAnalysis.suggestedRetryDelaySeconds);
             }
-            return true;
-        }
-        return false;
-    }
+            return true; // Signal to continue with same model/vendor
+        }
+        return false; // Too many retries, proceed to failover
+    }
+    /**
+     * Processes a failover error (either from catch block or from failed ChatResult).
+     * Handles vendor filtering, rate limit retries, fatal error detection, and failover logic.
+     *
+     * @returns Decision object indicating whether to retry same model, continue to next candidate, or stop
+     */
+    async processFailoverError(error, errorInfo, candidate, attemptStartTime, attemptIndex, allCandidates, failoverAttempts, prompt, failoverConfig) {
+        const attemptDuration = Date.now() - attemptStartTime;
+        // Create failover attempt record
+        const failoverAttempt = {
+            attemptNumber: attemptIndex + 1,
+            modelId: candidate.model.ID,
+            vendorId: candidate.vendorId,
+            error: error,
+            errorType: errorInfo.errorType,
+            duration: attemptDuration,
+            timestamp: new Date()
+        };
+        failoverAttempts.push(failoverAttempt);
+        // Vendor-level errors: filter out all candidates from this vendor
+        let updatedCandidates = allCandidates;
+        if (errorInfo.errorType === 'Authentication' || errorInfo.errorType === 'VendorValidationError') {
+            updatedCandidates = this.filterVendorCandidates(errorInfo.errorType, candidate.vendorId, allCandidates);
+        }
+        const isLastCandidate = attemptIndex === updatedCandidates.length - 1;
+        // Fatal errors: stop immediately
+        if (errorInfo.severity === 'Fatal') {
+            const errorMessage = error?.message || 'Unknown error';
+            LogErrorEx(`Stopping failover: Fatal error (${errorInfo.errorType}): ${errorMessage}`);
+            this.logFailoverAttempt(prompt.ID, failoverAttempt, false);
+            return { shouldRetry: false, shouldContinue: false, updatedCandidates };
+        }
+        // Check errorScope filter if configured
+        if (failoverConfig.errorScope && failoverConfig.errorScope !== 'All') {
+            const matchesScope = this.errorMatchesScope(errorInfo.errorType, failoverConfig.errorScope);
+            if (!matchesScope) {
+                this.logFailoverAttempt(prompt.ID, failoverAttempt, false);
+                return { shouldRetry: false, shouldContinue: false, updatedCandidates };
+            }
+        }
+        // Rate limit errors: check if we should retry the same model before failing over
+        if (errorInfo.errorType === 'RateLimit') {
+            const shouldRetry = await this.handleRateLimitRetry(errorInfo, candidate.model, candidate.vendorId, failoverAttempts, prompt, attemptIndex, updatedCandidates.length, failoverAttempt);
+            if (shouldRetry) {
+                return { shouldRetry: true, shouldContinue: false, updatedCandidates };
+            }
+        }
+        // If this is the last candidate, we're done
+        if (isLastCandidate) {
+            this.logFailoverAttempt(prompt.ID, failoverAttempt, false);
+            return { shouldRetry: false, shouldContinue: false, updatedCandidates };
+        }
+        // Log and signal to continue to next candidate
+        this.logFailoverAttempt(prompt.ID, failoverAttempt, true);
+        return { shouldRetry: false, shouldContinue: true, updatedCandidates };
+    }
+    /**
+     * Transitions to the next failover candidate.
+     * Returns the next candidate info or null if no candidates are available.
+     */
     async transitionToNextCandidate(currentModel, currentVendorId, failoverConfig, allCandidates, failoverAttempts, promptId, failoverAttempt, attemptNumber) {
+        // Select next candidate using failover strategy
         const nextCandidates = this.selectFailoverCandidates(currentModel, currentVendorId, failoverConfig.strategy, failoverConfig.modelStrategy, allCandidates, failoverAttempts);
         if (nextCandidates.length === 0) {
+            // No more candidates available
             this.logFailoverAttempt(promptId, failoverAttempt, false);
             return null;
         }
         const nextCandidate = nextCandidates[0];
+        // Log the successful transition
         this.logFailoverAttempt(promptId, failoverAttempt, true);
+        // Apply delay before next attempt (if not the last attempt)
         if (attemptNumber < failoverConfig.maxAttempts) {
             const delay = this.calculateFailoverDelay(attemptNumber, failoverConfig.delaySeconds);
             await new Promise(resolve => setTimeout(resolve, delay));
@@ -2122,6 +2772,9 @@ class AIPromptRunner {
             supportsEffortLevel: nextCandidate.supportsEffortLevel || false
         };
     }
+    /**
+     * Provides a human-readable description of the validation decision
+     */
     getValidationDecisionDescription(finalSuccess, totalAttempts, validationBehavior) {
         if (finalSuccess) {
             return totalAttempts === 1
@@ -2141,6 +2794,9 @@ class AIPromptRunner {
             }
         }
     }
+    /**
+     * Generates a JSON schema from an example object for validation
+     */
     generateSchemaFromExample(example) {
         if (typeof example !== 'object' || example === null) {
             return { type: 'object' };
@@ -2149,18 +2805,26 @@ class AIPromptRunner {
             type: 'object',
             properties: {},
             required: [],
-            additionalProperties: true,
+            additionalProperties: true, // Allow additional properties for flexibility with examples
         };
+        // Check if this entire object appears to be a placeholder/example
         const isPlaceholderObject = this.isObjectLikelyPlaceholder(example);
         for (const [key, value] of Object.entries(example)) {
+            // For placeholder objects, generate very permissive schemas
             if (isPlaceholderObject) {
+                // Don't define specific properties for placeholder objects
+                // Just indicate it should be an object with any properties
                 schema.properties = {};
                 schema.required = [];
                 break;
             }
+            // Check if the key ends with '?' to indicate optional property (TypeScript style)
             const isOptional = key.endsWith('?');
             const cleanKey = isOptional ? key.slice(0, -1) : key;
             schema.properties[cleanKey] = this.generateSchemaForValue(value);
+            // Don't make fields required if:
+            // 1. They're marked as optional with '?'
+            // 2. They look like placeholder/example values
             const isPlaceholder = this.isLikelyPlaceholder(cleanKey, value);
             if (!isOptional && !isPlaceholder) {
                 schema.required.push(cleanKey);
@@ -2168,11 +2832,16 @@ class AIPromptRunner {
         }
         return schema;
     }
+    /**
+     * Detects if a key/value pair looks like a placeholder or example value
+     */
     isLikelyPlaceholder(key, value) {
+        // Check if key contains common placeholder patterns
         const placeholderKeyPatterns = /^(param|example|placeholder|sample|dummy|test)/i;
         if (placeholderKeyPatterns.test(key)) {
             return true;
         }
+        // Check if string value contains common placeholder text
         if (typeof value === 'string') {
             const placeholderValuePatterns = /(goes here|placeholder|example|sample value|value\d+|UUID|your .* here|insert .* here)/i;
             if (placeholderValuePatterns.test(value)) {
@@ -2181,15 +2850,23 @@ class AIPromptRunner {
         }
         return false;
     }
+    /**
+     * Detects if an entire object looks like it contains only placeholder/example data
+     */
     isObjectLikelyPlaceholder(obj) {
         if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
             return false;
         }
         const entries = Object.entries(obj);
+        // If object has placeholder-like keys (param1, param2, etc)
         const hasPlaceholderKeys = entries.some(([key]) => /^(param\d+|key\d+|value\d+|example\d+|placeholder\d+)$/i.test(key));
+        // If all values are simple placeholders
         const allValuesArePlaceholders = entries.every(([key, value]) => this.isLikelyPlaceholder(key, value));
         return hasPlaceholderKeys || allValuesArePlaceholders;
     }
+    /**
+     * Generates schema for a specific value type
+     */
     generateSchemaForValue(value) {
         if (value === null) {
             return { type: 'null' };
@@ -2207,7 +2884,7 @@ class AIPromptRunner {
                         return {
                             type: 'array',
                             items: this.generateSchemaForValue(value[0]),
-                            minItems: 0,
+                            minItems: 0, // Don't require minimum items for example arrays
                         };
                     }
                     else {
@@ -2218,9 +2895,19 @@ class AIPromptRunner {
                     return this.generateSchemaFromExample(value);
                 }
             default:
-                return { type: 'string' };
-        }
-    }
+                return { type: 'string' }; // Fallback
+        }
+    }
+    /**
+     * Enhanced parsing and validation with detailed error reporting and JSON repair capabilities.
+     *
+     * @param modelResult - The raw result from the AI model
+     * @param prompt - The AI prompt entity containing configuration
+     * @param skipValidation - Whether to skip validation
+     * @param cleanValidationSyntax - Whether to clean validation syntax from results
+     * @param params - Optional prompt parameters containing additional configuration like attemptJSONRepair
+     * @returns Parsed result with optional validation results and errors
+     */
     async parseAndValidateResultEnhanced(modelResult, prompt, skipValidation = false, cleanValidationSyntax = false, currentPromptRun, params) {
         const validationErrors = [];
         let rawOutput;
@@ -2232,6 +2919,7 @@ class AIPromptRunner {
             if (!rawOutput) {
                 throw new Error('No output received from model');
             }
+            // Parse based on output type
             let parsedResult = rawOutput;
             try {
                 switch (prompt.OutputType) {
@@ -2255,24 +2943,27 @@ class AIPromptRunner {
                 }
             }
             catch (parseError) {
-                const validationResult = new global_1.ValidationResult();
+                // Type parsing failed
+                const validationResult = new ValidationResult();
                 validationResult.Success = false;
-                const error = new global_1.ValidationErrorInfo('parseAndValidateResultEnhanced', `Invalid OutputExample JSON: ${parseError.message}`, rawOutput, global_1.ValidationErrorType.Failure);
+                const error = new ValidationErrorInfo('parseAndValidateResultEnhanced', `Invalid OutputExample JSON: ${parseError.message}`, rawOutput, ValidationErrorType.Failure);
                 validationErrors.push(error);
                 validationResult.Errors = validationErrors;
                 return { result: rawOutput, validationResult, validationErrors };
             }
+            // Perform JSON schema validation for object types
             if (!skipValidation && prompt.OutputExample && prompt.OutputType === 'object' && parsedResult) {
                 try {
                     const schemaValidationErrors = await this.validateAgainstSchema(parsedResult, prompt.OutputExample, prompt.ID);
                     validationErrors.push(...schemaValidationErrors);
                 }
                 catch (schemaError) {
-                    const error = new global_1.ValidationErrorInfo('schema', `Schema validation failed: ${schemaError.message}`, undefined, global_1.ValidationErrorType.Failure);
+                    const error = new ValidationErrorInfo('schema', `Schema validation failed: ${schemaError.message}`, undefined, ValidationErrorType.Failure);
                     validationErrors.push(error);
                 }
             }
-            const validationResult = new global_1.ValidationResult();
+            // Create validation result
+            const validationResult = new ValidationResult();
             validationResult.Success = validationErrors.length === 0;
             validationResult.Errors = validationErrors;
             return { result: parsedResult, validationResult, validationErrors };
@@ -2287,10 +2978,11 @@ class AIPromptRunner {
                 },
                 maxErrorLength: params?.maxErrorLength
             });
-            const validationResult = new global_1.ValidationResult();
+            // Handle validation behavior
+            const validationResult = new ValidationResult();
             validationResult.Success = false;
             validationResult.Errors = validationErrors.length > 0 ? validationErrors : [
-                new global_1.ValidationErrorInfo('general', error.message, undefined, global_1.ValidationErrorType.Failure)
+                new ValidationErrorInfo('general', error.message, undefined, ValidationErrorType.Failure)
             ];
             switch (prompt.ValidationBehavior) {
                 case 'Strict':
@@ -2309,26 +3001,51 @@ class AIPromptRunner {
                     return { result: modelResult.data?.choices?.[0]?.message?.content, validationResult, validationErrors: validationResult.Errors };
                 case 'None':
                 default:
+                    // For None, we still return the validation result but mark as successful
                     validationResult.Success = true;
                     return { result: modelResult.data?.choices?.[0]?.message?.content, validationResult, validationErrors: [] };
             }
         }
     }
+    /**
+     * Parses a string output value.
+     *
+     * @param rawOutput - The raw output from the model
+     * @returns The parsed string value
+     */
     parseStringOutput(rawOutput) {
         return rawOutput.toString();
     }
+    /**
+     * Parses a number output value with validation.
+     *
+     * @param rawOutput - The raw output from the model
+     * @param skipValidation - Whether to skip validation
+     * @param validationErrors - Array to collect validation errors
+     * @returns The parsed number value
+     * @throws Error if the value cannot be parsed as a number and validation is enabled
+     */
     parseNumberOutput(rawOutput, skipValidation, validationErrors) {
         const numberResult = parseFloat(rawOutput);
         if (isNaN(numberResult)) {
             if (!skipValidation) {
-                const error = new global_1.ValidationErrorInfo('output', `Expected number output but got: ${rawOutput}`, rawOutput, global_1.ValidationErrorType.Failure);
+                const error = new ValidationErrorInfo('output', `Expected number output but got: ${rawOutput}`, rawOutput, ValidationErrorType.Failure);
                 validationErrors.push(error);
                 throw new Error(error.Message);
             }
-            return numberResult;
+            return numberResult; // Will be NaN if skipValidation is true
         }
         return numberResult;
     }
+    /**
+     * Parses a boolean output value with flexible input handling.
+     *
+     * @param rawOutput - The raw output from the model
+     * @param skipValidation - Whether to skip validation
+     * @param validationErrors - Array to collect validation errors
+     * @returns The parsed boolean value
+     * @throws Error if the value cannot be parsed as a boolean and validation is enabled
+     */
     parseBooleanOutput(rawOutput, skipValidation, validationErrors) {
         const lowerOutput = rawOutput.toLowerCase().trim();
         if (['true', 'yes', '1'].includes(lowerOutput)) {
@@ -2338,46 +3055,82 @@ class AIPromptRunner {
             return false;
         }
         else if (!skipValidation) {
-            const error = new global_1.ValidationErrorInfo('output', `Expected boolean output but got: ${rawOutput}`, rawOutput, global_1.ValidationErrorType.Failure);
+            const error = new ValidationErrorInfo('output', `Expected boolean output but got: ${rawOutput}`, rawOutput, ValidationErrorType.Failure);
             validationErrors.push(error);
             throw new Error(error.Message);
         }
-        return false;
-    }
+        return false; // Default to false if skipValidation is true
+    }
+    /**
+     * Parses a date output value with validation.
+     *
+     * @param rawOutput - The raw output from the model
+     * @param skipValidation - Whether to skip validation
+     * @param validationErrors - Array to collect validation errors
+     * @returns The parsed Date value
+     * @throws Error if the value cannot be parsed as a date and validation is enabled
+     */
     parseDateOutput(rawOutput, skipValidation, validationErrors) {
         const dateResult = new Date(rawOutput);
         if (isNaN(dateResult.getTime()) && !skipValidation) {
-            const error = new global_1.ValidationErrorInfo('output', `Expected date output but got: ${rawOutput}`, rawOutput, global_1.ValidationErrorType.Failure);
+            const error = new ValidationErrorInfo('output', `Expected date output but got: ${rawOutput}`, rawOutput, ValidationErrorType.Failure);
             validationErrors.push(error);
             throw new Error(error.Message);
         }
         return dateResult;
     }
+    /**
+     * Parses an object (JSON) output value with optional repair capabilities.
+     *
+     * @param rawOutput - The raw output from the model
+     * @param prompt - The AI prompt entity containing configuration
+     * @param skipValidation - Whether to skip validation
+     * @param cleanValidationSyntax - Whether to clean validation syntax
+     * @param validationErrors - Array to collect validation errors
+     * @param params - Optional prompt parameters containing attemptJSONRepair flag
+     * @returns The parsed object value
+     * @throws Error if the value cannot be parsed as JSON and validation is enabled
+     */
     async parseObjectOutput(rawOutput, prompt, skipValidation, cleanValidationSyntax, validationErrors, currentPromptRun, params) {
         let parsedResult;
         try {
-            parsedResult = JSON.parse((0, global_1.CleanJSON)(rawOutput));
+            // First attempt: Use CleanJSON to handle common JSON issues
+            parsedResult = JSON.parse(CleanJSON(rawOutput));
         }
         catch (jsonError) {
+            // If attemptJSONRepair is enabled and we're dealing with object output
             if (params?.attemptJSONRepair && prompt.OutputType === 'object') {
                 parsedResult = await this.attemptJSONRepair(rawOutput, jsonError, params, currentPromptRun);
             }
             else {
+                // Original error handling
                 if (!skipValidation) {
-                    const error = new global_1.ValidationErrorInfo('output', `Expected JSON object but got invalid JSON: ${rawOutput}`, rawOutput, global_1.ValidationErrorType.Failure);
+                    const error = new ValidationErrorInfo('output', `Expected JSON object but got invalid JSON: ${rawOutput}`, rawOutput, ValidationErrorType.Failure);
                     validationErrors.push(error);
                     throw new Error(error.Message);
                 }
-                return rawOutput;
+                return rawOutput; // Return raw output if skipping validation
             }
         }
+        // Clean validation syntax if needed
         if (parsedResult && (cleanValidationSyntax || (!skipValidation && prompt.OutputExample))) {
-            const validator = new global_1.JSONValidator();
+            const validator = new JSONValidator();
             parsedResult = validator.cleanValidationSyntax(parsedResult);
         }
         return parsedResult;
     }
+    /**
+     * Attempts to repair malformed JSON using a two-step process.
+     *
+     * @param rawOutput - The malformed JSON string
+     * @param originalError - The original parsing error
+     * @param params - Prompt parameters containing contextUser
+     * @returns The repaired and parsed JSON object
+     * @throws Error if JSON repair fails
+     */
     async attemptJSONRepair(rawOutput, originalError, params, currentPromptRun) {
+        // Step 0: First, see if the raw output has any { } [ ] characters at all
+        // if not, we KNOW it is not JSON and we should not attempt to repair it
         if (!rawOutput.includes('{') && !rawOutput.includes('[')) {
             this.logError(new Error('Raw output does not contain any JSON-like characters'), {
                 category: 'JSONRepairSkipped',
@@ -2389,11 +3142,13 @@ class AIPromptRunner {
             });
             throw new Error(`JSON repair skipped: raw output does not contain JSON-like characters. Original error: ${originalError.message}`);
         }
+        // Step 1: Try JSON5 parsing
         try {
             this.logStatus('   🔧 Attempting JSON repair with JSON5...', true, params);
+            // first try to clean JSON in case we have it in a markdown block
             let jsonToParse = rawOutput;
             try {
-                jsonToParse = (0, global_1.CleanJSON)(rawOutput);
+                jsonToParse = CleanJSON(rawOutput);
             }
             catch (cleanError) {
                 if (params.verbose) {
@@ -2414,14 +3169,17 @@ class AIPromptRunner {
             return json5Result;
         }
         catch (json5Error) {
+            // Step 2: Use AI to repair the JSON
             if (params.verbose) {
                 this.logStatus('   🤖 JSON5 failed, attempting AI-based JSON repair...', true, params);
             }
             try {
-                const repairPrompt = aiengine_1.AIEngine.Instance.Prompts.find(p => p.Name.trim().toLowerCase() === 'repair json' && p.Category.trim().toLowerCase() === 'mj: system');
+                // Find the "Repair JSON" prompt in the "MJ: System" category
+                const repairPrompt = AIEngine.Instance.Prompts.find(p => p.Name.trim().toLowerCase() === 'repair json' && p.Category.trim().toLowerCase() === 'mj: system');
                 if (!repairPrompt) {
                     throw new Error('Repair JSON prompt not found in MJ: System category');
                 }
+                // Run the repair prompt
                 const repairResult = await this.ExecutePrompt({
                     parentPromptRunId: currentPromptRun.ID,
                     agentRunId: currentPromptRun.AgentRunID,
@@ -2431,19 +3189,23 @@ class AIPromptRunner {
                         ERROR_MESSAGE: originalError.message,
                         MALFORMED_JSON: rawOutput
                     },
-                    skipValidation: true
+                    skipValidation: true // don't want to validate as this would cause recursive infinity scenario if the JSON is invalid. Just one shot, fix or no fix
                 });
                 if (!repairResult.success || !repairResult.result) {
                     throw new Error('AI-based JSON repair failed' + (repairResult.errorMessage ? `: ${repairResult.errorMessage}` : ''));
                 }
+                // if we get here we have the text result in the reapairResult.result so let's try to parse it
                 const repairedJSON = JSON.parse(repairResult.result);
+                // make sure repairedJSON is not this object: { error: "not_json" } -- if it is that means the LLM said it isn't JSOn
                 if (repairedJSON && typeof repairedJSON === 'object' && Object.keys(repairedJSON).length === 1 && repairedJSON.error?.trim().toLowerCase() === 'not_json') {
                     throw new Error('AI-based JSON repair returned a non-JSON response indicating it could not repair the JSON');
                 }
+                // if we get here, we successfully repaired the JSON!!!
                 this.logStatus('   ✅ AI successfully repaired the JSON', true, params);
                 return repairedJSON;
             }
             catch (aiRepairError) {
+                // Both repair attempts failed
                 if (params.verbose) {
                     this.logError(aiRepairError, {
                         category: 'JSONRepairFailed',
@@ -2460,48 +3222,115 @@ class AIPromptRunner {
             }
         }
     }
+    /**
+     * Validates parsed result against JSON schema derived from OutputExample
+     */
     async validateAgainstSchema(parsedResult, outputExample, promptId) {
         const validationErrors = [];
         try {
+            // Parse the output example
             let exampleObject;
             try {
                 exampleObject = JSON.parse(outputExample);
             }
             catch (parseError) {
-                const error = new global_1.ValidationErrorInfo('outputExample', `Invalid OutputExample JSON: ${parseError.message}`, outputExample, global_1.ValidationErrorType.Failure);
+                const error = new ValidationErrorInfo('outputExample', `Invalid OutputExample JSON: ${parseError.message}`, outputExample, ValidationErrorType.Failure);
                 validationErrors.push(error);
                 return validationErrors;
             }
+            // Use the JSONValidator to validate against the example
             const validationResult = this._jsonValidator.validate(parsedResult, exampleObject);
             validationErrors.push(...validationResult.Errors);
             if (validationErrors.length !== 0) {
-                (0, core_1.LogStatus)(`⚠️ Validation found ${validationErrors.length} issues for prompt ${promptId}:`);
+                LogStatus(`⚠️ Validation found ${validationErrors.length} issues for prompt ${promptId}:`);
                 validationErrors.forEach((error, index) => {
-                    (0, core_1.LogStatus)(`   ${index + 1}. ${error.Source}: ${error.Message}`);
+                    LogStatus(`   ${index + 1}. ${error.Source}: ${error.Message}`);
                 });
-                (0, core_1.LogStatus)(`   Note: Validation syntax in OutputExample:`);
-                (0, core_1.LogStatus)(`   - '?' = optional field (e.g., "reasoning?": "...")`);
-                (0, core_1.LogStatus)(`   - '*' = required but any content (e.g., "payload*": {})`);
-                (0, core_1.LogStatus)(`   - ':type' = type validation (e.g., "age:number": 25)`);
-                (0, core_1.LogStatus)(`   - ':[N+]' = array length (e.g., "items:[2+]": [])`);
-            }
+                LogStatus(`   Note: Validation syntax in OutputExample:`);
+                LogStatus(`   - '?' = optional field (e.g., "reasoning?": "...")`);
+                LogStatus(`   - '*' = required but any content (e.g., "payload*": {})`);
+                LogStatus(`   - ':type' = type validation (e.g., "age:number": 25)`);
+                LogStatus(`   - ':[N+]' = array length (e.g., "items:[2+]": [])`);
+            }
+            /* FUTURE IMPLEMENTATION - Keep this commented for reference
+            // Get or create cached validator for this prompt using static cache
+            let validator = AIPromptRunner._schemaCache.get(promptId);
+            
+            if (!validator) {
+              // Parse the output example
+              let exampleObject: unknown;
+              try {
+                exampleObject = JSON.parse(outputExample);
+              } catch (parseError) {
+                const error = new ValidationErrorInfo('outputExample', `Invalid OutputExample JSON: ${parseError.message}`, outputExample, ValidationErrorType.Failure);
+                validationErrors.push(error);
+                return validationErrors;
+              }
+      
+              // Generate schema from example
+              const schema = this.generateSchemaFromExample(exampleObject);
+              
+              // Compile and cache the validator
+              try {
+                validator = this._ajv.compile(schema);
+                AIPromptRunner._schemaCache.set(promptId, validator);
+                const cacheStats = AIPromptRunner.getSchemaCacheStats();
+                LogStatus(`📋 Compiled and cached JSON schema for prompt ${promptId} (global cache size: ${cacheStats.size})`);
+              } catch (compileError) {
+                const error = new ValidationErrorInfo('schema', `Failed to compile schema: ${compileError.message}`, schema, ValidationErrorType.Failure);
+                validationErrors.push(error);
+                return validationErrors;
+              }
+            }
+      
+            // Validate the result
+            const isValid = validator(parsedResult);
+            
+            if (!isValid && validator.errors) {
+              for (const ajvError of validator.errors) {
+                const fieldPath = ajvError.instancePath || ajvError.schemaPath || 'root';
+                const message = `${ajvError.instancePath || 'root'}: ${ajvError.message}`;
+                const error = new ValidationErrorInfo(fieldPath, message, ajvError.data, ValidationErrorType.Failure);
+                validationErrors.push(error);
+              }
+            }
+      
+            if (validationErrors.length === 0) {
+              //LogStatus(`✅ Schema validation passed for prompt ${promptId}`);
+            } else {
+              LogStatus(`⚠️ Schema validation found ${validationErrors.length} potential issues for prompt ${promptId}:`);
+              validationErrors.forEach((error, index) => {
+                LogStatus(`   ${index + 1}. ${error.Source}: ${error.Message}`);
+              });
+              // Log additional context to help with debugging
+              LogStatus(`   Note: The schema was generated from OutputExample. Consider:`);
+              LogStatus(`   - Mark optional properties with '?' suffix (e.g., "subAgent?": {...})`)
+              LogStatus(`   - Example values like "param1", "value1" are treated as placeholders`);
+            }
+            */
         }
         catch (error) {
-            const validationError = new global_1.ValidationErrorInfo('validation', `Unexpected validation error: ${error.message}`, undefined, global_1.ValidationErrorType.Failure);
+            const validationError = new ValidationErrorInfo('validation', `Unexpected validation error: ${error.message}`, undefined, ValidationErrorType.Failure);
             validationErrors.push(validationError);
         }
         return validationErrors;
     }
+    /**
+     * Updates the AIPromptRun entity with execution results
+     */
     async updatePromptRun(promptRun, prompt, modelResult, parsedResult, endTime, executionTimeMS, validationAttempts, cumulativeTokens) {
         try {
             promptRun.CompletedAt = endTime;
             promptRun.ExecutionTimeMS = executionTimeMS;
+            // Determine what to save as the result
             let resultToSave;
             const rawResult = modelResult.data?.choices?.[0]?.message?.content || '';
             if (parsedResult.result === undefined ||
                 parsedResult.result === null ||
                 (typeof parsedResult.result === 'string' && parsedResult.result.trim().length === 0)) {
+                // Use raw result as fallback when parsed result is undefined, null, or empty string
                 resultToSave = rawResult;
+                // Also set error message when we have to fall back to raw result
                 if (!promptRun.ErrorMessage) {
                     const validationErrors = parsedResult.validationResult?.Errors;
                     if (validationErrors && validationErrors.length > 0) {
@@ -2519,25 +3348,31 @@ class AIPromptRunner {
                 resultToSave = JSON.stringify(parsedResult.result);
             }
             promptRun.Result = resultToSave;
+            // Extract token usage and cost - use cumulative if retries occurred
             if (cumulativeTokens && validationAttempts && validationAttempts.length > 1) {
+                // Multiple attempts occurred, use cumulative totals
                 promptRun.TokensPrompt = cumulativeTokens.promptTokens;
                 promptRun.TokensCompletion = cumulativeTokens.completionTokens;
                 promptRun.TokensUsed = cumulativeTokens.promptTokens + cumulativeTokens.completionTokens;
                 promptRun.Cost = cumulativeTokens.totalCost;
+                // Cost currency from the last model result
                 if (modelResult.data?.usage?.costCurrency !== undefined) {
                     promptRun.CostCurrency = modelResult.data.usage.costCurrency;
                 }
             }
             else if (modelResult.data?.usage) {
+                // Single attempt, use standard token tracking
                 promptRun.TokensUsed = modelResult.data.usage.totalTokens;
                 promptRun.TokensPrompt = modelResult.data.usage.promptTokens;
                 promptRun.TokensCompletion = modelResult.data.usage.completionTokens;
+                // Save cost information if available
                 if (modelResult.data.usage.cost !== undefined) {
                     promptRun.Cost = modelResult.data.usage.cost;
                 }
                 if (modelResult.data.usage.costCurrency !== undefined) {
                     promptRun.CostCurrency = modelResult.data.usage.costCurrency;
                 }
+                // Save timing information if available
                 if (modelResult.data.usage.queueTime !== undefined) {
                     promptRun.QueueTime = modelResult.data.usage.queueTime;
                 }
@@ -2548,14 +3383,18 @@ class AIPromptRunner {
                     promptRun.CompletionTime = modelResult.data.usage.completionTime;
                 }
             }
+            // Save model-specific response details if available
             if (modelResult.modelSpecificResponseDetails) {
                 promptRun.ModelSpecificResponseDetails = JSON.stringify(modelResult.modelSpecificResponseDetails);
             }
+            // Populate retry tracking columns
             if (validationAttempts && validationAttempts.length > 0) {
+                // Update retry tracking columns
                 promptRun.ValidationAttemptCount = validationAttempts.length;
                 promptRun.SuccessfulValidationCount = validationAttempts.filter(a => a.success).length;
                 promptRun.FinalValidationPassed = parsedResult.validationResult?.Success === true;
                 promptRun.LastAttemptAt = endTime;
+                // Calculate total retry duration (excluding first attempt)
                 if (validationAttempts.length > 1) {
                     const firstAttemptTime = validationAttempts[0].timestamp;
                     const lastAttemptTime = validationAttempts[validationAttempts.length - 1].timestamp;
@@ -2564,11 +3403,13 @@ class AIPromptRunner {
                 else {
                     promptRun.TotalRetryDurationMS = 0;
                 }
+                // Get final validation error if any
                 const finalAttempt = validationAttempts[validationAttempts.length - 1];
                 if (!finalAttempt.success && finalAttempt.errorMessage) {
-                    promptRun.FinalValidationError = finalAttempt.errorMessage.substring(0, 500);
+                    promptRun.FinalValidationError = finalAttempt.errorMessage.substring(0, 500); // Truncate to fit column
                     promptRun.ValidationErrorCount = finalAttempt.validationErrors?.length || 0;
                 }
+                // Find most common validation error
                 if (validationAttempts.some(a => !a.success)) {
                     const errorCounts = new Map();
                     validationAttempts.forEach(attempt => {
@@ -2579,9 +3420,10 @@ class AIPromptRunner {
                     });
                     if (errorCounts.size > 0) {
                         const [commonError] = [...errorCounts.entries()].sort((a, b) => b[1] - a[1])[0];
-                        promptRun.CommonValidationError = commonError.substring(0, 255);
+                        promptRun.CommonValidationError = commonError.substring(0, 255); // Truncate to fit column
                     }
                 }
+                // Store detailed attempts in JSON columns
                 promptRun.ValidationAttempts = JSON.stringify(validationAttempts.map(a => ({
                     attemptNumber: a.attemptNumber,
                     success: a.success,
@@ -2613,14 +3455,18 @@ class AIPromptRunner {
                 });
             }
             else {
-                promptRun.ValidationAttemptCount = 1;
+                // No validation attempts (possibly skipped validation)
+                promptRun.ValidationAttemptCount = 1; // At least one attempt was made
                 promptRun.SuccessfulValidationCount = parsedResult.validationResult?.Success !== false ? 1 : 0;
                 promptRun.FinalValidationPassed = parsedResult.validationResult?.Success !== false;
                 promptRun.LastAttemptAt = endTime;
                 promptRun.TotalRetryDurationMS = 0;
             }
+            // Set Success flag based on validation result
             promptRun.Success = modelResult.success && (parsedResult.validationResult?.Success !== false);
+            // Set final Status based on success
             promptRun.Status = promptRun.Success ? 'Completed' : 'Failed';
+            // Set ErrorDetails if failed
             if (!promptRun.Success) {
                 if (!modelResult.success && modelResult.errorMessage) {
                     promptRun.ErrorDetails = modelResult.errorMessage;
@@ -2629,6 +3475,9 @@ class AIPromptRunner {
                     promptRun.ErrorDetails = `Validation failed: ${parsedResult.validationResult.Errors?.map(e => e.Message).join(', ')}`;
                 }
             }
+            // Note: Failover tracking fields are now updated directly in executeModelWithFailover
+            // The promptRun entity already has the failover information set
+            // With template composition, we only execute once so rollup equals regular fields
             promptRun.TokensPromptRollup = promptRun.TokensPrompt;
             promptRun.TokensCompletionRollup = promptRun.TokensCompletion;
             promptRun.TokensUsedRollup = promptRun.TokensUsed;
@@ -2637,6 +3486,7 @@ class AIPromptRunner {
             }
             const saveResult = await promptRun.Save();
             if (!saveResult) {
+                // Safely extract error message using CompleteMessage getter
                 let errorMsg = 'Unknown error';
                 try {
                     if (promptRun.LatestResult?.CompleteMessage) {
@@ -2666,6 +3516,27 @@ class AIPromptRunner {
             });
         }
     }
+    // ==================== CONTEXT LENGTH METHODS ====================
+    /**
+     * Estimates the number of tokens in a rendered prompt and conversation messages.
+     * This is a rough estimation based on character count and typical token ratios.
+     *
+     * @param renderedPrompt - The rendered prompt text
+     * @param conversationMessages - Optional conversation messages
+     * @returns Estimated token count
+     */
+    // ==================== FAILOVER METHODS ====================
+    /**
+     * Retrieves failover configuration from the prompt entity.
+     *
+     * @param prompt - The AI prompt entity containing failover settings
+     * @returns FailoverConfiguration object with strategy and settings
+     *
+     * @remarks
+     * This method extracts failover configuration from the prompt entity and provides
+     * default values when configuration is not specified. Override this method to
+     * implement custom failover configuration logic.
+     */
     getFailoverConfiguration(prompt) {
         return {
             strategy: prompt.FailoverStrategy || 'None',
@@ -2675,14 +3546,31 @@ class AIPromptRunner {
             errorScope: prompt.FailoverErrorScope || 'All'
         };
     }
+    /**
+     * Determines whether a failover attempt should be made based on the error and configuration.
+     *
+     * @param error - The error that occurred during execution
+     * @param config - The failover configuration
+     * @param attemptNumber - The current attempt number (1-based)
+     * @returns True if failover should be attempted, false otherwise
+     *
+     * @remarks
+     * This method uses the ErrorAnalyzer to classify errors and determine if they are
+     * eligible for failover based on the configured error scope. Override this method
+     * to implement custom failover decision logic.
+     */
     shouldAttemptFailover(error, config, attemptNumber) {
+        // Don't failover if strategy is None or we've exceeded max attempts
         if (config.strategy === 'None' || attemptNumber > config.maxAttempts) {
             return false;
         }
-        const errorAnalysis = ai_1.ErrorAnalyzer.analyzeError(error);
+        // Analyze the error to determine if it's eligible for failover
+        const errorAnalysis = ErrorAnalyzer.analyzeError(error);
+        // Check if error analysis allows failover
         if (!errorAnalysis.canFailover) {
             return false;
         }
+        // Check error scope configuration
         switch (config.errorScope) {
             case 'NetworkOnly':
                 return errorAnalysis.errorType === 'NetworkError';
@@ -2696,6 +3584,13 @@ class AIPromptRunner {
                 return true;
         }
     }
+    /**
+     * Checks if an error type matches the configured error scope
+     *
+     * @param errorType - The error type from ErrorAnalyzer
+     * @param scope - The configured error scope
+     * @returns True if the error matches the scope
+     */
     errorMatchesScope(errorType, scope) {
         switch (scope) {
             case 'NetworkOnly':
@@ -2709,31 +3604,74 @@ class AIPromptRunner {
                 return true;
         }
     }
+    /**
+     * Calculates the delay before the next failover attempt.
+     *
+     * @param attemptNumber - The current attempt number (1-based)
+     * @param baseDelaySeconds - The base delay in seconds from configuration
+     * @param previousError - The error from the previous attempt
+     * @returns Delay in milliseconds before the next attempt
+     *
+     * @remarks
+     * Implements exponential backoff with jitter by default. The delay increases
+     * exponentially with each attempt and includes random jitter to prevent
+     * thundering herd problems. Override this method to implement custom delay logic.
+     */
     calculateFailoverDelay(attemptNumber, baseDelaySeconds) {
+        // Exponential backoff: delay = base * 2^(attempt-1)
         const exponentialDelay = baseDelaySeconds * Math.pow(2, attemptNumber - 1);
+        // Add jitter (0-25% of delay) to prevent thundering herd
         const jitter = exponentialDelay * 0.25 * Math.random();
+        // Cap at 30 seconds to prevent excessive delays
         const totalDelay = Math.min(exponentialDelay + jitter, 30);
-        return totalDelay * 1000;
-    }
+        return totalDelay * 1000; // Convert to milliseconds
+    }
+    /**
+     * Selects candidate models for failover based on the strategy and current failure.
+     *
+     * @param currentModel - The model that just failed
+     * @param currentVendorId - The vendor ID that just failed
+     * @param strategy - The failover strategy to use
+     * @param modelStrategy - The model selection preference
+     * @param allCandidates - All available model-vendor candidates
+     * @param attemptHistory - History of previous failover attempts
+     * @returns Array of candidates sorted by priority (highest first)
+     *
+     * @remarks
+     * This method implements different strategies for selecting failover candidates:
+     * - SameModelDifferentVendor: Try the same model with different vendors
+     * - NextBestModel: Try different models in order of preference
+     * - PowerRank: Use the global power ranking of models
+     *
+     * Override this method to implement custom candidate selection logic.
+     */
     selectFailoverCandidates(currentModel, currentVendorId, strategy, modelStrategy, allCandidates, attemptHistory) {
+        // Filter out candidates that have already failed
+        // Note: Authentication errors are already filtered from allCandidates upstream,
+        // so we only need to filter out specific model/vendor pairs that have failed
         const failedPairs = new Set(attemptHistory.map(a => `${a.modelId}:${a.vendorId || 'default'}`));
         const availableCandidates = allCandidates.filter(c => {
             const key = `${c.model.ID}:${c.vendorId || 'default'}`;
             return !failedPairs.has(key);
         });
+        // Check if we have context length exceeded errors in the attempt history
         const hasContextLengthError = attemptHistory.some(a => a.errorType === 'ContextLengthExceeded' ||
-            ai_1.ErrorAnalyzer.analyzeError(a.error).errorType === 'ContextLengthExceeded');
+            ErrorAnalyzer.analyzeError(a.error).errorType === 'ContextLengthExceeded');
+        // Apply strategy-specific filtering and sorting
         let candidates;
         switch (strategy) {
             case 'SameModelDifferentVendor':
+                // Only consider same model with different vendors
                 candidates = availableCandidates.filter(c => c.model.ID === currentModel.ID && c.vendorId !== currentVendorId);
                 break;
             case 'NextBestModel':
+                // Consider all models, apply model strategy preference
                 candidates = availableCandidates;
                 if (modelStrategy === 'RequireSameModel') {
                     candidates = candidates.filter(c => c.model.ID === currentModel.ID);
                 }
                 else if (modelStrategy === 'PreferSameModel') {
+                    // Sort to put same model first
                     candidates.sort((a, b) => {
                         const aSameModel = a.model.ID === currentModel.ID ? 1 : 0;
                         const bSameModel = b.model.ID === currentModel.ID ? 1 : 0;
@@ -2741,6 +3679,7 @@ class AIPromptRunner {
                     });
                 }
                 else if (modelStrategy === 'PreferDifferentModel') {
+                    // Sort to put different models first
                     candidates.sort((a, b) => {
                         const aDiffModel = a.model.ID !== currentModel.ID ? 1 : 0;
                         const bDiffModel = b.model.ID !== currentModel.ID ? 1 : 0;
@@ -2749,21 +3688,25 @@ class AIPromptRunner {
                 }
                 break;
             case 'PowerRank':
+                // Use all candidates, they're already sorted by power rank
                 candidates = availableCandidates;
                 break;
             default:
                 candidates = [];
         }
+        // If we have context length errors, prioritize models with larger context windows
         if (hasContextLengthError) {
             const currentMaxTokens = currentModel.ModelVendors?.length > 0 ?
                 Math.max(...currentModel.ModelVendors.map(mv => mv.MaxInputTokens || 0)) : 0;
+            // Filter out models with same or smaller context windows
             candidates = candidates.filter(c => {
                 const candidateMaxTokens = c.model.ModelVendors?.length > 0 ?
                     Math.max(...c.model.ModelVendors.map(mv => mv.MaxInputTokens || 0)) : 0;
                 return candidateMaxTokens > currentMaxTokens;
             });
+            // If no larger models exist, this is a fatal error - return empty to stop retrying
             if (candidates.length === 0) {
-                (0, core_1.LogStatusEx)({
+                LogStatusEx({
                     message: `❌ Context length exceeded and no models with larger context windows available. Current model: ${currentModel.Name} (${currentMaxTokens} max tokens). This is a fatal error.`,
                     category: 'AI',
                     additionalArgs: [{
@@ -2773,22 +3716,27 @@ class AIPromptRunner {
                             reason: 'No models with larger context windows available for failover'
                         }]
                 });
+                // Return empty array - caller will see no candidates and stop retrying
                 return [];
             }
+            // Sort by priority first (existing algorithm), then by context window size as tiebreaker
             candidates.sort((a, b) => {
+                // Primary sort: priority (higher is better) - maintains existing algorithm
                 if (a.priority !== b.priority) {
                     return b.priority - a.priority;
                 }
+                // Secondary sort: context window size (largest first) - only as tiebreaker
                 const aMaxTokens = a.model.ModelVendors?.length > 0 ?
                     Math.max(...a.model.ModelVendors.map((mv) => mv.MaxInputTokens || 0)) : 0;
                 const bMaxTokens = b.model.ModelVendors?.length > 0 ?
                     Math.max(...b.model.ModelVendors.map((mv) => mv.MaxInputTokens || 0)) : 0;
                 return bMaxTokens - aMaxTokens;
             });
+            // Log context-aware failover selection
             const bestCandidate = candidates[0];
             const bestCandidateMaxTokens = bestCandidate.model.ModelVendors?.length > 0 ?
                 Math.max(...bestCandidate.model.ModelVendors.map((mv) => mv.MaxInputTokens || 0)) : 0;
-            (0, core_1.LogStatusEx)({
+            LogStatusEx({
                 message: `🔄 Context-aware failover: Selected model ${bestCandidate.model.Name} with ${bestCandidateMaxTokens} max input tokens (vs ${currentMaxTokens} for failed model)`,
                 category: 'AI',
                 additionalArgs: [{
@@ -2801,10 +3749,23 @@ class AIPromptRunner {
             });
         }
         else {
+            // Final sort by priority (higher is better) for non-context-length errors
             candidates.sort((a, b) => b.priority - a.priority);
         }
         return candidates;
     }
+    /**
+     * Logs a failover attempt for tracking and debugging.
+     *
+     * @param promptId - The ID of the prompt being executed
+     * @param attempt - The failover attempt details
+     * @param willRetry - Whether another attempt will be made
+     *
+     * @remarks
+     * This method logs detailed information about each failover attempt to help with
+     * debugging and monitoring. Override this method to implement custom logging or
+     * integrate with external monitoring systems.
+     */
     logFailoverAttempt(promptId, attempt, willRetry) {
         const message = `Failover attempt ${attempt.attemptNumber} for prompt ${promptId}`;
         const metadata = {
@@ -2818,14 +3779,14 @@ class AIPromptRunner {
             error: attempt.error.message
         };
         if (willRetry) {
-            (0, core_1.LogStatusEx)({
+            LogStatusEx({
                 message: `⚡ ${message}`,
                 category: 'AI',
                 additionalArgs: [metadata]
             });
         }
         else {
-            (0, core_1.LogErrorEx)({
+            LogErrorEx({
                 message: message,
                 error: attempt.error,
                 category: 'AI',
@@ -2835,8 +3796,4 @@ class AIPromptRunner {
         }
     }
 }
-exports.AIPromptRunner = AIPromptRunner;
-function LoadAIPromptRunner() {
-}
-exports.LoadAIPromptRunner = LoadAIPromptRunner;
 //# sourceMappingURL=AIPromptRunner.js.map