nestjs-langchain 1.0.2 → 2.0.0

package/lib/tools/tool-discovery.service.ts

@@ -0,0 +1,191 @@
+import { Injectable, Scope, Type } from '@nestjs/common';
+// From `langchain`, not `@langchain/core`: core's declaration gives an
+// identity `createAgent` rejects. See #52.
+import { DynamicStructuredTool } from 'langchain';
+import {
+  DiscoveryService,
+  MetadataScanner,
+  ModulesContainer,
+} from '@nestjs/core';
+import { ToolConfigurationError } from '../errors/index.js';
+import {
+  toolModuleWithoutTools,
+  toolOnNonSingleton,
+} from '../errors/messages.js';
+import { ToolModule } from '../interfaces/langchain-module-options.interface.js';
+import { RunReporter } from '../logging/index.js';
+import { buildTool } from './tool.factory.js';
+import { readToolMethod, ToolMethod } from './tool-method.util.js';
+import { findDuplicateToolNames } from './tool-name.util.js';
+import { resolveToolModules } from './tool-modules.util.js';
+
+/**
+ * Maps each item, skipping `undefined`. An item that throws adds its message
+ * to `problems` rather than stopping the others, so one bad tool does not hide
+ * the next.
+ */
+const collect = <T, R>(
+  items: T[],
+  map: (item: T) => R | undefined,
+  problems: string[],
+): R[] =>
+  items.flatMap((item) => {
+    try {
+      const result = map(item);
+      return result === undefined ? [] : [result];
+    } catch (error) {
+      problems.push(error instanceof Error ? error.message : String(error));
+      return [];
+    }
+  });
+
+type ProviderWrapper = ReturnType<DiscoveryService['getProviders']>[number];
+
+/**
+ * Why a provider is not a singleton, or `undefined` when it is. An agent is
+ * one, and a provider built per request or per consumer leaves only an
+ * unconstructed placeholder in `instance`. See #127.
+ */
+const nonSingletonScope = (
+  wrapper: ProviderWrapper,
+): 'request' | 'transient' | 'request-dependency' | undefined => {
+  // `TRANSIENT` reports a static dependency tree.
+  if (wrapper.isTransient) {
+    return 'transient';
+  }
+
+  if (wrapper.isDependencyTreeStatic()) {
+    return undefined;
+  }
+
+  return wrapper.scope === Scope.REQUEST ? 'request' : 'request-dependency';
+};
+
+/** Finds the `@Tool()` methods of an agent's tool modules and builds their tools. */
+@Injectable()
+export class ToolDiscoveryService {
+  constructor(
+    private readonly discoveryService: DiscoveryService,
+    private readonly metadataScanner: MetadataScanner,
+    private readonly modulesContainer: ModulesContainer,
+  ) {}
+
+  private modulesInContext(): Map<Type, number> {
+    const modules = new Map<Type, number>();
+
+    this.modulesContainer.forEach(({ metatype }) =>
+      modules.set(metatype, (modules.get(metatype) ?? 0) + 1),
+    );
+
+    return modules;
+  }
+
+  /**
+   * Every `@Tool()` method of the providers that `modules` host. Adds to
+   * `declaring` each module declaring one, accepted or not.
+   */
+  private toolMethods(
+    modules: Set<Type>,
+    declaring: Set<Type>,
+    problems: string[],
+  ): ToolMethod[] {
+    return this.discoveryService.getProviders().flatMap((wrapper) => {
+      const { instance, host } = wrapper;
+
+      // A `useValue` primitive carries no decorator, nor metadata to read.
+      if (
+        typeof instance !== 'object' ||
+        !instance ||
+        !host ||
+        !modules.has(host.metatype)
+      ) {
+        return [];
+      }
+
+      const reported = problems.length;
+      const methods = collect(
+        this.metadataScanner.getAllMethodNames(Object.getPrototypeOf(instance)),
+        (method) => readToolMethod(instance, method),
+        problems,
+      );
+
+      // A method already reported as a problem is one this module declares.
+      if (methods.length > 0 || problems.length > reported) {
+        declaring.add(host.metatype);
+      }
+
+      const scope = nonSingletonScope(wrapper);
+
+      if (scope && methods.length > 0) {
+        problems.push(
+          toolOnNonSingleton(
+            instance.constructor.name,
+            scope,
+            methods.map(({ method }) => method),
+          ),
+        );
+        return [];
+      }
+
+      return methods;
+    });
+  }
+
+  /** One tool per method, each reporting its calls to `reporter`. */
+  private buildTools(
+    methods: ToolMethod[],
+    reporter: RunReporter,
+    problems: string[],
+  ): { tool: DynamicStructuredTool; where: string }[] {
+    return collect(
+      methods,
+      (method) => ({ tool: buildTool(method, reporter), where: method.where }),
+      problems,
+    );
+  }
+
+  /**
+   * The tools of the modules listed in an agent's `tools` option, each one
+   * reporting its calls to `reporter`. Throws a `ToolConfigurationError`
+   * listing every problem found: a module that is not imported, imported
+   * several times or declaring no tool, a name or a schema that is invalid,
+   * two tools sharing a name.
+   *
+   * Async because an entry may be a `Promise<DynamicModule>`, which Nest's
+   * own `imports` accepts.
+   */
+  async getToolsFromModules(
+    entries: ToolModule[],
+    reporter: RunReporter,
+  ): Promise<DynamicStructuredTool[]> {
+    // By constructor, not `host.name`: two modules may share a class name.
+    // See #58.
+    const { modules, problems } = await resolveToolModules(
+      entries,
+      this.modulesInContext(),
+    );
+
+    const declaring = new Set<Type>();
+    const methods = this.toolMethods(modules, declaring, problems);
+
+    modules.forEach((module) => {
+      if (!declaring.has(module)) {
+        problems.push(toolModuleWithoutTools(module.name));
+      }
+    });
+
+    const built = this.buildTools(methods, reporter, problems);
+    // Per agent: the same name in two agents is legitimate.
+    problems.push(
+      ...findDuplicateToolNames(
+        built.map(({ tool, where }) => ({ name: tool.name, where })),
+      ),
+    );
+
+    if (problems.length > 0) {
+      throw new ToolConfigurationError(problems, reporter.agent);
+    }
+
+    return built.map(({ tool }) => tool);
+  }
+}

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

