ai-retry 0.6.0 → 0.7.0

package/README.md

@@ -40,7 +40,8 @@ import { createRetryable } from 'ai-retry';
 
 // Create a retryable model
 const retryableModel = createRetryable({
-  model: openai('gpt-4-mini'), // Base model
+  // Base model
+  model: openai('gpt-4-mini'),
   retries: [
     // Retry strategies and fallbacks...
   ],
@@ -74,7 +75,8 @@ import { createRetryable } from 'ai-retry';
 
 // Create a retryable model
 const retryableModel = createRetryable({
-  model: openai.textEmbedding('text-embedding-3-large'), // Base model
+  // Base model
+  model: openai.textEmbedding('text-embedding-3-large'),
   retries: [
     // Retry strategies and fallbacks...
   ],
@@ -89,6 +91,165 @@ const result = await embed({
 console.log(result.embedding);
 ```
 
+### Retryables
+
+The objects passed to the `retries` are called retryables and control the retry behavior. We can distinguish between two types of retryables:
+
+- **Static retryables** are simply models instances (language or embedding) that will always be used when an error occurs. This is also called a fallback model.
+- **Dynamic retryables** are functions that receive the current attempt context (error/result and previous attempts) and decide whether to retry with a different model based on custom logic.
+
+You can think of `retries` as a big `if-else` block, where each dynamic retryable is an `if` condition that can match a certain error/result condition, and static retryables are the `else` branches that match all other conditions. The analogy is not perfect, because the order of retryables matters because `retries` are evaluated in order until one matches:
+
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { generateText, streamText } from 'ai';
+import { createRetryable } from 'ai-retry';
+
+const retryableModel = createRetryable({
+  // Base model
+  model: openai('gpt-4-mini'),
+  // Retryables are evaluated in order
+  retries: [
+    // Dynamic retryable that matches only certain errors
+    (context) => {
+      return context.current.error.statusCode === 429 
+        ? { model: openai('gpt-3.5-turbo') }  // Retry with this model
+        : undefined;                          // Skip to next retryable
+    },
+
+    // Static retryable that always matches (fallback)
+    anthropic('claude-3-haiku-20240307'),
+    // Same as:
+    // { model: anthropic('claude-3-haiku-20240307'), maxAttempts: 1 }
+  ],
+});
+```
+
+In this example, if the base model fails with a 429 error, it will retry with `gpt-4`. In any other error case, it will fallback to `gpt-3.5-turbo`. If the order would be reversed, the static retryable would catch all errors first, and the dynamic retryable would never be reached.
+
+#### Fallbacks
+
+If you don't need precise error matching with custom logic and just want to fallback to different models on any error, you can simply provide a list of models.
+
+> [!NOTE] 
+> Use the object syntax `{ model: openai('gpt-4') }` if you need to provide additional options like `maxAttempts`, `delay`, etc.
+
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { generateText, streamText } from 'ai';
+import { createRetryable } from 'ai-retry';
+
+const retryableModel = createRetryable({
+  // Base model
+  model: openai('gpt-4-mini'),
+  // List of fallback models
+  retries: [
+    openai('gpt-3.5-turbo'), // Fallback for first error
+    // Same as:
+    // { model: openai('gpt-3.5-turbo'), maxAttempts: 1 },
+
+    anthropic('claude-3-haiku-20240307'), // Fallback for second error
+    // Same as:
+    // { model: anthropic('claude-3-haiku-20240307'), maxAttempts: 1 },
+  ],
+});
+```
+
+In this example, if the base model fails, it will retry with `gpt-3.5-turbo`. If that also fails, it will retry with `claude-3-haiku-20240307`. If that fails again, the whole retry process stops and a `RetryError` is thrown.
+
+#### Custom
+
+If you need more control over when to retry and which model to use, you can create your own custom retryable. This function is called with a context object containing the current attempt (error or result) and all previous attempts and needs to return a retry model or `undefined` to skip to the next retryable. The object you return from the retryable function is the same as the one you provide in the `retries` array.
+
+> [!NOTE]
+> You can return additional options like `maxAttempts`, `delay`, etc. along with the model.
+
+```typescript
+import { anthropic } from '@ai-sdk/anthropic';
+import { openai } from '@ai-sdk/openai';
+import { APICallError } from 'ai';
+import { createRetryable, isErrorAttempt } from 'ai-retry';
+import type { Retryable } from 'ai-retry';
+
+// Custom retryable that retries on rate limit errors (429)
+const rateLimitRetry: Retryable = (context) => {
+  // Only handle error attempts
+  if (isErrorAttempt(context.current)) {
+    // Get the error from the current attempt
+    const { error } = context.current;
+
+    // Check for rate limit error
+    if (APICallError.isInstance(error) && error.statusCode === 429) {
+      // Retry with a different model
+      return { model: anthropic('claude-3-haiku-20240307') };
+    }
+  }
+
+  // Skip to next retryable
+  return undefined;
+};
+
+const retryableModel = createRetryable({
+  // Base model
+  model: openai('gpt-4-mini'), 
+  retries: [
+    // Use custom rate limit retryable
+    rateLimitRetry
+
+    // Other retryables...
+  ],
+});
+```
+
+In this example, if the base model fails with a 429 error, it will retry with `claude-3-haiku-20240307`. For any other error, it will skip to the next retryable (if any) or throw the original error.
+
+#### All Retries Failed
+
+If all retry attempts failed, a `RetryError` is thrown containing all individual errors.
+If no retry was attempted (e.g. because all retryables returned `undefined`), the original error is thrown directly.
+
+```typescript
+import { RetryError } from 'ai';
+
+const retryableModel = createRetryable({
+  // Base model = first attempt
+  model: azure('gpt-4-mini'), 
+  retries: [
+    // Fallback model 1 = Second attempt
+    openai('gpt-3.5-turbo'), 
+    // Fallback model 2 = Third attempt
+    anthropic('claude-3-haiku-20240307') 
+  ],
+});
+
+try {
+  const result = await generateText({
+    model: retryableModel,
+    prompt: 'Hello world!',
+  });
+} catch (error) {
+  // RetryError is an official AI SDK error
+  if (error instanceof RetryError) {
+    console.error('All retry attempts failed:', error.errors);
+  } else {
+    console.error('Request failed:', error);
+  }
+}
+```
+
+Errors are tracked per unique model (provider + modelId). That means on the first error, it will retry with `gpt-3.5-turbo`. If that also fails, it will retry with `claude-3-haiku-20240307`. If that fails again, the whole retry process stops and a `RetryError` is thrown.
+
+### Built-in Retryables
+
+There are several built-in dynamic retryables available for common use cases:
+
+- [`contentFilterTriggered`](./src/retryables/content-filter-triggered.ts): Content filter was triggered based on the prompt or completion.
+- [`requestTimeout`](./src/retryables/request-timeout.ts): Request timeout occurred.
+- [`requestNotRetryable`](./src/retryables/request-not-retryable.ts): Request failed with a non-retryable error.
+- [`retryAfterDelay`](./src/retryables/retry-after-delay.ts): Retry with delay and exponential backoff and respect `retry-after` headers.
+- [`serviceOverloaded`](./src/retryables/service-overloaded.ts): Response with status code 529 (service overloaded).
+  - Use this retryable to handle Anthropic's overloaded errors.
+
 #### Content Filter
 
 Automatically switch to a different model when content filtering blocks your request.
@@ -195,82 +356,6 @@ const retryableModel = createRetryable({
 
 By default, if a [`retry-after-ms`](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/provisioned-get-started#what-should--i-do-when-i-receive-a-429-response) or [`retry-after`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After) header is present in the response, it will be prioritized over the configured delay. The delay from the header will be capped at 60 seconds for safety.
 
-#### Fallbacks
-
-If you always want to fallback to a different model on any error, you can simply provide a list of models.
-
-```typescript
-const retryableModel = createRetryable({
-  model: azure('gpt-4'),
-  retries: [
-    openai('gpt-4'), 
-    anthropic('claude-3-haiku-20240307')
-  ],
-});
-```
-
-#### Custom
-
-Create your own retryables for specific use cases:
-
-```typescript
-import { anthropic } from '@ai-sdk/anthropic';
-import { openai } from '@ai-sdk/openai';
-import { APICallError } from 'ai';
-import { createRetryable, isErrorAttempt } from 'ai-retry';
-import type { Retryable } from 'ai-retry';
-
-const rateLimitRetry: Retryable = (context) => {
-  if (isErrorAttempt(context.current)) {
-    const { error } = context.current;
-
-    if (APICallError.isInstance(error) && error.statusCode === 429) {
-      return { model: anthropic('claude-3-haiku-20240307') };
-    }
-  }
-
-  return undefined;
-};
-
-const retryableModel = createRetryable({
-  model: openai('gpt-4'),
-  retries: [
-    rateLimitRetry
-  ],
-});
-```
-
-#### All Retries Failed
-
-If all retry attempts failed, a `RetryError` is thrown containing all individual errors.
-If no retry was attempted (e.g. because all retryables returned `undefined`), the original error is thrown directly.
-
-```typescript
-import { RetryError } from 'ai';
-
-const retryableModel = createRetryable({
-  model: azure('gpt-4'),
-  retries: [
-    openai('gpt-4'), 
-    anthropic('claude-3-haiku-20240307')
-  ],
-});
-
-try {
-  const result = await generateText({
-    model: retryableModel,
-    prompt: 'Hello world!',
-  });
-} catch (error) {
-  // RetryError is an official AI SDK error
-  if (error instanceof RetryError) {
-    console.error('All retry attempts failed:', error.errors);
-  } else {
-    console.error('Request failed:', error);
-  }
-}
-```
-
 ### Options
 
 #### Retry Delays
@@ -282,10 +367,10 @@ const retryableModel = createRetryable({
   model: openai('gpt-4'),
   retries: [
     // Retry model 3 times with fixed 2s delay
-    () => ({ model: openai('gpt-4'), delay: 2000, maxAttempts: 3 }),
+    { model: openai('gpt-4'), delay: 2000, maxAttempts: 3 },
 
     // Or retry with exponential backoff (2s, 4s, 8s)
-    () => ({ model: openai('gpt-4'), delay: 2000, backoffFactor: 2, maxAttempts: 3 }),
+    { model: openai('gpt-4'), delay: 2000, backoffFactor: 2, maxAttempts: 3 },
   ],
 });
 
@@ -322,7 +407,7 @@ const retryableModel = createRetryable({
     // Try this once
     anthropic('claude-3-haiku-20240307'), 
     // Try this one more time (initial + 1 retry)
-    () => ({ model: openai('gpt-4'), maxAttempts: 2 }), 
+    { model: openai('gpt-4'), maxAttempts: 2 }, 
     // Already tried, won't be retried again
     anthropic('claude-3-haiku-20240307') 
   ],
@@ -340,7 +425,7 @@ const retryableModel = createRetryable({
   model: openai('gpt-5'),
   retries: [
     // Use different provider options for the retry
-    () => ({
+    {
       model: openai('gpt-4o-2024-08-06'),
       providerOptions: {
         openai: {
@@ -348,7 +433,7 @@ const retryableModel = createRetryable({
           structuredOutputs: false,
         },
       },
-    }),
+    },
   ],
 });
 
@@ -396,18 +481,6 @@ Errors during streaming requests can occur in two ways:
 
 In the second case, errors during stream processing will not always be retried, because the stream might have already emitted some actual content and the consumer might have processed it. Retrying will be stopped as soon as the first content chunk (e.g. types of `text-delta`, `tool-call`, etc.) is emitted. The type of chunks considered as content are the same as the ones that are passed to [onChunk()](https://github.com/vercel/ai/blob/1fe4bd4144bff927f5319d9d206e782a73979ccb/packages/ai/src/generate-text/stream-text.ts#L684-L697).
 
-### Retryables
-
-A retryable is a function that receives the current attempt and determines whether to retry with a different model based on the error/result and any previous attempts. 
-There are several built-in retryables:
-
-- [`contentFilterTriggered`](./src/retryables/content-filter-triggered.ts): Content filter was triggered based on the prompt or completion.
-- [`requestTimeout`](./src/retryables/request-timeout.ts): Request timeout occurred.
-- [`requestNotRetryable`](./src/retryables/request-not-retryable.ts): Request failed with a non-retryable error.
-- [`retryAfterDelay`](./src/retryables/retry-after-delay.ts): Retry with delay and exponential backoff and respect `retry-after` headers.
-- [`serviceOverloaded`](./src/retryables/service-overloaded.ts): Response with status code 529 (service overloaded).
-  - Use this retryable to handle Anthropic's overloaded errors.
-
 ### API Reference
 
 #### `createRetryable(options: RetryableModelOptions): LanguageModelV2 | EmbeddingModelV2`

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { a as LanguageModelV2Generate, c as Retry, d as RetryErrorAttempt, f as RetryResultAttempt, h as RetryableOptions, i as LanguageModelV2, l as RetryAttempt, m as RetryableModelOptions, n as EmbeddingModelV2CallOptions, o as LanguageModelV2Stream, p as Retryable, r as EmbeddingModelV2Embed, s as Retries, t as EmbeddingModelV2, u as RetryContext } from "./types-DhGbwiB4.js";
+import { a as LanguageModelV2Generate, c as Retry, d as RetryErrorAttempt, f as RetryResultAttempt, h as RetryableOptions, i as LanguageModelV2, l as RetryAttempt, m as RetryableModelOptions, n as EmbeddingModelV2CallOptions, o as LanguageModelV2Stream, p as Retryable, r as EmbeddingModelV2Embed, s as Retries, t as EmbeddingModelV2, u as RetryContext } from "./types-CfE400mD.js";
 import * as _ai_sdk_provider0 from "@ai-sdk/provider";
 import { LanguageModelV2 as LanguageModelV2$1, LanguageModelV2StreamPart } from "@ai-sdk/provider";
 
 //#region src/create-retryable-model.d.ts
-declare function createRetryable<MODEL extends LanguageModelV2>(options: RetryableModelOptions<MODEL>): LanguageModelV2;
-declare function createRetryable<MODEL extends EmbeddingModelV2>(options: RetryableModelOptions<MODEL>): EmbeddingModelV2;
+declare function createRetryable<MODEL$1 extends LanguageModelV2>(options: RetryableModelOptions<MODEL$1>): LanguageModelV2;
+declare function createRetryable<MODEL$1 extends EmbeddingModelV2>(options: RetryableModelOptions<MODEL$1>): EmbeddingModelV2;
 //#endregion
 //#region src/get-model-key.d.ts
 /**
@@ -66,5 +66,9 @@ declare const isStreamContentPart: (part: LanguageModelV2StreamPart) => part is
   type: "raw";
   rawValue: unknown;
 };
+/**
+ * Type guard to check if a value is a Retry object (has a model property with a MODEL)
+ */
+declare const isRetry: <MODEL extends LanguageModelV2$1 | EmbeddingModelV2>(value: unknown) => value is Retry<MODEL>;
 //#endregion
-export { EmbeddingModelV2, EmbeddingModelV2CallOptions, EmbeddingModelV2Embed, LanguageModelV2, LanguageModelV2Generate, LanguageModelV2Stream, Retries, Retry, RetryAttempt, RetryContext, RetryErrorAttempt, RetryResultAttempt, Retryable, RetryableModelOptions, RetryableOptions, createRetryable, getModelKey, isEmbeddingModelV2, isErrorAttempt, isGenerateResult, isLanguageModelV2, isModelV2, isObject, isResultAttempt, isStreamContentPart, isStreamResult, isString };
+export { EmbeddingModelV2, EmbeddingModelV2CallOptions, EmbeddingModelV2Embed, LanguageModelV2, LanguageModelV2Generate, LanguageModelV2Stream, Retries, Retry, RetryAttempt, RetryContext, RetryErrorAttempt, RetryResultAttempt, Retryable, RetryableModelOptions, RetryableOptions, createRetryable, getModelKey, isEmbeddingModelV2, isErrorAttempt, isGenerateResult, isLanguageModelV2, isModelV2, isObject, isResultAttempt, isRetry, isStreamContentPart, isStreamResult, isString };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as isModelV2, c as isStreamContentPart, i as isLanguageModelV2, l as isStreamResult, n as isErrorAttempt, o as isObject, r as isGenerateResult, s as isResultAttempt, t as isEmbeddingModelV2, u as isString } from "./utils-BlCGaP0E.js";
+import { a as isModelV2, c as isRetry, d as isString, i as isLanguageModelV2, l as isStreamContentPart, n as isErrorAttempt, o as isObject, r as isGenerateResult, s as isResultAttempt, t as isEmbeddingModelV2, u as isStreamResult } from "./utils-DsvLGk6a.js";
 import { delay } from "@ai-sdk/provider-utils";
 import { getErrorMessage } from "@ai-sdk/provider";
 import { RetryError } from "ai";
@@ -35,15 +35,18 @@ function countModelAttempts(model, attempts) {
 async function findRetryModel(retries, context) {
 	/**
 	* Filter retryables based on attempt type:
-	* - Result-based attempts: Only consider function retryables (skip plain models)
-	* - Error-based attempts: Consider all retryables (functions + plain models)
+	* - Result-based attempts: Only consider function retryables (skip plain models and static Retry objects)
+	* - Error-based attempts: Consider all retryables (functions + plain models + static Retry objects)
 	*/
 	const applicableRetries = isResultAttempt(context.current) ? retries.filter((retry) => typeof retry === "function") : retries;
 	/**
 	* Iterate through the applicable retryables to find a model to retry with
 	*/
 	for (const retry of applicableRetries) {
-		const retryModel = typeof retry === "function" ? await retry(context) : { model: retry };
+		let retryModel;
+		if (typeof retry === "function") retryModel = await retry(context);
+		else if (isRetry(retry)) retryModel = retry;
+		else retryModel = { model: retry };
 		if (retryModel) {
 			/**
 			* The model key uniquely identifies a model instance (provider + modelId)
@@ -485,4 +488,4 @@ function createRetryable(options) {
 }
 
 //#endregion
-export { createRetryable, getModelKey, isEmbeddingModelV2, isErrorAttempt, isGenerateResult, isLanguageModelV2, isModelV2, isObject, isResultAttempt, isStreamContentPart, isStreamResult, isString };
+export { createRetryable, getModelKey, isEmbeddingModelV2, isErrorAttempt, isGenerateResult, isLanguageModelV2, isModelV2, isObject, isResultAttempt, isRetry, isStreamContentPart, isStreamResult, isString };

package/dist/retryables/index.d.ts

@@ -1,4 +1,4 @@
-import { h as RetryableOptions, i as LanguageModelV2, p as Retryable, t as EmbeddingModelV2 } from "../types-DhGbwiB4.js";
+import { h as RetryableOptions, i as LanguageModelV2, p as Retryable, t as EmbeddingModelV2 } from "../types-CfE400mD.js";
 
 //#region src/retryables/content-filter-triggered.d.ts
 

package/dist/retryables/index.js

@@ -1,4 +1,4 @@
-import { n as isErrorAttempt, o as isObject, s as isResultAttempt, u as isString } from "../utils-BlCGaP0E.js";
+import { d as isString, n as isErrorAttempt, o as isObject, s as isResultAttempt } from "../utils-DsvLGk6a.js";
 import { isAbortError } from "@ai-sdk/provider-utils";
 import { APICallError } from "ai";
 

package/dist/{types-DhGbwiB4.d.ts → types-CfE400mD.d.ts}

@@ -61,7 +61,7 @@ type Retry<MODEL extends LanguageModelV2$1 | EmbeddingModelV2$1> = {
  * A function that determines whether to retry with a different model based on the current attempt and all previous attempts.
  */
 type Retryable<MODEL extends LanguageModelV2$1 | EmbeddingModelV2$1> = (context: RetryContext<MODEL>) => Retry<MODEL> | Promise<Retry<MODEL>> | undefined;
-type Retries<MODEL extends LanguageModelV2$1 | EmbeddingModelV2$1> = Array<Retryable<MODEL> | MODEL>;
+type Retries<MODEL extends LanguageModelV2$1 | EmbeddingModelV2$1> = Array<Retryable<MODEL> | Retry<MODEL> | MODEL>;
 type RetryableOptions<MODEL extends LanguageModelV2$1 | EmbeddingModelV2$1> = Partial<Omit<Retry<MODEL>, 'model'>>;
 type LanguageModelV2Generate = Awaited<ReturnType<LanguageModelV2$1['doGenerate']>>;
 type LanguageModelV2Stream = Awaited<ReturnType<LanguageModelV2$1['doStream']>>;

package/dist/{utils-BlCGaP0E.js → utils-DsvLGk6a.js}

@@ -26,6 +26,10 @@ function isResultAttempt(attempt) {
 const isStreamContentPart = (part) => {
 	return part.type === "text-delta" || part.type === "reasoning-delta" || part.type === "source" || part.type === "tool-call" || part.type === "tool-result" || part.type === "tool-input-start" || part.type === "tool-input-delta" || part.type === "raw";
 };
+/**
+* Type guard to check if a value is a Retry object (has a model property with a MODEL)
+*/
+const isRetry = (value) => isObject(value) && "model" in value && isModelV2(value.model);
 
 //#endregion
-export { isModelV2 as a, isStreamContentPart as c, isLanguageModelV2 as i, isStreamResult as l, isErrorAttempt as n, isObject as o, isGenerateResult as r, isResultAttempt as s, isEmbeddingModelV2 as t, isString as u };
+export { isModelV2 as a, isRetry as c, isString as d, isLanguageModelV2 as i, isStreamContentPart as l, isErrorAttempt as n, isObject as o, isGenerateResult as r, isResultAttempt as s, isEmbeddingModelV2 as t, isStreamResult as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-retry",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "AI SDK Retry",
   "main": "./dist/index.js",
   "module": "./dist/index.js",