# Mistral SDK -- Chat & Streaming Examples

> Chat completions, streaming with async iteration, multi-turn conversations, and token tracking. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [core.md](core.md) -- Client setup, error handling
- [structured-output.md](structured-output.md) -- Structured outputs with Zod
- [function-calling.md](function-calling.md) -- Tool/function calling
- [embeddings-vision.md](embeddings-vision.md) -- Embeddings and vision
- [codestral.md](codestral.md) -- Codestral FIM code completion

---

## Basic Chat Completion

```typescript
// basic-chat.ts
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

async function chat(userMessage: string): Promise<string> {
  const result = await client.chat.complete({
    model: "mistral-large-latest",
    messages: [
      { role: "system", content: "You are a helpful assistant. Be concise." },
      { role: "user", content: userMessage },
    ],
  });

  const content = result?.choices?.[0]?.message?.content;
  if (!content) {
    throw new Error("No content in response");
  }

  // Log token usage
  if (result.usage) {
    console.log(`Tokens: ${result.usage.totalTokens}`);
  }

  return typeof content === "string" ? content : content.join("");
}

const answer = await chat("What is TypeScript in one sentence?");
console.log(answer);
```

**Why good:** Safe optional chaining on nullable fields, handles `content` being `string | string[]`, token tracking

---

## Streaming with Async Iteration

```typescript
// streaming-chat.ts
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

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." },
  ],
});

// IMPORTANT: events wrap data in event.data -- not directly on event
for await (const event of result) {
  const content = event.data.choices[0]?.delta?.content;
  if (content) {
    // content may be string | string[] depending on model
    process.stdout.write(
      typeof content === "string" ? content : content.join(""),
    );
  }
}
console.log(); // newline
```

**Why good:** Accesses `event.data.choices[0]` (not `event.choices[0]`), handles string union type

### BAD: OpenAI-style streaming (wrong for Mistral)

```typescript
// BAD: Trying OpenAI's event shape
for await (const chunk of result) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? ""); // WRONG: no .data wrapper
}
```

**Why bad:** Mistral wraps streaming data in `event.data` -- accessing `chunk.choices` directly fails silently or throws

---

## Multi-Turn Conversation

```typescript
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

interface ChatMessage {
  role: "system" | "user" | "assistant";
  content: string;
}

const messages: ChatMessage[] = [
  { role: "system", content: "You are a TypeScript expert." },
  { role: "user", content: "What is a union type?" },
];

const first = await client.chat.complete({
  model: "mistral-large-latest",
  messages,
});

const firstContent = first?.choices?.[0]?.message?.content;
if (firstContent) {
  // Append assistant response for next turn
  messages.push({
    role: "assistant",
    content:
      typeof firstContent === "string" ? firstContent : firstContent.join(""),
  });
  messages.push({ role: "user", content: "Give me a real-world example." });

  const followUp = await client.chat.complete({
    model: "mistral-large-latest",
    messages,
  });

  console.log(followUp?.choices?.[0]?.message?.content);
}
```

---

## Controlling Output Length and Temperature

```typescript
const MAX_TOKENS = 500;

const result = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [{ role: "user", content: "Summarize this article." }],
  maxTokens: MAX_TOKENS,
  temperature: 0, // Deterministic output
});

const finishReason = result?.choices?.[0]?.finishReason;
if (finishReason === "length") {
  console.warn("Output was truncated -- increase maxTokens");
}
```

**Why good:** Uses `maxTokens` (camelCase), checks `finishReason` (camelCase) for truncation

---

## Token Usage Tracking

```typescript
const result = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [{ role: "user", content: "Hello" }],
});

const usage = result?.usage;
if (usage) {
  console.log(`Prompt tokens: ${usage.promptTokens}`);
  console.log(`Completion tokens: ${usage.completionTokens}`);
  console.log(`Total tokens: ${usage.totalTokens}`);
}
```

**Why good:** Uses camelCase properties (`promptTokens`, not `prompt_tokens`)

---

## Streaming with Abort

```typescript
const controller = new AbortController();
const ABORT_TIMEOUT_MS = 5_000;

setTimeout(() => controller.abort(), ABORT_TIMEOUT_MS);

try {
  const result = await client.chat.stream(
    {
      model: "mistral-large-latest",
      messages: [{ role: "user", content: "Tell me a long story." }],
    },
    {
      fetchOptions: { signal: controller.signal },
    },
  );

  for await (const event of result) {
    const content = event.data.choices[0]?.delta?.content;
    if (content) {
      process.stdout.write(
        typeof content === "string" ? content : content.join(""),
      );
    }
  }
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    console.log("\nStream aborted");
  } else {
    throw error;
  }
}
```

