@providerkit/core 0.30.0 → 0.31.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 (132) hide show
  1. package/README.md +33 -5
  2. package/THIRD_PARTY_NOTICES +144 -0
  3. package/dist/auth/chatgpt-models.js.map +1 -1
  4. package/dist/auth/oauth.d.ts.map +1 -1
  5. package/dist/auth/oauth.js.map +1 -1
  6. package/dist/capability.js.map +1 -1
  7. package/dist/context.d.ts +4 -3
  8. package/dist/context.d.ts.map +1 -1
  9. package/dist/context.js +19 -5
  10. package/dist/context.js.map +1 -1
  11. package/dist/decisions.js.map +1 -1
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/errors.js.map +1 -1
  14. package/dist/fallback.d.ts +3 -0
  15. package/dist/fallback.d.ts.map +1 -1
  16. package/dist/fallback.js +9 -5
  17. package/dist/fallback.js.map +1 -1
  18. package/dist/gate.js.map +1 -1
  19. package/dist/hosted/anthropic.d.ts +30 -0
  20. package/dist/hosted/anthropic.d.ts.map +1 -0
  21. package/dist/hosted/anthropic.js +465 -0
  22. package/dist/hosted/anthropic.js.map +1 -0
  23. package/dist/hosted/gemini.d.ts +22 -0
  24. package/dist/hosted/gemini.d.ts.map +1 -0
  25. package/dist/hosted/gemini.js +440 -0
  26. package/dist/hosted/gemini.js.map +1 -0
  27. package/dist/hosted/openai.d.ts +33 -0
  28. package/dist/hosted/openai.d.ts.map +1 -0
  29. package/dist/hosted/openai.js +107 -0
  30. package/dist/hosted/openai.js.map +1 -0
  31. package/dist/hosted/responses.d.ts +28 -0
  32. package/dist/hosted/responses.d.ts.map +1 -0
  33. package/dist/hosted/responses.js +358 -0
  34. package/dist/hosted/responses.js.map +1 -0
  35. package/dist/hosted/shared.d.ts +107 -0
  36. package/dist/hosted/shared.d.ts.map +1 -0
  37. package/dist/hosted/shared.js +264 -0
  38. package/dist/hosted/shared.js.map +1 -0
  39. package/dist/hosted/types.d.ts +191 -0
  40. package/dist/hosted/types.d.ts.map +1 -0
  41. package/dist/hosted/types.js +10 -0
  42. package/dist/hosted/types.js.map +1 -0
  43. package/dist/hosted.d.ts +33 -0
  44. package/dist/hosted.d.ts.map +1 -0
  45. package/dist/hosted.js +61 -0
  46. package/dist/hosted.js.map +1 -0
  47. package/dist/index.d.ts +8 -7
  48. package/dist/index.d.ts.map +1 -1
  49. package/dist/index.js +8 -7
  50. package/dist/index.js.map +1 -1
  51. package/dist/key-pool.d.ts.map +1 -1
  52. package/dist/key-pool.js.map +1 -1
  53. package/dist/presets.d.ts +2 -2
  54. package/dist/presets.d.ts.map +1 -1
  55. package/dist/providers/anthropic.d.ts +75 -1
  56. package/dist/providers/anthropic.d.ts.map +1 -1
  57. package/dist/providers/anthropic.js +207 -135
  58. package/dist/providers/anthropic.js.map +1 -1
  59. package/dist/providers/factory.d.ts +10 -0
  60. package/dist/providers/factory.d.ts.map +1 -1
  61. package/dist/providers/factory.js +31 -23
  62. package/dist/providers/factory.js.map +1 -1
  63. package/dist/providers/gemini.d.ts +123 -1
  64. package/dist/providers/gemini.d.ts.map +1 -1
  65. package/dist/providers/gemini.js +114 -54
  66. package/dist/providers/gemini.js.map +1 -1
  67. package/dist/providers/hosted-codecs.d.ts +10 -0
  68. package/dist/providers/hosted-codecs.d.ts.map +1 -0
  69. package/dist/providers/hosted-codecs.js +8 -0
  70. package/dist/providers/hosted-codecs.js.map +1 -0
  71. package/dist/providers/openai.d.ts +69 -0
  72. package/dist/providers/openai.d.ts.map +1 -1
  73. package/dist/providers/openai.js +38 -14
  74. package/dist/providers/openai.js.map +1 -1
  75. package/dist/providers/responses.d.ts +123 -0
  76. package/dist/providers/responses.d.ts.map +1 -1
  77. package/dist/providers/responses.js +57 -22
  78. package/dist/providers/responses.js.map +1 -1
  79. package/dist/providers/speech-factory.js.map +1 -1
  80. package/dist/registry.d.ts +3 -0
  81. package/dist/registry.d.ts.map +1 -1
  82. package/dist/registry.js +8 -4
  83. package/dist/registry.js.map +1 -1
  84. package/dist/retry.js.map +1 -1
  85. package/dist/speech-core.d.ts.map +1 -1
  86. package/dist/speech-core.js.map +1 -1
  87. package/dist/tools.d.ts.map +1 -1
  88. package/dist/tools.js.map +1 -1
  89. package/dist/transcription-core.d.ts.map +1 -1
  90. package/dist/transcription-core.js.map +1 -1
  91. package/dist/transport.js.map +1 -1
  92. package/dist/turn.d.ts +10 -1
  93. package/dist/turn.d.ts.map +1 -1
  94. package/dist/turn.js +53 -1
  95. package/dist/turn.js.map +1 -1
  96. package/dist/types.d.ts +51 -0
  97. package/dist/types.d.ts.map +1 -1
  98. package/dist/types.js.map +1 -1
  99. package/dist/usage.d.ts +10 -1
  100. package/dist/usage.d.ts.map +1 -1
  101. package/dist/usage.js +40 -2
  102. package/dist/usage.js.map +1 -1
  103. package/dist/watchdog.d.ts +6 -0
  104. package/dist/watchdog.d.ts.map +1 -1
  105. package/dist/watchdog.js +10 -2
  106. package/dist/watchdog.js.map +1 -1
  107. package/package.json +10 -5
  108. package/src/context.ts +21 -5
  109. package/src/fallback.ts +21 -6
  110. package/src/hosted/anthropic.ts +512 -0
  111. package/src/hosted/gemini.ts +510 -0
  112. package/src/hosted/openai.ts +137 -0
  113. package/src/hosted/responses.ts +420 -0
  114. package/src/hosted/shared.ts +341 -0
  115. package/src/hosted/types.ts +214 -0
  116. package/src/hosted.ts +101 -0
  117. package/src/index.ts +64 -7
  118. package/src/providers/anthropic.ts +252 -143
  119. package/src/providers/factory.ts +127 -82
  120. package/src/providers/gemini.ts +184 -60
  121. package/src/providers/hosted-codecs.ts +29 -0
  122. package/src/providers/openai.ts +52 -15
  123. package/src/providers/responses.ts +93 -24
  124. package/src/registry.ts +14 -4
  125. package/src/turn.ts +55 -1
  126. package/src/types.ts +62 -1
  127. package/src/usage.ts +32 -2
  128. package/src/watchdog.ts +12 -2
  129. package/dist/jev.d.ts +0 -123
  130. package/dist/jev.d.ts.map +0 -1
  131. package/dist/jev.js +0 -278
  132. package/dist/jev.js.map +0 -1
