ai-provider-mistral-sdk
Official Mistral AI TypeScript SDK patterns — client setup, chat completions, streaming, function calling, structured outputs, embeddings, vision, Codestral FIM, and production best practices
Install
npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/ai-provider-mistral-sdk/skills/ai-provider-mistral-sdk
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
git clone https://github.com/agents-inc/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Mistral SDK Patterns
Quick Guide: Use
@mistralai/mistralai(ESM-only) to interact with Mistral's API. Useclient.chat.complete()for chat,client.chat.stream()for streaming (async iterable viafor await),client.chat.parse()with a Zod schema for structured outputs, andclient.fim.complete()for Codestral fill-in-middle code completion. The SDK usesresponseFormat(camelCase) notresponse_format. Streaming events expose content viaevent.data.choices[0]?.delta?.content. Retries default tostrategy: "none"-- you must configure them explicitly for production.
<critical_requirements>
CRITICAL: Before Using This Skill
(You MUST use responseFormat (camelCase) in SDK calls -- NOT response_format (snake_case). The SDK uses camelCase property names throughout.)
(You MUST configure retries explicitly -- the SDK defaults to strategy: "none" (no retries), unlike OpenAI's SDK which retries automatically)
(You MUST consume streaming results with for await (const event of result) and access content via event.data.choices[0]?.delta?.content -- the event shape differs from OpenAI)
(You MUST never hardcode API keys -- use process.env["MISTRAL_API_KEY"] with the bracket notation the SDK documents)
(You MUST use client.chat.parse() with a Zod schema for structured outputs -- NOT manual JSON.parse() on completion content)
</critical_requirements>
Auto-detection: Mistral, mistral, @mistralai/mistralai, client.chat.complete, client.chat.stream, client.chat.parse, client.fim.complete, client.embeddings.create, mistral-large, mistral-small, codestral, pixtral, ministral, magistral, devstral, MISTRAL_API_KEY, responseFormat, mistral-embed
When to use:
- Building applications that call Mistral models directly (Mistral Large, Small, Codestral, etc.)
- Implementing chat completions with SSE streaming
- Using Codestral for code generation and fill-in-middle (FIM) completion
- Extracting structured data with
client.chat.parse()and Zod schemas - Implementing function calling / tool use
- Creating embeddings for RAG pipelines or semantic search
- Processing images with vision-capable models (Mistral Small, Medium, Large, Ministral)
- Using Mistral Agents API for pre-configured agent completions
Key patterns covered:
- Client initialization and configuration (retries, timeouts, custom HTTP client)
- Chat completions (
chat.complete) and streaming (chat.stream) - Structured outputs with
chat.parse()and Zod schemas - Function calling / tool use with tool call loop
- Embeddings (
embeddings.create) withmistral-embed - Vision (image URL / base64 with vision-capable models)
- Codestral FIM (
fim.complete) for code completion - Error handling, retry configuration, and production patterns
When NOT to use:
- Multi-provider applications where you need to switch between Mistral, OpenAI, Anthropic, etc. -- use a unified provider SDK
- React-specific chat UI hooks (
useChat) -- use a framework-integrated AI SDK - When you need OpenAI-compatible endpoints -- use OpenAI SDK with Mistral's compatible endpoint instead
Examples Index
- Core: Setup & Configuration -- Client init, production config, error handling, retries, custom HTTP client
- Chat & Streaming -- Chat completions, streaming with async iteration, multi-turn
- Structured Output --
chat.parse()with Zod, JSON mode, typed responses - Function Calling -- Tool definitions, tool call loop, streaming tools
- Embeddings & Vision -- Semantic search, image analysis with vision-capable models
- Codestral FIM -- Fill-in-middle code completion, code generation
- Quick API Reference -- Model IDs, method signatures, error types, configuration options
<decision_framework>
Decision Framework
Which Method to Use
What do you need?
+-- Chat completion (text in, text out)?
| +-- Need streaming? -> client.chat.stream()
| +-- Need structured JSON? -> client.chat.parse() with Zod schema
| +-- Basic completion? -> client.chat.complete()
+-- Code completion / fill-in-middle?
| +-- YES -> client.fim.complete() with Codestral
+-- Embeddings for search/RAG?
| +-- YES -> client.embeddings.create() with mistral-embed
+-- Pre-configured agent?
+-- YES -> client.agents.complete() with agent ID
Which Model to Choose
What is your task?
+-- Most capable general purpose -> mistral-large-latest
+-- Balanced cost/performance -> mistral-medium-latest
+-- Fast + cost-efficient -> mistral-small-latest
+-- Minimal / edge deployment -> ministral-3b-latest
+-- Complex reasoning / math -> magistral-medium-latest
+-- Code generation (chat) -> codestral-latest or devstral-latest
+-- Code completion (FIM) -> codestral-latest
+-- Vision / image analysis -> mistral-small-latest (or any vision-capable model)
+-- Embeddings -> mistral-embed
+-- Code embeddings -> codestral-embed-latest
Streaming vs Non-Streaming
Is the response user-facing?
+-- YES -> Use client.chat.stream()
| +-- Iterate with: for await (const event of result)
| +-- Access content: event.data.choices[0]?.delta?.content
+-- NO -> Use client.chat.complete()
+-- Background processing -> chat.complete()
+-- Structured output -> chat.parse() with Zod
When to Use This SDK vs a Provider-Agnostic SDK
Do you need multiple LLM providers (Mistral + others)?
+-- YES -> Not this skill's scope -- use a unified provider SDK
+-- NO -> Do you need Mistral-specific features?
+-- YES -> Use Mistral SDK directly
| Examples: Codestral FIM, Mistral Agents,
| Voxtral audio, OCR, custom endpoints
+-- NO -> Mistral SDK is simplest for Mistral-only use
</decision_framework>
<red_flags>
RED FLAGS
High Priority Issues:
- Using
response_format(snake_case) instead ofresponseFormat(camelCase) -- silently ignored, no error thrown - Using
input(singular) for embeddings instead ofinputs(plural) -- Mistral-specific naming - Not configuring retries for production (SDK defaults to
strategy: "none"-- zero retries) - Hardcoding API keys instead of using environment variables
- Accessing
chunk.choices[0]?.delta?.contentdirectly on streaming events instead ofevent.data.choices[0]?.delta?.content
Medium Priority Issues:
- Not setting
timeoutMsfor production (default is-1, meaning no timeout -- requests can hang indefinitely) - Using
max_tokensinstead ofmaxTokens(camelCase SDK convention) - Missing
systemrole message for behavior guidance - Using
tool_choiceinstead oftoolChoice - Using
tool_callsinstead oftoolCallswhen reading responses
Common Mistakes:
- Importing from
"mistralai"instead of"@mistralai/mistralai"-- the correct package name has the org scope - Using CommonJS
require()-- the package is ESM-only, useimportorawait import() - Confusing Mistral's
imageUrl: "url"(flat string) with OpenAI'simage_url: { url: "..." }(nested object) - Using
client.chat.completions.create()(OpenAI pattern) instead ofclient.chat.complete()(Mistral pattern) - Assuming embedding dimensions match OpenAI's --
mistral-embedreturns 1024-dimensional vectors, not 1536
Gotchas & Edge Cases:
- The SDK is ESM-only. In CommonJS projects, you must use
const { Mistral } = await import("@mistralai/mistralai"). - Streaming content may be
string | string[]-- cast or check type when writing to stdout. chat.parse()requires a Zod schema passed toresponseFormat-- it does not accept{ type: "json_object" }.- The
apiKeyconstructor option accepts a string OR an async function() => Promise<string>for dynamic key rotation. - Model aliases like
mistral-large-latestresolve to the latest version of that model tier. Pin to specific versions (e.g.,mistral-large-3-25-12) for reproducibility. toolChoice: "any"forces the model to call a tool.toolChoice: "auto"lets the model decide.toolChoice: "none"prevents tool calls.parallelToolCalls: falseforces sequential tool calling (defaulttrueallows parallel).- FIM endpoint (
fim.complete()) usesprompt+suffixparameters, NOT themessagesarray. safePrompt: trueinjects Mistral's safety system prompt before your messages.- The SDK provides standalone functions (e.g.,
chatComplete()from"@mistralai/mistralai/funcs/chatComplete.js") for tree-shaking in browser/edge runtimes.
</red_flags>
<critical_reminders>
CRITICAL REMINDERS
(You MUST use responseFormat (camelCase) in SDK calls -- NOT response_format (snake_case). The SDK uses camelCase property names throughout.)
(You MUST configure retries explicitly -- the SDK defaults to strategy: "none" (no retries), unlike OpenAI's SDK which retries automatically)
(You MUST consume streaming results with for await (const event of result) and access content via event.data.choices[0]?.delta?.content -- the event shape differs from OpenAI)
(You MUST never hardcode API keys -- use process.env["MISTRAL_API_KEY"] with the bracket notation the SDK documents)
(You MUST use client.chat.parse() with a Zod schema for structured outputs -- NOT manual JSON.parse() on completion content)
Failure to follow these rules will produce broken API calls (snake_case properties silently ignored), unreliable production services (no retries), or incorrectly parsed streaming data.
</critical_reminders>
Files (skills)
-
examples
-
chat.md 5.7 KB
Loading… -
codestral.md 4 KB
Loading… -
core.md 6.4 KB
Loading… -
embeddings-vision.md 6 KB
Loading… -
function-calling.md 6.8 KB
Loading… -
structured-output.md 5.3 KB
Loading…
-
-
reference.md 9.9 KB
Loading… -
SKILL.md 21.2 KB
--- name: ai-provider-mistral-sdk description: Official Mistral AI TypeScript SDK patterns — client setup, chat completions, streaming, function calling, structured outputs, embeddings, vision, Codestral FIM, and production best practices --- # Mistral SDK Patterns > **Quick Guide:** Use `@mistralai/mistralai` (ESM-only) to interact with Mistral's API. Use `client.chat.complete()` for chat, `client.chat.stream()` for streaming (async iterable via `for await`), `client.chat.parse()` with a Zod schema for structured outputs, and `client.fim.complete()` for Codestral fill-in-middle code completion. The SDK uses `responseFormat` (camelCase) not `response_format`. Streaming events expose content via `event.data.choices[0]?.delta?.content`. Retries default to `strategy: "none"` -- you must configure them explicitly for production. --- <critical_requirements> ## CRITICAL: Before Using This Skill **(You MUST use `responseFormat` (camelCase) in SDK calls -- NOT `response_format` (snake_case). The SDK uses camelCase property names throughout.)** **(You MUST configure retries explicitly -- the SDK defaults to `strategy: "none"` (no retries), unlike OpenAI's SDK which retries automatically)** **(You MUST consume streaming results with `for await (const event of result)` and access content via `event.data.choices[0]?.delta?.content` -- the event shape differs from OpenAI)** **(You MUST never hardcode API keys -- use `process.env["MISTRAL_API_KEY"]` with the bracket notation the SDK documents)** **(You MUST use `client.chat.parse()` with a Zod schema for structured outputs -- NOT manual `JSON.parse()` on completion content)** </critical_requirements> --- **Auto-detection:** Mistral, mistral, @mistralai/mistralai, client.chat.complete, client.chat.stream, client.chat.parse, client.fim.complete, client.embeddings.create, mistral-large, mistral-small, codestral, pixtral, ministral, magistral, devstral, MISTRAL_API_KEY, responseFormat, mistral-embed **When to use:** - Building applications that call Mistral models directly (Mistral Large, Small, Codestral, etc.) - Implementing chat completions with SSE streaming - Using Codestral for code generation and fill-in-middle (FIM) completion - Extracting structured data with `client.chat.parse()` and Zod schemas - Implementing function calling / tool use - Creating embeddings for RAG pipelines or semantic search - Processing images with vision-capable models (Mistral Small, Medium, Large, Ministral) - Using Mistral Agents API for pre-configured agent completions **Key patterns covered:** - Client initialization and configuration (retries, timeouts, custom HTTP client) - Chat completions (`chat.complete`) and streaming (`chat.stream`) - Structured outputs with `chat.parse()` and Zod schemas - Function calling / tool use with tool call loop - Embeddings (`embeddings.create`) with `mistral-embed` - Vision (image URL / base64 with vision-capable models) - Codestral FIM (`fim.complete`) for code completion - Error handling, retry configuration, and production patterns **When NOT to use:** - Multi-provider applications where you need to switch between Mistral, OpenAI, Anthropic, etc. -- use a unified provider SDK - React-specific chat UI hooks (`useChat`) -- use a framework-integrated AI SDK - When you need OpenAI-compatible endpoints -- use OpenAI SDK with Mistral's compatible endpoint instead --- ## Examples Index - [Core: Setup & Configuration](examples/core.md) -- Client init, production config, error handling, retries, custom HTTP client - [Chat & Streaming](examples/chat.md) -- Chat completions, streaming with async iteration, multi-turn - [Structured Output](examples/structured-output.md) -- `chat.parse()` with Zod, JSON mode, typed responses - [Function Calling](examples/function-calling.md) -- Tool definitions, tool call loop, streaming tools - [Embeddings & Vision](examples/embeddings-vision.md) -- Semantic search, image analysis with vision-capable models - [Codestral FIM](examples/codestral.md) -- Fill-in-middle code completion, code generation - [Quick API Reference](reference.md) -- Model IDs, method signatures, error types, configuration options --- <philosophy> ## Philosophy The `@mistralai/mistralai` SDK is **auto-generated from Mistral's OpenAPI spec using Speakeasy**, giving you a thin, type-safe wrapper over the REST API. It is ESM-only and uses camelCase property names (not snake_case like the REST API). **Core principles:** 1. **ESM-only** -- The package is published as ESM only. CommonJS projects must use `await import()`. This is a hard constraint, not optional. 2. **camelCase API surface** -- SDK properties use camelCase (`responseFormat`, `maxTokens`, `toolChoice`) even though the REST API uses snake_case. This catches OpenAI SDK migrants who write `response_format`. 3. **No automatic retries** -- Unlike OpenAI's SDK (2 retries by default), Mistral defaults to `strategy: "none"`. You must configure retries explicitly for production. 4. **Streaming via async iterables** -- `chat.stream()` returns an `EventStream` consumed with `for await...of`. Events have a `data` wrapper: `event.data.choices[0]?.delta?.content`. 5. **Structured outputs via `chat.parse()`** -- Pass a Zod schema directly to `responseFormat` and access `message.parsed` for typed results. No manual JSON schema construction needed. 6. **Codestral FIM** -- Dedicated `fim.complete()` endpoint for fill-in-middle code completion, separate from chat. **When to use the Mistral SDK directly:** - You only use Mistral models and want the simplest, most direct integration - You need Mistral-specific features (Codestral FIM, Mistral Agents, Voxtral audio) - You want minimal dependencies and zero abstraction overhead - You need the latest Mistral API features on day one **When NOT to use:** - You need to switch between providers (OpenAI, Anthropic, Mistral) -- use a unified provider SDK - You want React-specific chat UI hooks -- use a framework-integrated AI SDK - You want an OpenAI-compatible wrapper -- Mistral exposes an OpenAI-compatible endpoint, use the OpenAI SDK for that </philosophy> --- <patterns> ## Core Patterns ### Pattern 1: Client Setup Initialize the Mistral client. It reads `MISTRAL_API_KEY` from the environment. ```typescript // lib/mistral.ts -- basic setup import { Mistral } from "@mistralai/mistralai"; const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "", }); export { client }; ``` ```typescript // lib/mistral.ts -- production configuration import { Mistral } from "@mistralai/mistralai"; const TIMEOUT_MS = 30_000; const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "", timeoutMs: TIMEOUT_MS, retryConfig: { strategy: "backoff", backoff: { initialInterval: 1_000, maxInterval: 30_000, exponent: 1.5, maxElapsedTime: 120_000, }, retryConnectionErrors: true, }, }); export { client }; ``` **Why good:** Explicit retry config (SDK defaults to no retries), named constants, env var with bracket notation **See:** [examples/core.md](examples/core.md) for custom HTTP client, async API key provider, error handling --- ### Pattern 2: Chat Completions Basic chat using `chat.complete()`. ```typescript const result = await client.chat.complete({ model: "mistral-large-latest", messages: [ { role: "system", content: "You are a helpful coding assistant." }, { role: "user", content: "Explain TypeScript generics." }, ], }); const content = result?.choices?.[0]?.message?.content; console.log(content); ``` **Why good:** Uses `system` role for instructions, safe optional chaining on nullable response ```typescript // BAD: Using snake_case properties (REST API style, not SDK style) const result = await client.chat.complete({ model: "mistral-large-latest", messages: [{ role: "user", content: "hello" }], response_format: { type: "json_object" }, // WRONG: use responseFormat max_tokens: 100, // WRONG: use maxTokens }); ``` **Why bad:** SDK uses camelCase properties -- `response_format` and `max_tokens` will be silently ignored **See:** [examples/chat.md](examples/chat.md) for multi-turn, token tracking, temperature control --- ### Pattern 3: Streaming Use `chat.stream()` for streaming. Events are async iterables. ```typescript const result = await client.chat.stream({ model: "mistral-large-latest", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "Explain async/await in TypeScript." }, ], }); for await (const event of result) { const content = event.data.choices[0]?.delta?.content; if (content) { process.stdout.write(content as string); } } console.log(); ``` **Why good:** Proper `for await` iteration, accesses `event.data` (not `event` directly), handles nullable delta ```typescript // BAD: Trying to access content directly on event (OpenAI pattern) for await (const chunk of result) { process.stdout.write(chunk.choices[0]?.delta?.content ?? ""); // WRONG } ``` **Why bad:** Mistral streaming events wrap data in `event.data` -- direct access on `chunk` will fail **See:** [examples/chat.md](examples/chat.md) for complete streaming examples --- ### Pattern 4: Structured Outputs with Zod Use `chat.parse()` with a Zod schema for type-safe structured responses. ```typescript import { Mistral } from "@mistralai/mistralai"; import { z } from "zod"; const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" }); const BookSchema = z.object({ name: z.string(), authors: z.array(z.string()), }); const MAX_TOKENS = 256; const result = await client.chat.parse({ model: "mistral-large-latest", messages: [ { role: "system", content: "Extract the book information." }, { role: "user", content: "I recently read 'Dune' by Frank Herbert." }, ], responseFormat: BookSchema, maxTokens: MAX_TOKENS, temperature: 0, }); const parsed = result.choices?.[0]?.message?.parsed; // parsed is typed as { name: string; authors: string[] } ``` **Why good:** Schema passed directly to `responseFormat`, `message.parsed` is fully typed, named constants **See:** [examples/structured-output.md](examples/structured-output.md) for JSON mode, complex schemas --- ### Pattern 5: Function Calling / Tool Use Define tools and handle the tool call loop. ```typescript const tools = [ { type: "function" as const, function: { name: "get_weather", description: "Get current weather for a city", parameters: { type: "object", properties: { location: { type: "string", description: "City name" }, }, required: ["location"], }, }, }, ]; const result = await client.chat.complete({ model: "mistral-large-latest", messages: [{ role: "user", content: "Weather in Paris?" }], tools, toolChoice: "any", }); const toolCall = result?.choices?.[0]?.message?.toolCalls?.[0]; if (toolCall) { const args = JSON.parse(toolCall.function.arguments); console.log(`Call ${toolCall.function.name} with:`, args); } ``` **Why good:** Uses `toolChoice` (camelCase), `toolCalls` (camelCase), proper `as const` for type literal **See:** [examples/function-calling.md](examples/function-calling.md) for complete tool loop, parallel calls --- ### Pattern 6: Embeddings Create embeddings with `mistral-embed`. Note: uses `inputs` (plural), not `input`. ```typescript const EMBEDDING_MODEL = "mistral-embed"; const result = await client.embeddings.create({ model: EMBEDDING_MODEL, inputs: ["First document", "Second document", "Third document"], }); const vectors = result.data?.map((item) => item.embedding) ?? []; ``` **Why good:** Uses `inputs` (Mistral-specific, plural), named model constant, safe optional chaining ```typescript // BAD: Using singular 'input' (OpenAI pattern) const result = await client.embeddings.create({ model: "mistral-embed", input: ["First document"], // WRONG: Mistral uses 'inputs' (plural) }); ``` **Why bad:** Mistral SDK uses `inputs` (plural) -- `input` (singular) will error or be silently ignored **See:** [examples/embeddings-vision.md](examples/embeddings-vision.md) for cosine similarity, semantic search --- ### Pattern 7: Vision Send images to vision-capable models using multi-part content arrays. ```typescript const result = await client.chat.complete({ model: "mistral-small-latest", messages: [ { role: "user", content: [ { type: "text", text: "What is in this image?" }, { type: "image_url", imageUrl: "https://example.com/photo.jpg", }, ], }, ], }); ``` **Why good:** Uses `imageUrl` (camelCase string), not `image_url: { url }` (OpenAI's nested object pattern) **See:** [examples/embeddings-vision.md](examples/embeddings-vision.md) for base64 images, multiple images --- ### Pattern 8: Codestral FIM Fill-in-middle code completion using the dedicated FIM endpoint. ```typescript const result = await client.fim.complete({ model: "codestral-latest", prompt: "function fibonacci(n: number): number {\n if (n <= 1) return n;\n", suffix: "}\n\nconsole.log(fibonacci(10));", temperature: 0, }); const completion = result.choices?.[0]?.message?.content; // completion fills the gap between prompt and suffix ``` **Why good:** Dedicated FIM endpoint, separate `prompt` + `suffix` (not messages), deterministic with `temperature: 0` **See:** [examples/codestral.md](examples/codestral.md) for code generation patterns --- ### Pattern 9: Error Handling The SDK provides specific error types. Configure retries since the default is no retries. ```typescript import { Mistral } from "@mistralai/mistralai"; import { SDKError, SDKValidationError, HTTPValidationError, } from "@mistralai/mistralai/models/errors"; try { const result = await client.chat.complete({ model: "mistral-large-latest", messages: [{ role: "user", content: "Hello" }], }); } catch (error) { if (error instanceof HTTPValidationError) { console.error("Validation error:", error.message); } else if (error instanceof SDKValidationError) { console.error("Input validation error:", error.message); } else if (error instanceof SDKError) { console.error(`API error [${error.statusCode}]: ${error.message}`); } else { throw error; } } ``` **Why good:** Specific error types checked in order of specificity, re-throws unexpected errors **See:** [examples/core.md](examples/core.md) for full error handling, timeout handling, retry configuration </patterns> --- <performance> ## Performance Optimization ### Model Selection ``` General purpose (most capable) -> mistral-large-latest (Mistral Large 3) Balanced cost/quality -> mistral-medium-latest (Mistral Medium 3.1) Cost-sensitive / fast -> mistral-small-latest (Mistral Small 4) Edge / minimal -> ministral-3b-latest or ministral-8b-latest Complex reasoning -> magistral-medium-latest Code generation -> codestral-latest or devstral-latest Code completion (FIM) -> codestral-latest (dedicated FIM endpoint) Vision / images -> mistral-small-latest or mistral-large-latest Embeddings -> mistral-embed (1024 dimensions) Code embeddings -> codestral-embed-latest ``` ### Key Optimization Patterns - **Configure retries** -- Default is no retries. Always set `retryConfig` for production. - **Set timeouts** -- Default is no timeout (`-1`). Set `timeoutMs` to avoid hanging requests. - **Use `temperature: 0`** for deterministic output (enables server-side caching). - **Batch embedding inputs** -- Pass multiple strings to `inputs` array in one call. - **Use FIM for code completion** -- `fim.complete()` is purpose-built and more efficient than chat for code completion tasks. </performance> --- <decision_framework> ## Decision Framework ### Which Method to Use ``` What do you need? +-- Chat completion (text in, text out)? | +-- Need streaming? -> client.chat.stream() | +-- Need structured JSON? -> client.chat.parse() with Zod schema | +-- Basic completion? -> client.chat.complete() +-- Code completion / fill-in-middle? | +-- YES -> client.fim.complete() with Codestral +-- Embeddings for search/RAG? | +-- YES -> client.embeddings.create() with mistral-embed +-- Pre-configured agent? +-- YES -> client.agents.complete() with agent ID ``` ### Which Model to Choose ``` What is your task? +-- Most capable general purpose -> mistral-large-latest +-- Balanced cost/performance -> mistral-medium-latest +-- Fast + cost-efficient -> mistral-small-latest +-- Minimal / edge deployment -> ministral-3b-latest +-- Complex reasoning / math -> magistral-medium-latest +-- Code generation (chat) -> codestral-latest or devstral-latest +-- Code completion (FIM) -> codestral-latest +-- Vision / image analysis -> mistral-small-latest (or any vision-capable model) +-- Embeddings -> mistral-embed +-- Code embeddings -> codestral-embed-latest ``` ### Streaming vs Non-Streaming ``` Is the response user-facing? +-- YES -> Use client.chat.stream() | +-- Iterate with: for await (const event of result) | +-- Access content: event.data.choices[0]?.delta?.content +-- NO -> Use client.chat.complete() +-- Background processing -> chat.complete() +-- Structured output -> chat.parse() with Zod ``` ### When to Use This SDK vs a Provider-Agnostic SDK ``` Do you need multiple LLM providers (Mistral + others)? +-- YES -> Not this skill's scope -- use a unified provider SDK +-- NO -> Do you need Mistral-specific features? +-- YES -> Use Mistral SDK directly | Examples: Codestral FIM, Mistral Agents, | Voxtral audio, OCR, custom endpoints +-- NO -> Mistral SDK is simplest for Mistral-only use ``` </decision_framework> --- <red_flags> ## RED FLAGS **High Priority Issues:** - Using `response_format` (snake_case) instead of `responseFormat` (camelCase) -- silently ignored, no error thrown - Using `input` (singular) for embeddings instead of `inputs` (plural) -- Mistral-specific naming - Not configuring retries for production (SDK defaults to `strategy: "none"` -- zero retries) - Hardcoding API keys instead of using environment variables - Accessing `chunk.choices[0]?.delta?.content` directly on streaming events instead of `event.data.choices[0]?.delta?.content` **Medium Priority Issues:** - Not setting `timeoutMs` for production (default is `-1`, meaning no timeout -- requests can hang indefinitely) - Using `max_tokens` instead of `maxTokens` (camelCase SDK convention) - Missing `system` role message for behavior guidance - Using `tool_choice` instead of `toolChoice` - Using `tool_calls` instead of `toolCalls` when reading responses **Common Mistakes:** - Importing from `"mistralai"` instead of `"@mistralai/mistralai"` -- the correct package name has the org scope - Using CommonJS `require()` -- the package is ESM-only, use `import` or `await import()` - Confusing Mistral's `imageUrl: "url"` (flat string) with OpenAI's `image_url: { url: "..." }` (nested object) - Using `client.chat.completions.create()` (OpenAI pattern) instead of `client.chat.complete()` (Mistral pattern) - Assuming embedding dimensions match OpenAI's -- `mistral-embed` returns 1024-dimensional vectors, not 1536 **Gotchas & Edge Cases:** - The SDK is ESM-only. In CommonJS projects, you must use `const { Mistral } = await import("@mistralai/mistralai")`. - Streaming content may be `string | string[]` -- cast or check type when writing to stdout. - `chat.parse()` requires a Zod schema passed to `responseFormat` -- it does not accept `{ type: "json_object" }`. - The `apiKey` constructor option accepts a string OR an async function `() => Promise<string>` for dynamic key rotation. - Model aliases like `mistral-large-latest` resolve to the latest version of that model tier. Pin to specific versions (e.g., `mistral-large-3-25-12`) for reproducibility. - `toolChoice: "any"` forces the model to call a tool. `toolChoice: "auto"` lets the model decide. `toolChoice: "none"` prevents tool calls. - `parallelToolCalls: false` forces sequential tool calling (default `true` allows parallel). - FIM endpoint (`fim.complete()`) uses `prompt` + `suffix` parameters, NOT the `messages` array. - `safePrompt: true` injects Mistral's safety system prompt before your messages. - The SDK provides standalone functions (e.g., `chatComplete()` from `"@mistralai/mistralai/funcs/chatComplete.js"`) for tree-shaking in browser/edge runtimes. </red_flags> --- <critical_reminders> ## CRITICAL REMINDERS **(You MUST use `responseFormat` (camelCase) in SDK calls -- NOT `response_format` (snake_case). The SDK uses camelCase property names throughout.)** **(You MUST configure retries explicitly -- the SDK defaults to `strategy: "none"` (no retries), unlike OpenAI's SDK which retries automatically)** **(You MUST consume streaming results with `for await (const event of result)` and access content via `event.data.choices[0]?.delta?.content` -- the event shape differs from OpenAI)** **(You MUST never hardcode API keys -- use `process.env["MISTRAL_API_KEY"]` with the bracket notation the SDK documents)** **(You MUST use `client.chat.parse()` with a Zod schema for structured outputs -- NOT manual `JSON.parse()` on completion content)** **Failure to follow these rules will produce broken API calls (snake_case properties silently ignored), unreliable production services (no retries), or incorrectly parsed streaming data.** </critical_reminders>
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.