# Jeremylongshore Claude Code Plugins Plus Skills Mistral Upgrade Migration > Mistral AI Upgrade & Migration - Skill: `tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-mistral-upgr` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-mistral-upgr` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-mistral-upgr/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-mistral-upgr --- # 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 ```bash 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 ```typescript // 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 ```bash 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: ```typescript // Model alias mapping — update when models deprecate const MODEL_ALIASES: Record = { // 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 ```typescript 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 ```bash 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](https://github.com/mistralai/client-ts/releases) - [Python SDK Releases](https://github.com/mistralai/client-python/releases) - [Changelog](https://docs.mistral.ai/getting-started/changelog/) - [Models Deprecation](https://docs.mistral.ai/getting-started/models/) ## Output - Updated SDK to latest version - Automated code migration applied - Model name references updated - Test suite passing after upgrade - Rollback procedure documented --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/jeremylongshore) — claim your Tome and manage your conversions.