---

name: mistral-migration-deep-dive description: | Execute Mistral AI major migrations and re-architecture strategies. Use when migrating to Mistral AI from another provider, performing major refactoring, or re-platforming existing AI integrations to Mistral AI. Trigger with phrases like "migrate to mistral", "mistral migration", "switch to mistral", "mistral replatform", "openai to mistral". allowed-tools: Read, Write, Edit, Bash(npm:), Bash(node:), Bash(kubectl:*) version: 1.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io

Mistral AI Migration Deep Dive

Overview

Comprehensive guide for migrating to Mistral AI from other providers or major version upgrades.

Prerequisites

• Current system documentation
• Mistral AI SDK installed
• Feature flag infrastructure
• Rollback strategy tested

Migration Types

Type	Complexity	Duration	Risk
Fresh install	Low	Days	Low
OpenAI to Mistral	Medium	Weeks	Medium
Multi-provider	Medium	Weeks	Medium
Full replatform	High	Months	High

Instructions

Step 1: Pre-Migration Assessment

# Document current implementation
echo "=== Pre-Migration Assessment ==="

# Find all AI-related code
find . -name "*.ts" -o -name "*.py" | xargs grep -l "openai\|anthropic\|ai" > ai-files.txt
echo "Files with AI code: $(wc -l < ai-files.txt)"

# Count integration points
grep -r "chat.completions\|createChatCompletion" src/ --include="*.ts" | wc -l

# Check current SDK versions
npm list openai @anthropic-ai/sdk 2>/dev/null || echo "No existing AI SDKs"

// scripts/assess-migration.ts
interface MigrationAssessment {
  currentProvider: string;
  integrationPoints: number;
  features: string[];
  estimatedEffort: 'low' | 'medium' | 'high';
  risks: string[];
}

async function assessMigration(): Promise<MigrationAssessment> {
  const files = await glob('src/**/*.{ts,js}');
  const features = new Set<string>();
  let integrationPoints = 0;

  for (const file of files) {
    const content = await fs.readFile(file, 'utf-8');

    // Detect features
    if (/chat\.completions|createChatCompletion/i.test(content)) {
      features.add('chat');
      integrationPoints++;
    }
    if (/embeddings\.create|createEmbedding/i.test(content)) {
      features.add('embeddings');
      integrationPoints++;
    }
    if (/function_call|tools/i.test(content)) {
      features.add('function_calling');
      integrationPoints++;
    }
    if (/stream/i.test(content)) {
      features.add('streaming');
      integrationPoints++;
    }
  }

  return {
    currentProvider: detectProvider(files),
    integrationPoints,
    features: Array.from(features),
    estimatedEffort: integrationPoints > 10 ? 'high' : integrationPoints > 3 ? 'medium' : 'low',
    risks: identifyRisks(features),
  };
}

Step 2: Create Adapter Layer

// src/ai/adapter.ts
// Provider-agnostic interface

export interface Message {
  role: 'system' | 'user' | 'assistant';
  content: string;
}

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

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

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

Step 3: Implement OpenAI Adapter (Current)

// src/ai/adapters/openai.ts
import OpenAI from 'openai';
import { AIAdapter, Message, ChatOptions, ChatResponse } from '../adapter';

export class OpenAIAdapter implements AIAdapter {
  private client: OpenAI;

  constructor() {
    this.client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  }

  async chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse> {
    const response = await this.client.chat.completions.create({
      model: options?.model || 'gpt-3.5-turbo',
      messages,
      temperature: options?.temperature,
      max_tokens: options?.maxTokens,
    });

    return {
      content: response.choices[0]?.message?.content || '',
      usage: response.usage ? {
        inputTokens: response.usage.prompt_tokens,
        outputTokens: response.usage.completion_tokens,
      } : undefined,
    };
  }

  async *chatStream(messages: Message[], options?: ChatOptions): AsyncGenerator<string> {
    const stream = await this.client.chat.completions.create({
      model: options?.model || 'gpt-3.5-turbo',
      messages,
      stream: true,
    });

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

  async embed(text: string | string[]): Promise<number[][]> {
    const input = Array.isArray(text) ? text : [text];
    const response = await this.client.embeddings.create({
      model: 'text-embedding-ada-002',
      input,
    });
    return response.data.map(d => d.embedding);
  }
}

Step 4: Implement Mistral Adapter (Target)

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

export class MistralAdapter implements AIAdapter {
  private client: Mistral;

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

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

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

