BreezeML

A beginner-friendly, production-aware ML workflow layer for students, analysts, and AI agents.

Train, compare, explain, export, and deploy scikit-learn models without drowning in boilerplate.

Website · Getting Started · API Reference · Examples · Contributing · Changelog

Interactive docs & playground: breezeml.org — run BreezeML live in your browser, no install.

Overview

BreezeML is a beginner-friendly, production-aware ML workflow layer for students, analysts, and AI agents. It helps you train, compare, explain, export, and deploy scikit-learn models without drowning in boilerplate, while keeping the underlying workflow statistically sound: leakage-safe preprocessing, stratified splits, honest metrics, and reproducible seeds by default.

New in 2.0 — honest by default, agent-native by design. One call, one verdict: report(model, df) runs the whole honesty gauntlet (performance vs a naive baseline, leakage audit, class imbalance, fairness) and returns a single SHIP / WARN / STOP. fit() now returns one unified Model with .report(), .evaluate(), .explain(), .card(), .export(), .deploy(), and conformal .predict_interval() / .predict_set(). Ships py.typed; AI agents get the same verdict over MCP. See the changelog.

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.

Why BreezeML

Four promises no other low-code ML library makes together:

4 dependencies. Always. Core installs with only scikit-learn, pandas, numpy, joblib, CI-enforced. No dependency hell, ever.
Zero lock-in. export() hands you a standalone sklearn script reproducing your exact pipeline, with no breezeml import. Graduate anytime.
It teaches you. explain_decisions=True narrates every pipeline choice in plain English, and card() writes an honest model card with auto-detected caveats.
AI agents can use it. breezeml-mcp is a built-in MCP server: Claude and other agents train, compare, explain, and deploy models with sound statistical defaults.

import breezeml
from breezeml import datasets

df = datasets.iris()
model, report = breezeml.auto(df, "species", explain_decisions=True)  # learn while training

breezeml.card(model, "MODEL_CARD.md")     # honest model card
breezeml.export(model, "train.py")        # pure-sklearn script, zero lock-in
breezeml.deploy(model, "api/")            # FastAPI app + Dockerfile, ready to run

Start Here: The Garden Path

BreezeML is big, but you never need all of it. It is layered like a garden path: walk only as far as you need, and every layer is optional. Lost? Run breezeml.guide() any time for this map in your terminal.

Breath 1 - your first model (day one, 3 lines)

from breezeml import datasets, fit, predict

model = fit(datasets.iris(), "species")
predict(model, new_df)

That is a complete, leakage-safe, stratified, seeded ML workflow. If this is all you need, stop here. You are done.

Breath 2 - understand and choose

model, report = breezeml.auto(df, "target", explain_decisions=True)  # narrates every choice
breezeml.classifiers.compare(df, "target")   # leaderboard of 22 models
breezeml.card(model, "MODEL_CARD.md")        # honest model card

Breath 3 - automate and ship

breezeml.automl(df, "target", time_budget=60)  # search everything, honestly
breezeml.export(model, "train.py")             # pure sklearn, zero lock-in
breezeml.deploy(model, "api/")                 # FastAPI + Docker
breezeml.drift.check(model, new_df)            # production drift report

Breath 4 - beyond

Time series forecasting, clustering, feature engineering, text embeddings, SHAP explainability, the MCP server for AI agents, and the zen garden. Everything below this line is reference material - come back when you need it.

Key Features

