ai-retry 0.0.1-alpha.2 → 0.0.1-alpha.3

package/README.md

@@ -1,24 +1,29 @@
-# ai-retry
-
-🚧 **WORK IN PROGRESS - DO NOT USE IN PRODUCTION**
+### ai-retry
 
 Intelligent retry and fallback mechanisms for AI SDK models. Automatically handle API failures, content filtering, timeouts, and schema mismatches by switching between different AI models.
 
-## How It Works
+#### How?
+
+`ai-retry` wraps the provided base model with a set of retry conditions (retryables). When a request fails due to specific errors (like content filtering or timeouts), it iterates through the given retryables to find a suitable fallback model. It automatically tracks which models have been tried and how many attempts have been made to prevent infinite loops.
 
-`ai-retry` wraps the provided base model with a set of retry conditions (retryables). When a request fails due to specific errors (like content filtering or timeouts), it iterates through the given retryables to find a suitable fallback model. It tracks which models have been tried and how many attempts have been made to prevent infinite loops.
+### Installation
 
-## Installation
+This library only supports AI SDK v5.
+
+> [!WARNING]  
+> `ai-retry` is in alpha stage and the API may change in future releases.
 
 ```bash
-npm install ai-retry
-# or
-pnpm add ai-retry
-# or
-yarn add ai-retry
+npm install ai-retry@alpha
 ```
 
-## Usage
+### Usage
+
+Create a retryable model by providing a base model and a list of retryables or fallback models.
+
+> [!WARNING]  
+> `ai-retry` currently only supports `generateText` and `generateObject` calls.
+> Streaming via `streamText` and `streamObject` is not supported yet.
 
 ```typescript
 import { azure } from '@ai-sdk/azure';
@@ -47,35 +52,21 @@ const result = await generateText({
 });
 ```
 
-### Default Fallback
-
-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')
-  ],
-});
-```
-
-## Retryables
+#### Retryables
 
-A retryable is a function that receives an error and determines whether to retry with a different model based on the error and context of previous attempts. 
-`ai-retry` includes several built-in retryables:
+A retryable is a function that receives the current failed attempt and determines whether to retry with a different model based on the error and any previous attempts. 
+There are several built-in retryables:
 
-- `contentFilterTriggered`: Automatically switch to a different model when content filtering blocks your request.
-- `responseSchemaMismatch`: Retry with different models when structured output validation fails.
-- `requestTimeout`: Handle timeouts by switching to potentially faster models.
-- `requestNotRetryable`: Handle cases where the primary model cannot process the request.
+- `contentFilterTriggered`: Content filter was triggered based on the prompt or completion.
+- `responseSchemaMismatch`: Structured output validation failed.
+- `requestTimeout`: Request timeout occurred.
+- `requestNotRetryable`: Request failed with a non-retryable error.
 
 By default, each retryable will only attempt to retry once per model to avoid infinite loops. You can customize this behavior by returning a `maxAttempts` value from your retryable function.
 
-### Content Filter Triggered
+##### Content Filter Triggered
 
-Automatically switch to a different model when content filtering blocks your request:
+Automatically switch to a different model when content filtering blocks your request.
 
 ```typescript
 import { contentFilterTriggered } from 'ai-retry/retryables';
@@ -88,7 +79,7 @@ const retryableModel = createRetryable({
 });
 ```
 
-### Response Schema Mismatch
+##### Response Schema Mismatch
 
 Retry with different models when structured output validation fails:
 
@@ -98,7 +89,7 @@ import { responseSchemaMismatch } from 'ai-retry/retryables';
 const retryableModel = createRetryable({
   model: azure('gpt-4-mini'),
   retries: [
-    responseSchemaMismatch(azure('gpt-4')), // Try full model for better structure output
+    responseSchemaMismatch(azure('gpt-4')), // Try full model for better structured output
   ],
 });
 
@@ -115,9 +106,12 @@ const result = await generateObject({
 });
 ```
 
-### Request Timeout
+##### Request Timeout
 
-Handle timeouts by switching to potentially faster models:
+Handle timeouts by switching to potentially faster models.
+
+> [!NOTE] 
+> You need to set an `abortSignal` with a timeout on your request for this to work. 
 
 ```typescript
 import { requestTimeout } from 'ai-retry/retryables';
@@ -136,9 +130,9 @@ const result = await generateText({
 });
 ```
 
-### Request Not Retryable
+##### Request Not Retryable
 
-Handle cases where the base model fails with a non-retryable error (e.g., unsupported features):
+Handle cases where the base model fails with a non-retryable error.
 
 ```typescript
 import { requestNotRetryable } from 'ai-retry/retryables';
@@ -151,7 +145,7 @@ const retryable = createRetryable({
 });
 ```
 
