@depup/ai 6.0.116-depup.0

package/src/agent/tool-loop-agent-settings.ts

@@ -0,0 +1,244 @@
+import {
+  FlexibleSchema,
+  MaybePromiseLike,
+  ProviderOptions,
+  SystemModelMessage,
+} from '@ai-sdk/provider-utils';
+import type {
+  OnFinishEvent,
+  OnStartEvent,
+  OnStepFinishEvent,
+  OnStepStartEvent,
+  OnToolCallFinishEvent,
+  OnToolCallStartEvent,
+} from '../generate-text/callback-events';
+import { Output } from '../generate-text/output';
+import { PrepareStepFunction } from '../generate-text/prepare-step';
+import { StopCondition } from '../generate-text/stop-condition';
+import { ToolCallRepairFunction } from '../generate-text/tool-call-repair-function';
+import { ToolSet } from '../generate-text/tool-set';
+import { CallSettings } from '../prompt/call-settings';
+import { Prompt } from '../prompt/prompt';
+import { TelemetrySettings } from '../telemetry/telemetry-settings';
+import { LanguageModel, ToolChoice } from '../types/language-model';
+import { DownloadFunction } from '../util/download/download-function';
+import { AgentCallParameters } from './agent';
+
+export type ToolLoopAgentOnStartCallback<
+  TOOLS extends ToolSet = ToolSet,
+  OUTPUT extends Output = Output,
+> = (event: OnStartEvent<TOOLS, OUTPUT>) => PromiseLike<void> | void;
+
+export type ToolLoopAgentOnStepStartCallback<
+  TOOLS extends ToolSet = ToolSet,
+  OUTPUT extends Output = Output,
+> = (event: OnStepStartEvent<TOOLS, OUTPUT>) => PromiseLike<void> | void;
+
+export type ToolLoopAgentOnToolCallStartCallback<
+  TOOLS extends ToolSet = ToolSet,
+> = (event: OnToolCallStartEvent<TOOLS>) => PromiseLike<void> | void;
+
+export type ToolLoopAgentOnToolCallFinishCallback<
+  TOOLS extends ToolSet = ToolSet,
+> = (event: OnToolCallFinishEvent<TOOLS>) => PromiseLike<void> | void;
+
+export type ToolLoopAgentOnStepFinishCallback<TOOLS extends ToolSet = {}> = (
+  stepResult: OnStepFinishEvent<TOOLS>,
+) => Promise<void> | void;
+
+export type ToolLoopAgentOnFinishCallback<TOOLS extends ToolSet = {}> = (
+  event: OnFinishEvent<TOOLS>,
+) => PromiseLike<void> | void;
+
+/**
+ * Configuration options for an agent.
+ */
+export type ToolLoopAgentSettings<
+  CALL_OPTIONS = never,
+  TOOLS extends ToolSet = {},
+  OUTPUT extends Output = never,
+> = Omit<CallSettings, 'abortSignal'> & {
+  /**
+   * The id of the agent.
+   */
+  id?: string;
+
+  /**
+   * The instructions for the agent.
+   *
+   * It can be a string, or, if you need to pass additional provider options (e.g. for caching), a `SystemModelMessage`.
+   */
+  instructions?: string | SystemModelMessage | Array<SystemModelMessage>;
+
+  /**
+   * The language model to use.
+   */
+  model: LanguageModel;
+
+  /**
+   * The tools that the model can call. The model needs to support calling tools.
+   */
+  tools?: TOOLS;
+
+  /**
+   * The tool choice strategy. Default: 'auto'.
+   */
+  toolChoice?: ToolChoice<NoInfer<TOOLS>>;
+
+  /**
+   * Condition for stopping the generation when there are tool results in the last step.
+   * When the condition is an array, any of the conditions can be met to stop the generation.
+   *
+   * @default stepCountIs(20)
+   */
+  stopWhen?:
+    | StopCondition<NoInfer<TOOLS>>
+    | Array<StopCondition<NoInfer<TOOLS>>>;
+
+  /**
+   * Optional telemetry configuration (experimental).
+   */
+  experimental_telemetry?: TelemetrySettings;
+
+  /**
+   * Limits the tools that are available for the model to call without
+   * changing the tool call and result types in the result.
+   */
+  activeTools?: Array<keyof NoInfer<TOOLS>>;
+
+  /**
+   * Optional specification for generating structured outputs.
+   */
+  output?: OUTPUT;
+
+  /**
+   * Optional function that you can use to provide different settings for a step.
+   */
+  prepareStep?: PrepareStepFunction<NoInfer<TOOLS>>;
+
+  /**
+   * A function that attempts to repair a tool call that failed to parse.
+   */
+  experimental_repairToolCall?: ToolCallRepairFunction<NoInfer<TOOLS>>;
+
+  /**
+   * Callback that is called when the agent operation begins, before any LLM calls.
+   */
+  experimental_onStart?: ToolLoopAgentOnStartCallback<NoInfer<TOOLS>, OUTPUT>;
+
+  /**
+   * Callback that is called when a step (LLM call) begins, before the provider is called.
+   */
+  experimental_onStepStart?: ToolLoopAgentOnStepStartCallback<
+    NoInfer<TOOLS>,
+    OUTPUT
+  >;
+
+  /**
+   * Callback that is called before each tool execution begins.
+   */
+  experimental_onToolCallStart?: ToolLoopAgentOnToolCallStartCallback<
+    NoInfer<TOOLS>
+  >;
+
+  /**
+   * Callback that is called after each tool execution completes.
+   */
+  experimental_onToolCallFinish?: ToolLoopAgentOnToolCallFinishCallback<
+    NoInfer<TOOLS>
+  >;
+
+  /**
+   * Callback that is called when each step (LLM call) is finished, including intermediate steps.
+   */
+  onStepFinish?: ToolLoopAgentOnStepFinishCallback<NoInfer<TOOLS>>;
+
+  /**
+   * Callback that is called when all steps are finished and the response is complete.
+   */
+  onFinish?: ToolLoopAgentOnFinishCallback<NoInfer<TOOLS>>;
+
+  /**
+   * Additional provider-specific options. They are passed through
+   * to the provider from the AI SDK and enable provider-specific
+   * functionality that can be fully encapsulated in the provider.
+   */
+  providerOptions?: ProviderOptions;
+
+  /**
+   * Context that is passed into tool calls.
+   *
+   * Experimental (can break in patch releases).
+   *
+   * @default undefined
+   */
+  experimental_context?: unknown;
+
+  /**
+   * Custom download function to use for URLs.
+   *
+   * By default, files are downloaded if the model does not support the URL for the given media type.
+   */
+  experimental_download?: DownloadFunction | undefined;
+
+  /**
+   * The schema for the call options.
+   */
+  callOptionsSchema?: FlexibleSchema<CALL_OPTIONS>;
+
+  /**
+   * Prepare the parameters for the generateText or streamText call.
+   *
+   * You can use this to have templates based on call options.
+   */
+  prepareCall?: (
+    options: Omit<
+      AgentCallParameters<CALL_OPTIONS, NoInfer<TOOLS>>,
+      'onStepFinish'
+    > &
+      Pick<
+        ToolLoopAgentSettings<CALL_OPTIONS, TOOLS, OUTPUT>,
+        | 'model'
+        | 'tools'
+        | 'maxOutputTokens'
+        | 'temperature'
+        | 'topP'
+        | 'topK'
+        | 'presencePenalty'
+        | 'frequencyPenalty'
+        | 'stopSequences'
+        | 'seed'
+        | 'headers'
+        | 'instructions'
+        | 'stopWhen'
+        | 'experimental_telemetry'
+        | 'activeTools'
+        | 'providerOptions'
+        | 'experimental_context'
+        | 'experimental_download'
+      >,
+  ) => MaybePromiseLike<
+    Pick<
+      ToolLoopAgentSettings<CALL_OPTIONS, TOOLS, OUTPUT>,
+      | 'model'
+      | 'tools'
+      | 'maxOutputTokens'
+      | 'temperature'
+      | 'topP'
+      | 'topK'
+      | 'presencePenalty'
+      | 'frequencyPenalty'
+      | 'stopSequences'
+      | 'seed'
+      | 'headers'
+      | 'instructions'
+      | 'stopWhen'
+      | 'experimental_telemetry'
+      | 'activeTools'
+      | 'providerOptions'
+      | 'experimental_context'
+      | 'experimental_download'
+    > &
+      Omit<Prompt, 'system'>
+  >;
+};

