@memberjunction/ai-prompts 6.1.4 → 6.2.0-edge.1

package/dist/AIPromptRunner.d.ts

@@ -1,92 +1,108 @@
 import { ChatResult, ChatMessage, AIPromptConfiguration } from '@memberjunction/ai';
+import { BaseModelRunner, type ModelVendorCandidate } from './BaseModelRunner.js';
 import { NativeToolCallingDecision } from './nativeToolCallingGate.js';
 import { AIModelRunner } from './AIModelRunner.js';
-import { AIPromptRunResult } from '@memberjunction/ai-core-plus';
-import { IMetadataProvider } from '@memberjunction/core';
+import { AIPromptRunResult, AIModelSelectionInfo } from '@memberjunction/ai-core-plus';
+import { UserInfo } from '@memberjunction/core';
 import { MJAIModelEntityExtended, MJAIPromptEntityExtended, MJAIPromptRunEntityExtended } from "@memberjunction/ai-core-plus";
 import { type IParallelExecutionCoordinator } from './ParallelExecution.js';
-import { TemplateMessageRole, AIPromptParams } from '@memberjunction/ai-core-plus';
+import { TemplateMessageRole, ChildPromptParam, AIPromptParams } from '@memberjunction/ai-core-plus';
+export type { ExecutionBound, FailoverConfiguration } from './BaseModelRunner.js';
 /**
- * The composed bound applied to a single model call: the caller's cancellation token (if any) merged
- * with the prompt's configured `AIPrompt.TimeoutMS` (if any).
+ * Advanced AI Prompt execution engine with comprehensive template support, hierarchical template composition,
+ * sophisticated model selection, parallelization, output validation, and execution tracking.
  *
- * Produced by `AIPromptRunner.createExecutionBound` and consumed by the bounded ChatCompletion race.
- * `Dispose()` MUST be called when the call settles so the timeout timer and abort listener are
- * released.
- */
-export interface ExecutionBound {
-    /** Merged abort signal; `undefined` when there is neither a caller token nor a prompt timeout. */
-    Signal?: AbortSignal;
-    /** The prompt-configured timeout in ms, when one applies. */
-    TimeoutMS?: number;
-    /** True once the TIMEOUT (not the caller's token) fired — used to build the right error. */
-    TimedOut: () => boolean;
-    /** Releases the timer and the caller-token listener. Safe to call multiple times. */
-    Dispose: () => void;
-}
-/**
- * Represents a model-vendor pair candidate for execution
- */
-interface ModelVendorCandidate {
-    model: MJAIModelEntityExtended;
-    vendorId?: string;
-    vendorName?: string;
-    driverClass: string;
-    apiName?: string;
-    supportsEffortLevel?: boolean;
-    effortLevel?: number;
-    /**
-     * The `PromptConfiguration` bag of the `AIPromptModel` row this candidate came from, when it came
-     * from one. Threaded like `effortLevel` rather than looked up later, because a candidate sourced
-     * from power-rank or model-type has NO prompt-model row and must contribute no override.
-     */
-    promptModelConfiguration?: AIPromptConfiguration | null;
-    isPreferredVendor: boolean;
-    priority: number;
-    source: 'explicit' | 'prompt-model' | 'model-type' | 'power-rank' | 'power-match-fallback';
-}
-/**
- * Configuration for failover behavior when primary model fails.
+ * ## Core Features
+ * - **Template-based prompt generation** using MJ Templates system
+ * - **Hierarchical template composition** with depth-first rendering and parallel template processing
+ * - **Advanced model selection** strategies (Default, Specific, ByPower)
+ * - **Parallel execution** with multiple models and execution groups
+ * - **Structured output validation** and type conversion with retry logic
+ * - **Comprehensive execution tracking** with agent run linking
+ * - **Configuration-driven behavior** with caching and performance optimization
+ * - **Real-time progress updates** and streaming response support
+ *
+ * ## Hierarchical Template Composition
+ * When `childPrompts` array is provided in {@link AIPromptParams}:
+ * 1. Renders child prompt templates in depth-first manner (children before parents)
+ * 2. At each level, renders sibling templates in parallel for optimal performance
+ * 3. Recursively handles grandchild templates (unlimited nesting depth)
+ * 4. Substitutes rendered child templates into corresponding placeholders in parent template
+ * 5. Executes the final composed prompt as a single operation
+ *
+ * This enables complex prompt composition patterns where templates can be built from reusable
+ * sub-templates, creating sophisticated prompts through hierarchical template inheritance.
  *
- * Exported because it is the return type of `AIPromptRunner.getFailoverConfiguration`, a
- * `protected` method documented as an override point — a subclass cannot name its own return type
- * otherwise, which made the documented extension point unusable from outside this package.
+ * ## Agent Integration
+ * - Supports agent decision-making workflows with structured JSON responses
+ * - Enables hierarchical template patterns in AI agents
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const runner = new AIPromptRunner();
+ * const params = new AIPromptParams();
+ * params.prompt = aiPrompt;
+ * params.data = { key: 'value' };
+ * const result = await runner.ExecutePrompt(params);
+ * ```
+ *
+ * @example Hierarchical Template Composition
+ * ```typescript
+ * const params = new AIPromptParams();
+ * params.prompt = parentPrompt;
+ * params.childPrompts = [
+ *   new ChildPromptParam(analysisPrompt, 'analysis'),
+ *   new ChildPromptParam(summaryPrompt, 'summary'),
+ *   new ChildPromptParam(complexChild, 'complex') // This can have its own child templates
+ * ];
+ * params.data = { userInput: 'complex data to process' };
+ * const result = await runner.ExecutePrompt(params);
+ * // Child templates render first, then parent template uses {{ analysis }}, {{ summary }}, {{ complex }}
+ * // Final composed prompt is executed once
+ * ```
  */