  async *chatStream(messages: Message[], options?: ChatOptions): AsyncGenerator<string> {
    const stream = await this.client.chat.stream({
      model: options?.model || 'mistral-small-latest',
      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(text: string | string[]): Promise<number[][]> {
    const input = Array.isArray(text) ? text : [text];
    const response = await this.client.embeddings.create({
      model: 'mistral-embed',
      inputs: input,
    });
    return response.data.map(d => d.embedding);
  }
}

Step 5: Feature Flag Controlled Migration

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

type Provider = 'openai' | 'mistral';

function getAIProvider(): Provider {
  // Feature flag based migration
  const mistralPercentage = parseInt(process.env.MISTRAL_ROLLOUT_PERCENT || '0');
  const random = Math.random() * 100;

  if (random < mistralPercentage) {
    return 'mistral';
  }

  return 'openai';
}

export function createAIAdapter(): AIAdapter {
  const provider = getAIProvider();

  switch (provider) {
    case 'mistral':
      console.log('[AI] Using Mistral adapter');
      return new MistralAdapter();
    case 'openai':
    default:
      console.log('[AI] Using OpenAI adapter');
      return new OpenAIAdapter();
  }
}

Step 6: Gradual Rollout

# Phase 1: 0% Mistral (validation)
export MISTRAL_ROLLOUT_PERCENT=0
# Run tests, verify adapter works

# Phase 2: 5% Mistral (canary)
export MISTRAL_ROLLOUT_PERCENT=5
# Monitor for errors, compare latency

# Phase 3: 25% Mistral
export MISTRAL_ROLLOUT_PERCENT=25
# Monitor for 24-48 hours

# Phase 4: 50% Mistral
export MISTRAL_ROLLOUT_PERCENT=50
# Monitor for 24-48 hours

# Phase 5: 100% Mistral
export MISTRAL_ROLLOUT_PERCENT=100
# Full migration complete

Step 7: Model Mapping

// src/ai/model-mapping.ts

interface ModelMapping {
  openai: string;
  mistral: string;
  notes: string;
}

const MODEL_MAPPINGS: ModelMapping[] = [
  {
    openai: 'gpt-3.5-turbo',
    mistral: 'mistral-small-latest',
    notes: 'Fast, cost-effective',
  },
  {
    openai: 'gpt-4',
    mistral: 'mistral-large-latest',
    notes: 'Complex reasoning',
  },
  {
    openai: 'gpt-4-turbo',
    mistral: 'mistral-large-latest',
    notes: 'Best available',
  },
  {
    openai: 'text-embedding-ada-002',
    mistral: 'mistral-embed',
    notes: '1024 dimensions',
  },
];

export function mapModel(openaiModel: string): string {
  const mapping = MODEL_MAPPINGS.find(m => m.openai === openaiModel);
  return mapping?.mistral || 'mistral-small-latest';
}

Step 8: Validation & Testing

// tests/migration/compare-outputs.test.ts
import { describe, it, expect } from 'vitest';
import { OpenAIAdapter } from '../../src/ai/adapters/openai';
import { MistralAdapter } from '../../src/ai/adapters/mistral';

describe('Migration Validation', () => {
  const openai = new OpenAIAdapter();
  const mistral = new MistralAdapter();

  const testCases = [
    { name: 'Simple greeting', messages: [{ role: 'user', content: 'Hello' }] },
    { name: 'Math question', messages: [{ role: 'user', content: 'What is 2+2?' }] },
    { name: 'Code generation', messages: [{ role: 'user', content: 'Write hello world in Python' }] },
  ];

  for (const testCase of testCases) {
    it(`should produce similar output: ${testCase.name}`, async () => {
      const [openaiResult, mistralResult] = await Promise.all([
        openai.chat(testCase.messages, { temperature: 0 }),
        mistral.chat(testCase.messages, { temperature: 0 }),
      ]);

      // Both should return non-empty content
      expect(openaiResult.content.length).toBeGreaterThan(0);
      expect(mistralResult.content.length).toBeGreaterThan(0);

      // Log for manual review
      console.log(`[${testCase.name}]`);
      console.log('OpenAI:', openaiResult.content);
      console.log('Mistral:', mistralResult.content);
    });
  }
});

Step 9: Rollback Plan

#!/bin/bash
# rollback-to-openai.sh

echo "=== Rolling back to OpenAI ==="

# 1. Set rollout percentage to 0
kubectl set env deployment/ai-service MISTRAL_ROLLOUT_PERCENT=0

# 2. Verify rollback
kubectl rollout status deployment/ai-service

# 3. Check health
curl -sf https://api.yourapp.com/health | jq '.services.ai'

# 4. Alert team
echo "Rollback complete. Mistral disabled."

Output

• Migration assessment complete
• Adapter layer implemented
• Gradual rollout in progress
• Rollback procedure ready

Error Handling

Issue	Cause	Solution
Different output format	API differences	Normalize in adapter
Missing feature	Not supported	Implement fallback
Performance difference	Model characteristics	Adjust timeouts
Cost increase	Token differences	Monitor and optimize

Examples

Quick A/B Comparison

const [openaiResponse, mistralResponse] = await Promise.all([
  openaiAdapter.chat(messages, { temperature: 0 }),
  mistralAdapter.chat(messages, { temperature: 0 }),
]);

console.log('OpenAI tokens:', openaiResponse.usage);
console.log('Mistral tokens:', mistralResponse.usage);

Resources

• Mistral AI Documentation
• Strangler Fig Pattern
• Feature Flags Best Practices

Completion

Congratulations! You've completed the Mistral AI skill pack. For ongoing support, visit docs.mistral.ai.