@nestjs/ai 0.0.0-stage → 0.0.1

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,13 @@
+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, getModelToken } from './ai.constants.js';
+export type { AiBudget, AiCallDefaults, AiCallSettings, AiModelDefinition, AiModelPricing, AiModuleOptions, AiModuleStructure, } from './interfaces/index.js';
+export { AiModels } from './models/ai-models.service.js';
+export { AiService } from './services/ai.service.js';
+export { AiTextStream, type AiStreamResponseOptions, type AiUIMessageStreamOptions, } from './runtime/text-stream.js';
+export type { AiCallOptions, 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,15 @@
+// Module and options
+export { AiModule } from './ai.module.js';
+export { AI_MODULE_OPTIONS, } from './ai.module-definition.js';
+export { DEFAULT_MODEL_NAME, getModelToken } from './ai.constants.js';
+// Models and model calls
+export { AiModels } from './models/ai-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-module-options.interface.d.ts

@@ -0,0 +1,88 @@
+import type { Duration, ResiliencePolicy, RetryOptions } from '@nestjs/resilience';
+import type { LanguageModel } from 'ai';
+import type { AiUsageEvent } from './ai-usage.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;
+}
+/** Settings a model, the module's `defaults` and each call can set; the call's win, then the model's. */
+export interface AiCallSettings {
+    /**
+     * 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. 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.
+     * `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.
+     */
+    resilience?: ResiliencePolicy | string;
+    /** 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 every call. `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;
+    /** Called after every model call that answered, with its tokens and cost. Errors it throws are logged. */
+    onUsage?: (event: AiUsageEvent) => 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[];
+}
+/** 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 {};

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

@@ -0,0 +1,54 @@
+import type { FinishReason, ModelMessage } from 'ai';
+import type { AiUsage } from './ai-usage.interface.js';
+/** Which model answered. */
+export interface AiModelInfo {
+    /** Its name in `forRoot({ models })`; `undefined` for a `LanguageModel` passed to the call. */
+    name?: string;
+    provider: string;
+    modelId: string;
+}
+export interface AiToolCall {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+export interface AiToolResult extends AiToolCall {
+    /** What the tool returned; absent when it failed. */
+    output?: unknown;
+    /** What the model was told about a failure. */
+    error?: string;
+}
+/** One model call of a text generation, with the tool calls it made and their results. */
+export interface AiStep {
+    index: number;
+    model: AiModelInfo;
+    text: string;
+    toolCalls: AiToolCall[];
+    toolResults: AiToolResult[];
+    finishReason: FinishReason;
+    usage: AiUsage;
+    cost?: number;
+    /** Attempts made for this step, over every model tried. */
+    attempts: number;
+}
+export interface AiTextResult {
+    /** The text of the last step. */
+    text: string;
+    /** The last step's: `tool-calls` when `maxSteps` ran out while the model still asked for tools. */
+    finishReason: FinishReason;
+    steps: AiStep[];
+    /** Summed over the steps. */
+    usage: AiUsage;
+    /** Summed over the steps whose model has `pricing`; `undefined` when none had. */
+    cost?: number;
+    toolCalls: AiToolCall[];
+    toolResults: AiToolResult[];
+    /** The assistant and tool messages of every step, to append to a conversation. */
+    responseMessages: ModelMessage[];
+    /** The model of the last step. */
+    model: AiModelInfo;
+}
+export interface AiObjectResult<T> extends AiTextResult {
+    /** The answer, validated by the schema. */
+    object: T;
+}

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

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

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

@@ -0,0 +1,44 @@
+/**
+ * A schema the package accepts: a Standard Schema that also produces JSON Schema (`~standard.jsonSchema`), as
+ * `@nestjs/mcp`'s schemas are, so that one schema serves a method's `@AgentFunction()` and its `@Tool()`. Zod 4.2+
+ * and ArkType schemas are, as they are; Valibot through
+ * `toStandardJsonSchema()` from `@valibot/to-json-schema`; a JSON Schema document through `fromJsonSchema()` from
+ * `@modelcontextprotocol/server`. The model is sent the JSON Schema, and what it answers is validated by the schema.
+ *
+ * The shape of the [Standard Schema](https://standardschema.dev) interfaces, declared here so that the package has no
+ * dependency for them.
+ */
+export interface AiSchema<Input = any, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+        readonly validate: (value: unknown, options?: {
+            readonly libraryOptions?: Record<string, unknown> | undefined;
+        } | undefined) => AiSchemaResult<Output> | Promise<AiSchemaResult<Output>>;
+        readonly jsonSchema: {
+            readonly input: (options: AiJsonSchemaOptions) => Record<string, unknown>;
+            readonly output: (options: AiJsonSchemaOptions) => Record<string, unknown>;
+        };
+    };
+}
+export interface AiJsonSchemaOptions {
+    readonly target: 'draft-2020-12' | 'draft-07' | 'openapi-3.0' | ({} & string);
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+}
+export type AiSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | {
+            readonly key: PropertyKey;
+        }> | undefined;
+    }>;
+};
+/** The type a schema validates to. */
+export type InferSchemaOutput<S extends AiSchema> = NonNullable<S['~standard']['types']>['output'];

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * Who an agent acts for. Agent functions receive it in their context (`AgentFunctionContext`), and guards read it
+ * there, as a route's guards read the request.
+ *
+ * ```ts
+ * caller: { request }                      // in a controller: the request's user, headers, session
+ * caller: { user: job.data.user, scopes }  // in a queue job
+ * ```
+ */
+export interface AiCaller<TUser = any, TRequest = any> {
+    /** The HTTP platform's request the agent runs in (Express, Fastify, the Node adapter). */
+    request?: TRequest;
+    /** The user, where there is no request (a queue job, a workflow); in a request, it is `request.user`. */
+    user?: TUser;
+    /** Scopes the caller holds, checked against an agent function's `scopes`. */
+    scopes?: readonly string[];
+}
+/**
+ * What a call's `tools` lists: agent function names, and provider classes (every agent function of the class). The
+ * model is offered each as a tool.
+ */
+export type AiToolSelection = ReadonlyArray<string | (abstract new (...args: any[]) => unknown)>;

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

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

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

