MLFOX

Source code: 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

python -m pip install mlfox

For a local checkout before the PyPI release:

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:

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. The package itself is callable, so use import mlfox followed by mlfox(...).

Quick start

Start with the defaults:

import mlfox

model = mlfox()
model.fit("customers.csv", target="Churn")
model.report()

You can also set the task and CV options yourself:

import mlfox

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

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

Classification example

import pandas as pd
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

import pandas as pd
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:

Full candidate details and failures are included in the HTML report.

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
import mlfox

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

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

model.report() prints only the concise benchmark table, best model, holdout metrics, and vprojectx footer. It returns no dictionary, so notebook frontends show only this summary. For the full styled HTML report, use model.html(); it writes a self-contained report with dataset, preprocessing, model comparison, holdout, explainability, and runtime sections:

model.html()  # writes mlfox_report.html
model.export_report("training_report.html")
model.export_report("training_report.json")

Save and reload a fitted pipeline:

import mlfox

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

loaded = mlfox.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:

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:

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/. See CHANGELOG.md for release notes. For local development:

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.