breezeml 0.3.0

BreezeML — Production-grade machine learning with zero boilerplate, built on scikit-learn.

BreezeML

Machine learning without the boilerplate.

Train, evaluate, compare, and save models in a few lines.

Getting Started · API Reference · Examples · Contributing · Changelog

---

Overview

BreezeML is a high-level machine learning library built on top of scikit-learn, designed to remove boilerplate while keeping the underlying workflow statistically sound. It handles preprocessing, train/test splits, model comparison, tuning, evaluation, and persistence behind a compact API that stays readable for both beginners and working practitioners.

from breezeml import datasets, fit, predict

df = datasets.iris()
model = fit(df, "species")
preds = predict(model, df.drop(columns=["species"]))

That is the core idea: fewer moving parts, fewer repetitive preprocessing steps, and sensible defaults.

---

Key Features

Feature	Description
Auto task detection	Automatically selects classification or regression based on the target column
12 classifiers	From Logistic Regression to Neural Nets, available in one function call
10 regressors (v0.3.0)	From Linear Regression to Gradient Boosting and MLP, available in one function call
Classifier leaderboard	classifiers.compare() ranks all built-in classifiers by accuracy and F1
Regressor leaderboard (v0.3.0)	regressors.compare() ranks all built-in regressors by R2, MAE, and RMSE
Cross-validation support (v0.3.0)	Most classifier and regressor training helpers now accept cv= and return mean/std metrics
Feature engineering toolkit (v0.3.0)	breezeml.features adds selection, importance, PCA, and polynomial expansion helpers
Optional boosting backends (v0.3.0)	XGBoost and LightGBM plug into the compare and tuning flows when installed
Hyperparameter tuning	quick_tune() wrappers run RandomizedSearchCV with curated parameter grids
Detailed reports	Classification and regression helpers expose richer diagnostics in one call
Built-in datasets	Iris, Wine, Breast Cancer, Diabetes, California Housing, and Penguins are available immediately
Model persistence	save() / load() use joblib under the hood
Text embeddings (v0.2.9)	breezeml.text.embed() converts raw text columns to dense semantic vectors
Explainability (v0.2.9)	breezeml.explain gives SHAP-based feature importance plots
Plotting helpers (v0.2.9)	breezeml.plot includes confusion matrix and ROC curve helpers
Strict validation (v0.2.8)	Public APIs validate dataframes and target columns up front

---

Architecture

breezeml/
|-- breezeml.py        # Core API: fit, predict, auto, from_csv, save, load
|-- classifiers.py     # 12 classifiers + compare, detailed_report, quick_tune
|-- regressors.py      # 10 regressors + compare, detailed_report, quick_tune
|-- clustering.py      # kmeans, agglomerative, dbscan
|-- features.py        # feature selection, importances, PCA, polynomial expansion
|-- text.py            # semantic text embeddings
|-- explain.py         # SHAP explainability
|-- plot.py            # plotting helpers
`-- __init__.py        # public API surface

Internal pipeline

Raw DataFrame
    |
    v
ColumnTransformer
  |- Numeric     -> Median imputer + scaler
  `- Categorical -> Mode imputer + one-hot encoder
    |
    v
sklearn estimator
    |
    v
EasyModel wrapper

---

Installation

Stable release

pip install breezeml

Latest from source

git clone https://github.com/venomez-viper/breezeml.git
cd breezeml
pip install -e .

Requirements: Python >= 3.8, scikit-learn, pandas, numpy, joblib

Optional extras:

pip install "breezeml[nlp]"
pip install "breezeml[explain]"
pip install "breezeml[plot]"
pip install "breezeml[boost]"
pip install "breezeml[datasets]"
pip install "breezeml[all]"

---

Quickstart

Classification in 3 lines

from breezeml import datasets, fit, predict

df = datasets.iris()
model = fit(df, "species")
print(predict(model, df.drop(columns=["species"]))[:5])

Auto mode for regression

from breezeml import auto, datasets

