@nestjs/ai 0.0.0-stage → 0.0.2

package/dist/runtime/steps.d.ts

@@ -0,0 +1,32 @@
+import { type ModelMessage, type Schema, type UIMessageChunk } from 'ai';
+import type { AiStep } from '../interfaces/ai-result.interface.js';
+import type { StepAttempt } from './model-policy.js';
+import type { CallPlan } from './call-plan.js';
+/** One model call's outcome, as the loop reads it. */
+export interface StepOutcome {
+    step: Omit<AiStep, 'attempts'>;
+    /** The assistant (and tool) messages the step added to the conversation. */
+    responseMessages: ModelMessage[];
+    /** The parsed answer, for structured output on a final step. */
+    output?: unknown;
+    durationMs: number;
+}
+/** Structured output: the `ai` schema of the answer, with its name and description. */
+export interface StepOutput {
+    schema: Schema<unknown>;
+    name?: string;
+    description?: string;
+}
+/** Whether the loop goes on after a step: the model asked for tools, and they ran. */
+export declare function wantsAnotherStep(outcome: StepOutcome): boolean;
+/** One model call with `generateText()`: its tool calls run inside it. */
+export declare function generateStep(plan: CallPlan, index: number, messages: ModelMessage[], attempt: StepAttempt, output?: StepOutput): Promise<StepOutcome>;
+/**
+ * One model call with `streamText()`, its UI message chunks sent with `attempt.emit()` as they come. Until the first
+ * chunk with content arrives the attempt can still fail and be retried: the chunks before it (`start`, `start-step`)
+ * are held. The first one sent commits the attempt, and a failure after it is final. The step's `finish` chunk is
+ * held for the loop, which writes one when the last step ends.
+ */
+export declare function streamStep(plan: CallPlan, index: number, messages: ModelMessage[], attempt: StepAttempt): Promise<StepOutcome & {
+    finish?: UIMessageChunk;
+}>;

package/dist/runtime/steps.js

