Skip to content

Explaining a decision: the smallest change that flips it

"What would have changed the answer?" — the smallest change of the given inputs, for adverse-action reasons in lending and clear answers in support: solvi.core.explain (stable since 1.1; until then solvi.experimental.counterfactual, which re-exports it for one release). Measured on the credit policy (benchmarks/counterfactual_credit.py): 3,613 of 3,613 explanations were valid when the decision was made again with the change, the thresholds found were minimal against a brute-force search in 53 of 53 cases, 507 of 522 refused or review applications got an explanation in one or two fields, at 0.065 s per search.

from solvi.core.explain import search
res = system.ask({"amount": 1200.0, "debt": 1000, "income": 5000, "history": "on time", "age": 30})
cf = search(res, "approve")
print(cf)
# approve = decline [ok]
#   approve if amount ≤ 1000 (now 1200)
#   held at their recorded proposals (no model called): risk
#   not searched: history (str: no domain (pass domains={'history': [...]}))
cf.best.changes[0]            # Change(fact="amount", now=1200.0, to=1000.0, op="≤", cost=0.17)
cf.to_dict()

Only the deterministic flow is re-run, on the recorded plan: every model-backed part — an extractor, a model decision, a learned answer head — is held at the proposal it recorded in this trace, and no model is called. The explanation is "what the code would decide if the models said what they said"; the result lists the parts held. A model part that did not run in the recorded decision (a hard check failed first) has no proposal: inputs that need it make the question abstain and do not count as a change (listed as "without a recorded proposal"). Learned rule lists (learn_rule) are code and re-run.

What is searched (over=: default, the given facts the question's flow reads):

  • numbers and dates — outward from the current value in both directions with doubling steps, then bisection between the last unchanged and the first changed value: the nearest threshold crossing, exact for inputs the answer is monotone in (a non-monotone input can hide a nearer crossing between two probes). A direction where no probe changes the answer is tried again on an even grid up to the farthest probe, which finds the band of a two-sided rule (abs(value + 20) > 5 at 40 → no if value ≤ -15); a narrower band can still be missed, so when nothing is found the result says "no change ... was found", not that none exists. Integers and dates give exact bounds (debt ≤ 1999, purchase_date ≥ 2026-08-20); floats are shown at the shortest decimal that holds, ≤ or < as the rule has it. A non-negative input stays non-negative; a domain (lo, hi) that does not contain the current value is refused for that input (cf.not_searched says why);
  • booleans, Enums and Literal fields of System(input_model=...) — every other value;
  • anything else only with domains={"history": ["on time", "late"]}; a tuple bounds a number: domains={"amount": (0, 5000)}.

max_changes=2 (the default) tries two inputs together when no single input changes the answer ("approve if amount ≤ 1000 (now 1200) and debt ≤ 1999 (now 2500)" — each bound holds with the other change made); max_changes=1 does not. target="approve" looks only for that answer. Results are ranked by the number of changes, then their size (the relative change of a number; for a date the days moved over 30, or over the width of its domain; text_cost, 1 by default, for an enumerated value — a text field searched over its domain, a boolean, an Enum), each times the field's weight in costs={"amount": 2.0} (1 by default). With the default a change of category often ranks first where a person would rather move a number (the credit measurement found such a case): raise text_cost= or weigh the fields so the ranking follows what is cheap to change for the person you explain to. A given input read only by a part that did not run (a soft check skipped after a hard check failed) is listed in cf.not_searched. max_evals=5000 caps the re-runs (cf.exhausted). A response loaded from a store with its System works the same; one loaded without it needs system= (search(res, "approve", system=system)).