VRAVEN

Visual Reasoning and Activation Visualisation for Explainable Networks

Compiler-assisted causal decompilation of PyTorch models

VRAVEN is an experimental framework for reverse engineering a trained PyTorch model into a compact, executable and experimentally tested high-level decision mechanism.

Name, origin and purpose

VRAVEN stands for Visual Reasoning and Activation Visualisation for Explainable Networks.

VRAVEN was born from the need to move explainable AI beyond feature attribution. It investigates how a trained neural network computes its decisions by recovering internal concepts, testing their causal relationships, compiling them into an executable high-level mechanism, and clearly reporting what remains unexplained.

The raven represents intelligence, observation and the discovery of hidden structure. That reflects VRAVEN's purpose: examining the internal behaviour of trained neural networks rather than treating them only as black boxes. The leading V also emphasises the project's visual and verifiable approach.

VRAVEN does not merely aim to produce a visually convincing explanation. It aims to produce an explanation that can be experimentally tested against the original model.

It addresses a different question from ordinary feature attribution:

SHAP / LIME:
Which input variables influenced the prediction?

VRAVEN:
What computation was recovered, what internal concepts appeared, how did they interact,
which relationships survived intervention, can the mechanism execute as a compact programme,
what would change the decision, and what remains unexplained?

The central pipeline is:

What VRAVEN can do

• ✅ Multi-route PyTorch model capture
• ✅ Architecture-neutral VRAVEN Mechanism IR
• ✅ Automatic internal concept discovery
• ✅ Cross-layer concept evolution tracking
• ✅ Graph-compiled causal interventions
• ✅ Causal-effect measurement with uncertainty evidence
• ✅ Executable decision programme recovery
• ✅ Contrastive explanations
• ✅ Verified concept-level counterfactuals
• ✅ Separate observational and interventional fidelity reporting
• ✅ Validity and coverage certificates
• ✅ Interactive and publication-ready scientific visualisations
• ✅ Trace-level scientific evidence auditing
• ✅ Local Python and command-line workflows

VRAVEN does not claim to recover one uniquely true explanation of every model. It recovers the smallest tested high-level programme found under the configured search and reports a validity envelope, fidelity evidence and unresolved model dark matter.

What is implemented in 0.9.0

Multi-route model capture

VRAVEN attempts:

1. torch.export
2. torch.fx
3. Runtime operator dispatch
4. Module-hook fallback

The preferred route produces a normalised ATen-level graph. Failed attempts and fallback limitations are retained in the certificate.

VRAVEN Mechanism IR

The architecture-neutral intermediate representation records:

• Operators, parameters and buffers
• Tensor-flow edges
• Shapes, data types, devices and strides
• Dynamic-shape constraints and guards
• Source and module provenance
• Operator semantics
• Autograd-path availability
• Graph intervention points
• Numerical equivalence
• Unsupported computation

Automatic internal concept discovery

VRAVEN currently supports:

• Deterministic PCA concepts
• Sparse-autoencoder concepts
• Class preference and effect size
• Top activating samples
• Conservative association with supplied domain feature groups
• Explicit unresolved concepts where meaning is not established

Cross-layer concept evolution

A regularised optimal-transport alignment represents concept birth, persistence, splitting, merging and termination without treating independent embeddings as literal movement.

Graph-compiled causal interventions

VRAVEN rewrites the captured FX or Export graph and inserts explicit intervention modules. Supported interventions include:

zero
replace
scale
add
erase_direction
set_concept
set_concept_mean
clamp

Effects are measured using a target-versus-alternatives logit margin and reported with bootstrap intervals, sign stability and prediction flips.

Intervention-constrained executable programme

The programme is fitted jointly against:

• Normal target margins
• Tested internal intervention effects

This is important because a conventional observational surrogate can achieve very high predictive fit while failing to reproduce the model under intervention.

VRAVEN reports:

