@tanstack/ai-mistral 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 (38) hide show
  1. package/README.md +93 -0
  2. package/dist/esm/adapters/text.d.ts +106 -0
  3. package/dist/esm/adapters/text.js +741 -0
  4. package/dist/esm/adapters/text.js.map +1 -0
  5. package/dist/esm/index.d.ts +10 -0
  6. package/dist/esm/index.js +9 -0
  7. package/dist/esm/index.js.map +1 -0
  8. package/dist/esm/message-types.d.ts +155 -0
  9. package/dist/esm/model-meta.d.ts +263 -0
  10. package/dist/esm/model-meta.js +50 -0
  11. package/dist/esm/model-meta.js.map +1 -0
  12. package/dist/esm/text/text-provider-options.d.ts +80 -0
  13. package/dist/esm/tools/function-tool.d.ts +13 -0
  14. package/dist/esm/tools/function-tool.js +26 -0
  15. package/dist/esm/tools/function-tool.js.map +1 -0
  16. package/dist/esm/tools/index.d.ts +2 -0
  17. package/dist/esm/tools/tool-converter.d.ts +6 -0
  18. package/dist/esm/tools/tool-converter.js +10 -0
  19. package/dist/esm/tools/tool-converter.js.map +1 -0
  20. package/dist/esm/utils/client.d.ts +24 -0
  21. package/dist/esm/utils/client.js +44 -0
  22. package/dist/esm/utils/client.js.map +1 -0
  23. package/dist/esm/utils/index.d.ts +2 -0
  24. package/dist/esm/utils/schema-converter.d.ts +18 -0
  25. package/dist/esm/utils/schema-converter.js +93 -0
  26. package/dist/esm/utils/schema-converter.js.map +1 -0
  27. package/package.json +60 -0
  28. package/src/adapters/text.ts +1141 -0
  29. package/src/index.ts +33 -0
  30. package/src/message-types.ts +194 -0
  31. package/src/model-meta.ts +285 -0
  32. package/src/text/text-provider-options.ts +103 -0
  33. package/src/tools/function-tool.ts +42 -0
  34. package/src/tools/index.ts +5 -0
  35. package/src/tools/tool-converter.ts +14 -0
  36. package/src/utils/client.ts +70 -0
  37. package/src/utils/index.ts +10 -0
  38. package/src/utils/schema-converter.ts +136 -0
