autoforge-engine 0.1.0__py3-none-any.whl

modelforge/prediction_validator.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+
+class PredictionSchemaError(ValueError):
+    """Raised when prediction data does not match the expected schema."""
+
+
+class PredictionSchemaValidator:
+    """
+    Validate prediction data against a training feature schema.
+
+    The validator checks:
+        - required columns
+        - unexpected columns
+        - column order
+        - empty datasets
+        - basic data types
+    """
+
+    def __init__(
+        self,
+        allow_extra_columns: bool = True,
+        enforce_column_order: bool = False,
+        enforce_dtypes: bool = False,
+    ):
+        if not isinstance(
+            allow_extra_columns,
+            bool,
+        ):
+            raise TypeError(
+                "allow_extra_columns must be a boolean."
+            )
+
+        if not isinstance(
+            enforce_column_order,
+            bool,
+        ):
+            raise TypeError(
+                "enforce_column_order must be a boolean."
+            )
+
+        if not isinstance(
+            enforce_dtypes,
+            bool,
+        ):
+            raise TypeError(
+                "enforce_dtypes must be a boolean."
+            )
+
+        self.allow_extra_columns = (
+            allow_extra_columns
+        )
+
+        self.enforce_column_order = (
+            enforce_column_order
+        )
+
+        self.enforce_dtypes = (
+            enforce_dtypes
+        )
+
+    def validate(
+        self,
+        data: pd.DataFrame,
+        expected_columns: list[str],
+        expected_dtypes: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Validate prediction data.
+
+        Returns a validation report.
+
+        Raises:
+            TypeError:
+                If inputs have invalid types.
+
+            PredictionSchemaError:
+                If the prediction schema is invalid.
+        """
+
+        if not isinstance(
+            data,
+            pd.DataFrame,
+        ):
+            raise TypeError(
+                "data must be a pandas DataFrame."
+            )
+
+        if not isinstance(
+            expected_columns,
+            list,
+        ):
+            raise TypeError(
+                "expected_columns must be a list."
+            )
+
+        if not all(
+            isinstance(column, str)
+            for column in expected_columns
+        ):
+            raise TypeError(
+                "expected_columns must contain strings."
+            )
+
+        if expected_dtypes is not None:
+            if not isinstance(
+                expected_dtypes,
+                dict,
+            ):
+                raise TypeError(
+                    "expected_dtypes must be a dictionary."
+                )
+
+        if data.empty:
+            raise PredictionSchemaError(
+                "Prediction data is empty."
+            )
+
+        actual_columns = list(
+            data.columns
+        )
+
+        missing_columns = [
+            column
+            for column in expected_columns
+            if column not in actual_columns
+        ]
+
+        unexpected_columns = [
+            column
+            for column in actual_columns
+            if column not in expected_columns
+        ]
+
+        order_matches = (
+            actual_columns
+            == expected_columns
+        )
+
+        dtype_mismatches = {}
+
+        if (
+            self.enforce_dtypes
+            and expected_dtypes is not None
+        ):
+            for column in expected_columns:
+                if column not in data.columns:
+                    continue
+
+                expected_dtype = str(
+                    expected_dtypes.get(
+                        column,
+                        "",
+                    )
+                )
+
+                actual_dtype = str(
+                    data[column].dtype
+                )
+
+                if (
+                    expected_dtype
+                    and actual_dtype
+                    != expected_dtype
+                ):
+                    dtype_mismatches[column] = {
+                        "expected": expected_dtype,
+                        "actual": actual_dtype,
+                    }
+
+        errors = []
+
+        if missing_columns:
+            errors.append(
+                "Missing required columns: "
+                + ", ".join(
+                    missing_columns
+                )
+            )
+
+        if (
+            unexpected_columns
+            and not self.allow_extra_columns
+        ):
+            errors.append(
+                "Unexpected columns: "
+                + ", ".join(
+                    unexpected_columns
+                )
+            )
+
+        if (
+            self.enforce_column_order
+            and not order_matches
+        ):
+            errors.append(
+                "Column order does not match "
+                "the expected feature order."
+            )
+
+        if dtype_mismatches:
+            errors.append(
+                "Data type mismatch for columns: "
+                + ", ".join(
+                    dtype_mismatches.keys()
+                )
+            )
+
+        valid = not errors
+
+        report = {
+            "valid": valid,
+            "expected_columns": expected_columns,
+            "actual_columns": actual_columns,
+            "missing_columns": missing_columns,
+            "unexpected_columns": unexpected_columns,
+            "order_matches": order_matches,
+            "dtype_mismatches": dtype_mismatches,
+            "row_count": len(data),
+        }
+
+        if not valid:
+            raise PredictionSchemaError(
+                "Prediction data failed schema "
+                "validation. "
+                + " ".join(errors)
+            )
+
+        return report
+
+    def validate_and_align(
+        self,
+        data: pd.DataFrame,
+        expected_columns: list[str],
+        expected_dtypes: dict[str, str] | None = None,
+    ) -> pd.DataFrame:
+        """
+        Validate prediction data and return it aligned
+        to the expected feature order.
+
+        Extra columns are removed when they are allowed.
+        """
+
+        self.validate(
+            data=data,
+            expected_columns=expected_columns,
+            expected_dtypes=expected_dtypes,
+        )
+
+        aligned = data.copy()
+
+        aligned = aligned[
+            expected_columns
+        ]
+
+        return aligned
+
+    @staticmethod
+    def infer_schema(
+        data: pd.DataFrame,
+    ) -> dict[str, Any]:
+        """
+        Infer a prediction schema from a DataFrame.
+        """
+
+        if not isinstance(
+            data,
+            pd.DataFrame,
+        ):
+            raise TypeError(
+                "data must be a pandas DataFrame."
+            )
+
+        if data.empty:
+            raise PredictionSchemaError(
+                "Cannot infer schema from "
+                "an empty DataFrame."
+            )
+
+        return {
+            "columns": list(
+                data.columns
+            ),
+            "dtypes": {
+                column: str(
+                    data[column].dtype
+                )
+                for column in data.columns
+            },
+            "n_features": len(
+                data.columns
+            ),
+        }
+
+    @staticmethod
+    def format_error(
+        error: Exception,
+    ) -> str:
+        """
+        Return a clean user-facing error message.
+        """
+
+        if isinstance(
+            error,
+            PredictionSchemaError,
+        ):
+            return str(error)
+
+        return (
+            "Prediction validation failed: "
+            f"{error}"
+        )

modelforge/preprocessing.py

@@ -0,0 +1,179 @@
+from typing import Iterable
+
+import pandas as pd
+from sklearn.compose import ColumnTransformer
+from sklearn.impute import SimpleImputer
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import (
+    OneHotEncoder,
+    StandardScaler,
+)
+
+
+class PreprocessingEngine:
+    """
+    Build leakage-safe preprocessing pipelines for ModelForge.
+
+    All preprocessing operations are placed inside a scikit-learn
+    Pipeline / ColumnTransformer so that transformations are fitted
+    only on training data during cross-validation.
+    """
+
+    SCALE_MODELS = {
+        "knn",
+        "svm",
+        "svr",
+        "linear_regression",
+        "ridge",
+        "lasso",
+        "elasticnet",
+        "logistic_regression",
+        "mlp",
+    }
+
+    def build(
+        self,
+        data: pd.DataFrame,
+        target: str,
+        model_type: str = "tree",
+        excluded_columns: Iterable[str] | None = None,
+    ) -> ColumnTransformer:
+        """
+        Build a preprocessing transformer.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Input dataset.
+
+        target : str
+            Target column.
+
+        model_type : str
+            Model family. Determines whether numerical features
+            should be scaled.
+
+        excluded_columns : Iterable[str] | None
+            Columns to exclude from preprocessing.
+
+        Returns
+        -------
+        ColumnTransformer
+            Leakage-safe preprocessing transformer.
+        """
+
+        if not isinstance(data, pd.DataFrame):
+            raise TypeError("data must be a pandas DataFrame.")
+
+        if data.empty:
+            raise ValueError("Cannot preprocess an empty dataset.")
+
+        if target not in data.columns:
+            raise ValueError(
+                f"Target column '{target}' does not exist."
+            )
+
+        excluded = set(excluded_columns or [])
+
+        feature_data = data.drop(
+            columns=[target],
+            errors="ignore",
+        )
+
+        feature_data = feature_data.drop(
+            columns=[
+                column
+                for column in excluded
+                if column in feature_data.columns
+            ],
+            errors="ignore",
+        )
+
+        numerical_columns = feature_data.select_dtypes(
+            include="number"
+        ).columns.tolist()
+
+        categorical_columns = feature_data.select_dtypes(
+            include=[
+                "object",
+                "category",
+                "bool",
+                "string",
+            ]
+        ).columns.tolist()
+
+        if not numerical_columns and not categorical_columns:
+            raise ValueError(
+                "No supported feature columns were found."
+            )
+
+        scale_numeric = self._should_scale(model_type)
+
+        numeric_steps = [
+            (
+                "imputer",
+                SimpleImputer(strategy="median"),
+            )
+        ]
+
+        if scale_numeric:
+            numeric_steps.append(
+                (
+                    "scaler",
+                    StandardScaler(),
+                )
+            )
+
+        numeric_pipeline = Pipeline(
+            steps=numeric_steps
+        )
+
+        categorical_pipeline = Pipeline(
+            steps=[
+                (
+                    "imputer",
+                    SimpleImputer(
+                        strategy="most_frequent"
+                    ),
+                ),
+                (
+                    "encoder",
+                    OneHotEncoder(
+                        handle_unknown="ignore",
+                        sparse_output=True,
+                    ),
+                ),
+            ]
+        )
+
+        transformers = []
+
+        if numerical_columns:
+            transformers.append(
+                (
+                    "numerical",
+                    numeric_pipeline,
+                    numerical_columns,
+                )
+            )
+
+        if categorical_columns:
+            transformers.append(
+                (
+                    "categorical",
+                    categorical_pipeline,
+                    categorical_columns,
+                )
+            )
+
+        return ColumnTransformer(
+            transformers=transformers,
+            remainder="drop",
+        )
+
+    def _should_scale(self, model_type: str) -> bool:
+        """Determine whether numerical features should be scaled."""
+
+        normalized_model = model_type.lower().strip()
+
+        return normalized_model in self.SCALE_MODELS

modelforge/profiler.py

@@ -0,0 +1,85 @@
+import pandas as pd
+
+
+class DatasetProfiler:
+    """Profile a dataset and generate structural and statistical information."""
+
+    def profile(self, data: pd.DataFrame) -> dict:
+        """
+        Generate a complete dataset profile.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Dataset to analyze.
+
+        Returns
+        -------
+        dict
+            Dataset profiling information.
+
+        Raises
+        ------
+        TypeError
+            If data is not a pandas DataFrame.
+
+        ValueError
+            If the dataset is empty.
+        """
+
+        if not isinstance(data, pd.DataFrame):
+            raise TypeError("data must be a pandas DataFrame.")
+
+        if data.empty:
+            raise ValueError("Cannot profile an empty dataset.")
+
+        column_info = {}
+
+        for column in data.columns:
+            series = data[column]
+
+            column_info[column] = {
+                "dtype": str(series.dtype),
+                "missing_values": int(series.isna().sum()),
+                "missing_percentage": float(
+                    series.isna().mean() * 100
+                ),
+                "unique_values": int(
+                    series.nunique(dropna=True)
+                ),
+                "is_numeric": bool(
+                    pd.api.types.is_numeric_dtype(series)
+                ),
+                "is_categorical": bool(
+                    pd.api.types.is_object_dtype(series)
+                    or pd.api.types.is_string_dtype(series)
+                    or isinstance(
+                        series.dtype,
+                        pd.CategoricalDtype,
+                    )
+                    or pd.api.types.is_bool_dtype(series)
+                ),
+            }
+
+        numeric_columns = data.select_dtypes(
+            include="number"
+        ).columns.tolist()
+
+        categorical_columns = data.select_dtypes(
+            include=["object", "category", "bool", "string"]
+        ).columns.tolist()
+
+        return {
+            "rows": int(data.shape[0]),
+            "columns": int(data.shape[1]),
+            "column_names": data.columns.tolist(),
+            "duplicate_rows": int(
+                data.duplicated().sum()
+            ),
+            "memory_usage_bytes": int(
+                data.memory_usage(deep=True).sum()
+            ),
+            "numeric_columns": numeric_columns,
+            "categorical_columns": categorical_columns,
+            "column_info": column_info,
+        }