nestjs-langchain 2.0.0 → 2.2.0

package/lib/output/run-output.ts

@@ -0,0 +1,154 @@
+import { toJsonSchema } from '@langchain/core/utils/json_schema';
+import {
+  MultipleStructuredOutputsError,
+  StructuredOutputParsingError,
+  toolStrategy,
+  TypedToolStrategy,
+} from 'langchain';
+import z, { ZodType } from 'zod';
+import { OUTPUT_TOOL } from '../constants.js';
+import { AgentRunError, StructuredOutputError } from '../errors/index.js';
+import {
+  agentPrefix,
+  noOutputJsonSchemaForm,
+  outputNotAnObject,
+  structuredOutputInvalid,
+  structuredOutputMissing,
+  structuredOutputMultiple,
+} from '../errors/messages.js';
+import { messageOf } from '../logging/index.js';
+
+// The default of LangChain's own retry middlewares. See #151.
+const MAX_RETRIES = 2;
+
+// LangChain's default for a Zod schema, which its JSON Schema path leaves
+// empty. See #282.
+const OUTPUT_DESCRIPTION =
+  "Tool for extracting structured output from the model's response.";
+
+/**
+ * The structured output one run asked for: the strategy its model calls use,
+ * and the answer parsed by the schema.
+ *
+ * @internal
+ */
+export class RunOutput {
+  /**
+   * Through a tool, whatever the model (see #274). One per run, which counts
+   * its own retries (see #151).
+   */
+  readonly strategy: TypedToolStrategy;
+  /** The tool the model answers through. */
+  readonly toolName = OUTPUT_TOOL;
+  #retries = 0;
+  private readonly prefix: string;
+
+  /**
+   * @param schema The run's `output` schema.
+   * @param agent The agent's name, for the errors.
+   * @throws AgentRunError when the schema has no JSON Schema form, or is not
+   * an object with named fields.
+   */
+  constructor(
+    private readonly schema: ZodType,
+    private readonly agent: string,
+  ) {
+    this.prefix = agentPrefix(agent);
+
+    // LangChain's own conversion, run before any model call.
+    let json: Record<string, unknown>;
+
+    try {
+      json = toJsonSchema(schema);
+    } catch (error) {
+      throw new AgentRunError(
+        noOutputJsonSchemaForm(this.prefix, messageOf(error)),
+        agent,
+        { cause: error },
+      );
+    }
+
+    // A tool's parameters. LangChain takes them as a JSON Schema with
+    // `properties` at every version, as a Zod schema other than an object at
+    // recent ones only. See #282.
+    if (json.type !== 'object' || !('properties' in json)) {
+      throw new AgentRunError(outputNotAnObject(this.prefix), agent);
+    }
+
+    // LangChain names the tool after the title.
+    this.strategy = toolStrategy(
+      {
+        ...json,
+        type: 'object',
+        title: OUTPUT_TOOL,
+        description: json.description ?? OUTPUT_DESCRIPTION,
+      },
+      { handleError: (error) => this.retry(error) },
+    );
+  }
+
+  // What LangChain sends back by default, until the retries run out.
+  private retry(error: Error): string {
+    this.#retries += 1;
+
+    if (this.#retries > MAX_RETRIES) {
+      throw error;
+    }
+
+    return error.message;
+  }
+
+  /**
+   * @param error What a model call threw.
+   * @returns A `StructuredOutputError` for LangChain's parsing failures, the
+   * error itself otherwise.
+   */
+  failure(error: unknown): unknown {
+    // Never LangChain's messages, which name the internal tool.
+    if (error instanceof StructuredOutputParsingError) {
+      return this.invalid(error.errors.join(' '), error);
+    }
+
+    if (error instanceof MultipleStructuredOutputsError) {
+      return new StructuredOutputError(
+        structuredOutputMultiple(this.prefix, error.toolNames.length),
+        this.agent,
+        { cause: error },
+      );
+    }
+
+    return error;
+  }
+
+  /**
+   * @param structuredResponse What the run left in `structuredResponse`.
+   * @returns The answer, as the schema parses it.
+   * @throws StructuredOutputError when the answer is missing or invalid.
+   */
+  read(structuredResponse: unknown): unknown {
+    if (structuredResponse === undefined) {
+      throw new StructuredOutputError(
+        structuredOutputMissing(this.prefix),
+        this.agent,
+      );
+    }
+
+    // LangChain checks the JSON Schema only: Zod also applies transforms and
+    // refinements. See #151.
+    const parsed = this.schema.safeParse(structuredResponse);
+
+    if (!parsed.success) {
+      throw this.invalid(z.prettifyError(parsed.error), parsed.error);
+    }
+
+    return parsed.data;
+  }
+
+  private invalid(reason: string, cause: unknown): StructuredOutputError {
+    return new StructuredOutputError(
+      structuredOutputInvalid(this.prefix, reason),
+      this.agent,
+      { cause },
+    );
+  }
+}

