Skip to content

Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.12.0] - 2026-11-22

Changed

  • Each page of the documentation has its own description and a title that names it, and the site loads the system fonts and no stylesheet from Google Fonts.
  • The site no longer publishes the implementation plans of the milestones. ROADMAP.md links them on GitHub.

Fixed

  • The active link of the nav and the labels of the API reference have enough contrast for WCAG 2.2 AA in the light and the dark color scheme.
  • A frame that holds the focus, such as an embedded notebook or paper, shows a focus ring, and the hidden "Back to top" button no longer takes the focus.
  • The headings of the pages Setup, Usage and Choosing the model no longer skip a level.
  • Each embedded paper has a link to its PDF next to the frame, for readers whose browser does not show the frame.
  • The graph of income has a fixed size, so the home page does not move when the image loads.

[0.11.0] - 2026-11-21

Added

  • The documentation has the pages "What is an EBM?", which defines an EBM, a glass-box model, a graph and a local explanation, and "Why EBaMl?", which follows one graph and one prediction from the model to the words.
  • The home page of the documentation sends each reader to a first page: a reader new to EBMs, a person who explains decisions, a user of the API and a developer of an agent.

Changed

  • The README is a short introduction with a quick start that runs as written. The setup, the usage, the providers, the notebooks and the development guide are on the documentation site.

[0.10.0] - 2026-11-21

Added

  • EditSession and every edit, constraint and report work on multiclass classifiers. An edit of a graph takes class_label: the class to change, or None for every class. Monotonize serves multiclass models, which monotonize of interpret refuses.
  • The report of an edit names the class of each changed score, and ClassShift gives the shift of the weighted mean and of the intercept of each class.
  • edit_effect gives MulticlassMetrics for a multiclass model: accuracy, balanced accuracy, the mean one-versus-rest ROC AUC and the confusion matrix of all classes. The row counts name the moves between classes.
  • The MCP edit tools edit multiclass models: list_bins gives the score of each class, and the edit and constraint objects take class_label.

Changed

  • load_gamchanger and save_gamchanger raise UnsupportedModelError with the fix steps for a multiclass model, because a .gamchanger file holds one score in each bin.

[0.9.1] - 2026-11-21

Changed

  • The options of an edit, a constraint, a history row and a graph are StrEnum members: Direction, MonotoneDirection, AlignTarget, HistoryKind, BudgetLevel and FeatureType. The functions still accept the plain text ("increasing") and turn it into the member. A wrong text raises InvalidOptionError.
  • The tool get_graph and the option --transport of the server take the enums Normalization and Transport. The schema of get_graph lists the values of normalization through a $ref.
  • The help of the edit tools lists the allowed values of each option.

[0.9.0] - 2026-11-21

Added

  • The editing notebook shows the tools of 0.9.0: business constraints and their repairs, an empty bin above the data, the effect of the edits on the data and on a subgroup, and a .gamchanger file that it saves and reads back.
  • 0.9.0 completes GAM Changer parity. The releases 0.8.3 to 0.8.6 hold its parts: the business constraints, the edits that change the bins, the effect of an edit on data and on subgroups, and .gamchanger files.

[0.8.6] - 2026-11-20

Added

  • save_gamchanger writes the original model and the applied edits of a session as a .gamchanger file that the GAM Changer widget opens. The result names each part of the session that the file cannot hold.

  • load_gamchanger reads any new bins of a commit, so it reads back the files that save_gamchanger writes after SplitBin and ExtendRange. It refuses only a commit that narrows the range of a feature.

[0.8.5] - 2026-11-19

Added

  • The effect of an edit on rows counts the rows whose class changes in each direction (rows_to_positive_class and rows_to_negative_class), in the edit report of the MCP tools too.

  • edit_effect measures the effect of the edits on data, as the Metric Panel of GAM Changer does: the metrics of the original model, the model before the last edit and the current model, for all rows, the rows that the last edit changes, and a Subgroup.

  • affected_profile shows which subgroups the last edit reaches: for each other feature, the mix of its bins among the affected rows and among all rows, with the l1 distance.

  • The MCP tools get_edit_effect and get_affected_profile show the effect of the edits on the rows of --data. The server flag --labels names the column with the true outcome, from which the tools compute the metrics.

[0.8.4] - 2026-11-18

Added

  • The edits SplitBin, Rebin and ExtendRange change the bins of a continuous feature. A split and an extension change no prediction, so a later edit can give the new bins their own scores.

  • load_gamchanger loads the equal-interpolate and equal-regression commits of GAM Changer as a Rebin followed by the scores of the commit.

Fixed

  • An edit built from a numpy number, such as a bound of feature_bounds_, joins the history. The history JSON refused such a number.

[0.8.3] - 2026-11-18

