@ai-sdk/provider 3.0.2 → 3.0.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ai-sdk/provider
 
+## 3.0.3
+
+### Patch Changes
+
+- 1b11dcb: chore(ai): include sources in npm package
+
 ## 3.0.2
 
 ### Patch Changes

package/dist/index.d.mts

@@ -267,7 +267,7 @@ type EmbeddingModelV2Embedding = Array<number>;
 
 /**
 Specification for an embedding model that implements the embedding model
-interface version 1.
+interface version 2.
 
 VALUE is the type of the values that the model can embed.
 This will allow us to go beyond text embeddings in the future,

package/dist/index.d.ts

@@ -267,7 +267,7 @@ type EmbeddingModelV2Embedding = Array<number>;
 
 /**
 Specification for an embedding model that implements the embedding model
-interface version 1.
+interface version 2.
 
 VALUE is the type of the values that the model can embed.
 This will allow us to go beyond text embeddings in the future,

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@ai-sdk/provider",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "source": "./src/index.ts",
   "files": [
     "dist/**/*",
+    "src",
     "CHANGELOG.md",
     "README.md"
   ],

package/src/embedding-model/index.ts

@@ -0,0 +1,2 @@
+export * from './v3/index';
+export * from './v2/index';

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

@@ -0,0 +1,5 @@
+/**
+An embedding is a vector, i.e. an array of numbers.
+It is e.g. used to represent a text as a vector of word embeddings.
+ */
+export type EmbeddingModelV2Embedding = Array<number>;

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

@@ -0,0 +1,113 @@
+import {
+  SharedV2Headers,
+  SharedV2ProviderOptions,
+  SharedV2ProviderMetadata,
+} from '../../shared';
+import { EmbeddingModelV2Embedding } from './embedding-model-v2-embedding';
+
+/**
+Specification for an embedding model that implements the embedding model
+interface version 2.
+
+VALUE is the type of the values that the model can embed.
+This will allow us to go beyond text embeddings in the future,
+e.g. to support image embeddings
+ */
+export type EmbeddingModelV2<VALUE> = {
+  /**
+The embedding model must specify which embedding model interface
+version it implements. This will allow us to evolve the embedding
+model interface and retain backwards compatibility. The different
+implementation versions can be handled as a discriminated union
+on our side.
+   */
+  readonly specificationVersion: 'v2';
+
+  /**
+Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+Limit of how many embeddings can be generated in a single API call.
+
+Use Infinity for models that do not have a limit.
+   */
+  readonly maxEmbeddingsPerCall:
+    | PromiseLike<number | undefined>
+    | number
+    | undefined;
+
+  /**
+True if the model can handle multiple embedding calls in parallel.
+   */
+  readonly supportsParallelCalls: PromiseLike<boolean> | boolean;
+
+  /**
+Generates a list of embeddings for the given input text.
+
+Naming: "do" prefix to prevent accidental direct usage of the method
+by the user.
+   */
+  doEmbed(options: {
+    /**
+List of values to embed.
+     */
+    values: Array<VALUE>;
+
+    /**
+Abort signal for cancelling the operation.
+     */
+    abortSignal?: AbortSignal;
+
+    /**
+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?: SharedV2ProviderOptions;
+
+    /**
+  Additional HTTP headers to be sent with the request.
+  Only applicable for HTTP-based providers.
+     */
+    headers?: Record<string, string | undefined>;
+  }): PromiseLike<{
+    /**
+Generated embeddings. They are in the same order as the input values.
+     */
+    embeddings: Array<EmbeddingModelV2Embedding>;
+
+    /**
+Token usage. We only have input tokens for embeddings.
+    */
+    usage?: { tokens: number };
+
+    /**
+Additional provider-specific metadata. They are passed through
+from the provider to the AI SDK and enable provider-specific
+results that can be fully encapsulated in the provider.
+     */
+    providerMetadata?: SharedV2ProviderMetadata;
+
+    /**
+Optional response information for debugging purposes.
+     */
+    response?: {
+      /**
+Response headers.
+       */
+      headers?: SharedV2Headers;
+
+      /**
+      The response body.
+      */
+      body?: unknown;
+    };
+  }>;
+};

package/src/embedding-model/v2/index.ts

@@ -0,0 +1,2 @@
+export * from './embedding-model-v2';
+export * from './embedding-model-v2-embedding';

package/src/embedding-model/v3/embedding-model-v3-call-options.ts

