@fondation-io/ai 7.0.0-beta.45

package/src/telemetry/record-span.ts

@@ -0,0 +1,75 @@
+import {
+  Attributes,
+  Span,
+  Tracer,
+  SpanStatusCode,
+  context,
+} from '@opentelemetry/api';
+
+export async function recordSpan<T>({
+  name,
+  tracer,
+  attributes,
+  fn,
+  endWhenDone = true,
+}: {
+  name: string;
+  tracer: Tracer;
+  attributes: Attributes | PromiseLike<Attributes>;
+  fn: (span: Span) => Promise<T>;
+  endWhenDone?: boolean;
+}) {
+  return tracer.startActiveSpan(
+    name,
+    { attributes: await attributes },
+    async span => {
+      // Capture the current context to maintain it across async generator yields
+      const ctx = context.active();
+
+      try {
+        // Execute within the captured context to ensure async generators
+        // don't lose the active span when they yield
+        const result = await context.with(ctx, () => fn(span));
+
+        if (endWhenDone) {
+          span.end();
+        }
+
+        return result;
+      } catch (error) {
+        try {
+          recordErrorOnSpan(span, error);
+        } finally {
+          // always stop the span when there is an error:
+          span.end();
+        }
+
+        throw error;
+      }
+    },
+  );
+}
+
+/**
+ * Record an error on a span. Sets the span status to error. If the error is
+ * an instance of Error, an exception event with name, message, and stack
+ * will also be recorded.
+ *
+ * @param span - The span to record the error on.
+ * @param error - The error to record on the span.
+ */
+export function recordErrorOnSpan(span: Span, error: unknown) {
+  if (error instanceof Error) {
+    span.recordException({
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+    });
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error.message,
+    });
+  } else {
+    span.setStatus({ code: SpanStatusCode.ERROR });
+  }
+}

package/src/telemetry/select-telemetry-attributes.ts

@@ -0,0 +1,78 @@
+import type { Attributes, AttributeValue } from '@opentelemetry/api';
+import type { TelemetrySettings } from './telemetry-settings';
+
+type ResolvableAttributeValue = () =>
+  | AttributeValue
+  | PromiseLike<AttributeValue>
+  | undefined;
+
+export async function selectTelemetryAttributes({
+  telemetry,
+  attributes,
+}: {
+  telemetry?: TelemetrySettings;
+  attributes: {
+    [attributeKey: string]:
+      | AttributeValue
+      | { input: ResolvableAttributeValue }
+      | { output: ResolvableAttributeValue }
+      | undefined;
+  };
+}): Promise<Attributes> {
+  // when telemetry is disabled, return an empty object to avoid serialization overhead:
+  if (telemetry?.isEnabled !== true) {
+    return {};
+  }
+
+  const resultAttributes: Attributes = {};
+
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value == null) {
+      continue;
+    }
+
+    // input value, check if it should be recorded:
+    if (
+      typeof value === 'object' &&
+      'input' in value &&
+      typeof value.input === 'function'
+    ) {
+      // default to true:
+      if (telemetry?.recordInputs === false) {
+        continue;
+      }
+
+      const result = await value.input();
+
+      if (result != null) {
+        resultAttributes[key] = result;
+      }
+
+      continue;
+    }
+
+    // output value, check if it should be recorded:
+    if (
+      typeof value === 'object' &&
+      'output' in value &&
+      typeof value.output === 'function'
+    ) {
+      // default to true:
+      if (telemetry?.recordOutputs === false) {
+        continue;
+      }
+
+      const result = await value.output();
+
+      if (result != null) {
+        resultAttributes[key] = result;
+      }
+      continue;
+    }
+
+    // value is an attribute value already:
+    resultAttributes[key] = value as AttributeValue;
+  }
+
+  return resultAttributes;
+}

package/src/telemetry/stringify-for-telemetry.ts

@@ -0,0 +1,33 @@
+import {
+  LanguageModelV4Message,
+  LanguageModelV4Prompt,
+} from '@ai-sdk/provider';
+import { convertDataContentToBase64String } from '../prompt/data-content';
+
+/**
+ * Helper utility to serialize prompt content for OpenTelemetry tracing.
+ * It is initially created because normalized LanguageModelV4Prompt carries
+ * images as Uint8Arrays, on which JSON.stringify acts weirdly, converting
+ * them to objects with stringified indices as keys, e.g. {"0": 42, "1": 69 }.
+ */
+export function stringifyForTelemetry(prompt: LanguageModelV4Prompt): string {
+  return JSON.stringify(
+    prompt.map((message: LanguageModelV4Message) => ({
+      ...message,
+      content:
+        typeof message.content === 'string'
+          ? message.content
+          : message.content.map(part =>
+              part.type === 'file'
+                ? {
+                    ...part,
+                    data:
+                      part.data instanceof Uint8Array
+                        ? convertDataContentToBase64String(part.data)
+                        : part.data,
+                  }
+                : part,
+            ),
+    })),
+  );
+}

