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
package/dist/cache.js ADDED
@@ -0,0 +1,433 @@
1
+ /**
2
+ * Caching layer for embeddings and generations
3
+ *
4
+ * Provides content-addressable caching for embeddings and parameter-aware
5
+ * caching for text/object generations with TTL support and LRU eviction.
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ // ============================================================================
10
+ // Memory Cache Implementation
11
+ // ============================================================================
12
+ /**
13
+ * In-memory cache implementation with TTL and LRU eviction support
14
+ *
15
+ * @deprecated Phase C Week 1 — `MemoryCache` has zero production callers in
16
+ * primitives.org.ai (audited 2026-05-06; see `bd show aip-ibid`). New code
17
+ * should use `cacheMiddleware` (for `wrapLanguageModel`) or
18
+ * `embeddingCacheMiddleware` (for `wrapEmbeddingModel`) instead — both
19
+ * compose with AI SDK 6's `wrapLanguageModel` / `wrapEmbeddingModel` and
20
+ * carry per-call telemetry (TraceEvent emission) and budget tracking when
21
+ * paired via `wrapForV3`. The `MemoryCache` class will be removed in the
22
+ * Phase C semver bump alongside `EmbeddingCache` and `GenerationCache`.
23
+ */
24
+ export class MemoryCache {
25
+ cache = new Map();
26
+ accessOrder = [];
27
+ options;
28
+ cleanupTimer;
29
+ constructor(options = {}) {
30
+ this.options = options;
31
+ // Start cleanup timer if interval is specified
32
+ if (options.cleanupInterval && options.cleanupInterval > 0) {
33
+ this.cleanupTimer = setInterval(() => {
34
+ this.cleanup();
35
+ }, options.cleanupInterval);
36
+ }
37
+ }
38
+ /**
39
+ * Get a value by key
40
+ */
41
+ async get(key) {
42
+ const entry = this.cache.get(key);
43
+ if (!entry) {
44
+ return undefined;
45
+ }
46
+ // Check if expired
47
+ if (entry.expiresAt && Date.now() > entry.expiresAt) {
48
+ this.cache.delete(key);
49
+ this.removeFromAccessOrder(key);
50
+ return undefined;
51
+ }
52
+ // Update access tracking
53
+ entry.lastAccessedAt = Date.now();
54
+ entry.accessCount++;
55
+ // Update access order for LRU
56
+ this.updateAccessOrder(key);
57
+ // Sliding expiration - refresh TTL on access
58
+ if (this.options.slidingExpiration && this.options.defaultTTL) {
59
+ entry.expiresAt = Date.now() + this.options.defaultTTL;
60
+ }
61
+ return entry.value;
62
+ }
63
+ /**
64
+ * Set a value by key
65
+ */
66
+ async set(key, value, options) {
67
+ const now = Date.now();
68
+ const ttl = options?.ttl ?? this.options.defaultTTL;
69
+ const entry = {
70
+ value,
71
+ createdAt: now,
72
+ lastAccessedAt: now,
73
+ accessCount: 0,
74
+ ...(ttl ? { expiresAt: now + ttl } : {}),
75
+ };
76
+ // Check if we need to evict (LRU)
77
+ if (this.options.maxSize && this.cache.size >= this.options.maxSize && !this.cache.has(key)) {
78
+ this.evictLRU();
79
+ }
80
+ this.cache.set(key, entry);
81
+ this.updateAccessOrder(key);
82
+ }
83
+ /**
84
+ * Check if a key exists
85
+ */
86
+ async has(key) {
87
+ const entry = this.cache.get(key);
88
+ if (!entry) {
89
+ return false;
90
+ }
91
+ // Check if expired
92
+ if (entry.expiresAt && Date.now() > entry.expiresAt) {
93
+ this.cache.delete(key);
94
+ this.removeFromAccessOrder(key);
95
+ return false;
96
+ }
97
+ return true;
98
+ }
99
+ /**
100
+ * Delete a key
101
+ */
102
+ async delete(key) {
103
+ this.cache.delete(key);
104
+ this.removeFromAccessOrder(key);
105
+ }
106
+ /**
107
+ * Clear all entries
108
+ */
109
+ async clear() {
110
+ this.cache.clear();
111
+ this.accessOrder = [];
112
+ }
113
+ /**
114
+ * Get the number of entries (excluding expired)
115
+ */
116
+ async size() {
117
+ await this.cleanup();
118
+ return this.cache.size;
119
+ }
120
+ /**
121
+ * Get all keys
122
+ */
123
+ async keys() {
124
+ await this.cleanup();
125
+ return Array.from(this.cache.keys());
126
+ }
127
+ /**
128
+ * Get full entry with metadata
129
+ */
130
+ async getEntry(key) {
131
+ const entry = this.cache.get(key);
132
+ if (!entry) {
133
+ return undefined;
134
+ }
135
+ // Check if expired
136
+ if (entry.expiresAt && Date.now() > entry.expiresAt) {
137
+ this.cache.delete(key);
138
+ this.removeFromAccessOrder(key);
139
+ return undefined;
140
+ }
141
+ return entry;
142
+ }
143
+ /**
144
+ * Dispose cleanup timer
145
+ */
146
+ dispose() {
147
+ if (this.cleanupTimer) {
148
+ clearInterval(this.cleanupTimer);
149
+ delete this.cleanupTimer;
150
+ }
151
+ }
152
+ /**
153
+ * Clean up expired entries
154
+ */
155
+ async cleanup() {
156
+ const now = Date.now();
157
+ const keysToDelete = [];
158
+ for (const [key, entry] of this.cache) {
159
+ if (entry.expiresAt && now > entry.expiresAt) {
160
+ keysToDelete.push(key);
161
+ }
162
+ }
163
+ for (const key of keysToDelete) {
164
+ this.cache.delete(key);
165
+ this.removeFromAccessOrder(key);
166
+ }
167
+ }
168
+ /**
169
+ * Evict the least recently used entry
170
+ */
171
+ evictLRU() {
172
+ if (this.accessOrder.length === 0)
173
+ return;
174
+ const lruKey = this.accessOrder[0];
175
+ if (lruKey) {
176
+ this.cache.delete(lruKey);
177
+ this.accessOrder.shift();
178
+ }
179
+ }
180
+ /**
181
+ * Update access order for LRU tracking
182
+ */
183
+ updateAccessOrder(key) {
184
+ this.removeFromAccessOrder(key);
185
+ this.accessOrder.push(key);
186
+ }
187
+ /**
188
+ * Remove a key from access order
189
+ */
190
+ removeFromAccessOrder(key) {
191
+ const index = this.accessOrder.indexOf(key);
192
+ if (index > -1) {
193
+ this.accessOrder.splice(index, 1);
194
+ }
195
+ }
196
+ }
197
+ // ============================================================================
198
+ // Hash / Key Generation
199
+ // ============================================================================
200
+ /**
201
+ * Generate a hash for cache keys
202
+ * Uses a fast, non-cryptographic hash suitable for cache keys
203
+ */
204
+ export function hashKey(input) {
205
+ const str = typeof input === 'string' ? input : stableStringify(input);
206
+ // Simple djb2 hash
207
+ let hash = 5381;
208
+ for (let i = 0; i < str.length; i++) {
209
+ hash = (hash << 5) + hash + str.charCodeAt(i);
210
+ hash = hash & hash; // Convert to 32bit integer
211
+ }
212
+ return (hash >>> 0).toString(36);
213
+ }
214
+ /**
215
+ * Stringify an object with sorted keys for stable hashing
216
+ */
217
+ function stableStringify(obj) {
218
+ if (obj === null || typeof obj !== 'object') {
219
+ return JSON.stringify(obj);
220
+ }
221
+ if (Array.isArray(obj)) {
222
+ return '[' + obj.map(stableStringify).join(',') + ']';
223
+ }
224
+ const keys = Object.keys(obj).sort();
225
+ const pairs = keys.map((key) => {
226
+ return JSON.stringify(key) + ':' + stableStringify(obj[key]);
227
+ });
228
+ return '{' + pairs.join(',') + '}';
229
+ }
230
+ /**
231
+ * Create a cache key for a specific type and parameters
232
+ */
233
+ export function createCacheKey(type, params) {
234
+ const hash = hashKey(params);
235
+ return `${type}:${hash}`;
236
+ }
237
+ /**
238
+ * Specialized cache for embedding vectors
239
+ *
240
+ * @deprecated Phase C Week 1 — `EmbeddingCache` has zero production callers
241
+ * in primitives.org.ai (audited 2026-05-06; see `bd show aip-ibid`). New
242
+ * code should use `embeddingCacheMiddleware` (for `wrapEmbeddingModel`) —
243
+ * it composes with AI SDK 6 directly and carries trace + budget telemetry
244
+ * when paired via `wrapForV3`. Note: `embeddingCacheMiddleware` keys on the
245
+ * whole batch, not per-text — callers wanting per-text caching should pass
246
+ * stable per-text batches. Will be removed in the Phase C semver bump.
247
+ */
248
+ export class EmbeddingCache {
249
+ storage;
250
+ stats = { hits: 0, misses: 0 };
251
+ constructor(options) {
252
+ this.storage = new MemoryCache(options);
253
+ }
254
+ /**
255
+ * Get a cached embedding
256
+ */
257
+ async get(content, options) {
258
+ const key = createCacheKey('embedding', { content, model: options.model });
259
+ const result = await this.storage.get(key);
260
+ if (result) {
261
+ this.stats.hits++;
262
+ }
263
+ else {
264
+ this.stats.misses++;
265
+ }
266
+ return result;
267
+ }
268
+ /**
269
+ * Set a cached embedding
270
+ */
271
+ async set(content, embedding, options) {
272
+ const key = createCacheKey('embedding', { content, model: options.model });
273
+ await this.storage.set(key, embedding);
274
+ }
275
+ /**
276
+ * Set multiple embeddings at once
277
+ */
278
+ async setMany(texts, embeddings, options) {
279
+ for (let i = 0; i < texts.length; i++) {
280
+ await this.set(texts[i], embeddings[i], options);
281
+ }
282
+ }
283
+ /**
284
+ * Get multiple embeddings, returning hits and misses
285
+ */
286
+ async getMany(texts, options) {
287
+ const hits = {};
288
+ const misses = [];
289
+ for (const text of texts) {
290
+ const embedding = await this.get(text, options);
291
+ if (embedding) {
292
+ hits[text] = embedding;
293
+ // Note: hits counter already incremented in get()
294
+ this.stats.hits--; // Avoid double counting
295
+ }
296
+ else {
297
+ misses.push(text);
298
+ this.stats.misses--; // Avoid double counting
299
+ }
300
+ }
301
+ // Add back correct counts
302
+ this.stats.hits += Object.keys(hits).length;
303
+ this.stats.misses += misses.length;
304
+ return { hits, misses };
305
+ }
306
+ /**
307
+ * Get cache statistics
308
+ */
309
+ getStats() {
310
+ const total = this.stats.hits + this.stats.misses;
311
+ return {
312
+ hits: this.stats.hits,
313
+ misses: this.stats.misses,
314
+ hitRate: total > 0 ? this.stats.hits / total : 0,
315
+ size: this.storage['cache'].size,
316
+ };
317
+ }
318
+ /**
319
+ * Clear the cache
320
+ */
321
+ async clear() {
322
+ await this.storage.clear();
323
+ this.stats = { hits: 0, misses: 0 };
324
+ }
325
+ }
326
+ /**
327
+ * Specialized cache for generation results
328
+ *
329
+ * @deprecated Phase C Week 1 — `GenerationCache` has zero production callers
330
+ * in primitives.org.ai (audited 2026-05-06; see `bd show aip-ibid`). New
331
+ * code should use `cacheMiddleware` (for `wrapLanguageModel`) — it composes
332
+ * with AI SDK 6 directly and carries trace + budget telemetry when paired
333
+ * via `wrapForV3`. Will be removed in the Phase C semver bump.
334
+ */
335
+ export class GenerationCache {
336
+ storage;
337
+ stats = { hits: 0, misses: 0 };
338
+ constructor(options) {
339
+ this.storage = new MemoryCache(options);
340
+ }
341
+ /**
342
+ * Get a cached generation result
343
+ */
344
+ async get(params, options) {
345
+ if (options?.bypass) {
346
+ return undefined;
347
+ }
348
+ const key = this.createKey(params);
349
+ const result = await this.storage.get(key);
350
+ if (result) {
351
+ this.stats.hits++;
352
+ }
353
+ else {
354
+ this.stats.misses++;
355
+ }
356
+ return result;
357
+ }
358
+ /**
359
+ * Set a cached generation result
360
+ */
361
+ async set(params, result) {
362
+ const key = this.createKey(params);
363
+ await this.storage.set(key, result);
364
+ }
365
+ /**
366
+ * Get cache statistics
367
+ */
368
+ getStats() {
369
+ const total = this.stats.hits + this.stats.misses;
370
+ return {
371
+ hits: this.stats.hits,
372
+ misses: this.stats.misses,
373
+ hitRate: total > 0 ? this.stats.hits / total : 0,
374
+ size: this.storage['cache'].size,
375
+ };
376
+ }
377
+ /**
378
+ * Clear the cache
379
+ */
380
+ async clear() {
381
+ await this.storage.clear();
382
+ this.stats = { hits: 0, misses: 0 };
383
+ }
384
+ /**
385
+ * Create a cache key from generation parameters
386
+ */
387
+ createKey(params) {
388
+ const keyParams = {
389
+ prompt: params.prompt,
390
+ model: params.model,
391
+ };
392
+ if (params.system !== undefined) {
393
+ keyParams['system'] = params.system;
394
+ }
395
+ if (params.temperature !== undefined) {
396
+ keyParams['temperature'] = params.temperature;
397
+ }
398
+ if (params.schemaVersion !== undefined) {
399
+ keyParams['schemaVersion'] = params.schemaVersion;
400
+ }
401
+ return createCacheKey('generation', keyParams);
402
+ }
403
+ }
404
+ /**
405
+ * Wrap an async function with caching
406
+ */
407
+ export function withCache(cache, fn, options) {
408
+ const { keyFn, ttl } = options;
409
+ const cachedFn = async (...args) => {
410
+ const key = keyFn(...args);
411
+ // Check cache
412
+ const cached = await cache.get(key);
413
+ if (cached !== undefined) {
414
+ return cached;
415
+ }
416
+ // Execute function
417
+ const result = await fn(...args);
418
+ // Cache result (don't cache errors - they throw before reaching here)
419
+ await cache.set(key, result, ttl !== undefined ? { ttl } : undefined);
420
+ return result;
421
+ };
422
+ // Add bypass method
423
+ cachedFn.bypass = async (...args) => {
424
+ const key = keyFn(...args);
425
+ // Execute function without checking cache
426
+ const result = await fn(...args);
427
+ // Update cache with new result
428
+ await cache.set(key, result, ttl !== undefined ? { ttl } : undefined);
429
+ return result;
430
+ };
431
+ return cachedFn;
432
+ }
433
+ //# sourceMappingURL=cache.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}
package/dist/context.d.ts CHANGED
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Execution Context for AI Functions
3
3
  *
