@nestjs/ai 0.0.0-stage → 0.0.2

package/dist/runtime/agent-loop.js

@@ -0,0 +1,81 @@
+import { AiBudgetExceededError } from '../errors/ai.errors.js';
+import { addCost, addUsage, ZERO_USAGE } from '../utils/usage.util.js';
+import { runStep } from './model-policy.js';
+import { generateStep, streamStep, wantsAnotherStep } from './steps.js';
+/**
+ * The agent loop: a model call, then, while the model asks for tools (which run inside the call), another one with
+ * the conversation so far, up to `maxSteps`. Each model call runs under its resilience policies (retry, timeout,
+ * fallback); the budget is checked before each. `report` receives a usage event per model call that answered.
+ */
+export async function runLoop(plan, mode, report) {
+    const messages = [...plan.messages];
+    const responseMessages = [];
+    const steps = [];
+    let usage = ZERO_USAGE;
+    let cost;
+    let last;
+    for (let index = 0; index < plan.maxSteps; index++) {
+        assertWithinBudget(plan, usage, cost);
+        const conversation = [...messages];
+        const run = async (attempt) => {
+            const outcome = mode.stream
+                ? await streamStep(plan, index, conversation, attempt)
+                : await generateStep(plan, index, conversation, attempt, mode.output);
+            report(usageEvent(plan, attempt, outcome, mode.stream));
+            return outcome;
+        };
+        const { value, attempts } = await runStep(plan, run, mode.stream ? (chunk) => mode.emit(chunk) : undefined);
+        last = value;
+        steps.push({ ...value.step, attempts });
+        usage = addUsage(usage, value.step.usage);
+        cost = addCost(cost, value.step.cost);
+        messages.push(...value.responseMessages);
+        responseMessages.push(...value.responseMessages);
+        if (!wantsAnotherStep(value)) {
+            break;
+        }
+    }
+    const final = last;
+    return {
+        result: {
+            text: final.step.text,
+            finishReason: final.step.finishReason,
+            steps,
+            usage,
+            ...(cost !== undefined && { cost }),
+            toolCalls: steps.flatMap((step) => step.toolCalls),
+            toolResults: steps.flatMap((step) => step.toolResults),
+            responseMessages,
+            model: final.step.model,
+        },
+        ...('output' in final && { output: final.output }),
+        ...(final.finish && { finish: final.finish }),
+    };
+}
+/** The usage event of a model call that answered. */
+export function usageEvent(plan, attempt, outcome, stream) {
+    return {
+        ...(plan.label !== undefined && { label: plan.label }),
+        model: attempt.model.info,
+        step: outcome.step.index,
+        attempt: attempt.attempt,
+        fallback: attempt.fallback,
+        stream,
+        usage: outcome.step.usage,
+        ...(outcome.step.cost !== undefined && { cost: outcome.step.cost }),
+        durationMs: Math.round(outcome.durationMs),
+        finishReason: outcome.step.finishReason,
+    };
+}
+/** Throws when the call has spent its budget. */
+export function assertWithinBudget(plan, usage, cost) {
+    const budget = plan.budget;
+    if (!budget) {
+        return;
+    }
+    const overTokens = budget.maxTokens !== undefined && usage.totalTokens >= budget.maxTokens;
+    const overCost = budget.maxCost !== undefined && (cost ?? 0) >= budget.maxCost;
+    if (overTokens || overCost) {
+        throw new AiBudgetExceededError(usage, cost, budget);
+    }
+}

package/dist/runtime/call-plan.d.ts

