Skip to main content

EBaMl

EBaMl explains an Explainable Boosting Machine (EBM) in plain words. An EBM is a glass-box model for tabular data: it adds one learned graph for each feature, so a person can read how each feature moves a prediction. EBaMl gives the graphs and the predictions of an EBM to a large language model (LLM), and returns text that a data scientist, a customer or a regulator can read.

The graph of income in an EBM of synthetic loan data. The score goes up from about -1.6 at low incomes, crosses zero
near 40,000, and stays near +1.3 above 55,000.

  • Describe a model. describe_graph and describe_ebm turn each graph, and the whole model, into a description.
  • Explain one prediction. explain_instance gives a local explanation: what must change to flip the decision, which inputs settle it, and how certain it is. Python computes these facts from the scores of the EBM, and the LLM only puts them in words.
  • Edit a model. EditSession changes the graphs to meet a requirement of the business, with a report and a history.
  • Give the model to an agent. ebaml-mcp is an MCP server with tools to read, explain and edit the model.
  • Use any LLM. The default is the free router of OpenRouter. Pass model= to use OpenAI, Anthropic, Gemini, a local Ollama server or another provider. The LLM gets the graph text and, for a local explanation, the values of the input. To keep the data on your machines, use a local model.

EBaMl is based on TalkToEBM. Python reads the EBM, and BAML holds the prompts and the LLM clients.

Why an EBM, and why EBaMl

Why an EBM instead of XGBoost? A model of boosted trees, such as XGBoost, is a black box: tools such as SHAP estimate why it made a prediction. An EBM is a sum of one score for each feature (and for a few pairs of features), so the contribution of each term is exact, and a person can find a wrong pattern in a graph and edit it. The InterpretML paper says that an EBM "can be as accurate as many blackbox models" (Nori et al., 2019). The fit is somewhat slower. What is an EBM? has the details and the sources.

What does EBaMl add to interpret? interpret fits the EBM, draws its graphs and gives the contribution of each feature to a prediction. EBaMl adds the words: a description of each graph and of the model, and a local explanation that a customer can read. It also adds the counterfactual and the sufficient reason of a prediction, edits of single bins with a history, and the MCP server. Why EBaMl? shows one example from the model to the words.

Quick start

Install the package, and set a free OpenRouter key in your shell:

pip install ebaml
export OPENROUTER_API_KEY=sk-or-...

Fit an EBM, and ask for a description of the graph of its first feature:

from interpret.glassbox import ExplainableBoostingClassifier
from sklearn.datasets import load_breast_cancer

from ebaml import DescribeGraphRequest, describe_graph

X, y = load_breast_cancer(return_X_y=True, as_frame=True)
ebm = ExplainableBoostingClassifier(interactions=0).fit(X, y)
print(describe_graph(DescribeGraphRequest(ebm, feature_index=0)))

The free router picks a model for each request, so the text changes from run to run.

Supported models

Feature Binary classifier Regressor Multiclass classifier Interactions
Graph descriptions (describe_graph) ✅ ✅ ✅ ⚠️
Model summary (describe_ebm) ✅ ✅ ✅ ⚠️
Graph text (EBMGraph) ✅ ✅ ✅ ⚠️
Local explanations (explain_instance) ✅ ✅ ✅ ❌
MCP server (ebaml-mcp) ✅ ✅ ✅ ⚠️
Editing (EditSession) ✅ ✅ ✅ ⚠️

✅ supported. ⚠️ partly supported: the main effects are described, and the interaction terms are skipped. describe_graph and describe_ebm name them in the prompt, so the description says that it leaves them out, and they log an interactions_skipped warning. ❌ not supported yet. Full support is on the roadmap.

Learn more

The documentation holds the guides:

Page Read it to
What is an EBM? Learn what an EBM is, and why a team uses one.
Why EBaMl? See one graph and one prediction go from the model to the words.
Setup Install from PyPI or from a source checkout, set an API key, and fix setup errors.
Usage Describe a graph or a model, and read the options and the errors.
Local explanations Explain one prediction, and learn what each guarantee means.
Editing a model Change the graphs of an EBM to meet a requirement of the business.
Choosing the model Use another LLM provider with model=.
MCP server Give an EBM to an agent, and chat with it in the terminal (ebaml-chat).
Notebooks Run each feature step by step in a marimo notebook.
API reference Read every public function and class.

Contributing

Read CONTRIBUTING.md and the development guide. The roadmap lists the planned releases. EBaMl is free software under the MIT license.

Metadata

Release files for ebaml 0.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ebaml 0.12.0
File Size Uploaded Provenance Actions
ebaml-0.12.0.tar.gz 1.8 MB Without provenance Details for ebaml-0.12.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ebaml 0.12.0
File Interpreter ABI Platform Actions
ebaml-0.12.0-py3-none-any.whl Python 3 none any Details for ebaml-0.12.0-py3-none-any.whl

Total release size: 3.7 MB

Release files / ebaml-0.12.0.tar.gz

Download URL ebaml-0.12.0.tar.gz
Size 1.8 MB
Tags Source
SHA-256 checksum
How to use checksums
bb88366ce3a14d1ed62f65096d1b88c27e46b64df23b737fd78249efdc1bf2e8
BLAKE2b-256 checksum
How to use checksums
eae7215f8eb8460ef60c9738997900fabba38049dc536a7806cd9790e43c515d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / ebaml-0.12.0-py3-none-any.whl

Download URL ebaml-0.12.0-py3-none-any.whl
Size 1.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
195e842e9787f44b1901f42314e916cd0767daa890f9df697775be2399554c82
BLAKE2b-256 checksum
How to use checksums
e9b04d5daa73aa4e09931e01407936ec031e7addb7824261486cef81d62b3b4c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for ebaml 0.12.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.12.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page