nestjs-langchain 1.0.2 → 2.0.0

package/lib/agent.ts

@@ -0,0 +1,257 @@
+import { Inject, Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+import { createAgent, initChatModel } from 'langchain';
+import {
+  AGENT_NAME_TOKEN,
+  MODULE_OPTIONS_TOKEN,
+  UNNAMED_AGENT,
+} from './langchain.module-definition.js';
+import {
+  LangChainModuleOptions,
+  ModelOption,
+} from './interfaces/langchain-module-options.interface.js';
+import { CompletedRun } from './interfaces/completed-run.interface.js';
+import {
+  ToolDiscoveryService,
+  toolErrors,
+  unknownTools,
+} from './tools/index.js';
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { LOG_CONTEXT, messageOf, RunReporter } from './logging/index.js';
+import { summariseRun } from './run/index.js';
+import { AgentRunError } from './errors/index.js';
+import {
+  agentNotBootstrapped,
+  agentPrefix,
+  agentRunFailed,
+  duplicateAgentName,
+  modelNeverReplied,
+  modelNotBuilt,
+  modelReplyEmpty,
+  notAChatModel,
+} from './errors/messages.js';
+
+// Derived, not imported from `@langchain/core`. See #52.
+type AgentModel = Parameters<typeof createAgent>[0]['model'];
+type ChatModel = Exclude<AgentModel, string>;
+type Graph = ReturnType<typeof createAgent>;
+type AgentState = Awaited<ReturnType<Graph['invoke']>>;
+
+/**
+ * One agent, registered through `LangChainModule`. Inject it directly for the
+ * unnamed agent, or with `@InjectAgent(name)` for a named one.
+ *
+ * @example
+ * ```ts
+ * constructor(private readonly agent: Agent) {}
+ *
+ * async ask(question: string): Promise<string> {
+ *   const { output } = await this.agent.run(question);
+ *   return output;
+ * }
+ * ```
+ */
+@Injectable()
+export class Agent implements OnModuleInit {
+  // Assembled in `onModuleInit`, once every tool module's providers exist.
+  #graph?: Graph;
+  // Without a context, since Nest appends the instance's to each call's own.
+  private readonly logger = new Logger();
+  private readonly prefix: string;
+  private readonly reporter: RunReporter;
+  // Model failures, which only LangChain's callbacks see. Tool calls are
+  // reported by their wrapper and the tool middlewares.
+  private readonly modelErrors: BaseCallbackHandler;
+
+  /** @internal Built by `LangChainModule`, never by hand. */
+  constructor(
+    @Inject(MODULE_OPTIONS_TOKEN)
+    private readonly options: LangChainModuleOptions,
+    @Inject(AGENT_NAME_TOKEN)
+    private readonly agentName: string,
+    private readonly toolDiscovery: ToolDiscoveryService,
+    private readonly discovery: DiscoveryService,
+  ) {
+    this.prefix = agentPrefix(agentName);
+    this.reporter = new RunReporter({
+      logger: this.logger,
+      agent: agentName,
+      prefix: this.prefix,
+      observer: options.observer,
+    });
+    this.modelErrors = BaseCallbackHandler.fromMethods({
+      handleLLMError: (error: unknown) => {
+        this.reporter.logError(`the model failed: ${messageOf(error)}`);
+        this.reporter.notify((observer) =>
+          observer.onModelError?.({ agent: agentName, error }),
+        );
+      },
+    });
+  }
+
+  /**
+   * Called by Nest: builds the agent, once the tool modules' providers exist.
+   *
+   * @internal
+   */
+  async onModuleInit() {
+    this.assertUniqueName();
+
+    const tools = await this.toolDiscovery.getToolsFromModules(
+      this.options.tools ?? [],
+      this.reporter,
+    );
+
+    this.#graph = createAgent({
+      model: await this.resolveModel(this.options.model),
+      tools,
+      systemPrompt: this.options.systemPrompt,
+      // The first wraps the next: `toolErrors` sits right around the tool.
+      middleware: [unknownTools(this.reporter), toolErrors(this.reporter)],
+    });
+
+    this.logger.log(
+      `${this.prefix}ready with ${tools.length} tool${tools.length === 1 ? '' : 's'}`,
+      LOG_CONTEXT,
+    );
+  }
+
+  // Every registration provides its own name, so a name found twice in the
+  // container is two agents behind one token.
+  private assertUniqueName(): void {
+    const registered = this.discovery
+      .getProviders()
+      .filter(
+        ({ token, instance }) =>
+          token === AGENT_NAME_TOKEN && instance === this.agentName,
+      );
+
+    if (registered.length > 1) {
+      throw new Error(
+        duplicateAgentName(
+          this.agentName === UNNAMED_AGENT ? undefined : this.agentName,
+        ),
+      );
+    }
+  }
+
+  /**
+   * Build the model from its configuration, or hand back the instance the
+   * caller already built. Recognised by the members `createAgent` checks,
+   * never by `instanceof`, which two copies of `@langchain/core` break.
+   * See #52.
+   *
+   * @param option The `model` option.
+   * @returns The model `createAgent` receives.
+   */
+  private async resolveModel(option: ModelOption): Promise<AgentModel> {
+    // The types forbid a primitive, an untyped configuration does not. See #236.
+    const given: unknown = option;
+
+    if (typeof given !== 'object' || given === null) {
+      throw new Error(notAChatModel(this.prefix));
+    }
+
+    if (!('invoke' in option)) {
+      const { model, ...fields } = option;
+
+      try {
+        return await initChatModel(model, fields);
+      } catch (error) {
+        throw new Error(modelNotBuilt(this.prefix, error), { cause: error });
+      }
+    }
+
+    if (
+      typeof option.invoke !== 'function' ||
+      typeof option.bindTools !== 'function' ||
+      typeof option._streamResponseChunks !== 'function'
+    ) {
+      throw new Error(notAChatModel(this.prefix));
+    }
+
+    // The same object, typed from the declarations `createAgent` reads.
+    return option as unknown as ChatModel;
+  }
+
+  /**
+   * Runs the agent to completion on one user message. Every failure is thrown
+   * as an `AgentRunError`, the original error in its `cause`.
+   *
+   * @param input The user's message.
+   * @returns The model's answer, the tools it called and what the run cost.
+   * @example
+   * ```ts
+   * const { output, tools } = await agent.run('What is 6 times 7?');
+   * ```
+   */
+  async run(input: string): Promise<CompletedRun> {
+    const startedAt = Date.now();
+    const durationMs = () => Date.now() - startedAt;
+
+    try {
+      const { answer, messages } = await this.complete(input);
+      const finished = {
+        durationMs: durationMs(),
+        ...summariseRun(messages),
+      };
+
+      this.reporter.notify((observer) =>
+        observer.onRunFinish?.({ agent: this.agentName, ...finished }),
+      );
+
+      return { status: 'completed', output: answer, ...finished };
+    } catch (thrown) {
+      const error =
+        thrown instanceof AgentRunError
+          ? thrown
+          : new AgentRunError(
+              agentRunFailed(this.prefix, thrown),
+              this.agentName,
+              { cause: thrown },
+            );
+
+      this.reporter.notify((observer) =>
+        observer.onRunError?.({
+          agent: this.agentName,
+          durationMs: durationMs(),
+          error,
+        }),
+      );
+
+      throw error;
+    }
+  }
+
+  private async complete(
+    input: string,
+  ): Promise<{ answer: string; messages: AgentState['messages'] }> {
+    if (!this.#graph) {
+      throw new AgentRunError(
+        agentNotBootstrapped(this.prefix),
+        this.agentName,
+      );
+    }
+
+    const { messages }: AgentState = await this.#graph.invoke(
+      { messages: [{ role: 'user', content: input }] },
+      { callbacks: [this.modelErrors, ...(this.options.callbacks ?? [])] },
+    );
+
+    const last = messages[messages.length - 1];
+
+    if (!last || last.type !== 'ai') {
+      throw new AgentRunError(
+        modelNeverReplied(this.prefix, last?.type),
+        this.agentName,
+      );
+    }
+
+    // `text`, not `content`: block answers are an array.
+    if (!last.text) {
+      throw new AgentRunError(modelReplyEmpty(this.prefix), this.agentName);
+    }
+
+    return { answer: last.text, messages };
+  }
+}

