mlpipe-cli 0.1.0__py3-none-any.whl

mlpipe/models/classification.py

@@ -0,0 +1,156 @@
+"""Classification candidate models and parameter spaces."""
+
+from typing import List
+
+from scipy.stats import randint, uniform
+from sklearn.ensemble import (
+    HistGradientBoostingClassifier,
+    RandomForestClassifier,
+)
+from sklearn.linear_model import LogisticRegression
+from sklearn.neighbors import KNeighborsClassifier
+from sklearn.tree import DecisionTreeClassifier
+
+from mlpipe.models.registry import ModelCandidate
+
+
+def get_classification_candidates() -> List[ModelCandidate]:
+    """Return all registered classification candidates."""
+
+    return [
+        # 1. Logistic Regression
+        ModelCandidate(
+            name="Logistic Regression",
+            estimator_factory=lambda random_seed=42, **kwargs: LogisticRegression(
+                random_state=random_seed, max_iter=1000, **kwargs
+            ),
+            task="classification",
+            supports_feature_importance=True,
+            importance_type="linear",
+            requires_scaling=True,
+            param_grid_fast={
+                "C": [0.1, 1.0, 10.0],
+            },
+            param_grid_balanced={
+                "C": uniform(0.01, 10.0),
+                "penalty": ["l2"],
+                "solver": ["lbfgs"],
+            },
+            param_grid_thorough={
+                "C": uniform(0.001, 50.0),
+                "penalty": ["l2"],
+                "solver": ["lbfgs", "saga"],
+            },
+        ),
+
+        # 2. Random Forest
+        ModelCandidate(
+            name="Random Forest",
+            estimator_factory=lambda random_seed=42, **kwargs: RandomForestClassifier(
+                random_state=random_seed, n_jobs=-1, **kwargs
+            ),
+            task="classification",
+            supports_feature_importance=True,
+            importance_type="tree",
+            requires_scaling=False,
+            param_grid_fast={
+                "n_estimators": [50, 100],
+                "max_depth": [5, 10, None],
+            },
+            param_grid_balanced={
+                "n_estimators": randint(50, 200),
+                "max_depth": [5, 10, 20, None],
+                "min_samples_split": randint(2, 10),
+                "min_samples_leaf": randint(1, 6),
+            },
+            param_grid_thorough={
+                "n_estimators": randint(50, 300),
+                "max_depth": [5, 10, 20, 30, None],
+                "min_samples_split": randint(2, 20),
+                "min_samples_leaf": randint(1, 10),
+                "max_features": ["sqrt", "log2", None],
+            },
+        ),
+
+        # 3. HistGradientBoosting
+        ModelCandidate(
+            name="HistGradientBoosting",
+            estimator_factory=lambda random_seed=42, **kwargs: HistGradientBoostingClassifier(
+                random_state=random_seed, **kwargs
+            ),
+            task="classification",
+            supports_feature_importance=False,  # sklearn's HistGradientBoosting doesn't expose feature_importances_ natively
+            importance_type="none",
+            requires_scaling=False,
+            param_grid_fast={
+                "max_iter": [50, 100],
+                "learning_rate": [0.05, 0.1],
+            },
+            param_grid_balanced={
+                "max_iter": randint(50, 200),
+                "learning_rate": uniform(0.01, 0.25),
+                "max_depth": [3, 5, 10, None],
+                "min_samples_leaf": randint(10, 40),
+            },
+            param_grid_thorough={
+                "max_iter": randint(50, 300),
+                "learning_rate": uniform(0.005, 0.3),
+                "max_depth": [3, 5, 10, 20, None],
+                "min_samples_leaf": randint(5, 50),
+                "l2_regularization": uniform(0.0, 2.0),
+            },
+        ),
+
+        # 4. Decision Tree
+        ModelCandidate(
+            name="Decision Tree",
+            estimator_factory=lambda random_seed=42, **kwargs: DecisionTreeClassifier(
+                random_state=random_seed, **kwargs
+            ),
+            task="classification",
+            supports_feature_importance=True,
+            importance_type="tree",
+            requires_scaling=False,
+            param_grid_fast={
+                "max_depth": [3, 5, 10, None],
+            },
+            param_grid_balanced={
+                "max_depth": [3, 5, 10, 20, None],
+                "min_samples_split": randint(2, 15),
+                "min_samples_leaf": randint(1, 8),
+            },
+            param_grid_thorough={
+                "max_depth": [3, 5, 10, 20, 30, None],
+                "min_samples_split": randint(2, 30),
+                "min_samples_leaf": randint(1, 15),
+                "criterion": ["gini", "entropy", "log_loss"],
+            },
+        ),
+
+        # 5. K-Nearest Neighbors
+        ModelCandidate(
+            name="K-Nearest Neighbors",
+            estimator_factory=lambda random_seed=42, **kwargs: KNeighborsClassifier(
+                **kwargs
+            ),
+            task="classification",
+            supports_feature_importance=False,
+            importance_type="none",
+            requires_scaling=True,
+            param_grid_fast={
+                "n_neighbors": [3, 5, 7],
+            },
+            param_grid_balanced={
+                "n_neighbors": randint(3, 15),
+                "weights": ["uniform"],
+                "metric": ["euclidean", "manhattan"],
+            },
+            param_grid_thorough={
+                "n_neighbors": randint(2, 25),
+                "weights": ["uniform"],
+                "metric": ["euclidean", "manhattan", "minkowski"],
+                "p": [1, 2],
+            },
+        ),
+
+    ]

