mlfox 1.0.1__py3-none-any.whl

mlfox/__init__.py

@@ -0,0 +1,52 @@
+from .ingestion import load_dataset
+from .profiler import DatasetProfile, profile_dataset, detect_task, is_discrete_numeric_multiclass
+from .splitter import DatasetSplit, split_dataset
+from .feature_selection import (
+    FeatureSelectionIntelligence,
+    FeatureSelectionReport
+)
+from .column_intelligence import (
+    ColumnIntelligenceReport,
+    analyze_columns
+)
+
+from .missing_intelligence import (
+    MissingValueIntelligence,
+    MissingValueReport
+)
+
+from .feature_engineering import (
+    FeatureEngineeringIntelligence,
+    FeatureEngineeringReport
+)
+
+from .encoding import (
+    EncodingScalingIntelligence,
+    EncodingReport
+)
+from .pipeline import FoldAwarePreprocessor
+from .model_selection import ModelSelectionEngine
+from .tuning import HyperparameterTuner
+from .mlfox import MLFOX, mlfox
+from .persistence import load_model
+
+__all__ = [
+    "load_dataset",
+    "DatasetProfile",
+    "profile_dataset",
+    "detect_task",
+    "is_discrete_numeric_multiclass",
+    "DatasetSplit",
+    "split_dataset",
+    "ColumnIntelligenceReport",
+    "analyze_columns",
+    "MissingValueIntelligence",
+    "MissingValueReport",
+    "FeatureEngineeringIntelligence",
+    "FeatureEngineeringReport",
+    "EncodingScalingIntelligence",
+    "EncodingReport",
+    "FeatureSelectionIntelligence",
+    "FeatureSelectionReport"
+    , "FoldAwarePreprocessor", "ModelSelectionEngine", "HyperparameterTuner", "MLFOX", "mlfox", "load_model"
+]

mlfox/column_intelligence.py