@@ -0,0 +1,68 @@
+import {
+  createMiddleware,
+  toolErrorMiddleware,
+  ToolInvocationError,
+} from 'langchain';
+import { unknownTool } from '../errors/messages.js';
+import { reportToolError, RunReporter } from '../logging/index.js';
+
+/**
+ * Turns a failed tool call into the text the model receives, LangChain's own,
+ * without the stack (and its server paths) LangChain puts in a schema failure.
+ * Every error is answered: past a middleware, LangChain's tool node rethrows
+ * any error left unhandled and fails the run. See #176.
+ *
+ * Also the only place that sees arguments the schema rejects, which never
+ * reach the `@Tool` wrapper: they are reported here. See #177.
+ *
+ * Once langchain-ai/langchainjs#11830 ships, LangChain's own text has no stack
+ * and `tool-errors.middleware.spec.ts` fails: the schema text can be left to
+ * LangChain, the reporting stays.
+ */
+export const toolErrors = (reporter: RunReporter) =>
+  toolErrorMiddleware({
+    onError: (error) => {
+      if (!ToolInvocationError.isInstance(error)) {
+        // LangChain's default for a method that throws.
+        return `${String(error)}\n Please fix your mistakes.`;
+      }
+
+      const { toolCall, toolError } = error;
+
+      reportToolError(reporter, {
+        tool: toolCall.name,
+        callId: toolCall.id ?? '',
+        reason: 'invalid-arguments',
+        error: toolError,
+        durationMs: 0,
+      });
+
+      return (
+        `Error invoking tool '${toolCall.name}' with kwargs ` +
+        `${JSON.stringify(toolCall.args)} with error: ${String(toolError)}\n` +
+        ' Please fix the error and try again.'
+      );
+    },
+  });
+
+/**
+ * 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.
+ */
+export const unknownTools = (reporter: RunReporter) =>
+  createMiddleware({
+    name: 'unknownTools',
+    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,
+        });
+      }
+
+      return handler(request);
+    },
+  });

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