Feature	Description
Honest scorecard (v2.0)	`report(model, df)` runs the whole honesty gauntlet - cross-validated performance vs a naive baseline, leakage audit, class imbalance, and optional fairness - and returns one SHIP / WARN / STOP verdict as a `Report` (`to_dict` / `to_json` / `to_markdown`)
Unified `Model` object (v2.0)	`fit()` returns one coherent object: `predict` / `evaluate` / `report` / `explain` / `card` / `export` / `deploy`, plus conformal `predict_interval()` (regression) and `predict_set()` (classification)
Agent-native report tool (v2.0)	the MCP server exposes a `report` tool, so AI agents read the SHIP/WARN/STOP verdict as JSON and confirm SHIP before calling `deploy` or `export`
Typed & stable (v2.0)	ships a `py.typed` marker (PEP 561) so type checkers read BreezeML's types; public entry points annotated; documented semver + deprecation policy (`docs/stability.md`)
Conformal prediction (v1.9)	`conformal_regressor()` and `conformal_classifier()` wrap any trained model with distribution-free prediction intervals / sets at a guaranteed marginal coverage; `coverage_report()` checks it empirically
Active learning (v1.9)	`active.query()` ranks an unlabeled pool by informativeness (uncertainty/margin/entropy); `active.simulate()` reports honestly whether active learning beat a random baseline
Automatic feature engineering (v1.9)	`autofeat.engineer()` does datetime expansion, leakage-safe out-of-fold target encoding, capped numeric interactions, and pruning, returning `(new_df, report)`
Causal inference and uplift (v1.9)	`causal.estimate_ate()` (naive/t_learner/ipw) reports the adjusted effect beside the confounded baseline; `causal.uplift()` gives per-row CATE; `causal.check_confounding()` flags covariate imbalance
Statistical significance testing (v1.8)	`significance.mcnemar()` and `paired_cv_ttest()` attach a p-value to a model gap and say "keep the simpler model" when it is noise; pure numpy, no scipy
Multi-label / multi-output (v1.8)	`multi.multi_label()` and `multi.multi_output()` predict several targets at once, with per-target metrics plus `subset_accuracy` / `hamming_loss`
Recommender systems (v1.8)	`recommend.collaborative_filter()` does SVD collaborative filtering with a popularity fallback and honest cold-start warnings
Survival analysis (v1.8)	`survival.kaplan_meier()` and `groups_kaplan_meier()` (with a log-rank test) do time-to-event modeling and refuse naive regression on censored durations
Data audit + leakage detection (v1.7)	`audit()` flags ID columns, duplicates, label noise, and single-feature target leakage; `contamination()` checks train/test overlap
Fairness reports (v1.7)	`fairness.report()` gives per-group metrics, demographic parity ratio, a four-fifths rule verdict, and TPR/FPR gaps
Imbalance toolkit (v1.7)	`balanced=True` training plus `tune_threshold()`, `calibrate()`, and `cost_report()` on the core dependencies
Model blending (v1.7)	`blend()` ensembles the `compare()` winners (vote or stack) and reports honestly whether it beats the best single model
Experiment tracking (v1.7)	`track.log()` / `leaderboard()` / `best()` in a plain `.breezeml/runs.json`; zero extra dependencies
Anomaly detection (v1.7)	4 detectors plus `anomaly.compare()` with majority/unanimous consensus across them
Semi-supervised learning (v1.7)	`semisupervised.self_train()` learns from NaN-target rows and always reports the supervised baseline
Command line interface (v1.7)	`breezeml train/compare/automl/audit/deploy/card/zen/guide` straight from the terminal
Native explainability (v1.7)	`explain.permutation_importance()` and `explain.partial_dependence()` on core dependencies; no SHAP needed
BreezeAutoML (v1.1)	`automl()` screens every model then tunes the best within a time budget; optional Optuna backend
Time series (v1.2)	`timeseries.forecast()` and `compare()` with walk-forward CV and a mandatory naive baseline
Drift monitoring (v1.3)	`drift.check()` + a live `/drift` endpoint in every deployed API; PSI, new categories, range violations
Live progress bars (v1.4)	`compare()`, `automl()`, and `timeseries.compare()` show training progress; pure stdlib, no tqdm
The zen garden (v1.5)	`zen()`, `haiku()`, and `fortune()` - ML wisdom as haiku and omikuji, under falling sakura
Zero lock-in export (v1.0)	`export()` writes a standalone sklearn training script with no breezeml imports
Model cards (v1.0)	`card()` generates honest markdown model cards with auto-detected caveats
Teaching narration (v1.0)	`explain_decisions=True` explains every pipeline choice in plain English
One-line deployment (v1.0)	`deploy()` writes a FastAPI app + Dockerfile serving the raw sklearn pipeline
MCP server for AI agents (v1.0)	`breezeml-mcp` lets Claude & other agents train/compare/explain/deploy models
Dependency contract (v1.0)	Core needs only sklearn, pandas, numpy, joblib, enforced by CI, forever
Auto task detection	Automatically selects classification or regression based on the target column
22 classifiers (v1.7)	From Logistic Regression to Hist Gradient Boosting, LDA/QDA, Neural Nets, and Bagging
22 regressors (v1.7)	From Linear Regression to Hist Gradient Boosting, Huber, Poisson, quantile, and robust fits
9 clusterers (v1.7)	K-Means to HDBSCAN, OPTICS, and Mean Shift, all with silhouette reporting
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: The Four Breaths