@@ -0,0 +1,315 @@
+
+from dataclasses import dataclass, asdict
+import re
+
+import pandas as pd
+
+
+@dataclass
+class ColumnIntelligenceReport:
+    numerical_columns: list
+    categorical_columns: list
+    datetime_columns: list
+    other_columns: list
+    constant_columns: list
+    duplicate_columns: list
+    possible_identifiers: list
+    high_missing_columns: list
+    high_cardinality_columns: list
+    high_correlation_pairs: list
+    possible_target_leakage: list
+    column_details: dict
+    warnings: list
+
+    def to_dict(self):
+        return asdict(self)
+
+
+def _is_identifier_name(column):
+    name = str(column).strip().lower()
+
+    # Pandas-generated CSV index columns
+    if re.fullmatch(r"unnamed(?::\s*\d+)?", name):
+        return True
+
+    compact = re.sub(r"[^a-z0-9]", "", name)
+    tokens = re.split(r"[^a-z0-9]+", name)
+
+    identifier_tokens = {
+        "id", "uuid", "identifier", "index",
+        "record", "row", "serial"
+    }
+
+    return (
+        any(token in identifier_tokens for token in tokens)
+        or compact.endswith("id")
+        or compact in {
+            "index", "rownumber", "serialnumber"
+        }
+    )
+
+
+def _is_one_to_one_mapping(feature, target, max_levels=20):
+    paired = pd.DataFrame({
+        "feature": feature,
+        "target": target
+    }).dropna()
+
+    if paired.empty:
+        return False
+
+    feature_count = paired["feature"].nunique()
+    target_count = paired["target"].nunique()
+
+    if (
+        feature_count < 2
+        or feature_count > max_levels
+        or feature_count != target_count
+    ):
+        return False
+
+    feature_mapping = (
+        paired.groupby("feature")["target"].nunique()
+    )
+
+    target_mapping = (
+        paired.groupby("target")["feature"].nunique()
+    )
+
+    return (
+        feature_mapping.max() == 1
+        and target_mapping.max() == 1
+    )
+
+
+def analyze_columns(
+    X_train,
+    y_train=None,
+    target=None,
+    missing_threshold=0.50,
+    max_categories=50,
+    correlation_threshold=0.98
+):
+    if not isinstance(X_train, pd.DataFrame):
+        raise TypeError("X_train must be a pandas DataFrame.")
+
+    if X_train.empty:
+        raise ValueError("Training features are empty.")
+
+    if not 0 < missing_threshold <= 1:
+        raise ValueError("missing_threshold must be between 0 and 1.")
+
+    if max_categories < 2:
+        raise ValueError("max_categories must be at least 2.")
+
+    if not 0 < correlation_threshold <= 1:
+        raise ValueError("correlation_threshold must be between 0 and 1.")
+
+    if not X_train.columns.is_unique:
+        raise ValueError("Duplicate feature column names detected.")
+
+    if y_train is not None:
+        if not isinstance(y_train, pd.Series):
+            raise TypeError("y_train must be a pandas Series.")
+
+        if not X_train.index.equals(y_train.index):
+            raise ValueError("X_train and y_train indices must match.")
+
+    numerical = []
+    categorical = []
+    datetime = []
+    other = []
+
+    constant = []
+    duplicates = []
+    identifiers = []
+    high_missing = []
+    high_cardinality = []
+    leakage = []
+    correlation_pairs = []
+    details = {}
+    warnings = []
+
+    # Analyze individual columns
+    for column in X_train.columns:
+        series = X_train[column]
+
+        missing_count = int(series.isna().sum())
+        missing_ratio = missing_count / len(X_train)
+
+        unique_count = int(series.nunique(dropna=True))
+        non_missing_count = int(series.notna().sum())
+
+        unique_ratio = (
+            unique_count / non_missing_count
+            if non_missing_count else 0.0
+        )
+
+        if pd.api.types.is_datetime64_any_dtype(series):
+            role = "datetime"
+            datetime.append(column)
+
+        elif pd.api.types.is_bool_dtype(series):
+            role = "categorical"
+            categorical.append(column)
+
+        elif pd.api.types.is_numeric_dtype(series):
+            role = "numerical"
+            numerical.append(column)
+
+        elif (
+            pd.api.types.is_object_dtype(series)
+            or pd.api.types.is_string_dtype(series)
+            or isinstance(series.dtype, pd.CategoricalDtype)
+        ):
+            role = "categorical"
+            categorical.append(column)
+
+        else:
+            role = "other"
+            other.append(column)
+
+        details[str(column)] = {
+            "dtype": str(series.dtype),
+            "role": role,
+            "missing_count": missing_count,
+            "missing_percentage": round(missing_ratio * 100, 2),
+            "unique_count": unique_count,
+            "unique_ratio": round(unique_ratio, 4)
+        }
+
+        if unique_count <= 1:
+            constant.append(column)
+
+        if missing_ratio >= missing_threshold:
+            high_missing.append({
+                "column": column,
+                "missing_percentage": round(missing_ratio * 100, 2)
+            })
+
+        if (
+            role == "categorical"
+            and unique_count > max_categories
+        ):
+            high_cardinality.append({
+                "column": column,
+                "unique_count": unique_count,
+                "unique_ratio": round(unique_ratio, 4)
+            })
+
+        # Possible identifiers
+        name_hint = _is_identifier_name(column)
+
+        sequential = (
+            non_missing_count > 1
+            and unique_count == non_missing_count
+            and (
+                series.is_monotonic_increasing
+                or series.is_monotonic_decreasing
+            )
+        )
+
+        if name_hint or (
+            unique_ratio >= 0.98 and sequential
+        ):
+            identifiers.append({
+                "column": column,
+                "unique_ratio": round(unique_ratio, 4),
+                "reasons": [
+                    reason for condition, reason in [
+                        (name_hint, "identifier-like column name"),
+                        (sequential, "unique sequential values")
+                    ] if condition
+                ]
+            })
+
+        # Potential target leakage
+        if y_train is not None:
+            paired = pd.concat(
+                [series.rename("feature"), y_train.rename("target")],
+                axis=1
+            ).dropna()
+
+            exact_match = (
+                not paired.empty
+                and paired["feature"].reset_index(drop=True).equals(
+                    paired["target"].reset_index(drop=True)
+                )
+            )
+
+            one_to_one = _is_one_to_one_mapping(
+                series, y_train
+            )
+
+            if exact_match or one_to_one:
+                leakage.append({
+                    "column": column,
+                    "reason": (
+                        "exact target match"
+                        if exact_match
+                        else "one-to-one mapping with target"
+                    )
+                })
+
+    # Detect duplicate columns
+    columns = list(X_train.columns)
+
+    for i, column in enumerate(columns):
+        for other_column in columns[i + 1:]:
+            left = X_train[column].reset_index(drop=True)
+            right = X_train[other_column].reset_index(drop=True)
+
+            if left.equals(right):
+                duplicates.append({
+                    "column": other_column,
+                    "duplicate_of": column
+                })
+
+    # Detect highly correlated numerical features
+    if len(numerical) > 1:
+        corr = X_train[numerical].corr()
+
+        for i, column_a in enumerate(numerical):
+            for column_b in numerical[i + 1:]:
+                value = corr.loc[column_a, column_b]
+
+                if (
+                    pd.notna(value)
+                    and abs(value) >= correlation_threshold
+                ):
+                    correlation_pairs.append({
+                        "feature_1": column_a,
+                        "feature_2": column_b,
+                        "correlation": round(float(value), 4)
+                    })
+
+    if identifiers:
+        warnings.append("Possible identifier columns detected.")
+
+    if high_missing:
+        warnings.append("Columns with high missingness detected.")
+
+    if high_cardinality:
+        warnings.append("High-cardinality categorical columns detected.")
+
+    if leakage:
+        warnings.append("Possible target leakage detected.")
+
+    if correlation_pairs:
+        warnings.append("Highly correlated numerical features detected.")
+
+    return ColumnIntelligenceReport(
+        numerical_columns=numerical,
+        categorical_columns=categorical,
+        datetime_columns=datetime,
+        other_columns=other,
+        constant_columns=constant,
+        duplicate_columns=duplicates,
+        possible_identifiers=identifiers,
+        high_missing_columns=high_missing,
+        high_cardinality_columns=high_cardinality,
+        high_correlation_pairs=correlation_pairs,
+        possible_target_leakage=leakage,
+        column_details=details,
+        warnings=warnings
+    )

