2_projects.py

"""
MLflow Tutorial - Component 2: MLflow Projects

This module demonstrates the MLflow Projects component, which enables
reproducible and reusable ML code.

Key Features Demonstrated:
1. Project structure with MLproject file
2. Parameterized runs
3. Running projects programmatically
4. Dependency management
5. Reproducible execution
"""

import mlflow
import mlflow.sklearn
import numpy as np
from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split, cross_val_score
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score, precision_score, recall_score, f1_score
import sys
import os


def print_section(title):
    """Print a formatted section header."""
    print("\n" + "=" * 80)
    print(f"  {title}")
    print("=" * 80 + "\n")


def run_training_with_params(n_estimators=100, max_depth=5):
    """
    Train a model with specified parameters.
    This function demonstrates how MLflow Projects can accept parameters.
    
    Args:
        n_estimators: Number of trees in the random forest
        max_depth: Maximum depth of the trees
    """
    print_section(f"Training with n_estimators={n_estimators}, max_depth={max_depth}")
    
    # Set experiment
    experiment_name = "MLflow_Projects_Demo"
    mlflow.set_experiment(experiment_name)
    
    # Generate data
    print("Generating dataset...")
    X, y = make_classification(
        n_samples=1000,
        n_features=20,
        n_informative=15,
        n_redundant=5,
        n_classes=2,
        random_state=42
    )
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=42
    )
    
    # Start MLflow run
    with mlflow.start_run(run_name=f"rf_n{n_estimators}_d{max_depth}") as run:
        print(f"\nRun ID: {run.info.run_id}")
        
        # Define parameters
        params = {
            "n_estimators": n_estimators,
            "max_depth": max_depth,
            "min_samples_split": 2,
            "random_state": 42
        }
        
        # Log parameters
        mlflow.log_params(params)
        print(f"Parameters: {params}")
        
        # Train model
        print("\nTraining model...")
        model = RandomForestClassifier(**params)
        model.fit(X_train, y_train)
        
        # Cross-validation
        print("Performing cross-validation...")
        cv_scores = cross_val_score(model, X_train, y_train, cv=5)
        cv_mean = cv_scores.mean()
        cv_std = cv_scores.std()
        
        # Predictions
        y_pred = model.predict(X_test)
        
        # Calculate metrics
        metrics = {
            "accuracy": accuracy_score(y_test, y_pred),
            "precision": precision_score(y_test, y_pred),
            "recall": recall_score(y_test, y_pred),
            "f1_score": f1_score(y_test, y_pred),
            "cv_mean": cv_mean,
            "cv_std": cv_std
        }
        
        # Log metrics
        mlflow.log_metrics(metrics)
        print(f"\nMetrics:")
        for key, value in metrics.items():
            print(f"  {key}: {value:.4f}")
        
        # Log model with signature and input example
        from mlflow.models.signature import infer_signature
        signature = infer_signature(X_test, model.predict(X_test))
        mlflow.sklearn.log_model(
            model,
            "model",
            signature=signature,
            input_example=X_test[:5],
            registered_model_name=None  # We'll register in component 4
        )
        
        # Add tags
        mlflow.set_tag("training_type", "parameterized")
        mlflow.set_tag("component", "mlflow_projects")
        
        print(f"\n✓ Training completed successfully!")
        print(f"View results at: http://localhost:5000/#/experiments/{run.info.experiment_id}/runs/{run.info.run_id}")
        
        return run.info.run_id, metrics


def run_project_programmatically():
    """
    Demonstrate running an MLflow project programmatically.
    This shows how to execute the same code with different parameters.
    """
    print_section("Running Project with Different Parameters")
    
    # Different parameter combinations to test
    param_combinations = [
        {"n_estimators": 50, "max_depth": 3},
        {"n_estimators": 100, "max_depth": 5},
        {"n_estimators": 200, "max_depth": 7},
    ]
    
    results = []
    
    for i, params in enumerate(param_combinations, 1):
        print(f"\n{'='*80}")
        print(f"  Configuration {i}/{len(param_combinations)}")
        print(f"{'='*80}")
        
        run_id, metrics = run_training_with_params(**params)
        results.append({
            "run_id": run_id,
            "params": params,
            "metrics": metrics
        })
    
    # Summary
    print_section("Experiment Summary")
    print(f"{'Config':<10} {'n_estimators':<15} {'max_depth':<12} {'Accuracy':<12} {'F1 Score':<12}")
    print("-" * 80)
    
    for i, result in enumerate(results, 1):
        params = result["params"]
        metrics = result["metrics"]
        print(f"{i:<10} {params['n_estimators']:<15} {params['max_depth']:<12} "
              f"{metrics['accuracy']:<12.4f} {metrics['f1_score']:<12.4f}")
    
    # Find best configuration
    best_result = max(results, key=lambda x: x["metrics"]["accuracy"])
    print("\n" + "=" * 80)
    print(f"Best Configuration:")
    print(f"  Parameters: {best_result['params']}")
    print(f"  Accuracy: {best_result['metrics']['accuracy']:.4f}")
    print(f"  F1 Score: {best_result['metrics']['f1_score']:.4f}")
    print(f"  Run ID: {best_result['run_id']}")
    print("=" * 80)