@@ -0,0 +1,81 @@
+import {
+  PARAM_TYPES_METADATA,
+  TOOL_METADATA,
+  TOOL_PARAMS_METADATA,
+} from '../constants.js';
+import {
+  ToolOptions,
+  ToolParamMetadata,
+} from '../decorators/tool.decorator.js';
+import { toolParamWithoutTool } from '../errors/messages.js';
+
+type Provider = Record<string, (...args: unknown[]) => unknown>;
+
+/** A provider method decorated with `@Tool()`, and what its decorators recorded. */
+export interface ToolMethod {
+  /** `MathService.add`, to name the method in error messages. */
+  where: string;
+  /** The method name, the tool's name when `options` gives none. */
+  method: string;
+  options: ToolOptions;
+  /** The `@ToolParam()` metadata, in declaration order. */
+  params: ToolParamMetadata[];
+  /** The declared parameter types, from TypeScript's `design:paramtypes`. */
+  paramTypes: unknown[];
+  /** Calls the method on its provider, with its arguments by position. */
+  call: (args: unknown[]) => unknown;
+}
+
+// The prototype that defines `method`: its metadata belongs to the function
+// `instance[method]` resolves to, the one carrying `@Tool()` or not.
+const definingPrototype = (instance: object, method: string): object => {
+  let prototype: object | null = Object.getPrototypeOf(instance);
+
+  while (
+    prototype &&
+    !Object.prototype.hasOwnProperty.call(prototype, method)
+  ) {
+    prototype = Object.getPrototypeOf(prototype);
+  }
+
+  return prototype ?? instance;
+};
+
+/**
+ * Reads `method` of a provider instance, or `undefined` if it is not a
+ * `@Tool()`. Throws when it carries a `@ToolParam()` but no `@Tool()`.
+ */
+export const readToolMethod = (
+  instance: object,
+  method: string,
+): ToolMethod | undefined => {
+  const provider = instance as Provider;
+  const options: ToolOptions | undefined = Reflect.getMetadata(
+    TOOL_METADATA,
+    provider[method],
+  );
+
+  const owner = definingPrototype(instance, method);
+  const declared: ToolParamMetadata[] =
+    Reflect.getOwnMetadata(TOOL_PARAMS_METADATA, owner, method) ?? [];
+  const where = `${instance.constructor.name}.${method}`;
+
+  if (!options) {
+    if (declared.length > 0) {
+      throw new Error(toolParamWithoutTool(where));
+    }
+
+    return undefined;
+  }
+
+  return {
+    where,
+    method,
+    options,
+    // Parameter decorators run right to left.
+    params: [...declared].sort((a, b) => a.index - b.index),
+    paramTypes:
+      Reflect.getOwnMetadata(PARAM_TYPES_METADATA, owner, method) ?? [],
+    call: (args) => provider[method](...args),
+  };
+};

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

@@ -0,0 +1,104 @@
+import { DynamicModule, ForwardReference, Type } from '@nestjs/common';
+import { MODULE_METADATA_KEYS } from '../constants.js';
+import {
+  notAToolModule,
+  severalToolModuleInstances,
+  toolModuleNotImported,
+} from '../errors/messages.js';
+import { ToolModule } from '../interfaces/langchain-module-options.interface.js';
+
+// `@Module({})` writes no metadata at all, so an unimported empty module and a
+// plain class are indistinguishable. Only used to sharpen the message.
+const looksLikeAModule = (entry: Type): boolean =>
+  MODULE_METADATA_KEYS.some(
+    (key) => Reflect.getMetadata(key, entry) !== undefined,
+  );
+
+interface Resolved {
+  type?: Type;
+  // A `{ module: Class }` entry says it is a module whatever its metadata
+  // holds, which a `@Module({})` host of a dynamic module never holds.
+  declaresItself: boolean;
+}
+
+/**
+ * Reduce an entry to the class Nest registered it under, the way the scanner
+ * resolves `imports`: await it, call a forward reference, take `module` off a
+ * dynamic module.
+ */
+const toModuleClass = async (entry: ToolModule): Promise<Resolved> => {
+  const awaited: unknown = await entry;
+
+  if (typeof awaited === 'function') {
+    return { type: awaited as Type, declaresItself: false };
+  }
+
+  if (typeof awaited !== 'object' || awaited === null) {
+    return { declaresItself: false };
+  }
+
+  const reference = awaited as Partial<ForwardReference<() => ToolModule>>;
+
+  if (typeof reference.forwardRef === 'function') {
+    return toModuleClass(reference.forwardRef());
+  }
+
+  const dynamic = awaited as Partial<DynamicModule>;
+
+  if (!dynamic.module) {
+    return { declaresItself: false };
+  }
+
+  return { ...(await toModuleClass(dynamic.module)), declaresItself: true };
+};
+
+// Only reached when the entry resolved to no class at all.
+const describeEntry = (entry: unknown): string =>
+  entry === null || entry === undefined
+    ? String(entry)
+    : `an entry of type ${typeof entry}`;
+
+interface ToolModules {
+  modules: Set<Type>;
+  problems: string[];
+}
+
+/**
+ * Split the `tools` entries into the modules discovery can match and the
+ * problems to report. `inContext` counts the modules Nest registered per
+ * class: one per plain import, one per dynamic module.
+ */
+export const resolveToolModules = async (
+  entries: readonly ToolModule[],
+  inContext: ReadonlyMap<Type, number>,
+): Promise<ToolModules> => {
+  const modules = new Set<Type>();
+  const problems: string[] = [];
+
+  for (const entry of entries) {
+    // A circular import resolves to `undefined` here rather than to a class.
+    const { type, declaresItself } = await toModuleClass(entry);
+    const instances = type ? (inContext.get(type) ?? 0) : 0;
+
+    if (type && instances === 1) {
+      modules.add(type);
+      continue;
+    }
+
+    // Tools are matched by class, which would merge the instances' tools.
+    // See #234.
+    if (type && instances > 1) {
+      problems.push(severalToolModuleInstances(type.name, instances));
+      continue;
+    }
+
+    const name = type?.name ?? describeEntry(entry);
+    const isModule = type && (declaresItself || looksLikeAModule(type));
+
+    problems.push(
+      isModule ? toolModuleNotImported(name) : notAToolModule(name),
+    );
+  }
+
+  return { modules, problems };
+};

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