BreezeML follows a layered design (in the spirit of fastai's layered API): approachable at the top, hackable underneath, honest everywhere.

 Breath 1  ONE LINE        fit . predict . auto . from_csv
           |               "give me a sound model"
 Breath 2  UNDERSTAND      compare . quick_tune . explain_decisions . card
           |               "which model, and why?"
 Breath 3  SHIP            automl . export . deploy . drift . timeseries
           |               "automate, productionize, monitor"
 Breath 4  EXTEND          features . clustering . text . explain . plot . MCP
                           "toolkits and agents"

breezeml/
|-- breezeml.py        # Breath 1: fit, predict, auto, from_csv, save, load
|-- classifiers.py     # Breath 2: 22 classifiers + compare, detailed_report, quick_tune
|-- regressors.py      # Breath 2: 22 regressors + compare, detailed_report, quick_tune
|-- automl.py          # Breath 3: budget-aware model search
|-- export.py          # Breath 3: zero lock-in sklearn codegen
|-- deploy.py          # Breath 3: FastAPI + Docker serving
|-- drift.py           # Breath 3: PSI drift detection
|-- timeseries.py      # Breath 3: forecasting with honesty checks
|-- audit.py           # Breath 3: data quality + target-leakage detection
|-- fairness.py        # Breath 3: per-group parity reports
|-- imbalance.py       # Breath 3: thresholds, calibration, cost decisions
|-- blend.py           # Breath 3: vote/stack ensembles with honest verdicts
|-- track.py           # Breath 3: experiment log (.breezeml/runs.json)
|-- cli.py             # Breath 3: the breezeml terminal command
|-- clustering.py      # Breath 4: 9 clustering algorithms
|-- anomaly.py         # Breath 4: 4 detectors + consensus
|-- semisupervised.py  # Breath 4: self-training on partial labels
|-- features.py        # Breath 4: selection, importances, PCA, polynomial
|-- text.py            # Breath 4: semantic text embeddings
|-- explain.py         # Breath 4: permutation importance + PDP (native), SHAP (extra)
|-- plot.py            # Breath 4: plotting helpers
|-- mcp_server.py      # Breath 4: AI-agent tools (breezeml-mcp)
`-- __init__.py        # public API + zen garden

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.9, 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[deploy]"   # fastapi + uvicorn for deploy()
pip install "breezeml[onnx]"     # ONNX export
pip install "breezeml[automl]"   # Optuna backend for automl()
pip install "breezeml[mcp]"      # MCP server for AI agents
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")

`report(model, df, target=None, sensitive=None) -> Report` (v2.0)

The honest scorecard. Runs the whole honesty gauntlet on a trained model - cross-validated performance vs a naive baseline, a data audit for leakage and quality, class-imbalance severity, and an optional fairness check - and returns one SHIP / WARN / STOP verdict.

model = fit(df, "target")
rep = report(model, df)            # prints SHIP / WARN / STOP
rep.verdict                        # "SHIP" | "WARN" | "STOP"
rep.to_json("report.json")         # also to_dict() / to_markdown()

The unified `Model` object (v2.0)

fit() returns one coherent object. Every workflow verb is a method:

model = fit(df, "target")
model.evaluate(df)                 # cross-validated metrics dict
model.report(df)                   # SHIP / WARN / STOP
model.explain(df)                  # permutation importances
model.card("MODEL_CARD.md")        # honest model card
model.export("train.py")           # standalone sklearn, zero lock-in
model.deploy("api/")               # FastAPI + Docker
# honest uncertainty (held-out calibration set required):
model.predict_interval(X, calib_df)   # regression: lower / point / upper
model.predict_set(X, calib_df)        # classification: label sets

`automl(df, target, time_budget=60)` (v1.1)

Budget-aware automated model selection: screens every built-in model with cross-validation, tunes the top candidates with the remaining time, and reports honest holdout metrics. backend="optuna" switches to TPE search (pip install breezeml[automl]).

model, report = breezeml.automl(df, "churn", time_budget=120)
print(report["best_model"], report["holdout"])

`timeseries.forecast(df, target, horizon, date_col)` (v1.2)

Univariate forecasting with lag/rolling features, walk-forward validation, and a mandatory naive-baseline comparison. timeseries.compare() ranks all models the same way.

from breezeml import timeseries
model, forecast, report = timeseries.forecast(df, "sales", horizon=14, date_col="date")
print(report["beats_naive"], report["skill_vs_naive"])

`drift.check(model, new_df)` (v1.3)

Compare new data against the training distributions stored on every core-API model: PSI per column, values outside the training range, unseen categories, missing-rate spikes. Deployed apps get a live GET /drift endpoint for free.

result = breezeml.drift.check(model, new_df)   # or model.check_drift(new_df)
print(result["summary"])

`audit(df, target)` (v1.7)

Pre-training data audit: ID-like columns, constants, duplicate rows, contradictory labels, high-cardinality categoricals, heavy missingness, class imbalance, and single-feature target-leakage probes (a tiny tree trained on one feature at a time; near-perfect scores flag a leak). Returns findings with severities and an overall ok flag. contamination(train_df, test_df) detects rows shared across a split.

result = breezeml.audit(df, "churn")
print(result["ok"], result["summary"])
breezeml.contamination(train_df, test_df)

`blend(df, target, method="vote")` (v1.7)

Ensemble the top compare() models by soft voting ("vote") or stacking ("stack"). The report always carries beats_best_single; when the blend loses to the best single model, BreezeML says to keep the single model. The result is a normal EasyModel: save(), card(), and deploy() work.

model, report = breezeml.blend(df, "target", method="stack")
print(report["blend_score"], report["best_single_score"], report["beats_best_single"])

`significance.mcnemar(model_a, model_b, df, target)` (v1.8)

Ask whether one model really beat another or you just got a lucky seed. mcnemar() splits df once (stratified, matching the core holdout), predicts with both fitted models on that shared slice, and runs McNemar's test on the discordant pairs, returning statistic, p_value, n_discordant, significant, and a plain-English verdict. paired_cv_ttest(algo_a, algo_b, df, target) compares two algorithms across the same CV folds with a paired t-test. Both are pure numpy (no scipy), and both say "keep the simpler model" when the gap is not significant.

from breezeml import significance
r = significance.mcnemar(model_a, model_b, df, "target")
print(r["p_value"], r["significant"], r["verdict"])
significance.paired_cv_ttest("random_forest", "logistic", df, "target")

`multi.multi_label(df, targets, chain=False)` (v1.8)

Predict several label columns at once. Returns an (EasyModel, report) pair where the report has per-target accuracy/F1 plus subset_accuracy (exact-match ratio) and hamming_loss. chain=True uses a ClassifierChain to capture label correlations; the default fits one independent model per label. multi.multi_output(df, targets) does the regression analogue and reports per-target r2/mae/rmse plus average_r2.

from breezeml import multi
model, report = multi.multi_label(df, ["billing", "urgent", "refund"])
print(report["subset_accuracy"], report["hamming_loss"])
multi.multi_output(df, ["temperature", "pressure"])

`recommend.collaborative_filter(df, user_col, item_col, rating_col=None)` (v1.8)

SVD collaborative filtering on the core dependencies. Builds a user-item matrix from a long-format interactions table, factorizes it with a truncated SVD, and returns a fitted Recommender. rec.recommend(user, k) returns [(item, score), ...] over items the user has not seen; rec.recommend_report(user, k) adds honest cold_start and method ("svd" or "popularity") flags. Cold users fall back to global popularity and it says so; sparse matrices and single-interaction users/items get warnings.

from breezeml import recommend
rec = recommend.collaborative_filter(df, "user", "item", rating_col="stars")
print(rec.recommend_report("u_7", k=5))

`survival.kaplan_meier(df, duration_col, event_col)` (v1.8)

Time-to-event modeling that respects censoring. kaplan_meier() returns the survival curve (timeline, survival, ci_lower/ci_upper, median_survival, censoring_rate) and prints a loud warning against regressing on duration while ignoring event. groups_kaplan_meier(..., group_col) fits a curve per group and adds a log-rank test (logrank_p_value, significant); check_censoring() reports the censoring rate on its own. Pure numpy.

from breezeml import survival
km = survival.kaplan_meier(df, "duration", "event")
survival.groups_kaplan_meier(df, "duration", "event", "arm")

`conformal_regressor(model, calib_df, target, alpha=0.1)` (v1.9)

Honest, distribution-free uncertainty on any already-trained model. Calibrate on held-out data the model has never seen and every prediction carries a prediction interval (regression) or prediction set (classification) with a guaranteed marginal coverage of at least 1 - alpha (alpha=0.1 gives 90%). conformal_regressor() returns a ConformalRegressor whose predict_interval(X) yields lower/point/upper columns (pass normalize=True for locally adaptive bands); conformal_classifier() returns a ConformalClassifier whose predict_set(X) yields per-row label sets. Both have coverage_report(df, target) to verify empirical coverage.

from breezeml import conformal, regressors
model, _ = regressors.random_forest(train_df, "target")
cp = conformal.conformal_regressor(model, calib_df, "target", alpha=0.1)
bands = cp.predict_interval(test_df.drop(columns=["target"]))
cp.coverage_report(test_df, "target")   # empirical coverage ~ 90%

`active.query(model, unlabeled_df, k, strategy)` (v1.9)

Spend your labeling budget where it helps. query() ranks an unlabeled pool by informativeness (strategy is uncertainty, margin, entropy, or random) and returns {"indices", "scores", "strategy", "k"} for the top-k rows to label next. active.simulate(df, target, initial, budget, step, strategy) runs the active loop against a random baseline from the same starting set and returns budgets, active_accuracy, random_accuracy, area_between_curves, and active_wins, printing an honest verdict on whether active learning won.

from breezeml import active
pick = active.query(model, unlabeled_df, k=20, strategy="uncertainty")
curve = active.simulate(df, "label", initial=20, budget=120, step=20)
print(curve["active_wins"], curve["area_between_curves"])

`autofeat.engineer(df, target)` (v1.9)

Automatic feature engineering that enriches without leaking. One call does datetime expansion, leakage-safe out-of-fold (5-fold) target-mean encoding plus frequency encoding for high-cardinality categoricals, capped pairwise numeric interactions, and pruning of constant and near-duplicate (|r| > 0.98) columns. Returns (new_df, report) where report lists added, dropped, encoded, datetime_expanded, and before/after feature counts. The input frame is never mutated.

from breezeml import autofeat
new_df, report = autofeat.engineer(df, "target")
print(report["n_features_before"], "->", report["n_features_after"])

`causal.estimate_ate(df, treatment, outcome, method="t_learner")` (v1.9)

Separate correlation from causation. estimate_ate() always reports the confounded naive baseline beside the adjusted estimate (method is naive, t_learner, or ipw) and returns ate, naive_ate, propensity_range, and a plain-English note; a large gap between naive and adjusted is the footprint of confounding. causal.uplift() returns a TLearnerPair whose predict_uplift(X) gives the per-row treatment effect (CATE). causal.check_confounding() flags covariate imbalance via standardized mean differences and warns that observational estimates rest on the untestable no-unmeasured-confounders assumption.

from breezeml import causal
res = causal.estimate_ate(df, "treated", "spend", method="t_learner")
print(res["ate"], res["naive_ate"], res["note"])
pair, r = causal.uplift(df, "treated", "spend")
causal.check_confounding(df, "treated", "spend")

`export(model, path, data_path="YOUR_DATA.csv")` (v1.0)

Write a standalone scikit-learn training script that reproduces the exact pipeline (imputers, scaler, encoder, estimator, seed, split) with zero breezeml imports. Also available as model.export(path).

breezeml.export(model, "train.py", data_path="iris.csv")

`card(model, path=None)` (v1.0)

Generate an honest markdown model card: data profile, metrics, every pipeline decision explained, and auto-detected caveats (small data, class imbalance, heavy imputation). Also available as model.card(path).

print(breezeml.card(model))
breezeml.card(model, "MODEL_CARD.md")

`deploy(model, out_dir, name)` (v1.0)

Write a complete serving directory: FastAPI app (/predict, /health, /docs), Dockerfile, requirements, and the raw sklearn pipeline. The app never imports breezeml. Also available as model.deploy(out_dir).

breezeml.deploy(model, "api/", name="iris-classifier")
# cd api && pip install -r requirements.txt && uvicorn app:app

Teaching narration (v1.0)

model, report = breezeml.auto(df, "species", explain_decisions=True)
# BreezeML decisions explained:
#   1. Detected a classification task: target 'species' has only 3 distinct values...
#   2. Used a stratified 80/20 train/test split because...
model.explain_decisions()  # again, anytime

MCP Server for AI Agents (v1.0)

BreezeML ships a Model Context Protocol server so AI agents (Claude Code, Claude Desktop, and other MCP clients) can train, compare, explain, export, and deploy models with statistically sound defaults.

pip install breezeml[mcp]
claude mcp add breezeml -- breezeml-mcp

Tools: inspect_data, compare, train, predict, explain, model_card, export, deploy, save. See the MCP guide.

Command Line Interface (v1.7)

Installing breezeml puts a breezeml command on your PATH:

breezeml train data.csv --target churn        # auto model -> model.joblib (--explain narrates)
breezeml compare data.csv --target churn      # leaderboard of all built-in models
breezeml automl data.csv --target churn --budget 120
breezeml audit data.csv --target churn        # data quality + leakage; exits 1 on critical findings
breezeml deploy model.joblib --out api/       # FastAPI + Docker serving directory
breezeml card model.joblib --out MODEL_CARD.md
breezeml zen                                  # the Zen of BreezeML
breezeml guide                                # the garden path map

The audit exit code makes it a natural CI gate before a scheduled retrain.

`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.hist_gradient_boosting` (v1.4)	Hist Gradient Boosting	sklearn's LightGBM-class booster, fast on large data
`classifiers.ridge` (v1.4)	Ridge Classifier	Very fast regularized linear baseline
`classifiers.sgd` (v1.4)	SGD (linear)	Scales to very large datasets
`classifiers.lda` (v1.4)	Linear Discriminant Analysis	Classic, strong on small data
`classifiers.qda` (v1.4)	Quadratic Discriminant Analysis	Curved class boundaries
`classifiers.complement_nb` (v1.4)	Complement Naive Bayes	Best NB variant for imbalanced text
`classifiers.bernoulli_nb` (v1.7)	Bernoulli Naive Bayes	For binary/boolean features
`classifiers.passive_aggressive` (v1.7)	Passive Aggressive	Online linear learner, scales to large data
`classifiers.nearest_centroid` (v1.7)	Nearest Centroid	One centroid per class; the simplest baseline
`classifiers.bagging` (v1.7)	Bagging	Bootstrap-aggregated trees

`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.hist_gradient_boosting` (v1.4)	Hist Gradient Boosting	sklearn's LightGBM-class booster, fast on large data
`regressors.extra_trees` (v1.4)	Extra Trees Regressor	Faster random-forest-style ensemble
`regressors.adaboost` (v1.4)	AdaBoost Regressor	Ensemble boosting
`regressors.huber` (v1.4)	Huber Regressor	Robust to outliers
`regressors.bayesian_ridge` (v1.4)	Bayesian Ridge	Uncertainty-aware linear model
`regressors.sgd` (v1.4)	SGD Regressor	Scales to very large datasets
`regressors.poisson` (v1.7)	Poisson GLM	Count targets (visits, orders, defects)
`regressors.quantile` (v1.7)	Quantile Regressor	Predict a quantile instead of the mean (`q=0.9` for conservative planning)
`regressors.theilsen` (v1.7)	Theil-Sen	Robust line fitting, immune to ~29% outliers
`regressors.ransac` (v1.7)	RANSAC	Fits on inlier consensus; shrugs off gross outliers
`regressors.kernel_ridge` (v1.7)	Kernel Ridge (RBF)	Nonlinear ridge regression
`regressors.bagging` (v1.7)	Bagging Regressor	Bootstrap-aggregated trees

`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
`clustering.gaussian_mixture(df, n_clusters)` (v1.4)	Gaussian Mixture (soft clustering + BIC)
`clustering.birch(df, n_clusters)` (v1.4)	Birch (memory-efficient, large data)
`clustering.spectral(df, n_clusters)` (v1.4)	Spectral (non-convex cluster shapes)
`clustering.meanshift(df, bandwidth)` (v1.7)	Mean Shift (finds the number of clusters itself)
`clustering.optics(df, min_samples)` (v1.7)	OPTICS (clusters of varying density)
`clustering.hdbscan(df, min_cluster_size)` (v1.7)	HDBSCAN (sklearn >= 1.3; noise-aware density clustering)

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 classifiers end-to-end
`test_clustering.py`	Clustering algorithms
`test_regression.py`	Core regression pipeline
`test_save_load.py`	Model persistence
`test_v020_features.py`	Broader feature coverage from earlier releases

Learn on Kaggle

The BreezeML Playground is a synthetic dataset collection where every trap is planted on purpose: a hidden post-outcome leak, labels carrying bias, a confounded campaign, a batch that drifted after training. The generator script ships inside the dataset, so nothing is hidden.

Twelve runnable notebooks teach one honest-ML lesson each:

Notebook	Lesson
Your First ML Model, Explained Simply	start here if you are new to ML
Honest ML on Titanic	the honest report on the classic dataset
Find the Leak Before It Finds You	catching planted target leakage
When Accuracy Lies	imbalanced classes, thresholds, cost tuning
Your Model Will Rot	drift detection on a shifted batch
AutoML on a Budget	honest model search in 60 seconds
Uncertainty You Can Trust	conformal prediction intervals
Is Your Model Fair?	the four-fifths rule on biased labels
When Will It Happen?	survival analysis with censoring
The Campaign That Lied	correlation vs causation, confounding
Finding Groups and Oddballs	clustering and anomaly consensus
Honest Forecasting	walk-forward validation vs the naive baseline

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

The Zen Garden

BreezeML is named for the wind, and the wind has opinions.

import breezeml

breezeml.zen()      # the Zen of BreezeML: 15 ML haiku, kaze no michi
breezeml.haiku()    # one haiku, carried in on the breeze
breezeml.fortune()  # draw an omikuji for your model
breezeml.sensei()   # seek the founder of the dojo, receive one teaching
# ~ omikuji ~
# [Kyou (Misfortune)]
# Beware: a test set has been touched twice. The numbers now flatter.

There are more eggs hidden in the leaderboards. A perfect score is not always good news; the wind will tell you why.

Benchmarks

Measured 2026-07-05, Windows 11, Python 3.11, same machine and venv. Reproduce with python benchmarks/run_benchmarks.py.

	BreezeML	PyCaret	LazyPredict
Fresh install	2m 36s / 274 MB	6m 21s / 952 MB	(shared venv)
Cold import	3.1s	6.9s	7.2s
Wine leaderboard	9.0s	19.3s	3.7s
Best accuracy	1.000	0.984	1.000
User LOC	3	5	8
Zero lock-in export	yes	no	no

Full methodology and honest caveats: docs/benchmarks.md.

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

Support and Community

Questions and usage help: GitHub Discussions (Q&A category)
Bug reports: GitHub Issues
Feature ideas: GitHub Discussions (Ideas category)

Citing BreezeML

If you use BreezeML in your work, please cite it via the repository's CITATION.cff (GitHub's "Cite this repository" button).

