Metadata-Version: 2.4
Name: vraven
Version: 0.9.0a1
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.

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:

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

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

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

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

```bash
vraven doctor
```

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

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

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

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


## Research and PyTorch source basis

The compiler design and research gap are documented in:

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