@@ -0,0 +1,54 @@
+import type { ResiliencePolicy } from '@nestjs/resilience';
+import type { ModelMessage, ToolSet } from 'ai';
+import type { AiCallOptions, AiToolChoice } from '../interfaces/ai-call-options.interface.js';
+import type { AiBudget, AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+import type { AiCaller } from '../interfaces/ai-tool.interface.js';
+import type { AiUsageEvent } from '../interfaces/ai-usage.interface.js';
+import type { AiModels, ResolvedModel } from '../models/ai-models.service.js';
+import type { AiTools } from '../tools/ai-tools.service.js';
+import { type PolicyPlan, type StepAttempt } from './model-policy.js';
+/** The generation settings of one model call, as `generateText()` and `streamText()` take them. */
+export interface GenerationSettings {
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    seed?: number;
+    stopSequences?: string[];
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    providerOptions?: Record<string, Record<string, any>>;
+    headers?: Record<string, string | undefined>;
+}
+/** Everything a call needs, resolved once from its options, the models and the module's defaults. Internal. */
+export interface CallPlan extends PolicyPlan {
+    label?: string;
+    maxSteps: number;
+    budget?: AiBudget;
+    instructions?: string;
+    messages: ModelMessage[];
+    tools?: ToolSet;
+    toolChoice?: AiToolChoice;
+    caller: AiCaller;
+    listeners: Array<(event: AiUsageEvent) => void | Promise<void>>;
+    settingsFor(model: ResolvedModel): GenerationSettings;
+    /**
+     * The attempt whose tools may run, set by the step. A tool that starts means the model has answered: the attempt
+     * commits (no timeout, retry or fallback from then on), so that no tool runs twice.
+     */
+    running?: StepAttempt;
+}
+/**
+ * Resolves a call's options. Mistakes (an unknown model or agent function, both `prompt` and `messages`) throw here,
+ * before anything is sent. `signal` is the call's: the caller's, or one combined with it.
+ */
+export declare function createCallPlan(options: AiCallOptions, { models, tools, moduleOptions, signal, preset, toolExecution, }: {
+    models: AiModels;
+    tools: AiTools;
+    moduleOptions: AiModuleOptions;
+    signal: AbortSignal;
+    /** A preset of `ResilienceService`, by name. */
+    preset: (name: string) => ResiliencePolicy;
+    /** `false`: tool calls are returned, not run (durable runs). */
+    toolExecution?: boolean;
+}): CallPlan;

package/dist/runtime/call-plan.js

@@ -0,0 +1,105 @@
+import { AiConfigurationError } from '../errors/ai.errors.js';
+import { modelPolicy } from './model-policy.js';
+const DEFAULT_MAX_STEPS = 10;
+/**
+ * Resolves a call's options. Mistakes (an unknown model or agent function, both `prompt` and `messages`) throw here,
+ * before anything is sent. `signal` is the call's: the caller's, or one combined with it.
+ */
+export function createCallPlan(options, { models, tools, moduleOptions, signal, preset, toolExecution = true, }) {
+    if (typeof options !== 'object' || options === null) {
+        throw new AiConfigurationError('Pass the call its options: { prompt } or { messages }, and the rest.');
+    }
+    const defaults = moduleOptions.defaults ?? {};
+    const primary = models.resolve(options.model);
+    const chain = [primary, ...fallbacks(options.fallback, primary, models)].filter((model, index, all) => all.findIndex((other) => other.model === model.model) === index);
+    const caller = { ...options.caller };
+    const plan = {};
+    const onExecute = () => plan.running?.commit();
+    // A streamed answer carries the agent functions' progress, as transient data chunks `useChat()` hands to `onData`.
+    const onProgress = (progress) => plan.running?.emit({ type: 'data-tool-progress', id: progress.toolCallId, data: progress, transient: true });
+    const selected = options.tools?.length
+        ? tools.select(options.tools, { caller, onExecute, onProgress, execute: toolExecution })
+        : undefined;
+    const maxSteps = options.maxSteps ?? defaults.maxSteps ?? DEFAULT_MAX_STEPS;
+    if (!Number.isInteger(maxSteps) || maxSteps < 1) {
+        throw new AiConfigurationError(`\`maxSteps\` must be a whole number of at least 1. Got ${String(maxSteps)}.`);
+    }
+    const policies = new Map();
+    const pick = (model, key) => options[key] ?? model.settings[key] ?? defaults[key];
+    return Object.assign(plan, {
+        ...(options.label !== undefined && { label: options.label }),
+        chain,
+        signal,
+        maxSteps,
+        ...((options.budget ?? defaults.budget) && { budget: options.budget ?? defaults.budget }),
+        ...(options.instructions !== undefined && { instructions: options.instructions }),
+        messages: messagesOf(options),
+        ...(selected && { tools: selected }),
+        ...(options.toolChoice !== undefined && { toolChoice: options.toolChoice }),
+        caller,
+        listeners: [moduleOptions.onUsage, options.onUsage].filter((listener) => typeof listener === 'function'),
+        source: options.label ?? 'AiService',
+        fallbackIf: options.fallbackIf ?? (() => true),
+        policyFor: (model) => {
+            let policy = policies.get(model);
+            if (!policies.has(model)) {
+                const own = options.resilience ?? model.settings.resilience ?? defaults.resilience;
+                policy =
+                    own === undefined
+                        ? modelPolicy(model, {
+                            retry: options.retry ?? model.settings.retry ?? defaults.retry,
+                            timeout: options.timeout ?? model.settings.timeout ?? defaults.timeout,
+                        })
+                        : typeof own === 'string'
+                            ? preset(own)
+                            : own;
+                policies.set(model, policy);
+            }
+            return policy;
+        },
+        settingsFor: (model) => {
+            const settings = {};
+            for (const key of [
+                'maxOutputTokens',
+                'temperature',
+                'topP',
+                'topK',
+                'seed',
+                'stopSequences',
+                'presencePenalty',
+                'frequencyPenalty',
+                'providerOptions',
+                'headers',
+            ]) {
+                const value = pick(model, key);
+                if (value !== undefined) {
+                    settings[key] = value;
+                }
+            }
+            return settings;
+        },
+    });
+}
+function fallbacks(option, primary, models) {
+    if (option === false) {
+        return [];
+    }
+    if (option === undefined) {
+        return primary.fallback.map((name) => models.resolve(name));
+    }
+    const references = Array.isArray(option) ? [...option] : [option];
+    return references.map((reference) => models.resolve(reference));
+}
+function messagesOf(options) {
+    const { prompt, messages } = options;
+    if (prompt !== undefined && messages !== undefined) {
+        throw new AiConfigurationError('Pass `prompt` or `messages`, not both.');
+    }
+    if (typeof prompt === 'string') {
+        return [{ role: 'user', content: prompt }];
+    }
+    if (Array.isArray(messages) && messages.length > 0) {
+        return [...messages];
+    }
+    throw new AiConfigurationError('Pass `prompt` (a string) or `messages` (a non-empty array of model messages).');
+}

package/dist/runtime/embedding-call.d.ts

@@ -0,0 +1,38 @@
+import type { ResiliencePolicy } from '@nestjs/resilience';
+import { type EmbedManyResult, type EmbedResult } from 'ai';
+import type { AiEmbeddingCallOptions, AiEmbeddingSettings, AiEmbeddingUsageEvent } from '../interfaces/ai-embedding.interface.js';
+import type { AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+import type { AiEmbeddingModels, ResolvedEmbeddingModel } from '../models/ai-embedding-models.service.js';
+import { type PolicyPlan } from './model-policy.js';
+/** One operation's state. Clients and explicitly supplied resilience policies remain shared. */
+export interface EmbeddingPlan extends PolicyPlan<ResolvedEmbeddingModel> {
+    model: ResolvedEmbeddingModel;
+    label?: string;
+    settings: Pick<AiEmbeddingSettings, 'headers' | 'providerOptions'> & {
+        maxParallelCalls: number;
+    };
+    listeners: Array<(event: AiEmbeddingUsageEvent) => void | Promise<void>>;
+}
+/**
+ * Resolves only embedding settings: language generation defaults never reach an embedding provider.
+ */
+export declare function createEmbeddingPlan(options: AiEmbeddingCallOptions, models: AiEmbeddingModels, moduleOptions: AiModuleOptions, preset: (name: string) => ResiliencePolicy): EmbeddingPlan;
+interface EmbeddingExecution<R> {
+    result: R;
+    event: AiEmbeddingUsageEvent;
+    attempts: number;
+    cost?: number;
+}
+/**
+ * The SDK splits `values` into provider requests. The policy runs around each of them, through the
+ * SDK's middleware, so a timeout or a retry covers one request and never repeats the others. When a
+ * request fails for good, its siblings are aborted, so that a failed operation does not keep
+ * consuming provider capacity.
+ */
+export declare function runEmbedding(plan: EmbeddingPlan, input: {
+    value: string;
+}): Promise<EmbeddingExecution<EmbedResult>>;
+export declare function runEmbedding(plan: EmbeddingPlan, input: {
+    values: string[];
+}): Promise<EmbeddingExecution<EmbedManyResult>>;
+export {};

package/dist/runtime/embedding-call.js

@@ -0,0 +1,120 @@
+import { embed, embedMany, gateway, wrapEmbeddingModel, } from 'ai';
+import { AiConfigurationError } from '../errors/ai.errors.js';
+import { modelPolicy, runStep } from './model-policy.js';
+const NEVER_ABORTED = new AbortController().signal;
+const DEFAULT_MAX_PARALLEL_CALLS = 4;
+/**
+ * Resolves only embedding settings: language generation defaults never reach an embedding provider.
+ */
+export function createEmbeddingPlan(options, models, moduleOptions, preset) {
+    if (typeof options !== 'object' || options === null) {
+        throw new AiConfigurationError('Pass the embedding call its options: { value } or { values }, and the rest.');
+    }
+    const model = models.resolve(options.model);
+    const defaults = moduleOptions.embeddingDefaults ?? {};
+    const pick = (key) => options[key] ?? model.settings[key] ?? defaults[key];
+    const maxParallelCalls = pick('maxParallelCalls') ?? DEFAULT_MAX_PARALLEL_CALLS;
+    if (!Number.isSafeInteger(maxParallelCalls) || maxParallelCalls < 1) {
+        throw new AiConfigurationError('`maxParallelCalls` must be a finite positive whole number.');
+    }
+    const own = pick('resilience');
+    const policy = own === undefined
+        ? modelPolicy(model, { retry: pick('retry'), timeout: pick('timeout') }, 'ai:embedding')
+        : typeof own === 'string'
+            ? preset(own)
+            : own;
+    return {
+        model,
+        chain: [model],
+        signal: options.abortSignal ?? NEVER_ABORTED,
+        source: options.label ?? 'AiService',
+        fallbackIf: () => false,
+        policyFor: () => policy,
+        ...(options.label !== undefined && { label: options.label }),
+        settings: {
+            maxParallelCalls,
+            ...(pick('headers') !== undefined && { headers: pick('headers') }),
+            ...(pick('providerOptions') !== undefined && { providerOptions: pick('providerOptions') }),
+        },
+        listeners: [moduleOptions.onEmbeddingUsage, options.onEmbeddingUsage].filter((listener) => typeof listener === 'function'),
+    };
+}
+export async function runEmbedding(plan, input) {
+    const started = performance.now();
+    const many = 'values' in input;
+    if (many
+        ? !Array.isArray(input.values) || [...input.values].some((value) => typeof value !== 'string')
+        : typeof input.value !== 'string') {
+        throw new AiConfigurationError(many ? '`values` must be an array of strings.' : '`value` must be a string.');
+    }
+    const values = many ? [...input.values] : undefined;
+    const controller = new AbortController();
+    const signal = AbortSignal.any([plan.signal, controller.signal]);
+    let attempts = 0;
+    const wrapped = wrapEmbeddingModel({
+        model: modelObject(plan.model.model),
+        middleware: {
+            wrapEmbed: async ({ params, model }) => {
+                const { value, attempts: used } = await runStep({ ...plan, signal }, async (attempt) => {
+                    attempt.signal.throwIfAborted();
+                    return model.doEmbed({ ...params, abortSignal: attempt.signal });
+                });
+                attempts += used;
+                return value;
+            },
+        },
+    });
+    let result;
+    try {
+        signal.throwIfAborted();
+        const settings = {
+            model: wrapped,
+            headers: plan.settings.headers,
+            providerOptions: plan.settings.providerOptions,
+            abortSignal: signal,
+            maxRetries: 0,
+        };
+        result =
+            values !== undefined
+                ? await embedMany({
+                    ...settings,
+                    values,
+                    maxParallelCalls: plan.settings.maxParallelCalls,
+                })
+                : await embed({ ...settings, value: input.value });
+        signal.throwIfAborted();
+    }
+    finally {
+        controller.abort();
+    }
+    const pricing = plan.model.pricing;
+    const cost = pricing && Number.isFinite(result.usage.tokens)
+        ? (result.usage.tokens * pricing.input) / 1_000_000
+        : undefined;
+    return {
+        result,
+        attempts,
+        ...(cost !== undefined && { cost }),
+        event: {
+            operation: many ? 'embedMany' : 'embed',
+            ...(plan.label !== undefined && { label: plan.label }),
+            model: plan.model.info,
+            inputCount: values?.length ?? 1,
+            usage: { tokens: result.usage.tokens },
+            attempts,
+            durationMs: Math.round(performance.now() - started),
+            ...(cost !== undefined && { cost }),
+        },
+    };
+}
+/**
+ * `wrapEmbeddingModel()` takes model objects. An id resolves as the SDK resolves it: with its
+ * default provider, the gateway unless the application set another.
+ */
+function modelObject(model) {
+    if (typeof model !== 'string') {
+        return model;
+    }
+    const provider = (globalThis.AI_SDK_DEFAULT_PROVIDER ?? gateway);
+    return provider.embeddingModel(model);
+}

package/dist/runtime/model-policy.d.ts

@@ -0,0 +1,53 @@
+import { ResiliencePolicy, type RetryOptions } from '@nestjs/resilience';
+import type { ResolvedModel } from '../models/ai-models.service.js';
+import type { AiModelInfo } from '../interfaces/ai-result.interface.js';
+/** The identity the policy layer needs; generation and embedding registries stay separately typed. */
+export interface PolicyModel {
+    info: AiModelInfo;
+}
+/** What one attempt of a model call receives. */
+export interface StepAttempt<M extends PolicyModel = ResolvedModel> {
+    model: M;
+    /** 1-based, per model. */
+    attempt: number;
+    fallback: boolean;
+    /** Aborted by the caller, or by the attempt's timeout (reason: `ResilienceTimeoutError`). */
+    signal: AbortSignal;
+    /** Commits the attempt: no timeout, retry or fallback from now on. A step whose tools start calls it. */
+    commit(): void;
+    /** Sends a stream chunk to the consumer, which commits the attempt too. */
+    emit(chunk: unknown): void;
+}
+/** How a call's models are retried, timed out and replaced. Internal. */
+export interface PolicyPlan<M extends PolicyModel = ResolvedModel> {
+    chain: M[];
+    /** The caller's signal. */
+    signal: AbortSignal;
+    /** Labels the policies' events (`source`). */
+    source: string;
+    /** The model's own policy: an application's, or the one built from its `retry` and `timeout`. */
+    policyFor(model: M): ResiliencePolicy | undefined;
+    fallbackIf: (error: unknown) => boolean;
+}
+/**
+ * Runs one model call (a step) under the call's policies: the model's own (retry, timeout, or the application's),
+ * then each fallback model's, through `executeObservable()`, so that the outcome is committed once a chunk reaches
+ * the consumer or the step's tools start. Chunks go to `emit` as they come. When the call fails: `AiModelError` with
+ * every attempt, the caller's abort reason, or what is not a model failure (an `AiOutputError`, a circuit breaker's
+ * rejection) as it is.
+ */
+export declare function runStep<T, M extends PolicyModel = ResolvedModel>(plan: PolicyPlan<M>, run: (attempt: StepAttempt<M>) => Promise<T>, emit?: (chunk: unknown) => void): Promise<{
+    value: T;
+    attempt: StepAttempt<M>;
+    attempts: number;
+}>;
+/**
+ * The model's own policy from its settings: `RetryPolicy` (honoring the provider's `retry-after`) around
+ * `TimeoutPolicy`, either one left out when it is `false`.
+ */
+export declare function modelPolicy(model: PolicyModel, { retry, timeout }: {
+    retry: RetryOptions | false | undefined;
+    timeout: number | string | false | undefined;
+}, namespace?: string): ResiliencePolicy | undefined;
+/** What is retried by default: what the provider marks retryable (with network failures), and timeouts. */
+export declare function isRetryable(error: unknown): boolean;

package/dist/runtime/model-policy.js

@@ -0,0 +1,202 @@
+import { FallbackPolicy, ResilienceContext, ResilienceError, ResiliencePolicy, ResilienceTimeoutError, RetryPolicy, TimeoutPolicy, } from '@nestjs/resilience';
+import { Logger } from '@nestjs/common';
+import { APICallError, RetryError } from 'ai';
+import { Observable } from 'rxjs';
+import { AiBudgetExceededError, AiConfigurationError, AiModelError, AiOutputError, } from '../errors/ai.errors.js';
+import { toMilliseconds } from '../utils/duration.util.js';
+const logger = new Logger('AiModule');
+/** `ai`'s argument errors, which no retry or other model fixes. */
+const CALLER_MISTAKES = new Set(['AI_InvalidPromptError', 'AI_InvalidArgumentError', 'AI_InvalidMessageRoleError', 'AI_MessageConversionError']);
+/**
+ * Runs one model call (a step) under the call's policies: the model's own (retry, timeout, or the application's),
+ * then each fallback model's, through `executeObservable()`, so that the outcome is committed once a chunk reaches
+ * the consumer or the step's tools start. Chunks go to `emit` as they come. When the call fails: `AiModelError` with
+ * every attempt, the caller's abort reason, or what is not a model failure (an `AiOutputError`, a circuit breaker's
+ * rejection) as it is.
+ */
+export function runStep(plan, run, emit) {
+    const failures = [];
+    let attempts = 0;
+    const attemptsOf = (index) => (context) => new Observable((subscriber) => {
+        attempts++;
+        const model = plan.chain[index];
+        let settled = false;
+        let committed = false;
+        const record = (error) => {
+            if (!settled) {
+                settled = true;
+                // An attempt aborted for its timeout failed for the timeout, whatever the request threw.
+                const reason = context.signal.aborted ? context.signal.reason : undefined;
+                failures.push({ model: model.info, attempt: context.attempt, error: reason instanceof ResilienceTimeoutError ? reason : unwrap(error) });
+            }
+        };
+        const attempt = {
+            model,
+            attempt: context.attempt,
+            fallback: index > 0,
+            signal: context.signal,
+            commit: () => {
+                if (!committed && !subscriber.closed) {
+                    committed = true;
+                    subscriber.next({ type: 'commit' });
+                }
+            },
+            emit: (chunk) => {
+                committed = true;
+                subscriber.next({ type: 'chunk', chunk });
+            },
+        };
+        run(attempt).then((value) => {
+            settled = true;
+            subscriber.next({ type: 'outcome', value, attempt });
+            subscriber.complete();
+        }, (error) => {
+            record(error);
+            subscriber.error(unwrap(error));
+        });
+        // Unsubscribed before it settled: its timeout ran out, or the caller went away.
+        return () => record(context.signal.reason);
+    });
+    const policyAt = (index) => {
+        const model = plan.chain[index];
+        const own = plan.policyFor(model);
+        const policies = [];
+        if (index < plan.chain.length - 1) {
+            policies.push(new FallbackPolicy((error, context) => {
+                // A fallback that works must not hide why the model failed: a revoked key, a refused request.
+                logger.warn(`The model "${labelOf(model)}" failed (${describeError(error)}); falling back to "${labelOf(plan.chain[index + 1])}".`);
+                return policyAt(index + 1).executeObservable(attemptsOf(index + 1), { signal: context.signal, source: plan.source });
+            }, { name: `${nameOf(model)} fallback`, handleIf: (error) => isFallbackable(error) && plan.fallbackIf(error) }));
+        }
+        if (own) {
+            policies.push(own);
+        }
+        return ResiliencePolicy.wrap(...policies);
+    };
+    // Inside a resilient entrypoint (or `ResilienceContext.run()`), its attempt's signal stops the call too.
+    const ambient = new ResilienceContext().signal;
+    const signal = ambient ? AbortSignal.any([plan.signal, ambient]) : plan.signal;
+    return new Promise((resolve, reject) => {
+        let outcome;
+        policyAt(0)
+            .executeObservable(attemptsOf(0), { signal, source: plan.source })
+            .subscribe({
+            next: (event) => {
+                if (event.type === 'chunk') {
+                    emit?.(event.chunk);
+                }
+                else if (event.type === 'outcome') {
+                    outcome = { value: event.value, attempt: event.attempt };
+                }
+            },
+            error: (error) => reject(finalError(error, failures, signal)),
+            complete: () => (outcome ? resolve({ ...outcome, attempts }) : reject(finalError(new Error('The model call ended without an answer'), failures, signal))),
+        });
+    });
+}
+/**
+ * The model's own policy from its settings: `RetryPolicy` (honoring the provider's `retry-after`) around
+ * `TimeoutPolicy`, either one left out when it is `false`.
+ */
+export function modelPolicy(model, { retry, timeout }, namespace = 'ai') {
+    const policies = [];
+    if (retry !== false) {
+        policies.push(retryPolicy(model, retry ?? {}, namespace));
+    }
+    if (timeout !== false) {
+        policies.push(new TimeoutPolicy({ timeout: toMilliseconds(timeout ?? DEFAULT_TIMEOUT, 'timeout'), name: `${nameOf(model, namespace)} timeout` }));
+    }
+    return policies.length > 0 ? ResiliencePolicy.wrap(...policies) : undefined;
+}
+const DEFAULT_TIMEOUT = '60s';
+const DEFAULT_BACKOFF = { delay: 1_000, factor: 2, maxDelay: 30_000 };
+function retryPolicy(model, retry, namespace) {
+    const backoff = retry.backoff;
+    const maxDelay = typeof backoff === 'object' && backoff.maxDelay !== undefined ? toMilliseconds(backoff.maxDelay, 'retry.backoff.maxDelay') : DEFAULT_BACKOFF.maxDelay;
+    const retryIf = retry.retryIf ?? isRetryable;
+    return new RetryPolicy({
+        name: `${nameOf(model, namespace)} retry`,
+        attempts: retry.attempts ?? 3,
+        ...(retry.retryOnResult && { retryOnResult: retry.retryOnResult }),
+        // A provider that asks for a longer wait than the backoff allows: on to the fallback.
+        retryIf: (error, attempt) => !(error instanceof AiOutputError) && (retryAfter(error) ?? 0) <= maxDelay && retryIf(error, attempt),
+        backoff: typeof backoff === 'function'
+            ? backoff
+            : (attempt, error) => retryAfter(error) ?? exponential(attempt, { ...DEFAULT_BACKOFF, ...backoff }),
+    });
+}
+/** What is retried by default: what the provider marks retryable (with network failures), and timeouts. */
+export function isRetryable(error) {
+    if (error instanceof ResilienceTimeoutError) {
+        return true;
+    }
+    return APICallError.isInstance(error) && error.isRetryable;
+}
+function isFallbackable(error) {
+    return !(error instanceof AiOutputError) && !(error instanceof Error && CALLER_MISTAKES.has(error.name));
+}
+function finalError(error, failures, signal) {
+    if (signal.aborted) {
+        return signal.reason;
+    }
+    if (error instanceof AiOutputError || error instanceof AiBudgetExceededError || error instanceof AiConfigurationError) {
+        return error;
+    }
+    // A circuit breaker's, bulkhead's or rate limit's rejection: the application's policy said no.
+    if (error instanceof ResilienceError && !(error instanceof ResilienceTimeoutError)) {
+        return error;
+    }
+    return new AiModelError(failures.length > 0 ? failures : [{ model: { provider: 'unknown', modelId: 'unknown' }, attempt: 1, error }]);
+}
+/** `ai` wraps errors it retried itself; with `maxRetries: 0` it should not, but the last one is what failed. */
+function unwrap(error) {
+    return RetryError.isInstance(error) ? (error.lastError ?? error) : error;
+}
+function exponential(attempt, { delay, factor = 2, maxDelay, jitter = 'full' }) {
+    const max = toMilliseconds(maxDelay ?? DEFAULT_BACKOFF.maxDelay, 'retry.backoff.maxDelay');
+    const computed = Math.min(max, toMilliseconds(delay ?? DEFAULT_BACKOFF.delay, 'retry.backoff.delay') * Math.max(1, factor) ** (attempt - 1));
+    switch (jitter) {
+        case 'none':
+            return computed;
+        case 'equal':
+            return computed / 2 + Math.random() * (computed / 2);
+        default:
+            return Math.random() * computed;
+    }
+}
+/** The provider's `retry-after-ms` or `retry-after`, in milliseconds. */
+function retryAfter(error) {
+    if (!APICallError.isInstance(error) || !error.responseHeaders) {
+        return undefined;
+    }
+    const headers = Object.fromEntries(Object.entries(error.responseHeaders).map(([name, value]) => [name.toLowerCase(), value]));
+    const ms = Number.parseFloat(headers['retry-after-ms'] ?? '');
+    if (Number.isFinite(ms) && ms >= 0) {
+        return ms;
+    }
+    const value = headers['retry-after'];
+    if (value === undefined) {
+        return undefined;
+    }
+    const seconds = Number.parseFloat(value);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1_000;
+    }
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+function nameOf(model, namespace = 'ai') {
+    return `${namespace}:${labelOf(model)}`;
+}
+function labelOf(model) {
+    return model.info.name ?? `${model.info.provider}:${model.info.modelId}`;
+}
+/** The error's class, its HTTP status if it has one, and its message: `APICallError, 401: Invalid API key`. */
+function describeError(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const { statusCode, status } = error;
+    const code = typeof statusCode === 'number' ? statusCode : typeof status === 'number' ? status : undefined;
+    return `${error.constructor.name}${code !== undefined ? `, ${code}` : ''}: ${error.message}`;
+}