mlfox/encoding.py

@@ -0,0 +1,256 @@
+
+from dataclasses import dataclass, asdict
+
+import numpy as np
+import pandas as pd
+
+from sklearn.preprocessing import OneHotEncoder, StandardScaler
+
+
+@dataclass
+class EncodingReport:
+    numerical_columns: list
+    categorical_columns: list
+    scaled_columns: list
+    encoded_columns: list
+    input_features: int
+    output_features: int
+    max_categories: int
+    warnings: list
+
+    def to_dict(self):
+        return asdict(self)
+
+
+class EncodingScalingIntelligence:
+
+    def __init__(self, max_categories=100):
+        if max_categories < 2:
+            raise ValueError("max_categories must be at least 2.")
+
+        self.max_categories = max_categories
+        self.fitted_ = False
+
+    @staticmethod
+    def _create_encoder(max_categories):
+        try:
+            return OneHotEncoder(
+                handle_unknown="ignore",
+                sparse_output=False,
+                max_categories=max_categories
+            )
+        except TypeError:
+            try:
+                return OneHotEncoder(
+                    handle_unknown="ignore",
+                    sparse=False,
+                    max_categories=max_categories
+                )
+            except TypeError:
+                return OneHotEncoder(
+                    handle_unknown="ignore",
+                    sparse=False
+                )
+
+    def fit(self, X_train):
+
+        if not isinstance(X_train, pd.DataFrame):
+            raise TypeError("X_train must be a pandas DataFrame.")
+
+        if X_train.empty:
+            raise ValueError("Training dataset is empty.")
+
+        if not X_train.columns.is_unique:
+            raise ValueError("Duplicate feature names detected.")
+
+        if not all(isinstance(c, str) for c in X_train.columns):
+            raise TypeError("All feature column names must be strings.")
+
+        if X_train.isna().any().any():
+            raise ValueError(
+                "Missing values detected. Run M5 before M7."
+            )
+
+        self.feature_columns_ = list(X_train.columns)
+
+        self.numeric_columns_ = [
+            col for col in self.feature_columns_
+            if (
+                pd.api.types.is_numeric_dtype(X_train[col])
+                and not pd.api.types.is_bool_dtype(X_train[col])
+            )
+        ]
+
+        self.categorical_columns_ = [
+            col for col in self.feature_columns_
+            if col not in self.numeric_columns_
+        ]
+
+        # Datetime features should already be handled by M6.
+        datetime_columns = [
+            col for col in self.feature_columns_
+            if pd.api.types.is_datetime64_any_dtype(X_train[col])
+        ]
+
+        if datetime_columns:
+            raise ValueError(
+                "Datetime columns remain. Run M6 first: "
+                f"{datetime_columns}"
+            )
+
+        if not self.numeric_columns_ and not self.categorical_columns_:
+            raise ValueError("No usable features found.")
+
+        self.scaler_ = None
+        self.encoder_ = None
+
+        output_names = []
+        self.warnings_ = []
+
+        # Numerical scaling
+        if self.numeric_columns_:
+            numeric_data = X_train[
+                self.numeric_columns_
+            ].astype("float64")
+
+            if not np.isfinite(numeric_data.to_numpy()).all():
+                raise ValueError(
+                    "Numerical features contain infinite values."
+                )
+
+            self.scaler_ = StandardScaler()
+            self.scaler_.fit(numeric_data)
+
+            output_names.extend([
+                f"num__{col}"
+                for col in self.numeric_columns_
+            ])
+
+        # Categorical encoding
+        if self.categorical_columns_:
+            categorical_data = (
+                X_train[self.categorical_columns_]
+                .astype(str)
+            )
+
+            self.encoder_ = self._create_encoder(
+                self.max_categories
+            )
+
+            self.encoder_.fit(categorical_data)
+
+            encoded_names = (
+                self.encoder_.get_feature_names_out(
+                    self.categorical_columns_
+                )
+            )
+
+            output_names.extend([
+                f"cat__{name}"
+                for name in encoded_names
+            ])
+
+        self.feature_names_out_ = output_names
+
+        if not self.categorical_columns_:
+            self.warnings_.append(
+                "No categorical columns required encoding."
+            )
+
+        if not self.numeric_columns_:
+            self.warnings_.append(
+                "No numerical columns required scaling."
+            )
+
+        self.report_ = EncodingReport(
+            numerical_columns=self.numeric_columns_,
+            categorical_columns=self.categorical_columns_,
+            scaled_columns=self.numeric_columns_,
+            encoded_columns=self.categorical_columns_,
+            input_features=len(self.feature_columns_),
+            output_features=len(self.feature_names_out_),
+            max_categories=self.max_categories,
+            warnings=self.warnings_
+        )
+
+        self.fitted_ = True
+        return self
+
+    def transform(self, X):
+
+        if not self.fitted_:
+            raise RuntimeError("Call fit() before transform().")
+
+        if not isinstance(X, pd.DataFrame):
+            raise TypeError("X must be a pandas DataFrame.")
+
+        missing = [
+            col for col in self.feature_columns_
+            if col not in X.columns
+        ]
+
+        if missing:
+            raise ValueError(
+                f"Missing expected columns: {missing}"
+            )
+
+        data = X.loc[:, self.feature_columns_]
+
+        if data.isna().any().any():
+            raise ValueError(
+                "Missing values detected. Run M5 before M7."
+            )
+
+        output_blocks = []
+
+        # Transform numerical features
+        if self.numeric_columns_:
+            numeric_data = data[
+                self.numeric_columns_
+            ].astype("float64")
+
+            numeric_array = numeric_data.to_numpy()
+
+            if not np.isfinite(numeric_array).all():
+                raise ValueError(
+                    "Numerical features contain infinite values."
+                )
+
+            scaled = self.scaler_.transform(numeric_data)
+            output_blocks.append(scaled)
+
+        # Transform categorical features
+        if self.categorical_columns_:
+            categorical_data = (
+                data[self.categorical_columns_]
+                .astype(str)
+            )
+
+            encoded = self.encoder_.transform(
+                categorical_data
+            )
+
+            output_blocks.append(encoded)
+
+        output = np.hstack(output_blocks)
+
+        return pd.DataFrame(
+            output,
+            index=X.index,
+            columns=self.feature_names_out_
+        )
+
+    def fit_transform(self, X_train):
+        return self.fit(X_train).transform(X_train)
+
+    def get_feature_names_out(self):
+        if not self.fitted_:
+            raise RuntimeError("The encoder has not been fitted.")
+
+        return list(self.feature_names_out_)
+
+    def to_dict(self):
+        if not self.fitted_:
+            raise RuntimeError("The encoder has not been fitted.")
+
+        return self.report_.to_dict()