@@ -0,0 +1,420 @@
1
+ // Hosted shapes and annotations follow Vercel AI SDK (Apache-2.0) and
2
+ // PydanticAI (MIT). See THIRD_PARTY_NOTICES.
3
+ import { ProviderError } from "../errors.ts";
4
+ import {
5
+ codePointIndex,
6
+ hostedCounts,
7
+ HostedRecorder,
8
+ planHostedTools,
9
+ queryInput,
10
+ servedAt,
11
+ } from "./shared.ts";
12
+ import type {
13
+ Citation,
14
+ HostedCall,
15
+ HostedCallDelta,
16
+ HostedInput,
17
+ HostedTool,
18
+ HostedToolType,
19
+ } from "./types.ts";
20
+ import type { ResponsesConfig, ResponsesEvent, ResponsesItem } from "../providers/responses.ts";
21
+ import type { ImagePart, ProviderChunk, StreamOptions } from "../types.ts";
22
+
23
+ /** The hosted types this wire has a shape for, and the fields it applies. No
24
+ * use cap on web search, and no fetch tool, on this wire. */
25
+ const RESPONSES_FIELDS: Partial<Record<HostedToolType, readonly string[]>> = {
26
+ web_search: ["allowedDomains", "blockedDomains", "userLocation"],
27
+ code_execution: ["fileIds"],
28
+ file_search: ["storeIds", "maxResults"],
29
+ image_generation: ["size", "quality", "format", "background"],
30
+ };
31
+ const RESPONSES_SENDS = Object.keys(RESPONSES_FIELDS);
32
+
33
+ /** The output each hosted tool needs asked for by name, or it comes back
34
+ * without its sources, logs or results. */
35
+ const RESPONSES_INCLUDES: Partial<Record<HostedToolType, string>> = {
36
+ web_search: "web_search_call.action.sources",
37
+ code_execution: "code_interpreter_call.outputs",
38
+ file_search: "file_search_call.results",
39
+ };
40
+
41
+ /** One hosted tool on the wire. Shapes from Vercel's AI SDK (Apache-2.0),
42
+ * openai-responses-prepare-tools.ts:238-381. */
43
+ function responsesHostedTool(provider: string, tool: HostedTool): unknown {
44
+ switch (tool.type) {
45
+ case "web_search":
46
+ return {
47
+ type: "web_search",
48
+ ...(tool.allowedDomains || tool.blockedDomains
49
+ ? {
50
+ filters: {
51
+ allowed_domains: tool.allowedDomains,
52
+ blocked_domains: tool.blockedDomains,
53
+ },
54
+ }
55
+ : {}),
56
+ ...(tool.userLocation
57
+ ? { user_location: { type: "approximate", ...tool.userLocation } }
58
+ : {}),
59
+ };
60
+ case "code_execution":
61
+ return { type: "code_interpreter", container: { type: "auto", file_ids: tool.fileIds } };
62
+ case "file_search":
63
+ return {
64
+ type: "file_search",
65
+ vector_store_ids: tool.storeIds,
66
+ max_num_results: tool.maxResults,
67
+ };
68
+ case "image_generation":
69
+ return {
70
+ type: "image_generation",
71
+ size: tool.size,
72
+ quality: tool.quality,
73
+ output_format: tool.format,
74
+ background: tool.background,
75
+ };
76
+ default:
77
+ // planHostedTools only passes the types in RESPONSES_FIELDS.
78
+ throw new ProviderError(
79
+ provider,
80
+ "invalid",
81
+ `${provider}: no Responses shape for ${tool.type}`,
82
+ );
83
+ }
84
+ }
85
+
86
+ /** The seam's type for a hosted output item, or undefined for any other item. */
87
+ const HOSTED_ITEMS: Record<string, HostedToolType> = {
88
+ web_search_call: "web_search",
89
+ code_interpreter_call: "code_execution",
90
+ file_search_call: "file_search",
91
+ image_generation_call: "image_generation",
92
+ };
93
+
94
+ /** A generated image's media type, read off its first bytes: the format the
95
+ * request asked for is a wish, the bytes are the image. */
96
+ function imageType(base64: string, asked: HostedTool | undefined): ImagePart["mimeType"] {
97
+ if (base64.startsWith("iVBORw0KGgo")) return "image/png";
98
+ if (base64.startsWith("/9j/")) return "image/jpeg";
99
+ if (base64.startsWith("UklGR")) return "image/webp";
100
+ if (base64.startsWith("R0lGOD")) return "image/gif";
101
+ // ponytail: unrecognized bytes fall back to the format asked for, PNG by
102
+ // default, which is the API's own default. Upgrade: refuse them.
103
+ switch (asked?.type === "image_generation" ? asked.format : undefined) {
104
+ case "jpeg":
105
+ return "image/jpeg";
106
+ case "webp":
107
+ return "image/webp";
108
+ default:
109
+ return "image/png";
110
+ }
111
+ }
112
+
113
+ /** What a web search did, from its `action`: the queries it ran, or the page
114
+ * it opened or searched within. */
115
+ function webSearchInput(action: ResponsesItem["action"]): HostedInput | undefined {
116
+ if (action?.type === "search") return queryInput(action.queries ?? [action.query]);
117
+ return action?.url ? { url: action.url } : undefined;
118
+ }
119
+
120
+ /** What a hosted item says it did. `.added` states only its id and type;
121
+ * `.done` states the whole call. A status other than `completed` on `.done`
122
+ * is a failed call, kept as data (invariant 7). */
123
+ function hostedItemDelta(
124
+ item: ResponsesItem,
125
+ done: boolean,
126
+ asked: HostedTool | undefined,
127
+ ): Omit<HostedCallDelta, "index"> {
128
+ const failed = done && item.status !== undefined && item.status !== "completed";
129
+ let status: HostedCall["status"] = "running";
130
+ if (failed) status = "failed";
131
+ else if (done) status = "completed";
132
+ const error = failed ? (item.error?.code ?? item.error?.message ?? item.status) : undefined;
133
+ const base = { status, ...(error ? { error } : {}) };
134
+ switch (item.type) {
135
+ case "web_search_call": {
136
+ const action = item.action;
137
+ const input = webSearchInput(action);
138
+ const sources = (action?.sources ?? []).flatMap((source) =>
139
+ source.type === "url" && source.url ? [{ type: "url" as const, url: source.url }] : [],
140
+ );
141
+ return {
142
+ ...base,
143
+ ...(input && Object.keys(input).length > 0 ? { input } : {}),
144
+ ...(done && sources.length > 0 ? { output: { sources } } : {}),
145
+ };
146
+ }
147
+ case "code_interpreter_call": {
148
+ const logs = (item.outputs ?? []).flatMap((out) =>
149
+ out.type === "logs" && out.logs ? [out.logs] : [],
150
+ );
151
+ const files = (item.outputs ?? []).flatMap((out) =>
152
+ out.type === "image" && out.url
153
+ ? [{ url: out.url, ...(item.container_id ? { containerId: item.container_id } : {}) }]
154
+ : [],
155
+ );
156
+ return {
157
+ ...base,
158
+ input: { ...(item.code ? { code: item.code } : {}), language: "python" },
159
+ ...(done && (logs.length > 0 || files.length > 0)
160
+ ? {
161
+ output: {
162
+ ...(logs.length > 0 ? { stdout: logs.join("\n") } : {}),
163
+ ...(files.length > 0 ? { files } : {}),
164
+ },
165
+ }
166
+ : {}),
167
+ };
168
+ }
169
+ case "file_search_call": {
170
+ const input = queryInput(item.queries ?? []);
171
+ const sources = (item.results ?? []).map((result) => ({
172
+ type: "file" as const,
173
+ ...(result.file_id ? { fileId: result.file_id } : {}),
174
+ ...(result.filename ? { title: result.filename } : {}),
175
+ ...(result.text ? { excerpt: result.text } : {}),
176
+ }));
177
+ return {
178
+ ...base,
179
+ ...(Object.keys(input).length > 0 ? { input } : {}),
180
+ ...(done && sources.length > 0 ? { output: { sources } } : {}),
181
+ };
182
+ }
183
+ default: {
184
+ const image = done && item.result ? item.result : undefined;
185
+ return {
186
+ ...base,
187
+ ...(item.revised_prompt ? { input: { prompt: item.revised_prompt } } : {}),
188
+ ...(image
189
+ ? {
190
+ output: {
191
+ images: [{ type: "image", mimeType: imageType(image, asked), data: image }],
192
+ },
193
+ }
194
+ : {}),
195
+ };
196
+ }
197
+ }
198
+ }
199
+
200
+ /** An annotation Responses attached to a part of the answer. */
201
+ export interface ResponsesAnnotation {
202
+ type?: string;
203
+ url?: string;
204
+ title?: string;
205
+ file_id?: string;
206
+ filename?: string;
207
+ container_id?: string;
208
+ start_index?: number;
209
+ end_index?: number;
210
+ index?: number;
211
+ }
212
+
213
+ /**
214
+ * One annotation as a citation, its offsets moved from the part's code points
215
+ * to the turn's JS indices. A URL citation selects the link the model wrote,
216
+ * so its span is kept only while it still contains the URL (PydanticAI, MIT,
217
+ * openai/_citations.py:112-118); a span that doesn't check out is dropped and
218
+ * the source kept. Mapping from Vercel's AI SDK (Apache-2.0),
219
+ * map-openai-responses-annotation.ts:11-74.
220
+ */
221
+ function annotationCitation(
222
+ annotation: ResponsesAnnotation,
223
+ text: string,
224
+ part: { start: number; end: number } | undefined,
225
+ ): Citation | undefined {
226
+ const partText = part ? text.slice(part.start, part.end) : "";
227
+ const at = (points: number | undefined) =>
228
+ part && points !== undefined ? codePointIndex(partText, points) : undefined;
229
+ const span = (start: number | undefined, end: number | undefined, contains?: string) =>
230
+ part &&
231
+ start !== undefined &&
232
+ end !== undefined &&
233
+ start < end &&
234
+ (contains === undefined || partText.slice(start, end).includes(contains))
235
+ ? { start: part.start + start, end: part.start + end, anchor: "marker" as const }
236
+ : {};
237
+ switch (annotation.type) {
238
+ case "url_citation": {
239
+ if (!annotation.url) return undefined;
240
+ const source = {
241
+ type: "url" as const,
242
+ url: annotation.url,
243
+ ...(annotation.title ? { title: annotation.title } : {}),
244
+ };
245
+ return {
246
+ source,
247
+ ...span(at(annotation.start_index), at(annotation.end_index), annotation.url),
248
+ };
249
+ }
250
+ case "file_citation":
251
+ case "container_file_citation": {
252
+ if (!annotation.file_id && !annotation.filename) return undefined;
253
+ const source = {
254
+ type: "file" as const,
255
+ ...(annotation.file_id ? { fileId: annotation.file_id } : {}),
256
+ ...(annotation.filename ? { title: annotation.filename } : {}),
257
+ ...(annotation.container_id ? { containerId: annotation.container_id } : {}),
258
+ };
259
+ // A file citation marks one point, where the model referred to the file.
260
+ const point = at(annotation.index);
261
+ if (annotation.type === "file_citation") {
262
+ return point === undefined || !part
263
+ ? { source }
264
+ : { source, start: part.start + point, end: part.start + point, anchor: "marker" };
265
+ }
266
+ return { source, ...span(at(annotation.start_index), at(annotation.end_index)) };
267
+ }
268
+ default:
269
+ // `file_path` names a file code wrote, not a source of the answer.
270
+ return undefined;
271
+ }
272
+ }
273
+
274
+ export const responsesHosted = {
275
+ plan(config: ResponsesConfig, baseUrl: string, id: string, opts: StreamOptions) {
276
+ const hosted = planHostedTools(
277
+ id,
278
+ {
279
+ name: "Responses",
280
+ serves: (
281
+ config.servesHostedTools ??
282
+ servedAt(baseUrl, "api.openai.com", [
283
+ "web_search",
284
+ "code_execution",
285
+ "file_search",
286
+ "image_generation",
287
+ ])
288
+ ).filter((type) => RESPONSES_SENDS.includes(type)),
289
+ fields: RESPONSES_FIELDS,
290
+ },
291
+ opts,
292
+ );
293
+ return {
294
+ hosted,
295
+ tools: hosted.map((tool) => responsesHostedTool(id, tool)),
296
+ include: hosted.flatMap((tool) => RESPONSES_INCLUDES[tool.type] ?? []),
297
+ };
298
+ },
299
+ stream(hosted: HostedTool[]) {
300
+ // Hosted calls, by item id. The answer so far, and where each part of it
301
+ // starts, so an annotation's offsets can be placed and checked.
302
+ const recorder = new HostedRecorder();
303
+ let text = "";
304
+ const parts = new Map<string, { start: number; end: number }>();
305
+ // Waiting annotations, by the message item they belong to.
306
+ const annotations = new Map<string, { part: string; annotation: ResponsesAnnotation }[]>();
307
+ const partKey = (event: ResponsesEvent) => `${event.item_id ?? ""}:${event.content_index ?? 0}`;
308
+ const asked = (type: HostedToolType) => hosted.find((tool) => tool.type === type);
309
+ // An annotation is placed once its part is whole: when its message item
310
+ // ends, or, for every item still waiting, when the turn does.
311
+ function* cite(item?: string): Generator<ProviderChunk> {
312
+ const due =
313
+ item === undefined ? [...annotations.values()].flat() : (annotations.get(item) ?? []);
314
+ if (item === undefined) annotations.clear();
315
+ else annotations.delete(item);
316
+ const citations = due.flatMap(({ part, annotation }) => {
317
+ const citation = annotationCitation(annotation, text, parts.get(part));
318
+ return citation ? [citation] : [];
319
+ });
320
+ if (citations.length > 0) yield { type: "delta", citations };
321
+ }
322
+ // The end of the turn: a hosted call the backend never finished fails,
323
+ // and every annotation still waiting is placed.
324
+ function* closeHosted(): Generator<ProviderChunk> {
325
+ const failed = recorder.settle();
326
+ if (failed.length > 0) yield { type: "delta", hosted: failed };
327
+ yield* cite();
328
+ }
329
+
330
+ return {
331
+ *event(event: ResponsesEvent): Generator<ProviderChunk> {
332
+ // Every step a hosted call reports (in progress, searching,
333
+ // interpreting, generating) goes out as a status delta: progress the
334
+ // watchdog's progress clock can see while the vendor's tool works.
335
+ if (
336
+ /^response\.(web_search|file_search|code_interpreter|image_generation)_call\.\w+$/.test(
337
+ event.type ?? "",
338
+ )
339
+ ) {
340
+ const index = recorder.indexOf(event.item_id);
341
+ if (index !== undefined) yield { type: "delta", hosted: [{ index, status: "running" }] };
342
+ return;
343
+ }
344
+
345
+ switch (event.type) {
346
+ case "response.output_text.delta":
347
+ if (event.delta) {
348
+ const key = partKey(event);
349
+ const part = parts.get(key) ?? { start: text.length, end: text.length };
350
+ text += event.delta;
351
+ part.end = text.length;
352
+ parts.set(key, part);
353
+ }
354
+ break;
355
+
356
+ case "response.output_text.annotation.added":
357
+ if (event.annotation) {
358
+ const item = event.item_id ?? "";
359
+ const waiting = annotations.get(item) ?? [];
360
+ waiting.push({ part: partKey(event), annotation: event.annotation });
361
+ annotations.set(item, waiting);
362
+ }
363
+ break;
364
+
365
+ case "response.code_interpreter_call_code.delta": {
366
+ const index = recorder.indexOf(event.item_id);
367
+ if (index !== undefined && event.delta) {
368
+ yield { type: "delta", hosted: [{ index, codeDelta: event.delta }] };
369
+ }
370
+ break;
371
+ }
372
+
373
+ // The whole program, which wins over the deltas it repeats.
374
+ case "response.code_interpreter_call_code.done": {
375
+ const index = recorder.indexOf(event.item_id);
376
+ if (index !== undefined && event.code !== undefined) {
377
+ yield { type: "delta", hosted: [{ index, input: { code: event.code } }] };
378
+ }
379
+ break;
380
+ }
381
+
382
+ case "response.output_item.added": {
383
+ const item = event.item;
384
+ const type = item?.type ? HOSTED_ITEMS[item.type] : undefined;
385
+ if (item && type) {
386
+ // A hosted call, never a function call: no tool for the loop to
387
+ // run, and no part in the finish reason.
388
+ const started = recorder.start(item.id, type, text.length);
389
+ yield {
390
+ type: "delta",
391
+ hosted: [{ ...started, ...hostedItemDelta(item, false, asked(type)) }],
392
+ };
393
+ break;
394
+ }
395
+ break;
396
+ }
397
+ case "response.output_item.done": {
398
+ const item = event.item;
399
+ const type = item?.type ? HOSTED_ITEMS[item.type] : undefined;
400
+ if (item && type) {
401
+ const delta = hostedItemDelta(item, true, asked(type));
402
+ // A backend that sends only the finished item still ran it.
403
+ const done =
404
+ recorder.end(item.id, delta) ?? recorder.whole(item.id, type, text.length, delta);
405
+ yield { type: "delta", hosted: [done] };
406
+ break;
407
+ }
408
+ if (item?.type === "message") {
409
+ yield* cite(item.id);
410
+ break;
411
+ }
412
+ break;
413
+ }
414
+ }
415
+ },
416
+ close: closeHosted,
417
+ counts: () => hostedCounts(recorder.shown()),
418
+ };
419
+ },
420
+ };