package/src/agent/tool-loop-agent.ts

@@ -0,0 +1,206 @@
+import { generateText } from '../generate-text/generate-text';
+import { GenerateTextResult } from '../generate-text/generate-text-result';
+import { Output } from '../generate-text/output';
+import { stepCountIs } from '../generate-text/stop-condition';
+import { streamText } from '../generate-text/stream-text';
+import { StreamTextResult } from '../generate-text/stream-text-result';
+import { ToolSet } from '../generate-text/tool-set';
+import { Prompt } from '../prompt';
+import { Agent, AgentCallParameters, AgentStreamParameters } from './agent';
+import { ToolLoopAgentSettings } from './tool-loop-agent-settings';
+
+/**
+ * A tool loop agent is an agent that runs tools in a loop. In each step,
+ * it calls the LLM, and if there are tool calls, it executes the tools
+ * and calls the LLM again in a new step with the tool results.
+ *
+ * The loop continues until:
+ * - A finish reasoning other than tool-calls is returned, or
+ * - A tool that is invoked does not have an execute function, or
+ * - A tool call needs approval, or
+ * - A stop condition is met (default stop condition is stepCountIs(20))
+ */
+export class ToolLoopAgent<
+  CALL_OPTIONS = never,
+  TOOLS extends ToolSet = {},
+  OUTPUT extends Output = never,
+> implements Agent<CALL_OPTIONS, TOOLS, OUTPUT>
+{
+  readonly version = 'agent-v1';
+
+  private readonly settings: ToolLoopAgentSettings<CALL_OPTIONS, TOOLS, OUTPUT>;
+
+  constructor(settings: ToolLoopAgentSettings<CALL_OPTIONS, TOOLS, OUTPUT>) {
+    this.settings = settings;
+  }
+
+  /**
+   * The id of the agent.
+   */
+  get id(): string | undefined {
+    return this.settings.id;
+  }
+
+  /**
+   * The tools that the agent can use.
+   */
+  get tools(): TOOLS {
+    return this.settings.tools as TOOLS;
+  }
+
+  private async prepareCall(options: {
+    prompt?: string | Array<import('@ai-sdk/provider-utils').ModelMessage>;
+    messages?: Array<import('@ai-sdk/provider-utils').ModelMessage>;
+    options?: CALL_OPTIONS;
+  }): Promise<
+    Omit<
+      ToolLoopAgentSettings<CALL_OPTIONS, TOOLS, OUTPUT>,
+      | 'prepareCall'
+      | 'instructions'
+      | 'experimental_onStart'
+      | 'experimental_onStepStart'
+      | 'experimental_onToolCallStart'
+      | 'experimental_onToolCallFinish'
+      | 'onStepFinish'
+      | 'onFinish'
+    > &
+      Prompt
+  > {
+    const {
+      experimental_onStart: _settingsOnStart,
+      experimental_onStepStart: _settingsOnStepStart,
+      experimental_onToolCallStart: _settingsOnToolCallStart,
+      experimental_onToolCallFinish: _settingsOnToolCallFinish,
+      onStepFinish: _settingsOnStepFinish,
+      onFinish: _settingsOnFinish,
+      ...settingsWithoutCallbacks
+    } = this.settings;
+
+    const baseCallArgs = {
+      ...settingsWithoutCallbacks,
+      stopWhen: this.settings.stopWhen ?? stepCountIs(20),
+      ...options,
+    };
+
+    const preparedCallArgs =
+      (await this.settings.prepareCall?.(
+        baseCallArgs as Parameters<
+          NonNullable<
+            ToolLoopAgentSettings<CALL_OPTIONS, TOOLS, OUTPUT>['prepareCall']
+          >
+        >[0],
+      )) ?? baseCallArgs;
+
+    const { instructions, messages, prompt, ...callArgs } = preparedCallArgs;
+
+    return {
+      ...callArgs,
+
+      // restore prompt types
+      ...({ system: instructions, messages, prompt } as Prompt),
+    };
+  }
+
+  private mergeCallbacks<T extends (event: any) => PromiseLike<void> | void>(
+    settingsCallback: T | undefined,
+    methodCallback: T | undefined,
+  ): T | undefined {
+    if (methodCallback && settingsCallback) {
+      return (async (event: Parameters<T>[0]) => {
+        await settingsCallback(event);
+        await methodCallback(event);
+      }) as unknown as T;
+    }
+    return methodCallback ?? settingsCallback;
+  }
+
+  /**
+   * Generates an output from the agent (non-streaming).
+   */
+  async generate({
+    abortSignal,
+    timeout,
+    experimental_onStart,
+    experimental_onStepStart,
+    experimental_onToolCallStart,
+    experimental_onToolCallFinish,
+    onStepFinish,
+    onFinish,
+    ...options
+  }: AgentCallParameters<CALL_OPTIONS, TOOLS>): Promise<
+    GenerateTextResult<TOOLS, OUTPUT>
+  > {
+    return generateText({
+      ...(await this.prepareCall(options)),
+      abortSignal,
+      timeout,
+      experimental_onStart: this.mergeCallbacks(
+        this.settings.experimental_onStart,
+        experimental_onStart,
+      ),
+      experimental_onStepStart: this.mergeCallbacks(
+        this.settings.experimental_onStepStart,
+        experimental_onStepStart,
+      ),
+      experimental_onToolCallStart: this.mergeCallbacks(
+        this.settings.experimental_onToolCallStart,
+        experimental_onToolCallStart,
+      ),
+      experimental_onToolCallFinish: this.mergeCallbacks(
+        this.settings.experimental_onToolCallFinish,
+        experimental_onToolCallFinish,
+      ),
+      onStepFinish: this.mergeCallbacks(
+        this.settings.onStepFinish,
+        onStepFinish,
+      ),
+      onFinish: this.mergeCallbacks(this.settings.onFinish, onFinish),
+    });
+  }
+
+  /**
+   * Streams an output from the agent (streaming).
+   */
+  async stream({
+    abortSignal,
+    timeout,
+    experimental_transform,
+    experimental_onStart,
+    experimental_onStepStart,
+    experimental_onToolCallStart,
+    experimental_onToolCallFinish,
+    onStepFinish,
+    onFinish,
+    ...options
+  }: AgentStreamParameters<CALL_OPTIONS, TOOLS>): Promise<
+    StreamTextResult<TOOLS, OUTPUT>
+  > {
+    return streamText({
+      ...(await this.prepareCall(options)),
+      abortSignal,
+      timeout,
+      experimental_transform,
+      experimental_onStart: this.mergeCallbacks(
+        this.settings.experimental_onStart,
+        experimental_onStart,
+      ),
+      experimental_onStepStart: this.mergeCallbacks(
+        this.settings.experimental_onStepStart,
+        experimental_onStepStart,
+      ),
+      experimental_onToolCallStart: this.mergeCallbacks(
+        this.settings.experimental_onToolCallStart,
+        experimental_onToolCallStart,
+      ),
+      experimental_onToolCallFinish: this.mergeCallbacks(
+        this.settings.experimental_onToolCallFinish,
+        experimental_onToolCallFinish,
+      ),
+      onStepFinish: this.mergeCallbacks(
+        this.settings.onStepFinish,
+        onStepFinish,
+      ),
+      onFinish: this.mergeCallbacks(this.settings.onFinish, onFinish),
+    });
+  }
+}

