autoforge-engine 0.1.2__tar.gz → 0.1.3__tar.gz

autoforge_engine-0.1.3/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: autoforge-engine
+Version: 0.1.3
+Summary: A transparent, local-first AutoML framework for automated ML pipeline discovery.
+Author: Aditya Kumar Singh
+Author-email: Aditya Kumar Singh <adityasingh45245@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Adityasinghrajput01/ModelForge
+Project-URL: Repository, https://github.com/Adityasinghrajput01/ModelForge
+Project-URL: Issues, https://github.com/Adityasinghrajput01/ModelForge/issues
+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
+
+> **Transparent, local-first AutoML experimentation for reproducible and inspectable machine learning.**
+
+ModelForge is a Python AutoML library for preparing data, screening and ranking
+scikit-learn pipelines, evaluating models, and saving models for later
+predictions. Training runs also record experiment and reproducibility
+information locally.
+
+A typical ModelForge workflow profiles a dataset, selects a target, audits and
+preprocesses its features, generates candidate pipelines, screens and ranks
+models, and saves the chosen pipeline for prediction. The workflow stays
+inspectable rather than hiding every stage behind a black-box call.
+
+The package is published as **`autoforge-engine`** and imported in Python as
+**`modelforge`**.
+
+## Features
+
+- Regression and classification workflows
+- Data profiling, column intelligence, and data-quality auditing
+- Preprocessing, feature engineering, and feature selection
+- Model screening, cross-validation, and ranking
+- Saved model pipelines and predictions from the command line or Python
+- Local experiment tracking, run metadata, and reproducibility information
+- Optional boosting models and hyperparameter optimization
+
+## Requirements
+
+- Python 3.11 or newer
+- A local dataset in a supported format
+
+The default installation includes NumPy, pandas, scikit-learn, Rich, Typer,
+and PyYAML.
+
+## Install
+
+### Install from PyPI
+
+Windows PowerShell:
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install autoforge-engine
+```
+
+If PowerShell does not allow virtual-environment activation, you can call its
+Python executable directly:
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip
+.\.venv\Scripts\python.exe -m pip install autoforge-engine
+```
+
+Linux or macOS:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install autoforge-engine
+```
+
+Optional integrations can be installed with extras:
+
+```bash
+python -m pip install "autoforge-engine[boosting,optimization]"
+```
+
+The `boosting` extra installs XGBoost, LightGBM, and CatBoost. The
+`optimization` extra installs Optuna.
+
+### Install from source
+
+Clone the repository, enter its directory, and install the development extras.
+This makes the `modelforge` command and test tools available in the active
+Python environment.
+
+```bash
+git clone https://github.com/Adityasinghrajput01/ModelForge.git
+cd ModelForge
+python -m venv .venv
+```
+
+Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+Linux or macOS:
+
+```bash
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+To install optional integrations from a source checkout, use
+`python -m pip install -e ".[dev,boosting,optimization]"`.
+
+## Dataset and file paths
+
+ModelForge reads local files. Training through the Python API supports CSV,
+Excel (`.xlsx` or `.xls`), Parquet, and JSON files. The CLI prediction command
+expects a CSV file.
+
+The training data must have a header row. Choose the column you want the model
+to predict as the **target**; all other usable columns become input features.
+For example, a regression CSV might look like this:
+
+```csv
+area,bedrooms,age,price
+1200,2,15,250000
+1850,3,8,385000
+900,1,30,190000
+```
+
+Here, `price` is the target. A prediction CSV should contain the feature
+columns (`area`, `bedrooms`, and `age`) with compatible names, but should not
+contain the target column.
+
+Paths are interpreted from the directory where you run the command or Python
+script:
+
+- A **relative path** such as `data/train.csv` starts from the current working
+	directory. Run commands from the repository root when using paths such as
+	`examples/house_prices.csv`.
+- An **absolute path** works from any directory. On Windows, quote paths that
+	contain spaces, for example `"C:\Users\Aditya Kumar\Datasets\train.csv"`.
+- In Python, use a raw string for a Windows path, such as
+	`r"C:\Users\Aditya Kumar\Datasets\train.csv"`, or use forward slashes:
+	`"C:/Users/Aditya Kumar/Datasets/train.csv"`.
+
+## Train and predict with the CLI
+
+After installation, check that the command is available:
+
+```bash
+modelforge --help
+```
+
+From the repository root, train a regression model using the included housing
+dataset. The target column is `price`:
+
+```bash
+modelforge train \
+	--data "examples/house_prices.csv" \
+	--target price \
+	--task-type regression \
+	--output "house_prices_model.joblib"
+```
+
+Run the saved model on new rows. The example prediction file contains features
+without the `price` target:
+
+```bash
+modelforge predict \
+	--model "house_prices_model.joblib" \
+	--data "examples/house_prices_new.csv" \
+	--output "predictions.csv"
+```
+
+On Windows PowerShell, the same commands can be written on one line, or use a
+backtick at the end of each continued line. For a dataset outside the
+repository, supply its absolute path to `--data`.
+
+For classification, use a classification dataset, provide its label column,
+and set `--task-type classification`. For example, the included Iris dataset
+uses `species` as its label:
+
+```bash
+modelforge train --data "examples/iris_classification.csv" --target species --task-type classification --output "iris_model.joblib"
+```
+
+To return class probabilities instead of predicted class labels, add
+`--proba` to `modelforge predict`. This option is only for classification
+models.
+
+Useful CLI commands:
+
+```bash
+modelforge train --help
+modelforge predict --help
+modelforge models --task-type classification
+modelforge experiments list --directory .modelforge/experiments
+modelforge experiments get EXPERIMENT_ID
+modelforge experiments compare ID_ONE ID_TWO
+```
+
+By default, experiment records are written to `.modelforge/experiments` in
+the current working directory. The model is saved to the path passed to
+`--output` (default: `model.joblib`). Use `--overwrite` to replace an existing
+model file.
+
+## Use ModelForge from Python
+
+For a one-call workflow that prints a dataset, model-ranking, data-quality,
+and run report, use the lowercase `automl` helper. It accepts a file path or a
+pandas DataFrame and returns the fitted `AutoML` instance:
+
+```python
+from modelforge import automl
+
+run = automl("data/heart_failure.csv", "DEATH_EVENT")
+predictions = run.predict("data/new_patients.csv")
+```
+
+Pass options such as `task_type="classification"`, `cv=5`, or
+`model_names=["logistic_regression"]` as keyword arguments when needed.
+
+Pass a pandas DataFrame to `AutoML.fit`, name the target column, then save the
+fitted pipeline. Replace the example path with the path to your own dataset.
+
+```python
+from pathlib import Path
+
+import pandas as pd
+from modelforge import AutoML
+
+data_path = Path("examples/house_prices.csv")
+data = pd.read_csv(data_path)
+
+automl = AutoML(cv=5, random_state=42)
+result = automl.fit(
+		data,
+		target="price",
+		task_type="regression",
+)
+
+model_path = Path("house_prices_model.joblib")
+automl.save(str(model_path), overwrite=True)
+print("Best model:", result["best_model"])
+
+new_data = pd.read_csv("examples/house_prices_new.csv")
+predictions = automl.predict(new_data)
+print(predictions.head())
+```
+
+For a file path outside the working directory, set `data_path` to an absolute
+path, for example `Path(r"C:\Users\Aditya Kumar\Datasets\train.csv")`.
+
+## Configuration
+
+You can put training settings in a YAML file and pass it to the CLI with
+`--config`. For example:
+
+```yaml
+target: price
+task_type: regression
+objective: balanced
+test_size: 0.2
+cv: 5
+random_state: 42
+experiment_directory: .modelforge/experiments
+```
+
+Save this as `modelforge.yaml`, then run:
+
+```bash
+modelforge train --data "examples/house_prices.csv" --config "modelforge.yaml" --output "house_prices_model.joblib"
+```
+
+The CLI options `--target`, `--task-type`, `--objective`, `--cv`, and
+`--test-size` can also be set directly on the command line. See
+`examples/modelforge_config.yaml` for a configuration that includes feature
+selection settings.
+
+## Run tests and checks
+
+Install the source checkout with the `dev` extra first, then run these from
+the repository root with the virtual environment activated:
+
+```bash
+python -m pytest -q
+ruff check .
+```
+
+To run a single test module while developing:
+
+```bash
+python -m pytest tests/test_cli_workflow.py -q
+```
+
+To exercise the included Python workflows and benchmark:
+
+```bash
+python examples/end_to_end_regression.py
+python benchmarks/benchmark_baselines.py
+```
+
+To verify a classification train-and-predict workflow with the included Iris
+files:
+
+```bash
+modelforge train --data "examples/iris_classification.csv" --target species --task-type classification --output "iris_model.joblib"
+modelforge predict --model "iris_model.joblib" --data "examples/iris_new.csv" --output "iris_predictions.csv"
+```
+
+To check the installed CLI and the available model names:
+
+```bash
+modelforge --help
+modelforge models --task-type regression
+modelforge models --task-type classification
+```
+
+## Project contents
+
+- `examples/` contains sample datasets, YAML configuration, and end-to-end
+	workflows.
+- `tests/` contains the automated test suite.
+- `benchmarks/` contains a baseline comparison script.
+- `docs/ROADMAP.md` describes planned project work.
+
+## License
+
+ModelForge is distributed under the MIT License. See [LICENSE](LICENSE).

