nestjs-langchain 2.0.0 → 2.1.0

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.1.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",
@@ -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",
+    "@types/node": "^26.6.4",
     "@vitest/coverage-v8": "^4.1.11",
     "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",