package/lib/output/structured-output.middleware.ts

@@ -0,0 +1,44 @@
+import { createMiddleware } from 'langchain';
+import { RunOutput } from './run-output.js';
+
+// The run's output travels under our own key in `configurable`, which
+// LangGraph keeps out of the trace metadata and checkpoints. See #151.
+const OUTPUT_KEY = 'nestjs-langchain:output';
+
+/**
+ * The `configurable` entry that hands a run's output to the middleware. A
+ * text run sets it to `null`, or it would inherit the output of the run it is
+ * nested in, which LangChain hands down. See #295.
+ *
+ * @internal
+ * @param output The run's output, if it asked for one.
+ * @returns The entry to put in `configurable`.
+ */
+export const outputConfig = (output: RunOutput | undefined) => ({
+  [OUTPUT_KEY]: output ?? null,
+});
+
+/**
+ * Sets the `responseFormat` of each model call of a run that asked for an
+ * `output`, so that one compiled agent serves text and structured runs.
+ * LangChain's parsing failures come out as a `StructuredOutputError`.
+ *
+ * @internal
+ */
+export const structuredOutput = () =>
+  createMiddleware({
+    name: 'structuredOutput',
+    wrapModelCall: async (request, handler) => {
+      const output = request.runtime.configurable?.[OUTPUT_KEY];
+
+      if (!(output instanceof RunOutput)) {
+        return handler(request);
+      }
+
+      try {
+        return await handler({ ...request, responseFormat: output.strategy });
+      } catch (error) {
+        throw output.failure(error);
+      }
+    },
+  });

package/lib/run/answered-calls.util.ts

@@ -0,0 +1,16 @@
+/**
+ * The ids of the tool calls the messages answer: the tool node answers every
+ * call it runs. Structural rather than `BaseMessage`. See #52.
+ *
+ * @internal
+ * @param messages A run's messages.
+ * @returns The ids their `tool_call_id`s answer.
+ */
+export const answeredCalls = (messages: readonly object[]): Set<string> =>
+  new Set(
+    messages.flatMap((message) =>
+      'tool_call_id' in message && typeof message.tool_call_id === 'string'
+        ? [message.tool_call_id]
+        : [],
+    ),
+  );

package/lib/run/index.ts

@@ -1,2 +1,5 @@
+export { answeredCalls } from './answered-calls.util.js';
+export { isRecursionLimit } from './recursion-limit.util.js';
 export { summariseRun } from './run-summary.util.js';
+export { UsageAside } from './usage-aside.js';
 export type { RunSummary } from './run-summary.util.js';

package/lib/run/recursion-limit.util.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether a `recursionLimit` is one LangGraph applies: it rejects a limit
+ * below 1, but runs on with `NaN`. See #194.
+ *
+ * @internal
+ * @param limit The option as given, from untyped JavaScript too.
+ * @returns `true` for an integer of at least 1, or no limit.
+ */
+export const isRecursionLimit = (limit: unknown): boolean =>
+  limit === undefined ||
+  (typeof limit === 'number' && Number.isInteger(limit) && limit >= 1);

package/lib/run/run-summary.util.ts