License

See LICENSE for full terms.

Maintained by Akash Anipakalu Giridhar

Name		Name	Last commit message	Last commit date
Latest commit History 82 Commits
.github		.github
Logs		Logs
assets		assets
benchmarks		benchmarks
breezeml		breezeml
docs		docs
examples		examples
tests		tests
.gitignore		.gitignore
.mailmap		.mailmap
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
IMPLEMENTATION_v0.3.0.md		IMPLEMENTATION_v0.3.0.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
RELEASE_NOTES_v0.1.1.md		RELEASE_NOTES_v0.1.1.md
RELEASE_NOTES_v0.1.2.md		RELEASE_NOTES_v0.1.2.md
RELEASE_NOTES_v0.2.0.md		RELEASE_NOTES_v0.2.0.md
RELEASE_NOTES_v0.2.1.md		RELEASE_NOTES_v0.2.1.md
RELEASE_NOTES_v0.2.2.md		RELEASE_NOTES_v0.2.2.md
RELEASE_NOTES_v0.2.3.md		RELEASE_NOTES_v0.2.3.md
RELEASE_NOTES_v0.2.4.md		RELEASE_NOTES_v0.2.4.md
RELEASE_NOTES_v0.2.5.md		RELEASE_NOTES_v0.2.5.md
RELEASE_NOTES_v0.2.6.md		RELEASE_NOTES_v0.2.6.md
RELEASE_NOTES_v0.2.7.md		RELEASE_NOTES_v0.2.7.md
RELEASE_NOTES_v0.2.8.md		RELEASE_NOTES_v0.2.8.md
RELEASE_NOTES_v0.2.9.md		RELEASE_NOTES_v0.2.9.md
RELEASE_NOTES_v0.3.0.md		RELEASE_NOTES_v0.3.0.md
RELEASE_NOTES_v1.0.0.md		RELEASE_NOTES_v1.0.0.md
iris_model.joblib		iris_model.joblib
mkdocs.yml		mkdocs.yml
paper.bib		paper.bib
paper.md		paper.md
pyproject.toml		pyproject.toml
server.json		server.json

