Environment Management

class EnvironmentManager(project_root: Path)

Bases: object

Manages environment capture, comparison, and export for reproducible runs.

Provides comprehensive environment management capabilities including capturing current environment state, comparing with saved environments, and exporting requirements files for reproducibility.

Attributes:

CRITICAL_PACKAGESset

Set of package names considered critical for ML reproducibility

project_rootpathlib.Path

Path to the project root directory

CRITICAL_PACKAGES = {'joblib', 'numpy', 'pandas', 'scikit-learn', 'scipy'}

capture_environment() → Dict

Capture current environment as structured data.

Collects comprehensive information about the current Python environment including Python version, system information, and installed packages.

Returns:

Dict

Environment information in a clean, structured format with keys: - python: Python version and implementation details - system: Platform, architecture, and processor information - packages: Dictionary of installed packages with versions

compare_environments(saved_env: Dict) → Tuple[List[EnvironmentDiff], bool]

Compare current environment with saved environment.

Performs comprehensive comparison between the current environment and a previously saved environment configuration. Identifies package differences, version changes, and compatibility issues.

Parameters:

saved_envDict

Saved environment configuration containing python, system, and packages information

Returns:

Tuple[List[EnvironmentDiff], bool]

Tuple containing: - List of EnvironmentDiff objects describing all differences - Boolean indicating whether environments are compatible

export_requirements(saved_env: Dict, output_path: Path, include_all: bool = False, include_python: bool = True) → Path

Export environment as requirements.txt file.

Creates a requirements.txt file from a saved environment configuration with options to include all packages or just critical ones.

Parameters:

saved_envDict

Saved environment configuration containing packages information

output_pathpathlib.Path

Path where the requirements file should be saved

include_allbool, default=False

Whether to include all packages or just critical ones

include_pythonbool, default=True

Whether to include Python version as a comment in the file

Returns:

pathlib.Path

Path to the created requirements file

Notes

The generated file includes: - Header comments with generation timestamp - Python version comment (if include_python=True) - Critical packages section (always included) - Other packages section (if include_all=True)

generate_environment_report(saved_env: Dict) → str

Generate a human-readable environment report.

Creates a comprehensive report comparing the current environment with a saved environment configuration, including detailed analysis of package differences and recommendations.

Parameters:

saved_envDict

Saved environment configuration to compare against

Returns:

str

Formatted report string containing: - Environment compatibility status - Python version comparison - System information comparison - Critical package differences - Non-critical package differences - Recommendations for environment recreation

class EnvironmentDiff(package: str, original_version: str | None, current_version: str | None, status: VersionMatch, is_critical: bool = False)

Bases: object

Represents differences between environments.

Contains information about package version differences between a saved environment and the current environment.

Attributes:

packagestr

Name of the package

original_versionOptional[str]

Version in the original/saved environment

current_versionOptional[str]

Version in the current environment

statusVersionMatch

Compatibility status of the version difference

is_criticalbool, default=False

Whether this package is considered critical for reproducibility

current_version: str | None

is_critical: bool = False

original_version: str | None

package: str

status: VersionMatch

class VersionMatch(*values)

Bases: Enum

Enumeration of version matching states.

Defines the possible states when comparing package versions between environments. Used to categorize compatibility levels.

Attributes:

EXACTstr

Versions match exactly

COMPATIBLEstr

Versions are compatible (patch-level differences for critical packages, or major version differences for non-critical packages)

INCOMPATIBLEstr

Versions are incompatible (major version differences for critical packages)

MISSINGstr

Package was present in original environment but missing in current

EXTRAstr

Package is present in current environment but was not in original

COMPATIBLE = 'compatible'

EXACT = 'exact'

EXTRA = 'extra'

INCOMPATIBLE = 'incompatible'

MISSING = 'missing'