Analyze, plan, and execute Mistral AI SDK upgrades with breaking change detection.
Use when upgrading Mistral SDK versions, detecting deprecations,
or migrating to new API versions.
Trigger with phrases like "upgrade mistral", "mistral migration",
"mistral breaking changes", "update mistral SDK", "analyze mistral version".
!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;
}
