@ax-llm/ax 22.0.5 → 22.0.7

package/index.d.cts

@@ -432,6 +432,20 @@ declare class AxBaseAI<TModel, TEmbedModel, TChatRequest, TEmbedRequest, TChatRe
     chat(req: Readonly<AxChatRequest<TModel | TModelKey>>, options?: Readonly<AxAIServiceOptions>): Promise<AxChatResponse | ReadableStream<AxChatResponse>>;
     private _chat1;
     private cleanupFunctionSchema;
+    /**
+     * Peeks the first raw streaming delta and, if the provider classifies it as a retryable
+     * transient error (e.g. an Anthropic `overloaded_error` SSE event), re-issues the request
+     * with exponential backoff — the same policy {@link apiCall} applies to an HTTP 529 status,
+     * so streaming and non-streaming overloads behave identically. The first delta is classified
+     * on the raw chunk (no stateful transform runs), so peeking has no side effects. After the
+     * retry budget is exhausted the original error delta is replayed so it surfaces normally
+     * (and the balancer can still fail over). A non-error first delta is replayed unchanged.
+     *
+     * Note: re-issuing cancels the previous stream's reader best-effort; the underlying fetch
+     * body of the abandoned overloaded request is released by GC rather than promptly aborted,
+     * since apiCall's streams don't propagate cancel. Acceptable for the transient-overload case.
+     */
+    private retryTransientStreamStart;
     private _chat2;
     embed(req: Readonly<AxEmbedRequest<TEmbedModel>>, options?: Readonly<AxAIServiceOptions>): Promise<AxEmbedResponse>;
     private _embed1;
@@ -1384,6 +1398,14 @@ interface AxAIServiceImpl<TModel, TEmbedModel, TChatRequest, TEmbedRequest, TCha
     createChatReq(req: Readonly<AxInternalChatRequest<TModel>>, config?: Readonly<AxAIServiceOptions>): Promise<[AxAPI, TChatRequest]> | [AxAPI, TChatRequest];
     createChatResp(resp: Readonly<TChatResponse>): AxChatResponse;
     createChatStreamResp?(resp: Readonly<TChatResponseDelta>, state: object): AxChatResponse;
+    /**
+     * Optional: classify a raw streaming delta that carries a transient error into the
+     * HTTP status it corresponds to (e.g. Anthropic's HTTP-200 `overloaded_error` SSE event
+     * → 529). The base layer applies the same retryable-status policy used for real HTTP
+     * status errors, so a streaming overload is retried-with-backoff before any failover —
+     * matching the non-streaming path. Return undefined for normal deltas (the common case).
+     */
+    classifyStreamErrorStatus?(resp: Readonly<TChatResponseDelta>): number | undefined;
     createEmbedReq?(req: Readonly<AxInternalEmbedRequest<TEmbedModel>>, config?: Readonly<AxAIServiceOptions>): Promise<[AxAPI, TEmbedRequest]> | [AxAPI, TEmbedRequest];
     createEmbedResp?(resp: Readonly<TEmbedResponse>): AxEmbedResponse;
     getModelConfig(): AxModelConfig;
