Major Changes Overview
- Enhanced schema validation system
- Thread-safe state management
- Improved error handling
- New configuration options
- Extended message history capabilities
- Streaming response improvements
- More robust progress tracking
Step-by-Step Migration
1. Update Dependencies
Update your pubspec.yaml:
dependencies: murmuration: ^2.0.0 google_generative_ai: ^latest_version shared_preferences: ^latest_version # New requirement synchronized: ^latest_version # New requirement
2. Configuration Updates
Before (1.0.0):
final config = MurmurationConfig( apiKey: 'your-api-key', model: 'gemini-1.5-flash-latest', debug: false, stream: false, logger: MurmurationLogger() );
After (2.0.0):
final config = MurmurationConfig( apiKey: 'your-api-key', model: 'gemini-1.5-pro', // Updated default model debug: true, stream: false, logger: MurmurationLogger(enabled: true), timeout: Duration(seconds: 30), // New option maxRetries: 3, // New option retryDelay: Duration(seconds: 1),// New option enableCache: true, // New option cacheTimeout: Duration(hours: 1) // New option );
3. Schema Validation Changes
Before (1.0.0):
final schema = {
'type': 'object',
'properties': {
'name': {'type': 'string'},
'age': {'type': 'number'}
}
};
After (2.0.0):
final schema = OutputSchema(
fields: {
'name': StringSchemaField(
description: 'User name',
minLength: 2,
required: true
),
'age': IntSchemaField(
description: 'User age',
min: 0,
required: true
)
},
strict: true
);
4. State Management Updates
Before (1.0.0):
agent.updateState({'key': 'value'});
final value = agent.getState()['key'];
After (2.0.0):
// State is now immutable
final newState = state.copyWith({'key': 'value'});
final value = state.get('key'); // Type-safe access
5. Error Handling Improvements
Before (1.0.0):
try {
final result = await agent.execute("Process data");
} catch (e) {
print('Error: $e');
}
After (2.0.0):
try {
final result = await agent.execute("Process data");
} on MurmurationException catch (e) {
print('Error: ${e.message}');
print('Original error: ${e.originalError}');
print('Stack trace: ${e.stackTrace}');
}
6. Message History Management
Before (1.0.0):
// Basic message storage final messages = []; messages.add(message);
After (2.0.0):
final history = MessageHistory( threadId: 'user-123', maxMessages: 50, maxTokens: 4000 ); await history.addMessage(Message( role: 'user', content: 'Hello!', timestamp: DateTime.now() )); await history.save(); // Persist to storage await history.load(); // Load from storage await history.clear(); // Clear history
7. Progress Tracking Updates
Before (1.0.0):
final result = await murmur.run(
input: "Process this",
onProgress: (progress) {
print('Progress: ${progress.toString()}');
}
);
After (2.0.0):
final result = await murmur.runAgentChain(
input: "Process this",
agentInstructions: [/* ... */],
logProgress: true,
onProgress: (progress) {
print('Agent: ${progress.currentAgent}/${progress.totalAgents}');
print('Status: ${progress.status}');
print('Output: ${progress.output}');
}
);
8. Tool Integration Changes
Before (1.0.0):
final tool = Tool( name: 'processor', description: 'Processes data', execute: (params) async => processData(params) );
After (2.0.0):
final tool = Tool(
name: 'processor',
description: 'Processes data parameters: {
'data': StringSchemaField(
description: 'Input data to process',
required: true
),
'format': StringSchemaField(
description: 'Output format',
enumValues: ['json', 'xml', 'text'],
required: true
)
},
execute: (params) async => processData(params)
);
Breaking Changes
- Schema System: Complete overhaul of schema validation with new type-safe field definitions required and strict validation mode by default.
- State Management: State is now immutable, requiring the use of copyWith() for updates and type-safe access methods.
- Configuration: New required configuration options, different default values, and additional dependencies required.
- Error Handling: Introduction of the MurmurationException class with more detailed error information and structured error handling required.
- Message History: Thread-safe by default with persistence required and automatic cleanup mechanisms.
Performance Improvements
- Caching: Built-in response caching with configurable cache timeout and automatic cache cleanup.
- Threading: Thread-safe operations with improved concurrency handling and better resource management.
- Memory Management: Automatic message cleanup, token limit enforcement, and resource optimization.
Best Practices for Migration
- Incremental Migration: Update dependencies first, migrate configuration, update schema definitions, implement new error handling, update state management, add message history, and implement new tools.
- Testing: Test each component after migration, verify error handling, check state management, validate schema compliance, and test concurrent operations.
- Monitoring: Enable debug logging, monitor performance, track error rates, observe memory usage, and check response times.
Additional Resources
For any migration issues or questions, please open an issue on GitHub or contact the maintainers.