solvi.core.explain¶
Explaining a decision: the smallest change of its given inputs that changes the answer (counterfactuals; stable since
1.1, until then solvi.experimental.counterfactual). Only the deterministic flow is re-run, model parts held at their
recorded proposals; text_cost= and costs= set what a change costs.
Counterfactual explanations: the smallest change of a decision's given inputs that changes its answer — "approve if amount ≤ 1000 (now 1200)", "refund if purchase_date ≥ 2026-08-20 (now 2026-08-10)" — for adverse-action reasons in lending and clear answers in support.
Stable since 1.1 (until then solvi.experimental.counterfactual, which re-exports every name for one release).
from solvi.core.explain import search
cf = search(res, "approve") # res: a Response (or one loaded from a store, with system=)
print(cf.best) # approve if amount <= 1000 (now 1200)
How: the recorded decision is re-run on changed inputs through the deterministic flow only. The flow is the recorded one (same keys, so the same plan); every model-backed part — an extractor, a model decision, a learned answer head, a part whose provenance is decided / learned / proposed — is replaced by the proposal it recorded in this trace, so no model is ever called: the answer is "what the code would decide if the models said what they said". A model part that did not run in the recorded decision (skipped after a hard check failed) has no proposal: on inputs that need it the question abstains, and such inputs are not counted as changing the answer. Learned rule lists (learn_rule) are code and are re-run.
The search, per input:
numbers (int, float) and dates — probe outward from the current value in both directions with doubling steps, then
bisect between the last unchanged and the first changed value: the nearest threshold crossing for inputs the answer
is monotone in. A direction where no probe changes the answer is tried again on an even grid between the current
value and the farthest probe within the range, which finds a band of a non-monotone input ("alert unless within 5
of -20") — a band narrower than the grid can still be missed, so "no change was found" is what the result says.
Non-negative inputs stay non-negative unless a domain says otherwise; a domain (lo, hi) that does not contain the
current value is refused for that input (listed as not searched); float bounds are shown at the shortest decimal
that still holds;
booleans, Enums and Literal-typed inputs (System(input_model=...)) — every other value;
anything else — only with domains={fact: [values]}.
Two inputs together only when no single one changes the answer: one input's candidates (its values, or probe points) with
a search over the other, then each bound tightened with the other change made. Changes are ranked by count, then by size
(relative change of a number; days moved over 30 — or over the domain's width — for a date; text_cost, 1 by default,
for an enumerated value — a text field, a boolean, an Enum), each times the field's weight in costs= (1 by default):
with the default a change of a category often ranks before a number moved far, where a person may prefer the number —
raise text_cost, or weigh fields, to say which changes are cheap for the people you explain to.
Change
dataclass
¶
One change of a given input in a counterfactual: the fact, its value now, the value tried (op "=" or a
boundary "≤", "<", "≥", ">" for a number) and its cost.
Counterfactual
dataclass
¶
Counterfactual(answer: object, changes: list, status: str = 'ok', why: str = '', kind: str | None = None)
The answer after a set of Changes (str: "cost (the sum
of the changes' costs); to_dict() for JSON.
Rerun ¶
The recorded decision as a function of its given inputs: rerun({fact: value}) → the question's Result, through the
recorded flow with every model-backed part held at its recorded proposal.
many ¶
Several re-runs in one batch, without hashing (nothing of them is stored or replayed) → [Result].
search ¶
search(res, question, max_changes=2, over=None, target=None, domains=None, system=None, max_evals=5000, *, text_cost=1.0, costs=None, exhaustive=0)
The smallest changes of res's given inputs that change the answer to question → Counterfactuals (best
first; see the module docs). max_changes: 1 or 2 inputs at once; over: the inputs to search (default: the given
inputs the answer rests on); target: an answer to reach (default: any other); domains: {fact: (lo, hi) or [values]};
system: the System that answered (default: the response's own); max_evals: re-runs at most. text_cost: the cost of
changing an enumerated value (a text field searched over its domain, a boolean, an Enum); costs: {fact: weight}
multiplying that fact's change costs (a number's relative change, a date's days, text_cost) — the ranking by cost
follows what is cheap to change for the person the explanation is for.
exhaustive=n (opt-in; small domains): when every searched input has an enumerated domain (values, a boolean, an
Enum, a Literal) and the combinations to try — each value alone, and with max_changes=2 each pair of values of two
inputs — number at most n (and max_evals), every one is re-run in one batch without hashing, and found holds
every counterfactual among them (pairs only where no single change suffices, as in the search), with complete
True. Otherwise the search runs as without it. Measured in one run on a three-input loan rule (tests/
test_explain_exhaustive.py): a re-run without hashing took 0.11 ms against 0.18 ms, and the whole search 0.74 ms
against 1.20 ms (single changes) and 1.92 ms against 2.92 ms (pairs), with the same counterfactuals found.
The old path, until 1.2¶
solvi.experimental.counterfactual re-exports every name above, as the same objects, with an ExperimentalWarning.
Graduated in 1.1: counterfactual explanations are the stable solvi.core.explain (search, Counterfactual,
Counterfactuals, Change, Rerun). This path re-exports every name, as the same objects, with the experimental
warning (its removal, planned for 1.2, is now in a future release). Import solvi.core.explain.