Added

  • The edits Clip and LimitSteps keep the scores of a graph in a range and limit the step between neighbour bins.
  • The selection EveryBin selects the missing bin, every real bin and the unseen bin of a feature.

  • Business constraints Monotone, MaxStep, Bounded, FixedScore and Unused. check_constraints finds the constraints that a model breaks, names the bins that break each one, and gives the edit that repairs it.

  • The MCP tool check_constraints finds the business constraints that the model breaks. Each violation holds the edit that repairs it, in the form that preview_edit and apply_edit take.

  • The edit AssignScores sets each selected score to its own value.

  • load_gamchanger reads a .gamchanger file of GAM Changer and builds the edits of the newest commit of each feature. apply_gamchanger applies them to an EditSession, with the GAM Changer description as the reason. The loader refuses a file of another model, and a commit that changes the bin edges.

Fixed

  • The descriptions of the MCP edit tools give the real default of each field. They showed "whole graph" as the default of the bounds of ValueInterval.

[0.8.2] - 2026-11-14

Changed

  • EBaMl requires baml-bridge 0.25.2 and the BAML toolchain 0.25.

[0.8.1] - 2026-11-14

Changed

  • The maintenance scripts live in the packages scripts/architecture, ignores, release, ci, mutation, docs and llm. Run them as python -m scripts.<group>.<name>, for example python -m scripts.architecture.layout.

[0.8.0] - 2026-11-14

Added

  • The MCP server has edit tools: list_bins, preview_edit, apply_edit, undo_edit, redo_edit, checkout_edit and list_edits. An agent edits a copy of the model with a written reason for each edit. The tools call no LLM.
  • preview_edit and apply_edit count the rows of --data that an edit changes. They say in one field when the server has no data.
  • save_model saves the edited model and its history after the person confirms the edits through MCP elicitation. If the client cannot ask, it saves and marks each edit as not reviewed by a person. --output-dir turns it on.
  • --edits replays the history file of an earlier session, so the work goes on. The server refuses a history that started from another model.
  • The read tools and explain_prediction take revision (original, current or the id of a commit) and report the revision that they read and the number of edits that the head holds.
  • EditSession.revision_info, EditSession.history_table(pending_only=True) and the fields base_revision and revision of EditReport.

Changed

  • BREAKING: list_features returns an object with session and features, and each JSON result of the read and explain tools has a session field. get_graph starts with a line that names the revision.
  • BREAKING: ModelStore keeps an EditSession in session, and the model of the loaded file is original. explain_prediction of ebaml.mcp.explain_tools takes a PredictionRequest.
  • describe_model keeps its text for the revision that it describes, so an edit never leaves a description of the model before the edit.
  • The mcp extra needs pydantic, which the confirmation of a save uses.

[0.7.2] - 2026-11-13

Changed

  • BREAKING: The result classes of the local facts (Change, CompletionStep, Counterfactual, SufficientReason, LocalFacts, LocalOptions, Prediction, Contribution) moved from ebaml.local.facts to ebaml.local.fact_types. Import them from ebaml, as in from ebaml import LocalFacts. compute_local_facts stays in ebaml.local.facts.

[0.7.1] - 2026-11-13

Added

  • ebaml-mcp and ebaml-chat read the --data file as Parquet or CSV. They detect the format from the first bytes of the file, not from its extension. Parquet keeps the type of each column, so the docs and examples use it.
  • A --data file that is empty, is cut off, or is neither Parquet nor UTF-8 CSV raises DataFileError with the file name and the fix.

[0.7.0] - 2026-11-13

Added

  • EditSession and the edits Shift, SetScores, Align, Monotonize, Interpolate, FitLine, Scale, ZeroTerm, Recenter, RemoveTerms and RemoveFeature change the graphs of a fitted binary classifier or regressor, as the tools of GAM Changer do. The edited model keeps its bagged scores and standard deviations in step with the scores, so predict_with_uncertainty, explain_global, EBMGraph.from_ebm and skops work on it.
  • The selections Bins, Categories, ValueInterval, WholeGraph, MissingBin and UnseenBin name the bins of an edit. An edit reaches the missing bin and the unseen bin too.
  • EditSession gives a report for each edit (preview, apply), undo, redo, checkout, a history table with a reason and a review flag for each edit, and a replayable JSON history (to_json, EditSession.replay).
  • EditSession.save writes the edited model with skops.io and its history next to it. It needs a message, refuses unreviewed edits, and never overwrites a file.
  • Several threads can share one session. A call that changes the head takes expected_revision and raises StaleRevisionError if the head differs.
  • The new documentation page "Editing a model" and the notebook notebooks/model_editing.py.

[0.6.9] - 2026-11-11