mlpipe/models/registry.py

@@ -0,0 +1,32 @@
+"""Model candidate representations and specifications."""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional, Type
+
+
+@dataclass
+class ModelCandidate:
+    """Specification of an ML estimator candidate."""
+
+    name: str
+    estimator_factory: Callable[..., Any]
+    task: str  # "classification" or "regression"
+    supports_feature_importance: bool = True
+    importance_type: str = "none"  # "tree", "linear", or "none"
+    requires_scaling: bool = False
+    param_grid_fast: Dict[str, Any] = field(default_factory=dict)
+    param_grid_balanced: Dict[str, Any] = field(default_factory=dict)
+    param_grid_thorough: Dict[str, Any] = field(default_factory=dict)
+
+    def create_estimator(self, random_seed: int = 42, **kwargs) -> Any:
+        """Instantiate estimator with seed if supported."""
+        return self.estimator_factory(random_seed=random_seed, **kwargs)
+
+    def get_search_space(self, mode: str) -> Dict[str, Any]:
+        """Return the hyperparameter search space for the given training mode."""
+        mode = mode.lower()
+        if mode == "fast":
+            return self.param_grid_fast
+        elif mode == "thorough":
+            return self.param_grid_thorough
+        return self.param_grid_balanced

mlpipe/models/regression.py

