autoforge-engine 0.1.0__py3-none-any.whl

modelforge/persistence.py

@@ -0,0 +1,456 @@
+from pathlib import Path
+from typing import Any
+
+import joblib
+import pandas as pd
+
+from sklearn.pipeline import Pipeline
+
+from modelforge.prediction_validator import (
+    PredictionSchemaError,
+    PredictionSchemaValidator,
+)
+
+
+class ModelPersistence:
+    """
+    Save, load, validate, and use trained ModelForge pipelines.
+
+    ModelForge persists the complete sklearn pipeline so that
+    preprocessing and model transformations remain identical
+    during future prediction.
+
+    Prediction schema validation is delegated to the dedicated
+    PredictionSchemaValidator component.
+    """
+
+    MODEL_FILENAME = "model.joblib"
+    METADATA_FILENAME = "metadata.joblib"
+
+    def save(
+        self,
+        pipeline: Pipeline,
+        path: str,
+        metadata: dict[str, Any] | None = None,
+        overwrite: bool = False,
+    ) -> str:
+        """
+        Save a trained pipeline to disk.
+
+        Parameters
+        ----------
+        pipeline:
+            Fitted sklearn Pipeline.
+
+        path:
+            Destination file path.
+
+        metadata:
+            Optional metadata associated with the model.
+
+        overwrite:
+            Whether an existing file may be replaced.
+
+        Returns
+        -------
+        str
+            Absolute path of the saved model.
+        """
+
+        self._validate_pipeline(
+            pipeline
+        )
+
+        destination = Path(path)
+
+        if (
+            destination.exists()
+            and not overwrite
+        ):
+            raise FileExistsError(
+                f"Model already exists: {destination}. "
+                "Set overwrite=True to replace it."
+            )
+
+        destination.parent.mkdir(
+            parents=True,
+            exist_ok=True,
+        )
+
+        joblib.dump(
+            pipeline,
+            destination,
+        )
+
+        if metadata is not None:
+            metadata_path = self._metadata_path(
+                destination
+            )
+
+            joblib.dump(
+                metadata,
+                metadata_path,
+            )
+
+        return str(
+            destination.resolve()
+        )
+
+    def load(
+        self,
+        path: str,
+    ) -> Pipeline:
+        """
+        Load a saved ModelForge pipeline.
+        """
+
+        model_path = Path(path)
+
+        if not model_path.exists():
+            raise FileNotFoundError(
+                f"Model not found: {model_path}"
+            )
+
+        if not model_path.is_file():
+            raise ValueError(
+                f"Model path is not a file: "
+                f"{model_path}"
+            )
+
+        pipeline = joblib.load(
+            model_path
+        )
+
+        self._validate_pipeline(
+            pipeline
+        )
+
+        return pipeline
+
+    def load_metadata(
+        self,
+        path: str,
+    ) -> dict[str, Any]:
+        """
+        Load metadata associated with a saved model.
+        """
+
+        model_path = Path(path)
+
+        if not model_path.exists():
+            raise FileNotFoundError(
+                f"Model not found: {model_path}"
+            )
+
+        metadata_path = self._metadata_path(
+            model_path
+        )
+
+        if not metadata_path.exists():
+            return {}
+
+        metadata = joblib.load(
+            metadata_path
+        )
+
+        if not isinstance(
+            metadata,
+            dict,
+        ):
+            raise ValueError(
+                "Saved metadata must be a dictionary."
+            )
+
+        return metadata
+
+    def predict(
+        self,
+        pipeline: Pipeline,
+        data: pd.DataFrame,
+    ) -> pd.Series:
+        """
+        Generate predictions using a fitted pipeline.
+
+        Prediction data is validated and aligned using
+        PredictionSchemaValidator before inference.
+        """
+
+        self._validate_pipeline(
+            pipeline
+        )
+
+        validated_data = (
+            self._validate_prediction_data(
+                pipeline,
+                data,
+            )
+        )
+
+        predictions = pipeline.predict(
+            validated_data
+        )
+
+        return pd.Series(
+            predictions,
+            index=validated_data.index,
+            name="prediction",
+        )
+
+    def predict_from_file(
+        self,
+        pipeline: Pipeline,
+        data_path: str,
+    ) -> pd.Series:
+        """
+        Load a CSV dataset and generate predictions.
+        """
+
+        path = Path(data_path)
+
+        if not path.exists():
+            raise FileNotFoundError(
+                f"Prediction dataset not found: {path}"
+            )
+
+        if not path.is_file():
+            raise ValueError(
+                f"Prediction dataset is not a file: "
+                f"{path}"
+            )
+
+        if path.suffix.lower() != ".csv":
+            raise ValueError(
+                "predict_from_file currently "
+                "supports CSV files only."
+            )
+
+        data = pd.read_csv(
+            path
+        )
+
+        return self.predict(
+            pipeline,
+            data,
+        )
+
+    @staticmethod
+    def predict_proba(
+        pipeline: Pipeline,
+        data: pd.DataFrame,
+    ) -> pd.DataFrame:
+        """
+        Generate class probabilities when supported.
+
+        Prediction data is validated and aligned using
+        PredictionSchemaValidator before inference.
+        """
+
+        if not isinstance(
+            pipeline,
+            Pipeline,
+        ):
+            raise TypeError(
+                "pipeline must be a sklearn Pipeline."
+            )
+
+        if not hasattr(
+            pipeline,
+            "predict_proba",
+        ):
+            raise ValueError(
+                "This pipeline does not support "
+                "probability predictions."
+            )
+
+        validated_data = (
+            ModelPersistence._validate_prediction_data(
+                pipeline,
+                data,
+            )
+        )
+
+        probabilities = (
+            pipeline.predict_proba(
+                validated_data
+            )
+        )
+
+        model = pipeline.named_steps.get(
+            "model"
+        )
+
+        if (
+            model is not None
+            and hasattr(
+                model,
+                "classes_",
+            )
+        ):
+            columns = [
+                f"probability_{label}"
+                for label in model.classes_
+            ]
+        else:
+            columns = [
+                f"probability_{index}"
+                for index in range(
+                    probabilities.shape[1]
+                )
+            ]
+
+        return pd.DataFrame(
+            probabilities,
+            index=validated_data.index,
+            columns=columns,
+        )
+
+    @staticmethod
+    def predict_proba_from_file(
+        pipeline: Pipeline,
+        data_path: str,
+    ) -> pd.DataFrame:
+        """
+        Load a CSV dataset and generate class probabilities.
+        """
+
+        path = Path(data_path)
+
+        if not path.exists():
+            raise FileNotFoundError(
+                f"Prediction dataset not found: {path}"
+            )
+
+        if not path.is_file():
+            raise ValueError(
+                f"Prediction dataset is not a file: "
+                f"{path}"
+            )
+
+        if path.suffix.lower() != ".csv":
+            raise ValueError(
+                "predict_proba_from_file currently "
+                "supports CSV files only."
+            )
+
+        data = pd.read_csv(
+            path
+        )
+
+        return ModelPersistence.predict_proba(
+            pipeline,
+            data,
+        )
+
+    @staticmethod
+    def _validate_prediction_data(
+        pipeline: Pipeline,
+        data: pd.DataFrame,
+    ) -> pd.DataFrame:
+        """
+        Validate prediction data through the dedicated
+        PredictionSchemaValidator.
+
+        The fitted sklearn pipeline provides the expected
+        training feature schema.
+        """
+
+        if not isinstance(
+            data,
+            pd.DataFrame,
+        ):
+            raise TypeError(
+                "data must be a pandas DataFrame."
+            )
+
+        if data.empty:
+            raise ValueError(
+                "Cannot predict on an empty dataset."
+            )
+
+        expected_columns = (
+            ModelPersistence._get_expected_columns(
+                pipeline
+            )
+        )
+
+        if expected_columns is None:
+            return data
+
+        validator = (
+            PredictionSchemaValidator(
+                allow_extra_columns=False,
+                enforce_column_order=False,
+                enforce_dtypes=False,
+            )
+        )
+
+        try:
+            return validator.validate_and_align(
+                data=data,
+                expected_columns=expected_columns,
+            )
+
+        except PredictionSchemaError as exc:
+            raise ValueError(
+                str(exc)
+            ) from exc
+
+    @staticmethod
+    def _get_expected_columns(
+        pipeline: Pipeline,
+    ) -> list[str] | None:
+        """
+        Extract the feature schema recorded by sklearn.
+
+        sklearn pipelines fitted with a pandas DataFrame
+        expose feature names through feature_names_in_.
+        """
+
+        feature_names = getattr(
+            pipeline,
+            "feature_names_in_",
+            None,
+        )
+
+        if feature_names is None:
+            return None
+
+        return [
+            str(column)
+            for column in feature_names
+        ]
+
+    @staticmethod
+    def _metadata_path(
+        model_path: Path,
+    ) -> Path:
+        """
+        Generate the metadata path corresponding
+        to a model file.
+        """
+
+        return model_path.with_name(
+            f"{model_path.stem}_metadata.joblib"
+        )
+
+    @staticmethod
+    def _validate_pipeline(
+        pipeline: Pipeline,
+    ) -> None:
+        """
+        Validate that the supplied object is a
+        usable sklearn Pipeline.
+        """
+
+        if not isinstance(
+            pipeline,
+            Pipeline,
+        ):
+            raise TypeError(
+                "pipeline must be a sklearn Pipeline."
+            )
+
+        if "model" not in pipeline.named_steps:
+            raise ValueError(
+                "Pipeline must contain a 'model' step."
+            )