@@ -0,0 +1,57 @@
+import {
+  duplicateToolName,
+  invalidToolName,
+  reservedToolName,
+} from '../errors/messages.js';
+
+// OpenAI's limit, the strictest published, restated: no provider SDK exports
+// 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,
+  where: string,
+): string => {
+  const name = declared ?? method;
+
+  if (!TOOL_NAME.test(name)) {
+    throw new Error(
+      invalidToolName(where, name, String(TOOL_NAME), declared === undefined),
+    );
+  }
+
+  if (name.startsWith(STRUCTURED_OUTPUT_PREFIX)) {
+    throw new Error(reservedToolName(where, name, STRUCTURED_OUTPUT_PREFIX));
+  }
+
+  return name;
+};
+
+/**
+ * One problem per tool whose name an earlier tool already took, naming both
+ * methods. `where` is the method each tool was built from.
+ */
+export const findDuplicateToolNames = (
+  tools: { name: string; where: string }[],
+): string[] => {
+  const seen = new Map<string, string>();
+  const problems: string[] = [];
+
+  tools.forEach(({ name, where }) => {
+    const first = seen.get(name);
+
+    if (first) {
+      problems.push(duplicateToolName(name, first, where));
+      return;
+    }
+
+    seen.set(name, where);
+  });
+
+  return problems;
+};

package/lib/tools/tool-schema.factory.ts

