Documentation

Learn machine learning by running it

New to ML? Start with Learn ML from scratch — plain English, no maths, and you will train a real model in your browser before you finish reading. Already comfortable? Jump to any feature. Every snippet marked Run here executes live, no install. Or open the blank canvas and try your own ideas.

Learn ML from scratch

Never done machine learning before? Start here. No maths, no jargon, just plain English and pictures in your head. By the end of this page you will understand what a model is, and you will have trained a real one in your browser.

What is machine learning?

Imagine teaching a child to recognise a cat. You do not write down rules like 'four legs, whiskers, pointy ears'. You just show them lots of cats, and soon they can spot a new cat they have never seen. Machine learning is the same idea for computers: instead of writing rules, we show the computer many examples, and it learns the pattern by itself. That learned pattern is called a MODEL.

Data, features, and the target

features = the clues · target = the answer

Think of a spreadsheet. Each ROW is one example (say, one flower). Each COLUMN is a FEATURE, a fact about it (petal length, petal width, colour). One special column is the TARGET, the thing we want to predict (which species of flower). BreezeML learns the link between the features and the target. That is why you only ever tell it two things: your table, and the name of the target column.

Two big jobs: sorting vs guessing a number

classification = buckets · regression = a number

Almost every ML problem is one of two jobs. CLASSIFICATION is sorting things into buckets: spam or not spam, cat or dog, which of 3 flowers. REGRESSION is guessing a number: tomorrow's temperature, a house price, how many visitors. BreezeML looks at your target column and picks the right job automatically, but now you know the difference.

Training and testing (no cheating!)

When you study for an exam, you practise on some questions and then the real test uses NEW questions you have not seen. If the teacher tested you on the exact practice questions, a good score would not mean you actually learned. Models are the same: we TRAIN on some rows and TEST on other, unseen rows. BreezeML always keeps a fair, unseen test set for you, so its scores are honest.

See it: train a real model now

Run here

Enough theory. Press Run. This loads 150 real flowers, learns to tell three species apart, and prints how often it is right, all inside this web page. You just did machine learning.

Try it yourself

Output

Press Run to execute this snippet.

What makes a score 'good'?

accuracy · F1 · ROC AUC

ACCURACY means 'out of 100 guesses, how many were right?'. Simple, but it can lie. If 99 out of 100 emails are NOT spam, a lazy model that always says 'not spam' is 99% accurate and completely useless. That is why BreezeML also shows F1 (a fairer score when the buckets are uneven) and, for yes/no problems, ROC AUC (how well it ranks the risky cases). More than one number keeps you honest.

Overfitting: memorising vs understanding

A student who memorises the answer key gets 100% on practice and fails the real exam. A model can do this too: it 'memorises' the training rows instead of learning the real pattern, so it looks amazing in practice and flops on new data. This is called OVERFITTING. The cure is testing on unseen data, which BreezeML does for you every time.

Cross-validation: five fair grades

5-fold cross-validation, always on

One test could be lucky or unlucky. So BreezeML splits your data into 5 parts, trains on 4 and tests on the 1 left out, then rotates until every part has been the test once. Averaging those 5 grades gives a score you can actually trust. That is CROSS-VALIDATION, and it runs by default.

Data leakage: the sneaky trap

breezeml.audit(df, target)Run here

Imagine predicting whether a patient is sick, but one column is 'medicine already prescribed'. The model will look brilliant, because that column basically contains the answer, but it is useless in real life where you do not know it yet. This is LEAKAGE. BreezeML's audit() hunts for these traps before you train. Honesty first.

Try it yourself

Output

Press Run to execute this snippet.

The cool stuff

BreezeML wraps scikit-learn so a beginner can go from a spreadsheet to an honest, deployable model in three lines, while an expert keeps full control. Here is what makes it special. Every promise below is a real feature.

A model in three lines

fit(df, target) -> modelRun here

No pipelines to wire, no config files. Give it a table and the name of the column you want to predict. BreezeML figures out the rest (classification vs regression, cleaning, encoding, scaling, cross-validation) and hands back a trained model.

Try it yourself

Output

Press Run to execute this snippet.

It explains itself

auto(df, target, explain_decisions=True)

Set explain_decisions=True and BreezeML narrates every choice it makes in plain English as it makes it: why it picked a model, how it cleaned the data, which metric it optimized. It teaches while it works.

Exampleruns locally after pip install

import breezeml

df = breezeml.datasets.wine()
model, report = breezeml.auto(
    df, "wine_class", explain_decisions=True
)

Zero lock-in, literally

export(model, 'train.py')

