autoforge-engine 0.1.0__py3-none-any.whl

autoforge_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: autoforge-engine
+Version: 0.1.0
+Summary: A transparent, local-first AutoML framework for automated ML pipeline discovery.
+Author: Aditya Kumar Singh
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: boosting
+Requires-Dist: xgboost>=2.0; extra == "boosting"
+Requires-Dist: lightgbm>=4.0; extra == "boosting"
+Requires-Dist: catboost>=1.2; extra == "boosting"
+Provides-Extra: optimization
+Requires-Dist: optuna>=3.6; extra == "optimization"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+ # ModelForge
+
+ModelForge is a transparent, local-first AutoML framework for discovering,
+evaluating, explaining, and persisting scikit-learn pipelines. It keeps the
+workflow inspectable: data audits, preprocessing, model screening,
+cross-validation, ranking, reproducibility metadata, and artifacts are all
+available as Python objects and local files.
+
+## Quick start
+
+```bash
+python -m pip install -e ".[dev]"
+modelforge train --data examples/house_prices.csv --target price \
+	--task-type regression --output model.joblib
+modelforge predict --model model.joblib --data examples/house_prices_new.csv
+```
+
+The same workflow is available from Python:
+
+```python
+from modelforge import AutoML
+
+automl = AutoML(cv=5, random_state=42)
+result = automl.fit(data, target="price", task_type="regression")
+automl.save("artifacts/house-prices.joblib", overwrite=True)
+print(result["best_model"])
+```
+
+## What is included
+
+ModelForge currently provides ingestion, target detection, profiling, column
+intelligence, data-quality and leakage auditing, preprocessing, feature
+engineering and selection, a model registry, screening, cross-validation,
+ranking, explainability, persistence, prediction validation, optimization,
+experiment tracking, run management, configuration, CLI workflows, failure
+isolation, robustness checks, and reproducibility snapshots.
+
+Optional model and optimization integrations are declared in `pyproject.toml`:
+
+```bash
+python -m pip install -e ".[boosting,optimization]"
+```
+
+## CLI
+
+```bash
+modelforge --help
+modelforge models --task-type classification
+modelforge experiments list --directory .modelforge/experiments
+modelforge experiments get EXPERIMENT_ID
+modelforge experiments compare ID_ONE ID_TWO
+```
+
+The CLI uses Rich tables and keeps generated models, experiment JSON, and
+metadata local by default.
+
+## Examples and benchmarks
+
+- `examples/end_to_end_regression.py` demonstrates a complete Python workflow.
+- `examples/end_to_end_classification.py` demonstrates classification and
+	probability prediction.
+- `benchmarks/benchmark_baselines.py` compares ModelForge with simple baseline
+	estimators and records runtime and quality metrics.
+
+Run an example with `python examples/end_to_end_regression.py` or run the
+benchmark with `python benchmarks/benchmark_baselines.py`.
+
+## Development
+
+```bash
+.venv\\Scripts\\python.exe -m pytest -q
+ruff check .
+```
+
+GitHub Actions runs the test suite on supported Python versions. The roadmap
+for the remaining product work lives in `docs/ROADMAP.md`; it separates
+implemented foundations from integrations that require optional dependencies
+or additional design work.

