mlpipe-cli 0.1.0__tar.gz

mlpipe_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MLPipe Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlpipe_cli-0.1.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: mlpipe-cli
+Version: 0.1.0
+Summary: Production-ready tabular ML automation library and terminal CLI
+Author: MLPipe Contributors
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: joblib>=1.3.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# MLPipe
+
+> **Production-ready tabular ML automation library and terminal CLI.**  
+> From raw CSV to evaluated, reproducible, deployable model pipelines in one command.
+
+---
+
+## 🚀 Overview
+
+**MLPipe** automates the repetitive engineering lifecycle for tabular machine learning models. Simply point MLPipe at your CSV dataset and designate a target column:
+
+```
+Raw CSV Dataset
+      ↓
+Data Ingestion (Format validation & SHA-256 integrity hash)
+      ↓
+Data Profiling (Column types, distributions, missingness & flags)
+      ↓
+Pre-training Validation (Fatal structural errors & non-blocking warnings)
+      ↓
+Task Detection (Automatic classification vs. regression inference)
+      ↓
+Leakage-Free Splitting (Stratified or random train/test split)
+      ↓
+Automated Preprocessing (ColumnTransformer: imputation, scaling & encoding)
+      ↓
+Multi-Model Training & Tuning (RandomizedSearchCV strictly on training folds)
+      ↓
+CV-Based Leaderboard Ranking (Winning model selected by CV, not test set)
+      ↓
+Held-Out Test Evaluation (Unbiased final metrics & confusion matrix)
+      ↓
+Model Explainability (Recovered transformed feature importances & coefficients)
+      ↓
+Artifact Generation (Reusable pipeline, model, metadata & reports)
+      ↓
+Instant Predictions (CLI & Python inference)
+```
+
+No hardcoded results. No fake training. Real scikit-learn models and metrics computed on your CPU machine.
+
+---
+
+## 📦 Installation
+
+Install locally in editable mode:
+
+```bash
+git clone https://github.com/your-org/mlpipe.git
+cd mlpipe
+pip install -e .
+```
+
+Verify the installation:
+
+```bash
+mlpipe --version
+```
+
+---
+
+## ⚡ Quick Start
+
+### 1. Terminal CLI
+
+Train an end-to-end classification pipeline:
+
+```bash
+mlpipe train demo_data/customer_churn.csv --target churn
+```
+
+Train a regression pipeline:
+
+```bash
+mlpipe train demo_data/house_prices.csv --target price
+```
+
+Generate predictions on new data:
+
+```bash
+mlpipe predict ./mlpipe_runs/<run_id>/pipeline.joblib demo_data/customer_churn.csv --output predictions.csv
+```
+
+### 2. Python API
+
+```python
+from mlpipe import Pipeline
+
+# 1. Initialize pipeline
+pipeline = Pipeline(
+    target="churn",
+    task="auto",       # auto-detects classification vs regression
+    mode="balanced",   # "fast", "balanced", or "thorough"
+)
+
+# 2. Fit pipeline on CSV or DataFrame
+result = pipeline.fit("demo_data/customer_churn.csv")
+
+# 3. Inspect results
+print("Best Model:", result.best_model)
+print("Primary Metric:", result.primary_metric)
+print("CV Score:", result.best_cv_score)
+print("Test Score:", result.test_score)
+print("Test Metrics:", result.metrics)
+
+# 4. Save and reload pipeline
+pipeline.save("./trained_models/churn_model")
+
+loaded_pipeline = Pipeline.load("./trained_models/churn_model")
+predictions = loaded_pipeline.predict("demo_data/customer_churn.csv")
+print("Predictions:", predictions[:5])
+```
+
+---
+
+## 🛠️ CLI Command Reference
+
+### `mlpipe train`
+Train multiple candidate models, tune hyperparameters, rank on leaderboard, and save artifacts.
+
+```bash
+mlpipe train <data.csv> --target <target_col> [OPTIONS]
+```
+
+**Options:**
+- `--target, -t`: Target column name to predict (required).
+- `--task`: Task type override: `auto` (default), `classification`, or `regression`.
+- `--mode, -m`: Training mode budget: `fast`, `balanced` (default), or `thorough`.
+- `--output, -o`: Base directory to store run artifacts (default: `./mlpipe_runs`).
+- `--format, -f`: Output format: `human` (default) or `json`.
+- `--verbose`: Enable detailed debug logging.
+
+### `mlpipe profile`
+Inspect dataset summary, column types, statistics, missingness, and structural issues.
+
+```bash
+mlpipe profile demo_data/customer_churn.csv
+mlpipe profile demo_data/customer_churn.csv --format json
+```
+
+### `mlpipe validate`
+Run pre-training validation checks on dataset and target.
+
+```bash
+mlpipe validate demo_data/customer_churn.csv --target churn
+```
+
+### `mlpipe predict`
+Generate predictions on a new CSV dataset using a saved pipeline.
+
+```bash
+mlpipe predict ./mlpipe_runs/<run_id>/pipeline.joblib new_data.csv --output preds.csv
+```
+
+### `mlpipe inspect`
+Inspect metadata, configuration, metrics, and generated artifacts from a previous run directory.
+
+```bash
+mlpipe inspect ./mlpipe_runs/<run_id>
+mlpipe inspect ./mlpipe_runs/<run_id> --format json
+```
+
+### `mlpipe version`
+Display the current version of MLPipe.
+
+```bash
+mlpipe version
+```
+
+---
+
+## 🧠 Supported Models
+
+### Classification
+- **Logistic Regression** (L2 penalty, liblinear/lbfgs/saga solvers)
+- **Random Forest Classifier** (trees, depth, sample split/leaf tuning)
+- **HistGradientBoosting Classifier** (iterations, learning rate, leaf bounds)
+- **Decision Tree Classifier** (depth, split thresholds, criteria)
+- **K-Nearest Neighbors** (neighbors, weights, distance metrics)
+
+### Regression
+- **Ridge Regression** (regularization alpha, solver selection)
+- **Random Forest Regressor** (trees, depth, sample bounds, features)
+- **HistGradientBoosting Regressor** (iterations, rate, regularization)
+- **Decision Tree Regressor** (depth, split criteria, sample leaves)
+
+---
+
+## 🔒 Data Leakage Prevention Guarantee
+
+MLPipe adheres to strict data integrity standards:
+1. **No Full-Data Transformations:** Preprocessing pipelines are never fitted on the entire dataset.
+2. **Train/Test Split First:** The raw dataset is partitioned (default 80% train, 20% test) before column classification and transformer fitting.
+3. **Cross-Validation Inside Pipelines:** During hyperparameter search, sklearn `Pipeline` objects fit transformers solely on the internal training fold of each split.
+4. **CV-Based Model Selection:** The winning model is selected strictly based on CV score on the training set. The held-out test set is evaluated exactly once for unbiased reporting.
+
+---
+
+## 📁 Artifact Structure
+
+Each completed training run generates a self-contained bundle under `./mlpipe_runs/<run_id>/`:
+
+```text
+mlpipe_runs/<run_id>/
+├── pipeline.joblib          # Complete fitted pipeline (preprocessor + estimator)
+├── model.joblib             # Fitted estimator alone
+├── metrics.json             # CV and test evaluation metrics
+├── leaderboard.json         # Complete ranked candidate comparison table
+├── metadata.json            # Dataset hash, seed, mode, environment & parameters
+├── feature_importance.json  # Top features with recovered transformed names
+└── report.txt               # Plain text human-readable run summary
+```
+
+---
+
+## 🧪 Running Tests
+
+Run the complete test suite using `pytest`:
+
+```bash
+pytest
+```
+
+Run with verbose test output:
+
+```bash
+pytest -v
+```
+
+---
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.

