Metadata-Version: 2.4
Name: mlfox
Version: 1.0.1
Summary: CPU-only MLFOX model selection, evaluation, explainability, and inference toolkit
Author: vprojectx
License-Expression: MIT
Project-URL: Homepage, https://github.com/viraj-salunke/Vprojectx
Project-URL: Repository, https://github.com/viraj-salunke/Vprojectx
Project-URL: Issues, https://github.com/viraj-salunke/Vprojectx/issues
Project-URL: Changelog, https://github.com/viraj-salunke/Vprojectx/blob/main/CHANGELOG.md
Keywords: machine-learning,automl,tabular,scikit-learn,xgboost,classification,regression
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: joblib>=1.3
Requires-Dist: xgboost-cpu<3.2,>=3.1.3; sys_platform == "win32" or sys_platform == "linux"
Requires-Dist: xgboost<3.2,>=3.1.3; sys_platform == "darwin"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: rich
Requires-Dist: rich>=13; extra == "rich"
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == "excel"
Requires-Dist: xlrd>=2.0; extra == "excel"
Dynamic: license-file

# MLFOX

[![PyPI version](https://img.shields.io/pypi/v/mlfox)](https://pypi.org/project/mlfox/)
[![Python versions](https://img.shields.io/pypi/pyversions/mlfox)](https://pypi.org/project/mlfox/)
[![CI](https://github.com/viraj-salunke/Vprojectx/actions/workflows/ci.yml/badge.svg)](https://github.com/viraj-salunke/Vprojectx/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Source code: [github.com/viraj-salunke/Vprojectx](https://github.com/viraj-salunke/Vprojectx)

By **vprojectx**.

MLFOX is a CPU-based Python library for training tabular classification and regression models. Give it a CSV file or pandas DataFrame; it profiles the data, builds fold-aware preprocessing, compares eligible models, evaluates the selected pipeline on a holdout set, and produces a report.

## Install

```bash
python -m pip install mlfox
```

For a local checkout before the PyPI release:

```bash
python -m pip install -e .
```

XGBoost is installed as a required dependency: Windows/Linux use `xgboost-cpu`; macOS uses `xgboost` with CPU execution. Optional extras are available for terminal formatting, Excel files, and development tests:

```bash
python -m pip install "mlfox[rich]"   # Rich progress and report formatting
python -m pip install "mlfox[excel]"  # .xlsx/.xls input support
python -m pip install "mlfox[test]"   # pytest
```

MLFOX requires Python 3.11 or later. The current CI configuration exercises Python 3.11–3.13. Install the `mlfox` distribution and use `from mlfox import mlfox`. `MLFOX` is also exported as a class-name alias for code that prefers capitalization.

## Quick start

```python
from mlfox import mlfox

model = mlfox(task="auto", cv=5, random_state=42)
model.fit("customers.csv", target="Churn")

report = model.report()
print("Selected model:", report["best_estimator"])
print("Holdout metrics:", report["holdout_metrics"])
```

The target column is the value to predict. MLFOX accepts CSV, Excel (`.xlsx`/`.xls`) files, or a pandas DataFrame.

## Classification example

```python
import pandas as pd
from mlfox import mlfox

data = pd.read_csv("customers.csv")
model = mlfox(task="binary_classification", cv=5, random_state=42)
model.fit(data, target="Churn")

predictions = model.predict(data.drop(columns="Churn"))
print(predictions.head())

# Probability output is available when the selected classifier supports it.
probabilities = model.predict_proba(data.drop(columns="Churn"))
print(probabilities.head())
```

For three or more target classes, set `task="multiclass_classification"` when you know the target type. `task="auto"` detects common binary and multiclass targets, including repeated integer-coded labels with modest cardinality. Numeric target detection is heuristic; use an explicit task when integer values represent a continuous or discrete-valued regression target.

## Regression example

```python
import pandas as pd
from mlfox import mlfox

data = pd.read_csv("sales.csv")
model = mlfox(task="regression", metric="rmse", cv=5, random_state=42)
model.fit(data, target="Sales")

predictions = model.predict(data.drop(columns="Sales"))
print(predictions.head())
```

## What `fit()` does

1. Loads and validates the input, profiles columns, and detects or checks the task.
2. Splits the data into training and holdout partitions.
3. Benchmarks eligible candidate models with cross-validation on the training partition.
4. Fits preprocessing separately inside each CV fold: column decisions, imputation, feature engineering, encoding/scaling, and feature selection are learned only from that fold’s training rows.
5. Selects the best candidate using the primary CV metric, refits its pipeline on the training partition, then evaluates once on the untouched holdout partition.

The holdout metrics are for final evaluation only; they are not used to select the model. Classification uses stratified CV and defaults to balanced accuracy for selection. Regression uses K-fold CV and defaults to RMSE. Set `cv`, `metric`, `test_size`, and `random_state` in `mlfox(...)` to configure the run.

## Models

Default classification candidates:

- Logistic Regression
- Decision Tree
- Random Forest
- Extra Trees
- XGBoost
- HistGradientBoosting when eligible
- Calibrated SVM within configured size limits

Default regression candidates:

- Linear Regression
- Ridge
- ElasticNet
- Decision Tree Regressor
- Random Forest Regressor
- Extra Trees Regressor
- XGBoost Regressor
- HistGradientBoosting Regressor when eligible

MLFOX runs sequentially on CPU. Some candidates are skipped for size or dimensionality limits. Candidate failures include the exception and fold in the structured model-selection report:

```python
report = model.report(display=False)
print(report["model_selection"]["failed_models"])
```

Each eligible candidate is evaluated across CV folds, so training can take several minutes. In these benchmark runs, 48k Adult rows took about 2.2 minutes, 54k Diamonds rows about 3.3 minutes, and full Covertype (581k rows) about 18 minutes. Timing depends on hardware and dataset features.

## Benchmarks

Results below are from the repository's [benchmark runner](https://github.com/viraj-salunke/Vprojectx/blob/main/test2.py). It uses an external holdout; fit time is the time spent in `model.fit()`. Runs used default five-fold CV and three seeds except full Covertype, which used one.

| Dataset | Rows | Accuracy | Macro F1 | R² | RMSE | Mean fit time |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| Adult | 48,842 | 0.8732 | 0.8149 | — | — | 132.6 s |
| Credit-g | 1,000 | 0.7667 | 0.6995 | — | — | 8.5 s |
| Covertype (full) | 581,012 | 0.9582 | 0.9309 | — | — | 1,079.2 s |
| California Housing | 20,640 | — | — | 0.8291 | 0.4751 | 62.0 s |
| Diamonds | 53,940 | — | — | 0.9762 | 612.62 | 195.8 s |

These are example runs, not guarantees; hardware, dependency versions, random splits, and dataset characteristics affect results. Credit-g varied more across seeds than the other classification runs.

## Metrics

Classification reports accuracy, balanced accuracy, weighted precision, weighted recall, weighted F1, and ROC-AUC when supported. Available primary metrics are `balanced_accuracy`, `accuracy`, `precision`, `recall`, `f1`, and `roc_auc`.

Regression reports R², MAE, and RMSE. Available primary metrics are `rmse`, `mae`, and `r2`.

## Bounded tuning

Tuning is optional and bounded; it is not an unbounded search:

```python
from mlfox import mlfox

model = mlfox(
    task="binary_classification",
    tune=True,
    max_tuning_trials=8,
    cv=3,
    random_state=42,
)
model.fit("customers.csv", target="Churn")
print(model.report()["best_hyperparameters"])
```

Use an explicit task value of `binary_classification`, `multiclass_classification`, or `regression` when configuring manually. The default `task="auto"` asks MLFOX to infer the task.

## Reports, saving, and loading

`report()` prints a terminal summary and returns structured report data. Call `report(display=False)` to get the data without printing. HTML and JSON exports are supported:

```python
model.export_report("training_report.html")
model.export_report("training_report.json")
```

Save and reload a fitted pipeline:

```python
from mlfox import load_model, mlfox

model = mlfox().fit("training.csv", target="target")
model.save("model.joblib")

loaded = load_model("model.joblib")
predictions = loaded.predict("new_rows.csv")
```

`fit()` returns the same model object, so chaining is supported. `predict()` returns a one-dimensional pandas Series named `prediction`, with shape `(n_rows,)` and the input index preserved. Example:

```text
0    yes
1     no
Name: prediction, dtype: object
```

`predict_proba()` returns a DataFrame with shape `(n_rows, n_classes)` when the selected classifier supports probabilities.

**Security:** Joblib uses pickle-based deserialization and can execute code embedded in an artifact. Load only model files from sources you trust.

## Explainability

Global permutation importance and single-row perturbation explanations are available:

```python
importance = model.feature_importance(
    data="labeled_evaluation.csv", target="target", n_repeats=10
)
explanation = model.explain_prediction(
    data="one_customer.csv", background_data="reference_rows.csv"
)
```

These describe model sensitivity, not causal effects. The current implementation does not provide SHAP explanations.

## Limitations

- MLFOX targets tabular data. It does not automatically vectorize free-form text.
- Automatic task detection treats integer-valued numeric targets as multiclass when there are at least 3 distinct labels, at least 2 rows per label, and no more labels than `min(100, max(20, int(2 * sqrt(n_valid_targets))))`. Continuous or higher-cardinality numeric targets are treated as regression. This is heuristic; explicitly configure ambiguous tasks.
- Splitting is random/stratified. Time-aware and group-aware holdout/CV strategies are not currently supported.
- Duplicate rows are reported but not automatically removed. Outliers are not automatically clipped or removed.
- High-cardinality categorical features can expand memory during one-hot encoding.
- No GPU training or parallel model benchmarking is provided.
- Windows/Linux install `xgboost-cpu`; macOS installs `xgboost`, which MLFOX configures for CPU execution.

## Examples and development

Runnable examples are in [`examples/`](examples/). See [CHANGELOG.md](CHANGELOG.md) for release notes. For local development:

```bash
python -m pip install -e ".[test,rich,excel]"
python -m compileall -q mlfox tests
python -m pytest -vv
python -m mlfox.test
```

The package is released under the MIT License; see [LICENSE](LICENSE).
