Principle:Mlflow Mlflow ML Framework Compatibility Management
| Knowledge Sources | |
|---|---|
| Domains | Dependency Management, Compatibility |
| Last Updated | 2026-02-13 20:00 GMT |
Overview
Centralized declaration and automated maintenance of supported version ranges for external framework integrations, with derived runtime compatibility data and time-based version window management.
Description
A platform that integrates with dozens of external frameworks must maintain a structured record of which versions of each framework are supported, tested, and compatible. This record serves multiple consumers: CI test matrix generation, runtime version compatibility checking, package dependency specification, and developer documentation.
The Version Declaration File (YAML format) serves as the single source of truth. For each integration flavor, it specifies:
- Package information: the pip package name, optional module name (when it differs from the pip name), a repository URL for dev installations, and a dev install command.
- Test categories (models, autologging): each with a minimum and maximum supported version, optional unsupported version exclusions, per-version dependency overrides, Python/Java version requirements, runner specifications, and the test command to execute.
- Flags: whether the package is a GenAI integration (affecting version window policy), whether to test the tracing SDK, and version sampling intervals.
The Runtime Compatibility Module is a derived Python file that is auto-generated from the YAML source. It contains:
- A dictionary mapping each flavor to its package info and version bounds (minimum/maximum for models and autologging), used at runtime to check whether an installed framework version falls within the supported range.
- Separate mappings of flavor names to importable module names for GenAI and non-GenAI packages, used by autologging initialization to locate the correct module for patching.
The Version Update Script automates the maintenance of version bounds by:
- Querying the package index for each flavor to discover all released versions with their upload dates.
- Computing the minimum supported version based on a time window policy: for GenAI packages, versions older than one year are dropped from the minimum; for non-GenAI packages, the window is two years.
- Updating the maximum version to the latest stable release, excluding yanked releases and those uploaded within the last 24 hours.
- Regenerating the runtime compatibility module from the updated YAML.
Special cases are handled: certain packages with known maintenance challenges can be excluded from automatic updates, and packages with historically long support commitments (such as big data frameworks) can retain their manually set minimums.
Usage
This principle applies when new framework versions are released (the update script is run periodically), when adding support for a new framework (a new entry is added to the YAML file), and at runtime when autologging or model logging checks whether the installed framework version is within the supported range.
Theoretical Basis
The version window management follows a time-based sliding window policy:
For each flavor:
1. Fetch all released versions with upload timestamps from the package index
2. Compute the cutoff date:
- GenAI packages: now - 1 year
- Non-GenAI packages: now - 2 years
3. Filter to versions released after the cutoff date
4. New minimum = earliest version in the filtered set (by upload date)
5. If new minimum > current minimum: update the minimum bound
6. If no versions in window: set minimum = maximum (effectively deprecating)
The maximum version update follows a latest-stable policy:
For each flavor and category:
1. Fetch all versions from the package index
2. Exclude: dev/pre-releases, yanked versions, recently uploaded (< 24h)
3. Exclude versions in the unsupported set
4. latest = max(remaining versions, by version ordering)
5. If latest > current maximum: update the maximum bound
The runtime compatibility module generation follows a flatten-and-serialize pattern:
For each flavor in the YAML:
1. Extract package_info (pip_release, module_name)
2. Extract version bounds for each category (models, autologging)
3. Classify as GenAI or non-GenAI based on the genai flag
4. Build the flavor-to-module mapping for autologging lookup
5. Serialize all structures as a Python module with literal dictionaries