ai-functions 2.1.1 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.turbo/turbo-build.log +1 -4
- package/CHANGELOG.md +68 -1
- package/README.md +397 -157
- package/dist/ai-promise.d.ts +50 -3
- package/dist/ai-promise.d.ts.map +1 -1
- package/dist/ai-promise.js +410 -51
- package/dist/ai-promise.js.map +1 -1
- package/dist/ai-schemas.d.ts +56 -0
- package/dist/ai-schemas.d.ts.map +1 -0
- package/dist/ai-schemas.js +53 -0
- package/dist/ai-schemas.js.map +1 -0
- package/dist/ai.d.ts +16 -242
- package/dist/ai.d.ts.map +1 -1
- package/dist/ai.js +54 -837
- package/dist/ai.js.map +1 -1
- package/dist/batch/anthropic.d.ts +6 -4
- package/dist/batch/anthropic.d.ts.map +1 -1
- package/dist/batch/anthropic.js +83 -145
- package/dist/batch/anthropic.js.map +1 -1
- package/dist/batch/bedrock.d.ts +8 -30
- package/dist/batch/bedrock.d.ts.map +1 -1
- package/dist/batch/bedrock.js +155 -338
- package/dist/batch/bedrock.js.map +1 -1
- package/dist/batch/cloudflare.d.ts +8 -20
- package/dist/batch/cloudflare.d.ts.map +1 -1
- package/dist/batch/cloudflare.js +68 -189
- package/dist/batch/cloudflare.js.map +1 -1
- package/dist/batch/google.d.ts +6 -20
- package/dist/batch/google.d.ts.map +1 -1
- package/dist/batch/google.js +70 -238
- package/dist/batch/google.js.map +1 -1
- package/dist/batch/index.d.ts +4 -1
- package/dist/batch/index.d.ts.map +1 -1
- package/dist/batch/index.js +4 -1
- package/dist/batch/index.js.map +1 -1
- package/dist/batch/memory.d.ts +1 -1
- package/dist/batch/memory.d.ts.map +1 -1
- package/dist/batch/memory.js +14 -10
- package/dist/batch/memory.js.map +1 -1
- package/dist/batch/openai.d.ts +11 -14
- package/dist/batch/openai.d.ts.map +1 -1
- package/dist/batch/openai.js +52 -156
- package/dist/batch/openai.js.map +1 -1
- package/dist/batch/provider.d.ts +111 -0
- package/dist/batch/provider.d.ts.map +1 -0
- package/dist/batch/provider.js +233 -0
- package/dist/batch/provider.js.map +1 -0
- package/dist/batch-map.d.ts.map +1 -1
- package/dist/batch-map.js +23 -17
- package/dist/batch-map.js.map +1 -1
- package/dist/batch-queue.d.ts +65 -0
- package/dist/batch-queue.d.ts.map +1 -1
- package/dist/batch-queue.js +169 -14
- package/dist/batch-queue.js.map +1 -1
- package/dist/budget.d.ts +272 -0
- package/dist/budget.d.ts.map +1 -0
- package/dist/budget.js +513 -0
- package/dist/budget.js.map +1 -0
- package/dist/cache.d.ts +295 -0
- package/dist/cache.d.ts.map +1 -0
- package/dist/cache.js +433 -0
- package/dist/cache.js.map +1 -0
- package/dist/context.d.ts +42 -8
- package/dist/context.d.ts.map +1 -1
- package/dist/context.js +64 -62
- package/dist/context.js.map +1 -1
- package/dist/digital-objects-registry.d.ts +229 -0
- package/dist/digital-objects-registry.d.ts.map +1 -0
- package/dist/digital-objects-registry.js +617 -0
- package/dist/digital-objects-registry.js.map +1 -0
- package/dist/embeddings.d.ts +2 -2
- package/dist/embeddings.d.ts.map +1 -1
- package/dist/errors.d.ts +22 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +35 -0
- package/dist/errors.js.map +1 -0
- package/dist/eval/runner.d.ts +10 -1
- package/dist/eval/runner.d.ts.map +1 -1
- package/dist/eval/runner.js +41 -35
- package/dist/eval/runner.js.map +1 -1
- package/dist/eval-log/in-memory.d.ts +34 -0
- package/dist/eval-log/in-memory.d.ts.map +1 -0
- package/dist/eval-log/in-memory.js +84 -0
- package/dist/eval-log/in-memory.js.map +1 -0
- package/dist/eval-log/index.d.ts +29 -0
- package/dist/eval-log/index.d.ts.map +1 -0
- package/dist/eval-log/index.js +39 -0
- package/dist/eval-log/index.js.map +1 -0
- package/dist/eval-log/types.d.ts +101 -0
- package/dist/eval-log/types.d.ts.map +1 -0
- package/dist/eval-log/types.js +16 -0
- package/dist/eval-log/types.js.map +1 -0
- package/dist/function-registry.d.ts +116 -0
- package/dist/function-registry.d.ts.map +1 -0
- package/dist/function-registry.js +546 -0
- package/dist/function-registry.js.map +1 -0
- package/dist/generate.d.ts +9 -3
- package/dist/generate.d.ts.map +1 -1
- package/dist/generate.js +18 -22
- package/dist/generate.js.map +1 -1
- package/dist/index.d.ts +35 -20
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +89 -42
- package/dist/index.js.map +1 -1
- package/dist/logger.d.ts +118 -0
- package/dist/logger.d.ts.map +1 -0
- package/dist/logger.js +187 -0
- package/dist/logger.js.map +1 -0
- package/dist/middleware/budget.d.ts +84 -0
- package/dist/middleware/budget.d.ts.map +1 -0
- package/dist/middleware/budget.js +110 -0
- package/dist/middleware/budget.js.map +1 -0
- package/dist/middleware/cache.d.ts +103 -0
- package/dist/middleware/cache.d.ts.map +1 -0
- package/dist/middleware/cache.js +228 -0
- package/dist/middleware/cache.js.map +1 -0
- package/dist/middleware/embed-cache.d.ts +99 -0
- package/dist/middleware/embed-cache.d.ts.map +1 -0
- package/dist/middleware/embed-cache.js +128 -0
- package/dist/middleware/embed-cache.js.map +1 -0
- package/dist/middleware/index.d.ts +11 -0
- package/dist/middleware/index.d.ts.map +1 -0
- package/dist/middleware/index.js +11 -0
- package/dist/middleware/index.js.map +1 -0
- package/dist/middleware/trace.d.ts +103 -0
- package/dist/middleware/trace.d.ts.map +1 -0
- package/dist/middleware/trace.js +176 -0
- package/dist/middleware/trace.js.map +1 -0
- package/dist/primitives.d.ts +120 -1
- package/dist/primitives.d.ts.map +1 -1
- package/dist/primitives.js +398 -26
- package/dist/primitives.js.map +1 -1
- package/dist/retry.d.ts +368 -0
- package/dist/retry.d.ts.map +1 -0
- package/dist/retry.js +646 -0
- package/dist/retry.js.map +1 -0
- package/dist/schema.d.ts.map +1 -1
- package/dist/schema.js +2 -10
- package/dist/schema.js.map +1 -1
- package/dist/telemetry.d.ts +128 -0
- package/dist/telemetry.d.ts.map +1 -0
- package/dist/telemetry.js +285 -0
- package/dist/telemetry.js.map +1 -0
- package/dist/template.d.ts.map +1 -1
- package/dist/template.js +6 -1
- package/dist/template.js.map +1 -1
- package/dist/tool-orchestration.d.ts +453 -0
- package/dist/tool-orchestration.d.ts.map +1 -0
- package/dist/tool-orchestration.js +763 -0
- package/dist/tool-orchestration.js.map +1 -0
- package/dist/type-guards.d.ts +28 -0
- package/dist/type-guards.d.ts.map +1 -0
- package/dist/type-guards.js +29 -0
- package/dist/type-guards.js.map +1 -0
- package/dist/types.d.ts +135 -17
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +36 -1
- package/dist/types.js.map +1 -1
- package/dist/wrap-for-v3.d.ts +80 -0
- package/dist/wrap-for-v3.d.ts.map +1 -0
- package/dist/wrap-for-v3.js +89 -0
- package/dist/wrap-for-v3.js.map +1 -0
- package/examples/00-quickstart.ts +232 -0
- package/examples/01-rag-chatbot.ts +212 -0
- package/examples/02-multi-agent-research.ts +290 -0
- package/examples/03-email-classification.ts +379 -0
- package/examples/04-content-moderation.ts +400 -0
- package/examples/05-document-extraction.ts +455 -0
- package/examples/06-streaming-chat-nextjs.ts +437 -0
- package/examples/07-cloudflare-worker.ts +483 -0
- package/examples/08-batch-processing.ts +491 -0
- package/examples/09-budget-constrained.ts +527 -0
- package/examples/10-tool-orchestration.ts +565 -0
- package/examples/11-retry-resilience.ts +403 -0
- package/examples/12-caching-strategies.ts +422 -0
- package/examples/README.md +145 -0
- package/package.json +10 -6
- package/src/ai-promise.ts +528 -99
- package/src/ai-schemas.ts +122 -0
- package/src/ai.ts +69 -1153
- package/src/batch/anthropic.ts +96 -161
- package/src/batch/bedrock.ts +203 -454
- package/src/batch/cloudflare.ts +99 -282
- package/src/batch/google.ts +91 -297
- package/src/batch/index.ts +4 -1
- package/src/batch/memory.ts +15 -10
- package/src/batch/openai.ts +65 -193
- package/src/batch/provider.ts +336 -0
- package/src/batch-map.ts +29 -24
- package/src/batch-queue.ts +200 -11
- package/src/budget.ts +740 -0
- package/src/cache.ts +681 -0
- package/src/context.ts +122 -76
- package/src/digital-objects-registry.ts +750 -0
- package/src/errors.ts +37 -0
- package/src/eval/runner.ts +63 -38
- package/src/eval-log/in-memory.ts +90 -0
- package/src/eval-log/index.ts +46 -0
- package/src/eval-log/types.ts +110 -0
- package/src/function-registry.ts +671 -0
- package/src/generate.ts +33 -33
- package/src/index.ts +325 -49
- package/src/logger.ts +232 -0
- package/src/middleware/budget.ts +171 -0
- package/src/middleware/cache.ts +299 -0
- package/src/middleware/embed-cache.ts +195 -0
- package/src/middleware/index.ts +23 -0
- package/src/middleware/trace.ts +248 -0
- package/src/primitives.ts +589 -62
- package/src/retry.ts +902 -0
- package/src/schema.ts +8 -17
- package/src/telemetry.ts +403 -0
- package/src/template.ts +8 -4
- package/src/tool-orchestration.ts +1173 -0
- package/src/type-guards.ts +31 -0
- package/src/types.ts +164 -25
- package/src/wrap-for-v3.ts +105 -0
- package/test/ai-promise.test.ts +1080 -0
- package/test/ai-proxy.test.ts +1 -1
- package/test/backward-compat.test.ts +147 -0
- package/test/batch-autosubmit-errors.test.ts +610 -0
- package/test/batch-blog-posts.test.ts +87 -129
- package/test/budget-tracking.test.ts +800 -0
- package/test/cache.test.ts +712 -0
- package/test/context-isolation.test.ts +687 -0
- package/test/core-functions.test.ts +183 -579
- package/test/decide.test.ts +154 -322
- package/test/define.test.ts +211 -8
- package/test/digital-objects-registry.test.ts +760 -0
- package/test/embedding-cache-middleware.test.ts +140 -0
- package/test/evals/deterministic.eval.test.ts +376 -0
- package/test/generate-core.test.ts +140 -229
- package/test/implicit-batch.test.ts +22 -65
- package/test/json-parse-error-handling.test.ts +463 -0
- package/test/retry-policy-integration.test.ts +117 -0
- package/test/retry.test.ts +1016 -0
- package/test/schema.test.ts +55 -19
- package/test/streaming.test.ts +316 -0
- package/test/template.test.ts +1164 -0
- package/test/tool-orchestration.test.ts +1040 -0
- package/test/wrap-for-v3.test.ts +612 -0
- package/vitest.config.js +6 -0
- package/vitest.config.ts +20 -0
- package/dist/rpc/auth.d.ts +0 -69
- package/dist/rpc/auth.d.ts.map +0 -1
- package/dist/rpc/auth.js +0 -136
- package/dist/rpc/auth.js.map +0 -1
- package/dist/rpc/client.d.ts +0 -62
- package/dist/rpc/client.d.ts.map +0 -1
- package/dist/rpc/client.js +0 -103
- package/dist/rpc/client.js.map +0 -1
- package/dist/rpc/deferred.d.ts +0 -60
- package/dist/rpc/deferred.d.ts.map +0 -1
- package/dist/rpc/deferred.js +0 -96
- package/dist/rpc/deferred.js.map +0 -1
- package/dist/rpc/index.d.ts +0 -22
- package/dist/rpc/index.d.ts.map +0 -1
- package/dist/rpc/index.js +0 -38
- package/dist/rpc/index.js.map +0 -1
- package/dist/rpc/local.d.ts +0 -42
- package/dist/rpc/local.d.ts.map +0 -1
- package/dist/rpc/local.js +0 -50
- package/dist/rpc/local.js.map +0 -1
- package/dist/rpc/server.d.ts +0 -165
- package/dist/rpc/server.d.ts.map +0 -1
- package/dist/rpc/server.js +0 -405
- package/dist/rpc/server.js.map +0 -1
- package/dist/rpc/session.d.ts +0 -32
- package/dist/rpc/session.d.ts.map +0 -1
- package/dist/rpc/session.js +0 -43
- package/dist/rpc/session.js.map +0 -1
- package/dist/rpc/transport.d.ts +0 -306
- package/dist/rpc/transport.d.ts.map +0 -1
- package/dist/rpc/transport.js +0 -731
- package/dist/rpc/transport.js.map +0 -1
- package/src/batch/anthropic.js +0 -256
- package/src/batch/bedrock.js +0 -584
- package/src/batch/cloudflare.js +0 -287
- package/src/batch/google.js +0 -359
- package/src/batch/index.js +0 -30
- package/src/batch/memory.js +0 -187
- package/src/batch/openai.js +0 -402
- package/src/eval/index.js +0 -7
- package/src/eval/models.js +0 -119
- package/src/eval/runner.js +0 -147
- package/test/schema.test.js +0 -96
package/dist/retry.d.ts
ADDED
|
@@ -0,0 +1,368 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Retry and fallback patterns for AI function calls
|
|
3
|
+
*
|
|
4
|
+
* Provides:
|
|
5
|
+
* - Exponential backoff with configurable base delay and multiplier
|
|
6
|
+
* - Jitter to prevent thundering herd (equal, full, decorrelated strategies)
|
|
7
|
+
* - Circuit breaker for fail-fast behavior after repeated failures
|
|
8
|
+
* - Fallback chains for model failover (sonnet -> opus -> gpt-4o)
|
|
9
|
+
* - Error classification for intelligent retry decisions
|
|
10
|
+
* - Partial retry for batch operations
|
|
11
|
+
*
|
|
12
|
+
* Per-model policy data (which models retry how, who falls back to whom,
|
|
13
|
+
* which batch tiers each model supports) lives in `language-models`'s
|
|
14
|
+
* `policyFor()`. The classes in this file are the *machinery* that reads
|
|
15
|
+
* that policy. See `RetryPolicy.forModel`, `CircuitBreaker.forModel`,
|
|
16
|
+
* `FallbackChain.forModel`.
|
|
17
|
+
*
|
|
18
|
+
* @packageDocumentation
|
|
19
|
+
*/
|
|
20
|
+
import { type ModelPolicy } from 'language-models';
|
|
21
|
+
/**
|
|
22
|
+
* Error categories for retry decision making
|
|
23
|
+
*/
|
|
24
|
+
export declare enum ErrorCategory {
|
|
25
|
+
/** Network connectivity issues (retryable) */
|
|
26
|
+
Network = "network",
|
|
27
|
+
/** Rate limiting / quota exceeded (retryable with backoff) */
|
|
28
|
+
RateLimit = "rate_limit",
|
|
29
|
+
/** Invalid input / bad request (not retryable) */
|
|
30
|
+
InvalidInput = "invalid_input",
|
|
31
|
+
/** Authentication / authorization errors (not retryable) */
|
|
32
|
+
Authentication = "authentication",
|
|
33
|
+
/** Server errors (retryable) */
|
|
34
|
+
Server = "server",
|
|
35
|
+
/** Context length exceeded (not retryable without modification) */
|
|
36
|
+
ContextLength = "context_length",
|
|
37
|
+
/** Unknown error type */
|
|
38
|
+
Unknown = "unknown"
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Base class for retryable errors
|
|
42
|
+
*/
|
|
43
|
+
export declare class RetryableError extends Error {
|
|
44
|
+
readonly retryable = true;
|
|
45
|
+
readonly category: ErrorCategory;
|
|
46
|
+
constructor(message: string, category?: ErrorCategory);
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Base class for non-retryable errors
|
|
50
|
+
*/
|
|
51
|
+
export declare class NonRetryableError extends Error {
|
|
52
|
+
readonly retryable = false;
|
|
53
|
+
readonly category: ErrorCategory;
|
|
54
|
+
constructor(message: string, category?: ErrorCategory);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Network-related errors (connection issues, timeouts)
|
|
58
|
+
*/
|
|
59
|
+
export declare class NetworkError extends RetryableError {
|
|
60
|
+
constructor(message: string);
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Rate limit errors with optional retry-after
|
|
64
|
+
*/
|
|
65
|
+
export declare class RateLimitError extends RetryableError {
|
|
66
|
+
readonly retryAfter?: number;
|
|
67
|
+
constructor(message: string, options?: {
|
|
68
|
+
retryAfter?: number;
|
|
69
|
+
});
|
|
70
|
+
/**
|
|
71
|
+
* Create RateLimitError from HTTP response
|
|
72
|
+
*/
|
|
73
|
+
static fromResponse(response: {
|
|
74
|
+
status: number;
|
|
75
|
+
headers?: Record<string, string>;
|
|
76
|
+
}): RateLimitError;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Error thrown when circuit breaker is open
|
|
80
|
+
*/
|
|
81
|
+
export declare class CircuitOpenError extends Error {
|
|
82
|
+
readonly retryable = false;
|
|
83
|
+
constructor(message?: string);
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Classify an error into a category for retry decisions
|
|
87
|
+
*/
|
|
88
|
+
export declare function classifyError(error: unknown): ErrorCategory;
|
|
89
|
+
/**
|
|
90
|
+
* Jitter strategy for backoff calculation
|
|
91
|
+
*/
|
|
92
|
+
export type JitterStrategy = 'equal' | 'full' | 'decorrelated';
|
|
93
|
+
/**
|
|
94
|
+
* Options for backoff calculation
|
|
95
|
+
*/
|
|
96
|
+
export interface BackoffOptions {
|
|
97
|
+
/** Base delay in milliseconds (default: 1000) */
|
|
98
|
+
baseDelay?: number;
|
|
99
|
+
/** Maximum delay cap in milliseconds (default: 30000) */
|
|
100
|
+
maxDelay?: number;
|
|
101
|
+
/** Exponential multiplier (default: 2) */
|
|
102
|
+
multiplier?: number;
|
|
103
|
+
/** Jitter factor 0-1 for equal jitter (default: 0) */
|
|
104
|
+
jitter?: number;
|
|
105
|
+
/** Jitter strategy (default: 'equal') */
|
|
106
|
+
jitterStrategy?: JitterStrategy;
|
|
107
|
+
/** Previous delay for decorrelated jitter */
|
|
108
|
+
previousDelay?: number;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Calculate backoff delay with exponential increase and optional jitter
|
|
112
|
+
*
|
|
113
|
+
* @param attempt - Current attempt number (0-indexed)
|
|
114
|
+
* @param options - Backoff configuration
|
|
115
|
+
* @returns Delay in milliseconds
|
|
116
|
+
*/
|
|
117
|
+
export declare function calculateBackoff(attempt: number, options?: BackoffOptions): number;
|
|
118
|
+
/**
|
|
119
|
+
* Options for retry policy
|
|
120
|
+
*/
|
|
121
|
+
export interface RetryOptions {
|
|
122
|
+
/** Maximum number of retries (default: 3) */
|
|
123
|
+
maxRetries?: number;
|
|
124
|
+
/** Base delay in milliseconds (default: 1000) */
|
|
125
|
+
baseDelay?: number;
|
|
126
|
+
/** Maximum delay cap in milliseconds (default: 30000) */
|
|
127
|
+
maxDelay?: number;
|
|
128
|
+
/** Exponential multiplier (default: 2) */
|
|
129
|
+
multiplier?: number;
|
|
130
|
+
/** Jitter factor 0-1 (default: 0) */
|
|
131
|
+
jitter?: number;
|
|
132
|
+
/** Jitter strategy (default: 'equal') */
|
|
133
|
+
jitterStrategy?: JitterStrategy;
|
|
134
|
+
/** Respect retry-after headers from rate limit errors (default: true) */
|
|
135
|
+
respectRetryAfter?: boolean;
|
|
136
|
+
/** Custom function to determine if error is retryable */
|
|
137
|
+
shouldRetry?: (error: unknown) => boolean;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Info passed to operations during retry
|
|
141
|
+
*/
|
|
142
|
+
export interface RetryInfo {
|
|
143
|
+
attempt: number;
|
|
144
|
+
maxRetries: number;
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Result of a batch item operation
|
|
148
|
+
*/
|
|
149
|
+
export interface BatchItemResult<T, R> {
|
|
150
|
+
success: boolean;
|
|
151
|
+
item: T;
|
|
152
|
+
result?: R;
|
|
153
|
+
error?: Error;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Retry policy for executing operations with exponential backoff
|
|
157
|
+
*
|
|
158
|
+
* @deprecated Phase C Week 3 — `RetryPolicy` has 1 real production caller
|
|
159
|
+
* (audited 2026-05-06; see `bd show aip-ibid`):
|
|
160
|
+
* `ai-database/src/cascade-orchestrator.ts:1235` (loose coupling — dynamic
|
|
161
|
+
* import + graceful try/catch fallback when ai-functions not available).
|
|
162
|
+
* AI SDK 6's `customProvider({ retryPolicy })` and `wrapLanguageModel(model,
|
|
163
|
+
* retryMiddleware)` cover the same surface. Migration tracked in aip-ibid;
|
|
164
|
+
* the one callsite can move on a separate commit. Will be removed in the
|
|
165
|
+
* Phase C semver bump.
|
|
166
|
+
*/
|
|
167
|
+
export declare class RetryPolicy {
|
|
168
|
+
private readonly options;
|
|
169
|
+
constructor(options?: RetryOptions);
|
|
170
|
+
/**
|
|
171
|
+
* Build a RetryPolicy from a model's `ModelPolicy` (loaded via
|
|
172
|
+
* `language-models`). Per-call `overrides` win over policy data.
|
|
173
|
+
*
|
|
174
|
+
* @example
|
|
175
|
+
* ```ts
|
|
176
|
+
* const policy = RetryPolicy.forModel('sonnet')
|
|
177
|
+
* // Uses retry settings derived for anthropic/claude-sonnet-4.5
|
|
178
|
+
* ```
|
|
179
|
+
*/
|
|
180
|
+
static forModel(alias: string, overrides?: RetryOptions): RetryPolicy;
|
|
181
|
+
/**
|
|
182
|
+
* Build a RetryPolicy directly from a `ModelPolicy`. Useful when the policy
|
|
183
|
+
* is already in hand (e.g. from a request context).
|
|
184
|
+
*/
|
|
185
|
+
static fromPolicy(policy: ModelPolicy, overrides?: RetryOptions): RetryPolicy;
|
|
186
|
+
/**
|
|
187
|
+
* Execute an operation with retry logic
|
|
188
|
+
*/
|
|
189
|
+
execute<T>(operation: (info: RetryInfo) => Promise<T>): Promise<T>;
|
|
190
|
+
/**
|
|
191
|
+
* Execute a batch operation with partial retry for failed items
|
|
192
|
+
*/
|
|
193
|
+
executeBatch<T, R>(items: T[], batchProcessor: (items: T[]) => Promise<BatchItemResult<T, R>[]>): Promise<BatchItemResult<T, R>[]>;
|
|
194
|
+
private isRetryable;
|
|
195
|
+
private sleep;
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Circuit breaker state
|
|
199
|
+
*/
|
|
200
|
+
export type CircuitState = 'closed' | 'open' | 'half-open';
|
|
201
|
+
/**
|
|
202
|
+
* Options for circuit breaker
|
|
203
|
+
*/
|
|
204
|
+
export interface CircuitBreakerOptions {
|
|
205
|
+
/** Number of failures before opening circuit (default: 5) */
|
|
206
|
+
failureThreshold?: number;
|
|
207
|
+
/** Time in ms before transitioning to half-open (default: 30000) */
|
|
208
|
+
resetTimeout?: number;
|
|
209
|
+
/** Number of successful calls to close circuit (default: 1) */
|
|
210
|
+
successThreshold?: number;
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Circuit breaker metrics
|
|
214
|
+
*/
|
|
215
|
+
export interface CircuitBreakerMetrics {
|
|
216
|
+
state: CircuitState;
|
|
217
|
+
failureCount: number;
|
|
218
|
+
successCount: number;
|
|
219
|
+
lastFailure: Date | null;
|
|
220
|
+
lastSuccess: Date | null;
|
|
221
|
+
totalFailures: number;
|
|
222
|
+
totalSuccesses: number;
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* Circuit breaker for fail-fast behavior
|
|
226
|
+
*
|
|
227
|
+
* States:
|
|
228
|
+
* - CLOSED: Normal operation, failures tracked
|
|
229
|
+
* - OPEN: Fail fast, reject all requests
|
|
230
|
+
* - HALF-OPEN: Allow single test request
|
|
231
|
+
*
|
|
232
|
+
* @deprecated Phase C Week 3 — `CircuitBreaker` has zero real callers in
|
|
233
|
+
* primitives.org.ai (audited 2026-05-06; only comment-only references in
|
|
234
|
+
* `language-models/src/index.ts`; see `bd show aip-ibid`). AI SDK 6's
|
|
235
|
+
* `wrapLanguageModel(model, circuitMiddleware)` replacement is the going-
|
|
236
|
+
* forward primitive. Will be removed in the Phase C semver bump.
|
|
237
|
+
*/
|
|
238
|
+
export declare class CircuitBreaker {
|
|
239
|
+
private _state;
|
|
240
|
+
private _failureCount;
|
|
241
|
+
private _successCount;
|
|
242
|
+
private _lastFailure;
|
|
243
|
+
private _lastSuccess;
|
|
244
|
+
private _totalFailures;
|
|
245
|
+
private _totalSuccesses;
|
|
246
|
+
private _openedAt;
|
|
247
|
+
private readonly options;
|
|
248
|
+
constructor(options?: CircuitBreakerOptions);
|
|
249
|
+
/**
|
|
250
|
+
* Build a CircuitBreaker for a specific model, using its `ModelPolicy`.
|
|
251
|
+
* Per-call overrides win over policy data.
|
|
252
|
+
*/
|
|
253
|
+
static forModel(alias: string, overrides?: CircuitBreakerOptions): CircuitBreaker;
|
|
254
|
+
/**
|
|
255
|
+
* Current circuit state
|
|
256
|
+
*/
|
|
257
|
+
get state(): CircuitState;
|
|
258
|
+
/**
|
|
259
|
+
* Current failure count
|
|
260
|
+
*/
|
|
261
|
+
get failureCount(): number;
|
|
262
|
+
/**
|
|
263
|
+
* Execute an operation through the circuit breaker
|
|
264
|
+
*/
|
|
265
|
+
execute<T>(operation: () => Promise<T>): Promise<T>;
|
|
266
|
+
/**
|
|
267
|
+
* Record a successful operation
|
|
268
|
+
*/
|
|
269
|
+
private recordSuccess;
|
|
270
|
+
/**
|
|
271
|
+
* Record a failed operation
|
|
272
|
+
*/
|
|
273
|
+
private recordFailure;
|
|
274
|
+
/**
|
|
275
|
+
* Get circuit breaker metrics
|
|
276
|
+
*/
|
|
277
|
+
getMetrics(): CircuitBreakerMetrics;
|
|
278
|
+
/**
|
|
279
|
+
* Manually reset the circuit breaker
|
|
280
|
+
*/
|
|
281
|
+
reset(): void;
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* A model in the fallback chain
|
|
285
|
+
*/
|
|
286
|
+
export interface FallbackModel<T = unknown, P = unknown> {
|
|
287
|
+
name: string;
|
|
288
|
+
execute: (params?: P) => Promise<T>;
|
|
289
|
+
}
|
|
290
|
+
/**
|
|
291
|
+
* Options for fallback chain
|
|
292
|
+
*/
|
|
293
|
+
export interface FallbackOptions {
|
|
294
|
+
/** Custom function to determine if fallback should be attempted */
|
|
295
|
+
shouldFallback?: (error: unknown) => boolean;
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* Metrics from fallback chain execution
|
|
299
|
+
*/
|
|
300
|
+
export interface FallbackMetrics {
|
|
301
|
+
attempts: number;
|
|
302
|
+
successfulModel: string | null;
|
|
303
|
+
failedModels: string[];
|
|
304
|
+
totalDuration: number;
|
|
305
|
+
errors: Array<{
|
|
306
|
+
model: string;
|
|
307
|
+
error: Error;
|
|
308
|
+
}>;
|
|
309
|
+
}
|
|
310
|
+
/**
|
|
311
|
+
* Fallback chain for model failover
|
|
312
|
+
*
|
|
313
|
+
* Tries models in order until one succeeds:
|
|
314
|
+
* sonnet -> opus -> gpt-4o -> gemini
|
|
315
|
+
*
|
|
316
|
+
* @deprecated Phase C Week 3 — `FallbackChain` (LLM model failover) has
|
|
317
|
+
* zero real callers in primitives.org.ai (audited 2026-05-06; the
|
|
318
|
+
* `human-in-the-loop` package's `FallbackChain` is a different class for
|
|
319
|
+
* HITL fallback resolution, not LLM failover). AI SDK 4.3+ ships native
|
|
320
|
+
* `customProvider({ fallbackProvider })` which is the going-forward
|
|
321
|
+
* primitive. See `bd show aip-ibid`. Will be removed in the Phase C
|
|
322
|
+
* semver bump.
|
|
323
|
+
*/
|
|
324
|
+
export declare class FallbackChain<T = unknown, P = unknown> {
|
|
325
|
+
private readonly models;
|
|
326
|
+
private readonly options;
|
|
327
|
+
private lastMetrics;
|
|
328
|
+
constructor(models: FallbackModel<T, P>[], options?: FallbackOptions);
|
|
329
|
+
/**
|
|
330
|
+
* Build a FallbackChain from a model's `ModelPolicy`. The caller supplies
|
|
331
|
+
* an `executor` that takes a model id and returns a promise — the chain
|
|
332
|
+
* applies it to the primary model first, then to each fallback in order.
|
|
333
|
+
*
|
|
334
|
+
* @example
|
|
335
|
+
* ```ts
|
|
336
|
+
* const chain = FallbackChain.forModel('sonnet', (modelId, params) =>
|
|
337
|
+
* ai({ model: modelId, prompt: params!.prompt })
|
|
338
|
+
* )
|
|
339
|
+
* await chain.execute({ prompt: 'Hello' })
|
|
340
|
+
* ```
|
|
341
|
+
*/
|
|
342
|
+
static forModel<T = unknown, P = unknown>(alias: string, executor: (modelId: string, params?: P) => Promise<T>, options?: FallbackOptions): FallbackChain<T, P>;
|
|
343
|
+
/**
|
|
344
|
+
* Execute the fallback chain
|
|
345
|
+
*/
|
|
346
|
+
execute(params?: P): Promise<T>;
|
|
347
|
+
/**
|
|
348
|
+
* Get metrics from the last execution
|
|
349
|
+
*/
|
|
350
|
+
getMetrics(): FallbackMetrics;
|
|
351
|
+
}
|
|
352
|
+
/**
|
|
353
|
+
* Wrap an async function with retry logic
|
|
354
|
+
*
|
|
355
|
+
* @example
|
|
356
|
+
* ```ts
|
|
357
|
+
* const reliableFetch = withRetry(fetch, {
|
|
358
|
+
* maxRetries: 3,
|
|
359
|
+
* baseDelay: 1000,
|
|
360
|
+
* jitter: 0.2,
|
|
361
|
+
* })
|
|
362
|
+
*
|
|
363
|
+
* const response = await reliableFetch('https://api.example.com')
|
|
364
|
+
* ```
|
|
365
|
+
*/
|
|
366
|
+
export declare function withRetry<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, options?: RetryOptions): (...args: TArgs) => Promise<TResult>;
|
|
367
|
+
export type { RetryOptions as RetryPolicyOptions };
|
|
368
|
+
//# sourceMappingURL=retry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}
|