Explainiverse

Explainiverse is a beta Python library for constructing and evaluating machine-learning explanations. Its public registry records what each explainer has actually been audited to do; it does not rank methods by quality or claim that one method is appropriate for a particular deployment.

Version 0.14.0 is the last legacy release: its distributions were uploaded with Twine, without Trusted Publishing or published provenance. The matching annotated Git tag is unsigned and no GitHub Release exists, so that cross-service release record is incomplete. The signed immutable v0.15.0 tag is retained as failed release-automation history: run 33891048942 stopped during SBOM generation before artifact upload, attestation, PyPI publication, or GitHub Release creation. The signed immutable v0.15.1 tag is also retained as failed release-automation history: run 33901507340 built successfully and retained workflow artifacts, including the repaired SBOM, but GitHub skipped distribution attestation, PyPI publication, and GitHub Release creation because a skipped ancestor condition propagated to those jobs. Neither 0.15.0 nor 0.15.1 is on PyPI or has a GitHub Release. The 0.15.2 roll-forward declares Python 3.10 through 3.13 and has an explicitly authorized, one-release CPU-only exception, EXPLAINIVERSE-v0.15.2-CPU-ONLY. Its CPU, packaging, and hosted compatibility gates remain mandatory, but CUDA hardware validation is not being performed and 0.15.2 makes no CUDA release-verification claim.

Accuracy status

Registry entries use three statuses:

• verified: the implementation and its tests support the specific claim_scope recorded in the registry.
• quarantined: the code remains available for compatibility, but must not be represented as the canonical named method.
• unverified: no formula-level accuracy claim is made yet.

verified is deliberately narrow. It does not mean that an explanation is causal, useful, fair, stable, or faithful for a particular model and dataset. Those conclusions require task-specific evidence.

Use the runtime metadata as the authoritative explainer inventory:

from explainiverse import default_registry

print(default_registry.summary())
print(default_registry.get_meta("lime").claim_scope)

Evaluation endpoints have an equivalent authoritative inventory:

import explainiverse.evaluation as evaluation

metrics = evaluation.default_metric_registry
metrics.validate_inventory(evaluation.__all__)
print(metrics.summary())
print(metrics.get_meta("compute_aopc").claim_scope)

The metric registry distinguishes formula-verified endpoints, quarantined compatibility aliases, explicit adaptations, score direction, stochastic estimators, and instance/batch/ dataset scope. A verified endpoint remains limited to its callable documentation and claim_scope; it is not automatically a canonical reproduction of an entire paper protocol.

The audited registry currently groups as follows:

Grad-CAM++ is not exposed. The previous implementation used only first derivatives and could not establish the general higher-derivative formula. The verified anchor_tabular key is the confidence-certified continuous-numeric implementation; the historical anchors key remains the fixed-sample compatibility heuristic. The historical counterfactual key does not claim the DiCE optimisation algorithm.

Evaluation scope

The evaluation namespace contains canonical formulas, explicitly named adaptations, and library-defined diagnostics. It is an API inventory, not a count of distinct scientific metrics and not a quality leaderboard.

Undefined quantities, incompatible targets, incomplete feature mappings, unsupported model outputs, and non-finite inputs are intended to fail explicitly rather than receive fabricated fallback scores.

Installation from a checkout

Base dependencies, including the image utilities required by the mandatory LIME backend:

python -m pip install -e .

PyTorch/Captum extras:

python -m pip install -e ".[all]"

The historical image extra was redundant because LIME already installed scikit-image. Scikit-image is now an explicit base dependency and the no-op extra has been removed. Consumers that previously installed .[image] should install the base package instead; .[all] continues to add Torch and Captum.

For development, synchronize the locked all-extras environment:

poetry sync --all-extras --with dev,tutorial --no-interaction

Minimal tabular example

This example uses the verified LIME wrapper scope. Its returned coefficients describe the fitted local surrogate; they are not causal effects.

from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestClassifier

from explainiverse import SklearnAdapter, default_registry

iris = load_iris()
feature_names = iris.feature_names
class_names = iris.target_names

model = RandomForestClassifier(n_estimators=20, random_state=0)
model.fit(iris.data, iris.target)