export() writes a standalone scikit-learn script that reproduces your exact pipeline with NO breezeml import. Delete the library and your model still runs. You are never trapped.

Exampleruns locally after pip install

import breezeml

df = breezeml.datasets.iris()
model = breezeml.fit(df, "species")
breezeml.export(model, "train.py")   # pure sklearn

Four dependencies. Always.

scikit-learn · pandas · numpy · joblib

The core installs with only four packages, and a CI test fails the build if anyone adds a fifth. That discipline is why the whole library can even run inside this web page.

Exampleruns locally after pip install

# the entire core dependency list
# scikit-learn, pandas, numpy, joblib
# (xgboost, lightgbm, onnx, etc. are optional extras)

It is honest by default

audit() · conformal · fairness · drift · significanceRun here

Most tools shout a single accuracy number. BreezeML ships a whole honesty toolkit: leakage detection, fairness gaps, drift monitoring, statistical significance, and distribution-free uncertainty. See the Honesty section.

Try it yourself

Output

Press Run to execute this snippet.

AI agents can use it

breezeml-mcp

A built-in Model Context Protocol server lets Claude and other agents train, compare, explain, and deploy models with sound statistical defaults, and get the same explanations you would.

Exampleruns locally after pip install

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

It has a soul

zen() · haiku() · fortune() · sensei()

When the work is done, breezeml.zen() rakes the gravel: a breathing pause, a haiku about your model, a fortune, or a word from the sensei. Machine learning, with calm.

Exampleruns locally after pip install

import breezeml

breezeml.haiku()
breezeml.fortune()

Getting started

Install once, then load a table and name your target column. Every snippet here runs in your browser, no setup.

Install

pip install breezeml

The core is four dependencies. Extras like xgboost, lightgbm, onnx, and the MCP server are opt-in.

Exampleruns locally after pip install

pip install breezeml

# optional extras
pip install "breezeml[boost]"   # xgboost + lightgbm
pip install "breezeml[mcp]"     # agent server
pip install "breezeml[all]"     # everything

Built-in datasets

breezeml.datasets.iris() -> DataFrameRun here

Practice datasets return a pandas DataFrame with a named target column. Available: iris, wine, breast_cancer, diabetes (regression), and penguins (needs seaborn).

Try it yourself

Output

Press Run to execute this snippet.

fit()

fit(df, target, task='auto') -> ModelRun here

The main entry point. Name the target and BreezeML trains a solid model with 5-fold cross-validation. task='auto' detects classification vs regression for you.

Try it yourself

Output

Press Run to execute this snippet.

predict()

predict(model, X) -> arrayRun here

Use a trained model on new rows.

Try it yourself

Output

Press Run to execute this snippet.

model.evaluate()

Model.evaluate() -> dictRun here

Read the honest, cross-validated scores of a fitted model.

Try it yourself

Output

Press Run to execute this snippet.

auto()

auto(df, target, explain_decisions=False, balanced=False) -> (model, report)

The teaching entry point: trains the best default model AND returns a report. With explain_decisions=True it narrates every step; with balanced=True it handles class imbalance.

Exampleruns locally after pip install

import breezeml

df = breezeml.datasets.wine()
model, report = breezeml.auto(df, "wine_class", explain_decisions=True)
print(report)

from_csv() · save() · load()

from_csv(path, target) · save(model, path) · load(path)

Train straight from a CSV file, then save and reload a model to disk with joblib.

Exampleruns locally after pip install

import breezeml

model = breezeml.from_csv("data.csv", "target")
breezeml.save(model, "model.joblib")
same = breezeml.load("model.joblib")

Classifiers

Predicting a category (spam or not, which species, which class). BreezeML ships 24 classifiers. Use classifiers.compare() to rank them all on your data, or call any one directly. Each returns a fitted model plus an honest cross-validated report.

All 24 classifiers

call as breezeml.classifiers.<name>(df, target). Marked * need the optional [boost] extra and run locally, not in the browser.

