@tanstack/ai 0.0.3 → 0.1.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 (146) hide show
  1. package/README.md +26 -0
  2. package/dist/esm/activities/chat/adapter.d.ts +100 -0
  3. package/dist/esm/activities/chat/adapter.js +14 -0
  4. package/dist/esm/activities/chat/adapter.js.map +1 -0
  5. package/dist/esm/{utilities → activities/chat}/agent-loop-strategies.d.ts +4 -4
  6. package/dist/esm/activities/chat/agent-loop-strategies.js.map +1 -0
  7. package/dist/esm/activities/chat/index.d.ts +165 -0
  8. package/dist/esm/{core/chat.js → activities/chat/index.js} +131 -33
  9. package/dist/esm/activities/chat/index.js.map +1 -0
  10. package/dist/esm/{message-converters.d.ts → activities/chat/messages.d.ts} +1 -1
  11. package/dist/esm/{message-converters.js → activities/chat/messages.js} +7 -7
  12. package/dist/esm/activities/chat/messages.js.map +1 -0
  13. package/dist/esm/activities/chat/stream/json-parser.js.map +1 -0
  14. package/dist/esm/{stream → activities/chat/stream}/message-updaters.d.ts +1 -1
  15. package/dist/esm/activities/chat/stream/message-updaters.js.map +1 -0
  16. package/dist/esm/{stream → activities/chat/stream}/processor.d.ts +1 -1
  17. package/dist/esm/{stream → activities/chat/stream}/processor.js +1 -1
  18. package/dist/esm/activities/chat/stream/processor.js.map +1 -0
  19. package/dist/esm/activities/chat/stream/strategies.js.map +1 -0
  20. package/dist/esm/{stream → activities/chat/stream}/types.d.ts +2 -9
  21. package/dist/esm/{tools → activities/chat/tools}/tool-calls.d.ts +1 -1
  22. package/dist/esm/{tools → activities/chat/tools}/tool-calls.js +9 -5
  23. package/dist/esm/activities/chat/tools/tool-calls.js.map +1 -0
  24. package/dist/esm/{tools → activities/chat/tools}/tool-definition.d.ts +14 -14
  25. package/dist/esm/activities/chat/tools/tool-definition.js.map +1 -0
  26. package/dist/esm/activities/chat/tools/zod-converter.d.ts +69 -0
  27. package/dist/esm/activities/chat/tools/zod-converter.js +99 -0
  28. package/dist/esm/activities/chat/tools/zod-converter.js.map +1 -0
  29. package/dist/esm/activities/generateImage/adapter.d.ts +68 -0
  30. package/dist/esm/activities/generateImage/adapter.js +14 -0
  31. package/dist/esm/activities/generateImage/adapter.js.map +1 -0
  32. package/dist/esm/activities/generateImage/index.d.ts +89 -0
  33. package/dist/esm/activities/generateImage/index.js +15 -0
  34. package/dist/esm/activities/generateImage/index.js.map +1 -0
  35. package/dist/esm/activities/generateSpeech/adapter.d.ts +62 -0
  36. package/dist/esm/activities/generateSpeech/adapter.js +14 -0
  37. package/dist/esm/activities/generateSpeech/adapter.js.map +1 -0
  38. package/dist/esm/activities/generateSpeech/index.d.ts +69 -0
  39. package/dist/esm/activities/generateSpeech/index.js +15 -0
  40. package/dist/esm/activities/generateSpeech/index.js.map +1 -0
  41. package/dist/esm/activities/generateTranscription/adapter.d.ts +62 -0
  42. package/dist/esm/activities/generateTranscription/adapter.js +14 -0
  43. package/dist/esm/activities/generateTranscription/adapter.js.map +1 -0
  44. package/dist/esm/activities/generateTranscription/index.d.ts +71 -0
  45. package/dist/esm/activities/generateTranscription/index.js +15 -0
  46. package/dist/esm/activities/generateTranscription/index.js.map +1 -0
  47. package/dist/esm/activities/generateVideo/adapter.d.ts +80 -0
  48. package/dist/esm/activities/generateVideo/adapter.js +14 -0
  49. package/dist/esm/activities/generateVideo/adapter.js.map +1 -0
  50. package/dist/esm/activities/generateVideo/index.d.ts +136 -0
  51. package/dist/esm/activities/generateVideo/index.js +47 -0
  52. package/dist/esm/activities/generateVideo/index.js.map +1 -0
  53. package/dist/esm/activities/index.d.ts +22 -0
  54. package/dist/esm/activities/index.js +34 -0
  55. package/dist/esm/activities/index.js.map +1 -0
  56. package/dist/esm/activities/summarize/adapter.d.ts +74 -0
  57. package/dist/esm/activities/summarize/adapter.js +14 -0
  58. package/dist/esm/activities/summarize/adapter.js.map +1 -0
  59. package/dist/esm/activities/summarize/index.d.ts +100 -0
  60. package/dist/esm/activities/summarize/index.js +90 -0
  61. package/dist/esm/activities/summarize/index.js.map +1 -0
  62. package/dist/esm/event-client.d.ts +4 -18
  63. package/dist/esm/event-client.js.map +1 -1
  64. package/dist/esm/index.d.ts +16 -14
  65. package/dist/esm/index.js +28 -19
  66. package/dist/esm/stream-to-response.d.ts +95 -0
  67. package/dist/esm/stream-to-response.js +118 -0
  68. package/dist/esm/stream-to-response.js.map +1 -0
  69. package/dist/esm/types.d.ts +347 -129
  70. package/package.json +5 -1
  71. package/src/activities/chat/adapter.ts +150 -0
  72. package/src/{utilities → activities/chat}/agent-loop-strategies.ts +4 -4
  73. package/src/{core/chat.ts → activities/chat/index.ts} +427 -79
  74. package/src/{message-converters.ts → activities/chat/messages.ts} +10 -13
  75. package/src/{stream → activities/chat/stream}/message-updaters.ts +1 -1
  76. package/src/{stream → activities/chat/stream}/processor.ts +2 -5
  77. package/src/{stream → activities/chat/stream}/types.ts +8 -18
  78. package/src/{tools → activities/chat/tools}/tool-calls.ts +36 -11
  79. package/src/{tools → activities/chat/tools}/tool-definition.ts +36 -27
  80. package/src/activities/chat/tools/zod-converter.ts +235 -0
  81. package/src/activities/generateImage/adapter.ts +104 -0
  82. package/src/activities/generateImage/index.ts +162 -0
  83. package/src/activities/generateSpeech/adapter.ts +87 -0
  84. package/src/activities/generateSpeech/index.ts +122 -0
  85. package/src/activities/generateTranscription/adapter.ts +89 -0
  86. package/src/activities/generateTranscription/index.ts +132 -0
  87. package/src/activities/generateVideo/adapter.ts +116 -0
  88. package/src/activities/generateVideo/index.ts +261 -0
  89. package/src/activities/index.ts +164 -0
  90. package/src/activities/summarize/adapter.ts +107 -0
  91. package/src/activities/summarize/index.ts +287 -0
  92. package/src/event-client.ts +5 -21
  93. package/src/index.ts +58 -15
  94. package/src/stream-to-response.ts +237 -0
  95. package/src/types.ts +404 -280
  96. package/dist/esm/base-adapter.d.ts +0 -36
  97. package/dist/esm/base-adapter.js +0 -12
  98. package/dist/esm/base-adapter.js.map +0 -1
  99. package/dist/esm/core/chat-common-options.d.ts +0 -52
  100. package/dist/esm/core/chat.d.ts +0 -30
  101. package/dist/esm/core/chat.js.map +0 -1
  102. package/dist/esm/core/embedding.d.ts +0 -8
  103. package/dist/esm/core/embedding.js +0 -33
  104. package/dist/esm/core/embedding.js.map +0 -1
  105. package/dist/esm/core/summarize.d.ts +0 -9
  106. package/dist/esm/core/summarize.js +0 -36
  107. package/dist/esm/core/summarize.js.map +0 -1
  108. package/dist/esm/message-converters.js.map +0 -1
  109. package/dist/esm/stream/json-parser.js.map +0 -1
  110. package/dist/esm/stream/message-updaters.js.map +0 -1
  111. package/dist/esm/stream/processor.js.map +0 -1
  112. package/dist/esm/stream/strategies.js.map +0 -1
  113. package/dist/esm/tools/tool-calls.js.map +0 -1
  114. package/dist/esm/tools/tool-definition.js.map +0 -1
  115. package/dist/esm/tools/zod-converter.d.ts +0 -30
  116. package/dist/esm/tools/zod-converter.js +0 -36
  117. package/dist/esm/tools/zod-converter.js.map +0 -1
  118. package/dist/esm/utilities/agent-loop-strategies.js.map +0 -1
  119. package/dist/esm/utilities/chat-options.d.ts +0 -6
  120. package/dist/esm/utilities/chat-options.js +0 -7
  121. package/dist/esm/utilities/chat-options.js.map +0 -1
  122. package/dist/esm/utilities/messages.d.ts +0 -30
  123. package/dist/esm/utilities/messages.js +0 -7
  124. package/dist/esm/utilities/messages.js.map +0 -1
  125. package/dist/esm/utilities/stream-to-response.d.ts +0 -48
  126. package/dist/esm/utilities/stream-to-response.js +0 -62
  127. package/dist/esm/utilities/stream-to-response.js.map +0 -1
  128. package/src/base-adapter.ts +0 -86
  129. package/src/core/chat-common-options.ts +0 -55
  130. package/src/core/embedding.ts +0 -54
  131. package/src/core/summarize.ts +0 -56
  132. package/src/tools/zod-converter.ts +0 -85
  133. package/src/utilities/chat-options.ts +0 -35
  134. package/src/utilities/messages.ts +0 -63
  135. package/src/utilities/stream-to-response.ts +0 -116
  136. /package/dist/esm/{utilities → activities/chat}/agent-loop-strategies.js +0 -0
  137. /package/dist/esm/{stream → activities/chat/stream}/index.d.ts +0 -0
  138. /package/dist/esm/{stream → activities/chat/stream}/json-parser.d.ts +0 -0
  139. /package/dist/esm/{stream → activities/chat/stream}/json-parser.js +0 -0
  140. /package/dist/esm/{stream → activities/chat/stream}/message-updaters.js +0 -0
  141. /package/dist/esm/{stream → activities/chat/stream}/strategies.d.ts +0 -0
  142. /package/dist/esm/{stream → activities/chat/stream}/strategies.js +0 -0
  143. /package/dist/esm/{tools → activities/chat/tools}/tool-definition.js +0 -0
  144. /package/src/{stream → activities/chat/stream}/index.ts +0 -0
  145. /package/src/{stream → activities/chat/stream}/json-parser.ts +0 -0
  146. /package/src/{stream → activities/chat/stream}/strategies.ts +0 -0