autoforge_engine-0.1.3/README.md

@@ -0,0 +1,323 @@
+# ModelForge
+
+> **Transparent, local-first AutoML experimentation for reproducible and inspectable machine learning.**
+
+ModelForge is a Python AutoML library for preparing data, screening and ranking
+scikit-learn pipelines, evaluating models, and saving models for later
+predictions. Training runs also record experiment and reproducibility
+information locally.
+
+A typical ModelForge workflow profiles a dataset, selects a target, audits and
+preprocesses its features, generates candidate pipelines, screens and ranks
+models, and saves the chosen pipeline for prediction. The workflow stays
+inspectable rather than hiding every stage behind a black-box call.
+
+The package is published as **`autoforge-engine`** and imported in Python as
+**`modelforge`**.
+
+## Features
+
+- Regression and classification workflows
+- Data profiling, column intelligence, and data-quality auditing
+- Preprocessing, feature engineering, and feature selection
+- Model screening, cross-validation, and ranking
+- Saved model pipelines and predictions from the command line or Python
+- Local experiment tracking, run metadata, and reproducibility information
+- Optional boosting models and hyperparameter optimization
+
+## Requirements
+
+- Python 3.11 or newer
+- A local dataset in a supported format
+
+The default installation includes NumPy, pandas, scikit-learn, Rich, Typer,
+and PyYAML.
+
+## Install
+
+### Install from PyPI
+
+Windows PowerShell:
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install autoforge-engine
+```
+
+If PowerShell does not allow virtual-environment activation, you can call its
+Python executable directly:
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip
+.\.venv\Scripts\python.exe -m pip install autoforge-engine
+```
+
+Linux or macOS:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install autoforge-engine
+```
+
+Optional integrations can be installed with extras:
+
+```bash
+python -m pip install "autoforge-engine[boosting,optimization]"
+```
+
+The `boosting` extra installs XGBoost, LightGBM, and CatBoost. The
+`optimization` extra installs Optuna.
+
+### Install from source
+
+Clone the repository, enter its directory, and install the development extras.
+This makes the `modelforge` command and test tools available in the active
+Python environment.
+
+```bash
+git clone https://github.com/Adityasinghrajput01/ModelForge.git
+cd ModelForge
+python -m venv .venv
+```
+
+Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+Linux or macOS:
+
+```bash
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+To install optional integrations from a source checkout, use
+`python -m pip install -e ".[dev,boosting,optimization]"`.
+
+## Dataset and file paths
+
+ModelForge reads local files. Training through the Python API supports CSV,
+Excel (`.xlsx` or `.xls`), Parquet, and JSON files. The CLI prediction command
+expects a CSV file.
+
+The training data must have a header row. Choose the column you want the model
+to predict as the **target**; all other usable columns become input features.
+For example, a regression CSV might look like this:
+
+```csv
+area,bedrooms,age,price
+1200,2,15,250000
+1850,3,8,385000
+900,1,30,190000
+```
+
+Here, `price` is the target. A prediction CSV should contain the feature
+columns (`area`, `bedrooms`, and `age`) with compatible names, but should not
+contain the target column.
+
+Paths are interpreted from the directory where you run the command or Python
+script:
+
+- A **relative path** such as `data/train.csv` starts from the current working
+	directory. Run commands from the repository root when using paths such as
+	`examples/house_prices.csv`.
+- An **absolute path** works from any directory. On Windows, quote paths that
+	contain spaces, for example `"C:\Users\Aditya Kumar\Datasets\train.csv"`.
+- In Python, use a raw string for a Windows path, such as
+	`r"C:\Users\Aditya Kumar\Datasets\train.csv"`, or use forward slashes:
+	`"C:/Users/Aditya Kumar/Datasets/train.csv"`.
+
+## Train and predict with the CLI
+
+After installation, check that the command is available:
+
+```bash
+modelforge --help
+```
+
+From the repository root, train a regression model using the included housing
+dataset. The target column is `price`:
+
+```bash
+modelforge train \
+	--data "examples/house_prices.csv" \
+	--target price \
+	--task-type regression \
+	--output "house_prices_model.joblib"
+```
+
+Run the saved model on new rows. The example prediction file contains features
+without the `price` target:
+
+```bash
+modelforge predict \
+	--model "house_prices_model.joblib" \
+	--data "examples/house_prices_new.csv" \
+	--output "predictions.csv"
+```
+
+On Windows PowerShell, the same commands can be written on one line, or use a
+backtick at the end of each continued line. For a dataset outside the
+repository, supply its absolute path to `--data`.
+
+For classification, use a classification dataset, provide its label column,
+and set `--task-type classification`. For example, the included Iris dataset
+uses `species` as its label:
+
+```bash
+modelforge train --data "examples/iris_classification.csv" --target species --task-type classification --output "iris_model.joblib"
+```
+
+To return class probabilities instead of predicted class labels, add
+`--proba` to `modelforge predict`. This option is only for classification
+models.
+
+Useful CLI commands:
+
+```bash
+modelforge train --help
+modelforge predict --help
+modelforge models --task-type classification
+modelforge experiments list --directory .modelforge/experiments
+modelforge experiments get EXPERIMENT_ID
+modelforge experiments compare ID_ONE ID_TWO
+```
+
+By default, experiment records are written to `.modelforge/experiments` in
+the current working directory. The model is saved to the path passed to
+`--output` (default: `model.joblib`). Use `--overwrite` to replace an existing
+model file.
+
+## Use ModelForge from Python
+
+For a one-call workflow that prints a dataset, model-ranking, data-quality,
+and run report, use the lowercase `automl` helper. It accepts a file path or a
+pandas DataFrame and returns the fitted `AutoML` instance:
+
+```python
+from modelforge import automl
+
+run = automl("data/heart_failure.csv", "DEATH_EVENT")
+predictions = run.predict("data/new_patients.csv")
+```
+
+Pass options such as `task_type="classification"`, `cv=5`, or
+`model_names=["logistic_regression"]` as keyword arguments when needed.
+
+Pass a pandas DataFrame to `AutoML.fit`, name the target column, then save the
+fitted pipeline. Replace the example path with the path to your own dataset.
+
+```python
+from pathlib import Path
+
+import pandas as pd
+from modelforge import AutoML
+
+data_path = Path("examples/house_prices.csv")
+data = pd.read_csv(data_path)
+
+automl = AutoML(cv=5, random_state=42)
+result = automl.fit(
+		data,
+		target="price",
+		task_type="regression",
+)
+
+model_path = Path("house_prices_model.joblib")
+automl.save(str(model_path), overwrite=True)
+print("Best model:", result["best_model"])
+
+new_data = pd.read_csv("examples/house_prices_new.csv")
+predictions = automl.predict(new_data)
+print(predictions.head())
+```
+
+For a file path outside the working directory, set `data_path` to an absolute
+path, for example `Path(r"C:\Users\Aditya Kumar\Datasets\train.csv")`.
+
+## Configuration
+
+You can put training settings in a YAML file and pass it to the CLI with
+`--config`. For example:
+
+```yaml
+target: price
+task_type: regression
+objective: balanced
+test_size: 0.2
+cv: 5
+random_state: 42
+experiment_directory: .modelforge/experiments
+```
+
+Save this as `modelforge.yaml`, then run:
+
+```bash
+modelforge train --data "examples/house_prices.csv" --config "modelforge.yaml" --output "house_prices_model.joblib"
+```
+
+The CLI options `--target`, `--task-type`, `--objective`, `--cv`, and
+`--test-size` can also be set directly on the command line. See
+`examples/modelforge_config.yaml` for a configuration that includes feature
+selection settings.
+
+## Run tests and checks
+
+Install the source checkout with the `dev` extra first, then run these from
+the repository root with the virtual environment activated:
+
+```bash
+python -m pytest -q
+ruff check .
+```
+
+To run a single test module while developing:
+
+```bash
+python -m pytest tests/test_cli_workflow.py -q
+```
+
+To exercise the included Python workflows and benchmark:
+
+```bash
+python examples/end_to_end_regression.py
+python benchmarks/benchmark_baselines.py
+```
+
+To verify a classification train-and-predict workflow with the included Iris
+files:
+
+```bash
+modelforge train --data "examples/iris_classification.csv" --target species --task-type classification --output "iris_model.joblib"
+modelforge predict --model "iris_model.joblib" --data "examples/iris_new.csv" --output "iris_predictions.csv"
+```
+
+To check the installed CLI and the available model names:
+
+```bash
+modelforge --help
+modelforge models --task-type regression
+modelforge models --task-type classification
+```
+
+## Project contents
+
+- `examples/` contains sample datasets, YAML configuration, and end-to-end
+	workflows.
+- `tests/` contains the automated test suite.
+- `benchmarks/` contains a baseline comparison script.
+- `docs/ROADMAP.md` describes planned project work.
+
+## License
+
+ModelForge is distributed under the MIT License. See [LICENSE](LICENSE).