Model	Call	Good for
Logistic Regression	logistic	Fast, interpretable baseline. Always try this first.
Random Forest	random_forest	Robust all-rounder. Great default on tabular data.
Gradient Boosting	gradient_boosting	Strong accuracy by correcting its own mistakes.
Hist Gradient Boosting	hist_gradient_boosting	Fast boosting for larger datasets.
Extra Trees	extra_trees	Like random forest, more randomness, often faster.
AdaBoost	adaboost	Boosts weak learners; good on clean data.
Decision Tree	decision_tree	One readable tree of if/else rules.
K-Nearest Neighbors	knn	Predicts from the closest examples. No training.
SVM (RBF)	svm	Powerful non-linear boundaries on small/medium data.
Linear SVM	linear_svm	Fast linear margin classifier for many features.
MLP (neural net)	mlp	A small neural network for non-linear patterns.
Ridge Classifier	ridge	Regularized linear classifier, resists overfitting.
SGD Classifier	sgd	Scales to huge datasets via online learning.
Passive Aggressive	passive_aggressive	Online learner for streaming text/data.
LDA	lda	Linear discriminant analysis, elegant on Gaussian data.
QDA	qda	Quadratic version, curved boundaries.
Gaussian NB	gaussian_nb	Naive Bayes for continuous features. Very fast.
Multinomial NB	multinomial_nb	Naive Bayes for counts, classic for text.
Complement NB	complement_nb	Naive Bayes tuned for imbalanced text.
Bernoulli NB	bernoulli_nb	Naive Bayes for binary features.
Nearest Centroid	nearest_centroid	Assigns to the closest class average. Tiny + fast.
Bagging	bagging	Averages many models to cut variance.
XGBoostextra	xgboost	Kaggle-winning gradient boosting.
LightGBMextra	lightgbm	Very fast, memory-light boosting.

compare()

classifiers.compare(df, target) -> leaderboardRun here

The signature move: rank every classifier on the SAME cross-validation folds, then light the winner. Fair by construction. (The browser runs a fast subset; run locally for all 24.)

Try it yourself

Output

Press Run to execute this snippet.

Call one directly

classifiers.random_forest(df, target) -> (model, report)

Every classifier is a one-liner that returns a fitted model and an honest report. Swap the name to swap the algorithm.

Exampleruns locally after pip install

import breezeml

df = breezeml.datasets.iris()
model, report = breezeml.classifiers.random_forest(df, "species")
print(report)

quick_tune()

classifiers.quick_tune(df, target, algo='random_forest')

Tune the winner's hyperparameters over a small, sensible grid, no sprawling search.

Exampleruns locally after pip install

import breezeml

df = breezeml.datasets.wine()
best = breezeml.classifiers.quick_tune(df, "wine_class", algo="random_forest")

Regressors

Predicting a number (a price, a temperature, a score). BreezeML ships 24 regressors with the same compare() and one-liner API as classifiers.

All 24 regressors

call as breezeml.regressors.<name>(df, target). * need the [boost] extra.

Model	Call	Good for
Linear Regression	linear	The classic straight-line baseline.
Ridge	ridge	Linear + L2 penalty; resists overfitting.
Lasso	lasso	Linear + L1; also selects features (zeros them out).
Elastic Net	elastic_net	Blend of Ridge and Lasso.
Random Forest	random_forest	Robust non-linear default.
Gradient Boosting	gradient_boosting	High accuracy by correcting residuals.
Hist Gradient Boosting	hist_gradient_boosting	Fast boosting for bigger data.
Extra Trees	extra_trees	Extra-random forest, often faster.
AdaBoost	adaboost	Boosted stumps for smooth targets.
Decision Tree	decision_tree	One readable tree of rules.
K-Nearest Neighbors	knn	Averages the closest examples.
SVR	svr	Support vector regression for non-linear curves.
MLP (neural net)	mlp	Small neural network for complex shapes.
Huber	huber	Linear but robust to outliers.
Bayesian Ridge	bayesian_ridge	Ridge with uncertainty built in.
SGD	sgd	Scales to very large datasets.
Poisson	poisson	For counts (visits, calls, events).
Quantile	quantile	Predicts a percentile, not just the mean.
Theil-Sen	theilsen	Median-based, very robust to outliers.
RANSAC	ransac	Fits the inliers, ignores gross outliers.
Kernel Ridge	kernel_ridge	Ridge with a kernel for non-linearity.
Bagging	bagging	Averages many regressors to cut variance.
XGBoostextra	xgboost	Gradient boosting powerhouse.
LightGBMextra	lightgbm	Fast, light boosting.

regressors.compare()

regressors.compare(df, target) -> leaderboard

Rank all regressors on the same folds, scored by R2, MAE and RMSE.

Exampleruns locally after pip install

import breezeml

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

Clustering

Finding groups when you have NO labels (customer segments, anomalies, topics). Nine algorithms, each returning labels plus a quality score.

All 9 clusterers

call as breezeml.clustering.<name>(df).