@@ -6259,7 +6281,7 @@ type AxAIAnthropicChatResponse = {
 type AxAIAnthropicChatError = {
     type: 'error';
     error: {
-        type: 'authentication_error';
+        type: 'overloaded_error' | 'api_error' | 'rate_limit_error' | 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'not_found_error' | 'request_too_large';
         message: string;
     };
 };
@@ -6349,7 +6371,7 @@ interface AxAIAnthropicPingEvent {
 interface AxAIAnthropicErrorEvent {
     type: 'error';
     error: {
-        type: 'overloaded_error';
+        type: 'overloaded_error' | 'api_error' | 'rate_limit_error' | 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'not_found_error' | 'request_too_large';
         message: string;
     };
 }
@@ -6858,6 +6880,7 @@ declare class AxBalancer<TServices extends readonly AxAIService<any, any, any>[]
     private maxBackoffMs;
     private maxRetries;
     private serviceFailures;
+    private static readonly RETRYABLE_STATUS_CODES;
     constructor(services: TServices, options?: AxBalancerOptions<TModelKey>);
     /**
      * Static factory method for type-safe balancer creation with automatic model key inference.
@@ -6885,6 +6908,26 @@ declare class AxBalancer<TServices extends readonly AxAIService<any, any, any>[]
     private canRetryService;
     private handleFailure;
     private handleSuccess;
+    /**
+     * Whether an error should route to another service rather than fail the request.
+     * Mirrors the decisions made in chat()'s catch block so the streaming peek path and
+     * the synchronous path agree on what "retryable" means.
+     */
+    private isRetryableServiceError;
+    /**
+     * Wraps a streaming response to make it participate in failover. Two responsibilities:
+     *
+     * 1. Pre-content errors: eagerly reads the first chunk so a provider error thrown while
+     *    reading (e.g. Anthropic's HTTP-200 `overloaded_error` SSE) rejects here, where
+     *    {@link chat}'s try/catch can route it through the normal failover path. On success it
+     *    returns a new stream that re-emits the buffered first chunk then pumps the rest.
+     * 2. Mid-stream errors: a retryable error *after* the first chunk can't fail over
+     *    transparently (partial output is already committed), so it is surfaced via
+     *    `controller.error`. But we record the failure first (see {@link handleFailure}) —
+     *    otherwise the failed service stays out of backoff and an app-level retry via chat()
+     *    (which restarts at index 0 and doesn't reset()) would route straight back to it.
+     */
+    private peekStreamForFailover;
     chat(req: Readonly<AxChatRequest<TModelKey>>, options?: Readonly<AxAIServiceOptions>): Promise<AxChatResponse | ReadableStream<AxChatResponse>>;
     embed(req: Readonly<AxEmbedRequest<TModelKey>>, options?: Readonly<AxAIServiceOptions>): Promise<AxEmbedResponse>;
     transcribe(req: Readonly<AxTranscriptionRequest<TModelKey>>, options?: Readonly<AxAIServiceOptions>): Promise<AxTranscriptionResponse>;

package/index.d.ts

@@ -432,6 +432,20 @@ declare class AxBaseAI<TModel, TEmbedModel, TChatRequest, TEmbedRequest, TChatRe
     chat(req: Readonly<AxChatRequest<TModel | TModelKey>>, options?: Readonly<AxAIServiceOptions>): Promise<AxChatResponse | ReadableStream<AxChatResponse>>;
     private _chat1;
     private cleanupFunctionSchema;
+    /**
+     * Peeks the first raw streaming delta and, if the provider classifies it as a retryable
+     * transient error (e.g. an Anthropic `overloaded_error` SSE event), re-issues the request
+     * with exponential backoff — the same policy {@link apiCall} applies to an HTTP 529 status,
+     * so streaming and non-streaming overloads behave identically. The first delta is classified
+     * on the raw chunk (no stateful transform runs), so peeking has no side effects. After the
+     * retry budget is exhausted the original error delta is replayed so it surfaces normally
+     * (and the balancer can still fail over). A non-error first delta is replayed unchanged.
+     *
+     * Note: re-issuing cancels the previous stream's reader best-effort; the underlying fetch
+     * body of the abandoned overloaded request is released by GC rather than promptly aborted,
+     * since apiCall's streams don't propagate cancel. Acceptable for the transient-overload case.
+     */
+    private retryTransientStreamStart;
     private _chat2;
     embed(req: Readonly<AxEmbedRequest<TEmbedModel>>, options?: Readonly<AxAIServiceOptions>): Promise<AxEmbedResponse>;
     private _embed1;
@@ -1384,6 +1398,14 @@ interface AxAIServiceImpl<TModel, TEmbedModel, TChatRequest, TEmbedRequest, TCha
     createChatReq(req: Readonly<AxInternalChatRequest<TModel>>, config?: Readonly<AxAIServiceOptions>): Promise<[AxAPI, TChatRequest]> | [AxAPI, TChatRequest];
     createChatResp(resp: Readonly<TChatResponse>): AxChatResponse;
     createChatStreamResp?(resp: Readonly<TChatResponseDelta>, state: object): AxChatResponse;
+    /**
+     * Optional: classify a raw streaming delta that carries a transient error into the
+     * HTTP status it corresponds to (e.g. Anthropic's HTTP-200 `overloaded_error` SSE event
+     * → 529). The base layer applies the same retryable-status policy used for real HTTP
+     * status errors, so a streaming overload is retried-with-backoff before any failover —
+     * matching the non-streaming path. Return undefined for normal deltas (the common case).
+     */
+    classifyStreamErrorStatus?(resp: Readonly<TChatResponseDelta>): number | undefined;
     createEmbedReq?(req: Readonly<AxInternalEmbedRequest<TEmbedModel>>, config?: Readonly<AxAIServiceOptions>): Promise<[AxAPI, TEmbedRequest]> | [AxAPI, TEmbedRequest];
     createEmbedResp?(resp: Readonly<TEmbedResponse>): AxEmbedResponse;
     getModelConfig(): AxModelConfig;
@@ -6259,7 +6281,7 @@ type AxAIAnthropicChatResponse = {
 type AxAIAnthropicChatError = {
     type: 'error';
     error: {
-        type: 'authentication_error';
+        type: 'overloaded_error' | 'api_error' | 'rate_limit_error' | 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'not_found_error' | 'request_too_large';
         message: string;
     };
 };
@@ -6349,7 +6371,7 @@ interface AxAIAnthropicPingEvent {
 interface AxAIAnthropicErrorEvent {
     type: 'error';
     error: {
-        type: 'overloaded_error';
+        type: 'overloaded_error' | 'api_error' | 'rate_limit_error' | 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'not_found_error' | 'request_too_large';
         message: string;
     };
 }
@@ -6858,6 +6880,7 @@ declare class AxBalancer<TServices extends readonly AxAIService<any, any, any>[]
     private maxBackoffMs;
     private maxRetries;
     private serviceFailures;
+    private static readonly RETRYABLE_STATUS_CODES;
     constructor(services: TServices, options?: AxBalancerOptions<TModelKey>);
     /**
      * Static factory method for type-safe balancer creation with automatic model key inference.
@@ -6885,6 +6908,26 @@ declare class AxBalancer<TServices extends readonly AxAIService<any, any, any>[]
     private canRetryService;
     private handleFailure;
     private handleSuccess;
+    /**
+     * Whether an error should route to another service rather than fail the request.
+     * Mirrors the decisions made in chat()'s catch block so the streaming peek path and
+     * the synchronous path agree on what "retryable" means.
+     */
+    private isRetryableServiceError;
+    /**
+     * Wraps a streaming response to make it participate in failover. Two responsibilities:
+     *
+     * 1. Pre-content errors: eagerly reads the first chunk so a provider error thrown while
+     *    reading (e.g. Anthropic's HTTP-200 `overloaded_error` SSE) rejects here, where
+     *    {@link chat}'s try/catch can route it through the normal failover path. On success it
+     *    returns a new stream that re-emits the buffered first chunk then pumps the rest.
+     * 2. Mid-stream errors: a retryable error *after* the first chunk can't fail over
+     *    transparently (partial output is already committed), so it is surfaced via
+     *    `controller.error`. But we record the failure first (see {@link handleFailure}) —
+     *    otherwise the failed service stays out of backoff and an app-level retry via chat()
+     *    (which restarts at index 0 and doesn't reset()) would route straight back to it.
+     */
+    private peekStreamForFailover;
     chat(req: Readonly<AxChatRequest<TModelKey>>, options?: Readonly<AxAIServiceOptions>): Promise<AxChatResponse | ReadableStream<AxChatResponse>>;
     embed(req: Readonly<AxEmbedRequest<TModelKey>>, options?: Readonly<AxAIServiceOptions>): Promise<AxEmbedResponse>;
     transcribe(req: Readonly<AxTranscriptionRequest<TModelKey>>, options?: Readonly<AxAIServiceOptions>): Promise<AxTranscriptionResponse>;