df = datasets.diabetes()
model, report = auto(df, "target")
print(report)

Dedicated regression workflow (new in v0.3.0)

from breezeml import datasets, regressors

df = datasets.diabetes()
model, report = regressors.gradient_boosting(df, "target")
print(report)

Cross-validation in one line (new in v0.3.0)

from breezeml import classifiers, datasets

df = datasets.iris()
model, report = classifiers.logistic(df, "species", cv=5)
print(report)

Load your own CSV

from breezeml import from_csv

model, report = from_csv("sales_data.csv", target="revenue")
print(report)

---

API Reference

Core Functions

fit(df, target, task="auto") -> EasyModel

Train a model. Task type is inferred automatically unless you override it.

model = fit(df, "target_column", task="classification")

predict(model, X) -> np.ndarray

Run inference on new data.

predictions = predict(model, new_df)

auto(df, target, task="auto") -> (EasyModel, dict)

Same as fit, but returns an evaluation report alongside the trained model.

model, report = auto(df, "target_column", task="regression")

from_csv(path, target) -> (EasyModel, dict)

Load a CSV, train a model, and return its evaluation report.

model, report = from_csv("data.csv", target="label")

save(model, path) / load(path)

Persist and restore any trained EasyModel.

save(model, "my_model.joblib")
model = load("my_model.joblib")

---

classifiers Module

All classifier functions share the same signature:

model, report = classifiers.<name>(df, target)

The standard report includes:

{"accuracy": float, "f1": float, "macro_f1": float}

Available Classifiers

Function	Algorithm	Notes
classifiers.logistic	Logistic Regression	Linear baseline
classifiers.svm	SVM (RBF kernel)	Robust for small to medium datasets
classifiers.linear_svm	Linear SVM	Scales well to large sparse feature spaces
classifiers.gaussian_nb	Gaussian Naive Bayes	Fast for numeric features
classifiers.multinomial_nb	Multinomial Naive Bayes	Good for counts and TF-IDF
classifiers.decision_tree	Decision Tree	Fully interpretable
classifiers.random_forest	Random Forest	Strong general-purpose baseline
classifiers.knn	K-Nearest Neighbors	Non-parametric
classifiers.gradient_boosting	Gradient Boosting	High tabular accuracy
classifiers.adaboost	AdaBoost	Ensemble boosting
classifiers.extra_trees	Extra Trees	Faster random-forest-style ensemble
classifiers.mlp	Neural Network (MLP)	Deep learning baseline

classifiers.compare(df, target)

Benchmark every built-in classifier and receive a ranked leaderboard.

from breezeml import classifiers, datasets

df = datasets.iris()
results = classifiers.compare(df, "species")

classifiers.detailed_report(df, target)

Returns confusion matrix, precision, recall, ROC-AUC, and the full classification report.

info = classifiers.detailed_report(df, "species", algo="decision_tree")
print(info["accuracy"])
print(info["confusion_matrix"])
print(info["roc_auc"])

classifiers.quick_tune(df, target, algo)

Runs RandomizedSearchCV with curated search spaces for the selected classifier.

model, params, report = classifiers.quick_tune(
    df, "species", algo="random_forest"
)
print(params)
print(report)

Supported algorithms: logistic, svm, knn, decision_tree, random_forest, gradient_boosting, adaboost, extra_trees, mlp, plus optional xgboost and lightgbm

Aliases:

• classifiers.logistic_regression
• classifiers.naive_bayes

---

regressors Module (new in v0.3.0)

All regressor functions share the same signature:

model, report = regressors.<name>(df, target)

The standard regression report includes:

{
    "r2": float,
    "mae": float,
    "rmse": float,
    "adjusted_r2": float,
    "mape": float,
}

Available Regressors