package/lib/constants.ts

@@ -0,0 +1,15 @@
+// Namespaced like the other tokens, so another library's marks are not read.
+export const TOOL_METADATA = 'nestjs-langchain:tool';
+export const TOOL_PARAMS_METADATA = 'nestjs-langchain:tool-params';
+
+// Emitted by `emitDecoratorMetadata` on every decorated method.
+export const PARAM_TYPES_METADATA = 'design:paramtypes';
+
+// The keys `@Module()` writes, restated: `@nestjs/common/constants` is
+// internal. See #97.
+export const MODULE_METADATA_KEYS = [
+  'imports',
+  'providers',
+  'controllers',
+  'exports',
+];

package/lib/decorators/index.ts

@@ -0,0 +1,3 @@
+export { InjectAgent } from './inject-agent.decorator.js';
+export { Tool, ToolParam } from './tool.decorator.js';
+export type { ToolOptions, ToolParamOptions } from './tool.decorator.js';

package/lib/decorators/inject-agent.decorator.ts

@@ -0,0 +1,15 @@
+import { Inject } from '@nestjs/common';
+import { getAgentToken } from '../langchain.module-definition.js';
+
+/**
+ * Injects the agent registered under `name`. The agent registered without a
+ * name is injected as `Agent`, with no decorator.
+ *
+ * @param name The `name` the agent was registered with.
+ * @returns The parameter decorator.
+ * @example
+ * ```ts
+ * constructor(@InjectAgent('MATH_AGENT') private readonly math: Agent) {}
+ * ```
+ */
+export const InjectAgent = (name: string) => Inject(getAgentToken(name));