-### Custom Retryables
+##### Custom Retryables
 
 Create your own retryables for specific use cases:
 
@@ -159,10 +153,10 @@ Create your own retryables for specific use cases:
 import type { Retryable } from 'ai-retry';
 
 const customRetry: Retryable = (context) => {
-  const { error, triedModels, totalAttempts } = context;
+  const { current, attempts, totalAttempts } = context;
   
   // Your custom logic here
-  if (shouldRetryWithDifferentModel(error)) {
+  if (shouldRetryWithDifferentModel(current.error)) {
     return {
       model: myFallbackModel,
       maxAttempts: 3,
@@ -178,24 +172,73 @@ const retryable = createRetryable({
 });
 ```
 
-### Error Monitoring
+#### Default Fallback
 
-Track retry attempts and errors:
+If you always want to fallback to a different model on any error, you can simply provide a list of models.
 
 ```typescript
-const retryable = createRetryable({
-  model: primaryModel,
+const retryableModel = createRetryable({
+  model: azure('gpt-4'),
+  retries: [
+    openai('gpt-4'), 
+    anthropic('claude-3-haiku-20240307')
+  ],
+});
+```
+
+#### 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);
+  }
+}
+```
+
+#### Logging
+
+You can use the following callbacks to log retry attempts and errors:
+- `onError` is invoked if an error occurs. 
+- `onRetry` is invoked before attempting a retry.
+
+```typescript
+const retryableModel = createRetryable({
+  model: openai('gpt-4-mini'),
   retries: [/* your retryables */],
   onError: (context) => {
-    console.log(`Attempt ${context.totalAttempts} failed:`, context.error);
-    console.log(`Tried models:`, Array.from(context.triedModels.keys()));
+    console.log(`Attempt ${context.totalAttempts} with ${context.current.model.provider}/${context.current.model.modelId} failed:`, context.current.error);
+  },
+  onRetry: (context) => {
+    console.log(`Retrying with model ${context.current.model.provider}/${context.current.model.modelId}...`);
   },
 });
 ```
 
-## API Reference
+### API Reference
 
-### `createRetryable(options: CreateRetryableOptions): LanguageModelV2`
+#### `createRetryable(options: CreateRetryableOptions): LanguageModelV2`
 
 Creates a retryable language model.
 
@@ -204,21 +247,23 @@ interface CreateRetryableOptions {
   model: LanguageModelV2;
   retries: Array<Retryable | LanguageModelV2>;
   onError?: (context: RetryContext) => void;
+  onRetry?: (context: RetryContext) => void;
 }
 ```
 
-### `Retryable`
+#### `Retryable`
 
-A `Retryable` is a function that receives a `RetryContext` with the current error and model and all previously tried models.
-It should evaluate the error and decide whether to retry by returning a new model or to skip by returning `undefined`.
+A `Retryable` is a function that receives a `RetryContext` with the current error and model and all previous attempts.
+It should evaluate the error and decide whether to retry by returning a `RetryModel` or to skip by returning `undefined`.
 
 ```ts
 type Retryable = (context: RetryContext) => RetryModel | Promise<RetryModel> | undefined;
 ```
 
-### `RetryModel`
+#### `RetryModel`
 
-A `RetryModel` specifies the model to retry with and an optional `maxAttempts` to limit how many times this model can be retried.
+A `RetryModel` specifies the model to retry and an optional `maxAttempts` to limit how many times this model can be retried.
+By default, each retryable will only attempt to retry once per model. This can be customized by setting the `maxAttempts` property.
 
 ```typescript
 interface RetryModel {
@@ -227,38 +272,29 @@ interface RetryModel {
 }
 ```
 
-### `RetryContext`
+#### `RetryContext`
 
-The `RetryContext` object contains information about the current error and previously tried models.
+The `RetryContext` object contains information about the current attempt and all previous attempts.
 
 ```typescript
 interface RetryContext {
-  error: unknown;                       
-  baseModel: LanguageModelV2;           
-  currentModel: LanguageModelV2;        
-  triedModels: Map<string, RetryState>; 
-  totalAttempts: number;                
+  current: RetryAttempt;
+  attempts: Array<RetryAttempt>;
+  totalAttempts: number;
 }
 ```
 
-### `RetryState`
+#### `RetryAttempt`
 
-The `RetryState` tracks the state of each model that has been tried, including the number of attempts and any errors encountered. The `modelKey` is a unique identifier for the model instance to keep track of models without relying on object reference equality.
+A `RetryAttempt` represents a single failed attempt with a specific model.
 
 ```typescript
-interface RetryState {
-  modelKey: string;
+interface RetryAttempt {
+  error: unknown;
   model: LanguageModelV2;
-  attempts: number;
-  errors: Array<unknown>;
 }
 ```
 
-## Requirements
-
-- AI SDK v2.0+
-- Node.js 16+
-
-## License
+### License
 
 MIT

package/dist/create-retryable-model-DKKgxKLw.d.ts

@@ -0,0 +1,42 @@
+import { LanguageModelV2 } from "@ai-sdk/provider";
+
+//#region src/create-retryable-model.d.ts
+
+/**
+ * The context provided to Retryables with the current attempt and all previous attempts.
+ */
+interface RetryContext {
+  current: RetryAttempt;
+  attempts: Array<RetryAttempt>;
+  totalAttempts: number;
+}
+/**
+ * A retry attempt with the error and model used
+ */
+interface RetryAttempt {
+  error: unknown;
+  model: LanguageModelV2;
+}
+/**
+ * A model to retry with and the maximum number of attempts for that model.
+ */
+type RetryModel = {
+  model: LanguageModelV2;
+  maxAttempts: number;
+};
+/**
+ * A function that determines whether to retry with a different model based on the current attempt and all previous attempts.
+ */
+type Retryable = (context: RetryContext) => RetryModel | Promise<RetryModel> | undefined;
+/**
+ * Options for creating a retryable model.
+ */
+interface CreateRetryableOptions {
+  model: LanguageModelV2;
+  retries: Array<Retryable | LanguageModelV2>;
+  onError?: (context: RetryContext) => void;
+  onRetry?: (context: RetryContext) => void;
+}
+declare function createRetryable(config: CreateRetryableOptions): LanguageModelV2;
+//#endregion
+export { CreateRetryableOptions, RetryAttempt, RetryContext, RetryModel, Retryable, createRetryable };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CreateRetryableOptions, RetryContext, RetryModel, RetryState, Retryable, createRetryable } from "./create-retryable-model-Ddjfs7Y2.js";
+import { CreateRetryableOptions, RetryAttempt, RetryContext, RetryModel, Retryable, createRetryable } from "./create-retryable-model-DKKgxKLw.js";
 import { LanguageModelV2 } from "@ai-sdk/provider";
 
 //#region src/get-model-key.d.ts
@@ -7,4 +7,4 @@ import { LanguageModelV2 } from "@ai-sdk/provider";
  */
 declare const getModelKey: (model: LanguageModelV2) => string;
 //#endregion
-export { CreateRetryableOptions, RetryContext, RetryModel, RetryState, Retryable, createRetryable, getModelKey };
+export { CreateRetryableOptions, RetryAttempt, RetryContext, RetryModel, Retryable, createRetryable, getModelKey };

package/dist/index.js

@@ -46,34 +46,60 @@ var RetryableModel = class {
 		*/
 		let totalAttempts = 0;
 		/**
-		* Track models that have already been tried to avoid infinite loops
+		* Track all attempts.
 		*/
-		const triedModels = /* @__PURE__ */ new Map();
+		const attempts = [];
+		/**
+		* The error occured in the previous attempt or undefined if this is the first attempt
+		*/
+		let currentError;
 		while (true) {
-			totalAttempts++;
+			/**
+			* Call the onRetry handler if provided.
+			* Skip on the first attempt since no error occured yet.
+			*/
+			if (currentError) {
+				/**
+				* Context for the onRetry handler
+				*/
+				const context = {
+					current: {
+						error: currentError,
+						model: this.currentModel
+					},
+					attempts,
+					totalAttempts
+				};
+				/**
+				* Call the onRetry handler if provided
+				*/
+				this.options.onRetry?.(context);
+			}
 			try {
+				totalAttempts++;
 				return await this.currentModel.doGenerate(options);
 			} catch (error) {
-				const currentModelKey = getModelKey(this.currentModel);
-				const prevState = triedModels.get(currentModelKey);
 				/**
-				* Save failed attempt with the current model
+				* Save the error of the current attempt for the retry of the next iteration
+				*/
+				currentError = error;
+				/**
+				* Current attempt with current error
 				*/
-				const newState = {
-					modelKey: currentModelKey,
-					model: this.currentModel,
-					attempts: (prevState?.attempts ?? 0) + 1,
-					errors: [...prevState?.errors ?? [], error]
+				const currentAttempt = {
+					error: currentError,
+					model: this.currentModel
 				};
-				triedModels.set(currentModelKey, newState);
 				/**
-				* Prepare context for the retry handlers
+				* Save the current attempt
+				*/
+				attempts.push(currentAttempt);
+				/**
+				* Context for the retryables and onError handler
 				*/
 				const context = {
-					error,
-					baseModel: this.baseModel,
-					currentModel: this.currentModel,
-					triedModels,
+					current: currentAttempt,
+					attempts,
 					totalAttempts
 				};
 				/**
@@ -87,12 +113,14 @@ var RetryableModel = class {
 				for (const retry of this.options.retries) {
 					const retryModel = typeof retry === "function" ? await retry(context) : defaultRetryModel(retry);
 					if (retryModel) {
+						/**
+						* The model key uniquely identifies a model instance (provider + modelId)
+						*/
 						const retryModelKey = getModelKey(retryModel.model);
-						const retryState = triedModels.get(retryModelKey);
 						/**
 						* Check if the model can still be retried based on maxAttempts
 						*/
-						if (!retryState || retryState.attempts < retryModel.maxAttempts) {
+						if (attempts.filter((a) => getModelKey(a.model) === retryModelKey).length < retryModel.maxAttempts) {
 							nextModel = retryModel.model;
 							break;
 						}
@@ -105,11 +133,11 @@ var RetryableModel = class {
 				if (!nextModel) {
 					if (totalAttempts > 1) {
 						const errorMessage = getErrorMessage(error);
-						const newErrors = Array.from(triedModels.values()).flatMap((state) => state.errors);
+						const errors = attempts.flatMap((a) => a.error);
 						throw new RetryError({
 							message: `Failed after ${totalAttempts} attempts. Last error: ${errorMessage}`,
 							reason: "maxRetriesExceeded",
-							errors: newErrors
+							errors
 						});
 					}
 					throw error;

package/dist/retryables/index.d.ts

@@ -1,4 +1,4 @@
-import { RetryModel, Retryable } from "../create-retryable-model-Ddjfs7Y2.js";
+import { RetryModel, Retryable } from "../create-retryable-model-DKKgxKLw.js";
 import { LanguageModelV2 } from "@ai-sdk/provider";
 
 //#region src/retryables/content-filter-triggered.d.ts

package/dist/retryables/index.js

@@ -13,7 +13,7 @@ const isString = (value) => typeof value === "string";
 */
 function contentFilterTriggered(input) {
 	return (context) => {
-		const { error } = context;
+		const { error } = context.current;
 		const model = "model" in input ? input.model : input;
 		if (APICallError.isInstance(error) && isObject(error.data) && isObject(error.data.error) && isString(error.data.error.code) && error.data.error.code === "content_filter") return {
 			model,
@@ -33,7 +33,7 @@ function contentFilterTriggered(input) {
 */
 function requestNotRetryable(input) {
 	return (context) => {
-		const { error } = context;
+		const { error } = context.current;
 		const model = "model" in input ? input.model : input;
 		if (APICallError$1.isInstance(error) && error.isRetryable === false) return {
 			model,
@@ -50,7 +50,7 @@ function requestNotRetryable(input) {
 */
 function requestTimeout(input) {
 	return (context) => {
-		const { error } = context;
+		const { error } = context.current;
 		const model = "model" in input ? input.model : input;
 		/**
 		* Fallback to the specified model after all retries are exhausted.
@@ -66,7 +66,7 @@ function requestTimeout(input) {
 //#region src/retryables/response-schema-mismatch.ts
 function responseSchemaMismatch(input) {
 	return (context) => {
-		const { error } = context;
+		const { error } = context.current;
 		const model = "model" in input ? input.model : input;
 		if (NoObjectGeneratedError.isInstance(error) && error.finishReason === "stop" && TypeValidationError.isInstance(error.cause)) return {
 			model,

package/package.json

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

package/dist/create-retryable-model-Ddjfs7Y2.d.ts

@@ -1,29 +0,0 @@
-import { LanguageModelV2 } from "@ai-sdk/provider";
-
-//#region src/create-retryable-model.d.ts
-interface RetryContext {
-  error: unknown;
-  baseModel: LanguageModelV2;
-  currentModel: LanguageModelV2;
-  triedModels: Map<string, RetryState>;
-  totalAttempts: number;
-}
-type RetryModel = {
-  model: LanguageModelV2;
-  maxAttempts: number;
-};
-type Retryable = (context: RetryContext) => RetryModel | Promise<RetryModel> | undefined;
-type RetryState = {
-  modelKey: string;
-  model: LanguageModelV2;
-  attempts: number;
-  errors: Array<unknown>;
-};
-interface CreateRetryableOptions {
-  model: LanguageModelV2;
-  retries: Array<Retryable | LanguageModelV2>;
-  onError?: (context: RetryContext) => void;
-}
-declare function createRetryable(config: CreateRetryableOptions): LanguageModelV2;
-//#endregion
-export { CreateRetryableOptions, RetryContext, RetryModel, RetryState, Retryable, createRetryable };