mlpipe_cli-0.1.0/README.md

@@ -0,0 +1,234 @@
+# MLPipe
+
+> **Production-ready tabular ML automation library and terminal CLI.**  
+> From raw CSV to evaluated, reproducible, deployable model pipelines in one command.
+
+---
+
+## 🚀 Overview
+
+**MLPipe** automates the repetitive engineering lifecycle for tabular machine learning models. Simply point MLPipe at your CSV dataset and designate a target column:
+
+```
+Raw CSV Dataset
+      ↓
+Data Ingestion (Format validation & SHA-256 integrity hash)
+      ↓
+Data Profiling (Column types, distributions, missingness & flags)
+      ↓
+Pre-training Validation (Fatal structural errors & non-blocking warnings)
+      ↓
+Task Detection (Automatic classification vs. regression inference)
+      ↓
+Leakage-Free Splitting (Stratified or random train/test split)
+      ↓
+Automated Preprocessing (ColumnTransformer: imputation, scaling & encoding)
+      ↓
+Multi-Model Training & Tuning (RandomizedSearchCV strictly on training folds)
+      ↓
+CV-Based Leaderboard Ranking (Winning model selected by CV, not test set)
+      ↓
+Held-Out Test Evaluation (Unbiased final metrics & confusion matrix)
+      ↓
+Model Explainability (Recovered transformed feature importances & coefficients)
+      ↓
+Artifact Generation (Reusable pipeline, model, metadata & reports)
+      ↓
+Instant Predictions (CLI & Python inference)
+```
+
+No hardcoded results. No fake training. Real scikit-learn models and metrics computed on your CPU machine.
+
+---
+
+## 📦 Installation
+
+Install locally in editable mode:
+
+```bash
+git clone https://github.com/your-org/mlpipe.git
+cd mlpipe
+pip install -e .
+```
+
+Verify the installation:
+
+```bash
+mlpipe --version
+```
+
+---
+
+## ⚡ Quick Start
+
+### 1. Terminal CLI
+
+Train an end-to-end classification pipeline:
+
+```bash
+mlpipe train demo_data/customer_churn.csv --target churn
+```
+
+Train a regression pipeline:
+
+```bash
+mlpipe train demo_data/house_prices.csv --target price
+```
+
+Generate predictions on new data:
+
+```bash
+mlpipe predict ./mlpipe_runs/<run_id>/pipeline.joblib demo_data/customer_churn.csv --output predictions.csv
+```
+
+### 2. Python API
+
+```python
+from mlpipe import Pipeline
+
+# 1. Initialize pipeline
+pipeline = Pipeline(
+    target="churn",
+    task="auto",       # auto-detects classification vs regression
+    mode="balanced",   # "fast", "balanced", or "thorough"
+)
+
+# 2. Fit pipeline on CSV or DataFrame
+result = pipeline.fit("demo_data/customer_churn.csv")
+
+# 3. Inspect results
+print("Best Model:", result.best_model)
+print("Primary Metric:", result.primary_metric)
+print("CV Score:", result.best_cv_score)
+print("Test Score:", result.test_score)
+print("Test Metrics:", result.metrics)
+
+# 4. Save and reload pipeline
+pipeline.save("./trained_models/churn_model")
+
+loaded_pipeline = Pipeline.load("./trained_models/churn_model")
+predictions = loaded_pipeline.predict("demo_data/customer_churn.csv")
+print("Predictions:", predictions[:5])
+```
+
+---
+
+## 🛠️ CLI Command Reference
+
+### `mlpipe train`
+Train multiple candidate models, tune hyperparameters, rank on leaderboard, and save artifacts.
+
+```bash
+mlpipe train <data.csv> --target <target_col> [OPTIONS]
+```
+
+**Options:**
+- `--target, -t`: Target column name to predict (required).
+- `--task`: Task type override: `auto` (default), `classification`, or `regression`.
+- `--mode, -m`: Training mode budget: `fast`, `balanced` (default), or `thorough`.
+- `--output, -o`: Base directory to store run artifacts (default: `./mlpipe_runs`).
+- `--format, -f`: Output format: `human` (default) or `json`.
+- `--verbose`: Enable detailed debug logging.
+
+### `mlpipe profile`
+Inspect dataset summary, column types, statistics, missingness, and structural issues.
+
+```bash
+mlpipe profile demo_data/customer_churn.csv
+mlpipe profile demo_data/customer_churn.csv --format json
+```
+
+### `mlpipe validate`
+Run pre-training validation checks on dataset and target.
+
+```bash
+mlpipe validate demo_data/customer_churn.csv --target churn
+```
+
+### `mlpipe predict`
+Generate predictions on a new CSV dataset using a saved pipeline.
+
+```bash
+mlpipe predict ./mlpipe_runs/<run_id>/pipeline.joblib new_data.csv --output preds.csv
+```
+
+### `mlpipe inspect`
+Inspect metadata, configuration, metrics, and generated artifacts from a previous run directory.
+
+```bash
+mlpipe inspect ./mlpipe_runs/<run_id>
+mlpipe inspect ./mlpipe_runs/<run_id> --format json
+```
+
+### `mlpipe version`
+Display the current version of MLPipe.
+
+```bash
+mlpipe version
+```
+
+---
+
+## 🧠 Supported Models
+
+### Classification
+- **Logistic Regression** (L2 penalty, liblinear/lbfgs/saga solvers)
+- **Random Forest Classifier** (trees, depth, sample split/leaf tuning)
+- **HistGradientBoosting Classifier** (iterations, learning rate, leaf bounds)
+- **Decision Tree Classifier** (depth, split thresholds, criteria)
+- **K-Nearest Neighbors** (neighbors, weights, distance metrics)
+
+### Regression
+- **Ridge Regression** (regularization alpha, solver selection)
+- **Random Forest Regressor** (trees, depth, sample bounds, features)
+- **HistGradientBoosting Regressor** (iterations, rate, regularization)
+- **Decision Tree Regressor** (depth, split criteria, sample leaves)
+
+---
+
+## 🔒 Data Leakage Prevention Guarantee
+
+MLPipe adheres to strict data integrity standards:
+1. **No Full-Data Transformations:** Preprocessing pipelines are never fitted on the entire dataset.
+2. **Train/Test Split First:** The raw dataset is partitioned (default 80% train, 20% test) before column classification and transformer fitting.
+3. **Cross-Validation Inside Pipelines:** During hyperparameter search, sklearn `Pipeline` objects fit transformers solely on the internal training fold of each split.
+4. **CV-Based Model Selection:** The winning model is selected strictly based on CV score on the training set. The held-out test set is evaluated exactly once for unbiased reporting.
+
+---
+
+## 📁 Artifact Structure
+
+Each completed training run generates a self-contained bundle under `./mlpipe_runs/<run_id>/`:
+
+```text
+mlpipe_runs/<run_id>/
+├── pipeline.joblib          # Complete fitted pipeline (preprocessor + estimator)
+├── model.joblib             # Fitted estimator alone
+├── metrics.json             # CV and test evaluation metrics
+├── leaderboard.json         # Complete ranked candidate comparison table
+├── metadata.json            # Dataset hash, seed, mode, environment & parameters
+├── feature_importance.json  # Top features with recovered transformed names
+└── report.txt               # Plain text human-readable run summary
+```
+
+---
+
+## 🧪 Running Tests
+
+Run the complete test suite using `pytest`:
+
+```bash
+pytest
+```
+
+Run with verbose test output:
+
+```bash
+pytest -v
+```
+
+---
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.

