Describe the bug
Instructor v1.11.1 introduced breaking changes that were released as a patch version instead of a major version, violating semantic versioning standards and breaking production systems that rely on automatic dependency updates.
Specific Breaking Change
PR #1731 removed backward compatibility for multimodal imports without deprecation warnings:
# ❌ BROKEN in v1.11.1+ (import path removed)
from instructor.multimodal import PDF, Image, Audio
# ✅ REQUIRED in v1.11.1+ (new import path)
from instructor.processing.multimodal import PDF, Image, Audio
Error produced:
ModuleNotFoundError: No module named 'instructor.multimodal'
To Reproduce
-
Install instructor v1.10.x and create code using the multimodal imports:
from instructor.multimodal import PDF, Image, Audio
-
Update to v1.11.1 (which happens automatically with version constraints like instructor>=1.9.0,<2.0.0)
-
Code breaks with ModuleNotFoundError
Expected behavior
According to https://semver.org/:
- PATCH version (1.11.1) should contain only backwards compatible bug fixes
- MINOR version (1.12.0) should contain backwards compatible functionality additions
- MAJOR version (2.0.0) should contain incompatible API changes
Expected behavior: Breaking changes should be released as v2.0.0, not v1.11.1.
Evidence of Production Impact
- Real Projects Affected
- Semantic Versioning Violation Analysis
What PR #1731 should have done (proper semantic versioning):
Step 1: Add deprecation warnings in patch version (v1.11.1)
import warnings
from instructor.processing.multimodal import PDF, Image, Audio
warnings.warn(
"instructor.multimodal is deprecated. Use instructor.processing.multimodal instead.",
DeprecationWarning,
stacklevel=2
)
Step 2: Remove deprecated imports in MAJOR version (v2.0.0)
What PR #1731 actually did:
- ❌ Removed imports immediately with no warnings
- ❌ No migration guide provided
- ❌ No breaking change notice in release notes
- ❌ Released as patch version instead of major
- Version Constraint Impact
Most projects use constraints like:
instructor = ">=1.9.0,<2.0.0" # Expects no breaking changes in minor/patch
This means automatic updates pull v1.11.1 and break production systems.
Urgency: Weekend Production Failures
This issue is causing production failures for teams using automatic dependency updates. Many projects are now forced to pin to instructor<1.11.0, which is not a sustainable solution.
Requested Resolution
Immediate:
- Restore backward compatibility by adding back the multimodal import shim:
# instructor/multimodal.py (restore this file)
import warnings
from instructor.processing.multimodal import *
warnings.warn(
"instructor.multimodal is deprecated. Use instructor.processing.multimodal instead.",
DeprecationWarning,
stacklevel=2
)
Long-term (v2.0.0 major):
- Properly version breaking changes as major releases
- Add migration documentation
- Follow proper deprecation cycle (warn in minor → remove in major)
References
Describe the bug
Instructor v1.11.1 introduced breaking changes that were released as a patch version instead of a major version, violating semantic versioning standards and breaking production systems that rely on automatic dependency updates.
Specific Breaking Change
PR #1731 removed backward compatibility for multimodal imports without deprecation warnings:
Error produced:
ModuleNotFoundError: No module named 'instructor.multimodal'To Reproduce
Install instructor v1.10.x and create code using the multimodal imports:
from instructor.multimodal import PDF, Image, AudioUpdate to v1.11.1 (which happens automatically with version constraints like instructor>=1.9.0,<2.0.0)
Code breaks with ModuleNotFoundError
Expected behavior
According to https://semver.org/:
Expected behavior: Breaking changes should be released as v2.0.0, not v1.11.1.
Evidence of Production Impact
What PR #1731 should have done (proper semantic versioning):
Step 1: Add deprecation warnings in patch version (v1.11.1)
Step 2: Remove deprecated imports in MAJOR version (v2.0.0)
What PR #1731 actually did:
Most projects use constraints like:
instructor = ">=1.9.0,<2.0.0" # Expects no breaking changes in minor/patch
This means automatic updates pull v1.11.1 and break production systems.
Urgency: Weekend Production Failures
This issue is causing production failures for teams using automatic dependency updates. Many projects are now forced to pin to instructor<1.11.0, which is not a sustainable solution.
Requested Resolution
Immediate:
Long-term (v2.0.0 major):
References