Metadata-Version: 2.4
Name: vraven
Version: 0.9.0
Summary: Compiler-assisted causal decompilation and scientific visual explanation of PyTorch models
Author: Daniel Jeremiah and VRAVEN contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/vraven-ai/vraven
Project-URL: Repository, https://github.com/vraven-ai/vraven
Project-URL: Issues, https://github.com/vraven-ai/vraven/issues
Keywords: explainable-ai,deep-learning,pytorch,mechanistic-interpretability,causal-decompilation,visualisation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.26
Requires-Dist: torch>=2.2
Requires-Dist: plotly>=6.1
Requires-Dist: networkx>=3.2
Provides-Extra: publication
Requires-Dist: kaleido>=1.0; extra == "publication"
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.4; extra == "sklearn"
Provides-Extra: analysis
Requires-Dist: scipy>=1.11; extra == "analysis"
Requires-Dist: scikit-learn>=1.4; extra == "analysis"
Provides-Extra: darkside
Requires-Dist: scipy>=1.11; extra == "darkside"
Requires-Dist: scikit-learn>=1.4; extra == "darkside"
Requires-Dist: ripser>=0.6.8; extra == "darkside"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: scikit-learn>=1.4; extra == "dev"
Requires-Dist: scipy>=1.11; extra == "dev"
Requires-Dist: svgwrite>=1.4; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Dynamic: license-file

# VRAVEN

<p align="center">
  <img src="assets/branding/avatars/vraven-avatar-256.png" alt="VRAVEN raven signature" width="220">
</p>

**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 **V**isual **R**easoning and **A**ctivation
**V**isualisation for **E**xplainable **N**etworks.

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:

```text
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:

<p align="center">
  <img src="docs/assets/vraven-pipeline.svg" alt="VRAVEN pipeline: a trained model progresses through internal concept discovery, concept evolution, a causal mechanism graph, an executable decision programme, contrastive explanation, counterfactual proof, and a validity and coverage certificate." width="100%">
</p>

## 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:

```text
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:

```text
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:

```text
interactive_dark
publication_light
```

| VRAVEN visual | Scientific object |
|---|---|
| **Raven Eye** | Full-stack model X-ray and capture coverage |
| **Raven Flight** | Cross-layer concept genome |
| **Raven Brain** | Bidirectional causal proof graph |
| **Raven Code** | Executable programme proof tree |
| **Raven Contrast** | Why the selected class defeated its alternative |
| **Raven Shadow** | Original versus counterfactual mechanism |
| **Raven Dark Matter** | Explained, associated, intervention-inaccessible and unresolved computation |

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.

```python
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:

```bash
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:

```bash
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:

```bash
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

```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

```bash
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:

```bash
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

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

### Local wheel

Build and validate the wheel:

```bash
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

```python
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

```bash
vraven doctor
vraven features
```

### Explain one model invocation

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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.

```bash
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`.