package/lib/decorators/tool.decorator.ts

@@ -0,0 +1,86 @@
+import { SetMetadata } from '@nestjs/common';
+import type { ZodType } from 'zod';
+import { TOOL_METADATA, TOOL_PARAMS_METADATA } from '../constants.js';
+import { toolParamOutsideMethod } from '../errors/messages.js';
+
+/** The options of `@Tool()`. */
+export interface ToolOptions {
+  /**
+   * The name the model calls, the method name by default. Matches
+   * `/^[a-zA-Z0-9_-]{1,64}$/` and does not start with `extract-`, which
+   * LangChain reserves for structured output.
+   */
+  name?: string;
+  /** What the tool does, which the model reads to decide when to call it. */
+  description: string;
+}
+
+/**
+ * Exposes a provider method as a tool to the agents whose `tools` list its
+ * module. A method decorator only: discovery never reads one placed on a
+ * class.
+ *
+ * @param options The tool's description and, optionally, its name.
+ * @returns The method decorator.
+ * @example
+ * ```ts
+ * \@Tool({ description: 'Doubles a number.' })
+ * double(@ToolParam({ name: 'x' }) x: number): number {
+ *   return x * 2;
+ * }
+ * ```
+ */
+export const Tool = (options: ToolOptions): MethodDecorator =>
+  SetMetadata(TOOL_METADATA, options);
+
+/** The options of `@ToolParam()`. */
+export interface ToolParamOptions {
+  /** The argument's name in the schema the model fills in. */
+  name: string;
+  /** What the argument means, read by the model. */
+  description?: string;
+  /** Required unless the signature resolves to string, number or boolean. */
+  schema?: ZodType;
+  /** Lets the model leave the argument out; declare the parameter `x?: T`. */
+  optional?: boolean;
+}
+
+/** What `@ToolParam()` records for one parameter. */
+export interface ToolParamMetadata extends ToolParamOptions {
+  /** The parameter's position in the method's signature. */
+  index: number;
+}
+
+/**
+ * Declares a parameter of a `@Tool()` method as an argument of the tool.
+ *
+ * @param options The argument's name and, optionally, its description,
+ *   schema and whether it is optional.
+ * @returns The parameter decorator.
+ * @example
+ * ```ts
+ * const Tags = z.array(z.string());
+ *
+ * count(@ToolParam({ name: 'tags', schema: Tags }) tags: string[]): number {
+ *   return tags.length;
+ * }
+ * ```
+ */
+export function ToolParam(options: ToolParamOptions): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    if (propertyKey === undefined) {
+      throw new Error(toolParamOutsideMethod());
+    }
+
+    // Own metadata only: a subclass redeclaring a method starts afresh.
+    const existing: ToolParamMetadata[] =
+      Reflect.getOwnMetadata(TOOL_PARAMS_METADATA, target, propertyKey) ?? [];
+
+    Reflect.defineMetadata(
+      TOOL_PARAMS_METADATA,
+      [...existing, { ...options, index: parameterIndex }],
+      target,
+      propertyKey,
+    );
+  };
+}

package/lib/errors/agent-run.error.ts

@@ -0,0 +1,29 @@
+/**
+ * A run of an agent failed. The base class of every run failure: everything
+ * `run()` throws is one, with the original error, if any, in `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await agent.run(question);
+ * } catch (error) {
+ *   if (error instanceof AgentRunError) {
+ *     console.error(error.agent, error.cause);
+ *   }
+ * }
+ * ```
+ */
+export class AgentRunError extends Error {
+  /** The error that made the run fail, when it came from elsewhere. */
+  declare readonly cause?: unknown;
+
+  constructor(
+    message: string,
+    /** `'default'` when the agent was registered without a name. */
+    readonly agent: string,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = 'AgentRunError';
+  }
+}