@@ -0,0 +1,30 @@
+import type { AiModelInfo } from './ai-result.interface.js';
+/** Tokens a model call used. A count the provider did not report is 0. */
+export interface AiUsage {
+    /** Every input token, cached ones included. */
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /** The part of `inputTokens` read from the provider's prompt cache. */
+    cachedInputTokens: number;
+    /** The part of `outputTokens` spent on reasoning. */
+    reasoningTokens: number;
+}
+/** One model call that answered: a step of `generateText()`, `generateObject()` or `streamText()`. */
+export interface AiUsageEvent {
+    /** The call's `label`, to tell calls apart (`'triage'`). */
+    label?: string;
+    model: AiModelInfo;
+    /** 0-based step of the call: a call that uses tools makes several model calls. */
+    step: number;
+    /** 1-based attempt of this model for this step. */
+    attempt: number;
+    /** Whether it was a fallback model. */
+    fallback: boolean;
+    stream: boolean;
+    usage: AiUsage;
+    /** In the unit of the model's `pricing`; `undefined` without one. */
+    cost?: number;
+    durationMs: number;
+    finishReason: string;
+}

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

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

package/dist/interfaces/index.d.ts

@@ -0,0 +1,7 @@
+export * from './agent-function.interface.js';
+export * from './ai-call-options.interface.js';
+export * from './ai-module-options.interface.js';
+export * from './ai-result.interface.js';
+export * from './ai-schema.interface.js';
+export * from './ai-tool.interface.js';
+export * from './ai-usage.interface.js';

package/dist/interfaces/index.js

@@ -0,0 +1,7 @@
+export * from './agent-function.interface.js';
+export * from './ai-call-options.interface.js';
+export * from './ai-module-options.interface.js';
+export * from './ai-result.interface.js';
+export * from './ai-schema.interface.js';
+export * from './ai-tool.interface.js';
+export * from './ai-usage.interface.js';

package/dist/models/ai-models.service.d.ts

@@ -0,0 +1,29 @@
+import type { LanguageModel } from 'ai';
+import type { AiModelReference } from '../interfaces/ai-call-options.interface.js';
+import type { AiCallSettings, AiModelPricing, AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+import type { AiModelInfo } from '../interfaces/ai-result.interface.js';
+/** A model, as calls use it. Internal. */
+export interface ResolvedModel {
+    info: AiModelInfo;
+    model: LanguageModel;
+    pricing?: AiModelPricing;
+    settings: AiCallSettings;
+    /** The names of the models tried after it. */
+    fallback: string[];
+}
+/** The configured models, by name. */
+export declare class AiModels {
+    private readonly models;
+    constructor(options: AiModuleOptions, overrides?: Record<string, LanguageModel> | null);
+    /** The names of the configured models. */
+    names(): string[];
+    /** The `LanguageModel` called `name`, for code that calls `ai` directly. */
+    get(name?: string): LanguageModel;
+    /** Whether a model called `name` is configured. */
+    has(name: string): boolean;
+    /** @internal What `@InjectModel(name)` injects into `inquirer`; a name that is not configured fails at startup. */
+    injected(name: string, inquirer: unknown): LanguageModel;
+    /** @internal A name, or a `LanguageModel` given to a call (with no settings of its own). */
+    resolve(reference: AiModelReference | undefined): ResolvedModel;
+    private known;
+}