@@ -0,0 +1,126 @@
+"""Regression candidate models and parameter spaces."""
+
+from typing import List
+
+from scipy.stats import randint, uniform
+from sklearn.ensemble import (
+    HistGradientBoostingRegressor,
+    RandomForestRegressor,
+)
+from sklearn.linear_model import Ridge
+from sklearn.tree import DecisionTreeRegressor
+
+from mlpipe.models.registry import ModelCandidate
+
+
+def get_regression_candidates() -> List[ModelCandidate]:
+    """Return all registered regression candidates."""
+
+    return [
+        # 1. Ridge Regression
+        ModelCandidate(
+            name="Ridge",
+            estimator_factory=lambda random_seed=42, **kwargs: Ridge(
+                random_state=random_seed, **kwargs
+            ),
+            task="regression",
+            supports_feature_importance=True,
+            importance_type="linear",
+            requires_scaling=True,
+            param_grid_fast={
+                "alpha": [0.1, 1.0, 10.0],
+            },
+            param_grid_balanced={
+                "alpha": uniform(0.01, 50.0),
+                "solver": ["auto", "svd", "cholesky", "lsqr"],
+            },
+            param_grid_thorough={
+                "alpha": uniform(0.001, 200.0),
+                "solver": ["auto", "svd", "cholesky", "lsqr", "sag"],
+            },
+        ),
+
+        # 2. Random Forest Regressor
+        ModelCandidate(
+            name="Random Forest Regressor",
+            estimator_factory=lambda random_seed=42, **kwargs: RandomForestRegressor(
+                random_state=random_seed, n_jobs=-1, **kwargs
+            ),
+            task="regression",
+            supports_feature_importance=True,
+            importance_type="tree",
+            requires_scaling=False,
+            param_grid_fast={
+                "n_estimators": [50, 100],
+                "max_depth": [5, 10, None],
+            },
+            param_grid_balanced={
+                "n_estimators": randint(50, 200),
+                "max_depth": [5, 10, 20, None],
+                "min_samples_split": randint(2, 10),
+                "min_samples_leaf": randint(1, 6),
+            },
+            param_grid_thorough={
+                "n_estimators": randint(50, 300),
+                "max_depth": [5, 10, 20, 30, None],
+                "min_samples_split": randint(2, 20),
+                "min_samples_leaf": randint(1, 10),
+                "max_features": ["sqrt", "log2", 1.0],
+            },
+        ),
+
+        # 3. HistGradientBoosting Regressor
+        ModelCandidate(
+            name="HistGradientBoosting Regressor",
+            estimator_factory=lambda random_seed=42, **kwargs: HistGradientBoostingRegressor(
+                random_state=random_seed, **kwargs
+            ),
+            task="regression",
+            supports_feature_importance=False,
+            importance_type="none",
+            requires_scaling=False,
+            param_grid_fast={
+                "max_iter": [50, 100],
+                "learning_rate": [0.05, 0.1],
+            },
+            param_grid_balanced={
+                "max_iter": randint(50, 200),
+                "learning_rate": uniform(0.01, 0.25),
+                "max_depth": [3, 5, 10, None],
+                "min_samples_leaf": randint(10, 40),
+            },
+            param_grid_thorough={
+                "max_iter": randint(50, 300),
+                "learning_rate": uniform(0.005, 0.3),
+                "max_depth": [3, 5, 10, 20, None],
+                "min_samples_leaf": randint(5, 50),
+                "l2_regularization": uniform(0.0, 2.0),
+            },
+        ),
+
+        # 4. Decision Tree Regressor
+        ModelCandidate(
+            name="Decision Tree Regressor",
+            estimator_factory=lambda random_seed=42, **kwargs: DecisionTreeRegressor(
+                random_state=random_seed, **kwargs
+            ),
+            task="regression",
+            supports_feature_importance=True,
+            importance_type="tree",
+            requires_scaling=False,
+            param_grid_fast={
+                "max_depth": [3, 5, 10, None],
+            },
+            param_grid_balanced={
+                "max_depth": [3, 5, 10, 20, None],
+                "min_samples_split": randint(2, 15),
+                "min_samples_leaf": randint(1, 8),
+            },
+            param_grid_thorough={
+                "max_depth": [3, 5, 10, 20, 30, None],
+                "min_samples_split": randint(2, 30),
+                "min_samples_leaf": randint(1, 15),
+                "criterion": ["squared_error", "friedman_mse", "absolute_error"],
+            },
+        ),
+    ]

mlpipe/models/selection.py

@@ -0,0 +1,24 @@
+"""Model selection and retrieval helpers."""
+
+from typing import List
+
+from mlpipe.models.classification import get_classification_candidates
+from mlpipe.models.regression import get_regression_candidates
+from mlpipe.models.registry import ModelCandidate
+
+
+def get_candidates_for_task(task_type: str, mode: str = "balanced") -> List[ModelCandidate]:
+    """
+    Retrieve appropriate candidate models for a given task and training mode.
+    """
+    if task_type == "classification":
+        candidates = get_classification_candidates()
+    elif task_type == "regression":
+        candidates = get_regression_candidates()
+    else:
+        raise ValueError(f"Unknown task type '{task_type}'")
+
+    if mode == "fast":
+        # For fast mode, we still evaluate all models or the fastest subset
+        return candidates
+    return candidates

mlpipe/preprocessing/__init__.py

@@ -0,0 +1,21 @@
+"""Feature preprocessing pipelines and builders for MLPipe."""
+
+from mlpipe.preprocessing.builder import (
+    ColumnAssignments,
+    build_preprocessor,
+    classify_columns,
+    get_transformed_feature_names,
+)
+from mlpipe.preprocessing.categorical import build_categorical_transformer
+from mlpipe.preprocessing.datetime import DatetimeFeatureExtractor
+from mlpipe.preprocessing.numeric import build_numeric_transformer
+
+__all__ = [
+    "ColumnAssignments",
+    "build_preprocessor",
+    "classify_columns",
+    "get_transformed_feature_names",
+    "build_categorical_transformer",
+    "DatetimeFeatureExtractor",
+    "build_numeric_transformer",
+]

mlpipe/preprocessing/builder.py

