Mistral AI Install & Auth

Overview

Set up the official Mistral AI SDK (@mistralai/mistralai for TypeScript, mistralai for Python) and configure authentication for chat completions, embeddings, function calling, vision, and agents.

Prerequisites

• Node.js 18+ or Python 3.9+
• Package manager (npm, pnpm, yarn, or pip)
• Mistral AI account at console.mistral.ai
• API key from La Plateforme (Settings > API Keys)

Instructions

Step 1: Install SDK

Node.js (TypeScript/JavaScript) — ESM only

set -euo pipefail
# npm
npm install @mistralai/mistralai

# pnpm
pnpm add @mistralai/mistralai

# yarn
yarn add @mistralai/mistralai

Python

set -euo pipefail
pip install mistralai

Step 2: Configure Authentication

Environment Variables (Recommended)

# Set in shell
export MISTRAL_API_KEY="your-api-key"

# Or create .env file (add to .gitignore!)
echo 'MISTRAL_API_KEY=your-api-key' >> .env
echo '.env' >> .gitignore

Using dotenv (Node.js)

set -euo pipefail
npm install dotenv

import 'dotenv/config';

Step 3: Verify Connection

TypeScript

import { Mistral } from '@mistralai/mistralai';

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

async function testConnection() {
  try {
    const models = await client.models.list();
    console.log('Connection successful! Available models:');
    for (const model of models.data ?? []) {
      console.log(`  - ${model.id}`);
    }
  } catch (error: any) {
    if (error.status === 401) {
      console.error('Invalid API key. Check your key at console.mistral.ai');
    } else {
      console.error('Connection failed:', error.message);
    }
  }
}

testConnection();

Python

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

def test_connection():
    try:
        models = client.models.list()
        print("Connection successful! Available models:")
        for model in models.data:
            print(f"  - {model.id}")
    except Exception as e:
        print(f"Connection failed: {e}")

test_connection()

Step 4: Production — Secret Manager

// GCP Secret Manager (recommended for production)
import { SecretManagerServiceClient } from '@google-cloud/secret-manager';

const sm =

Mistral AI Local Dev Loop

Overview

Set up a fast, reproducible local development workflow for Mistral AI integrations: project scaffold, environment config, hot reload with tsx, unit tests with Vitest mocking, and integration tests against the live API.

Prerequisites

• Completed mistral-install-auth setup
• Node.js 18+ with npm/pnpm
• MISTRAL_API_KEY set in environment

Instructions

Step 1: Project Structure

my-mistral-project/
├── src/
│   ├── mistral/
│   │   ├── client.ts       # Singleton client
│   │   ├── config.ts       # Config with Zod validation
│   │   └── types.ts        # TypeScript types
│   └── index.ts
├── tests/
│   ├── unit/
│   │   └── mistral.test.ts
│   └── integration/
│       └── mistral.integration.test.ts
├── .env.local              # Local secrets (git-ignored)
├── .env.example            # Template for team
├── tsconfig.json
├── vitest.config.ts
└── package.json

Step 2: Package Configuration

package.json

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:integration": "vitest run tests/integration/",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@mistralai/mistralai": "^1.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "dotenv": "^16.0.0",
    "tsx": "^4.0.0",
    "typescript": "^5.0.0",
    "vitest": "^1.0.0"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Step 3: Environment Setup

# Create environment template
cat > .env.example << 'EOF'
MISTRAL_API_KEY=your-api-key-here
MISTRAL_MODEL=mistral-small-latest
LOG_LEVEL=debug
EOF

cp .env.example .env.local
echo '.env.local' >> .gitignore
echo '.env' >> .gitignore

Step 4: Client Module

// src/mistral/client.ts
import { Mistral } from '@mistralai/mistralai';
import

Mistral AI Migration Deep Dive

Current State

!npm list openai @anthropic-ai/sdk @mistralai/mistralai 2>/dev/null | grep -E "openai|anthropic|mistral" || echo 'No AI SDKs found'

Overview

Comprehensive migration guide from OpenAI or Anthropic to Mistral AI using the adapter pattern with feature-flag controlled rollout. Covers model mapping, API differences, prompt adjustments, validation testing, and rollback procedures.

Prerequisites

• Current AI integration documented
• Mistral AI SDK installed (@mistralai/mistralai)
• Feature flag infrastructure (env vars or LaunchDarkly)
• Rollback plan tested

Migration Complexity

Instructions

Step 1: Assessment — Find All AI Touchpoints

set -euo pipefail
# Count integration points
echo "=== AI Integration Assessment ==="
echo "OpenAI imports: $(grep -r "from 'openai'" src/ --include='*.ts' -l 2>/dev/null | wc -l)"
echo "Anthropic imports: $(grep -r "from '@anthropic'" src/ --include='*.ts' -l 2>/dev/null | wc -l)"
echo "Chat completions: $(grep -r "chat\.completions\|messages\.create" src/ --include='*.ts' -c 2>/dev/null | wc -l)"
echo "Embeddings: $(grep -r "embeddings\.create" src/ --include='*.ts' -c 2>/dev/null | wc -l)"
echo "Streaming: $(grep -r "stream\|for await" src/ --include='*.ts' -c 2>/dev/null | wc -l)"

