@nestjs/ai 0.0.0-stage → 0.0.2

package/dist/errors/ai.errors.d.ts

@@ -0,0 +1,54 @@
+import type { AiModelInfo } from '../interfaces/ai-result.interface.js';
+import type { AiUsage } from '../interfaces/ai-usage.interface.js';
+/** The base class of the package's errors. */
+export declare class AiError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A model name, an agent function or an option the package cannot use. Thrown at startup or when the call is made.
+ */
+export declare class AiConfigurationError extends AiError {
+}
+/** One failed attempt of a model call. */
+export interface AiAttemptFailure {
+    model: AiModelInfo;
+    attempt: number;
+    error: unknown;
+}
+/** Every attempt of a model call failed, on every model tried. `cause` is the last error. */
+export declare class AiModelError extends AiError {
+    readonly attempts: AiAttemptFailure[];
+    constructor(attempts: AiAttemptFailure[]);
+}
+/** The call would have started a model call over its `budget`. */
+export declare class AiBudgetExceededError extends AiError {
+    readonly usage: AiUsage;
+    readonly cost: number | undefined;
+    readonly limit: {
+        maxTokens?: number;
+        maxCost?: number;
+    };
+    constructor(usage: AiUsage, cost: number | undefined, limit: {
+        maxTokens?: number;
+        maxCost?: number;
+    });
+}
+/** The model's answer to `generateObject()` is not JSON, or does not match the schema. */
+export declare class AiOutputError extends AiError {
+    /** What the model answered. */
+    readonly text: string;
+    constructor(message: string, 
+    /** What the model answered. */
+    text: string, options?: ErrorOptions);
+}
+/**
+ * What the model is told about a tool call that failed: a guard's refusal (`Forbidden resource`), an
+ * `HttpException`'s message, `Internal server error` for anything else. `toolName` is the agent function's name.
+ */
+export declare class AiToolError extends AiError {
+    readonly toolName: string;
+    constructor(message: string, toolName: string, options?: ErrorOptions);
+    /** The model reads `String(error)`: the message alone, not the class name. */
+    toString(): string;
+}
+export declare function describeModel(model: AiModelInfo): string;

package/dist/errors/ai.errors.js