package/src/telemetry/telemetry-integration-registry.ts

@@ -0,0 +1,22 @@
+import type { TelemetryIntegration } from './telemetry-integration';
+
+/**
+ * Registers a telemetry integration globally.
+ */
+export function registerTelemetryIntegration(
+  integration: TelemetryIntegration,
+): void {
+  if (!globalThis.AI_SDK_TELEMETRY_INTEGRATIONS) {
+    globalThis.AI_SDK_TELEMETRY_INTEGRATIONS = [];
+  }
+  globalThis.AI_SDK_TELEMETRY_INTEGRATIONS.push(integration);
+}
+
+export function getGlobalTelemetryIntegrations(): TelemetryIntegration[] {
+  return globalThis.AI_SDK_TELEMETRY_INTEGRATIONS ?? [];
+}
+
+// TODO remove when OTel is moved to a separate package
+export function hasIntegration(integration: TelemetryIntegration): boolean {
+  return (globalThis.AI_SDK_TELEMETRY_INTEGRATIONS ?? []).includes(integration);
+}

package/src/telemetry/telemetry-integration.ts

@@ -0,0 +1,139 @@
+import type {
+  OnChunkEvent,
+  OnFinishEvent,
+  OnStartEvent,
+  OnStepFinishEvent,
+  OnStepStartEvent,
+  OnToolCallFinishEvent,
+  OnToolCallStartEvent,
+} from '../generate-text/core-events';
+import type { Output } from '../generate-text/output';
+import type { ToolSet } from '../generate-text/tool-set';
+import type {
+  EmbedOnStartEvent,
+  EmbedOnFinishEvent,
+  EmbedStartEvent,
+  EmbedFinishEvent,
+} from '../embed/embed-events';
+import type {
+  RerankOnStartEvent,
+  RerankOnFinishEvent,
+  RerankStartEvent,
+  RerankFinishEvent,
+} from '../rerank/rerank-events';
+import { Listener } from '../util/notify';
+
+/**
+ * Implement this interface to create custom telemetry integrations.
+ * Methods can be sync or return a PromiseLike.
+ */
+export interface TelemetryIntegration {
+  /**
+   * Called when an operation begins. Fired for both text generation
+   * (generateText/streamText) and embedding (embed/embedMany) operations.
+   *
+   * Use the `operationId` field to distinguish between operation types.
+   */
+  onStart?: Listener<
+    OnStartEvent<ToolSet, Output> | EmbedOnStartEvent | RerankOnStartEvent
+  >;
+
+  /**
+   * Called when an individual step (single LLM invocation) begins.
+   * A generation may consist of multiple steps (e.g. when tool calls trigger
+   * follow-up LLM calls). Use this to create per-step spans or record
+   * step-level inputs.
+   *
+   * The event includes the step number, accumulated previous step results,
+   * and the messages that will be sent to the model.
+   */
+  onStepStart?: Listener<OnStepStartEvent<ToolSet, Output>>;
+
+  /**
+   * Called when a tool execution begins, before the tool's `execute` function
+   * is invoked. Use this to create tool-level spans or log tool invocations.
+   */
+  onToolCallStart?: Listener<OnToolCallStartEvent<ToolSet>>;
+
+  /**
+   * Called when a tool execution completes, either successfully or with an error.
+   * The event uses a discriminated union on the `success` field — check
+   * `event.success` to determine whether `output` or `error` is available.
+   *
+   * The event includes execution duration (`durationMs`) for performance tracking.
+   */
+  onToolCallFinish?: Listener<OnToolCallFinishEvent<ToolSet>>;
+
+  /**
+   * Called for each chunk received during streaming.
+   * Only relevant for `streamText` — not called during `generateText`.
+   */
+  onChunk?: Listener<OnChunkEvent>;
+
+  /**
+   * Called when an individual step (single LLM invocation) completes.
+   * The event is a `StepResult` containing the model's response, tool calls
+   * and results, usage statistics, finish reason, and optional request/response
+   * bodies.
+   */
+  onStepFinish?: Listener<OnStepFinishEvent<ToolSet>>;
+
+  /**
+   * Called when an individual embedding model call (doEmbed) begins.
+   * For `embed`, there is one call. For `embedMany`, there may be multiple
+   * calls when values are chunked.
+   */
+  onEmbedStart?: Listener<EmbedStartEvent>;
+
+  /**
+   * Called when an individual embedding model call (doEmbed) completes.
+   * Contains the embeddings, usage, and any warnings from the model response.
+   */
+  onEmbedFinish?: Listener<EmbedFinishEvent>;
+
+  /**
+   * Called when an individual reranking model call (doRerank) begins.
+   * There is one call per `rerank` invocation.
+   */
+  onRerankStart?: Listener<RerankStartEvent>;
+
+  /**
+   * Called when an individual reranking model call (doRerank) completes.
+   * Contains the ranking results from the model response.
+   */
+  onRerankFinish?: Listener<RerankFinishEvent>;
+
+  /**
+   * Called when an operation completes. Fired for both text generation
+   * (generateText/streamText) and embedding (embed/embedMany) operations.
+   *
+   * Use the event shape or `operationId` to distinguish between operation types.
+   */
+  onFinish?: Listener<
+    OnFinishEvent<ToolSet> | EmbedOnFinishEvent | RerankOnFinishEvent
+  >;
+
+  /**
+   * Called when an unrecoverable error occurs during the generation lifecycle.
+   * The error value is untyped — it may be an `Error` instance, an `AISDKError`,
+   * or any thrown value.
+   *
+   * Use this to record error details on telemetry spans and set error status.
+   */
+  onError?: Listener<unknown>;
+
+  /**
+   * Optionally runs the tool execute function in a telemetry-integration-specific context. This enables
+   * nested traces — e.g. when a tool's `execute` function calls `generateText`,
+   * the inner call's spans become children of the tool span.
+   *
+   * @param params.callId - The call ID of the tool call.
+   * @param params.toolCallId - The tool call ID.
+   * @param params.execute - The function to execute.
+   */
+  executeTool?: <T>(params: {
+    callId: string;
+    toolCallId: string;
+    execute: () => PromiseLike<T>;
+  }) => PromiseLike<T>;
+}