adapter = SklearnAdapter(
    model,
    feature_names=feature_names,
    class_names=class_names,
    task="classification",
)
explainer = default_registry.create(
    "lime",
    model=adapter,
    training_data=iris.data,
    feature_names=feature_names,
    class_names=class_names,
    random_state=0,
)

explanation = explainer.explain(iris.data[0])
print(explanation.target_class)
print(explanation.get_top_features(k=4))

default_registry.filter(...) performs metadata matching. The historical default_registry.recommend(...) name only orders metadata-compatible entries; it does not recommend the best method or predict suitability, accuracy, runtime, or explanation quality.

BaseExplainer.explain intentionally has a generic abstract signature because local, global, dataset-level, and feature-oriented explainers do not share one honest input contract. Consult the concrete class and registry scope before use.

ExplanationSuite.run(...) executes only local explainers, checks both constructor and method arguments, and leaves exact array shape to each concrete contract. Required method arguments such as ProtoDash reference data must be supplied through explainer_call_kwargs or call_kwargs_by_explainer. The returned mapping is detached from suite.explanations, so changing its keys does not alter the suite's stored results; both mappings contain the same Explanation objects. ExplanationSuite.compare() requires the same ordered feature identity, explained target, and explicit caller-asserted metadata["comparison_contract"] across multiple outputs. Built-in explainers do not currently emit that contract. The allow_incommensurate=True escape hatch is a warned descriptive display, not a mathematical comparison.

Explanation.to_dict() returns a defensive-copy dictionary. Payload values keep their original Python or NumPy types, so the result is not promised to be directly JSON serializable.

Tutorials and other packages

The LIME, KernelSHAP, TreeSHAP, and finite-estimator uncertainty/intervention-sensitivity notebooks under tutorials/ are deterministic, offline teaching artifacts verified against this checkout. Each published notebook contains a dated execution record, package version, Python/platform record, and canonicalized poetry.lock digest. The repository harness statically rejects common package-install/network access paths, adds a non-loopback Python socket guard, executes a clean in-memory copy, and fails on stale source, output, runner, package-tree, or lock provenance:

poetry run python scripts/execute_tutorials.py

The guard prevents accidental network dependence in the reviewed notebooks; it is not a security sandbox for hostile notebook code.

These examples verify their stated API and numerical contracts; they are not research benchmarks or evidence that an explanation is causal or suitable for deployment.

The TypeScript package under packages/js/ is private and experimental. It is not a published JavaScript equivalent of the Python implementation.

Verification and contribution gate

Before adding a method or metric:

1. identify the primary formula and its assumptions;
2. declare target, score-space, perturbation, shape, and unsupported-domain contracts;
3. add analytical or official-reference tests and invariants;
4. mark adaptations and heuristics in the public name, metadata, and result payload;
5. run formatting, lint, type, test, build, and package-smoke gates appropriate to the change.

The reproducible checkout gate is:

poetry sync --all-extras --with dev,tutorial --no-interaction
poetry check --lock
poetry run python -m pip check
poetry run black --check src tests scripts
poetry run isort --check-only src tests scripts
poetry run mypy src scripts
poetry run pytest --strict-config --strict-markers --cov=explainiverse --cov-branch
poetry run python scripts/execute_tutorials.py
poetry build

CPU CI permits the four explicitly allowlisted CUDA skips plus the conditional Python 3.10 / XGBoost-before-3.1 vector-intercept skip; any other skipped test fails the corresponding pytest job. The exact 0.15.2 exception records those CUDA release jobs as not run, not passed. CUDA execution remains outside the verified device scope until approved GPU runners satisfy the normal release gate. Reference packages are imported explicitly before tests, and the built wheel and source distribution are each exercised in isolated consumer environments.

See the 0.15 migration notes, the residual-limitations mitigation plan, and the accuracy roadmap for current contracts and priorities. The former competitive comparison was withdrawn in SOTA_COMPARISON.md because raw API counts and cross-library marketing claims were not scientifically comparable.

License and citation

The Python distribution declares the MIT license; see LICENSE. The separate private packages/js workspace declares UNLICENSED in its own package metadata and is not a published JavaScript distribution.

If you use a particular explainer or metric, cite its primary source as well as the exact software revision and configuration you ran. For release 0.14.0, cite the v0.14.0 tag (or its commit hash) and your configuration. PyPI hosts 0.14.0 artifacts, but there is no corresponding GitHub Release or Trusted-Publishing provenance record.