observational validation R²
observational decision agreement
interventional correlation
interventional mean absolute error
interventional sign agreement
counterfactual programme and model agreement

No opaque combined trust score is emitted.

Contrastive and counterfactual explanation

VRAVEN explains why the selected class was preferred over its strongest alternative and can search for bounded concept-level counterfactuals. Candidates are verified by executing graph-compiled interventions in the original captured model.

Internal counterfactual validity and domain validity are reported separately.

Explanation certificate

Every result includes:

• Validity envelope
• Operator coverage
• Parameter coverage
• Gradient coverage
• Intervention coverage
• Validated semantic coverage
• Association-only semantic coverage
• Causally weighted unresolved responsibility
• Observational fidelity
• Interventional fidelity
• Counterfactual evidence
• Claim lattice
• Known limitations

Signature scientific visualisations

Each figure is standalone and supports the same scientific values in two modes:

interactive_dark
publication_light

The figures are not generic dashboards. Every node, edge, width, colour and pattern has a declared scientific meaning stored in Plotly metadata.

Trace-level Scientific Evidence Audit

The standard vraven.explain(..., mode="causal") report now tests whether local activation–gradient rankings agree with measured zero-output ablations. It exposes evidence entropy, effective layer count, participation ratio, Gini concentration, signed cancellation, causal coverage, rank/sign/cosine concordance, L1 discrepancy and permutation significance as separate quantities. HTML reports lead with critical findings and a complete layer evidence ledger; no composite trust score is emitted.

report = vraven.explain(model, inputs, target=1, mode="causal")
audit = report.scientific_audit()
report.mechanism_concordance(mode="publication_light")
report.export_html("vraven_report.html")

Definitions, assumptions and validation limits are in docs/EVIDENCE_AUDIT.md.

Run every applicable analysis from one self-describing artefact

When a model bundle contains model.pt, meta.json, reference.npz and optional ordered checkpoints, the complete research suite can be launched with the artefact directory as its only argument:

python scripts/run_vraven_artifact.py Models/image_pattern_cnn2d

The runner reconstructs the declared architecture with safe state-dictionary loading, records SHA-256 provenance, executes capture, decompilation, adversarial stress, Proof, Atlas, Watch, Compare and every scientifically applicable DarkSide analysis, then writes an indexed HTML gallery under vraven_outputs/artifact_runs/. Non-estimable analyses are recorded with their missing evidence contract; they are never replaced with synthetic results.

Installation

Requirements

VRAVEN requires Python 3.10 or newer. Check the Python interpreter before installing:

python3 --version

If this reports Python 3.9 or older, install a newer Python release first. A virtual environment is recommended so that pip cannot accidentally use an older system Python.

Install from PyPI

macOS and Linux

Create and activate a virtual environment using any installed Python 3.10+ interpreter. For example, with Python 3.13:

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

Use python3.10, python3.11, or python3.12 instead if that is the supported Python 3.10+ command installed on your system.

Windows PowerShell

py -3.13 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install vraven==0.9.0
vraven doctor

Install the latest release

python -m pip install --upgrade vraven

If pip says that VRAVEN “Requires-Python >=3.10” and cannot find a matching distribution, the active pip belongs to Python 3.9 or older. Confirm the interpreter linked to it with:

python -m pip --version

Then create the virtual environment with a Python 3.10+ executable as shown above. Prefer python -m pip over an unqualified pip or pip3 command.

Editable development installation

python -m pip install -e ".[analysis,publication,dev]"
vraven doctor

Local wheel

Build and validate the wheel:

bash scripts/build_package.sh
python -m pip install dist/vraven-0.9.0-py3-none-any.whl

Release builds are published through GitHub Actions and PyPI Trusted Publishing. See docs/PYPI_RELEASE_GUIDE.md for the controlled release process.

Quick Python example

import torch
import vraven

model = YourModel().eval()
reference = torch.load("reference_inputs.pt", weights_only=True)