package/src/telemetry/telemetry-settings.ts

@@ -0,0 +1,55 @@
+import type { JSONValue } from '@ai-sdk/provider';
+import type { Tracer } from '@opentelemetry/api';
+import type { TelemetryIntegration } from './telemetry-integration';
+
+/**
+ * Telemetry configuration.
+ */
+// This is meant to be both flexible for custom app requirements (metadata)
+// and extensible for standardization (example: functionId, more to come).
+export type TelemetrySettings = {
+  /**
+   * Enable or disable telemetry. Disabled by default while experimental.
+   */
+  isEnabled?: boolean;
+
+  /**
+   * Enable or disable input recording. Enabled by default.
+   *
+   * You might want to disable input recording to avoid recording sensitive
+   * information, to reduce data transfers, or to increase performance.
+   */
+  recordInputs?: boolean;
+
+  /**
+   * Enable or disable output recording. Enabled by default.
+   *
+   * You might want to disable output recording to avoid recording sensitive
+   * information, to reduce data transfers, or to increase performance.
+   */
+  recordOutputs?: boolean;
+
+  /**
+   * Identifier for this function. Used to group telemetry data by function.
+   */
+  functionId?: string;
+
+  /**
+   * Additional information to include in the telemetry data.
+   */
+  metadata?: Record<string, JSONValue>;
+
+  /**
+   * A custom tracer to use for the telemetry data.
+   */
+  // TODO remove tracer (all ai functions need to be updated)
+  tracer?: Tracer;
+
+  /**
+   * Per-call telemetry integrations that receive lifecycle events during generation.
+   *
+   * These integrations run after any globally registered integrations
+   * (see `registerTelemetryIntegration`).
+   */
+  integrations?: TelemetryIntegration | TelemetryIntegration[];
+};

package/src/test/mock-embedding-model-v2.ts