mlpipe_cli-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mlpipe-cli"
+version = "0.1.0"
+description = "Production-ready tabular ML automation library and terminal CLI"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "MLPipe Contributors" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pandas>=2.0.0",
+    "numpy>=1.24.0",
+    "scikit-learn>=1.3.0",
+    "joblib>=1.3.0",
+    "scipy>=1.10.0",
+    "typer[all]>=0.9.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+mlpipe = "mlpipe.cli.main:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]

mlpipe_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mlpipe_cli-0.1.0/src/mlpipe/__init__.py

@@ -0,0 +1,43 @@
+"""
+MLPipe: Automated Machine Learning Library and Terminal CLI.
+"""
+
+from mlpipe.core.config import PipelineConfig, TaskType, TrainingMode
+from mlpipe.core.exceptions import (
+    ArtifactError,
+    ConfigurationError,
+    DatasetError,
+    EvaluationError,
+    MLPipeError,
+    PipelineError,
+    PredictionError,
+    PreprocessingError,
+    TrainingError,
+    ValidationError,
+)
+from mlpipe.core.pipeline import Pipeline
+from mlpipe.core.result import PipelineResult
+from mlpipe.data.profiling import DatasetProfile
+from mlpipe.data.validation import ValidationReport
+from mlpipe.version import __version__
+
+__all__ = [
+    "Pipeline",
+    "PipelineResult",
+    "DatasetProfile",
+    "ValidationReport",
+    "PipelineConfig",
+    "TaskType",
+    "TrainingMode",
+    "MLPipeError",
+    "DatasetError",
+    "ValidationError",
+    "PreprocessingError",
+    "TrainingError",
+    "EvaluationError",
+    "ArtifactError",
+    "ConfigurationError",
+    "PredictionError",
+    "PipelineError",
+    "__version__",
+]

mlpipe_cli-0.1.0/src/mlpipe/__main__.py

@@ -0,0 +1,6 @@
+"""CLI entrypoint when running python -m mlpipe."""
+
+from mlpipe.cli.main import app
+
+if __name__ == "__main__":
+    app()

mlpipe_cli-0.1.0/src/mlpipe/artifacts/__init__.py

@@ -0,0 +1,23 @@
+"""Artifact management and serialization for MLPipe."""
+
+from mlpipe.artifacts.manager import (
+    ArtifactManager,
+    inspect_run_directory,
+    load_pipeline_artifact,
+)
+from mlpipe.artifacts.serialization import (
+    load_joblib,
+    load_json,
+    save_joblib,
+    save_json,
+)
+
+__all__ = [
+    "ArtifactManager",
+    "inspect_run_directory",
+    "load_pipeline_artifact",
+    "load_joblib",
+    "load_json",
+    "save_joblib",
+    "save_json",
+]