nestjs-langchain 1.0.2 → 2.0.0

package/lib/interfaces/agent-observer.interface.ts

@@ -0,0 +1,113 @@
+import type { AgentRunError } from '../errors/agent-run.error.js';
+import type { RunSummary } from '../run/index.js';
+
+interface ToolEvent {
+  /** `'default'` when the agent was registered without a name. */
+  agent: string;
+  /** The tool's name, as the model called it. */
+  tool: string;
+  /**
+   * The id the model gave this call. Pairs a start with its end or error. A
+   * call that never reached the tool has an error and no start.
+   */
+  callId: string;
+}
+
+/** A tool call about to run, its arguments validated. */
+export interface ToolStartEvent extends ToolEvent {
+  /** The arguments, parsed and validated against the tool's schema. */
+  args: Record<string, unknown>;
+}
+
+/** A tool call that returned. */
+export interface ToolEndEvent extends ToolEvent {
+  /** What the method returned, before it is serialised for the model. */
+  output: unknown;
+  /** How long the method took. */
+  durationMs: number;
+}
+
+/** A tool call that failed, or never reached its tool. */
+export interface ToolErrorEvent extends ToolEvent {
+  /**
+   * Why the call failed: the agent has no such tool, the schema rejected the
+   * arguments, or the tool threw. Only `'threw'` follows an `onToolStart`.
+   * May gain values in a minor release: keep a `default` branch when
+   * switching on it.
+   */
+  reason: 'unknown-tool' | 'invalid-arguments' | 'threw';
+  /** What the tool threw, or why the call never reached it. */
+  error: unknown;
+  /** `0` when the tool never ran. */
+  durationMs: number;
+}
+
+/** A model call that failed. The run may still retry or fail. */
+export interface ModelErrorEvent {
+  /** `'default'` when the agent was registered without a name. */
+  agent: string;
+  /** What the provider threw. */
+  error: unknown;
+}
+
+/** A run that returned, with what it cost. */
+export interface RunFinishEvent extends RunSummary {
+  /** `'default'` when the agent was registered without a name. */
+  agent: string;
+  /** How long the run took. */
+  durationMs: number;
+}
+
+/** A run that threw. */
+export interface RunErrorEvent {
+  /** `'default'` when the agent was registered without a name. */
+  agent: string;
+  /** How long the run took before it failed. */
+  durationMs: number;
+  /** The same error the caller of `run()` receives. */
+  error: AgentRunError;
+}
+
+/**
+ * Called as a run goes. Every method is optional and may be async. It is
+ * never awaited, and a throw or a rejection is logged and swallowed, never
+ * propagated into the run.
+ */
+export interface AgentObserver {
+  /**
+   * Before a tool runs, once its arguments are validated.
+   *
+   * @param event The call and its arguments.
+   */
+  onToolStart?(event: ToolStartEvent): void | Promise<void>;
+  /**
+   * After a tool returns.
+   *
+   * @param event The call, its output and its duration.
+   */
+  onToolEnd?(event: ToolEndEvent): void | Promise<void>;
+  /**
+   * After a tool call fails: the tool threw, or the call never reached it.
+   *
+   * @param event The call, why it failed and the error.
+   */
+  onToolError?(event: ToolErrorEvent): void | Promise<void>;
+  /**
+   * After a model call fails.
+   *
+   * @param event The error the provider threw.
+   */
+  onModelError?(event: ModelErrorEvent): void | Promise<void>;
+  /**
+   * Only for a run that returns.
+   *
+   * @param event The run's duration, tools and tokens.
+   */
+  onRunFinish?(event: RunFinishEvent): void | Promise<void>;
+  /**
+   * For every run that throws, whatever the cause.
+   *
+   * @param event The run's duration and the error its caller receives.
+   */
+  onRunError?(event: RunErrorEvent): void | Promise<void>;
+}

package/lib/interfaces/completed-run.interface.ts