---

_For core concepts, see [SKILL.md](../SKILL.md). For API reference tables, see [reference.md](../reference.md)._

# Mistral SDK -- Codestral FIM Examples

> Fill-in-middle code completion and code generation with Codestral. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [core.md](core.md) -- Client setup, error handling
- [chat.md](chat.md) -- Chat completions and streaming
- [structured-output.md](structured-output.md) -- Structured outputs with Zod
- [function-calling.md](function-calling.md) -- Tool/function calling
- [embeddings-vision.md](embeddings-vision.md) -- Embeddings and vision

---

## Basic Fill-in-Middle (FIM)

```typescript
// fim-completion.ts
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

// FIM: provide code before (prompt) and after (suffix) the cursor
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;
console.log("Generated code:", completion);
// The model fills in the gap: "  return fibonacci(n - 1) + fibonacci(n - 2);\n"
```

**Why good:** Uses dedicated `fim.complete()` endpoint (not chat), separate `prompt` + `suffix`, deterministic with `temperature: 0`

---

## FIM with Stop Sequences

```typescript
const result = await client.fim.complete({
  model: "codestral-latest",
  prompt: "class UserService {\n  private users: User[] = [];\n\n  ",
  suffix: "\n\n  getUsers(): User[] {\n    return this.users;\n  }\n}",
  temperature: 0,
  stop: ["\n\n"], // Stop at double newline to prevent over-generation
});

const code = result.choices?.[0]?.message?.content;
console.log(code);
```

---

## FIM vs Chat for Code Generation

Use FIM when you have surrounding code context. Use chat when you need full function generation from a description.

```typescript
// FIM: filling a gap in existing code
const fimResult = await client.fim.complete({
  model: "codestral-latest",
  prompt: "const sorted = array.",
  suffix: ";\nconsole.log(sorted);",
  temperature: 0,
});
// Model completes: "sort((a, b) => a - b)"

// Chat: generating from a description
const chatResult = await client.chat.complete({
  model: "codestral-latest",
  messages: [
    {
      role: "system",
      content:
        "You are a TypeScript code generator. Return only code, no explanations.",
    },
    {
      role: "user",
      content:
        "Write a function that sorts an array of numbers in ascending order.",
    },
  ],
  temperature: 0,
});
```

**When to use FIM:** IDE autocomplete, code insertion at cursor position, completing partial code
**When to use Chat:** Generating entire functions, explaining code, code review

---

## Code Completion with Max Tokens

```typescript
const MAX_COMPLETION_TOKENS = 200;

const result = await client.fim.complete({
  model: "codestral-latest",
  prompt: "async function fetchUsers(): Promise<User[]> {\n  ",
  suffix: "\n}",
  temperature: 0,
  maxTokens: MAX_COMPLETION_TOKENS,
});

const finishReason = result.choices?.[0]?.finishReason;
if (finishReason === "length") {
  console.warn("Code completion was truncated -- increase maxTokens");
}
```

---

## Code Embeddings with Codestral Embed

For code-specific semantic search, use `codestral-embed-latest` instead of `mistral-embed`.

```typescript
const CODE_EMBEDDING_MODEL = "codestral-embed-latest";

const result = await client.embeddings.create({
  model: CODE_EMBEDDING_MODEL,
  inputs: [
    "function add(a: number, b: number): number { return a + b; }",
    "const sum = (x: number, y: number): number => x + y;",
    "class Calculator { add(a: number, b: number) { return a + b; } }",
  ],
});

// Use for code search, duplicate detection, or semantic code navigation
const vectors = result.data?.map((item) => item.embedding) ?? [];
console.log(`Generated ${vectors.length} code embeddings`);
```

---

_For core concepts, see [SKILL.md](../SKILL.md). For API reference tables, see [reference.md](../reference.md)._

# Mistral SDK -- Setup & Configuration Examples

