Actual Causes Identification — actualcauses

Description

actualcauses is a Python package to identify actual causes (Halpern–Pearl style) in deterministic or stochastic systems.
It implements approximate algorithms with adjustable precision introduced in the paper:

Searching for actual causes: approximate algorithms with adjustable precision (Reyd, Diaconescu, Dessalles).
Accepted at Transactions on Machine Learning Research (TMLR), 2026 — OpenReview.

The package is designed for explainability and causal analysis of autonomous / AI-based systems: given a system model, a context, and a target consequence, it searches for exact or approximate actual causes.

Installation

pip install actualcauses

For local development:

git clone https://github.com/SamuelReyd/ActualCausesIdentification
cd ActualCausesIdentification
python -m pip install -e ".[dev]"

Core concepts

SCM

An SCM object represents a Structural Causal Model:

• V: endogenous variables (names)
• U: exogenous variables (names)
• D: variable domains
• u: a context (values for exogenous variables)
• dag: optional causal graph (for algorithms that exploit structure)
• model: a system model (see SystemModel class) used to evaluate interventions

Once created, you call:

scm.find_causes(...)
scm.show_identification_result()

The result is stored on the SCM (scm.causes, scm.witnesses, scm.interventions, scm.n_calls, ...) and can be saved with scm.save(path) / SCM.load(path, model).

System models (SystemModel, BaseNumpyModel, …)

A system model defines how the system responds to interventions.

For simple Python models, subclass SystemModel and implement call(u, e).

For accelerated / vectorized evaluation, subclass BaseNumpyModel (and optionally its stochastic variants).

Quickstart (Suzzy rock-throwing example)

The package provides a ready-to-run example SCM:

from actualcauses import suzzy_example_scm

# Identify causes with two algorithms (Beam Search / ISI)
suzzy_example_scm.find_causes(ISI=False, max_steps=5, beam_size=20, epsilon=0.05, early_stop=False, verbose=2)
suzzy_example_scm.show_identification_result()

suzzy_example_scm.find_causes(ISI=True,  max_steps=5, beam_size=20, epsilon=0.05, early_stop=False, verbose=2)
suzzy_example_scm.show_identification_result()

A complete runnable version is in examples/quickstart.py.

See the examples/ folder for additional scenarios and advanced usage.

Minimal custom SCM example (deterministic)

This mirrors examples/custom_scm.py (forest fire scenario). The important part is implementing a SystemModel and passing it to SCM.

from actualcauses import SCM, SystemModel

class ForestFireModel(SystemModel):
    def __init__(self, disjunctive=True):
        super().__init__(
            phi=lambda s: s[-1],  # consequence predicate (example: last variable)
            psi=lambda s: sum(s), # heuristic used by search
        )
        self.disjunctive = disjunctive

    def __call__(self, u, e):
        md, l = u
        e = dict(e)
        MD = e.get("MD", md)
        L  = e.get("L",  l)
        if self.disjunctive:
            FF = e.get("FF", int(L or MD))
        else:
            FF = e.get("FF", int(L and MD))
        self.n_calls += 1
        return [MD, L, FF]

scm = SCM(
    V=("MD", "L", "FF"),
    U=("md", "l"),
    D=(0, 1),
    u=(1, 1),
    model=ForestFireModel(disjunctive=True),
    dag={"MD": [], "L": [], "FF": ["MD", "L"]},
)

scm.find_causes()
scm.show_identification_result()

Algorithms

All parameters are passed through SCM.find_causes(ISI=..., **kwargs). Every algorithm has 3 levels of verbosity (verbose=1, 2 or 3).

MBS — Minimal Beam Search (ISI=False, the default)

A beam search over interventions of increasing size, which only needs the oracle phi and the heuristic psi.

With beam_size=-1 and max_steps=-1, MBS is exhaustive.

ISI — Iterative Sub-Instance identification (ISI=True)

Uses the causal graph (dag) to split the search into subproblems, starting from the parents of the target and “causally backtracking” from every canceling intervention (paper, Section 4.2).

Exact ISI returns exactly the HP-causes (paper, Appendix G). Its cost follows the structure of the graph rather than the size of the model; for models whose causes are all singletons, MBS can be cheaper.

LUCB — adaptive sampling for stochastic models

LUCBNumpyModel(V, t, lucb_params) estimates phi and psi with confidence bounds and only resamples the interventions whose status is still ambiguous (paper, Section 4.3). lucb_params contains beam_size, a (canceling threshold), cause_eps, non_cause_eps, beam_eps (slacks), delta (confidence level), max_iter (average budget per intervention), init_batch_size, batch_size, and optionally seed and verbose. AverageNumpyModel is the fixed-budget baseline.

Examples

The examples/ folder contains scripts intended to be read and modified:

• quickstart.py — Minimal end-to-end run using suzzy_example_scm.
• custom_scm.py — Implement a custom basic SCM and identify actual causes.
• custom_heuristic.py — Use different heuristics (psi) with a fixed system model and SCM.
• vectorized_system_model.py — Use BaseNumpyModel to accelerate identification by vectorizing intervention evaluation.
• stochastic_system_model.py — Stochastic evaluation with a naive average estimator and the LUCB estimator.

Run any example from the repository root, e.g.:

python examples/quickstart.py

The code of the paper's experiments is available at SearchingForCauses.

License

MIT License. See LICENSE.

Citation

If you use this software in academic work, please cite:

Reyd, S., Diaconescu, A., & Dessalles, J.-L. (2026). Searching for actual causes: Approximate algorithms with adjustable precision. Transactions on Machine Learning Research (accepted).

@article{reyd2026searchingactualcauses,
  title        = {Searching for actual causes: Approximate algorithms with adjustable precision},
  author       = {Samuel Reyd and Ada Diaconescu and Jean-Louis Dessalles},
  journal      = {Transactions on Machine Learning Research},
  year         = {2026},
  url          = {https://openreview.net/forum?id=3NlYZPCH9v&}
}
```