@@ -0,0 +1,14 @@
+import type { RunSummary } from '../run/index.js';
+
+/**
+ * A run that went to completion. `status` may gain values in a minor release:
+ * keep a `default` branch when switching on it.
+ */
+export interface CompletedRun<TOutput = string> extends RunSummary {
+  /** Always `'completed'`: a run that fails throws instead. */
+  status: 'completed';
+  /** The model's text answer. */
+  output: TOutput;
+  /** How long the run took. */
+  durationMs: number;
+}

package/lib/interfaces/langchain-module-options.interface.ts

@@ -0,0 +1,91 @@
+import { ModuleMetadata } from '@nestjs/common';
+import type {
+  BaseCallbackHandler,
+  CallbackHandlerMethods,
+} from '@langchain/core/callbacks/base';
+import type { AgentObserver } from './agent-observer.interface.js';
+
+/**
+ * Model configuration, resolved at bootstrap through `initChatModel`. Its
+ * fields go as they are to the provider class, and a provider that names one
+ * differently ignores it (`ChatOllama` reads `numPredict`, not `maxTokens`):
+ * pass a model instance then.
+ */
+export type ModelConfig = {
+  /** Provider-qualified name, e.g. `openai:gpt-5-mini`. */
+  model: string;
+  /** Omit it to let the provider read its own env var, or to use IAM/ADC. */
+  apiKey?: string;
+  /** The sampling temperature. */
+  temperature?: number;
+  /** The longest answer, in tokens. */
+  maxTokens?: number;
+  /** How long one model call may take, in milliseconds. */
+  timeout?: number;
+  /** How many times a failed model call is retried. */
+  maxRetries?: number;
+};
+
+/**
+ * A LangChain chat model instance, by the members `createAgent` checks for.
+ * Structural rather than `BaseChatModel`: a CommonJS application types its
+ * model from `@langchain/core`'s other declaration files. See #169.
+ */
+interface ChatModelLike {
+  /** Calls the model. */
+  invoke(...args: never[]): Promise<unknown>;
+  /** Optional, as on `BaseChatModel`; required at bootstrap. */
+  bindTools?(...args: never[]): unknown;
+  /** Streams the model's answer. */
+  _streamResponseChunks(...args: never[]): unknown;
+}
+
+/**
+ * A configuration to resolve, or a model that is already built. The instance
+ * form takes anything {@link ModelConfig} cannot express.
+ */
+export type ModelOption = ModelConfig | ChatModelLike;
+
+/**
+ * What Nest's own `imports` accepts: a module class, a dynamic module, a
+ * promise of one, or a forward reference.
+ */
+export type ToolModule = NonNullable<ModuleMetadata['imports']>[number];
+
+/**
+ * Anything LangChain accepts as a run callback. Every method is optional, so a
+ * plain object of the `handle*` you care about is enough.
+ */
+export type AgentCallback = BaseCallbackHandler | CallbackHandlerMethods;
+
+/** The options of one agent, for `register` or `registerAsync`. */
+export interface LangChainModuleOptions {
+  /** The chat model: a `provider:model` configuration, or an instance. */
+  model: ModelOption;
+  /** The instructions the model receives before every run. */
+  systemPrompt?: string;
+  /**
+   * The modules declaring this agent's `@Tool()` providers. Each must also be
+   * imported into the Nest context, as a single instance.
+   */
+  tools?: ToolModule[];
+  /** Called as a run goes, so you decide what is worth recording. */
+  observer?: AgentObserver;
+  /** LangChain-native run callbacks, for handlers written against its API. */
+  callbacks?: AgentCallback[];
+}
+
+/**
+ * A class building an agent's options, for `registerAsync({ useClass })` or
+ * `useExisting`. Declare the method's return type, so that a key the options
+ * do not declare is rejected.
+ */
+export interface LangChainOptionsFactory {
+  /**
+   * Builds the agent's options.
+   *
+   * @returns The options, or a promise of them.
+   */
+  createLangChainOptions():
+    LangChainModuleOptions | Promise<LangChainModuleOptions>;
+}

