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.
- Describe a model.
describe_graphanddescribe_ebmturn each graph, and the whole model, into a description. - Explain one prediction.
explain_instancegives 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.
EditSessionchanges the graphs to meet a requirement of the business, with a report and a history. - Give the model to an agent.
ebaml-mcpis 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.