@@ -0,0 +1,26 @@
+import { SharedV3Headers, SharedV3ProviderOptions } from '../../shared';
+
+export type EmbeddingModelV3CallOptions = {
+  /**
+ List of text values to generate embeddings for.
+ */
+  values: Array<string>;
+
+  /**
+ Abort signal for cancelling the operation.
+ */
+  abortSignal?: AbortSignal;
+
+  /**
+  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?: SharedV3ProviderOptions;
+
+  /**
+   Additional HTTP headers to be sent with the request.
+   Only applicable for HTTP-based providers.
+ */
+  headers?: SharedV3Headers;
+};

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

@@ -0,0 +1,5 @@
+/**
+An embedding is a vector, i.e. an array of numbers.
+It is e.g. used to represent a text as a vector of word embeddings.
+ */
+export type EmbeddingModelV3Embedding = Array<number>;

package/src/embedding-model/v3/embedding-model-v3-result.ts

@@ -0,0 +1,48 @@
+import {
+  SharedV3Headers,
+  SharedV3ProviderMetadata,
+  SharedV3Warning,
+} from '../../shared';
+import { EmbeddingModelV3Embedding } from './embedding-model-v3-embedding';
+
+/**
+ * The result of a embedding model doEmbed call.
+ */
+export type EmbeddingModelV3Result = {
+  /**
+   * Generated embeddings. They are in the same order as the input values.
+   */
+  embeddings: Array<EmbeddingModelV3Embedding>;
+
+  /**
+   * Token usage. We only have input tokens for embeddings.
+   */
+  usage?: { tokens: number };
+
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * from the provider to the AI SDK and enable provider-specific
+   * results that can be fully encapsulated in the provider.
+   */
+  providerMetadata?: SharedV3ProviderMetadata;
+
+  /**
+   * Optional response information for debugging purposes.
+   */
+  response?: {
+    /**
+     * Response headers.
+     */
+    headers?: SharedV3Headers;
+
+    /**
+      The response body.
+      */
+    body?: unknown;
+  };
+
+  /**
+   * Warnings for the call, e.g. unsupported settings.
+   */
+  warnings: Array<SharedV3Warning>;
+};

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

@@ -0,0 +1,54 @@
+import { EmbeddingModelV3CallOptions } from './embedding-model-v3-call-options';
+import { EmbeddingModelV3Result } from './embedding-model-v3-result';
+
+/**
+Specification for an embedding model that implements the embedding model
+interface version 3.
+
+It is specific to text embeddings.
+ */
+export type EmbeddingModelV3 = {
+  /**
+The embedding model must specify which embedding model interface
+version it implements. This will allow us to evolve the embedding
+model interface and retain backwards compatibility. The different
+implementation versions can be handled as a discriminated union
+on our side.
+   */
+  readonly specificationVersion: 'v3';
+
+  /**
+Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+Limit of how many embeddings can be generated in a single API call.
+
+Use Infinity for models that do not have a limit.
+   */
+  readonly maxEmbeddingsPerCall:
+    | PromiseLike<number | undefined>
+    | number
+    | undefined;
+
+  /**
+True if the model can handle multiple embedding calls in parallel.
+   */
+  readonly supportsParallelCalls: PromiseLike<boolean> | boolean;
+
+  /**
+Generates a list of embeddings for the given input text.
+
+Naming: "do" prefix to prevent accidental direct usage of the method
+by the user.
+   */
+  doEmbed(
+    options: EmbeddingModelV3CallOptions,
+  ): PromiseLike<EmbeddingModelV3Result>;
+};

package/src/embedding-model/v3/index.ts

@@ -0,0 +1,4 @@
+export * from './embedding-model-v3';
+export * from './embedding-model-v3-call-options';
+export * from './embedding-model-v3-embedding';
+export * from './embedding-model-v3-result';

package/src/embedding-model-middleware/index.ts

@@ -0,0 +1 @@
+export * from './v3/index';

package/src/embedding-model-middleware/v3/embedding-model-v3-middleware.ts

