Mistral AI Upgrade & Migration

Overview

Guide for upgrading Mistral AI SDK versions and handling breaking changes.

Prerequisites

• Current Mistral AI SDK installed

• Git for version control

• Test suite available

• Staging environment

Instructions

Step 1: Check Current Version

set -euo pipefail

Node.js SDK

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

Python SDK

pip show mistralai pip index versions mistralai 2>/dev/null || pip install mistralai==

Check for outdated

npm outdated @mistralai/mistralai

Step 2: Review Changelog

set -euo pipefail

Check GitHub releases

open https://github.com/mistralai/client-js/releases open https://github.com/mistralai/client-python/releases

Check npm changelog

npm info @mistralai/mistralai

Step 3: Create Upgrade Branch

set -euo pipefail

Create feature branch

git checkout -b upgrade/mistral-sdk-vX.Y.Z

Backup current lock file

cp package-lock.json package-lock.json.bak

Upgrade SDK

npm install @mistralai/mistralai@latest

Or specific version

npm install @mistralai/mistralai@1.2.0

Check what changed

npm diff @mistralai/mistralai

Step 4: Handle Breaking Changes

Common Migration Patterns:

Import Changes (v0.x to v1.x)

// Before (v0.x) import MistralClient from '@mistralai/mistralai'; const client = new MistralClient(apiKey);

// After (v1.x) import Mistral from '@mistralai/mistralai'; const client = new Mistral({ apiKey });

Method Changes

// Before const response = await client.chat(params);

// After (v1.x) const response = await client.chat.complete(params);

Streaming Changes

// Before const stream = await client.chatStream(params); for await (const chunk of stream) { ... }

// After (v1.x) const stream = await client.chat.stream(params); for await (const event of stream) { const chunk = event.data; ... }

Step 5: Run Tests

set -euo pipefail

Type check

npm run typecheck

Unit tests

npm test

Integration tests

MISTRAL_API_KEY=$MISTRAL_API_KEY_TEST npm run test:integration

Compare outputs

npm run test -- --updateSnapshot # if using snapshots

Step 6: Create Migration Script

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

const MIGRATIONS: Array<{ pattern: RegExp; replacement: string }> = [ // Import statement { pattern: /import MistralClient from '@mistralai/mistralai'/g, replacement: "import Mistral from '@mistralai/mistralai'", }, // Client instantiation { pattern: /new MistralClient((\w+))/g, replacement: 'new Mistral({ apiKey: $1 })', }, // Chat method { pattern: /.chat(/g, replacement: '.chat.complete(', }, // Streaming method { pattern: /.chatStream(/g, replacement: '.chat.stream(', }, ];

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

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

for (const { pattern, replacement } of MIGRATIONS) {
  if (pattern.test(content)) {
    content = content.replace(pattern, replacement);
    modified = true;
  }
}

if (modified) {
  writeFileSync(file, content);
  console.log(`Migrated: ${file}`);
}

} }

migrate();

Step 7: Document Changes

Mistral SDK Upgrade: v0.x → v1.x

Breaking Changes Applied

1. Updated import statement
2. Changed client instantiation
3. Updated chat method calls
4. Modified streaming interface

Files Modified

• src/mistral/client.ts
• src/services/chat.ts
• tests/mistral.test.ts

Testing

• Unit tests pass
• Integration tests pass
• Staging deployment verified
• Performance benchmarked

Rollback

npm install @mistralai/mistralai@0.x.x
git checkout -- src/

## Output
- Updated SDK version
- Fixed breaking changes
- Passing test suite
- Documented rollback procedure

## Version Compatibility

| SDK Version | Node.js | API Version | Notable Changes |
|-------------|---------|-------------|-----------------|
| 1.x | 18+ | Latest | New client interface |
| 0.5.x | 16+ | v1 | Stable, legacy |
| 0.4.x | 16+ | v1 | Streaming improvements |

## Error Handling

| Error After Upgrade | Cause | Solution |
|---------------------|-------|----------|
| Import error | Changed exports | Update import statement |
| Type errors | Interface changes | Update types |
| Runtime error | Method signature changed | Check migration guide |
| Test failures | Response format changed | Update assertions |

## Examples

### Deprecation Handling
```typescript
// Monitor for deprecation warnings
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[Mistral SDK]', warning.message);
    }
  });
}

Gradual Migration with Feature Flag

const USE_NEW_SDK = process.env.MISTRAL_SDK_V1 === 'true';

async function chat(messages: Message[]): Promise<string> {
  if (USE_NEW_SDK) {
    // New SDK interface
    const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
    const response = await client.chat.complete({ model, messages });
    return response.choices?.[0]?.message?.content ?? '';
  } else {
    // Legacy interface
    const client = new MistralClient(process.env.MISTRAL_API_KEY);
    const response = await client.chat({ model, messages });
    return response.choices?.[0]?.message?.content ?? '';
  }
}

Rollback Procedure

set -euo pipefail
# Quick rollback
npm install @mistralai/mistralai@0.5.0 --save-exact

# Verify rollback
npm list @mistralai/mistralai
npm test

Resources

- Mistral AI Changelog

- Mistral AI Migration Guide

Next Steps

For CI integration during upgrades, see mistral-ci-integration
.