@fondation-io/ai 7.0.0-beta.45

package/src/rerank/rerank-events.ts

@@ -0,0 +1,189 @@
+import type { JSONObject, JSONValue } from '@ai-sdk/provider';
+import type { ProviderOptions } from '@ai-sdk/provider-utils';
+import type { ProviderMetadata } from '../types';
+import type { Warning } from '../types/warning';
+
+/**
+ * Event passed to the `onStart` callback for rerank operations.
+ *
+ * Called when the operation begins, before the reranking model is called.
+ */
+export interface RerankOnStartEvent {
+  /** Unique identifier for this rerank call, used to correlate events. */
+  readonly callId: string;
+
+  /** Identifies the operation type ('ai.rerank'). */
+  readonly operationId: string;
+
+  //** The provider identifier (e.g., 'openai', 'anthropic'). */
+  readonly provider: string;
+
+  /** The specific model identifier (e.g., 'gpt-4o'). */
+  readonly modelId: string;
+  /** The documents being reranked. */
+  readonly documents: Array<JSONObject | string>;
+
+  /** The query to rerank the documents against. */
+  readonly query: string;
+
+  /** Number of top documents to return. */
+  readonly topN: number | undefined;
+
+  /** 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 rerank operations.
+ *
+ * Called when the operation completes, after the reranking model returns.
+ */
+export interface RerankOnFinishEvent {
+  /** Unique identifier for this rerank call, used to correlate events. */
+  readonly callId: string;
+
+  /** Identifies the operation type ('ai.rerank'). */
+  readonly operationId: string;
+
+  //** The provider identifier (e.g., 'openai', 'anthropic'). */
+  readonly provider: string;
+
+  /** The specific model identifier (e.g., 'gpt-4o'). */
+  readonly modelId: string;
+
+  /** The documents that were reranked. */
+  readonly documents: Array<JSONObject | string>;
+
+  /** The query that documents were reranked against. */
+  readonly query: string;
+
+  /** The reranked results sorted by relevance score in descending order. */
+  readonly ranking: Array<{
+    originalIndex: number;
+    score: number;
+    document: JSONObject | string;
+  }>;
+
+  /** Warnings from the reranking model. */
+  readonly warnings: Array<Warning>;
+
+  /** Optional provider-specific metadata. */
+  readonly providerMetadata: ProviderMetadata | undefined;
+
+  /** Response data including headers and body. */
+  readonly response: {
+    id?: string;
+    timestamp: Date;
+    modelId: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+  };
+
+  /** 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 reranking model call (inner doRerank) begins.
+ */
+export interface RerankStartEvent {
+  /** Unique identifier for this rerank call, used to correlate events. */
+  readonly callId: string;
+
+  /** Identifies the inner operation ('ai.rerank.doRerank'). */
+  readonly operationId: string;
+
+  /** The provider identifier. */
+  readonly provider: string;
+
+  /** The specific model identifier. */
+  readonly modelId: string;
+
+  /** The documents being reranked. */
+  readonly documents: Array<JSONObject | string>;
+
+  /** The type of documents ('text' or 'object'). */
+  readonly documentsType: string;
+
+  /** The query to rerank against. */
+  readonly query: string;
+
+  /** Number of top documents to return. */
+  readonly topN: number | 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 reranking model call (doRerank) completes.
+ *
+ * Contains the ranking results from the model response.
+ */
+export interface RerankFinishEvent {
+  /** Unique identifier for this rerank call, used to correlate events. */
+  readonly callId: string;
+
+  /** Identifies the inner operation ('ai.rerank.doRerank'). */
+  readonly operationId: string;
+
+  /** The provider identifier. */
+  readonly provider: string;
+
+  /** The specific model identifier. */
+  readonly modelId: string;
+
+  /** The type of documents ('text' or 'object'). */
+  readonly documentsType: string;
+
+  /** The ranking results from the model. */
+  readonly ranking: Array<{ index: number; relevanceScore: number }>;
+}

package/src/rerank/rerank-result.ts

@@ -0,0 +1,70 @@
+import { ProviderMetadata } from '../types/provider-metadata';
+
+/**
+ * The result of a `rerank` call.
+ * It contains the original documents, the reranked documents, and additional information.
+ */
+export interface RerankResult<VALUE> {
+  /**
+   * The original documents that were reranked.
+   */
+  readonly originalDocuments: Array<VALUE>;
+
+  /**
+   * Reranked documents.
+   *
+   * Sorted by relevance score in descending order.
+   *
+   * Can be less than the original documents if there was a topN limit.
+   */
+  readonly rerankedDocuments: Array<VALUE>;
+
+  /**
+   * The ranking is a list of objects with the original index,
+   * relevance score, and the reranked document.
+   *
+   * Sorted by relevance score in descending order.
+   *
+   * Can be less than the original documents if there was a topN limit.
+   */
+  readonly ranking: Array<{
+    originalIndex: number;
+    score: number;
+    document: VALUE;
+  }>;
+
+  /**
+   * Optional provider-specific metadata.
+   */
+  readonly providerMetadata?: ProviderMetadata;
+
+  /**
+   * Optional raw response data.
+   */
+  readonly response: {
+    /**
+     * ID for the generated response if the provider sends one.
+     */
+    id?: string;
+
+    /**
+     * Timestamp of the generated response.
+     */
+    timestamp: Date;
+
+    /**
+     * The ID of the model that was used to generate the response.
+     */
+    modelId: string;
+
+    /**
+     * Response headers.
+     */
+    headers?: Record<string, string>;
+
+    /**
+     * The response body.
+     */
+    body?: unknown;
+  };
+}

package/src/rerank/rerank.ts

@@ -0,0 +1,348 @@
+import { JSONObject, RerankingModelV4CallOptions } from '@ai-sdk/provider';
+import { createIdGenerator, ProviderOptions } from '@ai-sdk/provider-utils';
+import { prepareRetries } from '../../src/util/prepare-retries';
+import { logWarnings } from '../logger/log-warnings';
+import { getGlobalTelemetryIntegration } from '../telemetry/get-global-telemetry-integration';
+import { TelemetrySettings } from '../telemetry/telemetry-settings';
+import { RerankingModel } from '../types';
+import { notify } from '../util/notify';
+import type { Listener } from '../util/notify';
+import type { RerankOnFinishEvent, RerankOnStartEvent } from './rerank-events';
+import { RerankResult } from './rerank-result';
+
+const originalGenerateCallId = createIdGenerator({
+  prefix: 'call',
+  size: 24,
+});
+
+/**
+ * Rerank documents using a reranking model. The type of the value is defined by the reranking model.
+ *
+ * @param model - The reranking model to use.
+ * @param documents - The documents that should be reranked.
+ * @param query - The query to rerank the documents against.
+ * @param topN - Number of top documents to return.
+ *
+ * @param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
+ * @param abortSignal - An optional abort signal that can be used to cancel the call.
+ * @param headers - Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
+ * @param providerOptions - Additional provider-specific options.
+ * @param experimental_telemetry - Optional telemetry configuration (experimental).
+ *
+ * @returns A result object that contains the reranked documents, the reranked indices, and additional information.
+ */
+export async function rerank<VALUE extends JSONObject | string>({
+  model,
+  documents,
+  query,
+  topN,
+  maxRetries: maxRetriesArg,
+  abortSignal,
+  headers,
+  providerOptions,
+  experimental_telemetry: telemetry,
+  experimental_onStart: onStart,
+  experimental_onFinish: onFinish,
+  _internal: { generateCallId = originalGenerateCallId } = {},
+}: {
+  /**
+   * The reranking model to use.
+   */
+  model: RerankingModel;
+
+  /**
+   * The documents that should be reranked.
+   */
+  documents: Array<VALUE>;
+
+  /**
+   * The query to rerank the documents against.
+   */
+  query: string;
+
+  /**
+   * Number of top documents to return.
+   */
+  topN?: number;
+
+  /**
+   * Maximum number of retries per reranking model call. Set to 0 to disable retries.
+   *
+   * @default 2
+   */
+  maxRetries?: number;
+
+  /**
+   * Abort signal.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Additional headers to include in the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Optional telemetry configuration (experimental).
+   */
+  experimental_telemetry?: TelemetrySettings;
+
+  /**
+   * 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;
+
+  /**
+   * Callback that is called when the rerank operation begins,
+   * before the reranking model is called.
+   */
+  experimental_onStart?: Listener<RerankOnStartEvent>;
+
+  /**
+   * Callback that is called when the rerank operation completes,
+   * after the reranking model returns.
+   */
+  experimental_onFinish?: Listener<RerankOnFinishEvent>;
+
+  /**
+   * Internal. For test use only. May change without notice.
+   */
+  _internal?: {
+    generateCallId?: () => string;
+  };
+}): Promise<RerankResult<VALUE>> {
+  const callId = generateCallId();
+
+  const createGlobalTelemetry = getGlobalTelemetryIntegration();
+  const globalTelemetry = createGlobalTelemetry({
+    integrations: telemetry?.integrations,
+  });
+
+  if (documents.length === 0) {
+    await notify({
+      event: {
+        callId,
+        operationId: 'ai.rerank',
+        provider: model.provider,
+        modelId: model.modelId,
+        documents,
+        query,
+        topN,
+        maxRetries: maxRetriesArg ?? 2,
+        abortSignal,
+        headers,
+        providerOptions,
+        isEnabled: telemetry?.isEnabled,
+        recordInputs: telemetry?.recordInputs,
+        recordOutputs: telemetry?.recordOutputs,
+        functionId: telemetry?.functionId,
+        metadata: telemetry?.metadata,
+      },
+      callbacks: [onStart, globalTelemetry.onStart],
+    });
+
+    await notify({
+      event: {
+        callId,
+        operationId: 'ai.rerank',
+        provider: model.provider,
+        modelId: model.modelId,
+        documents,
+        query,
+        ranking: [],
+        warnings: [],
+        providerMetadata: undefined,
+        response: {
+          timestamp: new Date(),
+          modelId: model.modelId,
+        },
+        isEnabled: telemetry?.isEnabled,
+        recordInputs: telemetry?.recordInputs,
+        recordOutputs: telemetry?.recordOutputs,
+        functionId: telemetry?.functionId,
+        metadata: telemetry?.metadata,
+      },
+      callbacks: [onFinish, globalTelemetry.onFinish],
+    });
+
+    return new DefaultRerankResult({
+      originalDocuments: [],
+      ranking: [],
+      providerMetadata: undefined,
+      response: {
+        timestamp: new Date(),
+        modelId: model.modelId,
+      },
+    });
+  }
+
+  const { maxRetries, retry } = prepareRetries({
+    maxRetries: maxRetriesArg,
+    abortSignal,
+  });
+
+  const documentsToSend: RerankingModelV4CallOptions['documents'] =
+    typeof documents[0] === 'string'
+      ? { type: 'text', values: documents as string[] }
+      : { type: 'object', values: documents as JSONObject[] };
+
+  await notify({
+    event: {
+      callId,
+      operationId: 'ai.rerank',
+      provider: model.provider,
+      modelId: model.modelId,
+      documents,
+      query,
+      topN,
+      maxRetries,
+      abortSignal,
+      headers,
+      providerOptions,
+      isEnabled: telemetry?.isEnabled,
+      recordInputs: telemetry?.recordInputs,
+      recordOutputs: telemetry?.recordOutputs,
+      functionId: telemetry?.functionId,
+      metadata: telemetry?.metadata,
+    },
+    callbacks: [onStart, globalTelemetry.onStart],
+  });
+
+  try {
+    const { ranking, response, providerMetadata, warnings } = await retry(
+      async () => {
+        await notify({
+          event: {
+            callId,
+            operationId: 'ai.rerank.doRerank',
+            provider: model.provider,
+            modelId: model.modelId,
+            documents,
+            documentsType: documentsToSend.type,
+            query,
+            topN,
+            isEnabled: telemetry?.isEnabled,
+            recordInputs: telemetry?.recordInputs,
+            recordOutputs: telemetry?.recordOutputs,
+            functionId: telemetry?.functionId,
+            metadata: telemetry?.metadata,
+          },
+          callbacks: [globalTelemetry.onRerankStart],
+        });
+
+        const modelResponse = await model.doRerank({
+          documents: documentsToSend,
+          query,
+          topN,
+          providerOptions,
+          abortSignal,
+          headers,
+        });
+
+        const ranking = modelResponse.ranking;
+
+        await notify({
+          event: {
+            callId,
+            operationId: 'ai.rerank.doRerank',
+            provider: model.provider,
+            modelId: model.modelId,
+            documentsType: documentsToSend.type,
+            ranking,
+          },
+          callbacks: [globalTelemetry.onRerankFinish],
+        });
+
+        return {
+          ranking,
+          providerMetadata: modelResponse.providerMetadata,
+          response: modelResponse.response,
+          warnings: modelResponse.warnings,
+        };
+      },
+    );
+
+    logWarnings({
+      warnings: warnings ?? [],
+      provider: model.provider,
+      model: model.modelId,
+    });
+
+    await notify({
+      event: {
+        callId,
+        operationId: 'ai.rerank',
+        provider: model.provider,
+        modelId: model.modelId,
+        documents,
+        query,
+        ranking: ranking.map(r => ({
+          originalIndex: r.index,
+          score: r.relevanceScore,
+          document: documents[r.index],
+        })),
+        warnings: warnings ?? [],
+        providerMetadata,
+        response: {
+          id: response?.id,
+          timestamp: response?.timestamp ?? new Date(),
+          modelId: response?.modelId ?? model.modelId,
+          headers: response?.headers,
+          body: response?.body,
+        },
+        isEnabled: telemetry?.isEnabled,
+        recordInputs: telemetry?.recordInputs,
+        recordOutputs: telemetry?.recordOutputs,
+        functionId: telemetry?.functionId,
+        metadata: telemetry?.metadata,
+      },
+      callbacks: [onFinish, globalTelemetry.onFinish],
+    });
+
+    return new DefaultRerankResult({
+      originalDocuments: documents,
+      ranking: ranking.map(ranking => ({
+        originalIndex: ranking.index,
+        score: ranking.relevanceScore,
+        document: documents[ranking.index],
+      })),
+      providerMetadata,
+      response: {
+        id: response?.id,
+        timestamp: response?.timestamp ?? new Date(),
+        modelId: response?.modelId ?? model.modelId,
+        headers: response?.headers,
+        body: response?.body,
+      },
+    });
+  } catch (error) {
+    await globalTelemetry.onError?.({ callId, error });
+    throw error;
+  }
+}
+
+class DefaultRerankResult<VALUE> implements RerankResult<VALUE> {
+  readonly originalDocuments: RerankResult<VALUE>['originalDocuments'];
+  readonly ranking: RerankResult<VALUE>['ranking'];
+  readonly response: RerankResult<VALUE>['response'];
+  readonly providerMetadata: RerankResult<VALUE>['providerMetadata'];
+
+  constructor(options: {
+    originalDocuments: RerankResult<VALUE>['originalDocuments'];
+    ranking: RerankResult<VALUE>['ranking'];
+    providerMetadata?: RerankResult<VALUE>['providerMetadata'];
+    response: RerankResult<VALUE>['response'];
+  }) {
+    this.originalDocuments = options.originalDocuments;
+    this.ranking = options.ranking;
+    this.response = options.response;
+    this.providerMetadata = options.providerMetadata;
+  }
+
+  get rerankedDocuments(): RerankResult<VALUE>['rerankedDocuments'] {
+    return this.ranking.map(ranking => ranking.document);
+  }
+}

package/src/telemetry/assemble-operation-name.ts

@@ -0,0 +1,21 @@
+import { TelemetrySettings } from './telemetry-settings';
+
+export function assembleOperationName({
+  operationId,
+  telemetry,
+}: {
+  operationId: string;
+  telemetry?: TelemetrySettings;
+}) {
+  return {
+    // standardized operation and resource name:
+    'operation.name': `${operationId}${
+      telemetry?.functionId != null ? ` ${telemetry.functionId}` : ''
+    }`,
+    'resource.name': telemetry?.functionId,
+
+    // detailed, AI SDK specific data:
+    'ai.operationId': operationId,
+    'ai.telemetry.functionId': telemetry?.functionId,
+  };
+}

package/src/telemetry/get-base-telemetry-attributes.ts

@@ -0,0 +1,45 @@
+import { Attributes, AttributeValue } from '@opentelemetry/api';
+import { CallSettings } from '../prompt/call-settings';
+import { TelemetrySettings } from './telemetry-settings';
+
+export function getBaseTelemetryAttributes({
+  model,
+  settings,
+  telemetry,
+  headers,
+}: {
+  model: { modelId: string; provider: string };
+  settings: Omit<CallSettings, 'abortSignal' | 'headers' | 'temperature'>;
+  telemetry: TelemetrySettings | undefined;
+  headers: Record<string, string | undefined> | undefined;
+}): Attributes {
+  return {
+    'ai.model.provider': model.provider,
+    'ai.model.id': model.modelId,
+
+    // settings:
+    ...Object.entries(settings).reduce((attributes, [key, value]) => {
+      attributes[`ai.settings.${key}`] = value as AttributeValue;
+      return attributes;
+    }, {} as Attributes),
+
+    // add metadata as attributes:
+    ...Object.entries(telemetry?.metadata ?? {}).reduce(
+      (attributes, [key, value]) => {
+        if (value != undefined) {
+          attributes[`ai.telemetry.metadata.${key}`] = value as AttributeValue;
+        }
+        return attributes;
+      },
+      {} as Attributes,
+    ),
+
+    // request headers
+    ...Object.entries(headers ?? {}).reduce((attributes, [key, value]) => {
+      if (value !== undefined) {
+        attributes[`ai.request.headers.${key}`] = value;
+      }
+      return attributes;
+    }, {} as Attributes),
+  };
+}