ai-retry 1.6.1 → 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:
 
-Compose conditions with the free functions or the methods on `Condition`:
+| 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`                                                      |
+
+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
+
+Every condition exposes two terminal actions that turn it into a `Retryable`:
+
+- **`.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.
 
-The two lowest-level builders. Reach for them when no helper covers your case:
+#### Combinators
 
-| 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) |
+Compose conditions with `.and`, `.or`, `.not`:
 
 ```typescript
-import { APICallError } from 'ai';
-import { error } from 'ai-retry/retryables/experimental';
+import {
+  error,
+  httpStatus,
+} from 'ai-retry/experimental/language-model';
 
-error<MODEL, APICallError>(
-  (e) => APICallError.isInstance(e) && e.statusCode === 418,
-).switch({ model: fallback });
+httpStatus(429).or(error.message('overloaded'));
+httpStatus(503).and(error.message('temporary'));
+error.isRetryable(true).not();
 ```
 
-A few common error fields have ready-made matchers on the `error` namespace:
-
-| 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                 |
-
 #### 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]
@@ -1169,7 +1208,7 @@ interface SuccessAttempt {
   type: 'success';
   model: LanguageModelV3 | EmbeddingModelV3 | ImageModelV3;
   result:
-    | LanguageModelGenerate
+    | LanguageModelResult
     | LanguageModelStream
     | EmbeddingModelEmbed
     | ImageModelGenerate;
@@ -1198,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;