@@ -0,0 +1,62 @@
+/** The base class of the package's errors. */
+export class AiError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/**
+ * A model name, an agent function or an option the package cannot use. Thrown at startup or when the call is made.
+ */
+export class AiConfigurationError extends AiError {
+}
+/** Every attempt of a model call failed, on every model tried. `cause` is the last error. */
+export class AiModelError extends AiError {
+    constructor(attempts) {
+        const last = attempts[attempts.length - 1];
+        const tried = [...new Set(attempts.map((attempt) => describeModel(attempt.model)))].join(', ');
+        super(`The model call failed after ${attempts.length} attempt(s) (${tried}): ${messageOf(last?.error)}`, {
+            cause: last?.error,
+        });
+        this.attempts = attempts;
+    }
+}
+/** The call would have started a model call over its `budget`. */
+export class AiBudgetExceededError extends AiError {
+    constructor(usage, cost, limit) {
+        const spent = limit.maxCost !== undefined && cost !== undefined ? `cost ${cost}` : `${usage.totalTokens} tokens`;
+        super(`The call's budget is spent (${spent}), so it stopped before the next model call`);
+        this.usage = usage;
+        this.cost = cost;
+        this.limit = limit;
+    }
+}
+/** The model's answer to `generateObject()` is not JSON, or does not match the schema. */
+export class AiOutputError extends AiError {
+    constructor(message, 
+    /** What the model answered. */
+    text, options) {
+        super(message, options);
+        this.text = text;
+    }
+}
+/**
+ * What the model is told about a tool call that failed: a guard's refusal (`Forbidden resource`), an
+ * `HttpException`'s message, `Internal server error` for anything else. `toolName` is the agent function's name.
+ */
+export class AiToolError extends AiError {
+    constructor(message, toolName, options) {
+        super(message, options);
+        this.toolName = toolName;
+    }
+    /** The model reads `String(error)`: the message alone, not the class name. */
+    toString() {
+        return this.message;
+    }
+}
+export function describeModel(model) {
+    return model.name ?? `${model.provider}:${model.modelId}`;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/errors/index.d.ts

@@ -0,0 +1 @@
+export * from './ai.errors.js';

package/dist/errors/index.js

@@ -0,0 +1 @@
+export * from './ai.errors.js';

package/dist/http/keep-alive.util.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `body` with a keep-alive comment written whenever it has been quiet for `intervalMs`: while a tool runs, or the
+ * model thinks, so that proxies and load balancers do not close the connection as idle. Comments go between the
+ * body's chunks, each a whole server-sent event.
+ */
+export declare function withKeepAlive(body: ReadableStream<Uint8Array>, intervalMs: number): ReadableStream<Uint8Array>;

package/dist/http/keep-alive.util.js

@@ -0,0 +1,38 @@
+/** An SSE comment line: clients skip it, and proxies see the connection is alive. */
+const KEEP_ALIVE = new TextEncoder().encode(': keep-alive\n\n');
+/**
+ * `body` with a keep-alive comment written whenever it has been quiet for `intervalMs`: while a tool runs, or the
+ * model thinks, so that proxies and load balancers do not close the connection as idle. Comments go between the
+ * body's chunks, each a whole server-sent event.
+ */
+export function withKeepAlive(body, intervalMs) {
+    const reader = body.getReader();
+    let pending;
+    return new ReadableStream({
+        pull: async (controller) => {
+            pending ??= reader.read();
+            let timer;
+            const quiet = new Promise((resolve) => {
+                timer = setTimeout(() => resolve('quiet'), intervalMs);
+            });
+            try {
+                const next = await Promise.race([pending, quiet]);
+                if (next === 'quiet') {
+                    controller.enqueue(KEEP_ALIVE);
+                    return;
+                }
+                pending = undefined;
+                if (next.done) {
+                    controller.close();
+                }
+                else {
+                    controller.enqueue(next.value);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+}

package/dist/http/node-response.util.d.ts

@@ -0,0 +1,14 @@
+import type { ServerResponse } from 'node:http';
+/**
+ * The Node response behind the platform's: Express's and the Node adapter's are Node responses; a Fastify reply is
+ * hijacked when the body starts (`open()`), with the headers set on it so far (CORS) copied to its raw response.
+ */
+export declare function toNodeResponse(response: unknown): {
+    res: ServerResponse;
+    open(): void;
+};
+/**
+ * Writes `response` to the Node response: status and headers, then the body as it streams, respecting backpressure.
+ * A client that goes away cancels the body (which aborts the call that produces it).
+ */
+export declare function writeWebResponse(response: Response, res: ServerResponse): Promise<void>;

package/dist/http/node-response.util.js

@@ -0,0 +1,104 @@
+import { AiConfigurationError } from '../errors/ai.errors.js';
+function isFastifyReply(value) {
+    const reply = value;
+    return typeof reply?.hijack === 'function' && typeof reply.raw?.writeHead === 'function';
+}
+function isServerResponse(value) {
+    const response = value;
+    return typeof response?.writeHead === 'function' && typeof response.on === 'function';
+}
+/**
+ * The Node response behind the platform's: Express's and the Node adapter's are Node responses; a Fastify reply is
+ * hijacked when the body starts (`open()`), with the headers set on it so far (CORS) copied to its raw response.
+ */
+export function toNodeResponse(response) {
+    if (isFastifyReply(response)) {
+        return {
+            res: response.raw,
+            open: () => {
+                const headers = response.getHeaders();
+                response.hijack();
+                for (const [name, value] of Object.entries(headers)) {
+                    if (value !== undefined && !response.raw.hasHeader(name)) {
+                        response.raw.setHeader(name, value);
+                    }
+                }
+            },
+        };
+    }
+    if (isServerResponse(response)) {
+        return { res: response, open: () => { } };
+    }
+    throw new AiConfigurationError('Pass the response that @Res() injects (Express, Fastify or the Node adapter) to pipeUIMessageStreamToResponse() ' +
+        'and pipeTextStreamToResponse().');
+}
+/**
+ * Writes `response` to the Node response: status and headers, then the body as it streams, respecting backpressure.
+ * A client that goes away cancels the body (which aborts the call that produces it).
+ */
+export async function writeWebResponse(response, res) {
+    if (res.headersSent || res.destroyed) {
+        await response.body?.cancel().catch(() => { });
+        return;
+    }
+    const headers = {};
+    response.headers.forEach((value, name) => {
+        if (name !== 'set-cookie') {
+            headers[name] = value;
+        }
+    });
+    const cookies = response.headers.getSetCookie();
+    if (cookies.length > 0) {
+        headers['set-cookie'] = cookies;
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        res.setHeader(name, value);
+    }
+    res.writeHead(response.status);
+    if (!response.body) {
+        res.end();
+        return;
+    }
+    // The client should see the stream open now, not with its first event.
+    res.flushHeaders();
+    const reader = response.body.getReader();
+    let gone = false;
+    let release;
+    const onClose = () => {
+        if (!res.writableFinished) {
+            gone = true;
+            release?.();
+            reader.cancel().catch(() => { });
+        }
+    };
+    res.once('close', onClose);
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done || gone) {
+                break;
+            }
+            if (!res.write(next.value)) {
+                await new Promise((resolve) => {
+                    release = resolve;
+                    res.once('drain', resolve);
+                });
+                release = undefined;
+            }
+        }
+        if (gone) {
+            // The client went away: the socket may be half-open still, and nothing more will be written to it.
+            res.destroy();
+        }
+        else {
+            res.end();
+        }
+    }
+    catch {
+        // The body failed (a text stream whose call failed): the response ends early, as the client will see.
+        res.destroy();
+    }
+    finally {
+        res.off('close', onClose);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { AiModule } from './ai.module.js';
+export { AI_MODULE_OPTIONS, type AiModuleAsyncOptions, type AiModuleRootOptions, type AiOptionsFactory, } from './ai.module-definition.js';
+export { DEFAULT_MODEL_NAME, getEmbeddingModelToken, getModelToken } from './ai.constants.js';
+export type { AiBudget, AiCallDefaults, AiCallSettings, AiModelDefinition, AiModelPricing, AiModuleOptions, AiModuleStructure, AiResilienceSettings, } from './interfaces/index.js';
+export { AiModels } from './models/ai-models.service.js';
+export { AiEmbeddingModels } from './models/ai-embedding-models.service.js';
+export { AiService } from './services/ai.service.js';
+export { AiTextStream, type AiStreamResponseOptions, type AiUIMessageStreamOptions, } from './runtime/text-stream.js';
+export type { AiCallOptions, AiEmbeddingCallOptions, AiEmbeddingModelDefinition, AiEmbeddingModelPricing, AiEmbeddingModelReference, AiEmbeddingSettings, AiEmbeddingUsageEvent, AiEmbedManyOptions, AiEmbedManyResult, AiEmbedOptions, AiEmbedResult, AiModelInfo, AiModelReference, AiObjectCallOptions, AiObjectResult, AiSchema, AiStep, AiTextResult, AiToolCall, AiToolChoice, AiToolResult, AiUsage, AiUsageEvent, InferSchemaOutput, } from './interfaces/index.js';
+export * from './decorators/index.js';
+export { AiExecutionContext, type AiContextType } from './context/ai-execution-context.js';
+export { AiTools, type AiToolEntry } from './tools/ai-tools.service.js';
+export type { AgentFunctionContext, AgentFunctionOptions, AiCaller, AiToolSelection } from './interfaces/index.js';
+export * from './errors/index.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+// Module and options
+export { AiModule } from './ai.module.js';
+export { AI_MODULE_OPTIONS, } from './ai.module-definition.js';
+export { DEFAULT_MODEL_NAME, getEmbeddingModelToken, getModelToken } from './ai.constants.js';
+// Models and model calls
+export { AiModels } from './models/ai-models.service.js';
+export { AiEmbeddingModels } from './models/ai-embedding-models.service.js';
+export { AiService } from './services/ai.service.js';
+export { AiTextStream, } from './runtime/text-stream.js';
+// Models by injection (`@InjectModel()`); agent functions (`@AgentFunction()`), which the model is offered as tools:
+// what the methods receive, the execution context of their calls, and the registry
+export * from './decorators/index.js';
+export { AiExecutionContext } from './context/ai-execution-context.js';
+export { AiTools } from './tools/ai-tools.service.js';
+// Errors
+export * from './errors/index.js';

package/dist/interfaces/agent-function.interface.d.ts

@@ -0,0 +1,53 @@
+import type { ModelMessage } from 'ai';
+import type { AiSchema } from './ai-schema.interface.js';
+/** The options of `@AgentFunction()`. */
+export interface AgentFunctionOptions {
+    /**
+     * The name calls list it by in `tools`, and the model calls it by: 1 to 64 characters out of `A-Z a-z 0-9 _ -`, which
+     * is what model providers accept as a tool name. Default: the method's name.
+     */
+    name?: string;
+    /** What it does: the model picks the functions it calls by their names and descriptions. */
+    description?: string;
+    /**
+     * Its arguments: an object schema, whose JSON Schema the model is sent, and which validates every call before the
+     * method runs. Default: no arguments.
+     */
+    inputSchema?: AiSchema;
+    /** The scopes the caller must hold (`caller.scopes`): a call without them is refused before any guard runs. */
+    scopes?: readonly string[];
+}
+/**
+ * The second argument of an agent function, and `AiExecutionContext.getContext()` in its guards, interceptors and
+ * exception filters: who the call acts for (the call's `caller`), and the model's tool call.
+ */
+export interface AgentFunctionContext<TRequest = any, TUser = any> {
+    /** The agent function's name. */
+    readonly name: string;
+    /**
+     * The HTTP platform's request the agent runs in (`caller.request`): Express's, Fastify's or the Node adapter's, with
+     * its headers and the `user` your authentication set on it. `undefined` where there is none, as in a queue job.
+     */
+    readonly request?: TRequest;
+    /** Who the call acts for where there is no request (`caller.user`), as in a queue job or a durable run. */
+    readonly user?: TUser;
+    /** The scopes the caller holds (`caller.scopes`), which the function's own `scopes` require. */
+    readonly scopes?: readonly string[];
+    /** Aborted when the call is: pass it on to `fetch()` and your database. */
+    readonly signal: AbortSignal;
+    /**
+     * In a streamed answer, sends the browser the call's progress, as a transient `data-tool-progress` chunk; elsewhere,
+     * does nothing.
+     */
+    reportProgress(progress: number, total?: number, message?: string): Promise<void>;
+    /** The model's id for this tool call, to tie the function's logs to the agent's conversation. */
+    readonly toolCallId: string;
+    /**
+     * In a durable run (`@nestjs/ai/workflows`): the same for every attempt of this call, including the one a process
+     * that died mid-call makes again. Pass it on to what the function changes (a payment provider's idempotency key), so
+     * the change happens once. `undefined` outside durable runs.
+     */
+    readonly idempotencyKey?: string;
+    /** The messages the model had read when it called the function, without the system prompt. */
+    readonly messages: readonly ModelMessage[];
+}

package/dist/interfaces/agent-function.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/ai-call-options.interface.d.ts

@@ -0,0 +1,65 @@
+import type { LanguageModel, ModelMessage } from 'ai';
+import type { AiBudget, AiCallSettings } from './ai-module-options.interface.js';
+import type { AiSchema } from './ai-schema.interface.js';
+import type { AiCaller, AiToolSelection } from './ai-tool.interface.js';
+import type { AiUsageEvent } from './ai-usage.interface.js';
+export type AiToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'tool';
+    toolName: string;
+};
+/** A model: its name in `forRoot({ models })`, or a `LanguageModel`. */
+export type AiModelReference = string | Exclude<LanguageModel, string>;
+/** The options of `generateText()` and `streamText()`. */
+export interface AiCallOptions extends AiCallSettings {
+    /** Default `'default'`. */
+    model?: AiModelReference;
+    /** The system prompt. */
+    instructions?: string;
+    /** The user's message; or `messages`, a whole conversation. */
+    prompt?: string;
+    messages?: ModelMessage[];
+    /**
+     * The agent functions (`@AgentFunction()` methods) the model may call, by name or by provider class (all its agent
+     * functions). The model is offered each as a tool, and only those listed here.
+     */
+    tools?: AiToolSelection;
+    /** Who the call acts for: what agent functions and their guards see. */
+    caller?: AiCaller;
+    toolChoice?: AiToolChoice;
+    /** Model calls this call may make while the model asks for tools. Default 10. */
+    maxSteps?: number;
+    /**
+     * Models tried in order when the model fails after its retries; `false` for none. Default: the model's own
+     * `fallback`.
+     */
+    fallback?: AiModelReference | ReadonlyArray<AiModelReference> | false;
+    /**
+     * Which failures move on to the next model (the `FallbackPolicy`'s `handleIf`). Default: any but the caller's
+     * abort, an answer that does not match the schema, and mistakes in the call.
+     */
+    fallbackIf?: (error: unknown) => boolean;
+    budget?: AiBudget;
+    /**
+     * Cancels the call: the model call in flight, the backoff, the agent functions running (through their context's
+     * `signal`).
+     */
+    abortSignal?: AbortSignal;
+    /** Names the call in usage events (`'triage'`). */
+    label?: string;
+    /** Called after every model call of this call that answered, after the module's `onUsage`. */
+    onUsage?: (event: AiUsageEvent) => void | Promise<void>;
+    topP?: number;
+    topK?: number;
+    seed?: number;
+    stopSequences?: string[];
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+}
+/** The options of `generateObject()`. */
+export interface AiObjectCallOptions<S extends AiSchema = AiSchema> extends AiCallOptions {
+    /** What the answer must be. The model is sent its JSON Schema, and its answer is validated by it. */
+    schema: S;
+    /** A name and a description of the object, which some providers pass on to the model. */
+    schemaName?: string;
+    schemaDescription?: string;
+}

package/dist/interfaces/ai-call-options.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/ai-embedding.interface.d.ts

@@ -0,0 +1,79 @@
+import type { EmbeddingModel, EmbeddingModelUsage, EmbedManyResult, EmbedResult } from 'ai';
+import type { AiResilienceSettings } from './ai-module-options.interface.js';
+import type { AiModelInfo } from './ai-result.interface.js';
+/** Embedding settings, independent of language-model generation defaults. */
+export interface AiEmbeddingSettings extends AiResilienceSettings {
+    /** Provider-specific options, by provider name. */
+    providerOptions?: Record<string, Record<string, any>>;
+    /** HTTP headers sent to the embedding provider. */
+    headers?: Record<string, string>;
+    /** Maximum concurrent SDK batch requests within one `embedMany()` operation. Default 4. */
+    maxParallelCalls?: number;
+}
+/** Price per million input tokens, in the unit used for reported `cost`. */
+export interface AiEmbeddingModelPricing {
+    input: number;
+}
+/** A registered SDK embedding model with its own embedding settings. */
+export interface AiEmbeddingModelDefinition extends AiEmbeddingSettings {
+    model: EmbeddingModel;
+    pricing?: AiEmbeddingModelPricing;
+}
+/** A registered embedding name, or an SDK embedding-model object passed directly to a call. */
+export type AiEmbeddingModelReference = string | Exclude<EmbeddingModel, string>;
+/** Options shared by single and batch embedding calls. */
+export interface AiEmbeddingCallOptions extends AiEmbeddingSettings {
+    /** Name in `embeddingModels` (default `'default'`), or a direct SDK model object. */
+    model?: AiEmbeddingModelReference;
+    /**
+     * Cancels in-flight provider requests and retry backoff. `timeout` covers one provider request,
+     * so this is how to set a deadline for the whole operation (`AbortSignal.timeout(ms)`).
+     */
+    abortSignal?: AbortSignal;
+    /** Names this operation in usage and resilience events. */
+    label?: string;
+    /** Called after a successful operation, after the module's embedding usage listener. */
+    onEmbeddingUsage?: (event: AiEmbeddingUsageEvent) => void | Promise<void>;
+}
+export interface AiEmbedOptions extends AiEmbeddingCallOptions {
+    value: string;
+}
+export interface AiEmbedManyOptions extends AiEmbeddingCallOptions {
+    values: string[];
+}
+/** SDK single-embedding result with the resolved model and attempt count. */
+export interface AiEmbedResult extends EmbedResult {
+    model: AiModelInfo;
+    /** Provider requests made, retries included. */
+    attempts: number;
+    /** Cost of the reported usage; absent without model pricing. */
+    cost?: number;
+}
+/**
+ * SDK batch result, in input order. A failed operation rejects rather than returning partial
+ * results.
+ */
+export interface AiEmbedManyResult extends EmbedManyResult {
+    model: AiModelInfo;
+    /** Provider requests made, retries included. */
+    attempts: number;
+    /** Cost of the reported usage; absent without model pricing. */
+    cost?: number;
+}
+/**
+ * One successful embedding operation. Not a billing ledger: a provider may bill a request that
+ * timed out, and an operation that fails reports nothing, including the requests it completed.
+ * Input contents and output vectors are excluded.
+ */
+export interface AiEmbeddingUsageEvent {
+    operation: 'embed' | 'embedMany';
+    label?: string;
+    model: AiModelInfo;
+    inputCount: number;
+    usage: EmbeddingModelUsage;
+    /** Provider requests made, retries included. */
+    attempts: number;
+    /** Total duration of the operation, including retries and backoff. */
+    durationMs: number;
+    cost?: number;
+}

package/dist/interfaces/ai-embedding.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/ai-module-options.interface.d.ts

@@ -0,0 +1,110 @@
+import type { Duration, ResiliencePolicy, RetryOptions } from '@nestjs/resilience';
+import type { EmbeddingModel, LanguageModel } from 'ai';
+import type { AiUsageEvent } from './ai-usage.interface.js';
+import type { AiEmbeddingModelDefinition, AiEmbeddingSettings, AiEmbeddingUsageEvent } from './ai-embedding.interface.js';
+/** Prices per million tokens, in a unit of your choice: what `cost` is reported in. */
+export interface AiModelPricing {
+    input: number;
+    output: number;
+    /** Input tokens read from the prompt cache. Default: `input`. */
+    cachedInput?: number;
+}
+/** Limits on one call, over every step it makes. */
+export interface AiBudget {
+    /** Total tokens, input and output. */
+    maxTokens?: number;
+    /** In the unit of the models' `pricing`. A model without pricing counts as free. */
+    maxCost?: number;
+}
+/** Resilience settings shared by language-model and embedding calls. */
+export interface AiResilienceSettings {
+    /**
+     * The longest a model call may take to answer: its whole response for `generateText()` and `generateObject()`,
+     * its first chunk for `streamText()`, until its tools start for a step that calls them, one provider request for
+     * an embedding. Applied to each attempt, as a `TimeoutPolicy`. Default `'60s'`; `false` for none.
+     */
+    timeout?: Duration | false;
+    /**
+     * Retries of a failed model call, as `@nestjs/resilience`'s `RetryPolicy` takes them: `attempts` (default 3, the
+     * first included), `backoff` (default from `'1s'`, doubling, up to `'30s'`, full jitter), `retryIf`. Retried by
+     * default: what the provider marks retryable (408, 409, 429, 5xx and network failures) and timeouts; a
+     * `retry-after` the provider sends is honored, and one longer than `backoff.maxDelay` moves on to the fallback.
+     * An embedding call has no fallback, and retries only the provider request that failed. `false` for none.
+     */
+    retry?: RetryOptions | false;
+    /**
+     * A policy of your own (`ResiliencePolicy.wrap(breaker, retry, timeout)`), or the name of a preset of
+     * `ResilienceService` (`ResilienceModule.forRoot({ presets })`), in place of `retry` and `timeout`: a circuit
+     * breaker or a bulkhead shared with the rest of the application. Fallback models are applied around it. An
+     * embedding call runs it around each provider request, so a bulkhead or a rate limit counts requests.
+     */
+    resilience?: ResiliencePolicy | string;
+}
+/** Settings a language model, the module's `defaults` and each call can set; the call's win, then the model's. */
+export interface AiCallSettings extends AiResilienceSettings {
+    /** Generation settings passed to the model. */
+    maxOutputTokens?: number;
+    temperature?: number;
+    /** Provider-specific options, by provider name (`{ anthropic: { ... } }`). */
+    providerOptions?: Record<string, Record<string, any>>;
+    /** HTTP headers sent to the provider. */
+    headers?: Record<string, string | undefined>;
+}
+export interface AiModelDefinition extends AiCallSettings {
+    model: LanguageModel;
+    pricing?: AiModelPricing;
+    /** The models tried, in order, when this one fails after its retries: names of other models. */
+    fallback?: string | string[];
+}
+/** Defaults for language-model calls. `maxSteps` and `budget` are also those of durable runs (`AiAgents.run()`). */
+export interface AiCallDefaults extends AiCallSettings {
+    /** Model calls one call may make while the model asks for tools. Default 10 (25 for a durable run). */
+    maxSteps?: number;
+    budget?: AiBudget;
+}
+/** `forRoot()`'s options, and what the `forRootAsync()` factory returns. */
+export interface AiModuleOptions {
+    /**
+     * The models, by name: a `LanguageModel` (`anthropic('claude-opus-5-5')`, a gateway id such as
+     * `'openai/gpt-5'`), or a definition with its pricing, fallback and settings. Calls that name no model use
+     * `default`.
+     */
+    models?: Record<string, LanguageModel | AiModelDefinition>;
+    defaults?: AiCallDefaults;
+    /**
+     * Named embedding models, independent of `models`. At least one of the two registries must be
+     * nonempty.
+     */
+    embeddingModels?: Record<string, EmbeddingModel | AiEmbeddingModelDefinition>;
+    /**
+     * Embedding-only defaults. They do not inherit generation settings, headers or options from
+     * `defaults`.
+     */
+    embeddingDefaults?: AiEmbeddingSettings;
+    /** Called after every model call that answered, with its tokens and cost. Errors it throws are logged. */
+    onUsage?: (event: AiUsageEvent) => void | Promise<void>;
+    /** Called once after a successful embedding operation. Errors it throws are logged. */
+    onEmbeddingUsage?: (event: AiEmbeddingUsageEvent) => void | Promise<void>;
+    /**
+     * The modules whose providers are searched for agent functions (`@AgentFunction()` methods). Default: every module
+     * of the application.
+     */
+    include?: Function[];
+}
+/** What only the top level of `forRoot()` and `forRootAsync()` takes. */
+export interface AiModuleStructure {
+    /**
+     * Model names `@InjectModel()` may inject, beyond those it was seen asking for when the module was defined (the
+     * classes the module's file imports): for classes loaded later, such as lazily loaded modules.
+     */
+    modelNames?: string[];
+    /**
+     * Embedding-model counterpart of `modelNames`, for injection sites loaded after module
+     * definition.
+     */
+    embeddingModelNames?: string[];
+}
+/** What a class passed to `forRootAsync({ useClass })` implements. */
+export interface AiOptionsFactory {
+    createAiOptions(): AiModuleOptions | Promise<AiModuleOptions>;
+}

package/dist/interfaces/ai-module-options.interface.js

@@ -0,0 +1 @@
+export {};