package/lib/errors/index.ts

@@ -0,0 +1,2 @@
+export { AgentRunError } from './agent-run.error.js';
+export { ToolConfigurationError } from './tool-configuration.error.js';

package/lib/errors/messages.ts

@@ -0,0 +1,158 @@
+// Message construction, kept together so the wording stays consistent.
+import { UNNAMED_AGENT } from '../langchain.module-definition.js';
+
+// `'MATH '` for a named agent, empty for the unnamed one: "the MATH agent".
+export const agentPrefix = (agent: string): string =>
+  agent === UNNAMED_AGENT ? '' : `${agent} `;
+
+export const toolProblems = (prefix: string, problems: string[]): string =>
+  `nestjs-langchain found ${problems.length} ` +
+  `problem${problems.length === 1 ? '' : 's'} ` +
+  `with the tools of the ${prefix}agent:\n` +
+  problems.map((problem) => `  - ${problem}`).join('\n');
+
+export const notAToolModule = (entry: string): string =>
+  `${entry} is listed in \`tools\` but is not a module in the Nest context. ` +
+  'Pass a class decorated with @Module, imported alongside LangChainModule.';
+
+export const toolModuleNotImported = (entry: string): string =>
+  `${entry} is listed in \`tools\` but is not imported into the Nest context. ` +
+  'Add it to the `imports` of the module registering the agent.';
+
+export const severalToolModuleInstances = (
+  entry: string,
+  count: number,
+): string =>
+  `${entry} is listed in \`tools\`, but the Nest context holds ${count} ` +
+  'instances of it, so their tools cannot be told apart. Import it once, or ' +
+  'give each configuration its own module class.';
+
+export const toolModuleWithoutTools = (entry: string): string =>
+  `${entry} is listed in \`tools\` but declares no @Tool method. ` +
+  'Tools are read from the providers a module declares, not from the ' +
+  'modules it imports.';
+
+export const toolParamWithoutTool = (where: string): string =>
+  `${where} has @ToolParam but no @Tool, so the model never sees it. ` +
+  'Add @Tool({ description }) to expose it, or remove the @ToolParam.';
+
+export const toolParamOutsideMethod = (): string =>
+  '@ToolParam can only be used on method parameters.';
+
+export const toolOnNonSingleton = (
+  provider: string,
+  scope: 'request' | 'transient' | 'request-dependency',
+  methods: string[],
+): string =>
+  `${provider} ${
+    {
+      request: 'is request-scoped',
+      transient: 'is transient',
+      'request-dependency': 'depends on a request-scoped provider',
+    }[scope]
+  }, so its @Tool methods (${methods.join(', ')}) cannot be called by an ` +
+  'agent, which is a singleton. Make it a default-scoped provider.';
+
+export const duplicateToolName = (
+  name: string,
+  first: string,
+  second: string,
+): string =>
+  `Two tools are named "${name}": ${first} and ${second}. ` +
+  'Give one of them a `name` in @Tool().';
+
+export const invalidToolName = (
+  where: string,
+  name: string,
+  pattern: string,
+  fromMethodName: boolean,
+): string =>
+  `${where}: "${name}" is not a valid tool name, providers match ${pattern}` +
+  (fromMethodName ? '. Pass a `name` to @Tool().' : '.');
+
+export const reservedToolName = (
+  where: string,
+  name: string,
+  prefix: string,
+): string =>
+  `${where}: "${name}" starts with "${prefix}", a prefix LangChain reserves ` +
+  'for structured output, so the agent would never run it. Give it another ' +
+  '`name` in @Tool().';
+
+export const cannotInferSchema = (
+  where: string,
+  param: string,
+  declared: string,
+): string =>
+  `${where}: cannot infer a schema for "${param}" declared as ${declared}. ` +
+  'Pass a `schema` to @ToolParam, or use string, number or boolean.';
+
+export const schemaContradictsSignature = (
+  where: string,
+  param: string,
+  declared: string[],
+  expected: string,
+): string =>
+  `${where}: the schema for "${param}" describes ${declared.join(' | ')} ` +
+  `but the signature declares ${expected}.`;
+
+export const noJsonSchemaForm = (
+  where: string,
+  param: string,
+  reason: string,
+): string =>
+  `${where}: "${param}" has no JSON Schema form (${reason}). ` +
+  'Declare a schema JSON Schema can express and convert it with .transform(), ' +
+  'such as z.iso.datetime() for a date.';
+
+export const duplicateParamName = (
+  where: string,
+  name: string,
+  first: number,
+  second: number,
+): string =>
+  `${where}: parameters ${first + 1} and ${second + 1} are both named "${name}". ` +
+  'Give each @ToolParam its own name.';
+
+export const notAChatModel = (prefix: string): string =>
+  `The ${prefix}agent's \`model\` is neither a LangChain chat model nor a ` +
+  "`{ model: 'provider:name' }` configuration. Pass a chat model instance " +
+  '(e.g. `new ChatOpenAI(...)`) or a configuration.';
+
+export const modelNotBuilt = (prefix: string, cause: unknown): string =>
+  `The ${prefix}agent's model could not be built: ` +
+  (cause instanceof Error ? cause.message : String(cause));
+
+export const agentNotBootstrapped = (prefix: string): string =>
+  `The ${prefix}agent ran before the application bootstrapped. ` +
+  'Call `app.init()` or `app.listen()` first.';
+
+export const duplicateAgentName = (name: string | undefined): string =>
+  name === undefined
+    ? 'Two agents are registered without a name. ' +
+      'Give all but one a `name` and inject them with @InjectAgent().'
+    : `Two agents are registered as "${name}". ` +
+      'Give each LangChainModule registration its own `name`.';
+
+export const reservedAgentName = (name: string): string =>
+  name === ''
+    ? "An agent's `name` cannot be empty. " +
+      'Omit it to register the unnamed agent.'
+    : `"${name}" cannot be an agent's \`name\`: it stands for the agent ` +
+      'registered without one. Pick another name.';
+
+export const agentRunFailed = (prefix: string, cause: unknown): string =>
+  `The ${prefix}agent's run failed: ` +
+  (cause instanceof Error ? cause.message : String(cause));
+
+export const modelNeverReplied = (
+  prefix: string,
+  last: string | undefined,
+): string =>
+  `The ${prefix}agent's loop ended before the model replied. ` +
+  `The last message was ${last ? `a ${last} message` : 'never produced'}.`;
+
+export const modelReplyEmpty = (prefix: string): string =>
+  `The ${prefix}agent's model replied with no text content.`;
+
+export const unknownTool = (): string => 'not a tool of this agent';