> Client initialization, environment config, production settings, error handling, custom HTTP client, and retry configuration. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [chat.md](chat.md) -- Chat completions and streaming
- [structured-output.md](structured-output.md) -- Structured outputs with Zod
- [function-calling.md](function-calling.md) -- Tool/function calling
- [embeddings-vision.md](embeddings-vision.md) -- Embeddings and vision
- [codestral.md](codestral.md) -- Codestral FIM code completion

---

## Basic Client Setup

```typescript
// lib/mistral.ts
import { Mistral } from "@mistralai/mistralai";

// Reads MISTRAL_API_KEY from env
const client = new Mistral({
  apiKey: process.env["MISTRAL_API_KEY"] ?? "",
});

export { client };
```

---

## Production Configuration

```typescript
// lib/mistral.ts
import { Mistral } from "@mistralai/mistralai";

const TIMEOUT_MS = 30_000;
const INITIAL_RETRY_INTERVAL_MS = 1_000;
const MAX_RETRY_INTERVAL_MS = 30_000;
const RETRY_EXPONENT = 1.5;
const MAX_ELAPSED_TIME_MS = 120_000;

const client = new Mistral({
  apiKey: process.env["MISTRAL_API_KEY"] ?? "",
  timeoutMs: TIMEOUT_MS,
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: INITIAL_RETRY_INTERVAL_MS,
      maxInterval: MAX_RETRY_INTERVAL_MS,
      exponent: RETRY_EXPONENT,
      maxElapsedTime: MAX_ELAPSED_TIME_MS,
    },
    retryConnectionErrors: true,
  },
});

export { client };
```

**Why good:** Explicit retry config (SDK defaults to zero retries), named constants, sensible backoff curve

---

## Async API Key Provider

```typescript
// lib/mistral.ts -- dynamic key rotation
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({
  apiKey: async () => {
    // Fetch from secrets manager, vault, or key rotation service
    return await getSecureApiKey();
  },
  timeoutMs: 30_000,
});

export { client };
```

**Why good:** Supports key rotation without restarting the process -- the SDK calls the function before each request

---

## Custom HTTP Client with Hooks

```typescript
// lib/mistral.ts -- custom HTTP client
import { Mistral } from "@mistralai/mistralai";
import { HTTPClient } from "@mistralai/mistralai/lib/http";

const REQUEST_TIMEOUT_MS = 10_000;

const httpClient = new HTTPClient({
  fetcher: (request) => fetch(request),
});

// Add timeout to every request
httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(REQUEST_TIMEOUT_MS),
  });
  nextRequest.headers.set("x-custom-header", "custom-value");
  return nextRequest;
});

// Log errors
httpClient.addHook("requestError", (error, request) => {
  console.error(
    `Mistral request failed: ${request.method} ${request.url}`,
    error,
  );
});

const client = new Mistral({
  httpClient,
  apiKey: process.env["MISTRAL_API_KEY"] ?? "",
});

export { client };
```

---

## Production Error Handling

```typescript
// error-handling.ts
import { Mistral } from "@mistralai/mistralai";
import {
  SDKError,
  SDKValidationError,
  HTTPValidationError,
} from "@mistralai/mistralai/models/errors";

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: 60_000,
    },
    retryConnectionErrors: true,
  },
});

async function safeCompletion(prompt: string): Promise<string | null> {
  try {
    const result = await client.chat.complete({
      model: "mistral-large-latest",
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: prompt },
      ],
    });

    const content = result?.choices?.[0]?.message?.content;
    if (!content) {
      console.warn("No content in response");
      return null;
    }

    // Log token usage for cost tracking
    if (result.usage) {
      console.log(
        `Tokens: prompt=${result.usage.promptTokens}, completion=${result.usage.completionTokens}, total=${result.usage.totalTokens}`,
      );
    }

    return typeof content === "string" ? content : content.join("");
  } catch (error) {
    if (error instanceof HTTPValidationError) {
      // 422 -- invalid request shape
      console.error("Validation error:", error.message);
      return null;
    }

    if (error instanceof SDKValidationError) {
      // Client-side input validation failure
      console.error("Input validation error:", error.message);
      return null;
    }

    if (error instanceof SDKError) {
      // General API error (4xx, 5xx)
      console.error(`API error [${error.statusCode}]: ${error.message}`);

      if (error.statusCode === 401) {
        throw new Error(
          "Invalid API key. Check MISTRAL_API_KEY environment variable.",
        );
      }

      if (error.statusCode === 429) {
        console.error("Rate limited. Retries exhausted.");
        return null;
      }

      return null;
    }

    // Unknown errors should be re-thrown
    throw error;
  }
}

const result = await safeCompletion("Hello!");
if (result) {
  console.log(result);
} else {
  console.error("Failed to get completion");
}
```