@@ -1,6 +1,66 @@
1
- import { CommonOptions } from './core/chat-common-options.js';
2
1
  import { z } from 'zod';
3
- import { ToolCallState, ToolResultState } from './stream/types.js';
2
+ /**
3
+ * Tool call states - track the lifecycle of a tool call
4
+ */
5
+ export type ToolCallState = 'awaiting-input' | 'input-streaming' | 'input-complete' | 'approval-requested' | 'approval-responded';
6
+ /**
7
+ * Tool result states - track the lifecycle of a tool result
8
+ */
9
+ export type ToolResultState = 'streaming' | 'complete' | 'error';
10
+ /**
11
+ * JSON Schema type for defining tool input/output schemas as raw JSON Schema objects.
12
+ * This allows tools to be defined without Zod when you have JSON Schema definitions available.
13
+ */
14
+ export interface JSONSchema {
15
+ type?: string | Array<string>;
16
+ properties?: Record<string, JSONSchema>;
17
+ items?: JSONSchema | Array<JSONSchema>;
18
+ required?: Array<string>;
19
+ enum?: Array<any>;
20
+ const?: any;
21
+ description?: string;
22
+ default?: any;
23
+ $ref?: string;
24
+ $defs?: Record<string, JSONSchema>;
25
+ definitions?: Record<string, JSONSchema>;
26
+ allOf?: Array<JSONSchema>;
27
+ anyOf?: Array<JSONSchema>;
28
+ oneOf?: Array<JSONSchema>;
29
+ not?: JSONSchema;
30
+ if?: JSONSchema;
31
+ then?: JSONSchema;
32
+ else?: JSONSchema;
33
+ minimum?: number;
34
+ maximum?: number;
35
+ exclusiveMinimum?: number;
36
+ exclusiveMaximum?: number;
37
+ minLength?: number;
38
+ maxLength?: number;
39
+ pattern?: string;
40
+ format?: string;
41
+ minItems?: number;
42
+ maxItems?: number;
43
+ uniqueItems?: boolean;
44
+ additionalProperties?: boolean | JSONSchema;
45
+ additionalItems?: boolean | JSONSchema;
46
+ patternProperties?: Record<string, JSONSchema>;
47
+ propertyNames?: JSONSchema;
48
+ minProperties?: number;
49
+ maxProperties?: number;
50
+ title?: string;
51
+ examples?: Array<any>;
52
+ [key: string]: any;
53
+ }
54
+ /**
55
+ * Union type for schema input - can be either a Zod schema or a JSONSchema object.
56
+ */
57
+ export type SchemaInput = z.ZodType | JSONSchema;
58
+ /**
59
+ * Infer the TypeScript type from a schema.
60
+ * For Zod schemas, uses z.infer to get the proper type.
61
+ * For JSONSchema, returns `any` since we can't infer types from JSON Schema at compile time.
62
+ */
63
+ export type InferSchemaType<T> = T extends z.ZodType ? z.infer<T> : any;
4
64
  export interface ToolCall {
5
65
  id: string;
6
66
  type: 'function';
@@ -87,13 +147,13 @@ export interface DocumentPart<TMetadata = unknown> {
87
147
  * @template TVideoMeta - Provider-specific video metadata type
88
148
  * @template TDocumentMeta - Provider-specific document metadata type
89
149
  */
90
- export type ContentPart<TImageMeta = unknown, TAudioMeta = unknown, TVideoMeta = unknown, TDocumentMeta = unknown, TTextMeta = unknown> = TextPart<TTextMeta> | ImagePart<TImageMeta> | AudioPart<TAudioMeta> | VideoPart<TVideoMeta> | DocumentPart<TDocumentMeta>;
150
+ export type ContentPart<TTextMeta = unknown, TImageMeta = unknown, TAudioMeta = unknown, TVideoMeta = unknown, TDocumentMeta = unknown> = TextPart<TTextMeta> | ImagePart<TImageMeta> | AudioPart<TAudioMeta> | VideoPart<TVideoMeta> | DocumentPart<TDocumentMeta>;
91
151
  /**
92
152
  * Helper type to filter ContentPart union to only include specific modalities.
93
153
  * Used to constrain message content based on model capabilities.
94
154
  */
95
- export type ContentPartForModalities<TModalities extends Modality, TImageMeta = unknown, TAudioMeta = unknown, TVideoMeta = unknown, TDocumentMeta = unknown, TTextMeta = unknown> = Extract<ContentPart<TImageMeta, TAudioMeta, TVideoMeta, TDocumentMeta, TTextMeta>, {
96
- type: TModalities;
155
+ export type ContentPartForInputModalitiesTypes<TInputModalitiesTypes extends InputModalitiesTypes> = Extract<ContentPart<TInputModalitiesTypes['messageMetadataByModality']['text'], TInputModalitiesTypes['messageMetadataByModality']['image'], TInputModalitiesTypes['messageMetadataByModality']['audio'], TInputModalitiesTypes['messageMetadataByModality']['video'], TInputModalitiesTypes['messageMetadataByModality']['document']>, {
156
+ type: TInputModalitiesTypes['inputModalities'][number];
97
157
  }>;
98
158
  /**
99
159
  * Helper type to convert a readonly array of modalities to a union type.
@@ -104,7 +164,7 @@ export type ModalitiesArrayToUnion<T extends ReadonlyArray<Modality>> = T[number
104
164
  * Type for message content constrained by supported modalities.
105
165
  * When modalities is ['text', 'image'], only TextPart and ImagePart are allowed in the array.
106
166
  */
107
- export type ConstrainedContent<TModalities extends ReadonlyArray<Modality>, TImageMeta = unknown, TAudioMeta = unknown, TVideoMeta = unknown, TDocumentMeta = unknown, TTextMeta = unknown> = string | null | Array<ContentPartForModalities<ModalitiesArrayToUnion<TModalities>, TImageMeta, TAudioMeta, TVideoMeta, TDocumentMeta, TTextMeta>>;
167
+ export type ConstrainedContent<TInputModalitiesTypes extends InputModalitiesTypes> = string | null | Array<ContentPartForInputModalitiesTypes<TInputModalitiesTypes>>;
108
168
  export interface ModelMessage<TContent extends string | null | Array<ContentPart> = string | null | Array<ContentPart>> {
109
169
  role: 'user' | 'assistant' | 'tool';
110
170
  content: TContent;
@@ -157,12 +217,16 @@ export interface UIMessage {
157
217
  parts: Array<MessagePart>;
158
218
  createdAt?: Date;
159
219
  }
220
+ export type InputModalitiesTypes = {
221
+ inputModalities: ReadonlyArray<Modality>;
222
+ messageMetadataByModality: DefaultMessageMetadataByModality;
223
+ };
160
224
  /**
161
225
  * A ModelMessage with content constrained to only allow content parts
162
226
  * matching the specified input modalities.
163
227
  */
164
- export type ConstrainedModelMessage<TModalities extends ReadonlyArray<Modality>, TImageMeta = unknown, TAudioMeta = unknown, TVideoMeta = unknown, TDocumentMeta = unknown, TTextMeta = unknown> = Omit<ModelMessage, 'content'> & {
165
- content: ConstrainedContent<TModalities, TImageMeta, TAudioMeta, TVideoMeta, TDocumentMeta, TTextMeta>;
228
+ export type ConstrainedModelMessage<TInputModalitiesTypes extends InputModalitiesTypes> = Omit<ModelMessage, 'content'> & {
229
+ content: ConstrainedContent<TInputModalitiesTypes>;
166
230
  };
167
231
  /**
168
232
  * Tool/Function definition for function calling.
@@ -170,12 +234,12 @@ export type ConstrainedModelMessage<TModalities extends ReadonlyArray<Modality>,
170
234
  * Tools allow the model to interact with external systems, APIs, or perform computations.
171
235
  * The model will decide when to call tools based on the user's request and the tool descriptions.
172
236
  *
173
- * Tools use Zod schemas for runtime validation and type safety.
237
+ * Tools can use either Zod schemas or JSON Schema objects for runtime validation and type safety.
174
238
  *
175
239
  * @see https://platform.openai.com/docs/guides/function-calling
176
240
  * @see https://docs.anthropic.com/claude/docs/tool-use
177
241
  */
178
- export interface Tool<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType, TName extends string = string> {
242
+ export interface Tool<TInput extends SchemaInput = z.ZodType, TOutput extends SchemaInput = z.ZodType, TName extends string = string> {
179
243
  /**
180
244
  * Unique name of the tool (used by the model to call it).
181
245
  *
@@ -195,31 +259,46 @@ export interface Tool<TInput extends z.ZodType = z.ZodType, TOutput extends z.Zo
195
259
  */
196
260
  description: string;
197
261
  /**
198
- * Zod schema describing the tool's input parameters.
262
+ * Schema describing the tool's input parameters.
199
263
  *
264
+ * Can be either a Zod schema or a JSON Schema object.
200
265
  * Defines the structure and types of arguments the tool accepts.
201
266
  * The model will generate arguments matching this schema.
202
- * The schema is converted to JSON Schema for LLM providers.
267
+ * Zod schemas are converted to JSON Schema for LLM providers.
203
268
  *
204
269
  * @see https://zod.dev/
270
+ * @see https://json-schema.org/
205
271
  *
206
272
  * @example
273
+ * // Using Zod schema
207
274
  * import { z } from 'zod';
208
- *
209
275
  * z.object({
210
276
  * location: z.string().describe("City name or coordinates"),
211
277
  * unit: z.enum(["celsius", "fahrenheit"]).optional()
212
278
  * })
279
+ *
280
+ * @example
281
+ * // Using JSON Schema
282
+ * {
283
+ * type: 'object',
284
+ * properties: {
285
+ * location: { type: 'string', description: 'City name or coordinates' },
286
+ * unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
287
+ * },
288
+ * required: ['location']
289
+ * }
213
290
  */
214
291
  inputSchema?: TInput;
215
292
  /**
216
- * Optional Zod schema for validating tool output.
293
+ * Optional schema for validating tool output.
217
294
  *
218
- * If provided, tool results will be validated against this schema before
295
+ * Can be either a Zod schema or a JSON Schema object.
296
+ * If provided with a Zod schema, tool results will be validated against this schema before
219
297
  * being sent back to the model. This catches bugs in tool implementations
220
298
  * and ensures consistent output formatting.
221
299
  *
222
300
  * Note: This is client-side validation only - not sent to LLM providers.
301
+ * Note: JSON Schema output validation is not performed at runtime.
223
302
  *
224
303
  * @example
225
304
  * z.object({
@@ -368,16 +447,67 @@ export type AgentLoopStrategy = (state: AgentLoopState) => boolean;
368
447
  /**
369
448
  * Options passed into the SDK and further piped to the AI provider.
370
449
  */
371
- export interface ChatOptions<TModel extends string = string, TProviderOptionsSuperset extends Record<string, any> = Record<string, any>, TOutput extends ResponseFormat<any> | undefined = undefined, TProviderOptionsForModel = TProviderOptionsSuperset> {
372
- model: TModel;
450
+ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any> = Record<string, any>, TProviderOptionsForModel = TProviderOptionsSuperset> {
451
+ model: string;
373
452
  messages: Array<ModelMessage>;
374
- tools?: Array<Tool>;
453
+ tools?: Array<Tool<any, any, any>>;
375
454
  systemPrompts?: Array<string>;
376
455
  agentLoopStrategy?: AgentLoopStrategy;
377
- options?: CommonOptions;
378
- providerOptions?: TProviderOptionsForModel;
456
+ /**
457
+ * Controls the randomness of the output.
458
+ * Higher values (e.g., 0.8) make output more random, lower values (e.g., 0.2) make it more focused and deterministic.
459
+ * Range: [0.0, 2.0]
460
+ *
461
+ * Note: Generally recommended to use either temperature or topP, but not both.
462
+ *
463
+ * Provider usage:
464
+ * - OpenAI: `temperature` (number) - in text.top_p field
465
+ * - Anthropic: `temperature` (number) - ranges from 0.0 to 1.0, default 1.0
466
+ * - Gemini: `generationConfig.temperature` (number) - ranges from 0.0 to 2.0
467
+ */
468
+ temperature?: number;
469
+ /**
470
+ * Nucleus sampling parameter. An alternative to temperature sampling.
471
+ * The model considers the results of tokens with topP probability mass.
472
+ * For example, 0.1 means only tokens comprising the top 10% probability mass are considered.
473
+ *
474
+ * Note: Generally recommended to use either temperature or topP, but not both.
475
+ *
476
+ * Provider usage:
477
+ * - OpenAI: `text.top_p` (number)
478
+ * - Anthropic: `top_p` (number | null)
479
+ * - Gemini: `generationConfig.topP` (number)
480
+ */
481
+ topP?: number;
482
+ /**
483
+ * The maximum number of tokens to generate in the response.
484
+ *
485
+ * Provider usage:
486
+ * - OpenAI: `max_output_tokens` (number) - includes visible output and reasoning tokens
487
+ * - Anthropic: `max_tokens` (number, required) - range x >= 1
488
+ * - Gemini: `generationConfig.maxOutputTokens` (number)
489
+ */
490
+ maxTokens?: number;
491
+ /**
492
+ * Additional metadata to attach to the request.
493
+ * Can be used for tracking, debugging, or passing custom information.
494
+ * Structure and constraints vary by provider.
495
+ *
496
+ * Provider usage:
497
+ * - OpenAI: `metadata` (Record<string, string>) - max 16 key-value pairs, keys max 64 chars, values max 512 chars
498
+ * - Anthropic: `metadata` (Record<string, any>) - includes optional user_id (max 256 chars)
499
+ * - Gemini: Not directly available in TextProviderOptions
500
+ */
501
+ metadata?: Record<string, any>;
502
+ modelOptions?: TProviderOptionsForModel;
379
503
  request?: Request | RequestInit;
380
- output?: TOutput;
504
+ /**
505
+ * Zod schema for structured output.
506
+ * When provided, the adapter should use the provider's native structured output API
507
+ * to ensure the response conforms to this schema.
508
+ * The schema will be converted to JSON Schema format before being sent to the provider.
509
+ */
510
+ outputSchema?: z.ZodType;
381
511
  /**
382
512
  * Conversation ID for correlating client and server-side devtools events.
383
513
  * When provided, server-side events will be linked to the client conversation in devtools.
@@ -469,7 +599,7 @@ export interface ThinkingStreamChunk extends BaseStreamChunk {
469
599
  * Chunk returned by the sdk during streaming chat completions.
470
600
  */
471
601
  export type StreamChunk = ContentStreamChunk | ToolCallStreamChunk | ToolResultStreamChunk | DoneStreamChunk | ErrorStreamChunk | ApprovalRequestedStreamChunk | ToolInputAvailableStreamChunk | ThinkingStreamChunk;
472
- export interface ChatCompletionChunk {
602
+ export interface TextCompletionChunk {
473
603
  id: string;
474
604
  model: string;
475
605
  content: string;
@@ -498,20 +628,207 @@ export interface SummarizationResult {
498
628
  totalTokens: number;
499
629
  };
500
630
  }
501
- export interface EmbeddingOptions {
631
+ /**
632
+ * Options for image generation.
633
+ * These are the common options supported across providers.
634
+ */
635
+ export interface ImageGenerationOptions<TProviderOptions extends object = object> {
636
+ /** The model to use for image generation */
502
637
  model: string;
503
- input: string | Array<string>;
504
- dimensions?: number;
638
+ /** Text description of the desired image(s) */
639
+ prompt: string;
640
+ /** Number of images to generate (default: 1) */
641
+ numberOfImages?: number;
642
+ /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
643
+ size?: string;
644
+ /** Model-specific options for image generation */
645
+ modelOptions?: TProviderOptions;
505
646
  }
506
- export interface EmbeddingResult {
647
+ /**
648
+ * A single generated image
649
+ */
650
+ export interface GeneratedImage {
651
+ /** Base64-encoded image data */
652
+ b64Json?: string;
653
+ /** URL to the generated image (may be temporary) */
654
+ url?: string;
655
+ /** Revised prompt used by the model (if applicable) */
656
+ revisedPrompt?: string;
657
+ }
658
+ /**
659
+ * Result of image generation
660
+ */
661
+ export interface ImageGenerationResult {
662
+ /** Unique identifier for the generation */
507
663
  id: string;
664
+ /** Model used for generation */
508
665
  model: string;
509
- embeddings: Array<Array<number>>;
510
- usage: {
511
- promptTokens: number;
512
- totalTokens: number;
666
+ /** Array of generated images */
667
+ images: Array<GeneratedImage>;
668
+ /** Token usage information (if available) */
669
+ usage?: {
670
+ inputTokens?: number;
671
+ outputTokens?: number;
672
+ totalTokens?: number;
513
673
  };
514
674
  }
675
+ /**
676
+ * Options for video generation.
677
+ * These are the common options supported across providers.
678
+ *
679
+ * @experimental Video generation is an experimental feature and may change.
680
+ */
681
+ export interface VideoGenerationOptions<TProviderOptions extends object = object> {
682
+ /** The model to use for video generation */
683
+ model: string;
684
+ /** Text description of the desired video */
685
+ prompt: string;
686
+ /** Video size in WIDTHxHEIGHT format (e.g., "1280x720") */
687
+ size?: string;
688
+ /** Video duration in seconds */
689
+ duration?: number;
690
+ /** Model-specific options for video generation */
691
+ modelOptions?: TProviderOptions;
692
+ }
693
+ /**
694
+ * Result of creating a video generation job.
695
+ *
696
+ * @experimental Video generation is an experimental feature and may change.
697
+ */
698
+ export interface VideoJobResult {
699
+ /** Unique job identifier for polling status */
700
+ jobId: string;
701
+ /** Model used for generation */
702
+ model: string;
703
+ }
704
+ /**
705
+ * Status of a video generation job.
706
+ *
707
+ * @experimental Video generation is an experimental feature and may change.
708
+ */
709
+ export interface VideoStatusResult {
710
+ /** Job identifier */
711
+ jobId: string;
712
+ /** Current status of the job */
713
+ status: 'pending' | 'processing' | 'completed' | 'failed';
714
+ /** Progress percentage (0-100), if available */
715
+ progress?: number;
716
+ /** Error message if status is 'failed' */
717
+ error?: string;
718
+ }
719
+ /**
720
+ * Result containing the URL to a generated video.
721
+ *
722
+ * @experimental Video generation is an experimental feature and may change.
723
+ */
724
+ export interface VideoUrlResult {
725
+ /** Job identifier */
726
+ jobId: string;
727
+ /** URL to the generated video */
728
+ url: string;
729
+ /** When the URL expires, if applicable */
730
+ expiresAt?: Date;
731
+ }
732
+ /**
733
+ * Options for text-to-speech generation.
734
+ * These are the common options supported across providers.
735
+ */
736
+ export interface TTSOptions<TProviderOptions extends object = object> {
737
+ /** The model to use for TTS generation */
738
+ model: string;
739
+ /** The text to convert to speech */
740
+ text: string;
741
+ /** The voice to use for generation */
742
+ voice?: string;
743
+ /** The output audio format */
744
+ format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm';
745
+ /** The speed of the generated audio (0.25 to 4.0) */
746
+ speed?: number;
747
+ /** Model-specific options for TTS generation */
748
+ modelOptions?: TProviderOptions;
749
+ }
750
+ /**
751
+ * Result of text-to-speech generation.
752
+ */
753
+ export interface TTSResult {
754
+ /** Unique identifier for the generation */
755
+ id: string;
756
+ /** Model used for generation */
757
+ model: string;
758
+ /** Base64-encoded audio data */
759
+ audio: string;
760
+ /** Audio format of the generated audio */
761
+ format: string;
762
+ /** Duration of the audio in seconds, if available */
763
+ duration?: number;
764
+ /** Content type of the audio (e.g., 'audio/mp3') */
765
+ contentType?: string;
766
+ }
767
+ /**
768
+ * Options for audio transcription.
769
+ * These are the common options supported across providers.
770
+ */
771
+ export interface TranscriptionOptions<TProviderOptions extends object = object> {
772
+ /** The model to use for transcription */
773
+ model: string;
774
+ /** The audio data to transcribe - can be base64 string, File, Blob, or Buffer */
775
+ audio: string | File | Blob | ArrayBuffer;
776
+ /** The language of the audio in ISO-639-1 format (e.g., 'en') */
777
+ language?: string;
778
+ /** An optional prompt to guide the transcription */
779
+ prompt?: string;
780
+ /** The format of the transcription output */
781
+ responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
782
+ /** Model-specific options for transcription */
783
+ modelOptions?: TProviderOptions;
784
+ }
785
+ /**
786
+ * A single segment of transcribed audio with timing information.
787
+ */
788
+ export interface TranscriptionSegment {
789
+ /** Unique identifier for the segment */
790
+ id: number;
791
+ /** Start time of the segment in seconds */
792
+ start: number;
793
+ /** End time of the segment in seconds */
794
+ end: number;
795
+ /** Transcribed text for this segment */
796
+ text: string;
797
+ /** Confidence score (0-1), if available */
798
+ confidence?: number;
799
+ /** Speaker identifier, if diarization is enabled */
800
+ speaker?: string;
801
+ }
802
+ /**
803
+ * A single word with timing information.
804
+ */
805
+ export interface TranscriptionWord {
806
+ /** The transcribed word */
807
+ word: string;
808
+ /** Start time in seconds */
809
+ start: number;
810
+ /** End time in seconds */
811
+ end: number;
812
+ }
813
+ /**
814
+ * Result of audio transcription.
815
+ */
816
+ export interface TranscriptionResult {
817
+ /** Unique identifier for the transcription */
818
+ id: string;
819
+ /** Model used for transcription */
820
+ model: string;
821
+ /** The full transcribed text */
822
+ text: string;
823
+ /** Language detected or specified */
824
+ language?: string;
825
+ /** Duration of the audio in seconds */
826
+ duration?: number;
827
+ /** Detailed segments with timing, if available */
828
+ segments?: Array<TranscriptionSegment>;
829
+ /** Word-level timestamps, if available */
830
+ words?: Array<TranscriptionWord>;
831
+ }
515
832
  /**
516
833
  * Default metadata type for adapters that don't define custom metadata.
517
834
  * Uses unknown for all modalities.
@@ -523,102 +840,3 @@ export interface DefaultMessageMetadataByModality {
523
840
  video: unknown;
524
841
  document: unknown;
525
842
  }
526
- /**
527
- * AI adapter interface with support for endpoint-specific models and provider options.
528
- *
529
- * Generic parameters:
530
- * - TChatModels: Models that support chat/text completion
531
- * - TEmbeddingModels: Models that support embeddings
532
- * - TChatProviderOptions: Provider-specific options for chat endpoint
533
- * - TEmbeddingProviderOptions: Provider-specific options for embedding endpoint
534
- * - TModelProviderOptionsByName: Map from model name to its specific provider options
535
- * - TModelInputModalitiesByName: Map from model name to its supported input modalities
536
- * - TMessageMetadataByModality: Map from modality type to adapter-specific metadata types
537
- */
538
- export interface AIAdapter<TChatModels extends ReadonlyArray<string> = ReadonlyArray<string>, TEmbeddingModels extends ReadonlyArray<string> = ReadonlyArray<string>, TChatProviderOptions extends Record<string, any> = Record<string, any>, TEmbeddingProviderOptions extends Record<string, any> = Record<string, any>, TModelProviderOptionsByName extends Record<string, any> = Record<string, any>, TModelInputModalitiesByName extends Record<string, ReadonlyArray<Modality>> = Record<string, ReadonlyArray<Modality>>, TMessageMetadataByModality extends {
539
- text: unknown;
540
- image: unknown;
541
- audio: unknown;
542
- video: unknown;
543
- document: unknown;
544
- } = DefaultMessageMetadataByModality> {
545
- name: string;
546
- /** Models that support chat/text completion */
547
- models: TChatModels;
548
- /** Models that support embeddings */
549
- embeddingModels?: TEmbeddingModels;
550
- _providerOptions?: TChatProviderOptions;
551
- _chatProviderOptions?: TChatProviderOptions;
552
- _embeddingProviderOptions?: TEmbeddingProviderOptions;
553
- /**
554
- * Type-only map from model name to its specific provider options.
555
- * Used by the core AI types to narrow providerOptions based on the selected model.
556
- * Must be provided by all adapters.
557
- */
558
- _modelProviderOptionsByName: TModelProviderOptionsByName;
559
- /**
560
- * Type-only map from model name to its supported input modalities.
561
- * Used by the core AI types to narrow ContentPart types based on the selected model.
562
- * Must be provided by all adapters.
563
- */
564
- _modelInputModalitiesByName?: TModelInputModalitiesByName;
565
- /**
566
- * Type-only map from modality type to adapter-specific metadata types.
567
- * Used to provide type-safe autocomplete for metadata on content parts.
568
- */
569
- _messageMetadataByModality?: TMessageMetadataByModality;
570
- chatStream: (options: ChatOptions<string, TChatProviderOptions>) => AsyncIterable<StreamChunk>;
571
- summarize: (options: SummarizationOptions) => Promise<SummarizationResult>;
572
- createEmbeddings: (options: EmbeddingOptions) => Promise<EmbeddingResult>;
573
- }
574
- export interface AIAdapterConfig {
575
- apiKey?: string;
576
- baseUrl?: string;
577
- timeout?: number;
578
- maxRetries?: number;
579
- headers?: Record<string, string>;
580
- }
581
- export type ChatStreamOptionsUnion<TAdapter extends AIAdapter<any, any, any, any, any, any, any>> = TAdapter extends AIAdapter<infer Models, any, any, any, infer ModelProviderOptions, infer ModelInputModalities, infer MessageMetadata> ? Models[number] extends infer TModel ? TModel extends string ? Omit<ChatOptions, 'model' | 'providerOptions' | 'responseFormat' | 'messages'> & {
582
- adapter: TAdapter;
583
- model: TModel;
584
- providerOptions?: TModel extends keyof ModelProviderOptions ? ModelProviderOptions[TModel] : never;
585
- /**
586
- * Messages array with content constrained to the model's supported input modalities.
587
- * For example, if a model only supports ['text', 'image'], you cannot pass audio or video content.
588
- * Metadata types are also constrained based on the adapter's metadata type definitions.
589
- */
590
- messages: TModel extends keyof ModelInputModalities ? ModelInputModalities[TModel] extends ReadonlyArray<Modality> ? MessageMetadata extends {
591
- text: infer TTextMeta;
592
- image: infer TImageMeta;
593
- audio: infer TAudioMeta;
594
- video: infer TVideoMeta;
595
- document: infer TDocumentMeta;
596
- } ? Array<ConstrainedModelMessage<ModelInputModalities[TModel], TImageMeta, TAudioMeta, TVideoMeta, TDocumentMeta, TTextMeta>> : Array<ConstrainedModelMessage<ModelInputModalities[TModel]>> : Array<ModelMessage> : Array<ModelMessage>;
597
- } : never : never : never;
598
- /**
599
- * Chat options constrained by a specific model's capabilities.
600
- * Unlike ChatStreamOptionsUnion which creates a union over all models,
601
- * this type takes a specific model and constrains messages accordingly.
602
- */
603
- export type ChatStreamOptionsForModel<TAdapter extends AIAdapter<any, any, any, any, any, any, any>, TModel extends string> = TAdapter extends AIAdapter<any, any, any, any, infer ModelProviderOptions, infer ModelInputModalities, infer MessageMetadata> ? Omit<ChatOptions, 'model' | 'providerOptions' | 'responseFormat' | 'messages'> & {
604
- adapter: TAdapter;
605
- model: TModel;
606
- providerOptions?: TModel extends keyof ModelProviderOptions ? ModelProviderOptions[TModel] : never;
607
- /**
608
- * Messages array with content constrained to the model's supported input modalities.
609
- * For example, if a model only supports ['text', 'image'], you cannot pass audio or video content.
610
- * Metadata types are also constrained based on the adapter's metadata type definitions.
611
- */
612
- messages: TModel extends keyof ModelInputModalities ? ModelInputModalities[TModel] extends ReadonlyArray<Modality> ? MessageMetadata extends {
613
- text: infer TTextMeta;
614
- image: infer TImageMeta;
615
- audio: infer TAudioMeta;
616
- video: infer TVideoMeta;
617
- document: infer TDocumentMeta;
618
- } ? Array<ConstrainedModelMessage<ModelInputModalities[TModel], TImageMeta, TAudioMeta, TVideoMeta, TDocumentMeta, TTextMeta>> : Array<ConstrainedModelMessage<ModelInputModalities[TModel]>> : Array<ModelMessage> : Array<ModelMessage>;
619
- } : never;
620
- export type ExtractModelsFromAdapter<T> = T extends AIAdapter<infer M, any, any, any, any, any> ? M[number] : never;
621
- /**
622
- * Extract the supported input modalities for a specific model from an adapter.
623
- */
624
- export type ExtractModalitiesForModel<TAdapter extends AIAdapter<any, any, any, any, any, any>, TModel extends string> = TAdapter extends AIAdapter<any, any, any, any, any, infer ModelInputModalities> ? TModel extends keyof ModelInputModalities ? ModelInputModalities[TModel] : ReadonlyArray<Modality> : ReadonlyArray<Modality>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tanstack/ai",
3
- "version": "0.0.3",
3
+ "version": "0.1.0",
4
4
  "description": "Core TanStack AI library - Open source AI SDK",
5
5
  "author": "Tanner Linsley",
6
6
  "license": "MIT",
@@ -17,6 +17,10 @@
17
17
  "types": "./dist/esm/index.d.ts",
18
18
  "import": "./dist/esm/index.js"
19
19
  },
20
+ "./adapters": {
21
+ "types": "./dist/esm/activities/index.d.ts",
22
+ "import": "./dist/esm/activities/index.js"
23
+ },
20
24
  "./event-client": {
21
25
  "types": "./dist/esm/event-client.d.ts",
22
26
  "import": "./dist/esm/event-client.js"