Model	Call	Good for
K-Means	kmeans	Fast, round clusters when you know how many (k).
Agglomerative	agglomerative	Builds a hierarchy of nested groups.
DBSCAN	dbscan	Finds dense blobs of any shape; flags noise.
HDBSCAN	hdbscan	DBSCAN that picks the density for you.
Gaussian Mixture	gaussian_mixture	Soft, elliptical clusters with probabilities.
BIRCH	birch	Memory-friendly clustering for large data.
Spectral	spectral	Graph-based; great on non-convex shapes.
Mean Shift	meanshift	Finds clusters without setting k.
OPTICS	optics	Density clustering across varying scales.

clustering.kmeans()

clustering.kmeans(df, n_clusters=3) -> dict

Returns the cluster labels and a silhouette score (how well-separated the groups are).

Exampleruns locally after pip install

import breezeml

df = breezeml.datasets.iris().drop(columns=["species"])
res = breezeml.clustering.kmeans(df, n_clusters=3)
print("silhouette:", round(res["silhouette"], 3))

Honesty toolkit

A score is a claim. These tools test that claim against the ways models quietly lie, before production does. This is the heart of BreezeML.

audit()

audit(df, target, show=True) -> dictRun here

Scans for target leakage (a feature that 'knows' the answer), duplicate rows, ID columns, and class imbalance, before you waste time training on broken data.

Try it yourself

Output

Press Run to execute this snippet.

contamination()

contamination(train_df, test_df, show=True) -> dict

Checks whether rows leaked between your train and test sets, the sneakiest way to fool yourself with a great score.

Exampleruns locally after pip install

import breezeml

breezeml.contamination(train_df, test_df)

fairness.report()

fairness.report(model, df, sensitive='group')

Per-group accuracy, demographic parity, and a four-fifths-rule verdict, so you learn who your model is worse for.

Exampleruns locally after pip install

import breezeml

breezeml.fairness.report(model, df, sensitive="gender")

drift.check()

drift.check(model, new_df, threshold=0.2) -> dict

Measures how far new data has drifted from training data (PSI), flags unseen categories and out-of-range values. Runs live in every deployed API.

Exampleruns locally after pip install

import breezeml

breezeml.drift.check(model, new_df)

significance.mcnemar()

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

Is model A's 2% edge real or luck? McNemar's test and a paired cross-validated t-test give you a p-value instead of a hunch.

Exampleruns locally after pip install

import breezeml

breezeml.significance.mcnemar(model_a, model_b, df, "target")

conformal

conformal.conformal_classifier(model, df, target, alpha=0.1)

Distribution-free prediction sets with a guaranteed coverage level. Instead of one guess, you get 'the answer is in {A, B} with 90% coverage', honest uncertainty on every prediction.

Exampleruns locally after pip install

import breezeml

sets = breezeml.conformal.conformal_classifier(
    model, calib_df, "target", alpha=0.1
)

imbalance

imbalance.tune_threshold(model, df, target) · calibrate() · cost_report()

For rare-event problems (fraud, disease): summarize the imbalance, move the decision threshold to what you care about, calibrate probabilities, and cost out false positives vs negatives.

Exampleruns locally after pip install

import breezeml

breezeml.imbalance.summary(df["target"])
breezeml.imbalance.tune_threshold(model, df, "target", metric="f1")

Explain & understand

Open the black box: which features mattered, how they change the prediction, and a plain-English summary.

explain()

explain(model, df, target_col=None)Run here

One call for a full plain-English explanation of the model: top features, direction of effect, and caveats.

Try it yourself

Output

Press Run to execute this snippet.

permutation_importance()

explain.permutation_importance(model, df, target, n_repeats=5)

Shuffle each feature and see how much the score drops; a model-agnostic, trustworthy importance ranking.

Exampleruns locally after pip install

import breezeml

breezeml.explain.permutation_importance(model, df, "target")

partial_dependence()

explain.partial_dependence(model, df, target, feature)

Shows how the prediction changes as one feature moves, holding the rest fixed. The 'what-if' curve.

Exampleruns locally after pip install

import breezeml

breezeml.explain.partial_dependence(model, df, "target", feature="age")

features: select · pca · polynomial

features.select(df, target, k=10) · features.pca(df) · features.polynomial(df)

Pick the k most informative columns, compress with PCA, or expand with polynomial interactions, all one-liners.

Exampleruns locally after pip install

import breezeml

top = breezeml.features.select(df, "target", k=10)
reduced = breezeml.features.pca(df, n_components=0.95)

Export & deploy

Turn a trained model into something you can run anywhere. Zero lock-in.

export()

export(model, 'train.py') -> str

Writes a standalone scikit-learn script that reproduces your pipeline with no breezeml import. The ultimate no-lock-in guarantee.

Exampleruns locally after pip install

import breezeml