Added

  • MinimalityStatus says why a counterfactual or a sufficient reason is, or is not, known to be the smallest set: SORTING_PROOF, SOLVER_PROOF, AT_LOWER_BOUND or UNPROVED. MinimalityStatus.is_smallest is false only for UNPROVED.
  • EBMDescription holds the description of an EBM (text) and the names of what it leaves out (skipped_terms and skipped_features).

Changed

  • BREAKING: describe_ebm returns an EBMDescription and not a str. Use its field text where you used the string, for example as global_explanation of explain_instance.
  • BREAKING: Counterfactual.minimum, SufficientReason.minimum and Cover.minimum are now minimality, a MinimalityStatus and not a bool. Read minimality.is_smallest for the old meaning. The is_smallest_set key of the facts for the prompts is unchanged.

[0.6.8] - 2026-11-11

Added

  • LocalFacts has two new fields, min_support and n_samples, so the facts carry the options that they hold under.
  • sample_size_word gives the word (large, moderate, small) that a layperson reads for the size of the sample of the completions.

Changed

  • BREAKING: Audience has three new abstract methods: guarantee, support and sample. An audience that subclasses Audience itself must add them. A subclass of Layperson or DataScientist needs no change. LocalFacts needs min_support and n_samples when you build it yourself.
  • describe_ebm and describe_graph tell the LLM which parts of the model the description leaves out: the interaction terms, and the features that exclude or remove_terms left without a graph. The text of the description then names them. describe_ebm logs a features_skipped warning for such features.
  • The BAML functions describe_graph_cot, summarize_ebm and describe_ebm accept omitted_terms, and the last two accept omitted_features. Both default to an empty list.

Fixed

  • The local explanation prompts claim a condition only when the facts state it. With confidence_level=0 they do not say that a flip or a guarantee survives the uncertainty of the model. With min_support=0 they do not say that rare values were left out. They tell the LLM the size of the sample of the completions, and they limit the robust flip to the changed features.
  • The docstring of ebaml.local.facts and the guide name the uncertainty model of each claim. A counterfactual moves only the scores of the changed features. The text said that every score moves.
  • The docstrings of Counterfactual and compute_local_facts, the guide and the MCP tool text say that a set is the smallest only when minimum is true, and that multiclass classifiers work. The guide showed an error for a multiclass classifier that the code does not raise.
  • The docstring of Prediction.score says that the class score of a multiclass classifier uses the scores centred over the classes, as the graphs do.
  • The guide and the docstring of the completions name the assumptions of the estimate: independent inputs, the training weights of every bin, the fitted scores and a fixed seed. A share can fall when an input becomes known.

[0.6.7] - 2026-11-10

Added

  • DescribeGraphRequest, DescribeEBMRequest and ExplainInstanceRequest hold the input of describe_graph, describe_ebm and explain_instance. Import them from ebaml.

Changed

  • BREAKING: describe_graph, describe_ebm and explain_instance take one request object and no other argument. Wrap the old arguments in the matching request: describe_ebm(DescribeEBMRequest(ebm, model="openai/gpt-4o-mini")). The fields keep the names, the order and the defaults of the old arguments, and graph, prompt, local, model and language stay keyword-only.

[0.6.6] - 2026-11-09

Added

  • describe_ebm(ebm, progress_bar=True) shows a progress bar on the error stream, with one step for each feature and one for the summary. If the stream is not a terminal, the bar writes one line for each step.
  • run_task(..., progress=True) shows a progress bar of the questions of a benchmark task. benchmark/run.py shows a bar by default. Use --no-progress to turn it off.

[0.6.5] - 2026-11-09

Added

  • The ebaml-chat command: a chat in the terminal with an agent that explains an EBM. Ask about the model or about one row of the data, and ask follow-up questions. The server starts once and stays up for the whole chat.
  • chat_with_mcp and chat_with_tools in BAML, and ebaml.llm.descriptors.chat_with_mcp in Python, for the same chat.

[0.6.4] - 2026-11-09

Changed

  • Internal loops in graph simplification, local explanations and the MCP model summary use enumerate and array conversion in place of index loops. The output stays the same.

[0.6.3] - 2026-11-09

Added

  • explain_with_mcp in BAML: an agent that starts ebaml-mcp, lets a language model call its tools, and returns the report with the list of tool calls. explain_with_tools runs the same loop on tools that you supply.

[0.6.2] - 2026-11-09

Changed

  • Local explanation prompts no longer overclaim. A failed counterfactual search says that no realistic change flips the prediction. A missing sufficient reason says that the search found none. Completion shares may fall as inputs become known.

[0.6.1] - 2026-11-09

