@nestjs/ai 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+(The MIT License)
+
+Copyright (c) 2026 Kamil Mysliwiec
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[travis-image]: https://api.travis-ci.org/nestjs/nest.svg?branch=master
+[travis-url]: https://travis-ci.org/nestjs/nest
+[linux-image]: https://img.shields.io/travis/nestjs/nest/master.svg?label=linux
+[linux-url]: https://travis-ci.org/nestjs/nest
+
+  <p align="center">A progressive <a href="http://nodejs.org" target="blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
+    <p align="center">
+<a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
+<a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
+<a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/dm/@nestjs/core.svg" alt="NPM Downloads" /></a>
+<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
+<a href="https://opencollective.com/nest#backer"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
+<a href="https://opencollective.com/nest#sponsor"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
+  <a href="https://paypal.me/kamilmysliwiec"><img src="https://img.shields.io/badge/Donate-PayPal-dc3d53.svg"/></a>
+  <a href="https://twitter.com/nestframework"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow"></a>
+</p>
+  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
+  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+
+## Description
+
+Language models for [Nest](https://github.com/nestjs/nest): named models through dependency injection, model calls with timeouts, retries and fallback models (run on [`@nestjs/resilience`](https://github.com/nestjs/resilience) policies, or your own), budgets and usage events, structured output validated by a schema, the application's own provider methods as agent functions its agents call (through Nest's guards, interceptors, pipes and exception filters, as the user the agent acts for), answers streamed to the browser on Express, Fastify and the Node adapter, and durable agent runs on [`@nestjs/workflows`](https://github.com/nestjs/workflows) (`@nestjs/ai/workflows`) that survive restarts and wait for a person's approval. You write an agent function with `@AgentFunction()`, and the model is offered it as a tool; a method can be an MCP tool too, served by [`@nestjs/mcp`](https://github.com/nestjs/mcp), with its `@Tool()` stacked on it. Comes with a fake model for tests. Built on the [AI SDK](https://ai-sdk.dev) (`ai`) and its provider packages.
+
+## Installation
+
+```bash
+$ npm i --save @nestjs/ai @nestjs/resilience ai @ai-sdk/anthropic zod
+```
+
+Any `@ai-sdk/*` provider package works (`@ai-sdk/openai`, `@ai-sdk/google`, ...). Zod 4.2 or later for the schemas; any other [Standard Schema](https://standardschema.dev) library that produces JSON Schema works too. Node.js 22 or later.
+
+Each major version of `@nestjs/ai` supports one major version of the AI SDK: this one, `ai` 7.
+
+## Quick Start
+
+Register the models, and call them:
+
+```ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { Injectable, Module } from '@nestjs/common';
+import { AgentFunction, AiModule, AiService, type AgentFunctionContext } from '@nestjs/ai';
+import * as z from 'zod';
+
+@Injectable()
+export class OrdersTools {
+  constructor(private readonly orders: OrdersService) {}
+
+  @AgentFunction({
+    name: 'find-order',
+    description: 'Find an order by its id',
+    inputSchema: z.object({ orderId: z.string() }),
+  })
+  find({ orderId }: { orderId: string }, ctx: AgentFunctionContext) {
+    return this.orders.findFor(ctx.request?.user, orderId);
+  }
+}
+
+@Injectable()
+export class SupportService {
+  constructor(private readonly ai: AiService) {}
+
+  async answer(question: string, request: unknown) {
+    const { text } = await this.ai.generateText({
+      prompt: question,
+      tools: ['find-order'],
+      caller: { request },
+    });
+    return text;
+  }
+}
+
+@Module({
+  imports: [
+    AiModule.forRoot({
+      models: {
+        default: anthropic('claude-opus-5-5'),
+        fast: anthropic('claude-haiku-5-5'),
+      },
+      defaults: { timeout: '30s', retry: { attempts: 3 } },
+    }),
+  ],
+  providers: [OrdersService, OrdersTools, SupportService],
+})
+export class AppModule {}
+```
+
+A method that MCP clients call too also carries `@nestjs/mcp`'s `@Tool()`, with options of its own: the two decorators don't read each other's, and one schema constant serves both. `generateObject({ schema })` answers a typed object, and `streamText()` an answer a controller sends to the browser with `pipeUIMessageStreamToResponse(res)`, as the AI SDK's `useChat()` reads it. Agent function calls run through the guards, interceptors, pipes and filters of the class and the method, with the context type `'ai'`, so `AiExecutionContext` reads them in enhancers (on a method with both decorators, they see `'mcp'` for MCP clients' calls), and `@nestjs/authentication` (0.1.4 or later) and `@nestjs/authorization` (0.1.2 or later) authenticate and authorize them. `@nestjs/ai/testing` has `FakeModel`, which answers with text, tool calls, objects or errors, without a network.
+
+The [sample](sample) is a cat store: it triages support emails, and runs a chat assistant that calls the same `find-order` method its MCP server serves. `npm run build && npx tsc -p sample/tsconfig.json`, then `node sample/dist/main.js` (with `ANTHROPIC_API_KEY` set, Claude answers; without it, fake models do).
+
+Read [Overview](https://docs.nestjs.com/ai/overview) to get started and for the module's options, [Models](https://docs.nestjs.com/ai/models) for retries, timeouts, fallback models and budgets, [Tools](https://docs.nestjs.com/ai/tools) for agent functions, the call context, guards and authorization, [Agents](https://docs.nestjs.com/ai/agents) for the agent loop, streaming to the browser and durable runs, and [Testing](https://docs.nestjs.com/ai/testing) for the fake model.
+
+## Support
+
+Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
+
+## Stay in touch
+
+- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
+- Website - [https://nestjs.com](https://nestjs.com/)
+- Twitter - [@nestframework](https://twitter.com/nestframework)
+
+## License
+
+Nest is [MIT licensed](LICENSE).

package/dist/ai.constants.d.ts

@@ -0,0 +1,22 @@
+/** The module options (`forRoot()`'s, or what the `forRootAsync()` factory returns). */
+export declare const AI_MODULE_OPTIONS = "AI_MODULE_OPTIONS";
+/** Where `@AgentFunction()` records its options, on the method. */
+export declare const AGENT_FUNCTION_METADATA = "nestjs:ai:agent-function";
+/**
+ * The `ExecutionContext` type of agent function calls: `context.getType() === 'ai'` in a guard, an interceptor or an
+ * exception filter, which reads the call with `AiExecutionContext`.
+ */
+export declare const AI_CONTEXT_TYPE = "ai";
+/**
+ * The parameter metadata of agent functions, read by `ExternalContextCreator` (so that pipes run on the input): Nest's
+ * own route-arguments key, where `createParamDecorator()` decorators record themselves. `@nestjs/mcp` records the two
+ * parameters of its methods under the same key, with the same numbers (`AiParamtype`), so a method that is both an
+ * agent function and an MCP tool is recorded once, and both read it.
+ */
+export declare const AI_PARAMS_METADATA = "__routeArguments__";
+/** The name of the model calls use when they name none. */
+export declare const DEFAULT_MODEL_NAME = "default";
+/** Models that replace configured ones by name, from `@nestjs/ai/testing`'s `overrideModels()`. Internal. */
+export declare const AI_MODEL_OVERRIDES: unique symbol;
+/** The injection token of the model called `name`, which `@InjectModel(name)` injects. */
+export declare function getModelToken(name?: string): string;

package/dist/ai.constants.js

@@ -0,0 +1,24 @@
+/** The module options (`forRoot()`'s, or what the `forRootAsync()` factory returns). */
+export const AI_MODULE_OPTIONS = 'AI_MODULE_OPTIONS';
+/** Where `@AgentFunction()` records its options, on the method. */
+export const AGENT_FUNCTION_METADATA = 'nestjs:ai:agent-function';
+/**
+ * The `ExecutionContext` type of agent function calls: `context.getType() === 'ai'` in a guard, an interceptor or an
+ * exception filter, which reads the call with `AiExecutionContext`.
+ */
+export const AI_CONTEXT_TYPE = 'ai';
+/**
+ * The parameter metadata of agent functions, read by `ExternalContextCreator` (so that pipes run on the input): Nest's
+ * own route-arguments key, where `createParamDecorator()` decorators record themselves. `@nestjs/mcp` records the two
+ * parameters of its methods under the same key, with the same numbers (`AiParamtype`), so a method that is both an
+ * agent function and an MCP tool is recorded once, and both read it.
+ */
+export const AI_PARAMS_METADATA = '__routeArguments__';
+/** The name of the model calls use when they name none. */
+export const DEFAULT_MODEL_NAME = 'default';
+/** Models that replace configured ones by name, from `@nestjs/ai/testing`'s `overrideModels()`. Internal. */
+export const AI_MODEL_OVERRIDES = Symbol('AI_MODEL_OVERRIDES');
+/** The injection token of the model called `name`, which `@InjectModel(name)` injects. */
+export function getModelToken(name = DEFAULT_MODEL_NAME) {
+    return `nestjs:ai:model:${name}`;
+}

package/dist/ai.module-definition.d.ts

@@ -0,0 +1,23 @@
+import { type ConfigurableModuleAsyncOptions } from '@nestjs/common';
+import type { AiModuleOptions, AiModuleStructure, AiOptionsFactory } from './interfaces/ai-module-options.interface.js';
+import { AI_MODULE_OPTIONS } from './ai.constants.js';
+/** `forRoot()`'s options: the module options, and `isGlobal` (default false). */
+export type AiModuleRootOptions = AiModuleOptions & {
+    isGlobal?: boolean;
+};
+/**
+ * What `forRootAsync()` takes: `modelNames` and `isGlobal` at the top level, and one of `useFactory`, `useClass` or
+ * `useExisting` for the options.
+ */
+export type AiModuleAsyncOptions = ConfigurableModuleAsyncOptions<AiModuleOptions, 'createAiOptions'> & AiModuleStructure & {
+    isGlobal?: boolean;
+};
+export type { AiOptionsFactory };
+export { AI_MODULE_OPTIONS };
+export declare const ConfigurableModuleClass: import("@nestjs/common").ConfigurableModuleCls<AiModuleOptions, "forRoot", "createAiOptions", AiModuleStructure & {
+    isGlobal?: boolean;
+}>, OPTIONS_TYPE: AiModuleOptions & Partial<AiModuleStructure & {
+    isGlobal?: boolean;
+}>, ASYNC_OPTIONS_TYPE: ConfigurableModuleAsyncOptions<AiModuleOptions, "createAiOptions"> & Partial<AiModuleStructure & {
+    isGlobal?: boolean;
+}>;

package/dist/ai.module-definition.js

@@ -0,0 +1,30 @@
+import { ConfigurableModuleBuilder, Scope } from '@nestjs/common';
+import { INQUIRER } from '@nestjs/core';
+import { AI_MODULE_OPTIONS, getModelToken } from './ai.constants.js';
+import { AiModels } from './models/ai-models.service.js';
+import { requestedModelNames } from './models/model-requests.js';
+export { AI_MODULE_OPTIONS };
+export const { ConfigurableModuleClass, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new ConfigurableModuleBuilder({
+    moduleName: 'Ai',
+    optionsInjectionToken: AI_MODULE_OPTIONS,
+})
+    .setClassMethodName('forRoot')
+    .setFactoryMethodName('createAiOptions')
+    .setExtras({ isGlobal: false, modelNames: undefined }, (definition, { isGlobal, modelNames }) => {
+    const names = new Set([...(modelNames ?? []), ...requestedModelNames()]);
+    // Transient, so that each class that injects a model is known (INQUIRER), and one that asks for a model the
+    // module does not configure is named in the error.
+    const tokens = [...names].map((name) => ({
+        provide: getModelToken(name),
+        scope: Scope.TRANSIENT,
+        inject: [AiModels, INQUIRER],
+        useFactory: (models, inquirer) => models.injected(name, inquirer),
+    }));
+    return {
+        ...definition,
+        global: isGlobal,
+        providers: [...(definition.providers ?? []), ...tokens],
+        exports: [...(definition.exports ?? []), ...tokens.map((provider) => provider.provide)],
+    };
+})
+    .build();

package/dist/ai.module.d.ts

@@ -0,0 +1,11 @@
+import { type DynamicModule } from '@nestjs/common';
+import { ConfigurableModuleClass, type AiModuleAsyncOptions, type AiModuleRootOptions } from './ai.module-definition.js';
+/**
+ * `AiModule.forRoot({ models: { default: ... } })`, or `forRootAsync({ imports, inject, useFactory })`: the
+ * application's models by name, `AiService` for model calls, and the `@AgentFunction()` methods of its providers,
+ * which its agents call as tools. Global with `isGlobal: true`.
+ */
+export declare class AiModule extends ConfigurableModuleClass {
+    static forRoot(options: AiModuleRootOptions): DynamicModule;
+    static forRootAsync(options: AiModuleAsyncOptions): DynamicModule;
+}

package/dist/ai.module.js

@@ -0,0 +1,36 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import { AI_MODEL_OVERRIDES } from './ai.constants.js';
+import { ConfigurableModuleClass, } from './ai.module-definition.js';
+import { AiModels } from './models/ai-models.service.js';
+import { AiService } from './services/ai.service.js';
+import { AiTools } from './tools/ai-tools.service.js';
+/**
+ * `AiModule.forRoot({ models: { default: ... } })`, or `forRootAsync({ imports, inject, useFactory })`: the
+ * application's models by name, `AiService` for model calls, and the `@AgentFunction()` methods of its providers,
+ * which its agents call as tools. Global with `isGlobal: true`.
+ */
+let AiModule = class AiModule extends ConfigurableModuleClass {
+    static forRoot(options) {
+        // `@InjectModel()` may ask for every model `forRoot()` names.
+        const modelNames = Object.keys(options?.models ?? {});
+        return super.forRoot({ ...options, modelNames });
+    }
+    static forRootAsync(options) {
+        return super.forRootAsync(options);
+    }
+};
+AiModule = __decorate([
+    Module({
+        imports: [DiscoveryModule],
+        providers: [AiModels, AiTools, AiService, { provide: AI_MODEL_OVERRIDES, useValue: null }],
+        exports: [AiModels, AiTools, AiService],
+    })
+], AiModule);
+export { AiModule };

package/dist/context/ai-execution-context.d.ts

@@ -0,0 +1,32 @@
+import type { ArgumentsHost, ExecutionContext } from '@nestjs/common';
+import { ExecutionContextHost } from '@nestjs/core/helpers/execution-context-host.js';
+import type { AgentFunctionContext } from '../interfaces/agent-function.interface.js';
+/** `context.getType<AiContextType>() === 'ai'` in an enhancer tells an agent function call from an HTTP request. */
+export type AiContextType = 'ai';
+/**
+ * The execution context of an agent function call, for guards, interceptors and exception filters, as
+ * `McpExecutionContext` is for MCP calls:
+ *
+ * ```ts
+ * canActivate(context: ExecutionContext) {
+ *   if (context.getType<AiContextType>() !== 'ai') {
+ *     return true;
+ *   }
+ *   const call = AiExecutionContext.create(context);
+ *   return call.getRequest()?.user?.role === 'support';
+ * }
+ * ```
+ *
+ * The arguments of an agent function call are `[input, context]`: `getInput()` (also `switchToRpc().getData()`) and
+ * `getContext()`.
+ */
+export declare class AiExecutionContext extends ExecutionContextHost {
+    static create(context: ExecutionContext | ArgumentsHost): AiExecutionContext;
+    /** The arguments, validated against the function's `inputSchema`. */
+    getInput<T = any>(): T;
+    getContext<TRequest = any, TUser = any>(): AgentFunctionContext<TRequest, TUser>;
+    /** The agent function's name. */
+    getName(): string | undefined;
+    /** The HTTP platform's request the agent runs in (`caller.request`); `undefined` where there is none, as in a job. */
+    getRequest<TRequest = any>(): TRequest | undefined;
+}

package/dist/context/ai-execution-context.js

@@ -0,0 +1,41 @@
+import { ExecutionContextHost } from '@nestjs/core/helpers/execution-context-host.js';
+/**
+ * The execution context of an agent function call, for guards, interceptors and exception filters, as
+ * `McpExecutionContext` is for MCP calls:
+ *
+ * ```ts
+ * canActivate(context: ExecutionContext) {
+ *   if (context.getType<AiContextType>() !== 'ai') {
+ *     return true;
+ *   }
+ *   const call = AiExecutionContext.create(context);
+ *   return call.getRequest()?.user?.role === 'support';
+ * }
+ * ```
+ *
+ * The arguments of an agent function call are `[input, context]`: `getInput()` (also `switchToRpc().getData()`) and
+ * `getContext()`.
+ */
+export class AiExecutionContext extends ExecutionContextHost {
+    static create(context) {
+        const host = context;
+        const ai = new AiExecutionContext(context.getArgs(), host.getClass?.(), host.getHandler?.());
+        ai.setType(context.getType());
+        return ai;
+    }
+    /** The arguments, validated against the function's `inputSchema`. */
+    getInput() {
+        return this.getArgByIndex(0);
+    }
+    getContext() {
+        return this.getArgByIndex(1);
+    }
+    /** The agent function's name. */
+    getName() {
+        return this.getContext()?.name;
+    }
+    /** The HTTP platform's request the agent runs in (`caller.request`); `undefined` where there is none, as in a job. */
+    getRequest() {
+        return this.getContext()?.request;
+    }
+}

package/dist/context/ai-params.d.ts

@@ -0,0 +1,20 @@
+import type { ParamsFactory } from '@nestjs/core';
+/**
+ * The parameters of an agent function. Pipes see the input as a `body` parameter (so `ValidationPipe` validates a DTO
+ * class) and the context as a `custom` one (which it skips). The numbers are `@nestjs/mcp`'s, and must stay so: a
+ * method that is an MCP tool too has its parameters recorded once, under the key both packages read, and either
+ * package's factory reads them.
+ */
+export declare enum AiParamtype {
+    INPUT = 3,
+    CONTEXT = 1001
+}
+export declare class AiParamsFactory implements ParamsFactory {
+    exchangeKeyForValue(type: number, data: unknown, args: unknown[]): unknown;
+}
+/**
+ * Records the two parameters of an agent function, `(input, context)`, as parameter metadata, where no parameter
+ * decorator took their place. `ExternalContextCreator` runs pipes only on parameters it has metadata for, and calls
+ * the method with those alone: custom decorators (`createParamDecorator()`) on other parameters keep theirs.
+ */
+export declare function recordHandlerParams(target: Function, methodName: string): void;

package/dist/context/ai-params.js

@@ -0,0 +1,44 @@
+import { RouteParamtypes } from '@nestjs/common/enums/route-paramtypes.enum.js';
+import { AI_PARAMS_METADATA } from '../ai.constants.js';
+/**
+ * The parameters of an agent function. Pipes see the input as a `body` parameter (so `ValidationPipe` validates a DTO
+ * class) and the context as a `custom` one (which it skips). The numbers are `@nestjs/mcp`'s, and must stay so: a
+ * method that is an MCP tool too has its parameters recorded once, under the key both packages read, and either
+ * package's factory reads them.
+ */
+export var AiParamtype;
+(function (AiParamtype) {
+    AiParamtype[AiParamtype["INPUT"] = 3] = "INPUT";
+    AiParamtype[AiParamtype["CONTEXT"] = 1001] = "CONTEXT";
+})(AiParamtype || (AiParamtype = {}));
+export class AiParamsFactory {
+    exchangeKeyForValue(type, data, args) {
+        switch (type) {
+            case AiParamtype.INPUT: {
+                const input = args[0];
+                return typeof data === 'string' && input ? input[data] : input;
+            }
+            case AiParamtype.CONTEXT:
+                return args[1];
+            default:
+                return null;
+        }
+    }
+}
+/**
+ * Records the two parameters of an agent function, `(input, context)`, as parameter metadata, where no parameter
+ * decorator took their place. `ExternalContextCreator` runs pipes only on parameters it has metadata for, and calls
+ * the method with those alone: custom decorators (`createParamDecorator()`) on other parameters keep theirs.
+ */
+export function recordHandlerParams(target, methodName) {
+    const existing = Reflect.getMetadata(AI_PARAMS_METADATA, target, methodName) ?? {};
+    const taken = new Set(Object.values(existing).map((param) => param.index));
+    if (taken.has(0) && taken.has(1)) {
+        return;
+    }
+    Reflect.defineMetadata(AI_PARAMS_METADATA, {
+        ...existing,
+        ...(!taken.has(0) && { [`${AiParamtype.INPUT}:0`]: { index: 0, data: undefined, pipes: [] } }),
+        ...(!taken.has(1) && { [`${AiParamtype.CONTEXT}:1`]: { index: 1, data: undefined, pipes: [] } }),
+    }, target, methodName);
+}

package/dist/decorators/agent-function.decorator.d.ts

@@ -0,0 +1,22 @@
+import type { AgentFunctionOptions } from '../interfaces/agent-function.interface.js';
+/**
+ * Makes the method an agent function: one the application's agents may call, which a call lists in `tools`, and the
+ * model is offered as a tool. It is called as `(input, context)`: `input` is the arguments, validated against
+ * `inputSchema`, and `context` the `AgentFunctionContext`. Guards, interceptors, pipes and exception filters run
+ * around it, with the context type `'ai'` (`AiExecutionContext` reads the call).
+ *
+ * ```ts
+ * @AgentFunction({
+ *   name: 'find-order',
+ *   description: 'Find an order by its id',
+ *   inputSchema: z.object({ orderId: z.string() }),
+ * })
+ * find({ orderId }: { orderId: string }, ctx: AgentFunctionContext) {
+ *   return this.orders.find(orderId);
+ * }
+ * ```
+ *
+ * A method that MCP clients call too also carries `@nestjs/mcp`'s `@Tool()`, with options of its own: neither
+ * decorator reads the other's.
+ */
+export declare function AgentFunction(options?: AgentFunctionOptions): MethodDecorator;

package/dist/decorators/agent-function.decorator.js

@@ -0,0 +1,36 @@
+import { AGENT_FUNCTION_METADATA } from '../ai.constants.js';
+/**
+ * Makes the method an agent function: one the application's agents may call, which a call lists in `tools`, and the
+ * model is offered as a tool. It is called as `(input, context)`: `input` is the arguments, validated against
+ * `inputSchema`, and `context` the `AgentFunctionContext`. Guards, interceptors, pipes and exception filters run
+ * around it, with the context type `'ai'` (`AiExecutionContext` reads the call).
+ *
+ * ```ts
+ * @AgentFunction({
+ *   name: 'find-order',
+ *   description: 'Find an order by its id',
+ *   inputSchema: z.object({ orderId: z.string() }),
+ * })
+ * find({ orderId }: { orderId: string }, ctx: AgentFunctionContext) {
+ *   return this.orders.find(orderId);
+ * }
+ * ```
+ *
+ * A method that MCP clients call too also carries `@nestjs/mcp`'s `@Tool()`, with options of its own: neither
+ * decorator reads the other's.
+ */
+export function AgentFunction(options = {}) {
+    const metadata = { ...options };
+    return (target, key, descriptor) => {
+        const method = descriptor.value;
+        const where = `${typeof target === 'function' ? target.name : target.constructor.name}.${String(key)}`;
+        if (typeof method !== 'function') {
+            throw new TypeError(`@AgentFunction() goes on a method, and ${where} is not one.`);
+        }
+        if (Reflect.hasOwnMetadata(AGENT_FUNCTION_METADATA, method)) {
+            throw new TypeError(`${where} has @AgentFunction() twice: give it one, with all its options.`);
+        }
+        Reflect.defineMetadata(AGENT_FUNCTION_METADATA, metadata, method);
+        return descriptor;
+    };
+}

package/dist/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export * from './agent-function.decorator.js';
+export * from './inject-model.decorator.js';

package/dist/decorators/index.js

@@ -0,0 +1,2 @@
+export * from './agent-function.decorator.js';
+export * from './inject-model.decorator.js';

package/dist/decorators/inject-model.decorator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Injects the configured `LanguageModel` called `name` (default `'default'`), for code that calls `ai` itself.
+ * `AiService` calls get retries, timeouts, fallback and usage events; a direct `ai` call gets none of them. A name
+ * the module does not configure fails at startup.
+ *
+ * ```ts
+ * constructor(@InjectModel('fast') private readonly model: LanguageModel) {}
+ * ```
+ */
+export declare function InjectModel(name?: string): PropertyDecorator & ParameterDecorator;

package/dist/decorators/inject-model.decorator.js

@@ -0,0 +1,16 @@
+import { Inject } from '@nestjs/common';
+import { DEFAULT_MODEL_NAME, getModelToken } from '../ai.constants.js';
+import { recordModelRequest } from '../models/model-requests.js';
+/**
+ * Injects the configured `LanguageModel` called `name` (default `'default'`), for code that calls `ai` itself.
+ * `AiService` calls get retries, timeouts, fallback and usage events; a direct `ai` call gets none of them. A name
+ * the module does not configure fails at startup.
+ *
+ * ```ts
+ * constructor(@InjectModel('fast') private readonly model: LanguageModel) {}
+ * ```
+ */
+export function InjectModel(name = DEFAULT_MODEL_NAME) {
+    recordModelRequest(name);
+    return Inject(getModelToken(name));
+}

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';