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.

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:

Trained Model
    ↓
Internal Concept Discovery
    ↓
Concept Evolution
    ↓
Causal Mechanism Graph
    ↓
Executable Decision Programme
    ↓
Contrastive Explanation
    ↓
Counterfactual Proof
    ↓
Validity and Coverage Certificate

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.0a1

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

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.0a1-py3-none-any.whl

To publish later, install the standard build and twine tools, build both wheel and source distribution, test with TestPyPI, and only then upload the reviewed release to public PyPI. See docs/PYPI_RELEASE_GUIDE.md.

This repository has not been published to the public PyPI index.

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.save("vraven_decision_proof")
result.write_report(
    "vraven_decision_proof/report.html",
    initial_mode="interactive_dark",
)

result.figure(
    "causal_proof",
    mode="publication_light",
).write_html("causal_proof.html")

Command line

Verify the environment

vraven doctor

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 \
  --output-dir vraven_decision_proof

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 \
  --output-dir vraven_decompile_demo

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.

Saved output structure

vraven_decision_proof/
├── mechanism_ir.json
├── concept_atlas/
├── concept_evolution.json
├── causal_mechanism_graph.json
├── executable_programme.json
├── executable_programme.txt
├── contrastive_explanation.json
├── counterfactual_proof.json
├── mechanism_certificate.json
├── mechanism_profile.json
├── decompilation_manifest.json
└── report.html

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.

Research and PyTorch source basis

The compiler design and research gap are documented in:

docs/decompiler/PYTORCH_2_13_SOURCE_INDEX.md
docs/decompiler/RESEARCH_SOURCE_INDEX.md
docs/decompiler/IMPLEMENTATION_GAP_CLOSURE.md
docs/decompiler/RESEARCH_POSITIONING.md
REFERENCES.bib

The package records primary sources and open-access links rather than redistributing copyrighted books or publisher-controlled papers.

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.

Documentation

Start with:

• docs/decompiler/ARCHITECTURE.md
• docs/decompiler/MECHANISM_IR.md
• docs/decompiler/MATHEMATICAL_FOUNDATIONS.md
• docs/decompiler/PYTORCH_2_13_BASIS.md
• docs/decompiler/INTERVENTION_COMPILER.md
• docs/decompiler/VALIDITY_CERTIFICATE.md
• docs/decompiler/VISUAL_SYSTEM.md
• docs/decompiler/RESEARCH_POSITIONING.md
• docs/decompiler/LIMITATIONS.md
• docs/decompiler/PUBLICATION_PLAN.md
• docs/decompiler/QUICKSTART.md

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.