config = vraven.DecompileConfig.quick()

result = vraven.reverse(
    model,
    (reference,),
    focus_args=(reference[:1],),
    target=1,
    class_names={0: "Benign", 1: "Malware"},
    config=config,
)

print(result.summary())

result.write_report(
    "vraven_decision_proof.html",
    format="html",
    initial_mode="interactive_dark",
)

Command line

Verify the environment

vraven doctor
vraven features

Explain one model invocation

vraven explain model.pt \
  --model-factory my_project.models:Classifier \
  --factory-kwargs '{"input_dim":476,"num_classes":2}' \
  --input sample.npy \
  --target 1 \
  --mode causal \
  --class-names Benign,Malware \
  --max-layers 128 \
  --max-units 64 \
  --causal-top-k 5 \
  --report-format html \
  --output vraven_explanation.html

Use vraven explain -h to see all model-loading, layer-selection, capture, causal and report parameters. fast, gradient and causal modes trade increasing evidence depth for increasing runtime.

Capture an unknown state-dictionary model into Mechanism IR

vraven capture model.pt \
  --model-factory my_project.models:Classifier \
  --factory-kwargs '{"input_dim":476,"num_classes":2}' \
  --input sample.npy \
  --output mechanism_ir.json

Run full decompilation

vraven reverse model.pt \
  --model-factory my_project.models:Classifier \
  --factory-kwargs '{"input_dim":476,"num_classes":2}' \
  --reference reference.npy \
  --labels labels.npy \
  --target 1 \
  --class-names Benign,Malware \
  --input-groups feature_groups.json \
  --profile standard \
  --report-format pdf \
  --output vraven_decision_proof.pdf

A .pt state dictionary contains weights, not an arbitrary architecture. A model factory is therefore required.

Run the planted-mechanism demonstration

vraven decompile-demo \
  --profile quick \
  --report-format html \
  --output vraven_decompile_demo.html

Profiles

Quick

Designed for development and smoke testing. It uses deterministic PCA, bounded concept counts and smaller bootstrap budgets.

Standard

Uses the default research configuration.

Publication

Uses wider concept and causal searches, larger bootstrap budgets and more profiling repetitions. Publication profile does not make the result publication-ready by itself. Replication and matched baselines remain necessary.

One report per invocation

Choose one output format for each CLI run:

vraven explain model.pt ... --report-format html --output explanation.html
vraven explain model.pt ... --report-format pdf  --output explanation.pdf
vraven explain model.pt ... --report-format json --output explanation.json

HTML is the interactive local report, PDF is the publication-light document, and JSON is the machine-readable trace. Advanced Python workflows can still call result.save(...) explicitly when a complete multi-file research evidence bundle is required.

Known-mechanism benchmark

The repository includes VRAVEN-DecompileBench, a small PyTorch-native development benchmark with planted causal concepts, distractors, inhibitory signals and redundant pathways.

python benchmarks/decompilebench.py \
  --model planted_concept_mlp \
  --samples 96 \
  --output vraven_decompilebench

It is a development benchmark, not yet a complete community benchmark.

Scientific boundaries

VRAVEN currently does not establish that:

• Every PyTorch model can be fully captured
• Every discovered latent direction has a human meaning
• Every internal intervention corresponds to a naturally reachable state
• The recovered programme is globally minimal or unique
• The programme is faithful outside its validity envelope
• The method is state of the art across architectures
• A counterfactual is domain-valid without an application validator

Unsupported operations, weak interventional fidelity and unresolved concepts are shown rather than hidden.

Security and privacy

VRAVEN runs locally by default. Complete Python-pickled models are blocked unless the user explicitly enables trusted loading. Do not load untrusted pickles. Raw activations and input data are not persisted by the Mechanism IR unless a user explicitly exports them.

Licence

Apache License 2.0. See LICENSE and NOTICE.