Step 2: Model Mapping

Instructions

Step 1: Configuration Structure

// config/mistral/base.ts
export interface MistralEnvConfig {
  apiKey: string;
  defaultModel: string;
  timeoutMs: number;
  maxRetries: number;
  debug: boolean;
  cache: { enabled: boolean; ttlMs: number };
  rateLimits: { rpm: number; tpm: number };
}

export const baseConfig: Omit<MistralEnvConfig, 'apiKey'> = {
  defaultModel: 'mistral-small-latest',
  timeoutMs: 30_000,
  maxRetries: 3,
  debug: false,
  cache: { enabled: true, ttlMs: 300_000 },
  rateLimits: { rpm: 60, tpm: 500_000 },
};

Step 2: Per-Environment Configs

// config/mistral/environments.ts
import { baseConfig, type MistralEnvConfig } from './base.js';

const configs: Record<string, Partial<MistralEnvConfig>> = {
  development: {
    debug: true,
    cache: { enabled: false, ttlMs: 60_000 },
    rateLimits: { rpm: 10, tpm: 100_000 },
  },
  staging: {
    cache: { enabled: true, ttlMs: 300_000 },
  },
  production: {
    timeoutMs: 60_000,
    maxRetries: 5,
    cache: { enabled: true, ttlMs: 600_000 },
  },
};

export function getMistralConfig(): MistralEnvConfig {
  const env = detectEnvironment();
  const envConfig = configs[env] ?? {};

  // API key sourced from environment
  const apiKeyVar = {
    development: 'MISTRAL_API_KEY_DEV',
    staging: 'MISTRAL_API_KEY_STAGING',
    production: 'MISTRAL_API_KEY',
  }[env] ?? 'MISTRAL_API_KEY';

  const apiKey = process.env[apiKeyVar] ?? process.env.MISTRAL_API_KEY;
  if (!apiKey) throw new Error(`Mistral API key not set for ${env} (expected ${apiKeyVar})`);

  return { ...baseConfig, ...envConfig, apiKey } as MistralEnvConfig;
}

Step 3: Environment Detection

type Environment = 'development' | 'staging' |

Mistral AI Observability

Overview

Monitor Mistral AI API usage, latency, token consumption, error rates, and costs. Covers instrumented client wrapper, Prometheus metrics, Grafana dashboard panels, alerting rules, and structured logging.

Prerequisites

• Mistral API integration in production
• Prometheus or OpenTelemetry-compatible metrics backend
• Alerting system (Alertmanager, PagerDuty, or similar)

Instructions

Step 1: Instrumented Client Wrapper

import { Mistral } from '@mistralai/mistralai';

const PRICING: Record<string, { input: number; output: number }> = {
  'mistral-small-latest':  { input: 0.10, output: 0.30 },
  'mistral-large-latest':  { input: 0.50, output: 1.50 },
  'codestral-latest':      { input: 0.30, output: 0.90 },
  'mistral-embed':         { input: 0.10, output: 0 },
};

interface MetricsEvent {
  model: string;
  endpoint: string;
  durationMs: number;
  status: 'success' | 'error';
  statusCode?: number;
  inputTokens?: number;
  outputTokens?: number;
  costUsd?: number;
}

function emitMetrics(event: MetricsEvent): void {
  // Push to your metrics backend (Prometheus, Datadog, etc.)
  console.log(JSON.stringify({ type: 'mistral_metric', ...event }));
}

async function instrumentedChat(
  client: Mistral,
  model: string,
  messages: any[],
  options?: any,
) {
  const start = performance.now();
  try {
    const response = await client.chat.complete({ model, messages, ...options });
    const duration = Math.round(performance.now() - start);
    const pricing = PRICING[model] ?? PRICING['mistral-small-latest'];
    const pt = response.usage?.promptTokens ?? 0;
    const ct = response.usage?.completionTokens ?? 0;

    emitMetrics({
      model,
      endpoint: 'chat.complete',
      durationMs: duration,
      status: 'success',
      inputTokens: pt,
      outputTokens: ct,
      costUsd: (pt / 1e6) * pricing.input + (ct / 1e6) * pricing.output,
    });

    return response;
  } catch (error: any) {
    emitMetrics({
      model,
      endpoint: 'chat.complete',
      durationMs: Math.round(performance.now() - start),
      status: 'error',
      statusCode: error.status,
    });
    throw error;
  }
}

Step 2: Prometheus Metrics

// Using prom-client
import { Counter, Histogram, Gauge } from 'prom-client';

const mistralRequests = new Counter({
  name: 'mistral_requests_total',
  help: 'Total Mistral API requests',
  labelNames: ['model', 'endpoint', 'status'],
});