Added

  • LocalOptions.search chooses the algorithm that solves the covering problems of the sufficient reason with several margins and of the counterfactual of a chosen class: MipCover (the default: branch and bound in a MIP solver, with stop=Stop.OPTIMAL or Stop.FIRST and a time_limit), LocalSearchCover (a seeded local search from the greedy set) or GreedyCover. The last two need no MIP solver.
  • MipBackend is the protocol of the optimization library behind MipCover and the lower bound. OrToolsBackend runs OR-Tools with HiGHS, SCIP or CP-SAT (OrToolsSolver). Another library plugs in as a class with the same solve method.
  • SufficientReason.lower_bound and Counterfactual.lower_bound give the fewest inputs that any set needs, from the LP relaxation. A set whose size equals the bound is marked as the smallest set.
  • Audience.lower_bound decides whether the facts give the lower bound: DataScientist writes smallest_possible_number_of_changes and smallest_possible_number_of_features, and Layperson leaves them out. The prompts tell the LLM that it may state the gap when the set is not proved smallest.
  • SearchLimitError tells that a solver ended with no set of changes for a chosen class and no proof that none exists, and names the fix.

Changed

  • BREAKING: LocalOptions.reason_search is replaced by LocalOptions.search, and Counterfactual and SufficientReason have the required field lower_bound.
  • The counterfactual of a chosen class is the smallest set of changes over every choice of bins when the solver proves it, and is_smallest_set is then true.
  • BREAKING: Audience has the abstract method lower_bound, so a custom audience must define it.
  • When is_smallest_set is false, the prompts tell the LLM to describe the set without a word about its size, in place of calling it minimal.
  • The package depends on ortools, and the lock moves protobuf to 6.33.

Removed

  • BREAKING: ebaml.local.reason_search with ReasonSearch, Minimal, ExactOrMinimal and Selection. Use a CoveringSolver in LocalOptions.search.

[0.6.0] - 2026-11-08

Added

  • LocalOptions.target_class asks, for a multiclass classifier, for the changes after which a chosen class is the predicted class. reason_search chooses the features. The result is never marked as the smallest set, and it has no proof.

Changed

  • The counterfactual prompt tells the LLM when the set of changes is not the smallest, and that a flip of a class means that another class becomes the predicted class. The counterfactual facts have the key is_smallest_set, and the key minimum_number_of_changes is now number_of_changes.
  • Counterfactual.minimum is false for the counterfactual of a chosen target class.

[0.5.2] - 2026-11-08

Added

  • explain_instance, compute_local_facts and the MCP tool explain_prediction explain a prediction of a multiclass classifier without interactions. The decision is the predicted class. The counterfactual is the fewest changes after which another class has a higher score, and the sufficient reason keeps the class against every other class. LocalOptions.reason_search chooses the search of the sufficient reason. The Lean proof of these facts is not done yet.
  • OutputKind.CLASS_PROBABILITY names the output of a multiclass classifier. The texts for the data scientist call the score of the predicted class class_score.

[0.5.1] - 2026-11-07

Changed

  • The mcp extra requires mcp>=2.3.0, and ebaml-mcp runs on the MCPServer class of mcp 2. The tool names and argument schemas are the same.

  • The lower bounds of the dependencies are the releases that the tests cover: narwhals>=2.28.0, pandas>=3.1.0, and, for the mcp extra, cyclopts>=5.3.2, joblib>=1.6.0 and polars>=2.1.0.

Security

  • The mcp extra and the project environment hold mcp 2.3.0 and the fixed opentelemetry releases, because the dependency overrides that held semgrep's old pins are gone.

[0.5.0] - 2026-11-07

Added

  • A Lean proof and a paper cover the local explanations of regressors: the shift of the intercept, the counterfactual of the answer "inside an interval", and the two searches of the sufficient reason (Minimal and ExactOrMinimal). The "Proof of the local explanations" page states what the proof shows and what it leaves out.

Fixed

  • A fresh pip install ebaml no longer installs a baml-bridge that rejects the generated baml_sdk with a version skew error. ebaml now requires baml-bridge==0.23.0, the version of the toolchain that generates the SDK.

  • The wheel and the source distribution no longer contain the .gitignore file that baml generate writes into baml_sdk.

  • pip install "ebaml[mcp]" no longer installs mcp 2.x, which has no FastMCP and made ebaml-mcp fail at start-up. The mcp extra now requires mcp>=1.30.0,<2.

[0.4.4] - 2026-11-07

Added

  • explain_instance and compute_local_facts explain a prediction of a regressor. LocalOptions(decision=...) sets the question about the predicted value: Threshold(value), or Interval(low, high) for a prediction below or above the interval. The default asks whether the value is above the average prediction. The sufficient reason and the counterfactual of a regressor have no proof yet, and an interval that contains the prediction raises UnsupportedModelError.
  • The MCP tool explain_prediction explains a regressor.

  • A regressor can explain the answer "inside" of Interval(low, high). LocalOptions.reason_search chooses how to find the sufficient reason of such a decision: Minimal() (the default) returns a set from which no input can be removed, and ExactOrMinimal() returns the smallest set up to a limit on the number of features.

  • The sufficient reason text says whether the set is the smallest or only minimal, and the prompt tells the LLM to use the matching word.

