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.mdlinks 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¶
EditSessionand every edit, constraint and report work on multiclass classifiers. An edit of a graph takesclass_label: the class to change, orNonefor every class.Monotonizeserves multiclass models, whichmonotonizeofinterpretrefuses.- The report of an edit names the class of each changed score, and
ClassShiftgives the shift of the weighted mean and of the intercept of each class. edit_effectgivesMulticlassMetricsfor 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_binsgives the score of each class, and the edit and constraint objects takeclass_label.
Changed¶
load_gamchangerandsave_gamchangerraiseUnsupportedModelErrorwith the fix steps for a multiclass model, because a.gamchangerfile 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
StrEnummembers:Direction,MonotoneDirection,AlignTarget,HistoryKind,BudgetLevelandFeatureType. The functions still accept the plain text ("increasing") and turn it into the member. A wrong text raisesInvalidOptionError. - The tool
get_graphand the option--transportof the server take the enumsNormalizationandTransport. The schema ofget_graphlists the values ofnormalizationthrough 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
.gamchangerfile 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
.gamchangerfiles.
[0.8.6] - 2026-11-20¶
Added¶
-
save_gamchangerwrites the original model and the applied edits of a session as a.gamchangerfile that the GAM Changer widget opens. The result names each part of the session that the file cannot hold. -
load_gamchangerreads any new bins of a commit, so it reads back the files thatsave_gamchangerwrites afterSplitBinandExtendRange. 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_classandrows_to_negative_class), in the edit report of the MCP tools too. -
edit_effectmeasures 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 aSubgroup. -
affected_profileshows 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_effectandget_affected_profileshow the effect of the edits on the rows of--data. The server flag--labelsnames the column with the true outcome, from which the tools compute the metrics.
[0.8.4] - 2026-11-18¶
Added¶
-
The edits
SplitBin,RebinandExtendRangechange 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_gamchangerloads theequal-interpolateandequal-regressioncommits of GAM Changer as aRebinfollowed 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
ClipandLimitStepskeep the scores of a graph in a range and limit the step between neighbour bins. -
The selection
EveryBinselects the missing bin, every real bin and the unseen bin of a feature. -
Business constraints
Monotone,MaxStep,Bounded,FixedScoreandUnused.check_constraintsfinds the constraints that a model breaks, names the bins that break each one, and gives the edit that repairs it. -
The MCP tool
check_constraintsfinds the business constraints that the model breaks. Each violation holds the edit that repairs it, in the form thatpreview_editandapply_edittake. -
The edit
AssignScoressets each selected score to its own value. -
load_gamchangerreads a.gamchangerfile of GAM Changer and builds the edits of the newest commit of each feature.apply_gamchangerapplies them to anEditSession, 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-bridge0.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,docsandllm. Run them aspython -m scripts.<group>.<name>, for examplepython -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_editandlist_edits. An agent edits a copy of the model with a written reason for each edit. The tools call no LLM. preview_editandapply_editcount the rows of--datathat an edit changes. They say in one field when the server has no data.save_modelsaves 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-dirturns it on.--editsreplays 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_predictiontakerevision(original,currentor 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 fieldsbase_revisionandrevisionofEditReport.
Changed¶
- BREAKING:
list_featuresreturns an object withsessionandfeatures, and each JSON result of the read and explain tools has asessionfield.get_graphstarts with a line that names the revision. - BREAKING:
ModelStorekeeps anEditSessioninsession, and the model of the loaded file isoriginal.explain_predictionofebaml.mcp.explain_toolstakes aPredictionRequest. describe_modelkeeps its text for the revision that it describes, so an edit never leaves a description of the model before the edit.- The
mcpextra needspydantic, 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 fromebaml.local.factstoebaml.local.fact_types. Import them fromebaml, as infrom ebaml import LocalFacts.compute_local_factsstays inebaml.local.facts.
[0.7.1] - 2026-11-13¶
Added¶
ebaml-mcpandebaml-chatread the--datafile 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
--datafile that is empty, is cut off, or is neither Parquet nor UTF-8 CSV raisesDataFileErrorwith the file name and the fix.
[0.7.0] - 2026-11-13¶
Added¶
EditSessionand the editsShift,SetScores,Align,Monotonize,Interpolate,FitLine,Scale,ZeroTerm,Recenter,RemoveTermsandRemoveFeaturechange 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, sopredict_with_uncertainty,explain_global,EBMGraph.from_ebmandskopswork on it.- The selections
Bins,Categories,ValueInterval,WholeGraph,MissingBinandUnseenBinname the bins of an edit. An edit reaches the missing bin and the unseen bin too. EditSessiongives 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.savewrites the edited model withskops.ioand 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_revisionand raisesStaleRevisionErrorif the head differs. - The new documentation page "Editing a model" and the notebook
notebooks/model_editing.py.
[0.6.9] - 2026-11-11¶
Added¶
MinimalityStatussays why a counterfactual or a sufficient reason is, or is not, known to be the smallest set:SORTING_PROOF,SOLVER_PROOF,AT_LOWER_BOUNDorUNPROVED.MinimalityStatus.is_smallestis false only forUNPROVED.EBMDescriptionholds the description of an EBM (text) and the names of what it leaves out (skipped_termsandskipped_features).
Changed¶
- BREAKING:
describe_ebmreturns anEBMDescriptionand not astr. Use its fieldtextwhere you used the string, for example asglobal_explanationofexplain_instance. - BREAKING:
Counterfactual.minimum,SufficientReason.minimumandCover.minimumare nowminimality, aMinimalityStatusand not abool. Readminimality.is_smallestfor the old meaning. Theis_smallest_setkey of the facts for the prompts is unchanged.
[0.6.8] - 2026-11-11¶
Added¶
LocalFactshas two new fields,min_supportandn_samples, so the facts carry the options that they hold under.sample_size_wordgives the word (large,moderate,small) that a layperson reads for the size of the sample of the completions.
Changed¶
- BREAKING:
Audiencehas three new abstract methods:guarantee,supportandsample. An audience that subclassesAudienceitself must add them. A subclass ofLaypersonorDataScientistneeds no change.LocalFactsneedsmin_supportandn_sampleswhen you build it yourself. describe_ebmanddescribe_graphtell the LLM which parts of the model the description leaves out: the interaction terms, and the features thatexcludeorremove_termsleft without a graph. The text of the description then names them.describe_ebmlogs afeatures_skippedwarning for such features.- The BAML functions
describe_graph_cot,summarize_ebmanddescribe_ebmacceptomitted_terms, and the last two acceptomitted_features. Both default to an empty list.
Fixed¶
- The local explanation prompts claim a condition only when the facts state it. With
confidence_level=0they do not say that a flip or a guarantee survives the uncertainty of the model. Withmin_support=0they 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.factsand 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
Counterfactualandcompute_local_facts, the guide and the MCP tool text say that a set is the smallest only whenminimumis 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.scoresays 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,DescribeEBMRequestandExplainInstanceRequesthold the input ofdescribe_graph,describe_ebmandexplain_instance. Import them fromebaml.
Changed¶
- BREAKING:
describe_graph,describe_ebmandexplain_instancetake 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, andgraph,prompt,local,modelandlanguagestay 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.pyshows a bar by default. Use--no-progressto turn it off.
[0.6.5] - 2026-11-09¶
Added¶
- The
ebaml-chatcommand: 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_mcpandchat_with_toolsin BAML, andebaml.llm.descriptors.chat_with_mcpin 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
enumerateand array conversion in place of index loops. The output stays the same.
[0.6.3] - 2026-11-09¶
Added¶
explain_with_mcpin BAML: an agent that startsebaml-mcp, lets a language model call its tools, and returns the report with the list of tool calls.explain_with_toolsruns 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.searchchooses 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, withstop=Stop.OPTIMALorStop.FIRSTand atime_limit),LocalSearchCover(a seeded local search from the greedy set) orGreedyCover. The last two need no MIP solver.MipBackendis the protocol of the optimization library behindMipCoverand the lower bound.OrToolsBackendruns OR-Tools with HiGHS, SCIP or CP-SAT (OrToolsSolver). Another library plugs in as a class with the samesolvemethod.SufficientReason.lower_boundandCounterfactual.lower_boundgive 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_bounddecides whether the facts give the lower bound:DataScientistwritessmallest_possible_number_of_changesandsmallest_possible_number_of_features, andLaypersonleaves them out. The prompts tell the LLM that it may state the gap when the set is not proved smallest.SearchLimitErrortells 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_searchis replaced byLocalOptions.search, andCounterfactualandSufficientReasonhave the required fieldlower_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_setis then true. - BREAKING:
Audiencehas the abstract methodlower_bound, so a custom audience must define it. - When
is_smallest_setis 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 movesprotobufto 6.33.
Removed¶
- BREAKING:
ebaml.local.reason_searchwithReasonSearch,Minimal,ExactOrMinimalandSelection. Use aCoveringSolverinLocalOptions.search.
[0.6.0] - 2026-11-08¶
Added¶
LocalOptions.target_classasks, for a multiclass classifier, for the changes after which a chosen class is the predicted class.reason_searchchooses 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 keyminimum_number_of_changesis nownumber_of_changes. Counterfactual.minimumis false for the counterfactual of a chosen target class.
[0.5.2] - 2026-11-08¶
Added¶
explain_instance,compute_local_factsand the MCP toolexplain_predictionexplain 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_searchchooses the search of the sufficient reason. The Lean proof of these facts is not done yet.OutputKind.CLASS_PROBABILITYnames the output of a multiclass classifier. The texts for the data scientist call the score of the predicted classclass_score.
[0.5.1] - 2026-11-07¶
Changed¶
-
The
mcpextra requiresmcp>=2.3.0, andebaml-mcpruns on theMCPServerclass ofmcp2. 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 themcpextra,cyclopts>=5.3.2,joblib>=1.6.0andpolars>=2.1.0.
Security¶
- The
mcpextra and the project environment holdmcp2.3.0 and the fixedopentelemetryreleases, 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 (
MinimalandExactOrMinimal). The "Proof of the local explanations" page states what the proof shows and what it leaves out.
Fixed¶
-
A fresh
pip install ebamlno longer installs abaml-bridgethat rejects the generatedbaml_sdkwith a version skew error.ebamlnow requiresbaml-bridge==0.23.0, the version of the toolchain that generates the SDK. -
The wheel and the source distribution no longer contain the
.gitignorefile thatbaml generatewrites intobaml_sdk. -
pip install "ebaml[mcp]"no longer installsmcp2.x, which has noFastMCPand madeebaml-mcpfail at start-up. Themcpextra now requiresmcp>=1.30.0,<2.
[0.4.4] - 2026-11-07¶
Added¶
explain_instanceandcompute_local_factsexplain a prediction of a regressor.LocalOptions(decision=...)sets the question about the predicted value:Threshold(value), orInterval(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 raisesUnsupportedModelError.-
The MCP tool
explain_predictionexplains a regressor. -
A regressor can explain the answer "inside" of
Interval(low, high).LocalOptions.reason_searchchooses how to find the sufficient reason of such a decision:Minimal()(the default) returns a set from which no input can be removed, andExactOrMinimal()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_outputandAudience.margintake theOutputKindof the model as a second argument. A custom audience must add it.Predictionhas two new fields,thresholdandoutput_kind, andpoints_towardsreads 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:
Intervalis open at the low end and closed at the high end, asThresholdis. The answers are "at mostlow", "abovelowand at mosthigh" and "abovehigh".Sideholds a tuple ofMarginobjects in place of one sign and one threshold.
[0.4.3] - 2026-11-06¶
Added¶
ebaml-mcptakes--hostand--portfor thestreamable-httptransport. The defaults are127.0.0.1and8000.
[0.4.2] - 2026-11-06¶
Fixed¶
ebaml-mcpwrites its log events to stderr. Before, they went to stdout and could corrupt the JSON-RPC stream of the stdio transport.- The
max_tokensargument of theget_graphtool 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 --modelloads 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
--dataCSV file with polars, andModelStoreaccepts a frame of any library that narwhals supports (pandas, polars, pyarrow). ebaml no longer imports pandas outside the type ofpd.NA. -
ebaml-mcpandbenchmark/run.pyuse cyclopts for the command line. The flags stay the same, and themcpextra 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-mcpcommand serves a fitted EBM as an MCP server (install themcpextra). 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¶
ebamlnow exports the functions, the option classes, the local-explanation facts and the audience helpers that the docs use, sofrom ebaml import describe_ebmworks.import ebamlstill loads no BAML code:describe_graph,describe_ebm,explain_instanceandLocalExplanationload on first use.
[0.3.2] - 2026-11-02¶
Added¶
TokenEstimatorestimates the tokens of a graph text from its words, bytes and digits, and is aBudgetCheck. It can learn its weights from the token counts of real calls withobserve.GraphOptions(token_learner=TokenLearner(learning=True))makesdescribe_graphanddescribe_ebmcheck 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), andscripts/fit_token_weights.pyadds a new model to it. sample_graph_tokenssends one request with a graph text and returns its token samples, at a small cost.TokenUsage.sampleslists 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.TokenFitErroris 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_tokensare now simplified at a different size, so the text that the LLM reads can differ.
Removed¶
- BREAKING: The BAML functions
estimate_tokensandcheck_token_budgetand the BAML classTokenBudgetare gone. Useebaml.graphs.token_budgetin Python. - BREAKING:
TokenUsagehas a new required fieldsamples, so code that builds aTokenUsagemust pass it.
[0.3.1] - 2026-11-01¶
Added¶
explain_instancetakeslanguage=(default"English"), so the three local explanations come in the language of the reader. It works with every audience.
Changed¶
- The
Audiencedocstring and the guide show an executive audience in place of a French one. Uselanguage=to change the language.
[0.3.0] - 2026-11-01¶
Added¶
Audienceis 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.LaypersonandDataScientistare the two built-in audiences, and a subclass of either changes one rule.explain_instanceandfacts_to_textsaccept anAudienceobject.- The module
ebaml.local.audiencehas the helpers of the built-in audiences:likelihood_word,strength_word,round_valueandpoints_towards.
Changed¶
- BREAKING:
Audienceis no longer an enum. UseLayperson()andDataScientist()in place ofAudience.LAYPERSONandAudience.DATA_SCIENTIST. The names"layperson"and"data_scientist"still work as strings. - BREAKING: The BAML functions
explain_local,LocalCounterfactual,LocalSufficientReason,LocalCompletionsandlocal_user_msgtake the textaudience_guidance: stringin place of the name of the audience, andaudience_guidanceis 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_budgetchecks the token budget of a graph text in Python, with no LLM and no key. Pass it ascheck_budgettoEBMGraph.to_text, which then simplifies a graph that is too large.estimate_tokensgives the estimate alone. Both follow the rule of the BAML functions of the same name, so you do not need to import the generatedbaml_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 islikelihood_of_new_predicted_class(probability_of_new_predicted_classfor 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.Categoricalof1, 2, 3or ofTrue, False. interpret keeps these categories as text, so such a row raisedInvalidInstanceError: Unknown category. A value that cannot be a category, such as a complex number, raisesInvalidInstanceError. -
A local explanation raises
InvalidInstanceErrorwhen the value of a continuous feature is not a number, such as"abc". It raised a bareValueErrororTypeError, whichexcept EBaMlErrordid not catch. -
EBMGraph.to_textwith 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_graphanddescribe_ebmread the scores of the right feature whenexcludeorremove_termsleaves a feature without a term. The graph of a feature showed the scores of another feature, or raised anIndexError. A feature without a term raisesUnsupportedModelError, anddescribe_ebmskips it.- The feature importances that
describe_ebmsends 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 aBinaryClassifier,MulticlassClassifierorRegressor. Each kind gives the names of the outputs, the meaning of a score and the conversion of scores to the output. -
EBMGraph.from_ebmreads the graph of a multiclass classifier: one score per bin and per class, centred over the classes of each bin.EBMGraph.classesnames the classes, andto_textwrites one series per class after aClass:line.from_textreads that text back. -
GraphOptions.classesand theclassesargument ofEBMGraph.from_ebmselect the classes of a multiclass graph, because the text of a model with many classes is long. -
describe_ebmanddescribe_graphlog aninteractions_skippedwarning that names the interaction terms they skip, because the descriptions cover the main effects only. -
describe_graphanddescribe_ebmdescribe multiclass classifiers.GraphOptions(classes=[...])selects the classes to describe. -
Prediction.marginis the log-odds of the predicted class: the margin of the decision, which means the same for every model kind. Counterfactual.new_decisionholds the class that the prediction flips to.SufficientReason.minimumtells 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_textraisesEBMGraphShapeErrorwhen the scores and the standard deviations do not have the same shape. -
The prompt of
describe_graphanddescribe_ebmsays 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 areClassLabel, the values of an instance areFeatureValue, andContribution.valueandChange.from_valuearestr.ebaml.core.custom_typesdefines the aliases.
Fixed¶
-
The local explanations reject an EBM with two classes whose link is not
logitwithUnsupportedModelError, because it is not a binary classifier. Every rejection starts with "Local explanations need a binary classifier." -
A local explanation raises
InvalidInstanceErrorfor a NaN of a NumPy float type and forpd.NA. A NumPy NaN got the last bin, andpd.NAraised aTypeError. ADecimalvalue 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
usagelog event ofdescribe_graphanddescribe_ebmhastruncated_attempts, the number of attempts thatmax_tokenscut 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_ebmandexplain_instancetakemodel=to choose the LLM of one call, asModelOptionsor the"provider/model"shorthand. The default model stays OpenRouter'sopenrouter/free.ebaml.llm.options.ModelOptionssets 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/modelruns the benchmark on another model. -
Importing
ebaml.llm.descriptorsrunsbaml generatewhen the generatedbaml_sdkpackage is missing. If the package was generated by another BAML toolchain thanbaml-bridgeexpects, the import selects the expected toolchain withbaml toolchain useand generates the package again. If the agent skill check stopsbaml generate, the import runs it again with the check off. - If the import cannot fix the cause, the new
SDKUnavailableError(also anImportError) lists the steps that fix it: install the BAML toolchain, put it onPATH, or runbaml generatein the checkout. It also shows the end of the command output. describe_graph,describe_ebmandexplain_instanceraiseMissingAPIKeyError,APIKeyRejectedError,RateLimitedErrororProviderUnreachableError(allLLMRequestError) 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 rawBamlErrorfor these causes.
Changed¶
- The BAML entry points
describe_graph_cot,summarize_ebm,describe_ebm,answer_benchmark_questionandexplain_localtake an optionalmodel: ModelSpec. The new BAML functioncheck_modelrejects an unknown provider. - EBaMl needs the BAML toolchain 0.23 and
baml-bridge0.23 or later.
Fixed¶
- The benchmark reads a number with no digit before the decimal point (
.5) as 0.5, not as 5, sois_correctaccepts 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.EBaMlErroris the base class of every error thatebamlraises on purpose, soexcept EBaMlErrorcatches all of them. Every error class of the package derives from it.- New error classes replace the plain
ValueErrorerrors:OptionRangeError,InvalidInstanceError,UnsupportedModelError,GraphTextErrorandEBMGraphShapeError. Each one also derives fromValueError. The README section "Errors" lists when each one is raised. EBMGraph.from_textraises aGraphTextErrorfor a line that is not valid JSON. It raised theJSONDecodeErroroforjsonbefore, which is also aValueError.
Fixed¶
explain_instanceraises anUnsupportedModelErrorfor a regressor. It raised anAttributeErrorfor the missingclasses_.EBMGraph.to_textwrites the confidence level of the bounds with its decimals, for example87.5%. It rounded the level to a whole percent before, soEBMGraph.from_textcomputed the standard deviations at the wrong level.EBMGraph.from_ebmandEBMGraph.simplifyreturn an instance of the subclass when you call them on a subclass ofEBMGraph. They returned a plainEBMGraphbefore, so the runtime type check raised an error.parse_str_tuple_to_float_tupleraises aValueErrorfor 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.accuracyis0.0for a task with no outcomes. It raised aZeroDivisionErrorbefore, and so didformat_results.
Changed¶
- BREAKING:
facts_to_textsreturns aFactTextsobject with the fieldsprediction,counterfactual,sufficient_reasonandcompletions, instead of adict.parse_graph_textreturns aParsedGraphobject instead of a tuple of five values. - BREAKING: The modules of
ebamlnow 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 withbaml test -i root::Liveand a real key. EBMGraph.to_body_textreturns the graph text without the preamble.- Runtime type checks with
beartype. Every function in theebamlpackage now checks its argument and return types. A call with a wrong type raises aBeartypeCallHintViolation.
Changed¶
InvalidOptionErrortakes anyCollection[str]of valid options, not only alist[str].- Fixed type hints that did not match the code:
EBMGraph.x_valscan hold categories,EBMGraph.scorescan be a NumPy array, andEBMGraph.from_ebmandEBMGraph.to_textaccept plain strings for their enum options. - BREAKING:
ebaml.graph_text.graph_to_textis now the methodEBMGraph.to_text. The moduleebaml.graph_textkeepsxy_to_json,parse_str_tuple_to_float_tupleandparse_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
beartypewrapper. - A separate
Prompt testsworkflow runs the live prompt tests with theOPENROUTER_API_KEYrepository 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.