4
- * Provides configuration without polluting function signatures.
5
- * Settings flow from environment global context local context.
4
+ * Standalone context module with batch processing and budget tracking features.
5
+ * Settings flow from environment -> global context -> local context.
6
6
  *
7
7
  * @example
8
8
  * ```ts
@@ -22,14 +22,44 @@
22
22
  *
23
23
  * @packageDocumentation
24
24
  */
25
- import type { FunctionOptions } from './template.js';
26
25
  import type { BatchProvider } from './batch-queue.js';
26
+ import type { RequestContext as IRequestContext, ModelPricing } from './budget.js';
27
+ /**
28
+ * Common options for all AI functions
29
+ */
30
+ export interface FunctionOptions {
31
+ /** Model to use (e.g., 'claude-opus-4-5', 'gpt-5-1', 'gemini-3-pro') */
32
+ model?: string;
33
+ /** Thinking level: 'none', 'low', 'medium', 'high', or token budget number */
34
+ thinking?: 'none' | 'low' | 'medium' | 'high' | number;
35
+ /** Temperature (0-2) */
36
+ temperature?: number;
37
+ /** Maximum tokens to generate */
38
+ maxTokens?: number;
39
+ /** System prompt */
40
+ system?: string;
41
+ /** Processing mode */
42
+ mode?: 'default' | 'background';
43
+ }
27
44
  /** Batch execution mode */
28
45
  export type BatchMode = 'auto' | 'immediate' | 'flex' | 'deferred';
29
- /** Execution context configuration */
46
+ /** Budget configuration for context */
47
+ export interface ContextBudgetConfig {
48
+ /** Maximum total tokens allowed */
49
+ maxTokens?: number;
50
+ /** Maximum cost in USD */
51
+ maxCost?: number;
52
+ /** Alert thresholds as fractions (e.g., [0.5, 0.8, 1.0]) */
53
+ alertThresholds?: number[];
54
+ /** Custom pricing for models not in default pricing table */
55
+ customPricing?: Record<string, ModelPricing>;
56
+ }
57
+ /**
58
+ * Execution context with batch processing and budget features.
59
+ */
30
60
  export interface ExecutionContext extends FunctionOptions {
31
- /** Batch provider to use */
32
- provider?: BatchProvider;
61
+ /** Provider to use (for model resolution) */
62
+ provider?: BatchProvider | string;
33
63
  /** Batch execution mode */
34
64
  batchMode?: BatchMode;
35
65
  /** Minimum items to use flex processing (for 'auto' mode, default: 5) */
@@ -40,6 +70,10 @@ export interface ExecutionContext extends FunctionOptions {
40
70
  webhookUrl?: string;
41
71
  /** Custom metadata for batch jobs */
42
72
  metadata?: Record<string, unknown>;
73
+ /** Budget configuration for tracking and limits */
74
+ budget?: ContextBudgetConfig;
75
+ /** Request context for tracing */
76
+ requestContext?: IRequestContext;
43
77
  }
44
78
  /**
45
79
  * Configure global defaults for AI functions
@@ -65,7 +99,7 @@ export declare function getGlobalContext(): ExecutionContext;
65
99
  export declare function resetContext(): void;
66
100
  /**
67
101
  * Get the current execution context
68
- * Merges: environment defaults global context local context
102
+ * Merges: environment defaults -> global context -> local context
69
103
  */
70
104
  export declare function getContext(): ExecutionContext;
71
105
  /**
@@ -85,7 +119,7 @@ export declare function withContext<T>(context: ExecutionContext, fn: () => T |
85
119
  */
86
120
  export declare function getModel(): string;
87
121
  /**
88
- * Get the effective provider from context
122
+ * Get the effective provider from context (typed as BatchProvider)
89
123
  */
90
124
  export declare function getProvider(): BatchProvider;
91
125
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAMrD,2BAA2B;AAC3B,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,WAAW,GACX,MAAM,GACN,UAAU,CAAA;AAEd,sCAAsC;AACtC,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,2BAA2B;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAEzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,CAEnD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAuCD;;;GAGG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,CAS7C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,gBAAgB,EACzB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAehB;AAwDD;;GAEG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAGjC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,aAAa,CAG3C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAGxC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAGzC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED,oCAAoC;AACpC,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAwBjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAGzC"}
1
+ {"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}