@@ -0,0 +1,69 @@
+import { EmbeddingModelV3 } from '../../embedding-model/v3/embedding-model-v3';
+import { EmbeddingModelV3CallOptions } from '../../embedding-model/v3/embedding-model-v3-call-options';
+
+/**
+ * Middleware for EmbeddingModelV3.
+ * This type defines the structure for middleware that can be used to modify
+ * the behavior of EmbeddingModelV3 operations.
+ */
+export type EmbeddingModelV3Middleware = {
+  /**
+   * Middleware specification version. Use `v3` for the current version.
+   */
+  readonly specificationVersion: 'v3';
+
+  /**
+   * Override the provider name if desired.
+   * @param options.model - The embedding model instance.
+   */
+  overrideProvider?: (options: { model: EmbeddingModelV3 }) => string;
+
+  /**
+   * Override the model ID if desired.
+   * @param options.model - The embedding model instance.
+   */
+  overrideModelId?: (options: { model: EmbeddingModelV3 }) => string;
+
+  /**
+   * Override the limit of how many embeddings can be generated in a single API call if desired.
+   * @param options.model - The embedding model instance.
+   */
+  overrideMaxEmbeddingsPerCall?: (options: {
+    model: EmbeddingModelV3;
+  }) => PromiseLike<number | undefined> | number | undefined;
+
+  /**
+   * Override support for handling multiple embedding calls in parallel, if desired..
+   * @param options.model - The embedding model instance.
+   */
+  overrideSupportsParallelCalls?: (options: {
+    model: EmbeddingModelV3;
+  }) => PromiseLike<boolean> | boolean;
+
+  /**
+   * Transforms the parameters before they are passed to the embed model.
+   * @param options - Object containing the type of operation and the parameters.
+   * @param options.params - The original parameters for the embedding model call.
+   * @returns A promise that resolves to the transformed parameters.
+   */
+  transformParams?: (options: {
+    params: EmbeddingModelV3CallOptions;
+    model: EmbeddingModelV3;
+  }) => PromiseLike<EmbeddingModelV3CallOptions>;
+
+  /**
+   * Wraps the embed operation of the embedding model.
+   *
+   * @param options - Object containing the embed function, parameters, and model.
+   * @param options.doEmbed - The original embed function.
+   * @param options.params - The parameters for the embed call. If the
+   * `transformParams` middleware is used, this will be the transformed parameters.
+   * @param options.model - The embedding model instance.
+   * @returns A promise that resolves to the result of the generate operation.
+   */
+  wrapEmbed?: (options: {
+    doEmbed: () => ReturnType<EmbeddingModelV3['doEmbed']>;
+    params: EmbeddingModelV3CallOptions;
+    model: EmbeddingModelV3;
+  }) => Promise<Awaited<ReturnType<EmbeddingModelV3['doEmbed']>>>;
+};

package/src/embedding-model-middleware/v3/index.ts

@@ -0,0 +1 @@
+export * from './embedding-model-v3-middleware';

package/src/errors/ai-sdk-error.ts

@@ -0,0 +1,62 @@
+/**
+ * Symbol used for identifying AI SDK Error instances.
+ * Enables checking if an error is an instance of AISDKError across package versions.
+ */
+const marker = 'vercel.ai.error';
+const symbol = Symbol.for(marker);
+
+/**
+ * Custom error class for AI SDK related errors.
+ * @extends Error
+ */
+export class AISDKError extends Error {
+  private readonly [symbol] = true; // used in isInstance
+
+  /**
+   * The underlying cause of the error, if any.
+   */
+  readonly cause?: unknown;
+
+  /**
+   * Creates an AI SDK Error.
+   *
+   * @param {Object} params - The parameters for creating the error.
+   * @param {string} params.name - The name of the error.
+   * @param {string} params.message - The error message.
+   * @param {unknown} [params.cause] - The underlying cause of the error.
+   */
+  constructor({
+    name,
+    message,
+    cause,
+  }: {
+    name: string;
+    message: string;
+    cause?: unknown;
+  }) {
+    super(message);
+
+    this.name = name;
+    this.cause = cause;
+  }
+
+  /**
+   * Checks if the given error is an AI SDK Error.
+   * @param {unknown} error - The error to check.
+   * @returns {boolean} True if the error is an AI SDK Error, false otherwise.
+   */
+  static isInstance(error: unknown): error is AISDKError {
+    return AISDKError.hasMarker(error, marker);
+  }
+
+  protected static hasMarker(error: unknown, marker: string): boolean {
+    const markerSymbol = Symbol.for(marker);
+    return (
+      error != null &&
+      typeof error === 'object' &&
+      markerSymbol in error &&
+      typeof error[markerSymbol] === 'boolean' &&
+      error[markerSymbol] === true
+    );
+  }
+}

package/src/errors/api-call-error.ts

