<!-- mcp-name: io.github.venomez-viper/breezeml --> <div align="center"> <img src="https://raw.githubusercontent.com/venomez-viper/breezeml/main/assets/breezeml_banner_1778130992461.png" alt="BreezeML Banner" width="800"/>

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.

<br/>

<br/>

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

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

</div>

---

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:

1. 4 dependencies. Always. Core installs with only scikit-learn, pandas, numpy, joblib, CI-enforced. No dependency hell, ever.
2. Zero lock-in. export() hands you a standalone sklearn script reproducing your exact pipeline, with no breezeml import. Graduate anytime.
3. It teaches you. explain_decisions=True narrates every pipeline choice in plain English, and card() writes an honest model card with auto-detected caveats.
4. 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 lead