mlfox/evaluation.py

@@ -0,0 +1,58 @@
+"""Cross-validation and one-time holdout metrics."""
+import numpy as np
+from sklearn.base import clone
+from sklearn.model_selection import StratifiedKFold, KFold
+from sklearn.metrics import (accuracy_score, balanced_accuracy_score, precision_score, recall_score, f1_score, roc_auc_score, r2_score, mean_absolute_error, mean_squared_error)
+
+def metric_values(model, X, y, task_type):
+    pred = model.predict(X)
+    if task_type == "regression":
+        return {"r2": float(r2_score(y, pred)), "mae": float(mean_absolute_error(y, pred)), "rmse": float(np.sqrt(mean_squared_error(y, pred)))}
+    result = {"accuracy": float(accuracy_score(y, pred)), "balanced_accuracy": float(balanced_accuracy_score(y, pred)), "precision": float(precision_score(y, pred, average="weighted", zero_division=0)), "recall": float(recall_score(y, pred, average="weighted", zero_division=0)), "f1": float(f1_score(y, pred, average="weighted", zero_division=0))}
+    try:
+        prob = model.predict_proba(X)
+        result["roc_auc"] = float(roc_auc_score(y, prob[:, 1] if prob.shape[1] == 2 else prob, multi_class="ovr" if prob.shape[1] > 2 else "raise", average="weighted"))
+    except (AttributeError, ValueError):
+        result["roc_auc"] = None
+    return result
+
+def cross_validate_pipeline(pipeline, X, y, task_type, cv=5, random_state=42,
+                            event_callback=None, candidate_name=None, diagnostics=None):
+    if diagnostics is None:
+        diagnostics = event_callback is not None
+    counts = y.value_counts() if task_type != "regression" else None
+    folds = min(cv, int(counts.min())) if counts is not None else min(cv, len(y))
+    if folds < 2: raise ValueError("At least two valid CV folds are required.")
+    splitter = StratifiedKFold(folds, shuffle=True, random_state=random_state) if counts is not None else KFold(folds, shuffle=True, random_state=random_state)
+    collected = {}
+    for fold_number, (train_idx, valid_idx) in enumerate(splitter.split(X, y), 1):
+        candidate = clone(pipeline)
+        pre_id = id(candidate.named_steps["preprocessing"])
+        def emit(event_type, details=None):
+            if event_callback:
+                event_callback({"event_type": event_type, "candidate": candidate_name,
+                    "fold": fold_number, "preprocessor_id": pre_id,
+                    "details": details or {}})
+        emit("fold_started", {"train_indices": X.index[train_idx].tolist(), "validation_indices": X.index[valid_idx].tolist()} if diagnostics else {})
+        try:
+            candidate.fit(X.iloc[train_idx], y.iloc[train_idx])
+            if diagnostics:
+                details = {"train_indices": X.index[train_idx].tolist(),
+                           "imputer_statistics": candidate.named_steps["preprocessing"].imputer_.fill_values_.copy(),
+                           "selector_input_indices": X.index[train_idx].tolist(),
+                           "selector_labels": y.iloc[train_idx].tolist(),
+                           "preprocessor": candidate.named_steps["preprocessing"],
+                           "fitted_pipeline": candidate}
+            else:
+                details = {"training_rows": len(train_idx)}
+            emit("preprocessing_fitted", details)
+            emit("model_fitted")
+        except Exception as exc:
+            emit("candidate_failed", {"exception": repr(exc)})
+            raise
+        scores = metric_values(candidate, X.iloc[valid_idx], y.iloc[valid_idx], task_type)
+        emit("fold_completed", {"metrics": scores})
+        for key, value in scores.items():
+            if value is not None: collected.setdefault(key, []).append(value)
+    summary = {key: {"mean": float(np.mean(vals)), "std": float(np.std(vals, ddof=1)) if len(vals)>1 else 0.0} for key, vals in collected.items()}
+    return summary, folds