Changed

  • BREAKING: Audience.class_output and Audience.margin take the OutputKind of the model as a second argument. A custom audience must add it. Prediction has two new fields, threshold and output_kind, and points_towards reads the threshold.
  • The error for a multiclass classifier says: "Local explanations need a binary classifier or a regressor."
  • The local prompts tell the LLM that a prediction can be a number, and the layperson guidance allows the predicted value and the limits of the question.

  • BREAKING: Interval is open at the low end and closed at the high end, as Threshold is. The answers are "at most low", "above low and at most high" and "above high". Side holds a tuple of Margin objects in place of one sign and one threshold.

[0.4.3] - 2026-11-06

Added

  • ebaml-mcp takes --host and --port for the streamable-http transport. The defaults are 127.0.0.1 and 8000.

[0.4.2] - 2026-11-06

Fixed

  • ebaml-mcp writes its log events to stderr. Before, they went to stdout and could corrupt the JSON-RPC stream of the stdio transport.
  • The max_tokens argument of the get_graph tool takes effect. The server merges the bins of a continuous graph until its estimated size fits the budget, and it raises an error if the graph cannot fit.

[0.4.1] - 2026-11-05

Added

  • ebaml-mcp --model loads a skops file as well as a joblib file, and reads the format from the file. The server trusts only the EBM classes, so a skops file runs no code.

Changed

  • The MCP server reads the --data CSV file with polars, and ModelStore accepts a frame of any library that narwhals supports (pandas, polars, pyarrow). ebaml no longer imports pandas outside the type of pd.NA.

  • ebaml-mcp and benchmark/run.py use cyclopts for the command line. The flags stay the same, and the mcp extra installs cyclopts. A wrong value now gives a usage error with the list of valid choices.

[0.4.0] - 2026-11-05

Added

  • The ebaml-mcp command serves a fitted EBM as an MCP server (install the mcp extra). An agent can read the model and its graphs, and explain one prediction with the exact local facts, with no LLM key. With --llm, it can also ask for LLM descriptions.

[0.3.3] - 2026-11-03

Added

  • ebaml now exports the functions, the option classes, the local-explanation facts and the audience helpers that the docs use, so from ebaml import describe_ebm works. import ebaml still loads no BAML code: describe_graph, describe_ebm, explain_instance and LocalExplanation load on first use.

[0.3.2] - 2026-11-02

Added

  • TokenEstimator estimates the tokens of a graph text from its words, bytes and digits, and is a BudgetCheck. It can learn its weights from the token counts of real calls with observe.
  • GraphOptions(token_learner=TokenLearner(learning=True)) makes describe_graph and describe_ebm check the token budget with the weights of the model that you chose, and learn the weights of each model that answers. The learned weights persist in ~/.cache/ebaml/token_weights.json. Learning is off by default.
  • A table of token weights for each model ships with the package (src/ebaml/llm/token_weights.json), and scripts/fit_token_weights.py adds a new model to it.
  • sample_graph_tokens sends one request with a graph text and returns its token samples, at a small cost.
  • TokenUsage.samples lists the token samples of the calls of a run. Each sample has the provider, the model, the request body and the input tokens. It never holds a header.
  • TokenFitError is raised when token weights cannot be fitted or read.

Changed

  • The default token estimate of a graph text is now 4.13 tokens for each word and 0.27 for each digit, with a margin above the fit, and no longer 1 token for 3 characters. The old rule gave 43% too few tokens on real graph texts. Graphs near max_tokens are now simplified at a different size, so the text that the LLM reads can differ.

Removed

  • BREAKING: The BAML functions estimate_tokens and check_token_budget and the BAML class TokenBudget are gone. Use ebaml.graphs.token_budget in Python.
  • BREAKING: TokenUsage has a new required field samples, so code that builds a TokenUsage must pass it.

[0.3.1] - 2026-11-01

Added

  • explain_instance takes language= (default "English"), so the three local explanations come in the language of the reader. It works with every audience.

Changed

  • The Audience docstring and the guide show an executive audience in place of a French one. Use language= to change the language.

[0.3.0] - 2026-11-01

Added

  • Audience is a base class that a user subclasses to explain a prediction to a new kind of reader. A subclass sets the instruction for the LLM (guidance) and the keys that the facts of the prompt get. Layperson and DataScientist are the two built-in audiences, and a subclass of either changes one rule. explain_instance and facts_to_texts accept an Audience object.
  • The module ebaml.local.audience has the helpers of the built-in audiences: likelihood_word, strength_word, round_value and points_towards.

