ai-retry 1.6.0 → 1.7.0

package/README.md

@@ -249,7 +249,7 @@ const retryableModel = createRetryable({
 });
 ```
 
-Result-based retryables are only available for generate calls like `generateText` and `generateObject`. They are not available for streaming calls like `streamText` and `streamObject`.
+Result-based retryables apply to language models for both generate (`generateText`, `generateObject`) and streaming (`streamText`, `streamObject`) calls. For streams, the retry decision happens when the upstream `finish` part arrives and only fires if no content has been emitted yet, so behavior like `finishReason: 'content-filter'` on an otherwise empty response can still trigger a fallback. Once any content chunk has been forwarded, the stream is committed and result-based retries are skipped.
 
 #### Fallbacks
 
@@ -389,8 +389,8 @@ There are several built-in dynamic retryables available for common use cases:
 
 Automatically switch to a different model when content filtering blocks your request.
 
-> [!WARNING]  
-> This retryable currently does not work with streaming requests, because the content filter is only indicated in the final response.
+> [!NOTE]
+> For streaming requests this retryable can only fire if the content filter trips before any content has been emitted. Once a text chunk flows through, the stream is committed and the fallback is skipped.
 
 ```typescript
 import { contentFilterTriggered } from 'ai-retry/retryables';
@@ -587,24 +587,40 @@ console.log(result.object); // { name: "Alice", age: 30 }
 ### Experimental: Composable Conditions
 
 > [!WARNING]
-> This API is experimental and may change. It is not exported from the package root; opt in via the deep import:
+> This API is experimental and may change. It is not exported from the package root; opt in via one of the per-model deep imports:
+>
+> ```ts
+> import { ... } from 'ai-retry/experimental/language-model';
+> import { ... } from 'ai-retry/experimental/image-model';
+> import { ... } from 'ai-retry/experimental/embedding-model';
+> ```
+>
+> Each entry point also re-exports `createRetryable` already typed for that model family, so you can either import everything from one path:
 >
 > ```ts
-> import { ... } from 'ai-retry/retryables/experimental';
+> import { createRetryable, error, httpStatus } from 'ai-retry/experimental/language-model';
+> ```
+>
+> or pull retryables from the dedicated `/retryables` subpath:
+>
+> ```ts
+> import { error, httpStatus } from 'ai-retry/experimental/language-model/retryables';
+> // or
+> import * as retryables from 'ai-retry/experimental/language-model/retryables';
 > ```
 
-A `condition().action()` API for retryables. Conditions are built from small primitives (`error(fn)`, `result(fn)`), composed with `and` / `or` / `not`, and turned into a `Retryable` by one of two terminal actions: `.switch({ model })` or `.retry({ delay })`. The result drops into the same `retries: [...]` array as the stable helpers, so you can mix the two styles freely.
+A `condition().action()` API for retryables. Conditions are built from small primitives (`error(fn)`, `result(fn)`), composed with `.and` / `.or` / `.not`, and turned into a `Retryable` by one of two terminal actions: `.switch({ model })` or `.retry({ delay })`. The result drops into the same `retries: [...]` array as the stable helpers, so you can mix the two styles freely.
 
 ```typescript
 import { anthropic } from '@ai-sdk/anthropic';
 import { openai } from '@ai-sdk/openai';
 import { generateText } from 'ai';
-import { createRetryable } from 'ai-retry';
 import {
+  createRetryable,
   error,
   finishReason,
   httpStatus,
-} from 'ai-retry/retryables/experimental';
+} from 'ai-retry/experimental/language-model';
 
 const retryableModel = createRetryable({
   model: openai('gpt-4'),
@@ -623,86 +639,109 @@ const retryableModel = createRetryable({
 });
 ```
 
-#### High-level helpers
+#### Picking an entry point
 
-These cover the common cases. Each returns a `Condition` that you finalize with `.switch(...)` or `.retry(...)`.
+Pick the entry point that matches the model you pass to `createRetryable`. Each module exposes the helpers that make sense for that model family already typed for it, so you don't need to add type annotations yourself.
 