package/lib/langchain.module-definition.ts

@@ -0,0 +1,36 @@
+import { ConfigurableModuleBuilder } from '@nestjs/common';
+import { LangChainModuleOptions } from './interfaces/langchain-module-options.interface.js';
+
+/** The base class and tokens Nest generates for `LangChainModule`. */
+export const {
+  ConfigurableModuleClass,
+  MODULE_OPTIONS_TOKEN,
+  OPTIONS_TYPE,
+  ASYNC_OPTIONS_TYPE,
+} = new ConfigurableModuleBuilder<LangChainModuleOptions>()
+  .setExtras<{ name?: string }>({ name: undefined })
+  .setFactoryMethodName('createLangChainOptions')
+  .build();
+
+/** The agent's own name. */
+export const AGENT_NAME_TOKEN = 'nestjs-langchain:agent-name';
+
+/** The name the unnamed agent carries in logs and observer events. */
+export const UNNAMED_AGENT = 'default';
+
+/**
+ * The injection token of the agent registered under `name`, for the places
+ * `@InjectAgent` cannot go: `overrideProvider` in a test, a factory's
+ * `inject`. The string it returns is not part of the API.
+ *
+ * @param name The `name` the agent was registered with.
+ * @returns The agent's injection token.
+ * @example
+ * ```ts
+ * Test.createTestingModule({ imports: [AppModule] })
+ *   .overrideProvider(getAgentToken('MATH_AGENT'))
+ *   .useValue({ run: async () => ({ status: 'completed', output: '42' }) });
+ * ```
+ */
+export const getAgentToken = (name: string): string =>
+  `nestjs-langchain:agent:${name}`;

package/lib/langchain.module.ts