Changed

  • BREAKING: Audience is no longer an enum. Use Layperson() and DataScientist() in place of Audience.LAYPERSON and Audience.DATA_SCIENTIST. The names "layperson" and "data_scientist" still work as strings.
  • BREAKING: The BAML functions explain_local, LocalCounterfactual, LocalSufficientReason, LocalCompletions and local_user_msg take the text audience_guidance: string in place of the name of the audience, and audience_guidance is no longer a BAML function.

[0.2.6] - 2026-10-31

Changed

  • The counterfactual facts that the local explanation prompts read put the class after the changes and its likelihood (or probability, for a data scientist) in one object, after_the_changes, with the same field names as the prediction. With the probability in a key of its own, a model read it as the probability of the old class.

[0.2.5] - 2026-10-31

Added

  • ebaml.graphs.token_budget.check_token_budget checks the token budget of a graph text in Python, with no LLM and no key. Pass it as check_budget to EBMGraph.to_text, which then simplifies a graph that is too large. estimate_tokens gives the estimate alone. Both follow the rule of the BAML functions of the same name, so you do not need to import the generated baml_sdk.

[0.2.4] - 2026-10-31

Changed

  • The default output limit of a call is 12000 tokens, and 16000 for the first turn of a conversation and for the benchmark. A reasoning model counts its hidden reasoning in this limit, and at 6000 and 8000 tokens some replies ended at the limit with no answer.

  • The counterfactual facts that the local explanation prompts read name the class that the prediction changes to (new_predicted_class), and the likelihood of that class is likelihood_of_new_predicted_class (probability_of_new_predicted_class for a data scientist). The LLM no longer has to guess which class the likelihood is about.

[0.2.3] - 2026-10-30

Fixed

  • A local explanation accepts a row of the training data whose categories are numbers or booleans, such as a pd.Categorical of 1, 2, 3 or of True, False. interpret keeps these categories as text, so such a row raised InvalidInstanceError: Unknown category. A value that cannot be a category, such as a complex number, raises InvalidInstanceError.

  • A local explanation raises InvalidInstanceError when the value of a continuous feature is not a number, such as "abc". It raised a bare ValueError or TypeError, which except EBaMlError did not catch.

  • EBMGraph.to_text with a boolean format says how many x-axis values the feature has, and that the format needs exactly two. The message said "more than x-axis values", which was also wrong for a feature with one value.

[0.2.2] - 2026-10-30

Fixed

  • EBMGraph.from_ebm, describe_graph and describe_ebm read the scores of the right feature when exclude or remove_terms leaves a feature without a term. The graph of a feature showed the scores of another feature, or raised an IndexError. A feature without a term raises UnsupportedModelError, and describe_ebm skips it.
  • The feature importances that describe_ebm sends to the summary pair each feature with its own importance when a feature has no term.
  • The local explanations name the features without a term in their UnsupportedModelError, and do not say that the model has interactions.

[0.2.1] - 2026-10-29

Added

  • A proof page shows that only the differences between the classes of a bin change the predicted probabilities of a multiclass classifier, and that its graphs keep the predictions of the EBM. A Lean proof checks the claims.

[0.2.0] - 2026-10-29

Added

  • model_kind(ebm) reads the kind of a fitted EBM as a BinaryClassifier, MulticlassClassifier or Regressor. Each kind gives the names of the outputs, the meaning of a score and the conversion of scores to the output.

  • EBMGraph.from_ebm reads the graph of a multiclass classifier: one score per bin and per class, centred over the classes of each bin. EBMGraph.classes names the classes, and to_text writes one series per class after a Class: line. from_text reads that text back.

  • GraphOptions.classes and the classes argument of EBMGraph.from_ebm select the classes of a multiclass graph, because the text of a model with many classes is long.

  • describe_ebm and describe_graph log an interactions_skipped warning that names the interaction terms they skip, because the descriptions cover the main effects only.

  • describe_graph and describe_ebm describe multiclass classifiers. GraphOptions(classes=[...]) selects the classes to describe.

  • Prediction.margin is the log-odds of the predicted class: the margin of the decision, which means the same for every model kind.

  • Counterfactual.new_decision holds the class that the prediction flips to.
  • SufficientReason.minimum tells whether no smaller set fixes the prediction. It is always true for a binary classifier.
  • The proof page of the local explanations defines the counterfactual, the sufficient reason and the completions of regressors and multiclass classifiers.