-| Helper                         | Matches when                                                                                       |
-| ------------------------------ | -------------------------------------------------------------------------------------------------- |
-| `httpStatus(...patterns)`      | Numbers match the status code; strings match the message (substring); regex matches either        |
-| `timeout()`                    | `Error.name === 'TimeoutError'` (`AbortSignal.timeout()` fired)                                    |
-| `aborted()`                    | `Error.name === 'AbortError'` (manual `controller.abort()`)                                        |
-| `noImage()`                    | The image model threw `NoImageGeneratedError`                                                      |
-| `finishReason(...reasons)`     | The result's `finishReason.unified` matches one of the given values                                |
-| `schemaInvalid()`              | The result text fails JSON-schema validation against the call's `responseFormat`                   |
+#### Low-level conditions
 
-#### Actions
+The primitive builders `error(...)` and `result(...)` take a predicate and turn it into a condition; their namespaces bundle the most common field matchers on top.
 
-Every `Condition` exposes two terminal actions that turn it into a `Retryable`:
+| Helper                            | Matches when                                                                          | Available in              |
+| --------------------------------- | ------------------------------------------------------------------------------------- | ------------------------- |
+| `error(predicate)`                | The current attempt failed and `predicate(err, ctx)` returns true                     | all three entry points    |
+| `error.isRetryable(flag)`         | `APICallError.isRetryable === flag` (default `true`)                                  | all three entry points    |
+| `error.statusCode(...patterns)`   | Numbers match exactly; regex matches the stringified code (e.g. `/^5\d\d$/` for 5xx)  | all three entry points    |
+| `error.message(...patterns)`      | Substring (case-insensitive) or regex match against the error message                 | all three entry points    |
+| `result(predicate)`               | The current attempt succeeded and `predicate(res, ctx)` returns true                  | `language-model` only     |
+| `result.finishReason(...reasons)` | The result's `finishReason.unified` matches one of the given values                   | `language-model` only     |
 
-- **`.switch({ model, ...options })`** falls back to a different model when the condition matches. Optional fields (`maxAttempts`, `delay`, `backoffFactor`, `timeout`, `options`) are the same as on a normal `Retry` object.
-- **`.retry({ delay?, backoffFactor?, ... })`** retries the current model when the condition matches. Honors `Retry-After` and `Retry-After-Ms` response headers when present, capped at 60 seconds.
+```typescript
+import { APICallError } from 'ai';
+import { error } from 'ai-retry/experimental/language-model';
 
-#### Combinators
+error((e) => APICallError.isInstance(e) && e.statusCode === 418).switch({
+  model: fallback,
+});
+```
+
+#### High-level conditions
+
+Convenience matchers built on top of the low-level ones for the common cases. Each returns a condition that you finalize with `.switch(...)` or `.retry(...)`.
+
+| Helper                     | language-model | image-model | embedding-model |
+| -------------------------- | :------------: | :---------: | :-------------: |
+| `httpStatus(...patterns)`  |       ✓        |      ✓      |        ✓        |
+| `timeout()`                |       ✓        |      ✓      |        ✓        |
+| `aborted()`                |       ✓        |      ✓      |        ✓        |
+| `finishReason(...reasons)` |       ✓        |      —      |        —        |
+| `schemaInvalid()`          |       ✓        |      —      |        —        |
+| `noImage()`                |       —        |      ✓      |        —        |
+
+What each one matches:
+
+| Helper                     | Matches when                                                                                       |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| `httpStatus(...patterns)`  | Numbers match the status code; strings match the message (substring); regex matches either         |
+| `timeout()`                | `Error.name === 'TimeoutError'` (`AbortSignal.timeout()` fired)                                    |
+| `aborted()`                | `Error.name === 'AbortError'` (manual `controller.abort()`)                                        |
+| `finishReason(...reasons)` | The result's `finishReason.unified` matches one of the given values                                |
+| `schemaInvalid()`          | The result text fails JSON-schema validation against the call's `responseFormat`                   |
+| `noImage()`                | The image model threw `NoImageGeneratedError`                                                      |
 
-Compose conditions with the free functions or the methods on `Condition`:
+Each high-level helper is a thin wrapper around the low-level ones. For example, `timeout()` is roughly:
 
 ```typescript
-import {
-  and,
-  error,
-  httpStatus,
-  not,
-  or,
-} from 'ai-retry/retryables/experimental';
+function timeout() {
+  return error(
+    (err) => err instanceof Error && err.name === 'TimeoutError',
+  );
+}
+```
 