autoforge_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+autoforge_engine-0.1.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modelforge/artifact_manager.py,sha256=ZzINwGTiyy6aNf1hVW0lxodcseTbDLaRx8CDhmQPfsc,10310
+modelforge/automl.py,sha256=TfAkoeK0VT8aHjxADDzx9D1n_G2IPkRP2QrfBvaYs7E,39010
+modelforge/cli.py,sha256=gDUbnBYZe5MAjVR4dYUyF7Fn4lCshNLt7me2yJIKBHs,28438
+modelforge/column_intelligence.py,sha256=6GbmXcPJtAGnM8Glg7i0CIOq6W0GXr6K3q8rSe8L68M,11648
+modelforge/config.py,sha256=aJvEAFQ-gWkXb0EO7Z1sStmjQCcMlzrxOxL5CX15YGI,13415
+modelforge/cross_validation.py,sha256=8EJzWTWKIH2pvZqzm3Hj2hdvX-5Mf7jCcWa3j02lxYs,18983
+modelforge/data_audit.py,sha256=1_ea_72B9_NtFY1kcogLPIpQdR3RSrCuZI69yiLmEFk,10681
+modelforge/data_loader.py,sha256=sTvkBKiCAc7GE-5z_h-TmpC30ggGa8GTdfIlmRsXkbI,1705
+modelforge/evaluation.py,sha256=1GTUE07KHn9xift1vR0AKFkX8AF-7z8j68ZcC-JDcWw,9516
+modelforge/experiment_tracker.py,sha256=g21CueH21G0ZOJ8oYuq9rCspZf63WUl5y_0Kyf6K-L4,11861
+modelforge/explainability.py,sha256=zKldBF-WTqjbTU7M_8l1EHqUfyipYoXkGHQm5_eGPGc,8299
+modelforge/feature_engineering.py,sha256=u91tSOcnZY1_dE5syn0Nfo8BacrgC4ES1GD7gY_u8zI,10056
+modelforge/feature_selection.py,sha256=P5LsQutsKcdwee8g_4CXUx4UoegvjoEPO8TNiR5KMW8,13667
+modelforge/hyperparameter_optimization.py,sha256=ZTV_4PI9pKHSOOmgH5QUdHzw6O64yddQntcu7p_55aE,14403
+modelforge/model_registry.py,sha256=8wuqNR2DegYsWwXG_QsO9Fv6_CwfvqhFu1tH1gkZv_c,19532
+modelforge/model_screening.py,sha256=On3GmIZrjcOW747V74S-RNtolX6djWaj-olcxvHYGQ4,13020
+modelforge/persistence.py,sha256=yOeShK8kqrS-cLa4NHnYEQaP7baTzagYhI6tF1eMCjw,10221
+modelforge/pipeline_generator.py,sha256=esWVlN4ZSOp9Vgg7tkvefdIdMidyh9tEDFBfHQfFKrs,6910
+modelforge/prediction_validator.py,sha256=xMOH-oU4HpJ_P1f0yz_ONxsxL_azr0vW0fMHEnfwAUM,7539
+modelforge/preprocessing.py,sha256=fpOYsBNgPgJiZ_O2WvICyvS9b3OIEq2lIRhNOTC3uUI,4490
+modelforge/profiler.py,sha256=DOIHWcrDKvIoA8roS1qJO3U1sjWtjydbx8SuZHsiAhY,2486
+modelforge/ranking.py,sha256=pqcKv4rhyiTcsKp8wQ65nqDAZbXq78bIsTS1B0yg2po,7991
+modelforge/reproducibility.py,sha256=yz_ammbZb57ASE3zAmpxgwJ9ZHnyok2mUBR9L9jFgYU,8020
+modelforge/reproducibility_integration.py,sha256=Lm5Zck6OphqTQQA3n1nvW_2xk6AkQMRnfAnEPnoDklc,4738
+modelforge/run_manager.py,sha256=SkvPzUmJIEuABSNAz8ddlGPNRwQ4GIMrPAg7E9mOc9o,4568
+modelforge/target_selector.py,sha256=eq9zeNL7A5iq0uRdI5GNKtqB1wdH1s0lAZdDZzKpXlc,3182
+autoforge_engine-0.1.0.dist-info/METADATA,sha256=lRtEINfeV7EQzee93g4Gc26D4oCxjDaySvytqE-807g,3534
+autoforge_engine-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+autoforge_engine-0.1.0.dist-info/entry_points.txt,sha256=X6ugP0SKpNhhpiWDbNpY_XYrAsOjR1yPl-JUQEepct4,50
+autoforge_engine-0.1.0.dist-info/top_level.txt,sha256=ZyKkWfjMHbQ1mlQyLT2xZlbeT0M1jOjB4nRWVR_YiI8,11
+autoforge_engine-0.1.0.dist-info/RECORD,,

autoforge_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

autoforge_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+modelforge = modelforge.cli:app

autoforge_engine-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+modelforge

modelforge/artifact_manager.py