@@ -0,0 +1,138 @@
+import { DynamicModule, Module, Provider, Type } from '@nestjs/common';
+import {
+  AGENT_NAME_TOKEN,
+  ASYNC_OPTIONS_TYPE,
+  ConfigurableModuleClass,
+  getAgentToken,
+  OPTIONS_TYPE,
+  UNNAMED_AGENT,
+} from './langchain.module-definition.js';
+import { Agent } from './agent.js';
+import {
+  LangChainModuleOptions,
+  LangChainOptionsFactory,
+} from './interfaces/langchain-module-options.interface.js';
+import { ToolDiscoveryService } from './tools/index.js';
+import { reservedAgentName } from './errors/messages.js';
+import { DiscoveryModule } from '@nestjs/core';
+
+/**
+ * Registers agents as Nest providers: each `register` or `registerAsync`
+ * adds one. Give each a `name` when there are several.
+ *
+ * @example
+ * ```ts
+ * imports: [
+ *   MathModule,
+ *   LangChainModule.register({
+ *     model: { model: 'openai:gpt-5-mini' },
+ *     tools: [MathModule],
+ *   }),
+ * ],
+ * ```
+ */
+@Module({
+  imports: [DiscoveryModule],
+  providers: [ToolDiscoveryService],
+})
+export class LangChainModule extends ConfigurableModuleClass {
+  /**
+   * Registers an agent from its options.
+   *
+   * @param options The agent's options, with its `name` when there are several.
+   * @returns The module providing the agent.
+   * @example
+   * ```ts
+   * LangChainModule.register({
+   *   name: 'MATH_AGENT',
+   *   model: { model: 'openai:gpt-5-mini' },
+   *   tools: [MathModule],
+   * });
+   * ```
+   */
+  static register(options: typeof OPTIONS_TYPE): DynamicModule {
+    const dynamicModule = super.register(options);
+    return this.addDynamicAgentProvider(dynamicModule, options.name);
+  }
+
+  /**
+   * Registers an agent whose options other providers build, through
+   * `useFactory`, `useClass` or `useExisting`. `name` stays outside the
+   * factory: it names the token `@InjectAgent()` resolves.
+   *
+   * @param options How to build the agent's options, and its `name`.
+   * @returns The module providing the agent.
+   * @example
+   * ```ts
+   * LangChainModule.registerAsync({
+   *   name: 'MATH_AGENT',
+   *   imports: [ConfigModule],
+   *   inject: [ConfigService],
+   *   useFactory: (config: ConfigService) => ({
+   *     model: {
+   *       model: 'openai:gpt-5-mini',
+   *       apiKey: config.getOrThrow<string>('OPENAI_API_KEY'),
+   *     },
+   *   }),
+   * });
+   * ```
+   */
+  static registerAsync<
+    // Rejects a key the options do not declare, which Nest's
+    // `T | Promise<T>` return type never checks in a returned literal.
+    T extends LangChainModuleOptions &
+      Record<Exclude<keyof T, keyof LangChainModuleOptions>, never>,
+  >(
+    options: Omit<
+      typeof ASYNC_OPTIONS_TYPE,
+      'useFactory' | 'useClass' | 'useExisting'
+    > & {
+      // Nest's own signature: `unknown[]` would reject a factory declaring
+      // its injected parameters, such as `(config: ConfigService) => …`.
+      // oxlint-disable-next-line typescript/no-explicit-any
+      useFactory?: (...args: any[]) => T | Promise<T>;
+      useClass?: Type<LangChainOptionsFactory>;
+      useExisting?: Type<LangChainOptionsFactory>;
+    },
+  ): DynamicModule {
+    const dynamicModule = super.registerAsync(options);
+    return this.addDynamicAgentProvider(dynamicModule, options.name);
+  }
+
+  private static addDynamicAgentProvider(
+    dynamicModule: DynamicModule,
+    name: string | undefined,
+  ): DynamicModule {
+    if (name === '' || name === UNNAMED_AGENT) {
+      throw new Error(reservedAgentName(name));
+    }
+
+    const nameProvider: Provider = {
+      provide: AGENT_NAME_TOKEN,
+      useValue: name ?? UNNAMED_AGENT,
+    };
+
+    // The class token belongs to the unnamed agent alone, in every module, so
+    // `overrideProvider(Agent)` and `get(Agent)` never reach a named one.
+    // See #128 and #170.
+    if (!name) {
+      return {
+        ...dynamicModule,
+        providers: [...(dynamicModule.providers ?? []), nameProvider, Agent],
+        exports: [...(dynamicModule.exports ?? []), Agent],
+      };
+    }
+
+    const agentToken = getAgentToken(name);
+
+    return {
+      ...dynamicModule,
+      providers: [
+        ...(dynamicModule.providers ?? []),
+        nameProvider,
+        { provide: agentToken, useClass: Agent },
+      ],
+      exports: [...(dynamicModule.exports ?? []), agentToken],
+    };
+  }
+}

package/lib/logging/index.ts

@@ -0,0 +1,2 @@
+export { observeToolCall, reportToolError } from './observe-tool-call.util.js';
+export { LOG_CONTEXT, messageOf, RunReporter } from './run-reporter.js';

package/lib/logging/observe-tool-call.util.ts

@@ -0,0 +1,59 @@
+import { ToolErrorEvent } from '../interfaces/agent-observer.interface.js';
+import { messageOf, RunReporter } from './run-reporter.js';
+
+interface ToolCall {
+  tool: string;
+  callId: string;
+  args: Record<string, unknown>;
+}
+
+/** Logs a failed tool call and hands it to the observer. */
+export const reportToolError = (
+  reporter: RunReporter,
+  event: Omit<ToolErrorEvent, 'agent'>,
+): void => {
+  reporter.logError(`${event.tool} failed: ${messageOf(event.error)}`);
+  reporter.notify((observer) =>
+    observer.onToolError?.({ agent: reporter.agent, ...event }),
+  );
+};
+
+/** Runs one tool call, reporting its start, then its end or its failure. */
+export const observeToolCall = async (
+  reporter: RunReporter,
+  { tool, callId, args }: ToolCall,
+  call: () => unknown,
+): Promise<unknown> => {
+  const { agent } = reporter;
+  const startedAt = Date.now();
+
+  reporter.notify((observer) =>
+    observer.onToolStart?.({ agent, tool, callId, args }),
+  );
+
+  try {
+    const output = await call();
+
+    reporter.notify((observer) =>
+      observer.onToolEnd?.({
+        agent,
+        tool,
+        callId,
+        output,
+        durationMs: Date.now() - startedAt,
+      }),
+    );
+
+    return output;
+  } catch (error) {
+    reportToolError(reporter, {
+      tool,
+      callId,
+      reason: 'threw',
+      error,
+      durationMs: Date.now() - startedAt,
+    });
+
+    throw error;
+  }
+};

