/ai-provider-mistral-sdk

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

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(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 provi