@@ -0,0 +1,35 @@
+import { EmbeddingModelV2 } from '@ai-sdk/provider';
+import { notImplemented } from './not-implemented';
+
+export class MockEmbeddingModelV2<VALUE> implements EmbeddingModelV2<VALUE> {
+  readonly specificationVersion = 'v2';
+
+  readonly provider: EmbeddingModelV2<VALUE>['provider'];
+  readonly modelId: EmbeddingModelV2<VALUE>['modelId'];
+  readonly maxEmbeddingsPerCall: EmbeddingModelV2<VALUE>['maxEmbeddingsPerCall'];
+  readonly supportsParallelCalls: EmbeddingModelV2<VALUE>['supportsParallelCalls'];
+
+  doEmbed: EmbeddingModelV2<VALUE>['doEmbed'];
+
+  constructor({
+    provider = 'mock-provider',
+    modelId = 'mock-model-id',
+    maxEmbeddingsPerCall = 1,
+    supportsParallelCalls = false,
+    doEmbed = notImplemented,
+  }: {
+    provider?: EmbeddingModelV2<VALUE>['provider'];
+    modelId?: EmbeddingModelV2<VALUE>['modelId'];
+    maxEmbeddingsPerCall?:
+      | EmbeddingModelV2<VALUE>['maxEmbeddingsPerCall']
+      | null;
+    supportsParallelCalls?: EmbeddingModelV2<VALUE>['supportsParallelCalls'];
+    doEmbed?: EmbeddingModelV2<VALUE>['doEmbed'];
+  } = {}) {
+    this.provider = provider;
+    this.modelId = modelId;
+    this.maxEmbeddingsPerCall = maxEmbeddingsPerCall ?? undefined;
+    this.supportsParallelCalls = supportsParallelCalls;
+    this.doEmbed = doEmbed;
+  }
+}

package/src/test/mock-embedding-model-v3.ts

@@ -0,0 +1,48 @@
+import { EmbeddingModelV3 } from '@ai-sdk/provider';
+import { notImplemented } from './not-implemented';
+
+export class MockEmbeddingModelV3 implements EmbeddingModelV3 {
+  readonly specificationVersion = 'v3';
+
+  readonly provider: EmbeddingModelV3['provider'];
+  readonly modelId: EmbeddingModelV3['modelId'];
+  readonly maxEmbeddingsPerCall: EmbeddingModelV3['maxEmbeddingsPerCall'];
+  readonly supportsParallelCalls: EmbeddingModelV3['supportsParallelCalls'];
+
+  doEmbed: EmbeddingModelV3['doEmbed'];
+
+  doEmbedCalls: Parameters<EmbeddingModelV3['doEmbed']>[0][] = [];
+
+  constructor({
+    provider = 'mock-provider',
+    modelId = 'mock-model-id',
+    maxEmbeddingsPerCall = 1,
+    supportsParallelCalls = false,
+    doEmbed = notImplemented,
+  }: {
+    provider?: EmbeddingModelV3['provider'];
+    modelId?: EmbeddingModelV3['modelId'];
+    maxEmbeddingsPerCall?: EmbeddingModelV3['maxEmbeddingsPerCall'] | null;
+    supportsParallelCalls?: EmbeddingModelV3['supportsParallelCalls'];
+    doEmbed?:
+      | EmbeddingModelV3['doEmbed']
+      | Awaited<ReturnType<EmbeddingModelV3['doEmbed']>>
+      | Awaited<ReturnType<EmbeddingModelV3['doEmbed']>>[];
+  } = {}) {
+    this.provider = provider;
+    this.modelId = modelId;
+    this.maxEmbeddingsPerCall = maxEmbeddingsPerCall ?? undefined;
+    this.supportsParallelCalls = supportsParallelCalls;
+    this.doEmbed = async options => {
+      this.doEmbedCalls.push(options);
+
+      if (typeof doEmbed === 'function') {
+        return doEmbed(options);
+      } else if (Array.isArray(doEmbed)) {
+        return doEmbed[this.doEmbedCalls.length];
+      } else {
+        return doEmbed;
+      }
+    };
+  }
+}

package/src/test/mock-embedding-model-v4.ts

@@ -0,0 +1,48 @@
+import { EmbeddingModelV4 } from '@ai-sdk/provider';
+import { notImplemented } from './not-implemented';
+
+export class MockEmbeddingModelV4 implements EmbeddingModelV4 {
+  readonly specificationVersion = 'v4';
+
+  readonly provider: EmbeddingModelV4['provider'];
+  readonly modelId: EmbeddingModelV4['modelId'];
+  readonly maxEmbeddingsPerCall: EmbeddingModelV4['maxEmbeddingsPerCall'];
+  readonly supportsParallelCalls: EmbeddingModelV4['supportsParallelCalls'];
+
+  doEmbed: EmbeddingModelV4['doEmbed'];
+
+  doEmbedCalls: Parameters<EmbeddingModelV4['doEmbed']>[0][] = [];
+
+  constructor({
+    provider = 'mock-provider',
+    modelId = 'mock-model-id',
+    maxEmbeddingsPerCall = 1,
+    supportsParallelCalls = false,
+    doEmbed = notImplemented,
+  }: {
+    provider?: EmbeddingModelV4['provider'];
+    modelId?: EmbeddingModelV4['modelId'];
+    maxEmbeddingsPerCall?: EmbeddingModelV4['maxEmbeddingsPerCall'] | null;
+    supportsParallelCalls?: EmbeddingModelV4['supportsParallelCalls'];
+    doEmbed?:
+      | EmbeddingModelV4['doEmbed']
+      | Awaited<ReturnType<EmbeddingModelV4['doEmbed']>>
+      | Awaited<ReturnType<EmbeddingModelV4['doEmbed']>>[];
+  } = {}) {
+    this.provider = provider;
+    this.modelId = modelId;
+    this.maxEmbeddingsPerCall = maxEmbeddingsPerCall ?? undefined;
+    this.supportsParallelCalls = supportsParallelCalls;
+    this.doEmbed = async options => {
+      this.doEmbedCalls.push(options);
+
+      if (typeof doEmbed === 'function') {
+        return doEmbed(options);
+      } else if (Array.isArray(doEmbed)) {
+        return doEmbed[this.doEmbedCalls.length];
+      } else {
+        return doEmbed;
+      }
+    };
+  }
+}