package/lib/errors/tool-configuration.error.ts

@@ -0,0 +1,24 @@
+import { agentPrefix, toolProblems } from './messages.js';
+
+/**
+ * An agent's tools are misconfigured, which fails the bootstrap. Lists every
+ * problem found while assembling them, not only the first.
+ *
+ * @example
+ * ```ts
+ * const app = await Test.createTestingModule({ imports: [AppModule] }).compile();
+ *
+ * await expect(app.init()).rejects.toThrow(ToolConfigurationError);
+ * ```
+ */
+export class ToolConfigurationError extends Error {
+  constructor(
+    /** One message per problem, in the order they were found. */
+    readonly problems: string[],
+    /** `'default'` when the agent was registered without a name. */
+    readonly agent: string,
+  ) {
+    super(toolProblems(agentPrefix(agent), problems));
+    this.name = 'ToolConfigurationError';
+  }
+}

package/lib/index.ts

@@ -0,0 +1,26 @@
+// The public surface, the one path `exports` opens. Named, so each export is
+// a decision. See #82.
+export { LangChainModule } from './langchain.module.js';
+export { getAgentToken } from './langchain.module-definition.js';
+export { Agent } from './agent.js';
+export { AgentRunError, ToolConfigurationError } from './errors/index.js';
+export { InjectAgent, Tool, ToolParam } from './decorators/index.js';
+export type { ToolOptions, ToolParamOptions } from './decorators/index.js';
+export type {
+  AgentObserver,
+  ModelErrorEvent,
+  RunErrorEvent,
+  RunFinishEvent,
+  ToolEndEvent,
+  ToolErrorEvent,
+  ToolStartEvent,
+} from './interfaces/agent-observer.interface.js';
+export type { CompletedRun } from './interfaces/completed-run.interface.js';
+export type {
+  AgentCallback,
+  LangChainModuleOptions,
+  LangChainOptionsFactory,
+  ModelConfig,
+  ModelOption,
+  ToolModule,
+} from './interfaces/langchain-module-options.interface.js';