Changed

  • EBMGraph.to_text raises EBMGraphShapeError when the scores and the standard deviations do not have the same shape.

  • The prompt of describe_graph and describe_ebm says how to read the graph of a multiclass classifier: one series per class, where only the differences between the classes of a bin change the predicted probabilities. The prompts of binary classifiers and regressors do not change.

  • BREAKING: The result types of the local explanations have field names that fit every model kind, so the explanations of regressors and multiclass classifiers can come later with no breaking change. The JSON texts for the prompts, and so the explanations of binary classifiers, do not change.

Type Old field New field
Prediction label decision
Prediction probability output
Prediction logit score
Prediction logit_std score_std
Counterfactual new_probability new_output
  • The type hints name the real types instead of object, so pyrefly and beartype check them: class labels are ClassLabel, the values of an instance are FeatureValue, and Contribution.value and Change.from_value are str. ebaml.core.custom_types defines the aliases.

Fixed

  • The local explanations reject an EBM with two classes whose link is not logit with UnsupportedModelError, because it is not a binary classifier. Every rejection starts with "Local explanations need a binary classifier."

  • A local explanation raises InvalidInstanceError for a NaN of a NumPy float type and for pd.NA. A NumPy NaN got the last bin, and pd.NA raised a TypeError. A Decimal value is accepted.

[0.1.1] - 2026-10-27

Fixed

  • GraphOptions(x_axis_precision=...) no longer fails on categorical features. The precision rounds interval ends only, and category names stay as they are.

  • The graph text escapes the keys as JSON. A category name with a quote or a backslash gave the LLM invalid JSON.

  • The simplification of a large graph stops at 10%. It tried 10.1% before it raised the error.

  • The completion share of a local explanation counts a completion at a logit of exactly 0 as the negative class. The share was too low for a negative prediction.

  • The usage log event of describe_graph and describe_ebm has truncated_attempts, the number of attempts that max_tokens cut off. The token usage leaves out those attempts, because the provider error carries no count, so it is a lower bound.

[0.1.0] - 2026-10-26

Added

  • describe_graph, describe_ebm and explain_instance take model= to choose the LLM of one call, as ModelOptions or the "provider/model" shorthand. The default model stays OpenRouter's openrouter/free.
  • ebaml.llm.options.ModelOptions sets the provider, the model, the environment variable of the key, the base URL, the temperature, the output limit and the headers.
  • benchmark/run.py --model provider/model runs the benchmark on another model.

  • Importing ebaml.llm.descriptors runs baml generate when the generated baml_sdk package is missing. If the package was generated by another BAML toolchain than baml-bridge expects, the import selects the expected toolchain with baml toolchain use and generates the package again. If the agent skill check stops baml generate, the import runs it again with the check off.

  • If the import cannot fix the cause, the new SDKUnavailableError (also an ImportError) lists the steps that fix it: install the BAML toolchain, put it on PATH, or run baml generate in the checkout. It also shows the end of the command output.
  • describe_graph, describe_ebm and explain_instance raise MissingAPIKeyError, APIKeyRejectedError, RateLimitedError or ProviderUnreachableError (all LLMRequestError) when the provider fails a request for a reason that the user can fix. The message names the cause, the environment variable to export where it applies, and the steps that fix it. These calls raised the raw BamlError for these causes.

Changed

  • The BAML entry points describe_graph_cot, summarize_ebm, describe_ebm, answer_benchmark_question and explain_local take an optional model: ModelSpec. The new BAML function check_model rejects an unknown provider.
  • EBaMl needs the BAML toolchain 0.23 and baml-bridge 0.23 or later.

Fixed

  • The benchmark reads a number with no digit before the decimal point (.5) as 0.5, not as 5, so is_correct accepts such an answer.

[0.0.3] - 2026-10-25

Added

  • The README and the home page of the documentation have a table of the model types that each feature supports: binary classifiers, regressors, multiclass classifiers and models with interactions.
  • ebaml.EBaMlError is the base class of every error that ebaml raises on purpose, so except EBaMlError catches all of them. Every error class of the package derives from it.
  • New error classes replace the plain ValueError errors: OptionRangeError, InvalidInstanceError, UnsupportedModelError, GraphTextError and EBMGraphShapeError. Each one also derives from ValueError. The README section "Errors" lists when each one is raised.
  • EBMGraph.from_text raises a GraphTextError for a line that is not valid JSON. It raised the JSONDecodeError of orjson before, which is also a ValueError.

Fixed

  • explain_instance raises an UnsupportedModelError for a regressor. It raised an AttributeError for the missing classes_.
  • EBMGraph.to_text writes the confidence level of the bounds with its decimals, for example 87.5%. It rounded the level to a whole percent before, so EBMGraph.from_text computed the standard deviations at the wrong level.
  • EBMGraph.from_ebm and EBMGraph.simplify return an instance of the subclass when you call them on a subclass of EBMGraph. They returned a plain EBMGraph before, so the runtime type check raised an error.
  • parse_str_tuple_to_float_tuple raises a ValueError for a text with more or fewer than two values. It returned a tuple of any length before, for example three ends for the interval "(1, 2, 3)".
  • TaskResult.accuracy is 0.0 for a task with no outcomes. It raised a ZeroDivisionError before, and so did format_results.