Function	Algorithm	Notes
regressors.linear	Linear Regression	Simple baseline
regressors.ridge	Ridge Regression	L2 regularization
regressors.lasso	Lasso Regression	L1 regularization
regressors.elastic_net	Elastic Net	Hybrid L1 + L2
regressors.svr	Support Vector Regression	Nonlinear baseline
regressors.decision_tree	Decision Tree Regressor	Interpretable
regressors.random_forest	Random Forest Regressor	Strong tabular baseline
regressors.gradient_boosting	Gradient Boosting Regressor	Often the strongest built-in option
regressors.knn	K-Nearest Neighbors Regressor	Non-parametric
regressors.mlp	Neural Network (MLP) Regressor	Deep learning baseline

regressors.compare(df, target)

Benchmark every built-in regressor and rank them by R2.

from breezeml import regressors, datasets

df = datasets.diabetes()
results = regressors.compare(df, "target")

regressors.detailed_report(df, target)

Returns richer diagnostics such as explained variance, residuals, and prediction-vs-actual pairs.

from breezeml import regressors, datasets

df = datasets.diabetes()
info = regressors.detailed_report(df, "target", algo="random_forest")
print(info["r2"])
print(info["explained_variance"])
print(info["residuals"][:5])

regressors.quick_tune(df, target, algo)

Runs RandomizedSearchCV with curated search spaces for the selected regressor.

from breezeml import regressors, datasets

df = datasets.diabetes()
model, params, report = regressors.quick_tune(
    df, "target", algo="decision_tree", n_iter=10, cv=3
)
print(params)
print(report)

Supported algorithms: linear, ridge, lasso, elastic_net, svr, decision_tree, random_forest, gradient_boosting, knn, mlp, plus optional xgboost and lightgbm

---

features Module (new in v0.3.0)

Use breezeml.features to reduce noisy feature spaces, inspect model importances, and engineer stronger tabular inputs.

features.select(df, target, method="mutual_info", k=10)

from breezeml import datasets, features

df = datasets.iris()
selected = features.select(df, "species", method="mutual_info", k=3)
print(selected.head())

features.importance(model, df, target=None)

from breezeml import datasets, features, regressors

df = datasets.diabetes()
model, _ = regressors.random_forest(df, "target")
print(features.importance(model, df, target="target"))

features.pca(df, n_components=0.95) and features.polynomial(df, degree=2, columns=None)

from breezeml import datasets, features

df = datasets.iris().drop(columns=["species"])
pca_df = features.pca(df, n_components=2)
poly_df = features.polynomial(df, degree=2, columns=df.columns[:2].tolist())

---

Cascade Classification (v0.2.6)

A cascade chains multiple BreezeML classifiers into a hierarchical pipeline where each level narrows the prediction space. This is useful when a target has a natural hierarchy, such as sector -> group -> leaf code.

from breezeml import classifiers
import joblib

m1, r1 = classifiers.linear_svm(X=X_train, y=y_sector, X_test=X_test, y_test=y_sector_test)
m2, r2 = classifiers.linear_svm(X=X_train, y=y_group, X_test=X_test, y_test=y_group_test)
m3, r3 = classifiers.linear_svm(X=X_train, y=y_code, X_test=X_test, y_test=y_code_test)

joblib.dump({"sector": m1, "group": m2, "code": m3}, "cascade_model.joblib")

---

NLP and Semantic Embeddings (v0.2.9)

Convert raw text columns into dense semantic vectors with sentence-transformers.

from breezeml.text import embed

df_dense = embed(df, text_columns=["review"])
model = fit(df_dense, target="sentiment")

---

Explainability and Plotting (v0.2.9)

explain.explain(model, df)

Generate a SHAP summary plot for a trained model.

from breezeml.explain import explain

explain(model, X_test)

plot.confusion_matrix(model, X_test, y_test) and plot.roc_curve(model, X_test, y_test)

Instant Matplotlib visualizations without the usual boilerplate.

from breezeml.plot import confusion_matrix, roc_curve

confusion_matrix(model, X_test, y_test, cmap="Blues")
roc_curve(model, X_test, y_test)

plot.compare_chart, plot.learning_curve, and plot.feature_importance (v0.3.0)

