VRAVEN

Evidence-aware explainability for PyTorch models
Trace internal evidence, test selected mechanisms and create auditable reports.

Documentation · Quick start · Python API · PyPI · Issues

VRAVEN stands for Visual Reasoning and Activation Visualisation for Explainable Networks. It is an explainability and model-auditing toolkit for investigating how a trained neural network reaches a decision.

VRAVEN can capture internal evidence, inspect candidate concepts, test selected relationships through interventions, search for bounded counterfactuals and report what the analysis did—and did not—cover. It keeps observational evidence separate from causal evidence and does not present an attractive visualisation as proof by itself.

Install

VRAVEN requires Python 3.10 or newer. Use a clean virtual environment so the package and its PyTorch dependencies do not affect other projects.

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

On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1. If installation reports that the release requires a newer Python version, run python --version and install Python 3.10 or newer.

Create your first report

Run the deterministic demonstration to create one self-contained HTML report:

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

Open vraven-demo.html in a browser. The report contains the prediction, evidence visualisations, analysis metadata and stated limitations.

Analyse your own model

For a saved state dictionary, provide the Python factory that rebuilds the model and a representative input tensor:

vraven analyse model.pt \
  --model-format state_dict \
  --model-factory my_project.models:Classifier \
  --input input.pt \
  --task explain \
  --preset standard \
  --format html \
  --output vraven-report.html

If the model has several files or configuration values, place them in a VRAVEN model bundle. The model-folder guide walks through the required files, validation and analysis commands.

A model.pt file does not always contain the model architecture. A saved state_dict also needs the model class or factory that created it. Full Python-pickled models should only be loaded when their source is trusted.

Python API

import vraven

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

Change the output extension to write one supported report per call, such as vraven-report.pdf or vraven-trace.json. See the API reference for the complete signatures and return types.

What VRAVEN can do

• ✅ Explain an individual prediction in fast, gradient or causal mode
• ✅ Capture PyTorch computation in an 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
• ✅ Record evidence coverage, limitations and unresolved computation

Run vraven features for the capability inventory installed on your machine. Use the command guide to pick one focused workflow and see its parameters.

How the analysis fits together

VRAVEN connects model capture, internal concept discovery, intervention, programme recovery, counterfactual testing and evidence certification in one traceable workflow.

The workflow is not a claim that every analysis completes every stage. Reports identify unsupported operations, missing evidence and the scope within which a result was produced.

Choose the right starting point

Scientific boundaries

VRAVEN does not claim that every model can be fully captured, that every discovered direction has human meaning, or that a recovered programme is globally unique. Internal counterfactual validity is also distinct from real-world domain validity. Treat each result according to its stated evidence level, coverage and assumptions.

Privacy and security

Analysis runs locally by default and VRAVEN adds no telemetry. Full Python-pickled models are blocked unless trusted loading is explicitly enabled. Never load a pickle from an untrusted source.

Project status

VRAVEN is experimental research software. APIs, report schemas and supported operations may change before a stable 1.0 release. Contributions and reproducible bug reports are welcome; see CONTRIBUTING.md.

Licensed under Apache-2.0. See LICENSE and NOTICE.