Changed

  • BREAKING: facts_to_texts returns a FactTexts object with the fields prediction, counterfactual, sufficient_reason and completions, instead of a dict. parse_graph_text returns a ParsedGraph object instead of a tuple of five values.
  • BREAKING: The modules of ebaml now sit in packages. Change your imports as the table shows. The classes and functions are the same.
Before After
ebaml.custom_types, ebaml.exceptions ebaml.core.custom_types, ebaml.core.exceptions
ebaml.graphs, ebaml.graph_text ebaml.graphs.ebm_graph, ebaml.graphs.graph_text
ebaml.local, ebaml.local_text ebaml.local.facts, ebaml.local.fact_text
ebaml.descriptors, ebaml.options, ebaml.retry ebaml.llm.descriptors, ebaml.llm.options, ebaml.llm.retry

The names ebaml.EBMGraph, ebaml.Audience and the other names in ebaml.__all__ do not change. The structlog logger ebaml.descriptors is now ebaml.llm.descriptors. - All prompts in baml_src/ follow the prompting guide. Inputs are in XML tags, long data comes first and the task comes last, rules give their reason, and multi-turn requests are in <instructions> tags. The default task_description is now "Describe the general pattern of the graph." Compare results before and after on the benchmark. - BREAKING: ebaml.benchmark no longer imports baml_sdk. run_task(task, data_dir, limit) is now run_task(task, questions, ask). Load the questions with load_questions and cut them with a slice for a limit. Pass baml_sdk.answer_benchmark_question as ask, or any function with the same keyword arguments that returns an object with text and usage. benchmark/run.py does this for you. - BREAKING: describe_graph, describe_ebm and explain_instance no longer take **kwargs. Three option classes replace them, as keyword-only arguments. graph=GraphOptions(...) (module ebaml.llm.options) holds the options of EBMGraph.from_ebm and EBMGraph.to_text. prompt=PromptOptions(...) (module ebaml.llm.options) holds expert_description, graph_description, dataset_description and task_description. local=LocalOptions(...) (module ebaml.local.facts, only for explain_instance) holds the options of the local facts. A misspelled option was silently ignored before. It now raises a TypeError. For example, change describe_ebm(ebm, dataset_description="x") to describe_ebm(ebm, prompt=PromptOptions(dataset_description="x")). - BREAKING: ebaml.graphs.ebm_graph no longer imports baml_sdk. EBMGraph.to_text takes a new keyword argument, check_budget, a function that compares the estimated tokens of the text with max_tokens and overbudget_percent. baml_sdk.check_token_budget is such a function. If you call EBMGraph.to_text yourself and pass no check_budget, the function checks nothing: it writes the text once, and does not warn or simplify. Pass check_budget=baml_sdk.check_token_budget to get the old behavior. describe_graph and describe_ebm pass it for you. - BREAKING: facts_to_texts moved from the local facts module to the new module ebaml.local.fact_text. ebaml.local.facts now computes the facts only, and ebaml.local.fact_text renders them. Change from ebaml.local import facts_to_texts to from ebaml.local.fact_text import facts_to_texts.

[0.0.2] - 2026-10-23

Added

  • Live prompt tests in baml_src/prompt_tests.baml. Run them with baml test -i root::Live and a real key.
  • EBMGraph.to_body_text returns the graph text without the preamble.
  • Runtime type checks with beartype. Every function in the ebaml package now checks its argument and return types. A call with a wrong type raises a BeartypeCallHintViolation.

Changed

  • InvalidOptionError takes any Collection[str] of valid options, not only a list[str].
  • Fixed type hints that did not match the code: EBMGraph.x_vals can hold categories, EBMGraph.scores can be a NumPy array, and EBMGraph.from_ebm and EBMGraph.to_text accept plain strings for their enum options.
  • BREAKING: ebaml.graph_text.graph_to_text is now the method EBMGraph.to_text. The module ebaml.graph_text keeps xy_to_json, parse_str_tuple_to_float_tuple and parse_graph_text.
  • Function parameters take abstract types (Sequence, Mapping, Iterable, str | os.PathLike[str]), and return values stay concrete.
  • The warning for a large graph points at the caller, and not at the beartype wrapper.
  • A separate Prompt tests workflow runs the live prompt tests with the OPENROUTER_API_KEY repository secret. It is slow, so the CI workflow does not wait for it.
  • The offline BAML tests now run with baml test -x root::Live.

[0.0.1] - 2026-10-23

Added

  • Project base.