df = breezeml.datasets.iris()
model = breezeml.fit(df, "species")
breezeml.export(model, "train.py")

card()

card(model, path=None) -> strRun here

Generates an honest Markdown model card: data profile, metrics, decisions, and auto-detected caveats. Governance made easy.

Try it yourself

Output

Press Run to execute this snippet.

deploy()

deploy(model, out_dir='deployment') -> str

Emits a FastAPI app + Dockerfile + pinned requirements. Every deployed API ships /predict, /health and a live /drift endpoint.

Exampleruns locally after pip install

import breezeml

breezeml.deploy(model, "api/")
# -> main.py, Dockerfile, requirements.txt, model.joblib

to_onnx()

deploy.to_onnx(model, 'model.onnx')

Export to the ONNX open standard so your model runs in other languages and runtimes.

Exampleruns locally after pip install

import breezeml

breezeml.deploy.to_onnx(model, "model.onnx")

automl()

automl(df, target, time_budget=60)

Give it a time budget and it searches models and hyperparameters for you, then returns the best honest pipeline.

Exampleruns locally after pip install

import breezeml

best = breezeml.automl(df, "target", time_budget=60)

track & blend

track.log(model, report) · track.leaderboard() · blend(models)

Log every experiment to a local leaderboard, then blend your best models into an ensemble.

Exampleruns locally after pip install

import breezeml

breezeml.track.log(model, report, name="run-1")
breezeml.track.leaderboard()

Advanced tools

The library goes far beyond basic ML. These are one-liners for problems that usually need specialist packages.

causal inference

causal.estimate_ate(df, treatment, outcome) · causal.uplift(...)

Not just correlation, causation: estimate the average treatment effect of an intervention, and model who responds to it (uplift).

Exampleruns locally after pip install

import breezeml

breezeml.causal.estimate_ate(df, treatment="promo", outcome="spend")

conformal regression

conformal.conformal_regressor(model, df, target, alpha=0.1)

Prediction intervals with guaranteed coverage: 'the price is 40k to 55k, 90% of the time'.

Exampleruns locally after pip install

import breezeml

lo, hi = breezeml.conformal.conformal_regressor(model, calib, "price", alpha=0.1)

anomaly detection

anomaly.compare(df) · isolation_forest · local_outlier_factor · one_class_svm

Find the weird rows with four methods, or compare them all at once.

Exampleruns locally after pip install

import breezeml

breezeml.anomaly.isolation_forest(df, contamination=0.05)

time series

timeseries.make_features(...) · timeseries.forecast(...) · timeseries.compare(...)

Build lag/rolling features, compare forecasting models with proper time-aware splits, and forecast ahead.

Exampleruns locally after pip install

import breezeml

feat = breezeml.timeseries.make_features(df, date_col="date", target="sales")
breezeml.timeseries.forecast(df, date_col="date", target="sales", horizon=30)

survival analysis

survival.kaplan_meier(df, duration_col, event_col)

Time-to-event modeling: how long until churn, failure, or recovery, with censoring handled correctly.

Exampleruns locally after pip install

import breezeml

breezeml.survival.kaplan_meier(df, "tenure_months", "churned")

multi-output & recommenders

multi.multi_label(df, targets) · recommend.collaborative_filter(...)

Predict several labels at once, or build a collaborative-filtering recommender from a ratings table.

Exampleruns locally after pip install

import breezeml

breezeml.multi.multi_label(df, targets=["tag_a", "tag_b"])

active & semi-supervised

active.query(...) · semisupervised.self_train(...) · autofeat.engineer(...)

Label smartly (active learning), learn from mostly-unlabeled data (self-training), and auto-engineer new features.

Exampleruns locally after pip install

import breezeml

next_to_label = breezeml.active.query(model, unlabeled_df, n=10)
breezeml.autofeat.engineer(df, "target")

text features

text.embed(df, text_columns)

Turn free-text columns into numeric embeddings you can feed to any model (needs the sentence-transformers extra).

Exampleruns locally after pip install

import breezeml

df2 = breezeml.text.embed(df, text_columns="review")

The Zen garden

When the metrics are honest and the work is done, rest. Yes, these are real functions.

zen() · haiku() · fortune() · sensei()

breezeml.zen()

A 60-second breathing pause, a haiku about your model, a fortune for your next step, or a word of wisdom from the sensei.

Exampleruns locally after pip install

import breezeml

breezeml.haiku()
breezeml.fortune()
breezeml.sensei()

guide()

breezeml.guide()

Lost? guide() prints a friendly map of the whole library and suggests the next step for your task.

Exampleruns locally after pip install

import breezeml

breezeml.guide()