> ## Documentation Index
> Fetch the complete documentation index at: https://docs.multimind.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Backward Compatibility for Transformers

## Overview

This document explains the backward compatibility implementation for `AutoModelForSeq2SeqGeneration` and `AutoModelForSeq2SeqLM` in the MultiMind SDK.

## Background

The Hugging Face Transformers library has evolved over time, and the class name for sequence-to-sequence models has changed:

* **Old versions**: Used `AutoModelForSeq2SeqGeneration`
* **New versions**: Use `AutoModelForSeq2SeqLM`

This change could potentially break existing code that depends on the old class name.

## Implementation

The MultiMind SDK now includes backward compatibility logic that automatically detects which class is available and uses the appropriate one. This ensures that the SDK works with both old and new versions of the Transformers library.

### How It Works

The backward compatibility is implemented using a try-except pattern:

```python theme={null}
# Backward compatibility for transformers AutoModelForSeq2SeqLM/AutoModelForSeq2SeqGeneration
try:
    from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
    _AUTO_MODEL_CLASS = AutoModelForSeq2SeqLM
except ImportError:
    try:
        from transformers import AutoTokenizer, AutoModelForSeq2SeqGeneration
        _AUTO_MODEL_CLASS = AutoModelForSeq2SeqGeneration
    except ImportError:
        # Fallback for very old versions
        from transformers import AutoTokenizer
        _AUTO_MODEL_CLASS = None
```

### Fallback Strategy

The implementation includes a three-tier fallback strategy:

1. **Current Transformers**: Uses `AutoModelForSeq2SeqLM` (preferred)
2. **Old Transformers**: Falls back to `AutoModelForSeq2SeqGeneration`
3. **Very Old Transformers**: Sets the class to `None`; `multimind/fine_tuning/peft_methods.py` additionally tries `BartForConditionalGeneration` before raising an `ImportError` with a helpful message

## Affected Modules

The backward compatibility has been implemented in the following modules:

* `multimind/document_processing/document_chunkers.py`
* `multimind/document_processing/document_processor.py`
* `multimind/fine_tuning/unified_peft.py`
* `multimind/fine_tuning/advanced_unified_peft.py`
* `multimind/fine_tuning/peft_methods.py`

## Testing

The compatibility logic is covered by:

* `tests/test_transformers_compatibility.py` (four tests: current, old and very-old transformers plus class-selection logic, using mocked imports so no real `transformers` install is needed)

Run the tests to verify compatibility:

```bash theme={null}
# Run the specific compatibility test
python tests/test_transformers_compatibility.py

# Or run with pytest
python -m pytest tests/test_transformers_compatibility.py -v

# Or run all tests including compatibility tests
python -m pytest tests/ -v
```

## User Impact

### For Existing Users

**No action required!** The SDK will automatically work with your existing Transformers version.

* If you have a current Transformers version (4.x), it will use `AutoModelForSeq2SeqLM`
* If you have an older Transformers version, it will automatically fall back to `AutoModelForSeq2SeqGeneration`
* If you have a very old version, it will use the appropriate fallback

### For New Users

The SDK is now more robust and will work with a wider range of Transformers versions. You can install the SDK without worrying about Transformers version conflicts.

## Version Compatibility Matrix

| Transformers Version | Class Used | Status |
| - | - | - |
| 4.x (current) | `AutoModelForSeq2SeqLM` | ✅ Preferred |
| 3.x (old) | `AutoModelForSeq2SeqGeneration` | ✅ Fallback |
| 2.x (very old) | `BartForConditionalGeneration` (fine-tuning only) | ⚠️ Fallback |
| \< 2.x | Error with helpful message | ❌ Not supported |

Note that the package's own `finetune` extra pins `transformers>=4.30.0`, so the older tiers only matter if you install `transformers` yourself.

## Troubleshooting

### Import Errors

If you encounter import errors related to Transformers classes, install the supported version through the extra:

```bash theme={null}
pip install "multimind-sdk[finetune]"   # transformers>=4.30.0
```

### Model Loading Issues

If you encounter issues loading seq2seq models, the SDK will provide helpful error messages indicating which Transformers version is required.

## Migration Guide

### From Old Transformers Versions

If you're upgrading from an old Transformers version, the SDK will automatically handle the transition. No code changes are required.

### To New Transformers Versions

If you're upgrading to a new Transformers version, the SDK will automatically use the new class names. No code changes are required.

## Best Practices

1. **Keep Transformers Updated**: While the SDK supports old versions, it's recommended to use current versions for best performance and features.

2. **Test Your Environment**: Run the compatibility tests to verify your setup works correctly.

3. **Report Issues**: If you encounter compatibility issues, please report them with your Transformers version information.

## Future Considerations

* The SDK will continue to support backward compatibility for the foreseeable future
* New Transformers versions will be tested and supported as they become available
* Deprecation warnings will be provided well in advance of removing support for old versions

## Contributing

When contributing to the SDK:

1. Always test with multiple Transformers versions
2. Use the backward compatibility pattern for new Transformers imports
3. Update tests to cover different Transformers versions
4. Document any breaking changes well in advance

## Support

For questions or issues related to backward compatibility:

1. Check this documentation
2. Run the compatibility tests
3. Check your Transformers version: `pip show transformers`
4. Report issues with version information included


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.