@@ -0,0 +1,163 @@
+"""
+Preprocessing pipeline builder and column classifier for MLPipe.
+
+Constructs unified sklearn ColumnTransformer structures with leakage-free feature processing.
+"""
+
+from dataclasses import dataclass
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+from sklearn.compose import ColumnTransformer
+from sklearn.pipeline import Pipeline
+
+from mlpipe.core.exceptions import PreprocessingError
+from mlpipe.data.profiling import detect_column_type
+from mlpipe.preprocessing.categorical import build_categorical_transformer
+from mlpipe.preprocessing.datetime import DatetimeFeatureExtractor
+from mlpipe.preprocessing.numeric import build_numeric_transformer
+from mlpipe.utils.logging import get_logger
+
+logger = get_logger("preprocessing")
+
+
+@dataclass
+class ColumnAssignments:
+    """Summary of column assignments across transformation types."""
+
+    numeric: List[str]
+    categorical: List[str]
+    datetime: List[str]
+    dropped: List[str]
+
+    def to_dict(self) -> Dict[str, List[str]]:
+        return {
+            "numeric": self.numeric,
+            "categorical": self.categorical,
+            "datetime": self.datetime,
+            "dropped": self.dropped,
+        }
+
+
+def classify_columns(df: pd.DataFrame) -> ColumnAssignments:
+    """
+    Categorize columns into numeric, categorical, datetime, or dropped.
+
+    Drops:
+    - Constant columns (<= 1 unique value)
+    - Columns with > 90% missing values
+    - Obvious unique ID / index columns (all unique string/integer identifiers)
+    """
+    n_rows = len(df)
+    numeric_cols: List[str] = []
+    categorical_cols: List[str] = []
+    datetime_cols: List[str] = []
+    dropped_cols: List[str] = []
+
+    id_pattern = re.compile(r"(^id$|_id$|^id_|^index$|^guid$|^uuid$)", re.IGNORECASE)
+
+    for col in df.columns:
+        series = df[col]
+        non_null = series.dropna()
+        n_unique = non_null.nunique()
+
+        # 1. Constant column check
+        if n_unique <= 1:
+            dropped_cols.append(col)
+            logger.info("Dropping constant column '%s' (unique values: %d)", col, n_unique)
+            continue
+
+        # 2. Extreme missingness check (> 90%)
+        if series.isna().mean() > 0.90:
+            dropped_cols.append(col)
+            logger.info("Dropping column '%s' with >90%% missing values", col)
+            continue
+
+        # 3. ID / index column heuristic
+        if n_unique == n_rows and (id_pattern.search(str(col)) or series.dtype == object):
+            dropped_cols.append(col)
+            logger.info("Dropping identifier column '%s' (100%% unique values)", col)
+            continue
+
+        detected = detect_column_type(series)
+        if detected == "numeric":
+            numeric_cols.append(col)
+        elif detected == "datetime":
+            datetime_cols.append(col)
+        else:  # categorical or boolean
+            categorical_cols.append(col)
+
+    if not numeric_cols and not categorical_cols and not datetime_cols:
+        raise PreprocessingError(
+            "No usable feature columns remain after filtering constant/ID/missing columns.",
+            "Verify that your dataset contains informative feature columns with variation."
+        )
+
+    return ColumnAssignments(
+        numeric=numeric_cols,
+        categorical=categorical_cols,
+        datetime=datetime_cols,
+        dropped=dropped_cols,
+    )
+
+
+def build_preprocessor(
+    assignments: ColumnAssignments,
+    with_scaling: bool = True,
+) -> ColumnTransformer:
+    """
+    Construct an unfitted ColumnTransformer based on column assignments.
+
+    Args:
+        assignments: ColumnAssignments partitioning features.
+        with_scaling: Whether to apply StandardScaler to numeric features.
+
+    Returns:
+        Unfitted ColumnTransformer instance.
+    """
+    transformers = []
+
+    if assignments.numeric:
+        num_pipeline = build_numeric_transformer(with_scaling=with_scaling)
+        transformers.append(("numeric", num_pipeline, assignments.numeric))
+
+    if assignments.categorical:
+        cat_pipeline = build_categorical_transformer()
+        transformers.append(("categorical", cat_pipeline, assignments.categorical))
+
+    if assignments.datetime:
+        dt_pipeline = Pipeline([
+            ("extractor", DatetimeFeatureExtractor())
+        ])
+        transformers.append(("datetime", dt_pipeline, assignments.datetime))
+
+    return ColumnTransformer(
+        transformers=transformers,
+        remainder="drop",
+        verbose_feature_names_out=False,
+    )
+
+
+def get_transformed_feature_names(fitted_preprocessor: ColumnTransformer) -> List[str]:
+    """
+    Extract human-readable feature names from a fitted ColumnTransformer.
+    """
+    try:
+        return list(fitted_preprocessor.get_feature_names_out())
+    except Exception as e:
+        logger.debug("Failed to get feature names via get_feature_names_out: %s", e)
+        # Fallback: inspect transformers
+        names: List[str] = []
+        for name, trans, cols in fitted_preprocessor.transformers_:
+            if name == "remainder" or trans == "drop":
+                continue
+            if hasattr(trans, "get_feature_names_out"):
+                try:
+                    names.extend(list(trans.get_feature_names_out(cols)))
+                except Exception:
+                    names.extend(list(cols))
+            else:
+                names.extend(list(cols))
+        return names

