mistral-upgrade-migration

Mistral AI Upgrade & Migration

Current State

!npm list @mistralai/mistralai 2>/dev/null || echo 'not installed' !pip show mistralai 2>/dev/null | grep -E "^(Name|Version)" || echo 'not installed'

Overview

Guide for upgrading the Mistral AI SDK between major versions. The TypeScript SDK (@mistralai/mistralai) moved from CommonJS to ESM-only in v1.x, with significant API surface changes. This skill covers version detection, breaking change migration, automated code transforms, and rollback.

Prerequisites

• Current Mistral AI SDK installed
• Git for version control
• Test suite available

Instructions

Step 1: Check Versions

set -euo pipefail
# Current version
npm list @mistralai/mistralai 2>/dev/null

# Latest available
npm view @mistralai/mistralai version

# All versions
npm view @mistralai/mistralai versions --json | jq '.[-5:]'

# Python
pip show mistralai 2>/dev/null | grep Version

Step 2: Known Breaking Changes (v0.x to v1.x)

Change	v0.x (old)	v1.x (current)
Module format	CommonJS + ESM	ESM only
Import	import MistralClient from '...'	import { Mistral } from '...'
Constructor	new MistralClient(apiKey)	new Mistral({ apiKey })
Chat method	client.chat(params)	client.chat.complete(params)
Streaming	client.chatStream(params)	client.chat.stream(params)
Stream events	for await (const chunk of stream)	for await (const event of stream) access .data
Embeddings	client.embeddings(params)	client.embeddings.create(params)
Response types	Longer names	Shorter type names
Enum values	String constants	Forward-compatible unions

Step 3: Automated Migration Script

// scripts/migrate-mistral-v1.ts
import { readFileSync, writeFileSync } from 'fs';
import { glob } from 'glob';

const TRANSFORMS = [
  // Import statement
  {
    find: /import\s+MistralClient\s+from\s+['"]@mistralai\/mistralai['"]/g,
    replace: "import { Mistral } from '@mistralai/mistralai'",
  },
  // Constructor
  {
    find: /new\s+MistralClient\((\w+)\)/g,
    replace: 'new Mistral({ apiKey: $1 })',
  },
  // Chat method (careful: only top-level .chat(), not .chat.complete())
  {
    find: /\.chat\((?!\.)/g,
    replace: '.chat.complete(',
  },
  // Streaming
  {
    find: /\.chatStream\(/g,
    replace: '.chat.stream(',
  },
  // Embeddings
  {
    find: /\.embeddings\((?!\.)/g,
    replace: '.embeddings.create(',
  },
];

async function migrate() {
  const files = await glob('src/**/*.{ts,js}');
  let totalChanges = 0;

  for (const file of files) {
    let content = readFileSync(file, 'utf-8');
    let changes = 0;

    for (const { find, replace } of TRANSFORMS) {
      const newContent = content.replace(find, replace);
      if (newContent !== content) {
        changes++;
        content = newContent;
      }
    }

    if (changes > 0) {
      writeFileSync(file, content);
      console.log(`Migrated: ${file} (${changes} changes)`);
      totalChanges += changes;
    }
  }

  console.log(`\nTotal: ${totalChanges} changes across ${files.length} files`);
}

migrate();

Step 4: Upgrade Procedure

set -euo pipefail
# Create branch
git checkout -b upgrade/mistral-sdk-v1

# Backup lock file
cp package-lock.json package-lock.json.bak

# Upgrade
npm install @mistralai/mistralai@latest

# Ensure package.json has "type": "module"
node -e "const p=require('./package.json'); if(p.type!=='module') console.warn('WARNING: Add \"type\": \"module\" to package.json for ESM')"

# Run migration script
npx tsx scripts/migrate-mistral-v1.ts

# Verify
npm run typecheck
npm test

Step 5: Model Name Updates

Model names change over time. Update hardcoded references:

// Model alias mapping — update when models deprecate
const MODEL_ALIASES: Record<string, string> = {
  // Deprecated → Current
  'mistral-tiny': 'mistral-small-latest',
  'mistral-medium': 'mistral-small-latest', // Deprecated Q1 2025
  'open-mistral-7b': 'mistral-small-latest',
  'open-mixtral-8x7b': 'mistral-small-latest',

  // Current (no change needed)
  'mistral-small-latest': 'mistral-small-latest',
  'mistral-large-latest': 'mistral-large-latest',
  'codestral-latest': 'codestral-latest',
  'mistral-embed': 'mistral-embed',
};

function resolveModel(model: string): string {
  const resolved = MODEL_ALIASES[model];
  if (resolved && resolved !== model) {
    console.warn(`Model "${model}" is deprecated, using "${resolved}"`);
  }
  return resolved ?? model;
}

Step 6: Validation Tests

import { describe, it, expect } from 'vitest';
import { Mistral } from '@mistralai/mistralai';

describe('SDK Upgrade Validation', () => {
  it('should import Mistral correctly', () => {
    expect(Mistral).toBeDefined();
    expect(typeof Mistral).toBe('function');
  });

  it('should construct client', () => {
    const client = new Mistral({ apiKey: 'test-key' });
    expect(client.chat).toBeDefined();
    expect(client.chat.complete).toBeDefined();
    expect(client.chat.stream).toBeDefined();
    expect(client.embeddings).toBeDefined();
    expect(client.embeddings.create).toBeDefined();
    expect(client.models).toBeDefined();
    expect(client.models.list).toBeDefined();
  });
});

Step 7: Rollback

set -euo pipefail
# Quick rollback
npm install @mistralai/mistralai@0.5.0 --save-exact
git checkout -- src/  # Restore pre-migration code
npm test

# Or just revert the branch
git checkout main
git branch -D upgrade/mistral-sdk-v1

Error Handling

Error After Upgrade	Cause	Solution
ERR_REQUIRE_ESM	Missing "type": "module"	Add to package.json
Mistral is not a constructor	Old import style	Use import { Mistral }
.chat is not a function	Old method call	Use .chat.complete()
Type errors	Interface changes	Update types to match v1.x
Test failures	Response shape changed	Update assertions and mocks

Resources

• TypeScript SDK Releases
• Python SDK Releases
• Changelog
• Models Deprecation

Output

• Updated SDK to latest version
• Automated code migration applied
• Model name references updated
• Test suite passing after upgrade
• Rollback procedure documented