---

## Per-Request Override

```typescript
// Override retries and timeout for a single request
const result = await client.chat.complete(
  {
    model: "mistral-large-latest",
    messages: [{ role: "user", content: "Quick question" }],
  },
  {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 500,
        maxInterval: 5_000,
        exponent: 2,
        maxElapsedTime: 15_000,
      },
    },
    fetchOptions: {
      signal: AbortSignal.timeout(10_000),
    },
  },
);
```

---

## Debug Logging

```typescript
// Enable via environment variable
// MISTRAL_DEBUG=true node app.js

// Or via constructor
const client = new Mistral({
  apiKey: process.env["MISTRAL_API_KEY"] ?? "",
  debugLogger: console,
});

// Or with a custom logger
const client = new Mistral({
  apiKey: process.env["MISTRAL_API_KEY"] ?? "",
  debugLogger: {
    log: (msg: string) => logger.info(msg),
    error: (msg: string) => logger.error(msg),
    warn: (msg: string) => logger.warn(msg),
    debug: (msg: string) => logger.debug(msg),
  },
});
```

---

_For core concepts, see [SKILL.md](../SKILL.md). For API reference tables, see [reference.md](../reference.md)._

# Mistral SDK -- Embeddings & Vision Examples

> Embeddings for semantic search and vision/image inputs with vision-capable models. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [core.md](core.md) -- Client setup, error handling
- [chat.md](chat.md) -- Chat completions and streaming
- [structured-output.md](structured-output.md) -- Structured outputs with Zod
- [function-calling.md](function-calling.md) -- Tool/function calling
- [codestral.md](codestral.md) -- Codestral FIM code completion

---

## Embeddings and Semantic Search

```typescript
// embeddings.ts
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

const EMBEDDING_MODEL = "mistral-embed";
const SIMILARITY_THRESHOLD = 0.7;
const TOP_K = 3;

function cosineSimilarity(a: number[], b: number[]): number {
  let dot = 0;
  let normA = 0;
  let normB = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

// Index documents -- batch multiple inputs in one call
const documents = [
  "TypeScript provides static type checking for JavaScript.",
  "React is a library for building user interfaces.",
  "Node.js is a JavaScript runtime built on V8.",
  "PostgreSQL is a powerful relational database.",
  "Docker containers package applications with dependencies.",
];

const docEmbeddings = await client.embeddings.create({
  model: EMBEDDING_MODEL,
  inputs: documents, // NOTE: 'inputs' (plural), not 'input'
});

const indexedDocs = documents.map((text, i) => ({
  text,
  embedding: docEmbeddings.data?.[i]?.embedding ?? [],
}));

// Search
async function search(
  query: string,
): Promise<Array<{ text: string; score: number }>> {
  const queryEmbedding = await client.embeddings.create({
    model: EMBEDDING_MODEL,
    inputs: [query],
  });

  const queryVector = queryEmbedding.data?.[0]?.embedding ?? [];

  return indexedDocs
    .map((doc) => ({
      text: doc.text,
      score: cosineSimilarity(queryVector, doc.embedding),
    }))
    .filter((r) => r.score > SIMILARITY_THRESHOLD)
    .sort((a, b) => b.score - a.score)
    .slice(0, TOP_K);
}

const results = await search("What is TypeScript?");
results.forEach((r) => {
  console.log(`[${r.score.toFixed(3)}] ${r.text}`);
});
```

**Why good:** Uses `inputs` (plural, Mistral-specific), batches documents in one call, named constants

---

## Embedding Gotchas

```typescript
// GOOD: Mistral uses 'inputs' (plural)
const result = await client.embeddings.create({
  model: "mistral-embed",
  inputs: ["text to embed"],
});
// Returns 1024-dimensional vectors

// BAD: OpenAI uses 'input' (singular), dimensions differ
const result = await client.embeddings.create({
  model: "mistral-embed",
  input: ["text to embed"], // WRONG: use 'inputs'
});
// OpenAI returns 1536 dimensions, Mistral returns 1024
```

**Why bad:** Wrong parameter name, wrong dimension expectations when migrating from OpenAI

---

## Vision -- Image from URL

