mistral-migration-deep-dive

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

Migration	Effort	Duration	Risk
Fresh install (no existing AI)	Low	Days	Low
OpenAI to Mistral	Medium	1-2 weeks	Medium
Anthropic to Mistral	Medium	1-2 weeks	Medium
Multi-provider to Mistral	High	2-4 weeks	Medium

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

OpenAI	Anthropic	Mistral	Notes
gpt-4o	claude-3-5-sonnet	mistral-large-latest	Complex reasoning
gpt-4o-mini	claude-3-5-haiku	mistral-small-latest	Fast, cheap
gpt-3.5-turbo	—	mistral-small-latest	General purpose
text-embedding-3-small	—	mistral-embed	1024 dims (vs 1536)
—	—	codestral-latest	Code-specialized
gpt-4-vision	claude-3-5-sonnet	pixtral-large-latest	Vision + text

Step 3: Provider-Agnostic Adapter

// adapters/types.ts
export interface Message {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string;
}

export interface ChatOptions {
  model?: string;
  temperature?: number;
  maxTokens?: number;
  stream?: boolean;
}

export interface ChatResponse {
  content: string;
  usage: { inputTokens: number; outputTokens: number };
  model: string;
}

export interface AIAdapter {
  chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse>;
  chatStream(messages: Message[], options?: ChatOptions): AsyncGenerator<string>;
  embed(texts: string[]): Promise<number[][]>;
}

Step 4: Mistral Adapter

// adapters/mistral.adapter.ts
import { Mistral } from '@mistralai/mistralai';
import type { AIAdapter, Message, ChatOptions, ChatResponse } from './types.js';

export class MistralAdapter implements AIAdapter {
  private client: Mistral;
  private defaultModel: string;

  constructor(apiKey: string, defaultModel = 'mistral-small-latest') {
    this.client = new Mistral({ apiKey });
    this.defaultModel = defaultModel;
  }

  async chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse> {
    const response = await this.client.chat.complete({
      model: options?.model ?? this.defaultModel,
      messages,
      temperature: options?.temperature,
      maxTokens: options?.maxTokens,
    });

    return {
      content: response.choices?.[0]?.message?.content ?? '',
      usage: {
        inputTokens: response.usage?.promptTokens ?? 0,
        outputTokens: response.usage?.completionTokens ?? 0,
      },
      model: response.model ?? this.defaultModel,
    };
  }

  async *chatStream(messages: Message[], options?: ChatOptions): AsyncGenerator<string> {
    const stream = await this.client.chat.stream({
      model: options?.model ?? this.defaultModel,
      messages,
      temperature: options?.temperature,
      maxTokens: options?.maxTokens,
    });

    for await (const event of stream) {
      const content = event.data?.choices?.[0]?.delta?.content;
      if (content) yield content;
    }
  }

  async embed(texts: string[]): Promise<number[][]> {
    const response = await this.client.embeddings.create({
      model: 'mistral-embed',
      inputs: texts,
    });
    return response.data.map(d => d.embedding);
  }
}

Step 5: Feature-Flag Controlled Rollout

// adapters/factory.ts
import { MistralAdapter } from './mistral.adapter.js';
import { OpenAIAdapter } from './openai.adapter.js';

export function createAdapter(): AIAdapter {
  const rolloutPercent = parseInt(process.env.MISTRAL_ROLLOUT_PERCENT ?? '0');
  const useMistral = Math.random() * 100 < rolloutPercent;

  if (useMistral) {
    console.log('[AI] Using Mistral');
    return new MistralAdapter(process.env.MISTRAL_API_KEY!);
  }

  console.log('[AI] Using OpenAI (legacy)');
  return new OpenAIAdapter(process.env.OPENAI_API_KEY!);
}

Step 6: Gradual Rollout Plan

Phase	Rollout %	Duration	Criteria to Advance
0. Validation	0%	1-2 days	A/B tests pass
1. Canary	5%	2-3 days	Error rate < 1%, latency OK
2. Partial	25%	3-5 days	Quality metrics match
3. Majority	50%	5-7 days	Cost reduction confirmed
4. Full	100%	—	Remove old adapter code

# Advance rollout
export MISTRAL_ROLLOUT_PERCENT=5   # Canary
export MISTRAL_ROLLOUT_PERCENT=25  # Partial
export MISTRAL_ROLLOUT_PERCENT=100 # Full migration
export MISTRAL_ROLLOUT_PERCENT=0   # Emergency rollback

Step 7: A/B Validation Testing

async function validateMigration(adapter1: AIAdapter, adapter2: AIAdapter) {
  const testPrompts = [
    'Summarize: TypeScript adds static typing to JavaScript.',
    'Classify: "The app crashes on login" — bug, feature, or question?',
    'What is 2+2?',
  ];

  for (const prompt of testPrompts) {
    const messages = [{ role: 'user' as const, content: prompt }];
    const [r1, r2] = await Promise.all([
      adapter1.chat(messages, { temperature: 0 }),
      adapter2.chat(messages, { temperature: 0 }),
    ]);

    console.log(`Prompt: ${prompt.slice(0, 50)}...`);
    console.log(`  Provider 1: ${r1.content.slice(0, 100)} (${r1.usage.outputTokens} tokens)`);
    console.log(`  Provider 2: ${r2.content.slice(0, 100)} (${r2.usage.outputTokens} tokens)`);
    console.log();
  }
}

Key API Differences

Feature	OpenAI	Mistral
SDK import	import OpenAI from 'openai'	import { Mistral } from '@mistralai/mistralai'
Chat method	client.chat.completions.create()	client.chat.complete()
Stream events	chunk.choices[0]?.delta?.content	event.data?.choices?.[0]?.delta?.content
Embeddings	client.embeddings.create()	client.embeddings.create() (same)
Tool calling	Identical JSON Schema format	Identical JSON Schema format
JSON mode	response_format: { type: 'json_object' }	responseFormat: { type: 'json_object' }
Vision	Base64 in content array	Same approach with pixtral models

Error Handling

Issue	Cause	Solution
Different output quality	Model differences	Adjust prompts, tune temperature
Embedding dimension mismatch	1536 vs 1024	Re-embed all vectors, update vector DB config
Missing feature	Not supported by Mistral	Implement fallback in adapter
Cost increase	Token counting differs	Monitor and optimize prompts

Resources

• Mistral AI Documentation
• Mistral vs OpenAI Comparison
• Strangler Fig Pattern

Output

• Integration assessment with effort estimation
• Provider-agnostic adapter interface
• Mistral adapter implementation
• Feature-flag controlled gradual rollout
• Model mapping and API difference reference
• A/B validation test suite
• Rollback procedure (set MISTRAL_ROLLOUT_PERCENT=0)