package/src/embed/embed-many-result.ts

@@ -0,0 +1,53 @@
+import { Embedding } from '../types';
+import { EmbeddingModelUsage } from '../types/usage';
+import { ProviderMetadata } from '../types';
+import { Warning } from '../types/warning';
+
+/**
+ * The result of an `embedMany` call.
+ * It contains the embeddings, the values, and additional information.
+ */
+export interface EmbedManyResult {
+  /**
+   * The values that were embedded.
+   */
+  readonly values: Array<string>;
+
+  /**
+   * The embeddings. They are in the same order as the values.
+   */
+  readonly embeddings: Array<Embedding>;
+
+  /**
+   * The embedding token usage.
+   */
+  readonly usage: EmbeddingModelUsage;
+
+  /**
+   * Warnings for the call, e.g. unsupported settings.
+   */
+  readonly warnings: Array<Warning>;
+
+  /**
+   * Optional provider-specific metadata.
+   */
+  readonly providerMetadata?: ProviderMetadata;
+
+  /**
+   * Optional raw response data.
+   */
+  readonly responses?: Array<
+    | {
+        /**
+         * Response headers.
+         */
+        headers?: Record<string, string>;
+
+        /**
+         * The response body.
+         */
+        body?: unknown;
+      }
+    | undefined
+  >;
+}