```typescript
// vision.ts
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

async function analyzeImageUrl(
  imageUrl: string,
  question: string,
): Promise<string> {
  const result = await client.chat.complete({
    model: "mistral-small-latest", // Vision-capable model
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: question },
          {
            type: "image_url",
            imageUrl: imageUrl, // NOTE: flat string, not { url: "..." }
          },
        ],
      },
    ],
  });

  const content = result?.choices?.[0]?.message?.content;
  return typeof content === "string" ? content : (content?.join("") ?? "");
}

const description = await analyzeImageUrl(
  "https://example.com/photo.jpg",
  "Describe what you see in this image.",
);
console.log(description);
```

**Why good:** Uses `imageUrl` (camelCase, flat string) -- NOT OpenAI's `image_url: { url: "..." }` nested object

---

## Vision -- Local Image (Base64)

```typescript
import { Mistral } from "@mistralai/mistralai";
import { readFileSync } from "node:fs";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

async function analyzeLocalImage(
  imagePath: string,
  question: string,
): Promise<string> {
  const imageBuffer = readFileSync(imagePath);
  const base64Image = imageBuffer.toString("base64");
  const mimeType = imagePath.endsWith(".png") ? "image/png" : "image/jpeg";

  const result = await client.chat.complete({
    model: "mistral-small-latest",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: question },
          {
            type: "image_url",
            imageUrl: `data:${mimeType};base64,${base64Image}`,
          },
        ],
      },
    ],
  });

  const content = result?.choices?.[0]?.message?.content;
  return typeof content === "string" ? content : (content?.join("") ?? "");
}
```

---

## Vision -- Multiple Images

```typescript
const result = await client.chat.complete({
  model: "mistral-small-latest",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Compare these two images." },
        {
          type: "image_url",
          imageUrl: "https://example.com/image1.jpg",
        },
        {
          type: "image_url",
          imageUrl: "https://example.com/image2.jpg",
        },
      ],
    },
  ],
});
```

---

## Vision Model Selection

```
Vision-capable models (as of 2026):
- mistral-small-latest (Mistral Small 4)
- mistral-medium-latest (Mistral Medium 3.1)
- mistral-large-latest (Mistral Large 3)
- ministral-14b-latest, ministral-8b-latest, ministral-3b-latest (Ministral 3)
```

Most current Mistral models support vision. Use `mistral-small-latest` for cost-efficient image analysis.

---

_For core concepts, see [SKILL.md](../SKILL.md). For API reference tables, see [reference.md](../reference.md)._

# Mistral SDK -- Function Calling Examples

> Tool definitions, tool call loop, parallel tool calls, streaming function calling. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [core.md](core.md) -- Client setup, error handling
- [chat.md](chat.md) -- Chat completions and streaming
- [structured-output.md](structured-output.md) -- Structured outputs with Zod
- [embeddings-vision.md](embeddings-vision.md) -- Embeddings and vision
- [codestral.md](codestral.md) -- Codestral FIM code completion

---

## Basic Function Calling

```typescript
// function-calling.ts
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

const tools = [
  {
    type: "function" as const,
    function: {
      name: "get_weather",
      description: "Get the current weather for a location",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string", description: "City name" },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
            description: "Temperature unit",
          },
        },
        required: ["location"],
      },
    },
  },
];

const result = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [{ role: "user", content: "What is the weather in Paris?" }],
  tools,
  toolChoice: "any", // Forces tool use
});

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);
  console.log(`Tool call ID: ${toolCall.id}`);
}
```

**Why good:** Uses `toolChoice` (camelCase), `toolCalls` (camelCase), `as const` for type literal, checks for tool calls

---

## Complete Tool Call Loop

The standard pattern: send message with tools -> get tool calls -> execute -> send results back.

