Metadata-Version: 2.4
Name: vraven
Version: 0.10.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://vraven-ai.github.io/vraven/
Project-URL: Documentation, https://vraven-ai.github.io/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="190">
</p>

<p align="center">
  <strong>Visual Reasoning and Activation Visualisation for Explainable Networks</strong><br>
  Compiler-assisted causal decompilation and scientific explanation for PyTorch models.
</p>

<p align="center">
  <a href="https://vraven-ai.github.io/vraven/"><strong>Documentation</strong></a> ·
  <a href="https://vraven-ai.github.io/vraven/guides/getting-started.html">Quick start</a> ·
  <a href="https://pypi.org/project/vraven/">PyPI</a> ·
  <a href="https://github.com/vraven-ai/vraven/issues">Issues</a>
</p>

VRAVEN investigates how a trained neural network forms a decision. It captures
internal evidence, tests selected relationships through interventions, searches
for bounded counterfactuals and reports both coverage and unresolved computation.

It separates observational evidence from causal evidence and never treats a
visually convincing explanation as proof by itself.

## Install

VRAVEN requires Python 3.10 or newer. A clean virtual environment is recommended.

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

On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1`.

## Start simply

Create one local demonstration report:

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

Or point the beginner workflow at a self-contained model folder:

```bash
vraven bundle ./my-model
vraven analyse ./my-model
```

The [model-folder guide](https://vraven-ai.github.io/vraven/guides/model-folder.html)
shows how to keep `model.pt`, its architecture, representative input and defaults
together in a validated VRAVEN bundle.

## What it can do

- ✅ Explain one prediction in fast, gradient or causal mode
- ✅ Capture PyTorch computation into the 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
- ✅ Report evidence coverage, limitations and unresolved computation

Run `vraven features` for the installed capability inventory or use the
[command chooser](https://vraven-ai.github.io/vraven/guides/commands.html) to
select one focused workflow.

## Python

```python
import vraven

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

Advanced configuration remains available through the Python API without making
the basic workflow depend on dozens of positional arguments.

## Methodology

Figure 3 is the twelve-stage methodology:

<p align="center">
  <img src="docs/assets/vraven-methodology.png" alt="VRAVEN twelve-stage methodology" width="100%">
</p>

The editable source is
[`docs/assets/vraven-methodology.drawio`](docs/assets/vraven-methodology.drawio).

## Scientific boundaries

VRAVEN does not claim that every model can be fully captured, every discovered
direction has human meaning, or a recovered programme is globally unique.
Internal counterfactual validity is distinct from real-world domain validity.
Unsupported operations and weak or missing evidence are reported rather than
hidden.

## Security and privacy

Processing is local by default and VRAVEN adds no telemetry. Full Python-pickled
models are blocked unless trusted loading is explicitly enabled. Never load an
untrusted pickle.

## Project

VRAVEN is experimental alpha research software licensed under Apache-2.0. See
[`CONTRIBUTING.md`](CONTRIBUTING.md), [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
