VRAVEN

Visual Reasoning and Activation Visualisation for Explainable Networks
Compiler-assisted causal decompilation and scientific explanation for PyTorch models.

Documentation · Quick start · PyPI · Issues

VRAVEN investigates how a trained neural network forms a decision. It captures internal evidence, tests selected relationships through interventions, searches for bounded counterfactuals and reports both coverage and unresolved computation.

It separates observational evidence from causal evidence and never treats a visually convincing explanation as proof by itself.

Install

VRAVEN requires Python 3.10 or newer. A clean virtual environment is recommended.

python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install vraven==0.10.0
vraven doctor

On Windows PowerShell, activate with .venv\Scripts\Activate.ps1.

Start simply

Create one local demonstration report:

vraven demo --mode gradient \
  --report-format html \
  --output vraven-demo.html

Or point the beginner workflow at a self-contained model folder:

vraven bundle ./my-model
vraven analyse ./my-model

The model-folder guide shows how to keep model.pt, its architecture, representative input and defaults together in a validated VRAVEN bundle.

What it can do

• ✅ Explain one prediction in fast, gradient or causal mode
• ✅ Capture PyTorch computation into the architecture-neutral Mechanism IR
• ✅ Discover and track candidate internal concepts across layers
• ✅ Compile and measure targeted internal interventions
• ✅ Recover and test compact executable decision programmes
• ✅ Produce contrastive and bounded counterfactual evidence
• ✅ Run adversarial, stability, LRP and supported formal analyses
• ✅ Analyse datasets, compare models and follow checkpoint evolution
• ✅ Export one HTML, PDF or JSON report per invocation
• ✅ Report evidence coverage, limitations and unresolved computation

Run vraven features for the installed capability inventory or use the command chooser to select one focused workflow.

Python

import vraven

report = vraven.explain(model, inputs, target=1, mode="causal")
report.export_html("vraven-report.html")

Advanced configuration remains available through the Python API without making the basic workflow depend on dozens of positional arguments.

Methodology

Figure 3 is the twelve-stage methodology:

The editable source is docs/assets/vraven-methodology.drawio.

Scientific boundaries

VRAVEN does not claim that every model can be fully captured, every discovered direction has human meaning, or a recovered programme is globally unique. Internal counterfactual validity is distinct from real-world domain validity. Unsupported operations and weak or missing evidence are reported rather than hidden.

Security and privacy

Processing is local by default and VRAVEN adds no telemetry. Full Python-pickled models are blocked unless trusted loading is explicitly enabled. Never load an untrusted pickle.

Project

VRAVEN is experimental alpha research software licensed under Apache-2.0. See CONTRIBUTING.md, LICENSE and NOTICE.