@@ -0,0 +1,485 @@
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import joblib
+
+
+class ArtifactManager:
+    """
+    Manage persisted ModelForge model artifacts and metadata.
+
+    Each artifact consists of:
+        <artifact_id>.pkl
+        <artifact_id>.json
+
+    The JSON file stores metadata describing the trained model.
+    """
+
+    def __init__(
+        self,
+        directory: str | Path = ".modelforge/artifacts",
+    ):
+        self.directory = Path(directory)
+
+        self.directory.mkdir(
+            parents=True,
+            exist_ok=True,
+        )
+
+    def create_artifact_id(
+        self,
+    ) -> str:
+        """
+        Generate a unique artifact identifier.
+        """
+
+        timestamp = datetime.now(
+            timezone.utc
+        ).strftime("%Y%m%d%H%M%S")
+
+        short_uuid = uuid.uuid4().hex[:8]
+
+        return f"artifact_{timestamp}_{short_uuid}"
+
+    def save(
+        self,
+        pipeline: Any,
+        metadata: dict[str, Any] | None = None,
+        artifact_id: str | None = None,
+        overwrite: bool = False,
+    ) -> str:
+        """
+        Save a trained pipeline and its metadata.
+
+        Returns:
+            Artifact ID.
+        """
+
+        if pipeline is None:
+            raise ValueError(
+                "pipeline cannot be None."
+            )
+
+        if metadata is not None:
+            if not isinstance(
+                metadata,
+                dict,
+            ):
+                raise TypeError(
+                    "metadata must be a dictionary."
+                )
+
+        artifact_id = (
+            artifact_id
+            or self.create_artifact_id()
+        )
+
+        self._validate_artifact_id(
+            artifact_id
+        )
+
+        model_path = self.model_path(
+            artifact_id
+        )
+
+        metadata_path = self.metadata_path(
+            artifact_id
+        )
+
+        if not overwrite:
+            if model_path.exists():
+                raise FileExistsError(
+                    f"Artifact '{artifact_id}' "
+                    "already exists."
+                )
+
+            if metadata_path.exists():
+                raise FileExistsError(
+                    f"Metadata for artifact "
+                    f"'{artifact_id}' already exists."
+                )
+
+        artifact_metadata = {
+            "artifact_id": artifact_id,
+            "created_at": datetime.now(
+                timezone.utc
+            ).isoformat(),
+            "artifact_type": "model_pipeline",
+            "metadata": self._safe_value(
+                metadata or {}
+            ),
+        }
+
+        joblib.dump(
+            pipeline,
+            model_path,
+        )
+
+        self._write_json(
+            metadata_path,
+            artifact_metadata,
+        )
+
+        return artifact_id
+
+    def load(
+        self,
+        artifact_id: str,
+    ) -> Any:
+        """
+        Load a saved model pipeline.
+        """
+
+        self._validate_artifact_id(
+            artifact_id
+        )
+
+        path = self.model_path(
+            artifact_id
+        )
+
+        if not path.exists():
+            raise FileNotFoundError(
+                f"Artifact '{artifact_id}' "
+                "does not exist."
+            )
+
+        return joblib.load(path)
+
+    def get_metadata(
+        self,
+        artifact_id: str,
+    ) -> dict[str, Any]:
+        """
+        Load artifact metadata.
+        """
+
+        self._validate_artifact_id(
+            artifact_id
+        )
+
+        path = self.metadata_path(
+            artifact_id
+        )
+
+        if not path.exists():
+            raise FileNotFoundError(
+                f"Metadata for artifact "
+                f"'{artifact_id}' does not exist."
+            )
+
+        with path.open(
+            "r",
+            encoding="utf-8",
+        ) as file:
+            return json.load(file)
+
+    def exists(
+        self,
+        artifact_id: str,
+    ) -> bool:
+        """
+        Check whether an artifact exists.
+        """
+
+        self._validate_artifact_id(
+            artifact_id
+        )
+
+        return self.model_path(
+            artifact_id
+        ).exists()
+
+    def delete(
+        self,
+        artifact_id: str,
+    ) -> None:
+        """
+        Delete an artifact and its metadata.
+        """
+
+        self._validate_artifact_id(
+            artifact_id
+        )
+
+        model_path = self.model_path(
+            artifact_id
+        )
+
+        metadata_path = self.metadata_path(
+            artifact_id
+        )
+
+        if not model_path.exists():
+            raise FileNotFoundError(
+                f"Artifact '{artifact_id}' "
+                "does not exist."
+            )
+
+        model_path.unlink()
+
+        if metadata_path.exists():
+            metadata_path.unlink()
+
+    def list_artifacts(
+        self,
+    ) -> list[dict[str, Any]]:
+        """
+        Return metadata for all saved artifacts.
+
+        Results are ordered newest first.
+        """
+
+        artifacts = []
+
+        for path in self.directory.glob(
+            "artifact_*.json"
+        ):
+            try:
+                with path.open(
+                    "r",
+                    encoding="utf-8",
+                ) as file:
+                    metadata = json.load(file)
+
+                artifact_id = metadata.get(
+                    "artifact_id"
+                )
+
+                if not artifact_id:
+                    continue
+
+                artifacts.append(
+                    metadata
+                )
+
+            except (
+                OSError,
+                json.JSONDecodeError,
+            ):
+                continue
+
+        artifacts.sort(
+            key=lambda item: item.get(
+                "created_at",
+                "",
+            ),
+            reverse=True,
+        )
+
+        return artifacts
+
+    def count(
+        self,
+    ) -> int:
+        """
+        Return the number of saved artifacts.
+        """
+
+        return len(
+            list(
+                self.directory.glob(
+                    "artifact_*.pkl"
+                )
+            )
+        )
+
+    def model_path(
+        self,
+        artifact_id: str,
+    ) -> Path:
+        """
+        Return the model path for an artifact.
+        """
+
+        self._validate_artifact_id(
+            artifact_id
+        )
+
+        return (
+            self.directory
+            / f"{artifact_id}.pkl"
+        )
+
+    def metadata_path(
+        self,
+        artifact_id: str,
+    ) -> Path:
+        """
+        Return the metadata path for an artifact.
+        """
+
+        self._validate_artifact_id(
+            artifact_id
+        )
+
+        return (
+            self.directory
+            / f"{artifact_id}.json"
+        )
+
+    def validate(
+        self,
+        artifact_id: str,
+    ) -> dict[str, Any]:
+        """
+        Validate that an artifact has both model
+        and metadata files.
+
+        Returns a validation report.
+        """
+
+        self._validate_artifact_id(
+            artifact_id
+        )
+
+        model_path = self.model_path(
+            artifact_id
+        )
+
+        metadata_path = self.metadata_path(
+            artifact_id
+        )
+
+        model_exists = model_path.exists()
+        metadata_exists = metadata_path.exists()
+
+        metadata_valid = False
+        metadata = None
+
+        if metadata_exists:
+            try:
+                metadata = self.get_metadata(
+                    artifact_id
+                )
+
+                metadata_valid = (
+                    isinstance(
+                        metadata,
+                        dict,
+                    )
+                    and metadata.get(
+                        "artifact_id"
+                    )
+                    == artifact_id
+                )
+
+            except (
+                OSError,
+                json.JSONDecodeError,
+            ):
+                metadata_valid = False
+
+        valid = (
+            model_exists
+            and metadata_exists
+            and metadata_valid
+        )
+
+        return {
+            "artifact_id": artifact_id,
+            "valid": valid,
+            "model_exists": model_exists,
+            "metadata_exists": metadata_exists,
+            "metadata_valid": metadata_valid,
+        }
+
+    @staticmethod
+    def _write_json(
+        path: Path,
+        data: dict[str, Any],
+    ) -> None:
+        with path.open(
+            "w",
+            encoding="utf-8",
+        ) as file:
+            json.dump(
+                data,
+                file,
+                indent=2,
+                ensure_ascii=False,
+            )
+
+    @staticmethod
+    def _validate_artifact_id(
+        artifact_id: str,
+    ) -> None:
+        if not isinstance(
+            artifact_id,
+            str,
+        ):
+            raise TypeError(
+                "artifact_id must be a string."
+            )
+
+        if not artifact_id:
+            raise ValueError(
+                "artifact_id cannot be empty."
+            )
+
+        if Path(artifact_id).name != artifact_id:
+            raise ValueError(
+                "Invalid artifact_id."
+            )
+
+        if not artifact_id.startswith(
+            "artifact_"
+        ):
+            raise ValueError(
+                "Invalid artifact_id."
+            )
+
+    @staticmethod
+    def _safe_value(
+        value: Any,
+    ) -> Any:
+        if value is None:
+            return None
+
+        if isinstance(
+            value,
+            (str, int, float, bool),
+        ):
+            return value
+
+        if isinstance(
+            value,
+            Path,
+        ):
+            return str(value)
+
+        if isinstance(
+            value,
+            dict,
+        ):
+            return {
+                str(key): ArtifactManager._safe_value(
+                    item
+                )
+                for key, item in value.items()
+            }
+
+        if isinstance(
+            value,
+            (list, tuple, set),
+        ):
+            return [
+                ArtifactManager._safe_value(
+                    item
+                )
+                for item in value
+            ]
+
+        try:
+            json.dumps(value)
+            return value
+        except (
+            TypeError,
+            ValueError,
+        ):
+            return str(value)