@fondation-io/ai 7.0.0-beta.45

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

@@ -0,0 +1,252 @@
+import {
+  FlexibleSchema,
+  MaybePromiseLike,
+  ProviderOptions,
+  SystemModelMessage,
+} from '@ai-sdk/provider-utils';
+import type {
+  OnFinishEvent,
+  OnStartEvent,
+  OnStepFinishEvent,
+  OnStepStartEvent,
+  OnToolCallFinishEvent,
+  OnToolCallStartEvent,
+} from '../generate-text/core-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, TimeoutConfiguration } 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'> & {
+  /**
+   * Timeout in milliseconds. The call will be aborted if it takes longer
+   * than the specified timeout. Can be used alongside abortSignal.
+   *
+   * Can be specified as a number (milliseconds) or as an object with `totalMs`.
+   */
+  timeout?: TimeoutConfiguration<TOOLS>;
+
+  /**
+   * 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,205 @@
+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-events.ts

@@ -0,0 +1,181 @@
+import type { JSONValue } from '@ai-sdk/provider';
+import type { ProviderOptions } from '@ai-sdk/provider-utils';
+import type { Embedding, ProviderMetadata } from '../types';
+import type { EmbeddingModelUsage } from '../types/usage';
+import type { Warning } from '../types/warning';
+
+/**
+ * Event passed to the `onStart` callback for embed and embedMany operations.
+ *
+ * Called when the operation begins, before the embedding model is called.
+ */
+export interface EmbedOnStartEvent {
+  /** Unique identifier for this embed call, used to correlate events. */
+  readonly callId: string;
+
+  /** Identifies the operation type (e.g. 'ai.embed' or 'ai.embedMany'). */
+  readonly operationId: string;
+
+  /** The provider identifier (e.g., 'openai', 'anthropic'). */
+  readonly provider: string;
+
+  /** The specific model identifier (e.g., 'text-embedding-3-small'). */
+  readonly modelId: string;
+
+  /** The value(s) being embedded. A string for embed, an array for embedMany. */
+  readonly value: string | Array<string>;
+
+  /** Maximum number of retries for failed requests. */
+  readonly maxRetries: number;
+
+  /** Abort signal for cancelling the operation. */
+  readonly abortSignal: AbortSignal | undefined;
+
+  /** Additional HTTP headers sent with the request. */
+  readonly headers: Record<string, string | undefined> | undefined;
+
+  /** Additional provider-specific options. */
+  readonly providerOptions: ProviderOptions | undefined;
+
+  /** Whether telemetry is enabled. */
+  readonly isEnabled: boolean | undefined;
+
+  /** Whether to record inputs in telemetry. Enabled by default. */
+  readonly recordInputs: boolean | undefined;
+
+  /** Whether to record outputs in telemetry. Enabled by default. */
+  readonly recordOutputs: boolean | undefined;
+
+  /** Identifier from telemetry settings for grouping related operations. */
+  readonly functionId: string | undefined;
+
+  /** Additional metadata from telemetry settings. */
+  readonly metadata: Record<string, JSONValue> | undefined;
+}
+
+/**
+ * Event passed to the `onFinish` callback for embed and embedMany operations.
+ *
+ * Called when the operation completes, after the embedding model returns.
+ */
+export interface EmbedOnFinishEvent {
+  /** Unique identifier for this embed call, used to correlate events. */
+  readonly callId: string;
+
+  /** Identifies the operation type (e.g. 'ai.embed' or 'ai.embedMany'). */
+  readonly operationId: string;
+
+  /** The provider identifier (e.g., 'openai', 'anthropic'). */
+  readonly provider: string;
+
+  /** The specific model identifier (e.g., 'text-embedding-3-small'). */
+  readonly modelId: string;
+
+  /** The value(s) that were embedded. A string for embed, an array for embedMany. */
+  readonly value: string | Array<string>;
+
+  /** The resulting embedding(s). A single vector for embed, an array for embedMany. */
+  readonly embedding: Embedding | Array<Embedding>;
+
+  /** Token usage for the embedding operation. */
+  readonly usage: EmbeddingModelUsage;
+
+  /** Warnings from the embedding model, e.g. unsupported settings. */
+  readonly warnings: Array<Warning>;
+
+  /** Optional provider-specific metadata. */
+  readonly providerMetadata: ProviderMetadata | undefined;
+
+  /** Response data including headers and body. A single response for embed, an array for embedMany. */
+  readonly response:
+    | { headers?: Record<string, string>; body?: unknown }
+    | Array<{ headers?: Record<string, string>; body?: unknown } | undefined>
+    | undefined;
+
+  /** Whether telemetry is enabled. */
+  readonly isEnabled: boolean | undefined;
+
+  /** Whether to record inputs in telemetry. Enabled by default. */
+  readonly recordInputs: boolean | undefined;
+
+  /** Whether to record outputs in telemetry. Enabled by default. */
+  readonly recordOutputs: boolean | undefined;
+
+  /** Identifier from telemetry settings for grouping related operations. */
+  readonly functionId: string | undefined;
+
+  /** Additional metadata from telemetry settings. */
+  readonly metadata: Record<string, JSONValue> | undefined;
+}
+
+/**
+ * Event fired when an individual embedding model call (inner operation doEmbed) begins.
+ *
+ * For `embed`, there is one call. For `embedMany`, there may be multiple
+ * calls when values are chunked.
+ */
+export interface EmbedStartEvent {
+  /** Unique identifier for this embed call, used to correlate events. */
+  readonly callId: string;
+
+  /** Unique identifier for this individual doEmbed invocation, used to correlate start/finish within parallel chunks. */
+  readonly embedCallId: string;
+
+  /** Identifies the inner operation (e.g. 'ai.embed.doEmbed' or 'ai.embedMany.doEmbed'). */
+  readonly operationId: string;
+
+  /** The provider identifier. */
+  readonly provider: string;
+
+  /** The specific model identifier. */
+  readonly modelId: string;
+
+  /** The values being embedded in this particular model call. */
+  readonly values: Array<string>;
+
+  /** Whether telemetry is enabled. */
+  readonly isEnabled: boolean | undefined;
+
+  /** Whether to record inputs in telemetry. Enabled by default. */
+  readonly recordInputs: boolean | undefined;
+
+  /** Whether to record outputs in telemetry. Enabled by default. */
+  readonly recordOutputs: boolean | undefined;
+
+  /** Identifier from telemetry settings for grouping related operations. */
+  readonly functionId: string | undefined;
+
+  /** Additional metadata from telemetry settings. */
+  readonly metadata: Record<string, JSONValue> | undefined;
+}
+
+/**
+ * Event fired when an individual embedding model call (doEmbed) completes.
+ *
+ * Contains the embeddings, usage, and any warnings from the model response.
+ */
+export interface EmbedFinishEvent {
+  /** Unique identifier for this embed call, used to correlate events. */
+  readonly callId: string;
+
+  /** Unique identifier for this individual doEmbed invocation, used to correlate start/finish within parallel chunks. */
+  readonly embedCallId: string;
+
+  /** Identifies the inner operation (e.g. 'ai.embed.doEmbed' or 'ai.embedMany.doEmbed'). */
+  readonly operationId: string;
+
+  /** The provider identifier. */
+  readonly provider: string;
+
+  /** The specific model identifier. */
+  readonly modelId: string;
+
+  /** The values that were embedded in this particular model call. */
+  readonly values: Array<string>;
+
+  /** The resulting embeddings from the model call. */
+  readonly embeddings: Array<Embedding>;
+
+  /** Token usage for this model call. */
+  readonly usage: EmbeddingModelUsage;
+}

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
+  >;
+}