const mistralDuration = new Histogram({
  name: 'mistral_request_duration_ms',
  help: 'Mistral request duration in milliseconds',
  labelNames: ['model', 'endpoint'],
  buckets: [100, 250, 500, 10

Mistral AI Performance Tuning

Overview

Optimize Mistral AI API response times and throughput. Key levers: model selection (Mistral Small ~200ms TTFT vs Large ~500ms), prompt length (fewer tokens = faster), streaming (perceived speed), caching (zero-latency repeats), and concurrent request management.

Prerequisites

• Mistral API integration in production
• Understanding of RPM/TPM limits for your tier
• Application architecture supporting streaming

Instructions

Step 1: Model Selection by Latency Budget

const MODELS_BY_USE_CASE: Record<string, { model: string; ttftMs: string; note: string }> = {
  realtime_chat:     { model: 'mistral-small-latest',  ttftMs: '~200ms',  note: '256k ctx, cheapest' },
  code_completion:   { model: 'codestral-latest',      ttftMs: '~150ms',  note: 'Optimized for code + FIM' },
  code_agents:       { model: 'devstral-latest',       ttftMs: '~300ms',  note: 'Agentic coding tasks' },
  reasoning:         { model: 'mistral-large-latest',  ttftMs: '~500ms',  note: '256k ctx, strongest' },
  vision:            { model: 'pixtral-large-latest',  ttftMs: '~600ms',  note: 'Image + text multimodal' },
  embeddings:        { model: 'mistral-embed',         ttftMs: '~50ms',   note: '1024-dim, batch-friendly' },
  edge_devices:      { model: 'ministral-latest',      ttftMs: '~100ms',  note: '3B-14B, fastest' },
};

Step 2: Streaming for User-Facing Responses

Streaming reduces perceived latency from 1-2s (full response) to ~200ms (first token):

import { Mistral } from '@mistralai/mistralai';

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

async function* streamChat(messages: any[], model = 'mistral-small-latest') {
  const stream = await client.chat.stream({ model, messages });
  for await (const chunk of stream) {
    const content = chunk.data?.choices?.[0]?.delta?.content;
    if (content) yield content;
  }
}

// Web Response with SSE
function streamToSSE(messages: any[]): Response {
  const encoder = new TextEncoder();
  const readable = new ReadableStream({
    async start(controller) {
      for await (const text of streamChat(messages)) {
        controller.enqueue(encoder.encode(`data: ${JSON.stringify({ text })}\n\n`));
      }
      controller.enqueue(encoder.encode('data: [DONE]\n\n'));
      controller.close();
    },
  });
  return new Response(readable, {
    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
  });
}

Step 3: Response Caching

import { createHash } from 'crypto';
import { LRUCache } fr

Mistral AI Production Checklist

Overview

Complete checklist for deploying Mistral AI integrations to production. Covers credential management, code quality gates, health endpoints, circuit breaker resilience, gradual rollout, and rollback procedures.

Prerequisites

• Staging environment tested and verified
• Production API keys from La Plateforme
• Deployment pipeline (CI/CD) configured
• Monitoring and alerting ready (see mistral-observability)

Instructions

Step 1: Pre-Deployment Verification

Credentials

• [ ] Production API key stored in secret manager (never in env files or code)
• [ ] Key tested with curl -H "Authorization: Bearer $KEY" https://api.mistral.ai/v1/models
• [ ] Key has appropriate model access scope
• [ ] Fallback key available for rotation

Code Quality

• [ ] npm run typecheck passes
• [ ] npm test passes (unit + integration)
• [ ] No hardcoded keys: grep -r "MISTRAL_API_KEY\|sk-" src/ --include="*.ts"
• [ ] Error handling covers 401, 429, 500+ status codes
• [ ] Rate limiting/backoff implemented
• [ ] Logging excludes message content and API keys

Model Configuration

• [ ] Using versioned model IDs or -latest aliases intentionally
• [ ] maxTokens set to prevent runaway costs
• [ ] temperature set appropriately (0 for deterministic, 0.7 for creative)
• [ ] Token budget alerts configured

Step 2: Health Check Endpoint

import { Mistral } from '@mistralai/mistralai';

interface HealthStatus {
  status: 'healthy' | 'degraded' | 'unhealthy';
  provider: 'mistral';
  latencyMs: number;
  model?: string;
  error?: string;
}

export async function checkHealth(): Promise<HealthStatus> {
  const start = performance.now();
  try {
    const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY! });
    const models = await client.models.list();
    const latencyMs = Math.round(performance.now() - start);

    return {
      status: latencyMs > 5000 ? 'degraded' : 'healthy',
      provider: 'mistral',
      latencyMs,
      model: models.data?.[0]?.id,
    };
  } catch (error: any) {
    return {
      status: 'unhealthy',
      provider: 'mistral',
      latencyMs: Math.round(performance.now() - start),
      error: error.message,
    };
  }
}

// Express route
app.get('/health', async (req, res) => {
  const health = await checkHealth();
  res.status(health.status === 'unhealthy' ? 503 : 200).json(health);
});

Step 3: Circuit Breaker