-or(httpStatus(429), error.message('overloaded'));
-and(httpStatus(503), error.message('temporary'));
-not(error.isRetryable(true));
+and `finishReason(...)` just delegates to `result.finishReason(...)`:
 
-// Method form
-httpStatus(429).or(error.message('overloaded'));
+```typescript
+function finishReason(...reasons: Array<string>) {
+  return result.finishReason(...reasons);
+}
 ```
 
-#### Primitives
+#### Actions
 
-The two lowest-level builders. Reach for them when no helper covers your case:
+Every condition exposes two terminal actions that turn it into a `Retryable`:
 
-| Primitive          | Matches when                                                                  |
-| ------------------ | ----------------------------------------------------------------------------- |
-| `error(predicate)` | The current attempt failed and `predicate(err, ctx)` returns true             |
-| `result(predicate)`| The current attempt succeeded and `predicate(res, ctx)` returns true (language models only) |
+- **`.switch({ model, ...options })`** falls back to a different model when the condition matches. Optional fields (`maxAttempts`, `delay`, `backoffFactor`, `timeout`, `options`) are the same as on a normal `Retry` object. `maxAttempts` defaults to `1`.
+- **`.retry({ delay?, backoffFactor?, maxAttempts?, ... })`** retries the current model when the condition matches. Honors `Retry-After` and `Retry-After-Ms` response headers when present, capped at 60 seconds. `maxAttempts` defaults to `2` (one original attempt + one retry); values below `2` throw, since the retry budget is consumed by the original failure.
 
-```typescript
-import { APICallError } from 'ai';
-import { error } from 'ai-retry/retryables/experimental';
+#### Combinators
 
-error<MODEL, APICallError>(
-  (e) => APICallError.isInstance(e) && e.statusCode === 418,
-).switch({ model: fallback });
-```
+Compose conditions with `.and`, `.or`, `.not`:
 
-A few common error fields have ready-made matchers on the `error` namespace:
+```typescript
+import {
+  error,
+  httpStatus,
+} from 'ai-retry/experimental/language-model';
 
-| Helper                          | Matches when                                                                          |
-| ------------------------------- | ------------------------------------------------------------------------------------- |
-| `error.isRetryable(flag)`       | `APICallError.isRetryable === flag` (default `true`)                                  |
-| `error.statusCode(...patterns)` | Numbers match exactly; regex matches the stringified code (e.g. `/^5\d\d$/` for 5xx)  |
-| `error.message(...patterns)`    | Substring (case-insensitive) or regex match against the error message                 |
+httpStatus(429).or(error.message('overloaded'));
+httpStatus(503).and(error.message('temporary'));
+error.isRetryable(true).not();
+```
 
 #### Mapping from Built-in retryables
 
-Each stable retryable has an equivalent in the new shape:
+Each stable retryable has an equivalent in the new shape (imports from `ai-retry/experimental/language-model` unless noted):
 
 | Built-in                                        | Composable form                                                                                       |
 | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `contentFilterTriggered(m)`                     | `or(error(/* check e.data.error.code === 'content_filter' */), finishReason('content-filter')).switch({ model: m })` |
+| `contentFilterTriggered(m)`                     | `error(/* check e.data.error.code === 'content_filter' */).or(finishReason('content-filter')).switch({ model: m })` |
 | `requestTimeout(m)`                             | `timeout().switch({ model: m, timeout: 60_000 })`                                                     |
 | `requestNotRetryable(m)`                        | `error.isRetryable(false).switch({ model: m })`                                                       |
 | `schemaMismatch(m)`                             | `schemaInvalid().switch({ model: m })`                                                                |
 | `serviceOverloaded(m)`                          | `httpStatus(529, 'overloaded').switch({ model: m })`                                                  |
 | `serviceUnavailable(m)`                         | `error.statusCode(503).switch({ model: m })`                                                          |
-| `noImageGenerated(m)`                           | `noImage().switch({ model: m })`                                                                      |
+| `noImageGenerated(m)`                           | `noImage().switch({ model: m })` (from `image-model`)                                                 |
 | `retryAfterDelay({ delay, backoffFactor })`     | `error.isRetryable(true).retry({ delay, backoffFactor })`                                             |
 
 > [!NOTE]