Folders and files

Latest commit

History

Repository files navigation

BreezeML

Overview

Why BreezeML

Start Here: The Garden Path

Breath 1 - your first model (day one, 3 lines)

Breath 2 - understand and choose

Breath 3 - automate and ship

Breath 4 - beyond

Key Features

Architecture: The Four Breaths

Installation

Quickstart

Classification in 3 lines

Auto mode for regression

Dedicated regression workflow (new in v0.3.0)

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

Load your own CSV

API Reference

Core Functions

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

predict(model, X) -> np.ndarray

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

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

save(model, path) / load(path)

report(model, df, target=None, sensitive=None) -> Report (v2.0)

The unified Model object (v2.0)

automl(df, target, time_budget=60) (v1.1)

timeseries.forecast(df, target, horizon, date_col) (v1.2)

drift.check(model, new_df) (v1.3)

audit(df, target) (v1.7)

blend(df, target, method="vote") (v1.7)

significance.mcnemar(model_a, model_b, df, target) (v1.8)

multi.multi_label(df, targets, chain=False) (v1.8)

recommend.collaborative_filter(df, user_col, item_col, rating_col=None) (v1.8)

survival.kaplan_meier(df, duration_col, event_col) (v1.8)

conformal_regressor(model, calib_df, target, alpha=0.1) (v1.9)

active.query(model, unlabeled_df, k, strategy) (v1.9)

autofeat.engineer(df, target) (v1.9)

causal.estimate_ate(df, treatment, outcome, method="t_learner") (v1.9)

export(model, path, data_path="YOUR_DATA.csv") (v1.0)

card(model, path=None) (v1.0)

deploy(model, out_dir, name) (v1.0)