BuildML

BuildML is a Python machine-learning library. One object holds your data, the train / validation / test split, preprocessing, the model, and the history of what you ran. That object is called a Session. The core path is classification and regression. The same object also runs forecasting, AutoML, fairness, recommenders, RAG, graphs, NLP, Torch, and the other domains in this repo. If you try to prepare or fit before a split, it stops you.

You choose the estimator. BuildML coordinates its data preparation, training, evaluation, and saved artifacts through the Session.

A Session is a unified, stateful ML lifecycle. Enforced leakage safeguards, fold-local preprocessing, contextual teaching, workflow guidance, checkpointing, and auditable export live on that same object.

pip install buildml

Python 3.10 through 3.13. This repository contains BuildML 2.6.3. pip install buildml installs the latest published stable release from PyPI. Wheels 2.4.0a3–2.6.0 cannot import buildml; use >=2.6.1. The public entry point is buildml.Session.

import pandas as pd
from sklearn.linear_model import LogisticRegression

from buildml import Session

frame = pd.DataFrame(
    {
        "age": [21, None, 35, 40, 29, 33, 52, 47],
        "income": [40, 55, 60, 80, 50, 70, 90, 65],
        "approved": [0, 1, 0, 1, 0, 1, 1, 0],
    }
)

session = Session.ingest(frame)
session.set_roles(
    {"age": "feature", "income": "feature", "approved": "target"}
)
session.split(test_size=0.25, stratify=True, random_state=42)
session.impute(strategy="median")
session.scale(method="standard")
session.fit(LogisticRegression(max_iter=500), task="classification")

print(session.evaluate(partition="test").metrics)

Roles say how each column may be used. split creates the holdout. impute and scale learn from training rows and apply frozen numbers everywhere else. evaluate scores the partition you name.

When rows are not interchangeable (the same customer twice, a time order), use group_split, time_split, or pass memberships you designed yourself with inject_split.

Docs: buildml.readthedocs.io

What the Session protects

Fit-capable preparation and fit learn from training rows. Validation and test receive the frozen plans. Cross-validation and search draw folds from the training partition only. Search does not use the test holdout to rank candidates.

For cross-validation, start a separate Session with unprocessed data. This example uses a larger bundled dataset so each fold has enough examples:

from sklearn.tree import DecisionTreeClassifier
from sklearn.datasets import load_breast_cancer
from buildml.preprocess import PreprocessRecipe

cv_frame = load_breast_cancer(as_frame=True).frame
cv_session = Session.ingest(cv_frame)
cv_session.set_roles({**{c: "feature" for c in cv_frame if c != "target"}, "target": "target"})
cv_session.split(test_size=0.2, stratify=True, random_state=42)
recipe = PreprocessRecipe(impute="median", scale="standard")
cv = cv_session.cv_score(
    LogisticRegression(max_iter=500),
    cv=5,
    preprocess=recipe,
)
search = cv_session.grid_search(
    DecisionTreeClassifier(random_state=0),
    param_grid={"max_depth": [2, 4, 6], "min_samples_leaf": [1, 5]},
    cv=5,
    preprocess=recipe,
)

Pass a PreprocessRecipe when encoding, binning, or scaling should be refit inside each fold, on data that has not already been prepared on the whole training partition. If you already ran Session-global impute / encode / scale, CV and search refuse by default. That is deliberate. Opt in with allow_session_global_preprocess=True only when you mean to accept leakage-biased scores.

The Session also remembers the run. You can ask what a step means, what is blocked, or write a walkthrough for someone else.

session.explain("split")           # this Session, right now
session.learn("leakage")           # the idea, in reading order
session.workflow()                 # done / available / blocked

beginner is the default reading level. It does not assume machine-learning vocabulary. Teaching copy explains the contract. It does not inspect your data or certify that a choice fits the domain.

Where to go next

Classical session.fit / session.evaluate stay first-class. Domain work uses namespaced facades (session.anomaly.*, session.forecast.*, …). Flat domain aliases still run and warn until BuildML 3.0. The stability note is in docs/stability.md.

Optional extras

pip install buildml stays light: numpy, pandas, pyarrow, scikit-learn. Plotting, Torch, the local EDA app, and industry backends are extras. Core RAG supports hashing embeddings, BM25, and a NumPy index; install buildml[rag] for sentence-transformer embeddings and reranking. Install what the job needs. The installation guide lists them by job.

pip install "buildml[torch]"
pip install "buildml[dashboard]"

buildml[production] is a best-effort bundle of domain depth. It is not a promise that every nested industry wheel installs on every machine. On Python 3.13, especially Windows, some pins are skipped when upstream wheels are missing. Ask the domain (session.automl.capability_matrix()) or, from a checkout, run python scripts/probe_industry_extras.py.

Save, reload, and trust

A checkpoint stores the data workflow (table, roles, split, history, optional preprocess plans). A pipeline bundle stores fitted plans and the estimator. They do not embed each other.

session.checkpoint_save("artifacts/checkpoint")
restored = Session.checkpoint_load("artifacts/checkpoint", trusted=True)

session.save_pipeline("artifacts/pipeline", evaluate_partition="test")

Pickle / joblib / torch loaders default to trusted=False and refuse until you pass trusted=True for an artifact you created or fully trust. A hash in the manifest can catch tampering after save. It cannot make an attacker-controlled file safe. Prefer JSON sidecars, parquet, or checkpoint_load(..., data_only=True) when provenance is unclear.

The AI operator (buildml[ai]) is propose, then confirm, then execute, with a closed tool list. Pattern checks on prompts are a best-effort layer, not a proof against injection. Details live in artifacts and AI operator safety.

Proof suite

proofs/ is end-to-end evidence that Session domains run with explicit splits and holdout metrics.

From a source checkout, after the extras that project needs:

python -m proofs._lib.run_all --tier all
python proofs/loan-approval-classical/script.py

Domain examples demonstrate individual workflows. Composition examples combine several Session domains. Where a comparison implementation exists, it writes comparison.json on the same split. These are runnable examples, not hosted applications supplied by BuildML.

BuildML 1.x legacy boundary

BuildML 1.x (SupervisedLearning and the old module layout) lives under buildml/_legacy/ for reference only. It is not imported from the 2.x package root. There is no compatibility shim that re-exports 1.x APIs from import buildml.

If you still need that line: pip install "buildml==1.0.9".

Author and license

Leonard Onyiriuba: LinkedIn · leonard.c.onyiriuba@gmail.com

Issues: GitHub

Apache License 2.0.