{"slug":"ai-provider-mistral-sdk","title":"ai-provider-mistral-sdk","summary":"Official Mistral AI TypeScript SDK patterns — client setup, chat completions, streaming, function calling, structured outputs, embeddings, vision, Codestral FIM, and production best practices","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-29T15:27:51.711253Z","repo":{"url":"https://github.com/agents-inc/skills","stars":24,"forks":8,"license":"MIT","updatedAt":"2026-09-07T17:50:55Z"},"bodyHtml":"<hr>\n<h2>name: ai-provider-mistral-sdk\ndescription: Official Mistral AI TypeScript SDK patterns — client setup, chat completions, streaming, function calling, structured outputs, embeddings, vision, Codestral FIM, and production best practices</h2>\n<h1>Mistral SDK Patterns</h1>\n<blockquote>\n<p><strong>Quick Guide:</strong> Use <code>@mistralai/mistralai</code> (ESM-only) to interact with Mistral's API. Use <code>client.chat.complete()</code> for chat, <code>client.chat.stream()</code> for streaming (async iterable via <code>for await</code>), <code>client.chat.parse()</code> with a Zod schema for structured outputs, and <code>client.fim.complete()</code> for Codestral fill-in-middle code completion. The SDK uses <code>responseFormat</code> (camelCase) not <code>response_format</code>. Streaming events expose content via <code>event.data.choices[0]?.delta?.content</code>. Retries default to <code>strategy: \"none\"</code> -- you must configure them explicitly for production.</p>\n</blockquote>\n<hr>\n<p>&lt;critical_requirements&gt;</p>\n<h2>CRITICAL: Before Using This Skill</h2>\n<blockquote>\n<p><strong>All code must follow project conventions in CLAUDE.md</strong> (kebab-case, named exports, import ordering, <code>import type</code>, named constants)</p>\n</blockquote>\n<p><strong>(You MUST use <code>responseFormat</code> (camelCase) in SDK calls -- NOT <code>response_format</code> (snake_case). The SDK uses camelCase property names throughout.)</strong></p>\n<p><strong>(You MUST configure retries explicitly -- the SDK defaults to <code>strategy: \"none\"</code> (no retries), unlike OpenAI's SDK which retries automatically)</strong></p>\n<p><strong>(You MUST consume streaming results with <code>for await (const event of result)</code> and access content via <code>event.data.choices[0]?.delta?.content</code> -- the event shape differs from OpenAI)</strong></p>\n<p><strong>(You MUST never hardcode API keys -- use <code>process.env[\"MISTRAL_API_KEY\"]</code> with the bracket notation the SDK documents)</strong></p>\n<p><strong>(You MUST use <code>client.chat.parse()</code> with a Zod schema for structured outputs -- NOT manual <code>JSON.parse()</code> on completion content)</strong></p>\n<p>&lt;/critical_requirements&gt;</p>\n<hr>\n<p><strong>Auto-detection:</strong> 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</p>\n<p><strong>When to use:</strong></p>\n<ul>\n<li>Building applications that call Mistral models directly (Mistral Large, Small, Codestral, etc.)</li>\n<li>Implementing chat completions with SSE streaming</li>\n<li>Using Codestral for code generation and fill-in-middle (FIM) completion</li>\n<li>Extracting structured data with <code>client.chat.parse()</code> and Zod schemas</li>\n<li>Implementing function calling / tool use</li>\n<li>Creating embeddings for RAG pipelines or semantic search</li>\n<li>Processing images with vision-capable models (Mistral Small, Medium, Large, Ministral)</li>\n<li>Using Mistral Agents API for pre-configured agent completions</li>\n</ul>\n<p><strong>Key patterns covered:</strong></p>\n<ul>\n<li>Client initialization and configuration (retries, timeouts, custom HTTP client)</li>\n<li>Chat completions (<code>chat.complete</code>) and streaming (<code>chat.stream</code>)</li>\n<li>Structured outputs with <code>chat.parse()</code> and Zod schemas</li>\n<li>Function calling / tool use with tool call loop</li>\n<li>Embeddings (<code>embeddings.create</code>) with <code>mistral-embed</code></li>\n<li>Vision (image URL / base64 with vision-capable models)</li>\n<li>Codestral FIM (<code>fim.complete</code>) for code completion</li>\n<li>Error handling, retry configuration, and production patterns</li>\n</ul>\n<p><strong>When NOT to use:</strong></p>\n<ul>\n<li>Multi-provider applications where you need to switch between Mistral, OpenAI, Anthropic, etc. -- use a unified provider SDK</li>\n<li>React-specific chat UI hooks (<code>useChat</code>) -- use a framework-integrated AI SDK</li>\n<li>When you need OpenAI-compatible endpoints -- use OpenAI SDK with Mistral's compatible endpoint instead</li>\n</ul>\n<hr>\n<h2>Examples Index</h2>\n<ul>\n<li><a href=\"examples/core.md\">Core: Setup &amp; Configuration</a> -- Client init, production config, error handling, retries, custom HTTP client</li>\n<li><a href=\"examples/chat.md\">Chat &amp; Streaming</a> -- Chat completions, streaming with async iteration, multi-turn</li>\n<li><a href=\"examples/structured-output.md\">Structured Output</a> -- <code>chat.parse()</code> with Zod, JSON mode, typed responses</li>\n<li><a href=\"examples/function-calling.md\">Function Calling</a> -- Tool definitions, tool call loop, streaming tools</li>\n<li><a href=\"examples/embeddings-vision.md\">Embeddings &amp; Vision</a> -- Semantic search, image analysis with vision-capable models</li>\n<li><a href=\"examples/codestral.md\">Codestral FIM</a> -- Fill-in-middle code completion, code generation</li>\n<li><a href=\"reference.md\">Quick API Reference</a> -- Model IDs, method signatures, error types, configuration options</li>\n</ul>\n<hr>\n\n<hr>\n\n<hr>\n\n<hr>\n<p>&lt;decision_framework&gt;</p>\n<h2>Decision Framework</h2>\n<h3>Which Method to Use</h3>\n<pre><code>What do you need?\n+-- Chat completion (text in, text out)?\n|   +-- Need streaming? -&gt; client.chat.stream()\n|   +-- Need structured JSON? -&gt; client.chat.parse() with Zod schema\n|   +-- Basic completion? -&gt; client.chat.complete()\n+-- Code completion / fill-in-middle?\n|   +-- YES -&gt; client.fim.complete() with Codestral\n+-- Embeddings for search/RAG?\n|   +-- YES -&gt; client.embeddings.create() with mistral-embed\n+-- Pre-configured agent?\n    +-- YES -&gt; client.agents.complete() with agent ID\n</code></pre>\n<h3>Which Model to Choose</h3>\n<pre><code>What is your task?\n+-- Most capable general purpose -&gt; mistral-large-latest\n+-- Balanced cost/performance -&gt; mistral-medium-latest\n+-- Fast + cost-efficient -&gt; mistral-small-latest\n+-- Minimal / edge deployment -&gt; ministral-3b-latest\n+-- Complex reasoning / math -&gt; magistral-medium-latest\n+-- Code generation (chat) -&gt; codestral-latest or devstral-latest\n+-- Code completion (FIM) -&gt; codestral-latest\n+-- Vision / image analysis -&gt; mistral-small-latest (or any vision-capable model)\n+-- Embeddings -&gt; mistral-embed\n+-- Code embeddings -&gt; codestral-embed-latest\n</code></pre>\n<h3>Streaming vs Non-Streaming</h3>\n<pre><code>Is the response user-facing?\n+-- YES -&gt; Use client.chat.stream()\n|   +-- Iterate with: for await (const event of result)\n|   +-- Access content: event.data.choices[0]?.delta?.content\n+-- NO -&gt; Use client.chat.complete()\n    +-- Background processing -&gt; chat.complete()\n    +-- Structured output -&gt; chat.parse() with Zod\n</code></pre>\n<h3>When to Use This SDK vs a Provider-Agnostic SDK</h3>\n<pre><code>Do you need multiple LLM providers (Mistral + others)?\n+-- YES -&gt; Not this skill's scope -- use a unified provider SDK\n+-- NO -&gt; Do you need Mistral-specific features?\n    +-- YES -&gt; Use Mistral SDK directly\n    |   Examples: Codestral FIM, Mistral Agents,\n    |   Voxtral audio, OCR, custom endpoints\n    +-- NO -&gt; Mistral SDK is simplest for Mistral-only use\n</code></pre>\n<p>&lt;/decision_framework&gt;</p>\n<hr>\n<p>&lt;red_flags&gt;</p>\n<h2>RED FLAGS</h2>\n<p><strong>High Priority Issues:</strong></p>\n<ul>\n<li>Using <code>response_format</code> (snake_case) instead of <code>responseFormat</code> (camelCase) -- silently ignored, no error thrown</li>\n<li>Using <code>input</code> (singular) for embeddings instead of <code>inputs</code> (plural) -- Mistral-specific naming</li>\n<li>Not configuring retries for production (SDK defaults to <code>strategy: \"none\"</code> -- zero retries)</li>\n<li>Hardcoding API keys instead of using environment variables</li>\n<li>Accessing <code>chunk.choices[0]?.delta?.content</code> directly on streaming events instead of <code>event.data.choices[0]?.delta?.content</code></li>\n</ul>\n<p><strong>Medium Priority Issues:</strong></p>\n<ul>\n<li>Not setting <code>timeoutMs</code> for production (default is <code>-1</code>, meaning no timeout -- requests can hang indefinitely)</li>\n<li>Using <code>max_tokens</code> instead of <code>maxTokens</code> (camelCase SDK convention)</li>\n<li>Missing <code>system</code> role message for behavior guidance</li>\n<li>Using <code>tool_choice</code> instead of <code>toolChoice</code></li>\n<li>Using <code>tool_calls</code> instead of <code>toolCalls</code> when reading responses</li>\n</ul>\n<p><strong>Common Mistakes:</strong></p>\n<ul>\n<li>Importing from <code>\"mistralai\"</code> instead of <code>\"@mistralai/mistralai\"</code> -- the correct package name has the org scope</li>\n<li>Using CommonJS <code>require()</code> -- the package is ESM-only, use <code>import</code> or <code>await import()</code></li>\n<li>Confusing Mistral's <code>imageUrl: \"url\"</code> (flat string) with OpenAI's <code>image_url: { url: \"...\" }</code> (nested object)</li>\n<li>Using <code>client.chat.completions.create()</code> (OpenAI pattern) instead of <code>client.chat.complete()</code> (Mistral pattern)</li>\n<li>Assuming embedding dimensions match OpenAI's -- <code>mistral-embed</code> returns 1024-dimensional vectors, not 1536</li>\n</ul>\n<p><strong>Gotchas &amp; Edge Cases:</strong></p>\n<ul>\n<li>The SDK is ESM-only. In CommonJS projects, you must use <code>const { Mistral } = await import(\"@mistralai/mistralai\")</code>.</li>\n<li>Streaming content may be <code>string | string[]</code> -- cast or check type when writing to stdout.</li>\n<li><code>chat.parse()</code> requires a Zod schema passed to <code>responseFormat</code> -- it does not accept <code>{ type: \"json_object\" }</code>.</li>\n<li>The <code>apiKey</code> constructor option accepts a string OR an async function <code>() =&gt; Promise&lt;string&gt;</code> for dynamic key rotation.</li>\n<li>Model aliases like <code>mistral-large-latest</code> resolve to the latest version of that model tier. Pin to specific versions (e.g., <code>mistral-large-3-25-12</code>) for reproducibility.</li>\n<li><code>toolChoice: \"any\"</code> forces the model to call a tool. <code>toolChoice: \"auto\"</code> lets the model decide. <code>toolChoice: \"none\"</code> prevents tool calls.</li>\n<li><code>parallelToolCalls: false</code> forces sequential tool calling (default <code>true</code> allows parallel).</li>\n<li>FIM endpoint (<code>fim.complete()</code>) uses <code>prompt</code> + <code>suffix</code> parameters, NOT the <code>messages</code> array.</li>\n<li><code>safePrompt: true</code> injects Mistral's safety system prompt before your messages.</li>\n<li>The SDK provides standalone functions (e.g., <code>chatComplete()</code> from <code>\"@mistralai/mistralai/funcs/chatComplete.js\"</code>) for tree-shaking in browser/edge runtimes.</li>\n</ul>\n<p>&lt;/red_flags&gt;</p>\n<hr>\n<p>&lt;critical_reminders&gt;</p>\n<h2>CRITICAL REMINDERS</h2>\n<blockquote>\n<p><strong>All code must follow project conventions in CLAUDE.md</strong> (kebab-case, named exports, import ordering, <code>import type</code>, named constants)</p>\n</blockquote>\n<p><strong>(You MUST use <code>responseFormat</code> (camelCase) in SDK calls -- NOT <code>response_format</code> (snake_case). The SDK uses camelCase property names throughout.)</strong></p>\n<p><strong>(You MUST configure retries explicitly -- the SDK defaults to <code>strategy: \"none\"</code> (no retries), unlike OpenAI's SDK which retries automatically)</strong></p>\n<p><strong>(You MUST consume streaming results with <code>for await (const event of result)</code> and access content via <code>event.data.choices[0]?.delta?.content</code> -- the event shape differs from OpenAI)</strong></p>\n<p><strong>(You MUST never hardcode API keys -- use <code>process.env[\"MISTRAL_API_KEY\"]</code> with the bracket notation the SDK documents)</strong></p>\n<p><strong>(You MUST use <code>client.chat.parse()</code> with a Zod schema for structured outputs -- NOT manual <code>JSON.parse()</code> on completion content)</strong></p>\n<p><strong>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.</strong></p>\n<p>&lt;/critical_reminders&gt;</p>\n","files":[{"path":"examples/chat.md","sizeBytes":5791,"isText":true},{"path":"examples/codestral.md","sizeBytes":4078,"isText":true},{"path":"examples/core.md","sizeBytes":6578,"isText":true},{"path":"examples/embeddings-vision.md","sizeBytes":6101,"isText":true},{"path":"examples/function-calling.md","sizeBytes":6989,"isText":true},{"path":"examples/structured-output.md","sizeBytes":5429,"isText":true},{"path":"reference.md","sizeBytes":10119,"isText":true},{"path":"SKILL.md","sizeBytes":21967,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-29T15:28:15.906041Z","sha256":"3AE5EB4EAF13C9F465F1DA413022C85FBD45D500C1F226EB731963AD0472C356","sizeBytes":23182},"review":null,"source":{"repositoryUrl":"https://github.com/agents-inc/skills","path":"dist/plugins/ai-provider-mistral-sdk/skills/ai-provider-mistral-sdk","license":"MIT","commit":"3a51ef571e996b18294bf776d53dbdad26de0617","subtreeSha":"41E6AA85BC3D462487E1A3F1F8D5F1F5118C7DF861C5A3852F0F6EE98CD630A7","lastSyncedAt":"2026-09-29T15:27:48.914434Z"},"reviewedAt":"2026-09-29T15:29:46.800345Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/ai-provider-mistral-sdk/skills/ai-provider-mistral-sdk"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart"},{"target":"git","command":"git clone https://github.com/agents-inc/skills.git"}]}