@nestjs/ai 0.0.0-stage → 0.0.1

package/dist/services/ai.service.js

@@ -0,0 +1,139 @@
+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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { ResilienceService } from '@nestjs/resilience';
+import { AI_MODULE_OPTIONS } from '../ai.constants.js';
+import { AiConfigurationError, AiOutputError } from '../errors/ai.errors.js';
+import { AiModels } from '../models/ai-models.service.js';
+import { runLoop, usageEvent } from '../runtime/agent-loop.js';
+import { createCallPlan } from '../runtime/call-plan.js';
+import { runStep } from '../runtime/model-policy.js';
+import { generateStep } from '../runtime/steps.js';
+import { AiTextStream } from '../runtime/text-stream.js';
+import { AiTools } from '../tools/ai-tools.service.js';
+import { toModelSchema } from '../utils/schema.util.js';
+const NEVER_ABORTED = new AbortController().signal;
+/**
+ * Model calls: text, structured output and streams, with the application's agent functions as tools, through the
+ * configured models, with timeouts, retries, fallback, budgets and usage events.
+ *
+ * ```ts
+ * const { text } = await this.ai.generateText({ prompt: 'Summarize this ticket: ...' });
+ * ```
+ */
+let AiService = class AiService {
+    constructor(models, tools, options, moduleRef) {
+        this.models = models;
+        this.tools = tools;
+        this.options = options;
+        this.moduleRef = moduleRef;
+        this.logger = new Logger('AiModule');
+    }
+    /** Generates text; with `tools`, calls them as the model asks, and answers when it is done. */
+    async generateText(options) {
+        const plan = this.plan(options, options?.abortSignal ?? NEVER_ABORTED);
+        const { result } = await runLoop(plan, { stream: false }, (event) => this.report(plan, event));
+        return result;
+    }
+    /**
+     * Generates an object that matches `schema`: an invoice from an email, a triage decision from a ticket. Rejects
+     * with `AiOutputError` when the answer does not match it.
+     */
+    async generateObject(options) {
+        const schema = toModelSchema(options?.schema, 'generateObject() `schema`');
+        const plan = this.plan(options, options.abortSignal ?? NEVER_ABORTED);
+        const { result, output } = await runLoop(plan, {
+            stream: false,
+            output: {
+                schema,
+                ...(options.schemaName !== undefined && { name: options.schemaName }),
+                ...(options.schemaDescription !== undefined && { description: options.schemaDescription }),
+            },
+        }, (event) => this.report(plan, event));
+        if (output === undefined) {
+            throw new AiOutputError(`The model was still calling tools after ${plan.maxSteps} step(s), and gave no answer. Raise \`maxSteps\`.`, result.text);
+        }
+        return { ...result, object: output };
+    }
+    /**
+     * Streams text: the call starts now, and its answer can be sent to the browser as it is generated
+     * (`pipeUIMessageStreamToResponse(res)`), read (`textStream`) or awaited (`text`). Mistakes in the options throw
+     * here; failures of the call reach the stream.
+     */
+    streamText(options) {
+        const controller = new AbortController();
+        const signal = options?.abortSignal ? AbortSignal.any([options.abortSignal, controller.signal]) : controller.signal;
+        const plan = this.plan(options, signal);
+        return new AiTextStream(controller, async (emit) => {
+            const { result, finish } = await runLoop(plan, { stream: true, emit }, (event) => this.report(plan, event));
+            emit(finish ?? { type: 'finish', finishReason: result.finishReason });
+            return result;
+        });
+    }
+    /**
+     * @internal One model call of a durable run (`@nestjs/ai/workflows`), with `messages` so far: the tools are offered
+     * and their calls returned, not run. Retries, timeouts, fallback and usage events as for any call.
+     */
+    async callModel(options, { index, messages, signal }) {
+        const plan = this.plan({ ...options, prompt: undefined, messages }, signal, false);
+        const { value, attempts } = await runStep(plan, async (attempt) => {
+            const outcome = await generateStep(plan, index, plan.messages, attempt);
+            this.report(plan, usageEvent(plan, attempt, outcome, false));
+            return outcome;
+        });
+        return { outcome: value, attempts };
+    }
+    plan(options, signal, toolExecution = true) {
+        return createCallPlan(options, {
+            models: this.models,
+            tools: this.tools,
+            moduleOptions: this.options,
+            signal,
+            preset: (name) => this.preset(name),
+            toolExecution,
+        });
+    }
+    /** A preset of the application's `ResilienceService`, which `ResilienceModule.forRoot({ presets })` configures. */
+    preset(name) {
+        let service;
+        try {
+            service = this.moduleRef.get(ResilienceService, { strict: false });
+        }
+        catch {
+            throw new AiConfigurationError(`\`resilience: '${name}'\` names a preset of ResilienceService, and the application does not import ResilienceModule.`);
+        }
+        return service.preset(name);
+    }
+    /** Calls the usage listeners. They never fail the call: what they throw is logged. */
+    report(plan, event) {
+        for (const listener of plan.listeners) {
+            try {
+                Promise.resolve(listener(event)).catch((error) => this.logListenerError(error));
+            }
+            catch (error) {
+                this.logListenerError(error);
+            }
+        }
+    }
+    logListenerError(error) {
+        this.logger.error(`onUsage failed: ${error?.message ?? String(error)}`, error?.stack);
+    }
+};
+AiService = __decorate([
+    Injectable(),
+    __param(2, Inject(AI_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [AiModels,
+        AiTools, Object, ModuleRef])
+], AiService);
+export { AiService };

package/dist/testing/fake-model.d.ts

@@ -0,0 +1,96 @@
+import { APICallError } from 'ai';
+import { MockLanguageModelV4 } from 'ai/test';
+import type { AiUsage } from '../interfaces/ai-usage.interface.js';
+type CallOptions = Parameters<MockLanguageModelV4['doGenerate']>[0];
+type GenerateResult = Awaited<ReturnType<MockLanguageModelV4['doGenerate']>>;
+type FinishReason = GenerateResult['finishReason']['unified'];
+/** A tool call the fake model makes. */
+export interface FakeToolCall {
+    /** The tool's name. */
+    name: string;
+    /** Its arguments. Default `{}`. */
+    input?: unknown;
+    /** Default `call-<n>`. */
+    id?: string;
+}
+/** One answer of the fake model. */
+export interface FakeTurn {
+    text?: string;
+    /** Answered as JSON text: what `generateObject()` reads. */
+    object?: unknown;
+    toolCalls?: FakeToolCall[];
+    /** Default: 10 input and 10 output tokens. */
+    usage?: Partial<Pick<AiUsage, 'inputTokens' | 'outputTokens' | 'cachedInputTokens' | 'reasoningTokens'>>;
+    /** Default `tool-calls` with tool calls, else `stop`. */
+    finishReason?: FinishReason;
+    /** Milliseconds before the model answers (a stream: before it opens). The call's abort cuts it short. */
+    delay?: number;
+    /** Milliseconds between a stream's chunks. */
+    chunkDelay?: number;
+    /** A stream fails with this error after its text, as a connection that breaks does. */
+    streamError?: unknown;
+}
+/**
+ * What the fake model answers a call with: text, a turn, an error (thrown, as a provider's failure: see
+ * `providerError()`), or a function of the call that returns one of these.
+ */
+export type FakeAnswer = string | FakeTurn | Error | ((call: FakeModelCall) => FakeAnswer | Promise<FakeAnswer>);
+/** A call the fake model received. */
+export interface FakeModelCall {
+    stream: boolean;
+    /** The system prompt. */
+    instructions?: string;
+    /** The text of the last user message. */
+    lastUserMessage?: string;
+    /** The results of the tools called in the previous step, as the model reads them. */
+    toolResults: Array<{
+        toolName: string;
+        toolCallId: string;
+        output: unknown;
+    }>;
+    /** The names of the tools offered. */
+    tools: string[];
+    /** Everything the model was sent (`ai`'s provider-level call options). */
+    options: CallOptions;
+}
+/**
+ * A language model for tests, with no network: it answers each call with the next of its `answers` (text, tool
+ * calls, objects, errors, delays), and records the calls. Pass a function instead of a list to answer every call
+ * with it.
+ *
+ * ```ts
+ * const model = new FakeModel([
+ *   { toolCalls: [{ name: 'find-order', input: { orderId: 'ord_1' } }] },
+ *   'Your order ships tomorrow.',
+ * ]);
+ * ```
+ */
+export declare class FakeModel extends MockLanguageModelV4 {
+    readonly calls: FakeModelCall[];
+    private readonly answers;
+    private readonly answerAll;
+    private toolCallCount;
+    constructor(answers?: FakeAnswer[] | ((call: FakeModelCall) => FakeAnswer | Promise<FakeAnswer>), { provider, modelId }?: {
+        modelId?: string | undefined;
+        provider?: string | undefined;
+    });
+    /** Adds answers, after the ones not used yet. */
+    reply(...answers: FakeAnswer[]): this;
+    /** The last call, or `undefined`. */
+    get lastCall(): FakeModelCall | undefined;
+    private answer;
+    private generate;
+    private stream;
+    private toolCalls;
+}
+/** `new FakeModel(answers)`. */
+export declare function fakeModel(...answers: FakeAnswer[]): FakeModel;
+/**
+ * A provider's HTTP error, as `@ai-sdk/*` providers throw it: retryable for 408, 409, 429 and 5xx. `retryAfter` (in
+ * seconds) is sent as a `retry-after` header.
+ */
+export declare function providerError(status: number, { message, retryAfter }?: {
+    message?: string;
+    retryAfter?: number;
+}): APICallError;
+export {};

package/dist/testing/fake-model.js

@@ -0,0 +1,201 @@
+import { APICallError } from 'ai';
+import { MockLanguageModelV4 } from 'ai/test';
+/**
+ * A language model for tests, with no network: it answers each call with the next of its `answers` (text, tool
+ * calls, objects, errors, delays), and records the calls. Pass a function instead of a list to answer every call
+ * with it.
+ *
+ * ```ts
+ * const model = new FakeModel([
+ *   { toolCalls: [{ name: 'find-order', input: { orderId: 'ord_1' } }] },
+ *   'Your order ships tomorrow.',
+ * ]);
+ * ```
+ */
+export class FakeModel extends MockLanguageModelV4 {
+    constructor(answers = [], { provider = 'fake', modelId = 'fake-model' } = {}) {
+        super({ provider, modelId });
+        this.calls = [];
+        this.toolCallCount = 0;
+        this.answers = Array.isArray(answers) ? [...answers] : [];
+        this.answerAll = typeof answers === 'function' ? answers : undefined;
+        this.doGenerate = async (options) => this.generate(await this.answer(options, false), options);
+        this.doStream = async (options) => this.stream(await this.answer(options, true), options);
+    }
+    /** Adds answers, after the ones not used yet. */
+    reply(...answers) {
+        this.answers.push(...answers);
+        return this;
+    }
+    /** The last call, or `undefined`. */
+    get lastCall() {
+        return this.calls[this.calls.length - 1];
+    }
+    async answer(options, stream) {
+        const call = describeCall(options, stream);
+        this.calls.push(call);
+        let answer = this.answerAll ?? this.answers.shift();
+        if (answer === undefined) {
+            throw new Error(`FakeModel: no answer left for call ${this.calls.length}. Give it more answers.`);
+        }
+        while (typeof answer === 'function') {
+            answer = await answer(call);
+        }
+        if (answer instanceof Error) {
+            throw answer;
+        }
+        const turn = typeof answer === 'string' ? { text: answer } : answer;
+        if (turn.delay) {
+            await sleep(turn.delay, options.abortSignal);
+        }
+        return turn;
+    }
+    generate(turn, options) {
+        options.abortSignal?.throwIfAborted();
+        const text = textOf(turn);
+        const toolCalls = this.toolCalls(turn);
+        return {
+            content: [...(text ? [{ type: 'text', text }] : []), ...toolCalls],
+            finishReason: finishOf(turn, toolCalls.length),
+            usage: usageOf(turn),
+            warnings: [],
+            response: { id: `response-${this.calls.length}`, modelId: this.modelId, timestamp: new Date(0) },
+        };
+    }
+    stream(turn, options) {
+        const text = textOf(turn);
+        const toolCalls = this.toolCalls(turn);
+        const parts = [
+            { type: 'stream-start', warnings: [] },
+            { type: 'response-metadata', id: `response-${this.calls.length}`, modelId: this.modelId, timestamp: new Date(0) },
+        ];
+        if (text) {
+            parts.push({ type: 'text-start', id: 'text-0' });
+            for (const delta of text.match(/\S+\s*|\s+/g) ?? []) {
+                parts.push({ type: 'text-delta', id: 'text-0', delta });
+            }
+            parts.push({ type: 'text-end', id: 'text-0' });
+        }
+        parts.push(...toolCalls);
+        if (turn.streamError !== undefined) {
+            parts.push({ type: 'error', error: turn.streamError });
+        }
+        else {
+            parts.push({ type: 'finish', finishReason: finishOf(turn, toolCalls.length), usage: usageOf(turn) });
+        }
+        const signal = options.abortSignal;
+        let index = 0;
+        return {
+            stream: new ReadableStream({
+                pull: async (controller) => {
+                    if (index > 0 && turn.chunkDelay) {
+                        try {
+                            await sleep(turn.chunkDelay, signal);
+                        }
+                        catch (error) {
+                            controller.error(error);
+                            return;
+                        }
+                    }
+                    if (signal?.aborted) {
+                        controller.error(signal.reason);
+                        return;
+                    }
+                    const part = parts[index++];
+                    if (part === undefined) {
+                        controller.close();
+                    }
+                    else {
+                        controller.enqueue(part);
+                        if (part.type === 'error') {
+                            controller.close();
+                        }
+                    }
+                },
+            }),
+        };
+    }
+    toolCalls(turn) {
+        return (turn.toolCalls ?? []).map((call) => ({
+            type: 'tool-call',
+            toolCallId: call.id ?? `call-${++this.toolCallCount}`,
+            toolName: call.name,
+            input: JSON.stringify(call.input ?? {}),
+        }));
+    }
+}
+/** `new FakeModel(answers)`. */
+export function fakeModel(...answers) {
+    return new FakeModel(answers);
+}
+/**
+ * A provider's HTTP error, as `@ai-sdk/*` providers throw it: retryable for 408, 409, 429 and 5xx. `retryAfter` (in
+ * seconds) is sent as a `retry-after` header.
+ */
+export function providerError(status, { message, retryAfter } = {}) {
+    return new APICallError({
+        message: message ?? `The provider answered ${status}`,
+        url: 'https://fake-provider.test/v1/messages',
+        requestBodyValues: {},
+        statusCode: status,
+        ...(retryAfter !== undefined && { responseHeaders: { 'retry-after': String(retryAfter) } }),
+    });
+}
+function textOf(turn) {
+    return turn.object !== undefined ? JSON.stringify(turn.object) : (turn.text ?? '');
+}
+function finishOf(turn, toolCalls) {
+    const unified = turn.finishReason ?? (toolCalls > 0 ? 'tool-calls' : 'stop');
+    return { unified, raw: unified };
+}
+function usageOf(turn) {
+    const input = turn.usage?.inputTokens ?? 10;
+    const output = turn.usage?.outputTokens ?? 10;
+    const cached = turn.usage?.cachedInputTokens ?? 0;
+    const reasoning = turn.usage?.reasoningTokens ?? 0;
+    return {
+        inputTokens: { total: input, noCache: input - cached, cacheRead: cached, cacheWrite: undefined },
+        outputTokens: { total: output, text: output - reasoning, reasoning },
+    };
+}
+function describeCall(options, stream) {
+    const prompt = options.prompt;
+    const system = prompt.filter((message) => message.role === 'system').map((message) => message.content);
+    const lastUser = [...prompt].reverse().find((message) => message.role === 'user');
+    const trailingTools = [];
+    for (let index = prompt.length - 1; index >= 0 && prompt[index].role === 'tool'; index--) {
+        trailingTools.unshift(prompt[index]);
+    }
+    return {
+        stream,
+        ...(system.length > 0 && { instructions: system.join('\n') }),
+        ...(lastUser && {
+            lastUserMessage: lastUser.content
+                .filter((part) => part.type === 'text')
+                .map((part) => part.text)
+                .join(''),
+        }),
+        toolResults: trailingTools.flatMap((message) => message.content
+            .filter((part) => part.type === 'tool-result')
+            .map((part) => ({ toolName: part.toolName, toolCallId: part.toolCallId, output: part.output?.value }))),
+        tools: (options.tools ?? []).map((tool) => tool.name),
+        options,
+    };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@nestjs/ai/testing`: a fake model, and helpers for tests of applications that use `AiModule`.
+ *
+ * ```ts
+ * const model = new FakeModel(['Your order ships tomorrow.']);
+ * const moduleRef = await overrideModels(Test.createTestingModule({ imports: [AppModule] }), { default: model }).compile();
+ * ```
+ */
+import type { INestApplicationContext } from '@nestjs/common';
+import type { TestingModuleBuilder } from '@nestjs/testing';
+import type { LanguageModel } from 'ai';
+import type { AiCaller } from '../interfaces/ai-tool.interface.js';
+export { FakeModel, fakeModel, providerError, type FakeAnswer, type FakeModelCall, type FakeToolCall, type FakeTurn } from './fake-model.js';
+/**
+ * Replaces configured models by name (`{ default: new FakeModel([...]) }`) in a testing module, keeping their other
+ * options (pricing, fallback, timeouts). A name that is not configured fails at compile time.
+ */
+export declare function overrideModels(builder: TestingModuleBuilder, models: Record<string, LanguageModel>): TestingModuleBuilder;
+/**
+ * Calls the agent function `name` with `input` as `caller`, as an agent's call does: the input validated by its
+ * schema, its scopes checked, then its guards, interceptors, pipes and filters, then the method. Resolves with what the
+ * model would read; rejects with the `AiToolError` it would read (a guard's `Forbidden resource`).
+ */
+export declare function callTool(app: INestApplicationContext, name: string, input?: unknown, { caller }?: {
+    caller?: AiCaller;
+}): Promise<unknown>;

package/dist/testing/index.js

@@ -0,0 +1,19 @@
+import { AI_MODEL_OVERRIDES } from '../ai.constants.js';
+import { AiTools } from '../tools/ai-tools.service.js';
+export { FakeModel, fakeModel, providerError } from './fake-model.js';
+/**
+ * Replaces configured models by name (`{ default: new FakeModel([...]) }`) in a testing module, keeping their other
+ * options (pricing, fallback, timeouts). A name that is not configured fails at compile time.
+ */
+export function overrideModels(builder, models) {
+    return builder.overrideProvider(AI_MODEL_OVERRIDES).useValue(models);
+}
+/**
+ * Calls the agent function `name` with `input` as `caller`, as an agent's call does: the input validated by its
+ * schema, its scopes checked, then its guards, interceptors, pipes and filters, then the method. Resolves with what the
+ * model would read; rejects with the `AiToolError` it would read (a guard's `Forbidden resource`).
+ */
+export async function callTool(app, name, input = {}, { caller } = {}) {
+    await app.init();
+    return app.get(AiTools, { strict: false }).call(name, input, caller);
+}

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

@@ -0,0 +1,77 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { DiscoveryService, ExternalContextCreator, MetadataScanner } from '@nestjs/core';
+import type { Schema, ToolSet } from 'ai';
+import type { AgentFunctionContext } from '../interfaces/agent-function.interface.js';
+import type { AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+import type { AiCaller, AiToolSelection } from '../interfaces/ai-tool.interface.js';
+/** A method behind Nest's enhancers: called as `(input, context)`. */
+export type AiToolHandler = (input: unknown, context: AgentFunctionContext) => Promise<unknown>;
+/** An agent function of the application: a provider method with `@AgentFunction()`, offered to models as a tool. */
+export interface AiToolEntry {
+    name: string;
+    description?: string;
+    scopes?: string[];
+    /** The `ai` schema of its arguments. */
+    inputSchema: Schema<unknown>;
+    handler: AiToolHandler;
+    /** The provider class it is a method of. */
+    host: Function;
+    /** `Class.method`, for messages. */
+    where: string;
+}
+/** An agent function's progress (`ctx.reportProgress()`), which a streamed answer sends as a transient data chunk. */
+export interface AiToolProgress {
+    toolCallId: string;
+    toolName: string;
+    progress: number;
+    total?: number;
+    message?: string;
+}
+/**
+ * The application's agent functions: the `@AgentFunction()` methods of its providers (or of the `include` modules),
+ * found once at startup, each wrapped by Nest's enhancers with the context type `'ai'`, and called with an
+ * `AgentFunctionContext`. `select()` turns some of them into `ai` tools for one caller.
+ */
+export declare class AiTools implements OnModuleInit {
+    private readonly discovery;
+    private readonly scanner;
+    private readonly options;
+    private readonly logger;
+    private readonly entries;
+    private readonly paramsFactory;
+    private readonly contextCreator;
+    private scanned;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner, externalContextCreator: ExternalContextCreator, options: AiModuleOptions);
+    onModuleInit(): void;
+    /** Every agent function, by name. */
+    get tools(): ReadonlyMap<string, AiToolEntry>;
+    /**
+     * `ai` tools for `names` (agent function names, or provider classes for all their agent functions), whose calls run
+     * as `caller`: what `AiService` calls pass the model, and what code that calls `ai` itself can pass `generateText()`.
+     */
+    select(selection: AiToolSelection, { caller, onExecute, onProgress, execute, }?: {
+        caller?: AiCaller;
+        /** @internal */
+        onExecute?: () => void;
+        /** @internal Where `ctx.reportProgress()` goes: a streamed answer. */
+        onProgress?: (progress: AiToolProgress) => void;
+        /** @internal `false`: the tools are offered to the model, and their calls returned, not run (durable runs). */
+        execute?: boolean;
+    }): ToolSet;
+    /**
+     * Runs the agent function `name` with `input` (validated by its schema) as `caller`, through its enhancers, as an
+     * agent's call does. Resolves with what the model would read; rejects with the `AiToolError` it would read.
+     */
+    call(entryOrName: AiToolEntry | string, input: unknown, caller?: AiCaller, options?: {
+        toolCallId?: string;
+        messages?: unknown[];
+        abortSignal?: AbortSignal;
+        idempotencyKey?: string;
+        onProgress?: (progress: AiToolProgress) => void;
+    }): Promise<unknown>;
+    /** The agent functions a selection names, each once, in order. Unknown names throw. */
+    resolve(selection: AiToolSelection): AiToolEntry[];
+    /** Finds the agent functions, once. */
+    scan(): void;
+    private known;
+}