@@ -0,0 +1,190 @@
+import { generateText, NoObjectGeneratedError, Output, streamText } from 'ai';
+import { AiOutputError, AiToolError } from '../errors/ai.errors.js';
+import { costOf, toUsage } from '../utils/usage.util.js';
+/** Whether the loop goes on after a step: the model asked for tools, and they ran. */
+export function wantsAnotherStep(outcome) {
+    return outcome.step.finishReason === 'tool-calls' && outcome.step.toolResults.length > 0;
+}
+function callSettings(plan, model, messages, attempt, output) {
+    return {
+        model: model.model,
+        ...(plan.instructions !== undefined && { instructions: plan.instructions }),
+        messages,
+        ...(plan.tools && { tools: plan.tools }),
+        ...(plan.toolChoice !== undefined && { toolChoice: plan.toolChoice }),
+        ...(output && {
+            output: Output.object({
+                schema: output.schema,
+                ...(output.name !== undefined && { name: output.name }),
+                ...(output.description !== undefined && { description: output.description }),
+            }),
+        }),
+        ...plan.settingsFor(model),
+        // Retries are the call's resilience policies'.
+        maxRetries: 0,
+        abortSignal: attempt.signal,
+    };
+}
+/** One model call with `generateText()`: its tool calls run inside it. */
+export async function generateStep(plan, index, messages, attempt, output) {
+    const started = performance.now();
+    // A tool that starts commits the attempt (`onExecute`): another attempt would run it again.
+    plan.running = attempt;
+    let result;
+    try {
+        result = await generateText(callSettings(plan, attempt.model, messages, attempt, output));
+    }
+    catch (error) {
+        // The model answered, and its answer is not the object: no retry or other model is tried.
+        if (output && NoObjectGeneratedError.isInstance(error)) {
+            throw toOutputError(error, error.text ?? '');
+        }
+        throw error;
+    }
+    finally {
+        plan.running = undefined;
+    }
+    const outcome = {
+        step: describeStep(index, attempt.model, {
+            text: result.text,
+            content: result.content,
+            finishReason: result.finishReason,
+            usage: result.usage,
+        }),
+        responseMessages: [...result.responseMessages],
+        durationMs: performance.now() - started,
+    };
+    if (output && !wantsAnotherStep(outcome)) {
+        try {
+            outcome.output = result.output;
+        }
+        catch (error) {
+            throw toOutputError(error, result.text);
+        }
+    }
+    return outcome;
+}
+/** An answer that is not JSON, or does not match the schema. */
+function toOutputError(error, text) {
+    const cause = error?.cause ?? error;
+    return new AiOutputError(`The model's answer does not match the schema: ${cause?.message ?? String(cause)}`, text, { cause: error });
+}
+/**
+ * One model call with `streamText()`, its UI message chunks sent with `attempt.emit()` as they come. Until the first
+ * chunk with content arrives the attempt can still fail and be retried: the chunks before it (`start`, `start-step`)
+ * are held. The first one sent commits the attempt, and a failure after it is final. The step's `finish` chunk is
+ * held for the loop, which writes one when the last step ends.
+ */
+export async function streamStep(plan, index, messages, attempt) {
+    const emit = (chunk) => attempt.emit(chunk);
+    plan.running = attempt;
+    try {
+        return await streamAttempt(plan, index, messages, attempt, emit);
+    }
+    finally {
+        plan.running = undefined;
+    }
+}
+async function streamAttempt(plan, index, messages, attempt, emit) {
+    const started = performance.now();
+    let failure;
+    const result = streamText({
+        ...callSettings(plan, attempt.model, messages, attempt),
+        // Errors are read from the chunks; `ai` would log them to the console.
+        onError: () => { },
+    });
+    const chunks = result.toUIMessageStream({
+        sendStart: index === 0,
+        sendFinish: true,
+        onError: (error) => {
+            // A tool's error is what the model was told; anything else is the stream's failure.
+            if (error instanceof AiToolError) {
+                return error.message;
+            }
+            failure = error;
+            return 'An error occurred.';
+        },
+    });
+    const held = [];
+    let opened = false;
+    let finish;
+    const reader = chunks.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (value.type === 'error') {
+                // `failure` was set by `onError` for this chunk.
+                throw failure ?? new Error(value.errorText);
+            }
+            if (value.type === 'abort') {
+                attempt.signal.throwIfAborted();
+                continue;
+            }
+            if (value.type === 'finish') {
+                finish = value;
+                continue;
+            }
+            if (!opened && (value.type === 'start' || value.type === 'start-step')) {
+                held.push(value);
+                continue;
+            }
+            if (!opened) {
+                opened = true;
+                held.splice(0).forEach(emit);
+            }
+            emit(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    attempt.signal.throwIfAborted();
+    if (!opened) {
+        // An empty answer (no content at all): what it held still opens the message.
+        held.splice(0).forEach(emit);
+    }
+    const [text, content, finishReason, usage, responseMessages] = await Promise.all([
+        result.text,
+        result.content,
+        result.finishReason,
+        result.usage,
+        result.responseMessages,
+    ]);
+    return {
+        step: describeStep(index, attempt.model, { text, content, finishReason, usage }),
+        responseMessages: [...responseMessages],
+        durationMs: performance.now() - started,
+        ...(finish && { finish }),
+    };
+}
+function describeStep(index, model, result) {
+    const toolCalls = [];
+    const toolResults = [];
+    for (const part of result.content) {
+        const call = { toolCallId: part.toolCallId ?? '', toolName: part.toolName ?? '', input: part.input };
+        if (part.type === 'tool-call') {
+            toolCalls.push(call);
+        }
+        else if (part.type === 'tool-result') {
+            toolResults.push({ ...call, output: part.output });
+        }
+        else if (part.type === 'tool-error') {
+            toolResults.push({ ...call, error: String(part.error) });
+        }
+    }
+    const usage = toUsage(result.usage);
+    const cost = costOf(usage, model.pricing);
+    return {
+        index,
+        model: model.info,
+        text: result.text,
+        toolCalls,
+        toolResults,
+        finishReason: result.finishReason,
+        usage,
+        ...(cost !== undefined && { cost }),
+    };
+}

package/dist/runtime/text-stream.d.ts

@@ -0,0 +1,64 @@
+import { type FinishReason, type ModelMessage, type UIMessageChunk } from 'ai';
+import type { Duration } from '@nestjs/resilience';
+import type { AiStep, AiTextResult } from '../interfaces/ai-result.interface.js';
+import type { AiUsage } from '../interfaces/ai-usage.interface.js';
+/** What the browser is told about a failure. Default: `An error occurred.`, so that no server detail leaks. */
+export interface AiUIMessageStreamOptions {
+    errorText?: (error: unknown) => string;
+}
+export interface AiStreamResponseOptions extends AiUIMessageStreamOptions {
+    /** Default 200. */
+    status?: number;
+    headers?: Record<string, string>;
+    /**
+     * A comment line (`: keep-alive`) sent after this long without a chunk, while a tool runs or the model thinks, so
+     * that proxies and load balancers do not close the connection as idle. Default `'15s'`; `false` for none.
+     */
+    keepAlive?: Duration | false;
+}
+/**
+ * A streamed answer: `streamText()`'s result. The call runs once, from the moment it is made, whatever reads it: the
+ * UI message stream (`toUIMessageStream()`, `pipeUIMessageStreamToResponse()`), the text (`textStream`,
+ * `pipeTextStreamToResponse()`), or the promises, which settle when the call ends. Each reader gets the whole
+ * stream from its start. A reader that cancels (a browser that goes away) aborts the call.
+ */
+export declare class AiTextStream {
+    private readonly controller;
+    /** Everything about the call, when it ends; rejects with its error. */
+    readonly result: Promise<AiTextResult>;
+    private readonly entries;
+    private readonly waiting;
+    private ended;
+    /** Settles with the first chunk, or with the call's error when it fails before one. */
+    private readonly opened;
+    /** @internal */
+    constructor(controller: AbortController, produce: (emit: (chunk: UIMessageChunk) => void) => Promise<AiTextResult>);
+    get text(): Promise<string>;
+    get usage(): Promise<AiUsage>;
+    get steps(): Promise<AiStep[]>;
+    get finishReason(): Promise<FinishReason>;
+    get responseMessages(): Promise<ModelMessage[]>;
+    /** The text as it is generated, over every step. Throws the call's error. */
+    get textStream(): AsyncIterable<string>;
+    /**
+     * The AI SDK's UI message stream: what `useChat()` reads. One message: `start`, each step's chunks (text, tool
+     * calls and their results), `finish`; or an `error` chunk when the call fails.
+     */
+    toUIMessageStream({ errorText }?: AiUIMessageStreamOptions): ReadableStream<UIMessageChunk>;
+    /** The UI message stream as a web-standard `Response` (server-sent events). */
+    toUIMessageStreamResponse({ status, headers, keepAlive, ...options }?: AiStreamResponseOptions): Response;
+    /**
+     * Sends the UI message stream to the browser, as server-sent events, on the response `@Res()` injects (Express,
+     * Fastify or the Node adapter). Resolves when the stream has been sent. A call that fails before its first chunk
+     * rejects instead, with nothing sent, so the route's exception filters answer it.
+     */
+    pipeUIMessageStreamToResponse(response: unknown, options?: AiStreamResponseOptions): Promise<void>;
+    /** Sends the text alone, as `text/plain` chunks; a failure after the first chunk ends the response early. */
+    pipeTextStreamToResponse(response: unknown, { status, headers }?: Omit<AiStreamResponseOptions, 'errorText' | 'keepAlive'>): Promise<void>;
+    /** Aborts the call: the model call in flight and the tools running. */
+    abort(reason?: unknown): void;
+    private send;
+    /** Every entry from the first, then the new ones as they come, until the call ends. */
+    private read;
+    private wakeAll;
+}

package/dist/runtime/text-stream.js

@@ -0,0 +1,211 @@
+import { createTextStreamResponse, createUIMessageStreamResponse } from 'ai';
+import { withKeepAlive } from '../http/keep-alive.util.js';
+import { toNodeResponse, writeWebResponse } from '../http/node-response.util.js';
+import { toMilliseconds } from '../utils/duration.util.js';
+const DEFAULT_KEEP_ALIVE_MS = 15_000;
+const DEFAULT_ERROR_TEXT = 'An error occurred.';
+/**
+ * A streamed answer: `streamText()`'s result. The call runs once, from the moment it is made, whatever reads it: the
+ * UI message stream (`toUIMessageStream()`, `pipeUIMessageStreamToResponse()`), the text (`textStream`,
+ * `pipeTextStreamToResponse()`), or the promises, which settle when the call ends. Each reader gets the whole
+ * stream from its start. A reader that cancels (a browser that goes away) aborts the call.
+ */
+export class AiTextStream {
+    /** @internal */
+    constructor(controller, produce) {
+        this.controller = controller;
+        this.entries = [];
+        this.waiting = new Set();
+        this.ended = false;
+        let open;
+        let fail;
+        this.opened = new Promise((resolve, reject) => {
+            open = resolve;
+            fail = reject;
+        });
+        const push = (entry) => {
+            this.entries.push(entry);
+            for (const wake of this.waiting) {
+                wake();
+            }
+            this.waiting.clear();
+        };
+        const emit = (chunk) => {
+            if (!this.ended) {
+                push({ chunk });
+                open();
+            }
+        };
+        this.result = Promise.resolve()
+            .then(() => produce(emit))
+            .then((result) => {
+            this.ended = true;
+            open();
+            this.wakeAll();
+            return result;
+        }, (error) => {
+            push({ error });
+            this.ended = true;
+            fail(error);
+            this.wakeAll();
+            throw error;
+        });
+        // Rejections are the readers' to handle: an unread stream must not crash the process.
+        this.result.catch(() => { });
+        this.opened.catch(() => { });
+    }
+    get text() {
+        return this.result.then((result) => result.text);
+    }
+    get usage() {
+        return this.result.then((result) => result.usage);
+    }
+    get steps() {
+        return this.result.then((result) => result.steps);
+    }
+    get finishReason() {
+        return this.result.then((result) => result.finishReason);
+    }
+    get responseMessages() {
+        return this.result.then((result) => result.responseMessages);
+    }
+    /** The text as it is generated, over every step. Throws the call's error. */
+    get textStream() {
+        const entries = this.read();
+        return {
+            [Symbol.asyncIterator]: async function* () {
+                for await (const entry of entries) {
+                    if ('error' in entry) {
+                        throw entry.error;
+                    }
+                    if (entry.chunk.type === 'text-delta') {
+                        yield entry.chunk.delta;
+                    }
+                }
+            },
+        };
+    }
+    /**
+     * The AI SDK's UI message stream: what `useChat()` reads. One message: `start`, each step's chunks (text, tool
+     * calls and their results), `finish`; or an `error` chunk when the call fails.
+     */
+    toUIMessageStream({ errorText = () => DEFAULT_ERROR_TEXT } = {}) {
+        const entries = this.read()[Symbol.asyncIterator]();
+        return new ReadableStream({
+            pull: async (controller) => {
+                const next = await entries.next();
+                if (next.done) {
+                    controller.close();
+                }
+                else if ('error' in next.value) {
+                    controller.enqueue({ type: 'error', errorText: safely(errorText, next.value.error) });
+                }
+                else {
+                    controller.enqueue(next.value.chunk);
+                }
+            },
+            cancel: () => this.abort(),
+        });
+    }
+    /** The UI message stream as a web-standard `Response` (server-sent events). */
+    toUIMessageStreamResponse({ status, headers, keepAlive, ...options } = {}) {
+        const response = createUIMessageStreamResponse({
+            stream: this.toUIMessageStream(options),
+            ...(status !== undefined && { status }),
+            ...(headers && { headers }),
+        });
+        const interval = keepAlive === false ? undefined : toMilliseconds(keepAlive ?? DEFAULT_KEEP_ALIVE_MS, 'keepAlive');
+        if (!interval || !response.body) {
+            return response;
+        }
+        return new Response(withKeepAlive(response.body, interval), {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    }
+    /**
+     * Sends the UI message stream to the browser, as server-sent events, on the response `@Res()` injects (Express,
+     * Fastify or the Node adapter). Resolves when the stream has been sent. A call that fails before its first chunk
+     * rejects instead, with nothing sent, so the route's exception filters answer it.
+     */
+    async pipeUIMessageStreamToResponse(response, options = {}) {
+        await this.send(response, () => this.toUIMessageStreamResponse(options));
+    }
+    /** Sends the text alone, as `text/plain` chunks; a failure after the first chunk ends the response early. */
+    async pipeTextStreamToResponse(response, { status, headers } = {}) {
+        const text = this.textStream[Symbol.asyncIterator]();
+        await this.send(response, () => createTextStreamResponse({
+            stream: new ReadableStream({
+                pull: async (controller) => {
+                    const next = await text.next();
+                    if (next.done) {
+                        controller.close();
+                    }
+                    else {
+                        controller.enqueue(next.value);
+                    }
+                },
+                cancel: () => this.abort(),
+            }),
+            ...(status !== undefined && { status }),
+            ...(headers && { headers }),
+        }));
+    }
+    /** Aborts the call: the model call in flight and the tools running. */
+    abort(reason) {
+        this.controller.abort(reason ?? new DOMException('The stream was cancelled', 'AbortError'));
+    }
+    async send(platformResponse, create) {
+        const node = toNodeResponse(platformResponse);
+        const gone = () => {
+            if (!node.res.writableFinished) {
+                this.abort();
+            }
+        };
+        node.res.once('close', gone);
+        try {
+            await this.opened;
+        }
+        catch (error) {
+            node.res.off('close', gone);
+            throw error;
+        }
+        node.open();
+        await writeWebResponse(create(), node.res);
+    }
+    /** Every entry from the first, then the new ones as they come, until the call ends. */
+    read() {
+        return {
+            [Symbol.asyncIterator]: async function* () {
+                let position = 0;
+                for (;;) {
+                    if (position < this.entries.length) {
+                        yield this.entries[position++];
+                        continue;
+                    }
+                    if (this.ended) {
+                        return;
+                    }
+                    await new Promise((resolve) => {
+                        this.waiting.add(resolve);
+                    });
+                }
+            }.bind(this),
+        };
+    }
+    wakeAll() {
+        for (const wake of this.waiting) {
+            wake();
+        }
+        this.waiting.clear();
+    }
+}
+function safely(errorText, error) {
+    try {
+        return errorText(error);
+    }
+    catch {
+        return DEFAULT_ERROR_TEXT;
+    }
+}

package/dist/services/ai.service.d.ts

@@ -0,0 +1,70 @@
+import { ModuleRef } from '@nestjs/core';
+import type { ModelMessage } from 'ai';
+import type { AiCallOptions, AiObjectCallOptions } from '../interfaces/ai-call-options.interface.js';
+import type { AiEmbedOptions, AiEmbedManyOptions, AiEmbedResult, AiEmbedManyResult } from '../interfaces/ai-embedding.interface.js';
+import type { AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+import type { AiObjectResult, AiTextResult } from '../interfaces/ai-result.interface.js';
+import type { AiSchema, InferSchemaOutput } from '../interfaces/ai-schema.interface.js';
+import { AiModels } from '../models/ai-models.service.js';
+import { AiEmbeddingModels } from '../models/ai-embedding-models.service.js';
+import { type StepOutcome } from '../runtime/steps.js';
+import { AiTextStream } from '../runtime/text-stream.js';
+import { AiTools } from '../tools/ai-tools.service.js';
+/**
+ * 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: ...' });
+ * ```
+ */
+export declare class AiService {
+    private readonly models;
+    private readonly tools;
+    private readonly options;
+    private readonly moduleRef;
+    private readonly embeddingModels;
+    private readonly logger;
+    constructor(models: AiModels, tools: AiTools, options: AiModuleOptions, moduleRef: ModuleRef, embeddingModels: AiEmbeddingModels);
+    /**
+     * Embeds one string, with the embedding model's settings, Nest policies and embedding usage
+     * events.
+     */
+    embed(options: AiEmbedOptions): Promise<AiEmbedResult>;
+    /**
+     * Embeds strings in input order; the SDK batches requests, with bounded concurrency (default 4).
+     * Timeouts, retries and policies apply to each request.
+     */
+    embedMany(options: AiEmbedManyOptions): Promise<AiEmbedManyResult>;
+    /** Generates text; with `tools`, calls them as the model asks, and answers when it is done. */
+    generateText(options: AiCallOptions): Promise<AiTextResult>;
+    /**
+     * 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.
+     */
+    generateObject<S extends AiSchema>(options: AiObjectCallOptions<S>): Promise<AiObjectResult<InferSchemaOutput<S>>>;
+    /**
+     * 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: AiCallOptions): AiTextStream;
+    /**
+     * @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.
+     */
+    callModel(options: AiCallOptions, { index, messages, signal }: {
+        index: number;
+        messages: ModelMessage[];
+        signal: AbortSignal;
+    }): Promise<{
+        outcome: StepOutcome;
+        attempts: number;
+    }>;
+    private plan;
+    /** A preset of the application's `ResilienceService`, which `ResilienceModule.forRoot({ presets })` configures. */
+    private preset;
+    /** Calls the usage listeners. They never fail the call: what they throw is logged. */
+    private report;
+    private logListenerError;
+}