api-ai-mistral-sdk

What it does

Guides developers on using the Mistral SDK in TypeScript, detailing how to initialize the client, perform chat completions and streaming, parse structured outputs with Zod, handle function calling with a tool loop, create embeddings, process vision tasks with Pixtral, and use Codestral FIM. It presents concrete method names and patterns to implement production-ready interactions with Mistral models.

How it works

• Client initialization examples show reading the API key from an environment variable and optional production configuration with timeout and retryConfig.
• Chat completions use chat.complete() with a model like mistral-large-latest and a messages array; streaming uses chat.stream() with an async iteration pattern and accesses event.data.choices[0]?.delta?.content for content.
• Structured outputs employ chat.parse() with a Zod schema passed via responseFormat and access result.choices?.[0]?.message?.parsed for typed results.
• Function calling demonstrates defining tools, using toolChoice, and inspecting toolCalls to extract function arguments.
• Embeddings are created with embeddings.create using inputs plural, and the resulting embeddings are read from result.data.
• Vision patterns show sending image references via imageUrl within messages.
• Codestral FIM uses fim.complete() with prompt and suffix to produce a completion.
• Error handling and production patterns emphasize explicit retry configuration, timeout usage, and specific error types.

When to use it

• Building applications that call Mistral models directly
• Implementing chat completions with SSE streaming
• Using Codestral for code generation and FIM
• 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 Pixtral / vision-capable models
• Using Mistral Agents API for pre-configured agent completions

What it can touch

• @mistralai/mistralai SDK usage including client.chat.complete, client.chat.stream, client.chat.parse, client.fim.complete, and client.embeddings.create.
• Environment variable MISTRAL_API_KEY for authentication.
• Zod schemas passed to responseFormat for structured outputs.
• Tool definitions and toolCalls handling in the tool call loop.

Caveats

• The SDK defaults to strategy: "none" for retries; retries must be configured explicitly for production.
• Streaming results must be consumed with for await (const event of result) and access content via event.data.choices[0]?.delta?.content.
• Do not use snake_case properties; the patterns require camelCase (e.g., responseFormat, maxTokens).
• Keys must be read from process.env["MISTRAL_API_KEY"] using bracket notation.