-export interface FailoverConfiguration {
-    strategy: 'SameModelDifferentVendor' | 'NextBestModel' | 'PowerRank' | 'None';
-    maxAttempts: number;
-    delaySeconds: number;
-    modelStrategy?: 'PreferSameModel' | 'PreferDifferentModel' | 'RequireSameModel';
-    errorScope?: 'All' | 'NetworkOnly' | 'RateLimitOnly' | 'ServiceErrorOnly';
-}
 /**
- * Tracks information about a failover attempt
+ * Bundles the full output of selectModel so it can be threaded through
+ * ExecutePrompt → executeSinglePrompt / executePromptInParallel without
+ * discarding vendor-resolution data that would need to be re-derived.
  */
-interface FailoverAttempt {
-    attemptNumber: number;
-    modelId: string;
-    vendorId?: string;
-    error: Error;
-    errorType: string;
-    duration: number;
-    timestamp: Date;
+export interface ModelSelectionResult {
+    model: MJAIModelEntityExtended | null;
+    vendorDriverClass?: string;
+    vendorApiName?: string;
+    vendorSupportsEffortLevel?: boolean;
+    modelEffortLevel?: number;
+    /** The selected candidate's AIPromptModel `PromptConfiguration`, for the native tool-calling gate. */
+    promptModelConfiguration?: AIPromptConfiguration | null;
+    selectionInfo?: AIModelSelectionInfo;
+    allCandidates: ModelVendorCandidate[];
+    /**
+     * Per-candidate credential-availability already computed by
+     * {@link AIPromptRunner.selectModelWithAPIKeyTracked} during selection, keyed by
+     * `driverClass:modelID:vendorId` (the same key {@link AIPromptRunner.executeModelWithFailover}
+     * uses for its own cache). Lets failover REUSE selection's credential probes instead of
+     * recomputing `HasCredentialsAvailable` for the prefix it already walked.
+     *
+     * Because selection short-circuits once the highest-priority credentialed candidate is found
+     * (see the DECISION note in {@link AIPromptRunner.selectModelWithAPIKeyTracked}), this map
+     * only contains the candidates UP TO AND INCLUDING the selected one. The not-evaluated tail is
+     * intentionally absent so failover still probes it lazily — only if it ever has to walk down
+     * there during an actual failover.
+     */
+    credentialAvailability?: Map<string, boolean>;
 }
-export declare class AIPromptRunner {
-    private _metadata;
+export declare class AIPromptRunner extends BaseModelRunner {
+    /**
+     * The model type this runner requires. Returns 'LLM' for AIPromptRunner.
+     */
+    get RequiredModelType(): string;
+    /** Keeps this runner's uncategorized errors logged under `AIPromptRunner`, as before the base class existed. */
+    protected get DefaultLogCategory(): string;
     private _templateEngine;
     private _executionPlanner;
     private _parallelCoordinator?;
     private _jsonValidator;
     private _modelRunner;
-    private _provider;
-    /**
-     * Fire-and-forget AIPromptRun persistence. Prompt-run logging never blocks the execution path on a
-     * DB round-trip; the shared {@link BaseEntitySaveQueue} sequences saves for the SAME entity (the
-     * initial 'Running' INSERT always completes before the finalize UPDATE, and the finalize mutation
-     * runs INSIDE the post-INSERT task so a slow INSERT can never clobber the finalized row). Failures
-     * stay in this runner's structured log stream via the queue's `onError` hook.
-     */
-    private _promptRunQueue;
     /**
      * Process-wide cache of parsed `OutputExample` JSON, keyed by the raw example string.
      * A prompt's OutputExample is a static string reused across every run and every validation
@@ -102,13 +118,6 @@ export declare class AIPromptRunner {
      * already been selected. See the DECISION note in {@link selectModelWithAPIKeyTracked}.
      */
     private static readonly NOT_EVALUATED_REASON;
-    /**
-     * Optional metadata provider override. Callers should set
-     * `instance.Provider = providerToUse` before invoking run methods
-     * in multi-provider contexts. Falls back to the global default provider when unset.
-     */
-    get Provider(): IMetadataProvider;
-    set Provider(value: IMetadataProvider | null);
     constructor();
     /** ClassFactory key the parallel coordinator self-registers under (see {@link ParallelCoordinator}). */
     private static readonly PARALLEL_COORDINATOR_KEY;
@@ -130,100 +139,6 @@ export declare class AIPromptRunner {
      * Use this when you need tracked embedding execution with AIPromptRun record creation.
      */
     get ModelRunner(): AIModelRunner;
-    /**
-     * Performs robust validation of an API key
-     * @returns true if the API key is valid (not null, undefined, or empty/whitespace)
-     */
-    private isValidAPIKey;
-    /**
-     * 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
-     */
-    protected logStatus(message: string, verboseOnly?: boolean, params?: AIPromptParams): void;
-    /**
-     * Helper method for enhanced error logging with metadata
-     */
-    protected logError(error: Error | string, options?: {
-        category?: string;
-        metadata?: Record<string, any>;
-        prompt?: MJAIPromptEntityExtended;
-        model?: MJAIModelEntityExtended;
-        severity?: 'warning' | 'error' | 'critical';
-        maxErrorLength?: number;
-    }): void;
-    /**
-     * Checks if a model vendor is configured as an inference provider.
-     * Delegates to the memoized {@link AIEngine.IsInferenceProvider} helper so the
-     * "Inference Provider" vendor-type lookup happens once per engine load rather than on
-     * every candidate in every selection pass.
-     * @param modelVendor The model vendor to check
-     * @returns true if the vendor is an inference provider
-     */
-    private isInferenceProvider;
-    /**
-     * 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
-     */
-    private resolveCredentialForExecution;
-    /**
-     * Attempts to resolve credentials from bindings with priority-based failover.
-     * Tries each binding in priority order until one succeeds.
-     */
-    private tryCredentialBindingsWithFailover;
-    /**
-     * Attempts to resolve a single credential, returning null on failure for failover support.
-     */
-    private tryResolveCredential;
-    /**
-     * Resolves a credential by its explicit ID (used for per-request override).
-     * This does not support failover since it's an explicit choice.
-     */
-    private resolveCredentialById;
-    /**
-     * Finds a default credential matching a specific credential type.
-     */
-    private findDefaultCredentialByType;
-    /**
-     * 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
-     */
-    private hasCredentialsAvailable;
     /**
      * Executes an AI prompt with full support for templates, model selection, and validation.
      *
@@ -293,6 +208,24 @@ export declare class AIPromptRunner {
      * @param cancellationToken - Cancellation token for aborting rendering
      * @returns Promise with rendered templates map
      */
+    /**
+     * Render a set of child prompt templates WITHOUT executing anything, returning the rendered text
+     * keyed by each child's parent placeholder — exactly what the hierarchical execution path embeds
+     * into the parent template.
+     *
+     * Exposed for callers that need a child's rendered text before the run: the loop agent uses it to
+     * relocate a volatile specialization into the trailing runtime-state message (see
+     * `ResolveSpecializationPlacement` in `@memberjunction/ai-agents`) while the system prompt renders a
+     * stub in its place. Rendering is deterministic for the same inputs, so a subsequent execution of
+     * the same params reproduces the same text.
+     *
+     * @param childPrompts The child prompt params, as they would be passed in `AIPromptParams.childPrompts`.
+     * @param params The parent params (context user, data, template data) the children render against.
+     * @param cancellationToken Optional abort signal.
+     */
+    RenderChildPromptTemplates(childPrompts: ChildPromptParam[], params: AIPromptParams, cancellationToken?: AbortSignal): Promise<{
+        renderedTemplates: Record<string, string>;
+    }>;
     private renderChildPromptTemplates;
     /**
      * Renders a prompt template with child prompt templates merged into the data context.
@@ -305,129 +238,10 @@ export declare class AIPromptRunner {
     private renderPromptWithChildTemplates;
     /**
      * Selects the appropriate AI model based on prompt configuration and parameters.
-     * Uses the unified buildModelVendorCandidates method to create an ordered list of candidates,
+     * Uses the unified BuildModelVendorCandidates method to create an ordered list of candidates,
      * then selects the first one with an available API key.
      */
-    private selectModel;
-    /**
-     * 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)
-     */
-    private buildModelVendorCandidates;
-    /**
-     * PHASE 1: Build candidates for explicitly specified model ID.
-     * Returns candidates for the single model if it's active and compatible.
-     */
-    private buildCandidatesForExplicitModel;
-    /**
-     * 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)
-     */
-    private buildCandidatesForSpecificStrategy;
-    /**
-     * Appends fallback candidates from the global model pool, sorted by proximity to the
-     * average power rank of the originally configured models. This ensures that when
-     * specific models lack credentials, the fallback uses models of similar capability
-     * rather than defaulting to the most or least powerful available model.
-     *
-     * Fallback candidates are given lower priority than any specific candidate so
-     * configured models are always preferred when their credentials are available.
-     */
-    private appendPowerMatchedFallbackCandidates;
-    /**
-     * Computes the target power rank from configured AIPromptModel records.
-     * Uses the weighted average (by priority) of the configured models' power ranks,
-     * so higher-priority models have more influence on the target.
-     * Falls back to simple average if priorities are all zero.
-     */
-    private computeTargetPowerRank;
-    /**
-     * Sorts models by proximity to a target power rank (closest first).
-     * When two models are equidistant, the higher-powered one is preferred.
-     */
-    private sortByPowerProximity;
-    /**
-     * PHASE 3: Build candidates for general selection strategies ('Default' or 'ByPower').
-     * Uses configuration-aware fallback hierarchy with legacy blended priority calculation.
-     */
-    private buildCandidatesForGeneralSelection;
-    /**
-     * Helper: Filter prompt models by configuration matching rules.
-     * Supports configuration inheritance - includes models from the entire inheritance chain.
-     */
-    private filterPromptModelsByConfiguration;
-    /**
-     * 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.
-     */
-    private sortPromptModelsForSpecificStrategy;
-    /**
-     * Helper: Build candidates from sorted AIPromptModel records.
-     * Expands VendorID=null to all vendors for that model.
-     */
-    private buildCandidatesFromPromptModels;
-    /**
-     * Helper: Create candidate for specific vendor from AIPromptModel.
-     */
-    private createCandidateForSpecificVendor;
-    /**
-     * Helper: Create candidates for all vendors of a model, sorted by vendor priority.
-     */
-    private createCandidatesForAllVendors;
-    /**
-     * Helper: true if this prompt has any AIPromptModel bindings at all, regardless of Status or
-     * ConfigurationID. Distinguishes "no bindings were ever configured" (general selection strategy
-     * should apply) from "bindings exist but are all Inactive" (no model should be selected).
-     */
-    private hasAnyPromptModelBindings;
-    /**
-     * 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.
-     */
-    private getPromptModelsForConfiguration;
-    /**
-     * Helper: Add prompt-specific candidates with blended priorities (legacy behavior).
-     */
-    private addPromptSpecificCandidates;
-    /**
-     * Helper: Add configuration fallback candidates from the inheritance chain.
-     * Adds models from parent configs (with decreasing priority) and null-config models as final fallback.
-     */
-    private addConfigurationFallbackCandidates;
-    /**
-     * Helper: Add strategy-based candidates when no prompt models exist.
-     */
-    private addStrategyBasedCandidates;
-    /**
-     * Helper: Get model pool filtered for strategy.
-     */
-    private getModelPoolForStrategy;
-    /**
-     * Helper: Sort model pool by selection strategy.
-     */
-    private sortModelPoolByStrategy;
-    /**
-     * Helper: Sort models by power preference.
-     */
-    private sortByPowerPreference;
-    /**
-     * Helper: Create candidates for a model with AIModelVendor priorities (legacy behavior).
-     */
-    private createCandidatesForModel;
+    protected selectModel(prompt: MJAIPromptEntityExtended, explicitModelId?: string, contextUser?: UserInfo, configurationId?: string, vendorId?: string, params?: AIPromptParams): Promise<ModelSelectionResult>;
     /**
      * Creates a properly typed AIModelSelectionInfo instance.
      * TypeScript requires instantiating the class to get the getValidCandidates() method.
@@ -450,24 +264,6 @@ export declare class AIPromptRunner {
      * so the error message is actionable for end users (e.g., missing API credentials).
      */
     private buildNoModelFoundMessage;
-    /**
-     * Creates an AIPromptRun entity for execution tracking
-     */
-    /**
-     * Resolves the scalar inference parameters for a run: each value is the per-request override
-     * from `additionalParameters` when supplied, otherwise the prompt's configured default. This
-     * is the single source of truth for parameter precedence so {@link executeModel} (ChatParams)
-     * and {@link createPromptRun} (the persisted record) stay in lockstep. Stop sequences and
-     * assistant prefill are intentionally excluded — their representations differ per target.
-     */
-    private resolveScalarInferenceParams;
-    /**
-     * Awaits all in-flight prompt-run saves queued by this runner instance. The normal execution path
-     * does NOT call this — prompt-run persistence is intentionally fire-and-forget. Exposed for tests
-     * and for callers that need the AIPromptRun rows durably written before proceeding.
-     */
-    WaitForPendingPromptRunSaves(): Promise<void>;
-    private createPromptRun;
     /**
      * Renders the prompt template with provided data
      */
@@ -480,30 +276,14 @@ export declare class AIPromptRunner {
      * 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
+     * Candidates come from model selection (`allCandidates`), already filtered to the prompt's
+     * model type by ID. When failover applies, the loop itself is
+     * {@link BaseModelRunner.ExecuteWithFailover}: this method supplies the chat call on each candidate
+     * (`executeModel` with that candidate's model, vendor, driver, effort level and prompt-model
+     * configuration) and the final error result (`createFailoverErrorResult`). The base records
+     * failover success or failure on the prompt run.
      */
     protected executeModelWithFailover(model: MJAIModelEntityExtended, renderedPrompt: string, prompt: MJAIPromptEntityExtended, params: AIPromptParams, vendorId: string | null, conversationMessages?: ChatMessage[], templateMessageRole?: TemplateMessageRole, cancellationToken?: AbortSignal, allCandidates?: ModelVendorCandidate[], promptRun?: MJAIPromptRunEntityExtended, vendorDriverClass?: string, vendorApiName?: string, vendorSupportsEffortLevel?: boolean, modelEffortLevel?: number, credentialAvailability?: Map<string, boolean>, promptModelConfiguration?: AIPromptConfiguration | null): Promise<ChatResult>;
-    /**
-     * Builds failover candidates for a prompt based on available models and type restrictions
-     */
-    protected buildFailoverCandidates(prompt: MJAIPromptEntityExtended): Promise<ModelVendorCandidate[]>;
-    /**
-     * Creates model-vendor candidates from a list of models
-     */
-    protected createCandidatesFromModels(models: MJAIModelEntityExtended[]): ModelVendorCandidate[];
-    /**
-     * Updates prompt run with successful failover tracking data
-     */
-    protected updatePromptRunWithFailoverSuccess(promptRun: MJAIPromptRunEntityExtended, failoverAttempts: FailoverAttempt[], currentModel: MJAIModelEntityExtended, currentVendorId: string | null): void;
-    /**
-     * Updates prompt run with failover failure tracking data
-     */
-    private updatePromptRunWithFailoverFailure;
     /**
      * Creates an error result for failed failover attempts
      */
@@ -540,6 +320,8 @@ export declare class AIPromptRunner {
      * Never throws: the gate is an opt-in enhancement and must not be able to fail a run that would
      * otherwise succeed, so any configuration problem resolves to the path that has always worked.
      */
+    ResolveNativeToolCallingDecision(prompt: MJAIPromptEntityExtended, params: AIPromptParams, model: MJAIModelEntityExtended, vendorId: string | null, promptModelConfiguration?: AIPromptConfiguration | null): NativeToolCallingDecision;
+    /** @deprecated Use {@link ResolveNativeToolCallingDecision}. */
     resolveNativeToolCallingDecision(prompt: MJAIPromptEntityExtended, params: AIPromptParams, model: MJAIModelEntityExtended, vendorId: string | null, promptModelConfiguration?: AIPromptConfiguration | null): NativeToolCallingDecision;
     private applyNativeToolCalling;
     /**
@@ -569,44 +351,6 @@ export declare class AIPromptRunner {
     /** Scans provider prose for a tools marker. Shared by the thrown-error and failed-result paths. */
     private isToolSpecificFailureText;
     protected executeModel(model: MJAIModelEntityExtended, renderedPrompt: string, prompt: MJAIPromptEntityExtended, params: AIPromptParams, vendorId: string | null, conversationMessages?: ChatMessage[], templateMessageRole?: TemplateMessageRole, cancellationToken?: AbortSignal, vendorDriverClass?: string, vendorApiName?: string, vendorSupportsEffortLevel?: boolean, modelEffortLevel?: number, promptModelConfiguration?: AIPromptConfiguration | null): Promise<ChatResult>;
-    /**
-     * Engine-level default model-call timeout, in milliseconds, applied when the caller supplies no
-     * `AIPromptParams.timeoutMS`. `undefined` (the default) means NO implicit bound — a prompt run
-     * with neither a timeout nor a cancellation token stays unbounded, exactly as before, so this
-     * change is behavior-preserving for existing callers.
-     *
-     * Subclasses (or a host application's runner subclass) can override this to impose a global
-     * safety ceiling on every prompt call.
-     */
-    protected get DefaultPromptTimeoutMS(): number | undefined;
-    /**
-     * Resolves the per-model-call timeout: the caller's `AIPromptParams.timeoutMS`, else the runner's
-     * {@link DefaultPromptTimeoutMS}. Non-positive / non-numeric values mean "no timeout".
-     *
-     * The bound is applied PER MODEL CALL (not per prompt execution), which mirrors the parallel
-     * path's existing `taskTimeoutMS` semantics: each failover candidate / validation retry gets a
-     * fresh budget rather than sharing one wall-clock window.
-     *
-     * NOTE (issue #3064): there is deliberately NO prompt-entity source here yet — the `AIPrompt`
-     * table has no `TimeoutMS` column today. Once a migration adds one and CodeGen regenerates the
-     * entity, this becomes `prompt.TimeoutMS ?? params.timeoutMS ?? this.DefaultPromptTimeoutMS`
-     * and every bound below starts honoring the per-prompt configuration with no other change.
-     */
-    protected getEffectiveTimeoutMS(params: AIPromptParams): number | undefined;
-    /**
-     * Composes the caller-supplied cancellation token with the resolved model-call timeout into a
-     * single {@link AbortSignal} that bounds one model call. NEITHER bound is discarded:
-     *
-     * - caller token only  → the caller's signal is used directly (behavior unchanged)
-     * - timeout only       → an internal controller aborts after the timeout elapses
-     * - both               → an internal controller relays the caller's abort AND fires on timeout;
-     *                        whichever happens first wins
-     * - neither            → `Signal` is undefined and the call runs unbounded (legacy behavior)
-     *
-     * Implemented with an AbortController + relay listener rather than `AbortSignal.any()` so it works
-     * on Node 18 (where `AbortSignal.any` does not exist — it landed in Node 20.3).
-     */
-    protected createExecutionBound(prompt: MJAIPromptEntityExtended, params: AIPromptParams, cancellationToken?: AbortSignal): ExecutionBound;
     /**
      * Runs the model call, racing it against the composed execution bound so a hung provider surfaces
      * as a rejected promise the caller's failover/retry logic can act on.
@@ -664,23 +408,6 @@ export declare class AIPromptRunner {
      */
     private injectNativeFileInputs;
     private buildMessageArray;
-    /**
-     * Default fallback instruction text used when no PrefillFallbackText is configured
-     * at any level of the AIModelType → AIModel → AIModelVendor cascade.
-     */
-    private static readonly DEFAULT_PREFILL_FALLBACK;
-    /**
-     * Regex used to trim only horizontal whitespace (spaces and tabs) from the start and end
-     * of each stop sequence token after comma-splitting.
-     *
-     * We intentionally do NOT use String.trim() here because stop sequences can legitimately
-     * begin or end with newline characters. For example, the sequence "\n```" is designed to
-     * match only a closing code fence (preceded by a newline), distinguishing it from an
-     * opening "```json" fence that does not start with a newline. Using trim() would strip
-     * that leading "\n", turning "\n```" into "```" and causing the stop to fire on the
-     * opening fence instead — producing an empty response for non-native prefill providers.
-     */
-    private static readonly STOP_SEQUENCE_TRIM_REGEX;
     /**
      * Substrings that mark a provider failure as TOOLS-specific, so the native call is worth one
      * envelope retry (see {@link AIPromptRunner.isToolSpecificFailure}). Drawn from how the
@@ -737,58 +464,31 @@ export declare class AIPromptRunner {
      */
     private shouldApplyStopSequences;
     private resolveSupportsPrefill;
-    /**
-     * Resolves the prefill fallback instruction text using the cascade:
-     * AIModelType → AIModel → AIModelVendor (most specific non-null wins).
-     * Falls back to DEFAULT_PREFILL_FALLBACK if none are configured.
-     */
-    private resolvePrefillFallbackText;
     /**
      * Applies assistant prefill to ChatParams based on prompt configuration and provider support.
      * Handles the full prefill resolution logic including fallback to system instructions.
      */
     private applyAssistantPrefill;
     /**
-     * Executes the model with retry logic for validation failures
-     */
-    private executeWithValidationRetries;
-    /**
-     * 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.
-     */
-    private calculateRetryDelay;
-    private applyRetryDelay;
-    /**
-     * 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
+     * Default fallback instruction text used when no PrefillFallbackText is configured
+     * at any level of the AIModelType → AIModel → AIModelVendor cascade.
      */
-    private filterVendorCandidates;
+    private static readonly DEFAULT_PREFILL_FALLBACK;
     /**
-     * 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.
+     * Resolves the prefill fallback instruction text using the cascade:
+     * AIModelType → AIModel → AIModelVendor (most specific non-null wins).
+     * Falls back to DEFAULT_PREFILL_FALLBACK if none are configured.
      */
-    private handleRateLimitRetry;
+    private resolvePrefillFallbackText;
     /**
-     * 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
+     * Executes the model with retry logic for validation failures
      */
-    private processFailoverError;
+    private executeWithValidationRetries;
     /**
      * Transitions to the next failover candidate.
      * Returns the next candidate info or null if no candidates are available.
      */
     private transitionToNextCandidate;
-    /**
-     * Provides a human-readable description of the validation decision
-     */
-    private getValidationDecisionDescription;
     /**
      * Generates a JSON schema from an example object for validation
      */
@@ -911,104 +611,38 @@ export declare class AIPromptRunner {
      */
     private validateAgainstSchema;
     /**
-     * Updates the AIPromptRun entity with execution results
-     */
-    private updatePromptRun;
-    /**
-     * Populates a prompt-run's finalized fields (result, tokens, cost, timing, rollups) from the model
-     * result. Runs INSIDE the post-INSERT save task — see {@link updatePromptRun}. Errors here are
-     * logged (non-fatal): the AIPromptRun is observability, not part of the prompt's success contract.
-     */
-    private applyFinalizedPromptRunFields;
-    /**
-     * 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
-     */
-    /**
-     * 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.
+     * Creates an AIPromptRun entity for execution tracking
      */
-    protected getFailoverConfiguration(prompt: MJAIPromptEntityExtended): FailoverConfiguration;
+    private createPromptRun;
     /**
-     * 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.
+     * Sets a prompt-run's chat-specific request fields: messages, prefill, sampling parameters,
+     * response format, streaming, effort level, child prompt and the validation/retry columns. Called by
+     * {@link BaseModelRunner.CreateRunRecord} just before the INSERT is queued.
      */
-    protected shouldAttemptFailover(error: Error, config: FailoverConfiguration, attemptNumber: number): boolean;
+    private applyChatRequestFields;
     /**
-     * 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
+     * Updates the AIPromptRun entity with execution results
      */
-    private errorMatchesScope;
+    private updatePromptRun;
     /**
-     * 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.
+     * Populates a prompt-run's chat-specific finalized fields (result, tokens, cost, timing, validation)
+     * from the model result. Runs INSIDE the post-INSERT save task — see {@link BaseModelRunner.FinalizeRunRecord},
+     * which sets the completion timing, `Success` and `Status` before this runs and the rollups after it,
+     * and logs (non-fatal) any error thrown here: the AIPromptRun is observability, not part of the
+     * prompt's success contract.
      */
-    protected calculateFailoverDelay(attemptNumber: number, baseDelaySeconds: number): number;
+    private applyChatResultFields;
     /**
-     * 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.
+     * Provides a human-readable description of the validation decision
      */
-    protected selectFailoverCandidates(currentModel: MJAIModelEntityExtended, currentVendorId: string | undefined, strategy: FailoverConfiguration['strategy'], modelStrategy: FailoverConfiguration['modelStrategy'], allCandidates: ModelVendorCandidate[], attemptHistory: FailoverAttempt[]): ModelVendorCandidate[];
+    private getValidationDecisionDescription;
     /**
-     * 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.
+     * Resolves the scalar inference parameters for a run: each value is the per-request override
+     * from `additionalParameters` when supplied, otherwise the prompt's configured default. This
+     * is the single source of truth for parameter precedence so {@link executeModel} (ChatParams)
+     * and {@link createPromptRun} (the persisted record) stay in lockstep. Stop sequences and
+     * assistant prefill are intentionally excluded — their representations differ per target.
      */
-    protected logFailoverAttempt(promptId: string, attempt: FailoverAttempt, willRetry: boolean): void;
+    private resolveScalarInferenceParams;
 }
-export {};
 //# sourceMappingURL=AIPromptRunner.d.ts.map