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.
Files changed (286) hide show
  1. package/.turbo/turbo-build.log +1 -4
  2. package/CHANGELOG.md +68 -1
  3. package/README.md +397 -157
  4. package/dist/ai-promise.d.ts +50 -3
  5. package/dist/ai-promise.d.ts.map +1 -1
  6. package/dist/ai-promise.js +410 -51
  7. package/dist/ai-promise.js.map +1 -1
  8. package/dist/ai-schemas.d.ts +56 -0
  9. package/dist/ai-schemas.d.ts.map +1 -0
  10. package/dist/ai-schemas.js +53 -0
  11. package/dist/ai-schemas.js.map +1 -0
  12. package/dist/ai.d.ts +16 -242
  13. package/dist/ai.d.ts.map +1 -1
  14. package/dist/ai.js +54 -837
  15. package/dist/ai.js.map +1 -1
  16. package/dist/batch/anthropic.d.ts +6 -4
  17. package/dist/batch/anthropic.d.ts.map +1 -1
  18. package/dist/batch/anthropic.js +83 -145
  19. package/dist/batch/anthropic.js.map +1 -1
  20. package/dist/batch/bedrock.d.ts +8 -30
  21. package/dist/batch/bedrock.d.ts.map +1 -1
  22. package/dist/batch/bedrock.js +155 -338
  23. package/dist/batch/bedrock.js.map +1 -1
  24. package/dist/batch/cloudflare.d.ts +8 -20
  25. package/dist/batch/cloudflare.d.ts.map +1 -1
  26. package/dist/batch/cloudflare.js +68 -189
  27. package/dist/batch/cloudflare.js.map +1 -1
  28. package/dist/batch/google.d.ts +6 -20
  29. package/dist/batch/google.d.ts.map +1 -1
  30. package/dist/batch/google.js +70 -238
  31. package/dist/batch/google.js.map +1 -1
  32. package/dist/batch/index.d.ts +4 -1
  33. package/dist/batch/index.d.ts.map +1 -1
  34. package/dist/batch/index.js +4 -1
  35. package/dist/batch/index.js.map +1 -1
  36. package/dist/batch/memory.d.ts +1 -1
  37. package/dist/batch/memory.d.ts.map +1 -1
  38. package/dist/batch/memory.js +14 -10
  39. package/dist/batch/memory.js.map +1 -1
  40. package/dist/batch/openai.d.ts +11 -14
  41. package/dist/batch/openai.d.ts.map +1 -1
  42. package/dist/batch/openai.js +52 -156
  43. package/dist/batch/openai.js.map +1 -1
  44. package/dist/batch/provider.d.ts +111 -0
  45. package/dist/batch/provider.d.ts.map +1 -0
  46. package/dist/batch/provider.js +233 -0
  47. package/dist/batch/provider.js.map +1 -0
  48. package/dist/batch-map.d.ts.map +1 -1
  49. package/dist/batch-map.js +23 -17
  50. package/dist/batch-map.js.map +1 -1
  51. package/dist/batch-queue.d.ts +65 -0
  52. package/dist/batch-queue.d.ts.map +1 -1
  53. package/dist/batch-queue.js +169 -14
  54. package/dist/batch-queue.js.map +1 -1
  55. package/dist/budget.d.ts +272 -0
  56. package/dist/budget.d.ts.map +1 -0
  57. package/dist/budget.js +513 -0
  58. package/dist/budget.js.map +1 -0
  59. package/dist/cache.d.ts +295 -0
  60. package/dist/cache.d.ts.map +1 -0
  61. package/dist/cache.js +433 -0
  62. package/dist/cache.js.map +1 -0
  63. package/dist/context.d.ts +42 -8
  64. package/dist/context.d.ts.map +1 -1
  65. package/dist/context.js +64 -62
  66. package/dist/context.js.map +1 -1
  67. package/dist/digital-objects-registry.d.ts +229 -0
  68. package/dist/digital-objects-registry.d.ts.map +1 -0
  69. package/dist/digital-objects-registry.js +617 -0
  70. package/dist/digital-objects-registry.js.map +1 -0
  71. package/dist/embeddings.d.ts +2 -2
  72. package/dist/embeddings.d.ts.map +1 -1
  73. package/dist/errors.d.ts +22 -0
  74. package/dist/errors.d.ts.map +1 -0
  75. package/dist/errors.js +35 -0
  76. package/dist/errors.js.map +1 -0
  77. package/dist/eval/runner.d.ts +10 -1
  78. package/dist/eval/runner.d.ts.map +1 -1
  79. package/dist/eval/runner.js +41 -35
  80. package/dist/eval/runner.js.map +1 -1
  81. package/dist/eval-log/in-memory.d.ts +34 -0
  82. package/dist/eval-log/in-memory.d.ts.map +1 -0
  83. package/dist/eval-log/in-memory.js +84 -0
  84. package/dist/eval-log/in-memory.js.map +1 -0
  85. package/dist/eval-log/index.d.ts +29 -0
  86. package/dist/eval-log/index.d.ts.map +1 -0
  87. package/dist/eval-log/index.js +39 -0
  88. package/dist/eval-log/index.js.map +1 -0
  89. package/dist/eval-log/types.d.ts +101 -0
  90. package/dist/eval-log/types.d.ts.map +1 -0
  91. package/dist/eval-log/types.js +16 -0
  92. package/dist/eval-log/types.js.map +1 -0
  93. package/dist/function-registry.d.ts +116 -0
  94. package/dist/function-registry.d.ts.map +1 -0
  95. package/dist/function-registry.js +546 -0
  96. package/dist/function-registry.js.map +1 -0
  97. package/dist/generate.d.ts +9 -3
  98. package/dist/generate.d.ts.map +1 -1
  99. package/dist/generate.js +18 -22
  100. package/dist/generate.js.map +1 -1
  101. package/dist/index.d.ts +35 -20
  102. package/dist/index.d.ts.map +1 -1
  103. package/dist/index.js +89 -42
  104. package/dist/index.js.map +1 -1
  105. package/dist/logger.d.ts +118 -0
  106. package/dist/logger.d.ts.map +1 -0
  107. package/dist/logger.js +187 -0
  108. package/dist/logger.js.map +1 -0
  109. package/dist/middleware/budget.d.ts +84 -0
  110. package/dist/middleware/budget.d.ts.map +1 -0
  111. package/dist/middleware/budget.js +110 -0
  112. package/dist/middleware/budget.js.map +1 -0
  113. package/dist/middleware/cache.d.ts +103 -0
  114. package/dist/middleware/cache.d.ts.map +1 -0
  115. package/dist/middleware/cache.js +228 -0
  116. package/dist/middleware/cache.js.map +1 -0
  117. package/dist/middleware/embed-cache.d.ts +99 -0
  118. package/dist/middleware/embed-cache.d.ts.map +1 -0
  119. package/dist/middleware/embed-cache.js +128 -0
  120. package/dist/middleware/embed-cache.js.map +1 -0
  121. package/dist/middleware/index.d.ts +11 -0
  122. package/dist/middleware/index.d.ts.map +1 -0
  123. package/dist/middleware/index.js +11 -0
  124. package/dist/middleware/index.js.map +1 -0
  125. package/dist/middleware/trace.d.ts +103 -0
  126. package/dist/middleware/trace.d.ts.map +1 -0
  127. package/dist/middleware/trace.js +176 -0
  128. package/dist/middleware/trace.js.map +1 -0
  129. package/dist/primitives.d.ts +120 -1
  130. package/dist/primitives.d.ts.map +1 -1
  131. package/dist/primitives.js +398 -26
  132. package/dist/primitives.js.map +1 -1
  133. package/dist/retry.d.ts +368 -0
  134. package/dist/retry.d.ts.map +1 -0
  135. package/dist/retry.js +646 -0
  136. package/dist/retry.js.map +1 -0
  137. package/dist/schema.d.ts.map +1 -1
  138. package/dist/schema.js +2 -10
  139. package/dist/schema.js.map +1 -1
  140. package/dist/telemetry.d.ts +128 -0
  141. package/dist/telemetry.d.ts.map +1 -0
  142. package/dist/telemetry.js +285 -0
  143. package/dist/telemetry.js.map +1 -0
  144. package/dist/template.d.ts.map +1 -1
  145. package/dist/template.js +6 -1
  146. package/dist/template.js.map +1 -1
  147. package/dist/tool-orchestration.d.ts +453 -0
  148. package/dist/tool-orchestration.d.ts.map +1 -0
  149. package/dist/tool-orchestration.js +763 -0
  150. package/dist/tool-orchestration.js.map +1 -0
  151. package/dist/type-guards.d.ts +28 -0
  152. package/dist/type-guards.d.ts.map +1 -0
  153. package/dist/type-guards.js +29 -0
  154. package/dist/type-guards.js.map +1 -0
  155. package/dist/types.d.ts +135 -17
  156. package/dist/types.d.ts.map +1 -1
  157. package/dist/types.js +36 -1
  158. package/dist/types.js.map +1 -1
  159. package/dist/wrap-for-v3.d.ts +80 -0
  160. package/dist/wrap-for-v3.d.ts.map +1 -0
  161. package/dist/wrap-for-v3.js +89 -0
  162. package/dist/wrap-for-v3.js.map +1 -0
  163. package/examples/00-quickstart.ts +232 -0
  164. package/examples/01-rag-chatbot.ts +212 -0
  165. package/examples/02-multi-agent-research.ts +290 -0
  166. package/examples/03-email-classification.ts +379 -0
  167. package/examples/04-content-moderation.ts +400 -0
  168. package/examples/05-document-extraction.ts +455 -0
  169. package/examples/06-streaming-chat-nextjs.ts +437 -0
  170. package/examples/07-cloudflare-worker.ts +483 -0
  171. package/examples/08-batch-processing.ts +491 -0
  172. package/examples/09-budget-constrained.ts +527 -0
  173. package/examples/10-tool-orchestration.ts +565 -0
  174. package/examples/11-retry-resilience.ts +403 -0
  175. package/examples/12-caching-strategies.ts +422 -0
  176. package/examples/README.md +145 -0
  177. package/package.json +10 -6
  178. package/src/ai-promise.ts +528 -99
  179. package/src/ai-schemas.ts +122 -0
  180. package/src/ai.ts +69 -1153
  181. package/src/batch/anthropic.ts +96 -161
  182. package/src/batch/bedrock.ts +203 -454
  183. package/src/batch/cloudflare.ts +99 -282
  184. package/src/batch/google.ts +91 -297
  185. package/src/batch/index.ts +4 -1
  186. package/src/batch/memory.ts +15 -10
  187. package/src/batch/openai.ts +65 -193
  188. package/src/batch/provider.ts +336 -0
  189. package/src/batch-map.ts +29 -24
  190. package/src/batch-queue.ts +200 -11
  191. package/src/budget.ts +740 -0
  192. package/src/cache.ts +681 -0
  193. package/src/context.ts +122 -76
  194. package/src/digital-objects-registry.ts +750 -0
  195. package/src/errors.ts +37 -0
  196. package/src/eval/runner.ts +63 -38
  197. package/src/eval-log/in-memory.ts +90 -0
  198. package/src/eval-log/index.ts +46 -0
  199. package/src/eval-log/types.ts +110 -0
  200. package/src/function-registry.ts +671 -0
  201. package/src/generate.ts +33 -33
  202. package/src/index.ts +325 -49
  203. package/src/logger.ts +232 -0
  204. package/src/middleware/budget.ts +171 -0
  205. package/src/middleware/cache.ts +299 -0
  206. package/src/middleware/embed-cache.ts +195 -0
  207. package/src/middleware/index.ts +23 -0
  208. package/src/middleware/trace.ts +248 -0
  209. package/src/primitives.ts +589 -62
  210. package/src/retry.ts +902 -0
  211. package/src/schema.ts +8 -17
  212. package/src/telemetry.ts +403 -0
  213. package/src/template.ts +8 -4
  214. package/src/tool-orchestration.ts +1173 -0
  215. package/src/type-guards.ts +31 -0
  216. package/src/types.ts +164 -25
  217. package/src/wrap-for-v3.ts +105 -0
  218. package/test/ai-promise.test.ts +1080 -0
  219. package/test/ai-proxy.test.ts +1 -1
  220. package/test/backward-compat.test.ts +147 -0
  221. package/test/batch-autosubmit-errors.test.ts +610 -0
  222. package/test/batch-blog-posts.test.ts +87 -129
  223. package/test/budget-tracking.test.ts +800 -0
  224. package/test/cache.test.ts +712 -0
  225. package/test/context-isolation.test.ts +687 -0
  226. package/test/core-functions.test.ts +183 -579
  227. package/test/decide.test.ts +154 -322
  228. package/test/define.test.ts +211 -8
  229. package/test/digital-objects-registry.test.ts +760 -0
  230. package/test/embedding-cache-middleware.test.ts +140 -0
  231. package/test/evals/deterministic.eval.test.ts +376 -0
  232. package/test/generate-core.test.ts +140 -229
  233. package/test/implicit-batch.test.ts +22 -65
  234. package/test/json-parse-error-handling.test.ts +463 -0
  235. package/test/retry-policy-integration.test.ts +117 -0
  236. package/test/retry.test.ts +1016 -0
  237. package/test/schema.test.ts +55 -19
  238. package/test/streaming.test.ts +316 -0
  239. package/test/template.test.ts +1164 -0
  240. package/test/tool-orchestration.test.ts +1040 -0
  241. package/test/wrap-for-v3.test.ts +612 -0
  242. package/vitest.config.js +6 -0
  243. package/vitest.config.ts +20 -0
  244. package/dist/rpc/auth.d.ts +0 -69
  245. package/dist/rpc/auth.d.ts.map +0 -1
  246. package/dist/rpc/auth.js +0 -136
  247. package/dist/rpc/auth.js.map +0 -1
  248. package/dist/rpc/client.d.ts +0 -62
  249. package/dist/rpc/client.d.ts.map +0 -1
  250. package/dist/rpc/client.js +0 -103
  251. package/dist/rpc/client.js.map +0 -1
  252. package/dist/rpc/deferred.d.ts +0 -60
  253. package/dist/rpc/deferred.d.ts.map +0 -1
  254. package/dist/rpc/deferred.js +0 -96
  255. package/dist/rpc/deferred.js.map +0 -1
  256. package/dist/rpc/index.d.ts +0 -22
  257. package/dist/rpc/index.d.ts.map +0 -1
  258. package/dist/rpc/index.js +0 -38
  259. package/dist/rpc/index.js.map +0 -1
  260. package/dist/rpc/local.d.ts +0 -42
  261. package/dist/rpc/local.d.ts.map +0 -1
  262. package/dist/rpc/local.js +0 -50
  263. package/dist/rpc/local.js.map +0 -1
  264. package/dist/rpc/server.d.ts +0 -165
  265. package/dist/rpc/server.d.ts.map +0 -1
  266. package/dist/rpc/server.js +0 -405
  267. package/dist/rpc/server.js.map +0 -1
  268. package/dist/rpc/session.d.ts +0 -32
  269. package/dist/rpc/session.d.ts.map +0 -1
  270. package/dist/rpc/session.js +0 -43
  271. package/dist/rpc/session.js.map +0 -1
  272. package/dist/rpc/transport.d.ts +0 -306
  273. package/dist/rpc/transport.d.ts.map +0 -1
  274. package/dist/rpc/transport.js +0 -731
  275. package/dist/rpc/transport.js.map +0 -1
  276. package/src/batch/anthropic.js +0 -256
  277. package/src/batch/bedrock.js +0 -584
  278. package/src/batch/cloudflare.js +0 -287
  279. package/src/batch/google.js +0 -359
  280. package/src/batch/index.js +0 -30
  281. package/src/batch/memory.js +0 -187
  282. package/src/batch/openai.js +0 -402
  283. package/src/eval/index.js +0 -7
  284. package/src/eval/models.js +0 -119
  285. package/src/eval/runner.js +0 -147
  286. package/test/schema.test.js +0 -96
@@ -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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"}