package/src/test/mock-image-model-v2.ts

@@ -0,0 +1,28 @@
+import { ImageModelV2 } from '@ai-sdk/provider';
+import { notImplemented } from './not-implemented';
+
+export class MockImageModelV2 implements ImageModelV2 {
+  readonly specificationVersion = 'v2';
+  readonly provider: ImageModelV2['provider'];
+  readonly modelId: ImageModelV2['modelId'];
+  readonly maxImagesPerCall: ImageModelV2['maxImagesPerCall'];
+
+  doGenerate: ImageModelV2['doGenerate'];
+
+  constructor({
+    provider = 'mock-provider',
+    modelId = 'mock-model-id',
+    maxImagesPerCall = 1,
+    doGenerate = notImplemented,
+  }: {
+    provider?: ImageModelV2['provider'];
+    modelId?: ImageModelV2['modelId'];
+    maxImagesPerCall?: ImageModelV2['maxImagesPerCall'];
+    doGenerate?: ImageModelV2['doGenerate'];
+  } = {}) {
+    this.provider = provider;
+    this.modelId = modelId;
+    this.maxImagesPerCall = maxImagesPerCall;
+    this.doGenerate = doGenerate;
+  }
+}

package/src/test/mock-image-model-v3.ts

@@ -0,0 +1,28 @@
+import { ImageModelV3 } from '@ai-sdk/provider';
+import { notImplemented } from './not-implemented';
+
+export class MockImageModelV3 implements ImageModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly provider: ImageModelV3['provider'];
+  readonly modelId: ImageModelV3['modelId'];
+  readonly maxImagesPerCall: ImageModelV3['maxImagesPerCall'];
+
+  doGenerate: ImageModelV3['doGenerate'];
+
+  constructor({
+    provider = 'mock-provider',
+    modelId = 'mock-model-id',
+    maxImagesPerCall = 1,
+    doGenerate = notImplemented,
+  }: {
+    provider?: ImageModelV3['provider'];
+    modelId?: ImageModelV3['modelId'];
+    maxImagesPerCall?: ImageModelV3['maxImagesPerCall'];
+    doGenerate?: ImageModelV3['doGenerate'];
+  } = {}) {
+    this.provider = provider;
+    this.modelId = modelId;
+    this.maxImagesPerCall = maxImagesPerCall;
+    this.doGenerate = doGenerate;
+  }
+}

package/src/test/mock-image-model-v4.ts

@@ -0,0 +1,28 @@
+import { ImageModelV4 } from '@ai-sdk/provider';
+import { notImplemented } from './not-implemented';
+
+export class MockImageModelV4 implements ImageModelV4 {
+  readonly specificationVersion = 'v4';
+  readonly provider: ImageModelV4['provider'];
+  readonly modelId: ImageModelV4['modelId'];
+  readonly maxImagesPerCall: ImageModelV4['maxImagesPerCall'];
+
+  doGenerate: ImageModelV4['doGenerate'];
+
+  constructor({
+    provider = 'mock-provider',
+    modelId = 'mock-model-id',
+    maxImagesPerCall = 1,
+    doGenerate = notImplemented,
+  }: {
+    provider?: ImageModelV4['provider'];
+    modelId?: ImageModelV4['modelId'];
+    maxImagesPerCall?: ImageModelV4['maxImagesPerCall'];
+    doGenerate?: ImageModelV4['doGenerate'];
+  } = {}) {
+    this.provider = provider;
+    this.modelId = modelId;
+    this.maxImagesPerCall = maxImagesPerCall;
+    this.doGenerate = doGenerate;
+  }
+}