@@ -0,0 +1,142 @@
+import { Type } from '@nestjs/common';
+import { toJsonSchema } from '@langchain/core/utils/json_schema';
+import z, { ZodObject, ZodType } from 'zod';
+import { ToolParamMetadata } from '../decorators/tool.decorator.js';
+import {
+  cannotInferSchema,
+  duplicateParamName,
+  noJsonSchemaForm,
+  schemaContradictsSignature,
+} from '../errors/messages.js';
+import { messageOf } from '../logging/index.js';
+
+const INFERRED = new Map<unknown, () => ZodType>([
+  [String, () => z.string()],
+  [Number, () => z.number()],
+  [Boolean, () => z.boolean()],
+]);
+
+// The JSON Schema types each primitive signature accepts, the first naming it.
+// `integer` is a subset of `number`.
+const JSON_SCHEMA_TYPES = new Map<unknown, string[]>([
+  [String, ['string']],
+  [Number, ['number', 'integer']],
+  [Boolean, ['boolean']],
+]);
+
+const resolveSchema = (
+  param: ToolParamMetadata,
+  paramType: unknown,
+  where: string,
+): ZodType => {
+  if (param.schema) {
+    return param.schema;
+  }
+
+  const inferred = INFERRED.get(paramType);
+
+  if (!inferred) {
+    const declared = (paramType as Type | undefined)?.name ?? 'unknown';
+
+    throw new Error(cannotInferSchema(where, param.name, declared));
+  }
+
+  return inferred();
+};
+
+interface JsonSchemaNode {
+  type?: string | string[];
+  anyOf?: JsonSchemaNode[];
+}
+
+// The JSON Schema types a schema allows, from its `type` or from the branches
+// of its `anyOf`: zod 4 gives a union either form (see #137). `undefined` when
+// it has no JSON Schema form, or a branch names no type.
+const typesOf = (schema: ZodType): string[] | undefined => {
+  let node: JsonSchemaNode;
+
+  try {
+    node = z.toJSONSchema(schema);
+  } catch {
+    return undefined;
+  }
+
+  const branches = node.type === undefined && node.anyOf ? node.anyOf : [node];
+
+  if (branches.some((branch) => branch.type === undefined)) {
+    return undefined;
+  }
+
+  return branches.flatMap((branch) => branch.type ?? []);
+};
+
+// A declared schema LangChain cannot convert to the JSON Schema a provider
+// receives. Wrapped in an object, as LangChain converts a tool's schema: only
+// there does it read the input side of a `.transform()`.
+const checkJsonSchemaForm = (
+  param: ToolParamMetadata,
+  schema: ZodType,
+  where: string,
+): void => {
+  try {
+    toJsonSchema(z.object({ [param.name]: schema }));
+  } catch (error) {
+    throw new Error(noJsonSchemaForm(where, param.name, messageOf(error)));
+  }
+};
+
+// A declared schema that contradicts a primitive signature. Skipped for any
+// other signature, where the schema is the only source of truth.
+const checkAgainstSignature = (
+  param: ToolParamMetadata,
+  paramType: unknown,
+  schema: ZodType,
+  where: string,
+): void => {
+  const accepted = JSON_SCHEMA_TYPES.get(paramType);
+  const types = accepted && typesOf(schema);
+
+  if (!accepted || !types || types.some((type) => accepted.includes(type))) {
+    return;
+  }
+
+  throw new Error(
+    schemaContradictsSignature(where, param.name, types, accepted[0]),
+  );
+};
+
+export const buildToolSchema = (
+  params: ToolParamMetadata[],
+  paramTypes: unknown[],
+  where: string,
+): ZodObject => {
+  const shape: Record<string, ZodType> = {};
+  const indexes = new Map<string, number>();
+
+  params.forEach((param) => {
+    const first = indexes.get(param.name);
+
+    if (first !== undefined) {
+      throw new Error(
+        duplicateParamName(where, param.name, first, param.index),
+      );
+    }
+
+    indexes.set(param.name, param.index);
+
+    const resolved = resolveSchema(param, paramTypes[param.index], where);
+
+    if (param.schema) {
+      checkJsonSchemaForm(param, resolved, where);
+      checkAgainstSignature(param, paramTypes[param.index], resolved, where);
+    }
+
+    const described = param.description
+      ? resolved.describe(param.description)
+      : resolved;
+
+    shape[param.name] = param.optional ? described.optional() : described;
+  });
+
+  return z.object(shape);
+};

package/lib/tools/tool.factory.ts

@@ -0,0 +1,56 @@
+// From `langchain`, not `@langchain/core`: core's declaration gives an
+// identity `createAgent` rejects. See #52.
+import { DynamicStructuredTool } from 'langchain';
+import { ToolParamMetadata } from '../decorators/tool.decorator.js';
+import { observeToolCall, RunReporter } from '../logging/index.js';
+import { buildToolSchema } from './tool-schema.factory.js';
+import { resolveToolName } from './tool-name.util.js';
+import { ToolMethod } from './tool-method.util.js';
+
+// What the agent's tool node adds to the config. Structural, see #52.
+interface ToolCallConfig {
+  toolCall?: { id?: string };
+}
+
+// Placed by index: an omitted optional leaves a hole rather than shifting the
+// arguments after it.
+const toPositional = (
+  params: ToolParamMetadata[],
+  values: Record<string, unknown>,
+): unknown[] => {
+  const args: unknown[] = [];
+
+  params.forEach((param) => {
+    args[param.index] = values[param.name];
+  });
+
+  return args;
+};
+
+/**
+ * Builds the LangChain tool that calls a `@Tool()` method and reports each
+ * call to `reporter`. Throws when the name or a parameter schema is invalid.
+ */
+export const buildTool = (
+  { where, method, options, params, paramTypes, call }: ToolMethod,
+  reporter: RunReporter,
+): DynamicStructuredTool => {
+  const name = resolveToolName(options.name, method, where);
+
+  return new DynamicStructuredTool({
+    name,
+    description: options.description,
+    schema: buildToolSchema(params, paramTypes, where),
+    func: (values: Record<string, unknown>, _runManager, config) =>
+      observeToolCall(
+        reporter,
+        {
+          tool: name,
+          // Empty only for a tool invoked outside an agent.
+          callId: (config as ToolCallConfig | undefined)?.toolCall?.id ?? '',
+          args: values,
+        },
+        () => call(toPositional(params, values)),
+      ),
+  });
+};