package/lib/logging/run-reporter.ts

@@ -0,0 +1,56 @@
+import { LoggerService } from '@nestjs/common';
+import { AgentObserver } from '../interfaces/agent-observer.interface.js';
+
+export const LOG_CONTEXT = 'LangChainAgent';
+
+interface RunReporterInput {
+  logger: LoggerService;
+  agent: string;
+  /** Empty for the unnamed agent, `'MATH '` otherwise. */
+  prefix: string;
+  observer?: AgentObserver;
+}
+
+export const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+/** One agent's error log lines and its observer. */
+export class RunReporter {
+  constructor(private readonly input: RunReporterInput) {}
+
+  get agent(): string {
+    return this.input.agent;
+  }
+
+  /** One line per error, whatever the message holds. */
+  logError(message: string): void {
+    const line = message
+      .split('\n')
+      .map((part) => part.trim())
+      .filter(Boolean)
+      .join(' ');
+
+    this.input.logger.error(`${this.input.prefix}${line}`, LOG_CONTEXT);
+  }
+
+  /**
+   * Hands an event to the observer, if any. Never awaited: a throw or a
+   * rejection is logged and swallowed, never propagated into the run.
+   */
+  notify(call: (observer: AgentObserver) => void | Promise<void>): void {
+    const { observer } = this.input;
+
+    if (!observer) {
+      return;
+    }
+
+    const onFailure = (error: unknown) =>
+      this.logError(`the observer failed: ${messageOf(error)}`);
+
+    try {
+      void Promise.resolve(call(observer)).catch(onFailure);
+    } catch (error) {
+      onFailure(error);
+    }
+  }
+}

package/lib/run/index.ts

@@ -0,0 +1,2 @@
+export { summariseRun } from './run-summary.util.js';
+export type { RunSummary } from './run-summary.util.js';

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

@@ -0,0 +1,51 @@
+import { mergeUsageMetadata, UsageMetadata } from '@langchain/core/messages';
+
+// Structural rather than `BaseMessage`. See #52.
+interface MessageLike {
+  usage_metadata?: UsageMetadata;
+  tool_calls?: { name: string }[];
+}
+
+/** What a run did and cost. */
+export interface RunSummary {
+  /** Every tool call the model made, failed and unknown ones included. */
+  tools: string[];
+  /**
+   * Summed over the run's model calls; absent when the provider reports no
+   * usage.
+   */
+  tokens?: { input: number; output: number; total: number };
+}
+
+/**
+ * What a finished run cost, read off the messages it returned.
+ *
+ * @internal
+ * @param messages The messages of the finished run.
+ * @returns The tool calls the model made, 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);
+
+  if (reported.length === 0) {
+    return { tools };
+  }
+
+  // Seeded with zeros, so a field a provider left out counts as zero.
+  const usage = reported.reduce(mergeUsageMetadata, mergeUsageMetadata());
+
+  return {
+    tools,
+    tokens: {
+      input: usage.input_tokens,
+      output: usage.output_tokens,
+      total: usage.total_tokens,
+    },
+  };
+};

package/lib/tools/index.ts

@@ -0,0 +1,2 @@
+export { ToolDiscoveryService } from './tool-discovery.service.js';
+export { toolErrors, unknownTools } from './tool-errors.middleware.js';