@@ -0,0 +1,1141 @@
1
+ import { BaseTextAdapter } from '@tanstack/ai/adapters'
2
+ import { convertToolsToProviderFormat } from '../tools'
3
+ import {
4
+ createMistralClient,
5
+ generateId,
6
+ getMistralApiKeyFromEnv,
7
+ makeMistralStructuredOutputCompatible,
8
+ transformNullsToUndefined,
9
+ } from '../utils'
10
+ import type {
11
+ ContentPart,
12
+ Modality,
13
+ ModelMessage,
14
+ StreamChunk,
15
+ TextOptions,
16
+ } from '@tanstack/ai'
17
+ import type {
18
+ MISTRAL_CHAT_MODELS,
19
+ MistralChatModelProviderOptionsByName,
20
+ MistralModelInputModalitiesByName,
21
+ } from '../model-meta'
22
+ import type {
23
+ StructuredOutputOptions,
24
+ StructuredOutputResult,
25
+ } from '@tanstack/ai/adapters'
26
+ import type { Mistral } from '@mistralai/mistralai'
27
+ import type { ChatCompletionStreamRequest } from '@mistralai/mistralai/models/components'
28
+ import type {
29
+ ExternalTextProviderOptions,
30
+ InternalTextProviderOptions,
31
+ } from '../text/text-provider-options'
32
+ import type {
33
+ ChatCompletionContentPart,
34
+ ChatCompletionMessageParam,
35
+ MistralImageMetadata,
36
+ MistralMessageMetadataByModality,
37
+ } from '../message-types'
38
+ import type { MistralClientConfig } from '../utils'
39
+
40
+ /** Cast an event object to StreamChunk. Adapters construct events with string
41
+ * literal types which are structurally compatible with the EventType enum. */
42
+ const asChunk = (chunk: Record<string, unknown>) =>
43
+ // eslint-disable-next-line no-restricted-syntax -- Record<string, unknown> doesn't structurally overlap the StreamChunk discriminated union; events are built with literal `type` fields the union accepts at runtime
44
+ chunk as unknown as StreamChunk
45
+
46
+ /**
47
+ * Parse the accumulated streaming arguments for a tool call. Throws a clear
48
+ * error if the JSON is malformed — silently substituting `{}` would let a
49
+ * tool fire with empty inputs, masking truncated streams or mis-shaped output.
50
+ */
51
+ function parseToolCallInput(toolCall: {
52
+ id: string
53
+ name: string
54
+ arguments: string
55
+ }): unknown {
56
+ if (!toolCall.arguments) return {}
57
+ try {
58
+ return transformNullsToUndefined(JSON.parse(toolCall.arguments))
59
+ } catch (cause) {
60
+ const preview = toolCall.arguments.slice(0, 200)
61
+ const ellipsis = toolCall.arguments.length > 200 ? '...' : ''
62
+ throw new Error(
63
+ `Failed to parse tool call arguments for tool '${toolCall.name}' (id: ${toolCall.id}). Arguments: ${preview}${ellipsis}`,
64
+ { cause },
65
+ )
66
+ }
67
+ }
68
+
69
+ /**
70
+ * Configuration for Mistral text adapter.
71
+ */
72
+ export type MistralTextConfig = MistralClientConfig
73
+
74
+ /**
75
+ * Alias for TextProviderOptions for external use.
76
+ */
77
+ export type MistralTextProviderOptions = ExternalTextProviderOptions
78
+
79
+ // ===========================
80
+ // Type Resolution Helpers
81
+ // ===========================
82
+
83
+ type ResolveProviderOptions<TModel extends string> =
84
+ TModel extends keyof MistralChatModelProviderOptionsByName
85
+ ? MistralChatModelProviderOptionsByName[TModel]
86
+ : MistralTextProviderOptions
87
+
88
+ type ResolveInputModalities<TModel extends string> =
89
+ TModel extends keyof MistralModelInputModalitiesByName
90
+ ? MistralModelInputModalitiesByName[TModel]
91
+ : readonly ['text']
92
+
93
+ // ===========================
94
+ // Wire-format chunk types
95
+ // ===========================
96
+
97
+ /**
98
+ * Snake-case shape of a Mistral chat completion stream chunk as returned on the
99
+ * wire. We bypass the SDK's `chat.stream` because its Zod validation rejects
100
+ * tool-call argument deltas that omit `function.name` (only the first chunk in
101
+ * a tool call carries the name).
102
+ */
103
+ interface MistralRawToolCall {
104
+ id?: string
105
+ type?: string
106
+ index?: number
107
+ function?: {
108
+ name?: string
109
+ arguments?: string | Record<string, unknown>
110
+ }
111
+ }
112
+
113
+ interface MistralRawChoice {
114
+ index?: number
115
+ delta?: {
116
+ role?: string | null
117
+ content?:
118
+ | string
119
+ | Array<{
120
+ type: string
121
+ text?: string
122
+ // Mistral magistral models stream reasoning as content parts of
123
+ // type 'thinking' whose `thinking` field is itself an array of
124
+ // text/reference chunks. See Mistral SDK ThinkChunk type.
125
+ thinking?: Array<{ type: string; text?: string }>
126
+ }>
127
+ | null
128
+ // Some OpenAI-compatible deployments (DeepSeek, Groq for reasoning
129
+ // models, and aimock-based test environments) emit reasoning via a
130
+ // separate `reasoning_content` delta field rather than as a content
131
+ // part. Accept both shapes — they cannot collide because real Mistral
132
+ // never sets the OpenAI-compat field, and aimock never sets the
133
+ // thinking content part.
134
+ reasoning_content?: string | null
135
+ tool_calls?: Array<MistralRawToolCall>
136
+ }
137
+ finish_reason?: string | null
138
+ }
139
+
140
+ interface MistralRawChunk {
141
+ id?: string
142
+ model?: string
143
+ choices?: Array<MistralRawChoice>
144
+ usage?: {
145
+ prompt_tokens?: number
146
+ completion_tokens?: number
147
+ total_tokens?: number
148
+ }
149
+ }
150
+
151
+ // ===========================
152
+ // Adapter Implementation
153
+ // ===========================
154
+
155
+ /**
156
+ * Mistral Text (Chat) Adapter.
157
+ *
158
+ * Tree-shakeable adapter for Mistral chat/text completion functionality.
159
+ */
160
+ export class MistralTextAdapter<
161
+ TModel extends (typeof MISTRAL_CHAT_MODELS)[number],
162
+ TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,
163
+ TInputModalities extends ReadonlyArray<Modality> =
164
+ ResolveInputModalities<TModel>,
165
+ > extends BaseTextAdapter<
166
+ TModel,
167
+ TProviderOptions,
168
+ TInputModalities,
169
+ MistralMessageMetadataByModality
170
+ > {
171
+ readonly name = 'mistral' as const
172
+
173
+ private readonly client: Mistral
174
+ private readonly rawConfig: MistralClientConfig
175
+
176
+ constructor(config: MistralTextConfig, model: TModel) {
177
+ super(config, model)
178
+ // The SDK client is retained for `structuredOutput` (non-streaming). The
179
+ // streaming path bypasses the SDK and uses `fetchRawMistralStream` because
180
+ // the SDK's Zod schemas reject partial tool-call argument deltas.
181
+ this.client = createMistralClient(config)
182
+ this.rawConfig = config
183
+ }
184
+
185
+ async *chatStream(
186
+ options: TextOptions<TProviderOptions>,
187
+ ): AsyncIterable<StreamChunk> {
188
+ const requestParams = this.mapTextOptionsToMistral(options)
189
+ const timestamp = Date.now()
190
+
191
+ const aguiState = {
192
+ runId: options.runId ?? generateId(this.name),
193
+ threadId: options.threadId ?? generateId(this.name),
194
+ messageId: generateId(this.name),
195
+ timestamp,
196
+ hasEmittedRunStarted: false,
197
+ }
198
+
199
+ try {
200
+ const stream = this.fetchRawMistralStream(requestParams, this.rawConfig)
201
+ yield* this.processMistralStreamChunks(stream, options, aguiState)
202
+ } catch (error: unknown) {
203
+ const err = error as Error & { code?: string }
204
+
205
+ if (!aguiState.hasEmittedRunStarted) {
206
+ aguiState.hasEmittedRunStarted = true
207
+ yield asChunk({
208
+ type: 'RUN_STARTED',
209
+ runId: aguiState.runId,
210
+ threadId: aguiState.threadId,
211
+ model: options.model,
212
+ timestamp,
213
+ })
214
+ }
215
+
216
+ yield asChunk({
217
+ type: 'RUN_ERROR',
218
+ runId: aguiState.runId,
219
+ model: options.model,
220
+ timestamp,
221
+ message: err.message || 'Unknown error',
222
+ code: err.code,
223
+ error: {
224
+ message: err.message || 'Unknown error',
225
+ code: err.code,
226
+ },
227
+ })
228
+
229
+ throw err
230
+ }
231
+ }
232
+
233
+ /**
234
+ * Generate structured output using Mistral's JSON Schema response format.
235
+ */
236
+ async structuredOutput(
237
+ options: StructuredOutputOptions<TProviderOptions>,
238
+ ): Promise<StructuredOutputResult<unknown>> {
239
+ const { chatOptions, outputSchema } = options
240
+ const { stream: _stream, ...nonStreamParams } =
241
+ this.mapTextOptionsToMistral(chatOptions)
242
+
243
+ const jsonSchema = makeMistralStructuredOutputCompatible(
244
+ outputSchema,
245
+ outputSchema.required || [],
246
+ )
247
+
248
+ const response = await this.client.chat.complete({
249
+ ...nonStreamParams,
250
+ responseFormat: {
251
+ type: 'json_schema',
252
+ jsonSchema: {
253
+ name: 'structured_output',
254
+ schemaDefinition: jsonSchema,
255
+ strict: true,
256
+ },
257
+ },
258
+ })
259
+
260
+ const rawText = response.choices[0]?.message?.content
261
+ const textContent = typeof rawText === 'string' ? rawText : ''
262
+
263
+ let parsed: unknown
264
+ try {
265
+ parsed = JSON.parse(textContent)
266
+ } catch {
267
+ throw new Error(
268
+ `Failed to parse structured output as JSON. Content: ${textContent.slice(0, 200)}${textContent.length > 200 ? '...' : ''}`,
269
+ )
270
+ }
271
+
272
+ return {
273
+ data: transformNullsToUndefined(parsed),
274
+ rawText: textContent,
275
+ }
276
+ }
277
+
278
+ /**
279
+ * Processes streaming chunks from the Mistral API and yields AG-UI stream events.
280
+ */
281
+ private async *processMistralStreamChunks(
282
+ stream: AsyncIterable<MistralRawChunk>,
283
+ options: TextOptions,
284
+ aguiState: {
285
+ runId: string
286
+ threadId: string
287
+ messageId: string
288
+ timestamp: number
289
+ hasEmittedRunStarted: boolean
290
+ },
291
+ ): AsyncIterable<StreamChunk> {
292
+ let accumulatedContent = ''
293
+ const timestamp = aguiState.timestamp
294
+ let hasEmittedTextMessageStart = false
295
+ let hasEmittedTextMessageEnd = false
296
+ let hasEmittedToolCall = false
297
+ let hasEmittedRunFinished = false
298
+ let lastChunkModel = options.model
299
+
300
+ // Reasoning lifecycle (magistral-* models stream `thinking` content
301
+ // parts before any text). Mirrors the anthropic adapter's pattern:
302
+ // open REASONING_* events on the first thinking delta, close them when
303
+ // text/tool content begins or the run finishes.
304
+ let reasoningMessageId: string | null = null
305
+ let hasClosedReasoning = false
306
+
307
+ const toolCallsInProgress = new Map<
308
+ number,
309
+ {
310
+ id: string
311
+ name: string
312
+ arguments: string
313
+ started: boolean
314
+ ended: boolean
315
+ }
316
+ >()
317
+
318
+ try {
319
+ for await (const chunk of stream) {
320
+ lastChunkModel = chunk.model || options.model
321
+ const choice = chunk.choices?.[0]
322
+ if (!choice) continue
323
+
324
+ const chunkModel = chunk.model || options.model
325
+
326
+ if (!aguiState.hasEmittedRunStarted) {
327
+ aguiState.hasEmittedRunStarted = true
328
+ yield asChunk({
329
+ type: 'RUN_STARTED',
330
+ runId: aguiState.runId,
331
+ threadId: aguiState.threadId,
332
+ model: chunkModel,
333
+ timestamp,
334
+ })
335
+ }
336
+
337
+ const delta = choice.delta
338
+ const { text: deltaContent, thinking: deltaThinkingFromContent } =
339
+ this.extractDeltaParts(delta?.content)
340
+ // Reasoning may also arrive as a separate top-level field
341
+ // (`delta.reasoning_content`) on OpenAI-compatible deployments.
342
+ const deltaThinking =
343
+ deltaThinkingFromContent +
344
+ (typeof delta?.reasoning_content === 'string'
345
+ ? delta.reasoning_content
346
+ : '')
347
+ const deltaToolCalls = delta?.tool_calls
348
+
349
+ // Emit reasoning events FIRST so they always precede the matching
350
+ // text or tool deltas in the same chunk.
351
+ if (deltaThinking) {
352
+ if (reasoningMessageId === null) {
353
+ reasoningMessageId = generateId(this.name)
354
+ yield asChunk({
355
+ type: 'REASONING_START',
356
+ messageId: reasoningMessageId,
357
+ model: chunkModel,
358
+ timestamp,
359
+ })
360
+ yield asChunk({
361
+ type: 'REASONING_MESSAGE_START',
362
+ messageId: reasoningMessageId,
363
+ role: 'reasoning',
364
+ model: chunkModel,
365
+ timestamp,
366
+ })
367
+ }
368
+ yield asChunk({
369
+ type: 'REASONING_MESSAGE_CONTENT',
370
+ messageId: reasoningMessageId,
371
+ model: chunkModel,
372
+ timestamp,
373
+ delta: deltaThinking,
374
+ })
375
+ }
376
+
377
+ // Close reasoning before any text/tool output starts in this chunk.
378
+ const aboutToEmitOutput =
379
+ !!deltaContent || (!!deltaToolCalls && deltaToolCalls.length > 0)
380
+ if (
381
+ reasoningMessageId !== null &&
382
+ !hasClosedReasoning &&
383
+ aboutToEmitOutput
384
+ ) {
385
+ hasClosedReasoning = true
386
+ yield asChunk({
387
+ type: 'REASONING_MESSAGE_END',
388
+ messageId: reasoningMessageId,
389
+ model: chunkModel,
390
+ timestamp,
391
+ })
392
+ yield asChunk({
393
+ type: 'REASONING_END',
394
+ messageId: reasoningMessageId,
395
+ model: chunkModel,
396
+ timestamp,
397
+ })
398
+ }
399
+
400
+ if (deltaContent) {
401
+ if (!hasEmittedTextMessageStart) {
402
+ hasEmittedTextMessageStart = true
403
+ yield asChunk({
404
+ type: 'TEXT_MESSAGE_START',
405
+ messageId: aguiState.messageId,
406
+ model: chunkModel,
407
+ timestamp,
408
+ role: 'assistant',
409
+ })
410
+ }
411
+
412
+ accumulatedContent += deltaContent
413
+
414
+ yield asChunk({
415
+ type: 'TEXT_MESSAGE_CONTENT',
416
+ messageId: aguiState.messageId,
417
+ model: chunkModel,
418
+ timestamp,
419
+ delta: deltaContent,
420
+ content: accumulatedContent,
421
+ })
422
+ }
423
+
424
+ if (deltaToolCalls) {
425
+ for (const [i, toolCallDelta] of deltaToolCalls.entries()) {
426
+ const index = toolCallDelta.index ?? i
427
+
428
+ let toolCall = toolCallsInProgress.get(index)
429
+ if (!toolCall) {
430
+ toolCall = {
431
+ id: toolCallDelta.id || '',
432
+ name: toolCallDelta.function?.name || '',
433
+ arguments: '',
434
+ started: false,
435
+ ended: false,
436
+ }
437
+ toolCallsInProgress.set(index, toolCall)
438
+ }
439
+
440
+ if (toolCallDelta.id) toolCall.id = toolCallDelta.id
441
+ if (toolCallDelta.function?.name) {
442
+ toolCall.name = toolCallDelta.function.name
443
+ }
444
+
445
+ const rawArgs = toolCallDelta.function?.arguments
446
+ const argsDelta =
447
+ rawArgs === undefined
448
+ ? undefined
449
+ : typeof rawArgs === 'string'
450
+ ? rawArgs
451
+ : JSON.stringify(rawArgs)
452
+
453
+ if (argsDelta !== undefined) {
454
+ toolCall.arguments += argsDelta
455
+ }
456
+
457
+ const justStarted =
458
+ !!toolCall.id && !!toolCall.name && !toolCall.started
459
+ if (justStarted) {
460
+ toolCall.started = true
461
+ yield asChunk({
462
+ type: 'TOOL_CALL_START',
463
+ toolCallId: toolCall.id,
464
+ toolCallName: toolCall.name,
465
+ toolName: toolCall.name,
466
+ model: chunkModel,
467
+ timestamp,
468
+ index,
469
+ })
470
+ // Replay any args buffered before id+name arrived (including
471
+ // this chunk's argsDelta, if any).
472
+ if (toolCall.arguments.length > 0) {
473
+ yield asChunk({
474
+ type: 'TOOL_CALL_ARGS',
475
+ toolCallId: toolCall.id,
476
+ model: chunkModel,
477
+ timestamp,
478
+ delta: toolCall.arguments,
479
+ })
480
+ }
481
+ } else if (argsDelta !== undefined && toolCall.started) {
482
+ yield asChunk({
483
+ type: 'TOOL_CALL_ARGS',
484
+ toolCallId: toolCall.id,
485
+ model: chunkModel,
486
+ timestamp,
487
+ delta: argsDelta,
488
+ })
489
+ }
490
+ }
491
+ }
492
+
493
+ const finishReason = choice.finish_reason
494
+ if (finishReason) {
495
+ if (finishReason === 'tool_calls' || toolCallsInProgress.size > 0) {
496
+ for (const [, toolCall] of toolCallsInProgress) {
497
+ if (
498
+ !toolCall.started ||
499
+ !toolCall.id ||
500
+ !toolCall.name ||
501
+ toolCall.ended
502
+ ) {
503
+ continue
504
+ }
505
+
506
+ const parsedInput = parseToolCallInput(toolCall)
507
+
508
+ toolCall.ended = true
509
+ hasEmittedToolCall = true
510
+ yield asChunk({
511
+ type: 'TOOL_CALL_END',
512
+ toolCallId: toolCall.id,
513
+ toolCallName: toolCall.name,
514
+ toolName: toolCall.name,
515
+ model: chunkModel,
516
+ timestamp,
517
+ input: parsedInput,
518
+ })
519
+ }
520
+ }
521
+
522
+ const computedFinishReason =
523
+ finishReason === 'tool_calls' || hasEmittedToolCall
524
+ ? 'tool_calls'
525
+ : finishReason === 'length'
526
+ ? 'length'
527
+ : 'stop'
528
+
529
+ // If the run finished while reasoning was still open (no text or
530
+ // tool output ever followed), close reasoning before TEXT/RUN
531
+ // finalization events.
532
+ if (reasoningMessageId !== null && !hasClosedReasoning) {
533
+ hasClosedReasoning = true
534
+ yield asChunk({
535
+ type: 'REASONING_MESSAGE_END',
536
+ messageId: reasoningMessageId,
537
+ model: chunkModel,
538
+ timestamp,
539
+ })
540
+ yield asChunk({
541
+ type: 'REASONING_END',
542
+ messageId: reasoningMessageId,
543
+ model: chunkModel,
544
+ timestamp,
545
+ })
546
+ }
547
+
548
+ if (hasEmittedTextMessageStart && !hasEmittedTextMessageEnd) {
549
+ hasEmittedTextMessageEnd = true
550
+ yield asChunk({
551
+ type: 'TEXT_MESSAGE_END',
552
+ messageId: aguiState.messageId,
553
+ model: chunkModel,
554
+ timestamp,
555
+ })
556
+ }
557
+
558
+ const usage = chunk.usage
559
+ hasEmittedRunFinished = true
560
+ yield asChunk({
561
+ type: 'RUN_FINISHED',
562
+ runId: aguiState.runId,
563
+ threadId: aguiState.threadId,
564
+ model: chunkModel,
565
+ timestamp,
566
+ usage: usage
567
+ ? {
568
+ promptTokens: usage.prompt_tokens || 0,
569
+ completionTokens: usage.completion_tokens || 0,
570
+ totalTokens: usage.total_tokens || 0,
571
+ }
572
+ : undefined,
573
+ finishReason: computedFinishReason,
574
+ })
575
+ }
576
+ }
577
+
578
+ // Stream ended cleanly without finish_reason — flush any open
579
+ // lifecycle events so consumers don't see orphaned starts. This
580
+ // happens for abrupt `[DONE]` or upstream cuts.
581
+ if (!hasEmittedRunFinished) {
582
+ if (reasoningMessageId !== null && !hasClosedReasoning) {
583
+ hasClosedReasoning = true
584
+ yield asChunk({
585
+ type: 'REASONING_MESSAGE_END',
586
+ messageId: reasoningMessageId,
587
+ model: lastChunkModel,
588
+ timestamp,
589
+ })
590
+ yield asChunk({
591
+ type: 'REASONING_END',
592
+ messageId: reasoningMessageId,
593
+ model: lastChunkModel,
594
+ timestamp,
595
+ })
596
+ }
597
+ for (const [, toolCall] of toolCallsInProgress) {
598
+ if (toolCall.started && !toolCall.ended) {
599
+ toolCall.ended = true
600
+ hasEmittedToolCall = true
601
+ yield asChunk({
602
+ type: 'TOOL_CALL_END',
603
+ toolCallId: toolCall.id,
604
+ toolCallName: toolCall.name,
605
+ toolName: toolCall.name,
606
+ model: lastChunkModel,
607
+ timestamp,
608
+ input: parseToolCallInput(toolCall),
609
+ })
610
+ }
611
+ }
612
+ if (hasEmittedTextMessageStart && !hasEmittedTextMessageEnd) {
613
+ hasEmittedTextMessageEnd = true
614
+ yield asChunk({
615
+ type: 'TEXT_MESSAGE_END',
616
+ messageId: aguiState.messageId,
617
+ model: lastChunkModel,
618
+ timestamp,
619
+ })
620
+ }
621
+ hasEmittedRunFinished = true
622
+ yield asChunk({
623
+ type: 'RUN_FINISHED',
624
+ runId: aguiState.runId,
625
+ threadId: aguiState.threadId,
626
+ model: lastChunkModel,
627
+ timestamp,
628
+ usage: undefined,
629
+ finishReason: hasEmittedToolCall ? 'tool_calls' : 'stop',
630
+ })
631
+ }
632
+ } catch (error: unknown) {
633
+ // Lifecycle cleanup (TEXT_MESSAGE_END / TOOL_CALL_END / REASONING_END)
634
+ // on error path so consumers don't see orphaned starts. RUN_ERROR is
635
+ // emitted by the outer chatStream catch — emitting it here would
636
+ // duplicate the event.
637
+ if (reasoningMessageId !== null && !hasClosedReasoning) {
638
+ hasClosedReasoning = true
639
+ yield asChunk({
640
+ type: 'REASONING_MESSAGE_END',
641
+ messageId: reasoningMessageId,
642
+ model: lastChunkModel,
643
+ timestamp,
644
+ })
645
+ yield asChunk({
646
+ type: 'REASONING_END',
647
+ messageId: reasoningMessageId,
648
+ model: lastChunkModel,
649
+ timestamp,
650
+ })
651
+ }
652
+ if (hasEmittedTextMessageStart && !hasEmittedTextMessageEnd) {
653
+ hasEmittedTextMessageEnd = true
654
+ yield asChunk({
655
+ type: 'TEXT_MESSAGE_END',
656
+ messageId: aguiState.messageId,
657
+ model: lastChunkModel,
658
+ timestamp,
659
+ })
660
+ }
661
+ for (const [, toolCall] of toolCallsInProgress) {
662
+ if (toolCall.started && !toolCall.ended) {
663
+ toolCall.ended = true
664
+ // Best-effort parse for the partial args; if invalid, surface
665
+ // empty input rather than throwing inside the cleanup path.
666
+ let partialInput: unknown = {}
667
+ try {
668
+ partialInput = toolCall.arguments
669
+ ? transformNullsToUndefined(JSON.parse(toolCall.arguments))
670
+ : {}
671
+ } catch {
672
+ partialInput = {}
673
+ }
674
+ yield asChunk({
675
+ type: 'TOOL_CALL_END',
676
+ toolCallId: toolCall.id,
677
+ toolCallName: toolCall.name,
678
+ toolName: toolCall.name,
679
+ model: lastChunkModel,
680
+ timestamp,
681
+ input: partialInput,
682
+ })
683
+ }
684
+ }
685
+ throw error
686
+ }
687
+ }
688
+
689
+ /**
690
+ * Makes a raw fetch request to the Mistral chat completions endpoint and
691
+ * parses the SSE stream manually, bypassing the SDK's Zod validation which
692
+ * rejects streaming tool call chunks that omit `name` in argument deltas.
693
+ */
694
+ private async *fetchRawMistralStream(
695
+ params: ChatCompletionStreamRequest,
696
+ config: MistralClientConfig,
697
+ ): AsyncGenerator<MistralRawChunk> {
698
+ const serverURL = (config.serverURL ?? 'https://api.mistral.ai')
699
+ .replace(/\/+$/, '')
700
+ .replace(/\/v1$/, '')
701
+ const url = `${serverURL}/v1/chat/completions`
702
+
703
+ const body = this.toWireBody(params)
704
+
705
+ const headers: Record<string, string> = {
706
+ 'Content-Type': 'application/json',
707
+ Authorization: `Bearer ${config.apiKey}`,
708
+ ...config.defaultHeaders,
709
+ }
710
+
711
+ const response = await fetch(url, {
712
+ method: 'POST',
713
+ headers,
714
+ body: JSON.stringify(body),
715
+ })
716
+
717
+ if (!response.ok) {
718
+ const errorText = await response.text()
719
+ throw new Error(`Mistral API error ${response.status}: ${errorText}`)
720
+ }
721
+
722
+ if (!response.body) {
723
+ throw new Error(
724
+ 'Mistral API returned a response with no body. This may indicate a proxy or runtime that does not support streaming.',
725
+ )
726
+ }
727
+
728
+ const reader = response.body.getReader()
729
+ const decoder = new TextDecoder()
730
+ let buffer = ''
731
+
732
+ try {
733
+ for (;;) {
734
+ const { done, value } = await reader.read()
735
+ if (done) break
736
+
737
+ buffer += decoder.decode(value, { stream: true })
738
+ const lines = buffer.split('\n')
739
+ // split('\n') always yields at least one element, so pop() is a
740
+ // string here; `?? ''` only satisfies the type narrowing.
741
+ buffer = lines.pop() ?? ''
742
+
743
+ for (const line of lines) {
744
+ const trimmed = line.trim()
745
+ if (!trimmed.startsWith('data:')) continue
746
+ const data = trimmed.slice(5).trimStart()
747
+ if (data === '[DONE]') return
748
+
749
+ let parsed: unknown
750
+ try {
751
+ parsed = JSON.parse(data)
752
+ } catch (e) {
753
+ if (e instanceof SyntaxError) {
754
+ console.warn(
755
+ `[mistral] skipped unparseable SSE chunk: ${data.slice(0, 200)}`,
756
+ )
757
+ continue
758
+ }
759
+ throw e
760
+ }
761
+
762
+ // Mistral signals mid-stream errors via an `error` field. Surface
763
+ // them as RUN_ERROR rather than swallowing them as empty chunks.
764
+ if (
765
+ parsed &&
766
+ typeof parsed === 'object' &&
767
+ 'error' in parsed &&
768
+ !('choices' in parsed)
769
+ ) {
770
+ const errPayload = parsed.error
771
+ const message =
772
+ typeof errPayload === 'string'
773
+ ? errPayload
774
+ : errPayload &&
775
+ typeof errPayload === 'object' &&
776
+ 'message' in errPayload
777
+ ? String(errPayload.message)
778
+ : JSON.stringify(errPayload)
779
+ throw new Error(`Mistral stream error: ${message}`)
780
+ }
781
+
782
+ yield parsed as MistralRawChunk
783
+ }
784
+ }
785
+ } finally {
786
+ await reader.cancel().catch(() => {})
787
+ reader.releaseLock()
788
+ }
789
+ }
790
+
791
+ /**
792
+ * Converts the SDK's camelCase `ChatCompletionStreamRequest` into the
793
+ * snake_case wire body, including converting messages.
794
+ */
795
+ private toWireBody(
796
+ params: ChatCompletionStreamRequest,
797
+ ): Record<string, unknown> {
798
+ const {
799
+ messages,
800
+ maxTokens,
801
+ topP,
802
+ randomSeed,
803
+ responseFormat,
804
+ toolChoice,
805
+ parallelToolCalls,
806
+ frequencyPenalty,
807
+ presencePenalty,
808
+ safePrompt,
809
+ stream: _stream,
810
+ ...rest
811
+ } = params
812
+
813
+ return {
814
+ ...rest,
815
+ messages: messages.map(messageToWire),
816
+ stream: true,
817
+ // Opt in to usage on the final streaming chunk.
818
+ stream_options: { include_usage: true },
819
+ ...(maxTokens != null && { max_tokens: maxTokens }),
820
+ ...(topP != null && { top_p: topP }),
821
+ ...(randomSeed != null && { random_seed: randomSeed }),
822
+ ...(responseFormat != null && { response_format: responseFormat }),
823
+ ...(toolChoice != null && { tool_choice: toolChoice }),
824
+ ...(parallelToolCalls != null && {
825
+ parallel_tool_calls: parallelToolCalls,
826
+ }),
827
+ ...(frequencyPenalty != null && { frequency_penalty: frequencyPenalty }),
828
+ ...(presencePenalty != null && { presence_penalty: presencePenalty }),
829
+ ...(safePrompt != null && { safe_prompt: safePrompt }),
830
+ }
831
+ }
832
+
833
+ /**
834
+ * Splits a Mistral delta content payload into text and reasoning deltas.
835
+ * Mistral reasoning models (magistral-*) stream reasoning content as
836
+ * `{ type: 'thinking', thinking: [{ type: 'text', text }, ...] }` content
837
+ * parts. A single delta may contain text only, thinking only, or — rarely —
838
+ * both (when a step transitions); both fields are returned so the caller
839
+ * can sequence REASONING and TEXT lifecycle events in order.
840
+ */
841
+ private extractDeltaParts(
842
+ content:
843
+ | string
844
+ | Array<{
845
+ type: string
846
+ text?: string
847
+ thinking?: Array<{ type: string; text?: string }>
848
+ }>
849
+ | null
850
+ | undefined,
851
+ ): { text: string; thinking: string } {
852
+ if (!content) return { text: '', thinking: '' }
853
+ if (typeof content === 'string') return { text: content, thinking: '' }
854
+
855
+ let text = ''
856
+ let thinking = ''
857
+ for (const part of content) {
858
+ if (part.type === 'text' && typeof part.text === 'string') {
859
+ text += part.text
860
+ } else if (part.type === 'thinking' && Array.isArray(part.thinking)) {
861
+ for (const inner of part.thinking) {
862
+ if (inner.type === 'text' && typeof inner.text === 'string') {
863
+ thinking += inner.text
864
+ }
865
+ }
866
+ }
867
+ }
868
+ return { text, thinking }
869
+ }
870
+
871
+ /**
872
+ * Maps common TextOptions to Mistral Chat Completions request parameters.
873
+ */
874
+ private mapTextOptionsToMistral(
875
+ options: TextOptions<TProviderOptions>,
876
+ ): ChatCompletionStreamRequest {
877
+ const modelOptions = options.modelOptions as
878
+ | Omit<InternalTextProviderOptions, 'tools'>
879
+ | undefined
880
+
881
+ const tools = options.tools
882
+ ? convertToolsToProviderFormat(options.tools)
883
+ : undefined
884
+
885
+ const messages: Array<ChatCompletionMessageParam> = []
886
+
887
+ if (options.systemPrompts && options.systemPrompts.length > 0) {
888
+ messages.push({
889
+ role: 'system',
890
+ content: options.systemPrompts.join('\n'),
891
+ })
892
+ }
893
+
894
+ for (const message of options.messages) {
895
+ messages.push(this.convertMessageToMistral(message))
896
+ }
897
+
898
+ return {
899
+ model: options.model,
900
+ messages: messages,
901
+ temperature: modelOptions?.temperature ?? undefined,
902
+ maxTokens: modelOptions?.max_tokens ?? undefined,
903
+ topP: modelOptions?.top_p ?? undefined,
904
+ tools: tools as ChatCompletionStreamRequest['tools'],
905
+ stream: true,
906
+ ...(modelOptions && {
907
+ ...(modelOptions.stop != null && { stop: modelOptions.stop }),
908
+ ...(modelOptions.random_seed != null && {
909
+ randomSeed: modelOptions.random_seed,
910
+ }),
911
+ ...(modelOptions.response_format != null && {
912
+ responseFormat: modelOptions.response_format,
913
+ }),
914
+ ...(modelOptions.tool_choice != null && {
915
+ toolChoice: modelOptions.tool_choice,
916
+ }),
917
+ ...(modelOptions.parallel_tool_calls != null && {
918
+ parallelToolCalls: modelOptions.parallel_tool_calls,
919
+ }),
920
+ ...(modelOptions.frequency_penalty != null && {
921
+ frequencyPenalty: modelOptions.frequency_penalty,
922
+ }),
923
+ ...(modelOptions.presence_penalty != null && {
924
+ presencePenalty: modelOptions.presence_penalty,
925
+ }),
926
+ ...(modelOptions.n != null && { n: modelOptions.n }),
927
+ ...(modelOptions.prediction != null && {
928
+ prediction: modelOptions.prediction,
929
+ }),
930
+ ...(modelOptions.safe_prompt != null && {
931
+ safePrompt: modelOptions.safe_prompt,
932
+ }),
933
+ }),
934
+ }
935
+ }
936
+
937
+ /**
938
+ * Converts a TanStack AI ModelMessage to a Mistral ChatCompletionMessageParam.
939
+ */
940
+ private convertMessageToMistral(
941
+ message: ModelMessage,
942
+ ): ChatCompletionMessageParam {
943
+ if (message.role === 'tool') {
944
+ if (!message.toolCallId) {
945
+ throw new Error('Missing toolCallId for tool message')
946
+ }
947
+ return {
948
+ role: 'tool',
949
+ toolCallId: message.toolCallId,
950
+ content:
951
+ typeof message.content === 'string'
952
+ ? message.content
953
+ : JSON.stringify(message.content),
954
+ }
955
+ }
956
+
957
+ if (message.role === 'assistant') {
958
+ const toolCalls = message.toolCalls?.map((tc) => ({
959
+ id: tc.id,
960
+ type: 'function' as const,
961
+ function: {
962
+ name: tc.function.name,
963
+ arguments:
964
+ typeof tc.function.arguments === 'string'
965
+ ? tc.function.arguments
966
+ : JSON.stringify(tc.function.arguments),
967
+ },
968
+ }))
969
+
970
+ return {
971
+ role: 'assistant',
972
+ content: this.extractTextContent(message.content),
973
+ ...(toolCalls && toolCalls.length > 0 ? { toolCalls } : {}),
974
+ }
975
+ }
976
+
977
+ const contentParts = this.normalizeContent(message.content)
978
+
979
+ if (contentParts.length === 1 && contentParts[0]?.type === 'text') {
980
+ return {
981
+ role: 'user',
982
+ content: contentParts[0].content,
983
+ }
984
+ }
985
+
986
+ const parts = contentParts.map((part) =>
987
+ this.convertContentPartToMistral(part),
988
+ )
989
+
990
+ return {
991
+ role: 'user',
992
+ content: parts.length > 0 ? parts : '',
993
+ }
994
+ }
995
+
996
+ /**
997
+ * Converts a ContentPart to a Mistral content part. Returns undefined for
998
+ * unsupported part types.
999
+ */
1000
+ private convertContentPartToMistral(
1001
+ part: ContentPart,
1002
+ ): ChatCompletionContentPart {
1003
+ if (part.type === 'text') {
1004
+ return { type: 'text', text: part.content }
1005
+ }
1006
+
1007
+ if (part.type === 'image') {
1008
+ const imageMetadata = part.metadata as MistralImageMetadata | undefined
1009
+ const imageValue = part.source.value
1010
+ const imageUrl =
1011
+ part.source.type === 'data' && !imageValue.startsWith('data:')
1012
+ ? `data:${part.source.mimeType};base64,${imageValue}`
1013
+ : imageValue
1014
+ return {
1015
+ type: 'image_url',
1016
+ imageUrl: imageMetadata?.detail
1017
+ ? { url: imageUrl, detail: imageMetadata.detail }
1018
+ : imageUrl,
1019
+ }
1020
+ }
1021
+
1022
+ throw new Error(
1023
+ `Mistral text adapter does not support content part of type '${(part as ContentPart).type}'. Supported types: text, image. Use a vision-capable model (pixtral-large-latest, pixtral-12b-2409, mistral-medium-latest, or mistral-small-latest) for images.`,
1024
+ )
1025
+ }
1026
+
1027
+ /**
1028
+ * Normalizes message content to an array of ContentPart.
1029
+ */
1030
+ private normalizeContent(
1031
+ content: string | null | Array<ContentPart>,
1032
+ ): Array<ContentPart> {
1033
+ if (content === null) return []
1034
+ if (typeof content === 'string') return [{ type: 'text', content }]
1035
+ return content
1036
+ }
1037
+
1038
+ /**
1039
+ * Extracts text content from a content value that may be string, null, or ContentPart array.
1040
+ */
1041
+ private extractTextContent(
1042
+ content: string | null | Array<ContentPart>,
1043
+ ): string {
1044
+ if (content === null) return ''
1045
+ if (typeof content === 'string') return content
1046
+ return content
1047
+ .filter((p) => p.type === 'text')
1048
+ .map((p) => p.content)
1049
+ .join('')
1050
+ }
1051
+ }
1052
+
1053
+ /**
1054
+ * Snake-cases a Mistral SDK message into the wire format expected by the API.
1055
+ */
1056
+ function messageToWire(msg: ChatCompletionStreamRequest['messages'][number]) {
1057
+ if (msg.role === 'tool') {
1058
+ return {
1059
+ role: 'tool',
1060
+ tool_call_id: msg.toolCallId,
1061
+ content: msg.content,
1062
+ ...(msg.name !== undefined ? { name: msg.name } : {}),
1063
+ }
1064
+ }
1065
+ if (msg.role === 'assistant') {
1066
+ const base: Record<string, unknown> = {
1067
+ role: 'assistant',
1068
+ content: msg.content ?? null,
1069
+ }
1070
+ if (msg.toolCalls && msg.toolCalls.length > 0) {
1071
+ base.tool_calls = msg.toolCalls.map((tc) => ({
1072
+ id: tc.id,
1073
+ type: tc.type ?? 'function',
1074
+ function: tc.function,
1075
+ }))
1076
+ }
1077
+ if (msg.prefix !== undefined) base.prefix = msg.prefix
1078
+ return base
1079
+ }
1080
+ if (msg.role === 'user' && Array.isArray(msg.content)) {
1081
+ return {
1082
+ role: 'user',
1083
+ content: msg.content.map((part) => {
1084
+ if (part.type === 'image_url') {
1085
+ return { type: 'image_url', image_url: part.imageUrl }
1086
+ }
1087
+ if (part.type === 'document_url') {
1088
+ return { type: 'document_url', document_url: part.documentUrl }
1089
+ }
1090
+ return part
1091
+ }),
1092
+ }
1093
+ }
1094
+ return msg
1095
+ }
1096
+
1097
+ /**
1098
+ * Creates a Mistral text adapter with explicit API key.
1099
+ *
1100
+ * @param model - The model name (e.g., 'mistral-large-latest')
1101
+ * @param apiKey - Your Mistral API key
1102
+ * @param config - Optional additional configuration
1103
+ * @returns Configured Mistral text adapter instance
1104
+ *
1105
+ * @example
1106
+ * ```typescript
1107
+ * const adapter = createMistralText('mistral-large-latest', 'api_key');
1108
+ * ```
1109
+ */
1110
+ export function createMistralText<
1111
+ TModel extends (typeof MISTRAL_CHAT_MODELS)[number],
1112
+ >(
1113
+ model: TModel,
1114
+ apiKey: string,
1115
+ config?: Omit<MistralTextConfig, 'apiKey'>,
1116
+ ): MistralTextAdapter<TModel> {
1117
+ return new MistralTextAdapter({ apiKey, ...config }, model)
1118
+ }
1119
+
1120
+ /**
1121
+ * Creates a Mistral text adapter using the `MISTRAL_API_KEY` environment variable.
1122
+ *
1123
+ * @param model - The model name (e.g., 'mistral-large-latest')
1124
+ * @param config - Optional configuration (excluding apiKey)
1125
+ * @returns Configured Mistral text adapter instance
1126
+ * @throws Error if MISTRAL_API_KEY is not found in environment
1127
+ *
1128
+ * @example
1129
+ * ```typescript
1130
+ * const adapter = mistralText('mistral-large-latest');
1131
+ * ```
1132
+ */
1133
+ export function mistralText<
1134
+ TModel extends (typeof MISTRAL_CHAT_MODELS)[number],
1135
+ >(
1136
+ model: TModel,
1137
+ config?: Omit<MistralTextConfig, 'apiKey'>,
1138
+ ): MistralTextAdapter<TModel> {
1139
+ const apiKey = getMistralApiKeyFromEnv()
1140
+ return createMistralText(model, apiKey, config)
1141
+ }