```typescript
// tool-loop.ts
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

// Tool implementations
async function getWeather(args: {
  location: string;
  unit?: string;
}): Promise<string> {
  return JSON.stringify({
    location: args.location,
    temperature: 22,
    unit: args.unit ?? "celsius",
    condition: "sunny",
  });
}

async function searchDatabase(args: { query: string }): Promise<string> {
  return JSON.stringify({
    results: [{ id: 1, title: `Result for: ${args.query}` }],
  });
}

const toolImplementations: Record<
  string,
  (args: Record<string, unknown>) => Promise<string>
> = {
  get_weather: getWeather as (args: Record<string, unknown>) => Promise<string>,
  search_database: searchDatabase as (
    args: Record<string, unknown>,
  ) => Promise<string>,
};

const tools = [
  {
    type: "function" as const,
    function: {
      name: "get_weather",
      description: "Get current weather for a location",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string", description: "City name" },
          unit: { type: "string", enum: ["celsius", "fahrenheit"] },
        },
        required: ["location"],
      },
    },
  },
  {
    type: "function" as const,
    function: {
      name: "search_database",
      description: "Search the knowledge base",
      parameters: {
        type: "object",
        properties: {
          query: { type: "string", description: "Search query" },
        },
        required: ["query"],
      },
    },
  },
];

interface ChatMessage {
  role: "system" | "user" | "assistant" | "tool";
  content: string;
  name?: string;
  toolCallId?: string;
  toolCalls?: Array<{
    id: string;
    function: { name: string; arguments: string };
  }>;
}

const MAX_TOOL_ITERATIONS = 5;

const messages: ChatMessage[] = [
  {
    role: "system",
    content: "You help users with weather and search queries.",
  },
  {
    role: "user",
    content: "What is the weather in London and search for TypeScript guides?",
  },
];

let iterations = 0;

while (iterations < MAX_TOOL_ITERATIONS) {
  const result = await client.chat.complete({
    model: "mistral-large-latest",
    messages,
    tools,
  });

  const choice = result?.choices?.[0];
  if (!choice) break;

  const assistantMessage = choice.message;

  // Check if the model wants to call tools
  if (!assistantMessage?.toolCalls || assistantMessage.toolCalls.length === 0) {
    // No tool calls -- model has a final answer
    console.log("Final answer:", assistantMessage?.content);
    break;
  }

  // Add assistant message with tool calls to history
  messages.push({
    role: "assistant",
    content:
      typeof assistantMessage.content === "string"
        ? assistantMessage.content
        : "",
    toolCalls: assistantMessage.toolCalls.map((tc) => ({
      id: tc.id ?? "",
      function: { name: tc.function.name, arguments: tc.function.arguments },
    })),
  });

  // Execute each tool call and add results
  for (const toolCall of assistantMessage.toolCalls) {
    const fnName = toolCall.function.name;
    const args = JSON.parse(toolCall.function.arguments);
    console.log(`Calling ${fnName}(${JSON.stringify(args)})`);

    const impl = toolImplementations[fnName];
    if (!impl) {
      throw new Error(`Unknown tool: ${fnName}`);
    }

    const toolResult = await impl(args);

    messages.push({
      role: "tool",
      name: fnName,
      content: toolResult,
      toolCallId: toolCall.id ?? "",
    });
  }

  iterations++;
}
```

**Why good:** Bounded loop with MAX_TOOL_ITERATIONS, proper tool message format with `toolCallId`, handles parallel tool calls

---

## Tool Choice Options

```typescript
// "auto" (default) -- model decides whether to call tools
const result1 = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [{ role: "user", content: "Hello" }],
  tools,
  toolChoice: "auto",
});

// "any" -- forces the model to call at least one tool
const result2 = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [{ role: "user", content: "Get weather in Tokyo" }],
  tools,
  toolChoice: "any",
});

// "none" -- prevents any tool calls
const result3 = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [{ role: "user", content: "Tell me about weather" }],
  tools,
  toolChoice: "none",
});
```

---

## Sequential Tool Calls

```typescript
// Force sequential tool calling (disable parallel calls)
const result = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [{ role: "user", content: "Weather in Paris and London?" }],
  tools,
  parallelToolCalls: false, // Forces sequential -- model calls one tool at a time
});
```

**Why good:** `parallelToolCalls: false` ensures tools are called one at a time, useful for dependent operations

---

_For core concepts, see [SKILL.md](../SKILL.md). For API reference tables, see [reference.md](../reference.md)._

# Mistral SDK -- Structured Output Examples

> Type-safe structured responses with Zod via `chat.parse()`, and JSON mode via `responseFormat`. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [core.md](core.md) -- Client setup, error handling
- [chat.md](chat.md) -- Chat completions and streaming
- [function-calling.md](function-calling.md) -- Tool/function calling
- [embeddings-vision.md](embeddings-vision.md) -- Embeddings and vision
- [codestral.md](codestral.md) -- Codestral FIM code completion