def demonstrate_project_structure():
    """Show the project structure and explain the MLproject file."""
    print_section("MLflow Project Structure")
    
    print("A typical MLflow Project contains:")
    print("""
    project_directory/
    ├── MLproject          # Project configuration file
    ├── conda.yaml         # Conda environment (optional)
    ├── python_env.yaml    # Python environment (alternative)
    ├── requirements.txt   # Pip requirements
    └── train.py          # Training script
    """)
    
    print("\nThe MLproject file for this tutorial:")
    mlproject_path = os.path.join(os.path.dirname(__file__), "MLproject")
    if os.path.exists(mlproject_path):
        with open(mlproject_path, 'r') as f:
            print("-" * 80)
            print(f.read())
            print("-" * 80)
    
    print("\nKey Components:")
    print("1. name: Project identifier")
    print("2. : Defined commands that can be run")
    print("3. parameters: Input parameters with types and defaults")
    print("4. commanentry_pointsd: Shell command to execute")
    
    print("\n✓ Project structure demonstration complete")


def demonstrate_project_execution():
    """Show different ways to execute MLflow projects."""
    print_section("Ways to Execute MLflow Projects")
    
    print("1. Run from command line:")
    print("   $ mlflow run . -e projects --experiment-name MyExperiment")
    print()
    
    print("2. Run with parameters:")
    print("   $ mlflow run . -e projects -P n_estimators=200 -P max_depth=10")
    print()
    
    print("3. Run from Git repository:")
    print("   $ mlflow run https://github.com/user/repo -v <version>")
    print()
    
    print("4. Run programmatically (Python):")
    print("""
    import mlflow
    
    mlflow.run(
        uri=".",
        entry_point="projects",
        parameters={"n_estimators": 150, "max_depth": 6},
        experiment_name="MyExperiment"
    )
    """)
    print()
    
    print("5. Run in isolated environment:")
    print("   $ mlflow run . --env-manager=conda")
    print()
    
    print("✓ Execution methods demonstration complete")


def main():
    """Run all project examples."""
    print("\n" + "=" * 80)
    print("  MLflow Projects Tutorial - Component 2")
    print("=" * 80)
    print("\nThis tutorial demonstrates the MLflow Projects component.")
    print("MLflow Projects provide a standard format for packaging ML code")
    print("in a reusable and reproducible way.\n")
    
    # Parse command line arguments if provided
    n_estimators = int(sys.argv[1]) if len(sys.argv) > 1 else 100
    max_depth = int(sys.argv[2]) if len(sys.argv) > 2 else 5
    
    try:
        # Show project structure
        demonstrate_project_structure()
        
        # Show execution methods
        demonstrate_project_execution()
        
        # If arguments provided, run single training
        if len(sys.argv) > 1:
            print_section("Running Single Training with Provided Parameters")
            run_training_with_params(n_estimators, max_depth)
        else:
            # Run multiple configurations
            run_project_programmatically()
        
        print_section("Tutorial Complete!")
        print("✓ All project examples completed successfully!")
        print("\nKey Takeaways:")
        print("1. MLproject file defines project structure and entry points")
        print("2. Projects can accept parameters for flexibility")
        print("3. Projects ensure reproducibility with environment management")
        print("4. Projects can be run from CLI or programmatically")
        print("5. Projects can be shared via Git repositories")
        print("\nNext: Run Component 3 (MLflow Models) with:")
        print("  $ python 3_models.py")
        
    except Exception as e:
        print(f"\n❌ Error occurred: {str(e)}")
        import traceback
        traceback.print_exc()


if __name__ == "__main__":
    main()