ai-retry 0.8.0 → 0.10.0

package/README.md

@@ -251,12 +251,16 @@ Errors are tracked per unique model (provider + modelId). That means on the firs
 
 There are several built-in dynamic retryables available for common use cases:
 
+> [!TIP]
+> You are missing a retryable for your use case? [Open an issue](https://github.com/zirkelc/ai-retry/issues/new) and let's discuss it!
+
 - [`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.
+- [`serviceUnavailable`](./src/retryables/service-unavailable.ts): Response with status code 503 (service unavailable).
 
 #### Content Filter
 
@@ -324,6 +328,21 @@ const retryableModel = createRetryable({
 });
 ```
 
+#### Service Unavailable
+
+Handle service unavailable errors (status code 503) by switching to a different provider.
+
+```typescript
+import { serviceUnavailable } from 'ai-retry/retryables';
+
+const retryableModel = createRetryable({
+  model: azure('gpt-4'),
+  retries: [
+    serviceUnavailable(openai('gpt-4')), // Switch to OpenAI if Azure is unavailable
+  ],
+});
+```
+
 #### Request Not Retryable
 
 Handle cases where the base model fails with a non-retryable error.
@@ -372,6 +391,32 @@ By default, if a [`retry-after-ms`](https://learn.microsoft.com/en-us/azure/ai-f
 
 ### Options
 
+#### Disabling Retries
+
+You can disable retries entirely, which is useful for testing or specific environments. When disabled, the base model will execute directly without any retry logic.
+
+```typescript
+const retryableModel = createRetryable({
+  model: openai('gpt-4'), // Base model
+  retries: [/* ... */],
+  disabled: true, // Retries are completely disabled
+});
+
+// Or disable based on environment
+const retryableModel = createRetryable({
+  model: openai('gpt-4'), // Base model
+  retries: [/* ... */],
+  disabled: process.env.NODE_ENV === 'test', // Disable in test environment
+});
+
+// Or use a function for dynamic control
+const retryableModel = createRetryable({
+  model: openai('gpt-4'), // Base model
+  retries: [/* ... */],
+  disabled: () => !featureFlags.isEnabled('ai-retries'), // Check feature flag
+});
+```
+
 #### Retry Delays
 
 You can delay retries with an optional exponential backoff. The delay respects abort signals, so requests can still be cancelled during the delay period.
@@ -529,11 +574,19 @@ Creates a retryable model that works with both language models and embedding mod
 interface RetryableModelOptions<MODEL extends LanguageModelV2 | EmbeddingModelV2> {
   model: MODEL;
   retries: Array<Retryable<MODEL> | MODEL>;
+  disabled?: boolean | (() => boolean);
   onError?: (context: RetryContext<MODEL>) => void;
   onRetry?: (context: RetryContext<MODEL>) => void;
 }
 ```
 
+**Options:**
+- `model`: The base model to use for the initial request.
+- `retries`: Array of retryables (functions, models, or retry objects) to attempt on failure.
+- `disabled`: Disable all retry logic. Can be a boolean or function returning boolean. Default: `false` (retries enabled).
+- `onError`: Callback invoked when an error occurs.
+- `onRetry`: Callback invoked before attempting a retry.
+
 #### `Retryable`
 
 A `Retryable` is a function that receives a `RetryContext` with the current error or result and model and all previous attempts.

package/dist/index.js

@@ -105,6 +105,13 @@ var RetryableEmbeddingModel = class {
 		this.currentModel = options.model;
 	}
 	/**
+	* Check if retries are disabled
+	*/
+	isDisabled() {
+		if (this.options.disabled === void 0) return false;
+		return typeof this.options.disabled === "function" ? this.options.disabled() : this.options.disabled;
+	}
+	/**
 	* Execute a function with retry logic for handling errors
 	*/
 	async withRetry(input) {
@@ -197,6 +204,10 @@ var RetryableEmbeddingModel = class {
 		* Always start with the original model
 		*/
 		this.currentModel = this.baseModel;
+		/**
+		* If retries are disabled, bypass retry machinery entirely
+		*/
+		if (this.isDisabled()) return this.currentModel.doEmbed(options);
 		const { result } = await this.withRetry({
 			fn: async (currentRetry) => {
 				const callOptions = {
@@ -234,6 +245,13 @@ var RetryableLanguageModel = class {
 		this.currentModel = options.model;
 	}
 	/**
+	* Check if retries are disabled
+	*/
+	isDisabled() {
+		if (this.options.disabled === void 0) return false;
+		return typeof this.options.disabled === "function" ? this.options.disabled() : this.options.disabled;
+	}
+	/**
 	* Execute a function with retry logic for handling errors
 	*/
 	async withRetry(input) {
@@ -371,6 +389,10 @@ var RetryableLanguageModel = class {
 		* Always start with the original model
 		*/
 		this.currentModel = this.baseModel;
+		/**
+		* If retries are disabled, bypass retry machinery entirely
+		*/
+		if (this.isDisabled()) return this.currentModel.doGenerate(options);
 		const { result } = await this.withRetry({
 			fn: async (currentRetry) => {
 				const callOptions = {
@@ -390,6 +412,10 @@ var RetryableLanguageModel = class {
 		*/
 		this.currentModel = this.baseModel;
 		/**
+		* If retries are disabled, bypass retry machinery entirely
+		*/
+		if (this.isDisabled()) return this.currentModel.doStream(options);
+		/**
 		* Perform the initial call to doStream with retry logic to handle errors before any data is streamed.
 		*/
 		let { result, attempts } = await this.withRetry({

package/dist/retryables/index.d.ts

@@ -39,4 +39,11 @@ declare function retryAfterDelay<MODEL extends LanguageModelV2 | EmbeddingModelV
  */
 declare function serviceOverloaded<MODEL extends LanguageModelV2 | EmbeddingModelV2>(model: MODEL, options?: RetryableOptions<MODEL>): Retryable<MODEL>;
 //#endregion
-export { contentFilterTriggered, requestNotRetryable, requestTimeout, retryAfterDelay, serviceOverloaded };
+//#region src/retryables/service-unavailable.d.ts
+/**
+ * Fallback to a different model if the provider returns a service unavailable error.
+ * This retryable handles HTTP status code 503 (Service Unavailable).
+ */
+declare function serviceUnavailable<MODEL extends LanguageModelV2 | EmbeddingModelV2>(model: MODEL, options?: RetryableOptions<MODEL>): Retryable<MODEL>;
+//#endregion
+export { contentFilterTriggered, requestNotRetryable, requestTimeout, retryAfterDelay, serviceOverloaded, serviceUnavailable };

package/dist/retryables/index.js

@@ -152,4 +152,24 @@ function serviceOverloaded(model, options) {
 }
 
 //#endregion
-export { contentFilterTriggered, requestNotRetryable, requestTimeout, retryAfterDelay, serviceOverloaded };
+//#region src/retryables/service-unavailable.ts
+/**
+* Fallback to a different model if the provider returns a service unavailable error.
+* This retryable handles HTTP status code 503 (Service Unavailable).
+*/
+function serviceUnavailable(model, options) {
+	return (context) => {
+		const { current } = context;
+		if (isErrorAttempt(current)) {
+			const { error } = current;
+			if (APICallError.isInstance(error) && error.statusCode === 503) return {
+				model,
+				maxAttempts: 1,
+				...options
+			};
+		}
+	};
+}
+
+//#endregion
+export { contentFilterTriggered, requestNotRetryable, requestTimeout, retryAfterDelay, serviceOverloaded, serviceUnavailable };

package/package.json

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