---

## Structured Output with `chat.parse()` and Zod

```typescript
// structured-output.ts
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

const ArticleSummary = z.object({
  title: z.string(),
  summary: z.string(),
  keyPoints: z.array(z.string()),
  sentiment: z.enum(["positive", "negative", "neutral"]),
});

type ArticleSummary = z.infer<typeof ArticleSummary>;

const MAX_TOKENS = 512;

async function extractSummary(
  articleText: string,
): Promise<ArticleSummary | null> {
  const result = await client.chat.parse({
    model: "mistral-large-latest",
    messages: [
      {
        role: "system",
        content: "Extract a structured summary from the article.",
      },
      { role: "user", content: articleText },
    ],
    responseFormat: ArticleSummary, // Pass Zod schema directly
    maxTokens: MAX_TOKENS,
    temperature: 0,
  });

  // Access the typed parsed result
  const parsed = result.choices?.[0]?.message?.parsed;
  return parsed ?? null;
}

const article = `
TypeScript 5.8 brings improved type inference, better error messages,
and performance optimizations focused on developer experience.
`;

const summary = await extractSummary(article);
if (summary) {
  console.log(`Title: ${summary.title}`);
  console.log(`Sentiment: ${summary.sentiment}`);
  console.log("Key Points:");
  summary.keyPoints.forEach((point) => console.log(`  - ${point}`));
}
```

**Why good:** Zod schema passed directly to `responseFormat`, `message.parsed` is fully typed, named constants

---

## JSON Mode (Simple)

When you need JSON output without strict schema validation, use `responseFormat: { type: "json_object" }`.

```typescript
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

const result = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [
    {
      role: "user",
      content:
        "List the top 3 programming languages with their use cases. Return as JSON.",
    },
  ],
  responseFormat: { type: "json_object" },
});

const content = result?.choices?.[0]?.message?.content;
if (typeof content === "string") {
  const data = JSON.parse(content);
  console.log(data);
}
```

**Why good:** Uses `responseFormat` (camelCase), explicitly asks for JSON in the prompt (recommended even with JSON mode)

### BAD: snake_case response_format

```typescript
// BAD: Using REST API naming in the SDK
const result = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [{ role: "user", content: "Return JSON" }],
  response_format: { type: "json_object" }, // WRONG: silently ignored
});
```

**Why bad:** The SDK uses camelCase -- `response_format` is silently ignored, model returns plain text

---

## Complex Schema with Nested Objects

```typescript
import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";

const client = new Mistral({ apiKey: process.env["MISTRAL_API_KEY"] ?? "" });

const Address = z.object({
  street: z.string(),
  city: z.string(),
  country: z.string(),
  postalCode: z.string(),
});

const Person = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email(),
  addresses: z.array(Address),
  occupation: z.string().optional(),
});

const MAX_TOKENS = 512;

const result = await client.chat.parse({
  model: "mistral-large-latest",
  messages: [
    { role: "system", content: "Extract person details from the text." },
    {
      role: "user",
      content:
        "John Smith, 34, works as a software engineer. " +
        "Email: john@example.com. Lives at 123 Main St, Paris, France 75001.",
    },
  ],
  responseFormat: Person,
  maxTokens: MAX_TOKENS,
  temperature: 0,
});

const person = result.choices?.[0]?.message?.parsed;
if (person) {
  console.log(`${person.name}, age ${person.age}`);
  console.log(`Email: ${person.email}`);
  person.addresses.forEach((addr) => {
    console.log(`Address: ${addr.street}, ${addr.city}, ${addr.country}`);
  });
}
```

---

## Accessing Raw vs Parsed Content

```typescript
const result = await client.chat.parse({
  model: "mistral-large-latest",
  messages: [
    { role: "system", content: "Extract book information." },
    { role: "user", content: "I read 'Dune' by Frank Herbert." },
  ],
  responseFormat: z.object({
    name: z.string(),
    authors: z.array(z.string()),
  }),
});

const message = result.choices?.[0]?.message;

// Raw JSON string (always available)
console.log("Raw:", message?.content);

// Parsed and typed object (available via chat.parse)
console.log("Parsed:", message?.parsed);
```

**Why good:** Shows both access paths -- `content` for raw JSON, `parsed` for typed object

---

_For core concepts, see [SKILL.md](../SKILL.md). For API reference tables, see [reference.md](../reference.md)._