@@ -782,7 +821,9 @@ const retryableModel = createRetryable({
 
 #### Timeouts
 
-When a retry specifies a `timeout` value, a fresh `AbortSignal.timeout()` is created for that retry attempt, replacing any existing abort signal. This is essential when retrying after timeout errors, as the original abort signal would already be in an aborted state.
+When a retry specifies a `timeout` value, a fresh `AbortSignal.timeout()` is created for that retry attempt. If the original `abortSignal` is still alive, the fresh deadline is composed with it via `AbortSignal.any()` so user cancellation still works mid-retry. If the original signal is already aborted (for example it carried a request-level deadline that already fired), it is dropped so the retry runs against the fresh deadline alone.
+
+If the original `abortSignal` is already aborted at the time of retry and the chosen retry does **not** supply a `timeout`, ai-retry rethrows the original error rather than firing a misleading retry against the dead signal. `onError` still fires for observability, but `onRetry` is skipped. Setting `retry.timeout` is the explicit opt-in for retrying past an aborted signal.
 
 ```typescript
 const retryableModel = createRetryable({
@@ -925,7 +966,7 @@ The following options can be overridden:
 
 #### Dynamic Call Options
 
-You can also override call options dynamically from inside the `onRetry` callback, instead of declaring them statically on the retry object. This is useful when the override depends on something only known at runtime, like the prompt that just failed, the model that's about to be tried next, or the error that triggered the retry. The overrides apply to the upcoming retry attempt only, and can change the same fields as the static `options` on a retry plus the request `timeout`. The callback may also be `async` if computing the override needs to do work (e.g. fetching a fresh credential).
+You can also override call options dynamically from inside the `onRetry` callback, instead of declaring them statically on the retry object. This is useful when the override depends on something only known at runtime, like the prompt that just failed, the model that's about to be tried next, or the error that triggered the retry. The overrides apply to the upcoming retry attempt only, and can change the same fields as the static `options` on a retry. The callback may also be `async` if computing the override needs to do work (e.g. fetching a fresh credential).
 
 A common use case is sanitizing provider-scoped metadata when falling back to a different provider, for example stripping `providerOptions.azure.itemId` references from the previous prompt before retrying on OpenAI:
 
@@ -1090,7 +1131,7 @@ interface RetryableModelOptions<
 - `disabled`: Disable all retry logic. Can be a boolean or function returning boolean. Default: `false` (retries enabled).
 - `reset`: Controls when to reset back to the base model after a successful retry. Default: `after-request`.
 - `onError`: Callback invoked when an error occurs.
-- `onRetry`: Callback invoked before attempting a retry. May optionally return an `OnRetryOverrides` object (or a `Promise` of one) to override `options.*` and `timeout` for the upcoming attempt only. See [Dynamic Call Options via `onRetry`](#dynamic-call-options-via-onretry).
+- `onRetry`: Callback invoked before attempting a retry. May optionally return an `OnRetryOverrides` object (or a `Promise` of one) to override `options.*` for the upcoming attempt only. See [Dynamic Call Options via `onRetry`](#dynamic-call-options-via-onretry).
 - `onSuccess`: Callback invoked after a successful request. Receives the model that handled the request and all previous attempts.
 
 #### `Reset`
@@ -1167,7 +1208,7 @@ interface SuccessAttempt {
   type: 'success';
   model: LanguageModelV3 | EmbeddingModelV3 | ImageModelV3;
   result:
-    | LanguageModelGenerate
+    | LanguageModelResult
     | LanguageModelStream
     | EmbeddingModelEmbed
     | ImageModelGenerate;
@@ -1196,12 +1237,12 @@ type RetryAttempt =
     }
   | {
       type: 'result';
-      result: LanguageModelV3Generate;
+      result: LanguageModelResult;
       model: LanguageModelV3;
       options: LanguageModelV3CallOptions;
     };
 
-// Note: Result-based retries only apply to language models, not embedding or image models
+// Note: Result-based retries only apply to language models (both generate and stream paths). They do not apply to embedding or image models. For streaming, retries are only possible before any content has been emitted; once a text-delta flows through, the stream is committed.
 
 // Type guards for discriminating attempts
 function isErrorAttempt(attempt: RetryAttempt): attempt is RetryErrorAttempt;