@@ -0,0 +1,59 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_APICallError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class APICallError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly url: string;
+  readonly requestBodyValues: unknown;
+  readonly statusCode?: number;
+
+  readonly responseHeaders?: Record<string, string>;
+  readonly responseBody?: string;
+
+  readonly isRetryable: boolean;
+  readonly data?: unknown;
+
+  constructor({
+    message,
+    url,
+    requestBodyValues,
+    statusCode,
+    responseHeaders,
+    responseBody,
+    cause,
+    isRetryable = statusCode != null &&
+      (statusCode === 408 || // request timeout
+        statusCode === 409 || // conflict
+        statusCode === 429 || // too many requests
+        statusCode >= 500), // server error
+    data,
+  }: {
+    message: string;
+    url: string;
+    requestBodyValues: unknown;
+    statusCode?: number;
+    responseHeaders?: Record<string, string>;
+    responseBody?: string;
+    cause?: unknown;
+    isRetryable?: boolean;
+    data?: unknown;
+  }) {
+    super({ name, message, cause });
+
+    this.url = url;
+    this.requestBodyValues = requestBodyValues;
+    this.statusCode = statusCode;
+    this.responseHeaders = responseHeaders;
+    this.responseBody = responseBody;
+    this.isRetryable = isRetryable;
+    this.data = data;
+  }
+
+  static isInstance(error: unknown): error is APICallError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/empty-response-body-error.ts

@@ -0,0 +1,17 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_EmptyResponseBodyError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export class EmptyResponseBodyError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  constructor({ message = 'Empty response body' }: { message?: string } = {}) {
+    super({ name, message });
+  }
+
+  static isInstance(error: unknown): error is EmptyResponseBodyError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/get-error-message.ts

@@ -0,0 +1,15 @@
+export function getErrorMessage(error: unknown | undefined) {
+  if (error == null) {
+    return 'unknown error';
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return JSON.stringify(error);
+}

package/src/errors/index.ts

@@ -0,0 +1,15 @@
+export { AISDKError } from './ai-sdk-error';
+export { APICallError } from './api-call-error';
+export { EmptyResponseBodyError } from './empty-response-body-error';
+export { getErrorMessage } from './get-error-message';
+export { InvalidArgumentError } from './invalid-argument-error';
+export { InvalidPromptError } from './invalid-prompt-error';
+export { InvalidResponseDataError } from './invalid-response-data-error';
+export { JSONParseError } from './json-parse-error';
+export { LoadAPIKeyError } from './load-api-key-error';
+export { LoadSettingError } from './load-setting-error';
+export { NoContentGeneratedError } from './no-content-generated-error';
+export { NoSuchModelError } from './no-such-model-error';
+export { TooManyEmbeddingValuesForCallError } from './too-many-embedding-values-for-call-error';
+export { TypeValidationError } from './type-validation-error';
+export { UnsupportedFunctionalityError } from './unsupported-functionality-error';

package/src/errors/invalid-argument-error.ts

@@ -0,0 +1,32 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_InvalidArgumentError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * A function argument is invalid.
+ */
+export class InvalidArgumentError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly argument: string;
+
+  constructor({
+    message,
+    cause,
+    argument,
+  }: {
+    argument: string;
+    message: string;
+    cause?: unknown;
+  }) {
+    super({ name, message, cause });
+
+    this.argument = argument;
+  }
+
+  static isInstance(error: unknown): error is InvalidArgumentError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/invalid-prompt-error.ts

@@ -0,0 +1,33 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_InvalidPromptError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * A prompt is invalid. This error should be thrown by providers when they cannot
+ * process a prompt.
+ */
+export class InvalidPromptError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly prompt: unknown;
+
+  constructor({
+    prompt,
+    message,
+    cause,
+  }: {
+    prompt: unknown;
+    message: string;
+    cause?: unknown;
+  }) {
+    super({ name, message: `Invalid prompt: ${message}`, cause });
+
+    this.prompt = prompt;
+  }
+
+  static isInstance(error: unknown): error is InvalidPromptError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/invalid-response-data-error.ts

@@ -0,0 +1,31 @@
+import { AISDKError } from './ai-sdk-error';
+
+const name = 'AI_InvalidResponseDataError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Server returned a response with invalid data content.
+ * This should be thrown by providers when they cannot parse the response from the API.
+ */
+export class InvalidResponseDataError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly data: unknown;
+
+  constructor({
+    data,
+    message = `Invalid response data: ${JSON.stringify(data)}.`,
+  }: {
+    data: unknown;
+    message?: string;
+  }) {
+    super({ name, message });
+
+    this.data = data;
+  }
+
+  static isInstance(error: unknown): error is InvalidResponseDataError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}