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

package/dist/BaseModelRunner.d.ts

@@ -0,0 +1,583 @@
+/**
+ * @fileoverview Abstract base runner for MemberJunction AI model executions.
+ *
+ * Encapsulates modality-agnostic machinery:
+ * - Candidate building and selection
+ * - Credential resolution and failover
+ * - Execution bounds and timeout management
+ * - AIPromptRun entity lifecycle tracking and persistence
+ * - Retry and failover helpers
+ *
+ * @module @memberjunction/ai-prompts
+ * @author MemberJunction.com
+ */
+import { BaseEntitySaveQueue, Metadata, IMetadataProvider } from '@memberjunction/core';
+import { MJAIModelVendorEntity } from '@memberjunction/core-entities';
+import { MJAIModelEntityExtended, MJAIPromptEntityExtended, MJAIPromptRunEntityExtended, AIPromptParams, AIModelSelectionInfo } from '@memberjunction/ai-core-plus';
+import { BaseResult, AIPromptConfiguration } from '@memberjunction/ai';
+/**
+ * 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).
+ *
+ * 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
+ */
+export 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.
+ *
+ * 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.
+ */
+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
+ */
+export interface FailoverAttempt {
+    attemptNumber: number;
+    modelId: string;
+    vendorId?: string;
+    error: Error;
+    errorType: string;
+    duration: number;
+    timestamp: Date;
+}
+/**
+ * Shared machinery for runners that invoke a model and record the call as an `MJ: AI Prompt Runs`
+ * row: candidate model/vendor selection, credential resolution, execution bounds (timeout and
+ * cancellation), failover helpers, and the prompt-run save queue.
+ *
+ * `AIPromptRunner`, the chat runner, is built on it. Subclasses declare the model type they run
+ * through {@link BaseModelRunner.RequiredModelType}.
+ */
+export declare abstract class BaseModelRunner {
+    /**
+     * The model type this runner requires, as the **name** of an `MJ: AI Model Types` row: `'LLM'` for
+     * `AIPromptRunner`, `'Embeddings'` (`AIEngine.Instance.EmbeddingModelTypeName`) for an embeddings
+     * runner.
+     *
+     * The contract:
+     * - It is a name, not an ID, so a subclass can declare it without a metadata lookup. The base
+     *   resolves it to the type's ID through `AIEngine.Instance.ModelTypes` ({@link RequiredModelTypeID}:
+     *   a case-insensitive, trimmed name match) and compares each model's `AIModelTypeID` with that ID
+     *   using `UUIDsEqual`, on every candidate-selection path. Names are never compared with each other,
+     *   and a name that matches no model type is an error.
+     * - It is a hard floor. `AIPrompt.AIModelTypeID` may equal it. Model types are flat, so a prompt type
+     *   that differs would widen or contradict the floor, and the runner refuses the prompt with an error
+     *   naming both the prompt's configured type and the runner's required type.
+     * - `AIPrompt.AIModelTypeID = NULL` means "whatever the runner requires" (not "any model").
+     *   This closes a footgun where prompts with an unset column drew models of every type.
+     * - Bound models (`AIPromptModel`) of a different type are skipped during candidate building
+     *   with a `LogStatus` warning, but do not fail the prompt unless no valid candidates remain.
+     * - Model overrides of a different type return no candidate (an override cannot violate the
+     *   runner's hard floor).
+     */
+    abstract get RequiredModelType(): string;
+    protected _provider: IMetadataProvider | null;
+    protected _metadata: Metadata;
+    /**
+     * 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);
+    /**
+     * 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;
+    /**
+     * The category {@link logError} records when the caller passes none. Override it so a runner's
+     * uncategorized errors are attributed to that runner rather than to the base.
+     */
+    protected get DefaultLogCategory(): string;
+    /**
+     * 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
+     */
+    protected IsInferenceProvider(modelVendor: MJAIModelVendorEntity): boolean;
+    /**
+     * 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.
+     */
+    protected _promptRunQueue: BaseEntitySaveQueue;
+    /**
+     * 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
+     */
+    protected ResolveCredentialForExecution(driverClass: string, promptId: string | undefined, modelId: string | undefined, vendorId: string | undefined, params: AIPromptParams): Promise<string>;
+    /**
+     * 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
+     */
+    protected HasCredentialsAvailable(driverClass: string, promptId: string | undefined, modelId: string | undefined, vendorId: string | undefined, params?: AIPromptParams): boolean;
+    /**
+     * Resolves the runner's {@link RequiredModelType} name against `AIEngine.Instance.ModelTypes`
+     * (case-insensitive, trimmed) and returns its UUID. Callers compare models' `AIModelTypeID` with it
+     * using `UUIDsEqual`.
+     * Throws a descriptive error if the model type is not found in the engine metadata.
+     */
+    protected RequiredModelTypeID(): string;
+    /** The name of a model type for messages, or its ID when the engine doesn't know it. */
+    private modelTypeName;
+    /**
+     * Asserts that the prompt's configured model type matches the runner's required model type.
+     * If `prompt.AIModelTypeID` is null or undefined, does not throw (the runner's required type applies).
+     * If `prompt.AIModelTypeID` is set and does not match {@link RequiredModelTypeID}, throws a descriptive
+     * error naming the prompt, the prompt's configured type (resolved to name if possible), and the runner's
+     * required type.
+     */
+    protected AssertPromptMatchesRequiredType(prompt: MJAIPromptEntityExtended): void;
+    /**
+     * 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)
+     */
+    protected BuildModelVendorCandidates(prompt: MJAIPromptEntityExtended, explicitModelId?: string, configurationId?: string, preferredVendorId?: string, verbose?: boolean): ModelVendorCandidate[];
+    /**
+     * PHASE 1: Build candidates for explicitly specified model ID.
+     * Returns candidates for the single model if it's active. Throws if the model is of a different type
+     * than the runner requires: the caller asked for that model by ID, so running a different one instead
+     * would be wrong, and an empty result would surface only a generic "no candidates" message.
+     */
+    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;
+    /**
+     * 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>;
+    /**
+     * Creates the `MJ: AI Prompt Runs` record for one model call, fills the fields every runner shares,
+     * lets the subclass add its own request fields, then queues the INSERT (fire-and-forget).
+     *
+     * For prompt-based runners: the record is always tied to an `AIPrompt` and its `AIPromptParams`.
+     *
+     * @param applyRequestFields Sets the runner's own request columns. It runs once, after the shared
+     *   fields are set and before the INSERT is queued, so everything it sets is on the inserted row.
+     *   **It must be synchronous.** An `async` callback type-checks against this signature, but any
+     *   field it sets after its first `await` races the INSERT and can miss the row.
+     */
+    protected CreateRunRecord(prompt: MJAIPromptEntityExtended, model: MJAIModelEntityExtended, params: AIPromptParams, startTime: Date, vendorId?: string, modelSelectionInfo?: AIModelSelectionInfo, applyRequestFields?: (promptRun: MJAIPromptRunEntityExtended) => void): Promise<MJAIPromptRunEntityExtended>;
+    /**
+     * 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;
+    /**
+     * Runs one model call across the failover candidates, in priority order: skips candidates with no
+     * credentials, lets processFailoverError decide retry / next candidate / stop, and records failover
+     * success or failure on the prompt run. The model call itself and the final error result are
+     * supplied by the subclass, so the loop works for any result type that extends BaseResult.
+     *
+     * For prompt-based runners: it takes the `AIPrompt` and `AIPromptParams` the call is for, and
+     * candidates that carry prompt-model fields (effort level, the `AIPromptModel` configuration).
+     *
+     * @param executeOnCandidate Makes the call on one candidate. It must use the candidate's own model,
+     *   vendor, driver and prompt-model fields, not those of the first candidate.
+     * @param createErrorResult Builds the result returned when every candidate has failed.
+     */
+    protected ExecuteWithFailover<TResult extends BaseResult>(prompt: MJAIPromptEntityExtended, params: AIPromptParams, allCandidates: ModelVendorCandidate[], failoverConfig: FailoverConfiguration, executeOnCandidate: (candidate: ModelVendorCandidate) => Promise<TResult>, createErrorResult: (lastError: Error | null, failoverAttempts: FailoverAttempt[]) => TResult, promptRun?: MJAIPromptRunEntityExtended, credentialAvailability?: Map<string, boolean>): Promise<TResult>;
+    /**
+     * 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;
+    /**
+     * 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;
+    protected ApplyRetryDelay(prompt: MJAIPromptEntityExtended, attemptNumber: number, suggestedDelaySeconds?: number): Promise<void>;
+    /**
+     * 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
+     */
+    private filterVendorCandidates;
+    /**
+     * 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.
+     */
+    private handleRateLimitRetry;
+    /**
+     * 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
+     */
+    private processFailoverError;
+    /**
+     * Queues the finalize UPDATE for a prompt-run record. Inside the queued task it sets, in order:
+     * the completion timing (`CompletedAt`, `ExecutionTimeMS`); the outcome (`Success`, and `Status` =
+     * `'Completed'` or `'Failed'` from it); then the subclass's result fields; then the token rollups and
+     * `TotalCost`.
+     *
+     * The outcome is a parameter, not left to the callback, so every runner's row leaves `'Running'`.
+     * It is written before the callback runs, so the row reaches its final status even if the callback
+     * throws (the error is logged under `PromptRunUpdate` and the rollups are skipped).
+     *
+     * For prompt-based runners, like {@link CreateRunRecord}.
+     *
+     * @param success Whether the call succeeded, as the runner judges it (the chat runner also requires
+     *   its output to pass validation).
+     * @param applyResultFields Sets the runner's own result columns. It can read the timing and outcome
+     *   already set, and may refine them (for example `ErrorDetails`). **It must be synchronous**: it runs
+     *   inside the queued save task, and anything it sets after an `await` can miss the UPDATE.
+     */
+    protected FinalizeRunRecord(promptRun: MJAIPromptRunEntityExtended, success: boolean, endTime: Date, executionTimeMS: number, applyResultFields: (promptRun: MJAIPromptRunEntityExtended) => void): Promise<void>;
+    /**
+     * 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.
+     */
+    protected getFailoverConfiguration(prompt: MJAIPromptEntityExtended): FailoverConfiguration;
+    /**
+     * 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.
+     */
+    protected shouldAttemptFailover(error: Error, config: FailoverConfiguration, attemptNumber: number): boolean;
+    /**
+     * 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
+     */
+    private errorMatchesScope;
+    /**
+     * 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.
+     */
+    protected calculateFailoverDelay(attemptNumber: number, baseDelaySeconds: number): number;
+    /**
+     * 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.
+     */
+    protected selectFailoverCandidates(currentModel: MJAIModelEntityExtended, currentVendorId: string | undefined, strategy: FailoverConfiguration['strategy'], modelStrategy: FailoverConfiguration['modelStrategy'], allCandidates: ModelVendorCandidate[], attemptHistory: FailoverAttempt[]): ModelVendorCandidate[];
+    /**
+     * 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.
+     */
+    protected logFailoverAttempt(promptId: string, attempt: FailoverAttempt, willRetry: boolean): void;
+}
+//# sourceMappingURL=BaseModelRunner.d.ts.map

package/dist/BaseModelRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseModelRunner.d.ts","sourceRoot":"","sources":["../src/BaseModelRunner.ts"],"names":[],"mappings":"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"}