modelforge/pipeline_generator.py

@@ -0,0 +1,278 @@
+from typing import Any
+
+import pandas as pd
+
+from sklearn.pipeline import Pipeline
+
+from modelforge.feature_selection import (
+    CorrelationFeatureSelector,
+    VarianceFeatureSelector,
+)
+from modelforge.model_registry import (
+    ModelRegistry,
+)
+from modelforge.preprocessing import (
+    PreprocessingEngine,
+)
+
+
+class PipelineGenerator:
+    """
+    Generate complete machine-learning pipelines
+    for ModelForge.
+
+    The generated pipeline connects:
+
+        preprocessing
+            ↓
+        feature selection
+            ↓
+        model
+    """
+
+    def __init__(
+        self,
+        model_registry: ModelRegistry | None = None,
+        preprocessing_engine: PreprocessingEngine | None = None,
+    ):
+        self.model_registry = (
+            model_registry
+            if model_registry is not None
+            else ModelRegistry()
+        )
+
+        self.preprocessing_engine = (
+            preprocessing_engine
+            if preprocessing_engine is not None
+            else PreprocessingEngine()
+        )
+
+    def build(
+        self,
+        data: pd.DataFrame,
+        target: str,
+        model_name: str,
+        task_type: str,
+        excluded_columns: list[str] | None = None,
+        variance_threshold: float | None = None,
+        correlation_threshold: float | None = None,
+        model_params: dict[str, Any] | None = None,
+    ) -> Pipeline:
+        """
+        Build a complete ModelForge pipeline.
+
+        Parameters
+        ----------
+        data : pd.DataFrame
+            Input dataset.
+
+        target : str
+            Target column.
+
+        model_name : str
+            Registered model identifier.
+
+        task_type : str
+            'regression' or 'classification'.
+
+        excluded_columns : list[str] | None
+            Columns that should not be used as features.
+
+        variance_threshold : float | None
+            Optional variance filtering threshold.
+
+        correlation_threshold : float | None
+            Optional correlation filtering threshold.
+
+        model_params : dict | None
+            Parameters overriding model defaults.
+
+        Returns
+        -------
+        sklearn.pipeline.Pipeline
+            Complete ML pipeline.
+        """
+
+        self._validate_inputs(
+            data=data,
+            target=target,
+            task_type=task_type,
+        )
+
+        model_spec = self.model_registry.get(
+            model_name
+        )
+
+        if model_spec.task_type != task_type:
+            raise ValueError(
+                f"Model '{model_name}' is a "
+                f"{model_spec.task_type} model and "
+                f"cannot be used for {task_type}."
+            )
+
+        excluded = list(
+            excluded_columns or []
+        )
+
+        preprocessing = (
+            self.preprocessing_engine.build(
+                data=data,
+                target=target,
+                model_type=self._get_model_type(
+                    model_spec
+                ),
+                excluded_columns=excluded,
+            )
+        )
+
+        # Feature-selection transformers in ModelForge
+        # explicitly require pandas DataFrames.
+        #
+        # ColumnTransformer normally produces a NumPy array.
+        # When feature selection is enabled, configure the
+        # preprocessing transformer to return pandas output.
+        if (
+            variance_threshold is not None
+            or correlation_threshold is not None
+        ):
+            if not hasattr(
+                preprocessing,
+                "set_output",
+            ):
+                raise RuntimeError(
+                    "The preprocessing transformer does not "
+                    "support pandas output. A compatible "
+                    "scikit-learn version is required."
+                )
+
+            preprocessing.set_output(
+                transform="pandas"
+            )
+
+        steps = []
+
+        steps.append(
+            (
+                "preprocessing",
+                preprocessing,
+            )
+        )
+
+        if variance_threshold is not None:
+            steps.append(
+                (
+                    "variance_selection",
+                    VarianceFeatureSelector(
+                        threshold=variance_threshold
+                    ),
+                )
+            )
+
+        if correlation_threshold is not None:
+            steps.append(
+                (
+                    "correlation_selection",
+                    CorrelationFeatureSelector(
+                        threshold=correlation_threshold
+                    ),
+                )
+            )
+
+        model = self.model_registry.create(
+            model_name,
+            **(model_params or {}),
+        )
+
+        steps.append(
+            (
+                "model",
+                model,
+            )
+        )
+
+        return Pipeline(
+            steps=steps
+        )
+
+    @staticmethod
+    def _validate_inputs(
+        data: pd.DataFrame,
+        target: str,
+        task_type: str,
+    ) -> None:
+        """
+        Validate pipeline construction inputs.
+        """
+
+        if not isinstance(
+            data,
+            pd.DataFrame,
+        ):
+            raise TypeError(
+                "data must be a pandas DataFrame."
+            )
+
+        if data.empty:
+            raise ValueError(
+                "Cannot build a pipeline from "
+                "an empty dataset."
+            )
+
+        if target not in data.columns:
+            raise ValueError(
+                f"Target column '{target}' "
+                "does not exist."
+            )
+
+        if task_type not in {
+            "regression",
+            "classification",
+        }:
+            raise ValueError(
+                "task_type must be 'regression' "
+                "or 'classification'."
+            )
+
+    @staticmethod
+    def _get_model_type(
+        model_spec,
+    ) -> str:
+        """
+        Convert model metadata into a preprocessing
+        model category.
+        """
+
+        if model_spec.requires_scaling:
+            if model_spec.category == "svm":
+                return "svm"
+
+            if model_spec.category == "distance_based":
+                return "knn"
+
+            if model_spec.category == "linear":
+                if (
+                    "classification"
+                    == model_spec.task_type
+                ):
+                    return "logistic_regression"
+
+                if model_spec.name.lower().startswith(
+                    "ridge"
+                ):
+                    return "ridge"
+
+                if model_spec.name.lower().startswith(
+                    "lasso"
+                ):
+                    return "lasso"
+
+                if model_spec.name.lower().startswith(
+                    "elastic"
+                ):
+                    return "elasticnet"
+
+                return "linear_regression"
+
+            return "mlp"
+
+        return "tree"