@@ -1,14 +1,19 @@
 import { mergeUsageMetadata, UsageMetadata } from '@langchain/core/messages';
+import { answeredCalls } from './answered-calls.util.js';
 
 // Structural rather than `BaseMessage`. See #52.
 interface MessageLike {
   usage_metadata?: UsageMetadata;
-  tool_calls?: { name: string }[];
+  tool_calls?: { name: string; id?: string }[];
+  tool_call_id?: string;
 }
 
 /** What a run did and cost. */
 export interface RunSummary {
-  /** Every tool call the model made, failed and unknown ones included. */
+  /**
+   * Every tool call that reached the agent's tools, failed and unknown ones
+   * included, but not the one returning a structured output.
+   */
   tools: string[];
   /**
    * Summed over the run's model calls; absent when the provider reports no
@@ -22,16 +27,33 @@ export interface RunSummary {
  *
  * @internal
  * @param messages The messages of the finished run.
- * @returns The tool calls the model made, and the tokens if reported.
+ * @param outputTool The tool the model returned a structured output through.
+ * @param aside The usage of the replies the run left out of its messages.
+ * @returns The tool calls that reached the tools, and the tokens if reported.
  */
-export const summariseRun = (messages: readonly MessageLike[]): RunSummary => {
-  const tools = messages.flatMap((message) =>
-    (message.tool_calls ?? []).map((call) => call.name),
-  );
-
-  const reported = messages
-    .map((message) => message.usage_metadata)
-    .filter((usage) => usage !== undefined);
+export const summariseRun = (
+  messages: readonly MessageLike[],
+  outputTool?: string,
+  aside: readonly UsageMetadata[] = [],
+): RunSummary => {
+  // One that did not run has no answer (see #290). One with no id cannot be
+  // told, and counts (see #295).
+  const answered = answeredCalls(messages);
+
+  const tools = messages
+    .flatMap((message) => message.tool_calls ?? [])
+    .filter(
+      ({ name, id }) =>
+        name !== outputTool && (id === undefined || answered.has(id)),
+    )
+    .map((call) => call.name);
+
+  const reported = [
+    ...messages
+      .map((message) => message.usage_metadata)
+      .filter((usage) => usage !== undefined),
+    ...aside,
+  ];
 
   if (reported.length === 0) {
     return { tools };

package/lib/run/usage-aside.ts

@@ -0,0 +1,41 @@
+import { UsageMetadata } from '@langchain/core/messages';
+
+// Our own key in `configurable`, like the run's output. See #296.
+const USAGE_ASIDE_KEY = 'nestjs-langchain:usage-aside';
+
+/**
+ * The usage of the model's replies a run leaves out of its messages, which its
+ * `tokens` still count: those the `unknownTools` re-ask asks again about. One
+ * per run, handed to the middlewares in `configurable`. See #296.
+ *
+ * @internal
+ */
+export class UsageAside {
+  readonly usage: UsageMetadata[] = [];
+
+  /** The `configurable` entry that hands it to the middlewares. */
+  get config(): Record<string, UsageAside> {
+    return { [USAGE_ASIDE_KEY]: this };
+  }
+
+  /**
+   * @param usage A left-out reply's usage, when the provider reported it.
+   */
+  add(usage: UsageMetadata | undefined): void {
+    if (usage) {
+      this.usage.push(usage);
+    }
+  }
+
+  /**
+   * @param configurable A middleware's `runtime.configurable`.
+   * @returns The run's aside, when it set one.
+   */
+  static of(
+    configurable: Record<string, unknown> | undefined,
+  ): UsageAside | undefined {
+    const aside = configurable?.[USAGE_ASIDE_KEY];
+
+    return aside instanceof UsageAside ? aside : undefined;
+  }
+}

package/lib/tools/tool-errors.middleware.ts

@@ -1,10 +1,33 @@
+import {
+  AIMessage,
+  BaseMessage,
+  ToolCall,
+  ToolMessage,
+} from '@langchain/core/messages';
 import {
   createMiddleware,
   toolErrorMiddleware,
   ToolInvocationError,
 } from 'langchain';
-import { unknownTool } from '../errors/messages.js';
+import { OUTPUT_TOOL, STRUCTURED_OUTPUT_PREFIX } from '../constants.js';
+import { invalidTool, toolNotRun, unknownTool } from '../errors/messages.js';
 import { reportToolError, RunReporter } from '../logging/index.js';
+import { answeredCalls, UsageAside } from '../run/index.js';
+
+// The default of LangChain's own retry middlewares. See #151.
+const MAX_REASKS = 2;
+
+// LangChain routes every `extract-` call to structured output, never to the
+// tools: one the model invents, which is not the run's output, neither runs
+// nor gets an answer. See #264.
+const isInvented = ({ name }: ToolCall): boolean =>
+  name.startsWith(STRUCTURED_OUTPUT_PREFIX) && name !== OUTPUT_TOOL;
+
+const invented = (calls: readonly ToolCall[]): ToolCall[] =>
+  calls.filter(isInvented);
+
+const callsOf = (message: BaseMessage | undefined): ToolCall[] =>
+  AIMessage.isInstance(message) ? (message.tool_calls ?? []) : [];
 
 /**
  * Turns a failed tool call into the text the model receives, LangChain's own,
@@ -48,21 +71,92 @@ export const toolErrors = (reporter: RunReporter) =>
 /**
  * Reports a call to a tool the agent does not have. LangChain's tool node
  * answers the model itself, without throwing, so `toolErrors` never sees it.
+ * One the model invents with the `extract-` prefix never reaches the tool
+ * node: it is answered here, as the tool node answers any other, and so is
+ * any call LangChain leaves unanswered.
+ *
+ * @param reporter The agent's reporter.
+ * @param tools The names of the agent's tools, which the answer lists.
  */
-export const unknownTools = (reporter: RunReporter) =>
-  createMiddleware({
+export const unknownTools = (reporter: RunReporter, tools: string[]) => {
+  const report = ({ name, id }: ToolCall) =>
+    reportToolError(reporter, {
+      tool: name,
+      callId: id ?? '',
+      reason: 'unknown-tool',
+      error: new Error(unknownTool()),
+      durationMs: 0,
+    });
+
+  const answer = (call: ToolCall) =>
+    new ToolMessage({
+      content: isInvented(call)
+        ? invalidTool(call.name, tools)
+        : toolNotRun(call.name),
+      tool_call_id: call.id ?? '',
+      name: call.name,
+      status: 'error',
+    });
+
+  // Every call without an answer gets one right after its message, which
+  // providers require: an invented one (see #264), or one LangChain left out
+  // next to the output (see #290). In the request, which the output's retry
+  // reaches without `beforeModel`; rebuilt on every model call, so only the
+  // reply just made is reported. See #297.
+  const answerLeft = (messages: BaseMessage[]): BaseMessage[] => {
+    const done = answeredCalls(messages);
+    const left = (message: BaseMessage | undefined) =>
+      callsOf(message).filter(({ id }) => id !== undefined && !done.has(id));
+
+    invented(left(messages.findLast((m) => AIMessage.isInstance(m)))).forEach(
+      report,
+    );
+
+    return messages.flatMap((message) => [
+      message,
+      ...left(message).map(answer),
+    ]);
+  };
+
+  return createMiddleware({
     name: 'unknownTools',
+    // Alone, LangChain would end the run: answered, and the model asked again,
+    // as `modelRetryMiddleware` asks it again. See #264.
+    wrapModelCall: async (request, handler) => {
+      let current = { ...request, messages: answerLeft(request.messages) };
+
+      for (let asked = 0; ; asked += 1) {
+        const reply = await handler(current);
+        const calls = callsOf(reply);
+        const left = invented(calls);
+
+        if (calls.length === 0 || left.length < calls.length) {
+          return reply;
+        }
+
+        left.forEach(report);
+
+        if (asked === MAX_REASKS) {
+          return reply;
+        }
+
+        // Left out of the run's messages, but paid for. See #296.
+        UsageAside.of(request.runtime.configurable)?.add(
+          AIMessage.isInstance(reply) ? reply.usage_metadata : undefined,
+        );
+
+        current = {
+          ...current,
+          messages: [...current.messages, reply, ...left.map(answer)],
+        };
+      }
+    },
     wrapToolCall: (request, handler) => {
       if (!request.tool) {
-        reportToolError(reporter, {
-          tool: request.toolCall.name,
-          callId: request.toolCall.id ?? '',
-          reason: 'unknown-tool',
-          error: new Error(unknownTool()),
-          durationMs: 0,
-        });
+        report(request.toolCall);
       }
 
       return handler(request);
     },
   });
+};

package/lib/tools/tool-name.util.ts

@@ -1,3 +1,4 @@
+import { STRUCTURED_OUTPUT_PREFIX } from '../constants.js';
 import {
   duplicateToolName,
   invalidToolName,
@@ -8,10 +9,6 @@ import {
 // it. See #90.
 const TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
 
-// The agent routes a call with this prefix to structured output, never to the
-// tool. Restated: LangChain does not export it. See #213.
-const STRUCTURED_OUTPUT_PREFIX = 'extract-';
-
 export const resolveToolName = (
   declared: string | undefined,
   method: string,

package/package.json

@@ -1,13 +1,32 @@
 {
   "name": "nestjs-langchain",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "type": "module",
-  "description": "NestJS library to build agents with LangChain",
+  "description": "AI agents for NestJS, powered by LangChain: declare agents as modules, give them your services as tools.",
   "keywords": [
     "nestjs",
+    "nest",
+    "nestjs-module",
     "langchain",
+    "langchainjs",
+    "ai",
+    "agent",
     "agents",
-    "ai"
+    "ai-agent",
+    "ai-agents",
+    "llm",
+    "tools",
+    "tool-calling",
+    "function-calling",
+    "structured-output",
+    "openai",
+    "anthropic",
+    "mistral",
+    "gemini",
+    "ollama",
+    "zod",
+    "decorators",
+    "typescript"
   ],
   "author": "Martin Bruel",
   "license": "MIT",
@@ -51,7 +70,7 @@
     "format": "prettier --write \"{lib,tests,scripts}/**/*.{ts,mjs}\" vitest.config.ts",
     "lint": "oxlint --type-aware lib/ tests/ scripts/ vitest.config.ts --fix",
     "lint:check": "oxlint --type-aware lib/ tests/ scripts/ vitest.config.ts",
-    "test": "vitest run --typecheck",
+    "test": "vitest run && tsc --noEmit",
     "test:watch": "vitest",
     "release": "release-it",
     "release:rc": "release-it --preRelease=rc --no-plugins.@release-it/conventional-changelog.infile",
@@ -64,20 +83,20 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@commitlint/cli": "21.2.3",
+    "@commitlint/cli": "21.2.4",
     "@commitlint/config-conventional": "^21.2.3",
     "@langchain/core": "^1.2.3",
     "@langchain/openai": "^1.2.10",
-    "@nestjs/common": "^11.1.18",
-    "@nestjs/core": "^11.1.18",
-    "@nestjs/testing": "^11.1.18",
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/core": "^12.0.1",
+    "@nestjs/testing": "^12.0.1",
     "@release-it/conventional-changelog": "12.0.2",
-    "@types/node": "^25.1.0",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@types/node": "^26.6.4",
+    "@vitest/coverage-v8": "^5.0.5",
     "eslint-plugin-jsdoc": "^65.2.0",
     "husky": "9.1.7",
     "langchain": "^1.5.4",
-    "lint-staged": "16.4.0",
+    "lint-staged": "17.6.0",
     "oxlint": "^1.83.0",
     "oxlint-tsgolint": "^7.0.2001",
     "prettier": "^3.8.1",
@@ -88,7 +107,7 @@
     "rxjs": "^7.8.2",
     "semver": "^7.8.5",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11",
+    "vitest": "^5.0.5",
     "zod": "^4.0.0"
   },
   "peerDependencies": {