from breezeml import datasets, classifiers, plot

df = datasets.iris()
results = classifiers.compare(df, "species", show=False)
plot.compare_chart(results, metric="accuracy")

---

clustering Module

from breezeml import clustering, datasets

df = datasets.wine()
res = clustering.kmeans(df.drop(columns=["class"]), n_clusters=3)
print(res["silhouette"])
print(res["labels"][:10])

Function	Algorithm
clustering.kmeans(df, n_clusters)	K-Means
clustering.agglomerative(df, n_clusters)	Agglomerative Hierarchical
clustering.dbscan(df, eps, min_samples)	DBSCAN

---

Built-in Datasets

Function	Source	Target Column	Task
datasets.iris()	sklearn	species	Classification
datasets.wine()	sklearn	class	Classification
datasets.breast_cancer()	sklearn	label	Classification
datasets.diabetes()	sklearn	target	Regression
datasets.california_housing()	sklearn	MedHouseVal	Regression
datasets.penguins()	seaborn	species	Classification
datasets.from_url(url)	CSV URL	user-defined	Mixed

---

Examples

All examples live in /examples. You can also open the Colab quickstart notebook:

File	Description
breezeml_quickstart.ipynb	Interactive notebook walkthrough
test_classification.py	Basic classification smoke test
test_classifiers.py	All 12 classifiers end-to-end
test_clustering.py	Clustering algorithms
test_boost.py	Optional XGBoost and LightGBM coverage
test_features.py	Feature engineering helpers
test_regression.py	Core regression pipeline
test_regressors.py	Regressor leaderboard, detailed report, and tuning coverage
test_save_load.py	Model persistence
test_v020_features.py	Broader feature coverage from earlier releases

---

Troubleshooting

Error	Cause	Fix
ModuleNotFoundError: breezeml	Library not installed	pip install breezeml
ValueError: columns do not match	Feature mismatch at inference	Ensure prediction data uses the same columns as training
ConvergenceWarning	Linear or neural models did not converge	Increase max_iter or normalize features
Version conflict	Outdated dependencies	pip install --upgrade scikit-learn pandas numpy

---

Roadmap

• Core fit / predict / auto API
• 12 classifiers with unified interface
• 10 regressors with leaderboard, detailed reports, and tuning (v0.3.0)
• Classifier leaderboard (compare)
• Regressor leaderboard (regressors.compare) (v0.3.0)
• Cross-validation support across classifiers and regressors (v0.3.0)
• Hyperparameter auto-tuning (quick_tune)
• Regression hyperparameter tuning (regressors.quick_tune) (v0.3.0)
• Detailed evaluation reports (confusion matrix, ROC-AUC)
• Detailed regression reports (adjusted_r2, mape, residuals) (v0.3.0)
• Feature engineering helpers (select, importance, pca, polynomial) (v0.3.0)
• Optional XGBoost and LightGBM integration (v0.3.0)
• Clustering (K-Means, DBSCAN, Agglomerative)
• Cascade classification - hierarchical multi-level pipelines (v0.2.6)
• External test set support (X_test / y_test) on all classifiers (v0.2.6)
• Macro F1 in all report dicts (v0.2.6)
• Native semantic text embeddings (breezeml.text) (v0.2.9)
• explain() - SHAP-based feature importance (v0.2.9)
• Native plotting (plot_confusion_matrix, plot_roc) (v0.2.9)
• Additional datasets (Titanic, MNIST subset)
• Pipeline.export() - export trained pipelines as Python
• BreezeAutoML - full AutoML via Optuna integration

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md first.

git clone https://github.com/venomez-viper/breezeml.git
cd breezeml
pip install -e ".[dev]"
pytest tests/ -v
ruff check .

All pull requests should:

• Pass the existing CI suite
• Include tests for new functionality
• Follow the existing docstring style

---

License

MIT © 2025 Akash Anipakalu Giridhar

See LICENSE for full terms.

---

Maintained by Akash Anipakalu Giridhar