mlpipe/preprocessing/categorical.py

@@ -0,0 +1,17 @@
+"""Categorical feature preprocessing pipelines."""
+
+from sklearn.impute import SimpleImputer
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import OneHotEncoder
+
+
+def build_categorical_transformer() -> Pipeline:
+    """
+    Build a preprocessing pipeline for categorical features.
+
+    Applies most-frequent imputation followed by one-hot encoding with unseen category handling.
+    """
+    return Pipeline([
+        ("imputer", SimpleImputer(strategy="most_frequent")),
+        ("encoder", OneHotEncoder(handle_unknown="ignore", sparse_output=False)),
+    ])

mlpipe/preprocessing/datetime.py

@@ -0,0 +1,55 @@
+"""Datetime feature extraction transformer."""
+
+from typing import List, Optional
+
+import numpy as np
+import pandas as pd
+from sklearn.base import BaseEstimator, TransformerMixin
+
+
+class DatetimeFeatureExtractor(BaseEstimator, TransformerMixin):
+    """
+    Extracts tabular calendar features (year, month, day, dayofweek) from datetime columns.
+    """
+
+    def __init__(self):
+        self.feature_names_: List[str] = []
+
+    def fit(self, X, y=None):
+        cols = X.columns if hasattr(X, "columns") else [f"dt_{i}" for i in range(X.shape[1])]
+        names = []
+        for col in cols:
+            names.extend([
+                f"{col}_year",
+                f"{col}_month",
+                f"{col}_day",
+                f"{col}_dayofweek",
+            ])
+        self.feature_names_ = names
+        return self
+
+    def transform(self, X):
+        df = X if isinstance(X, pd.DataFrame) else pd.DataFrame(X)
+        extracted = []
+
+        for col in df.columns:
+            s = pd.to_datetime(df[col], errors="coerce")
+            extracted.append(s.dt.year.fillna(-1).astype(float).values)
+            extracted.append(s.dt.month.fillna(-1).astype(float).values)
+            extracted.append(s.dt.day.fillna(-1).astype(float).values)
+            extracted.append(s.dt.dayofweek.fillna(-1).astype(float).values)
+
+        if not extracted:
+            return np.empty((len(df), 0))
+
+        return np.column_stack(extracted)
+
+    def get_feature_names_out(self, input_features: Optional[List[str]] = None) -> List[str]:
+        if self.feature_names_:
+            return self.feature_names_
+        if input_features is not None:
+            names = []
+            for col in input_features:
+                names.extend([f"{col}_year", f"{col}_month", f"{col}_day", f"{col}_dayofweek"])
+            return names
+        return []

mlpipe/preprocessing/numeric.py

@@ -0,0 +1,17 @@
+"""Numeric feature preprocessing pipelines."""
+
+from sklearn.impute import SimpleImputer
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+
+
+def build_numeric_transformer(with_scaling: bool = True) -> Pipeline:
+    """
+    Build a preprocessing pipeline for numeric features.
+
+    Applies median imputation followed optionally by standard scaling.
+    """
+    steps = [("imputer", SimpleImputer(strategy="median"))]
+    if with_scaling:
+        steps.append(("scaler", StandardScaler()))
+    return Pipeline(steps)

mlpipe/tuning/__init__.py

@@ -0,0 +1,10 @@
+"""Hyperparameter tuning and search engine for MLPipe."""
+
+from mlpipe.tuning.search import TuningResult, tune_candidate
+from mlpipe.tuning.spaces import get_search_iterations
+
+__all__ = [
+    "TuningResult",
+    "tune_candidate",
+    "get_search_iterations",
+]