Metadata-Version: 2.4
Name: vraven
Version: 0.10.1
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>Evidence-aware explainability for PyTorch models</strong><br>
  Trace internal evidence, test selected mechanisms and create auditable reports.
</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://vraven-ai.github.io/vraven/api/">Python API</a> ·
  <a href="https://pypi.org/project/vraven/">PyPI</a> ·
  <a href="https://github.com/vraven-ai/vraven/issues">Issues</a>
</p>

VRAVEN stands for **Visual Reasoning and Activation Visualisation for
Explainable Networks**. It is an explainability and model-auditing toolkit for
investigating how a trained neural network reaches a decision.

VRAVEN can capture internal evidence, inspect candidate concepts, test selected
relationships through interventions, search for bounded counterfactuals and
report what the analysis did—and did not—cover. It keeps observational evidence
separate from causal evidence and does not present an attractive visualisation
as proof by itself.

## Install

VRAVEN requires Python 3.10 or newer. Use a clean virtual environment so the
package and its PyTorch dependencies do not affect other projects.

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

On Windows PowerShell, activate the environment with
`.venv\Scripts\Activate.ps1`. If installation reports that the release requires
a newer Python version, run `python --version` and install Python 3.10 or newer.

## Create your first report

Run the deterministic demonstration to create one self-contained HTML report:

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

Open `vraven-demo.html` in a browser. The report contains the prediction,
evidence visualisations, analysis metadata and stated limitations.

## Analyse your own model

For a saved state dictionary, provide the Python factory that rebuilds the
model and a representative input tensor:

```bash
vraven analyse model.pt \
  --model-format state_dict \
  --model-factory my_project.models:Classifier \
  --input input.pt \
  --task explain \
  --preset standard \
  --format html \
  --output vraven-report.html
```

If the model has several files or configuration values, place them in a VRAVEN
model bundle. The
[model-folder guide](https://vraven-ai.github.io/vraven/guides/model-folder.html)
walks through the required files, validation and analysis commands.

> A `model.pt` file does not always contain the model architecture. A saved
> `state_dict` also needs the model class or factory that created it. Full
> Python-pickled models should only be loaded when their source is trusted.

## Python API

```python
import vraven

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

Change the output extension to write one supported report per call, such as
`vraven-report.pdf` or `vraven-trace.json`. See the
[API reference](https://vraven-ai.github.io/vraven/api/) for the complete
signatures and return types.

## What VRAVEN can do

- ✅ Explain an individual prediction in fast, gradient or causal mode
- ✅ Capture PyTorch computation in an 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
- ✅ Record evidence coverage, limitations and unresolved computation

Run `vraven features` for the capability inventory installed on your machine.
Use the
[command guide](https://vraven-ai.github.io/vraven/guides/commands.html) to pick
one focused workflow and see its parameters.

## How the analysis fits together

VRAVEN connects model capture, internal concept discovery, intervention,
programme recovery, counterfactual testing and evidence certification in one
traceable workflow.

<p align="center">
  <img src="docs/assets/vraven-methodology.png" alt="VRAVEN methodology from model capture to evidence certification" width="100%">
</p>

The workflow is not a claim that every analysis completes every stage. Reports
identify unsupported operations, missing evidence and the scope within which a
result was produced.

## Choose the right starting point

| Goal | Start here |
| --- | --- |
| Install VRAVEN and create a first report | [Getting started](https://vraven-ai.github.io/vraven/guides/getting-started.html) |
| Analyse a model and its configuration files | [Model folders](https://vraven-ai.github.io/vraven/guides/model-folder.html) |
| Select a terminal workflow | [Command guide](https://vraven-ai.github.io/vraven/guides/commands.html) |
| Use VRAVEN from Python | [API reference](https://vraven-ai.github.io/vraven/api/) |
| Choose a report format and understand its evidence | [Report guide](https://vraven-ai.github.io/vraven/guides/reports.html) |
| Review the scientific foundations | [Research foundations](https://vraven-ai.github.io/vraven/research.html) |

## Scientific boundaries

VRAVEN does not claim that every model can be fully captured, that every
discovered direction has human meaning, or that a recovered programme is
globally unique. Internal counterfactual validity is also distinct from
real-world domain validity. Treat each result according to its stated evidence
level, coverage and assumptions.

## Privacy and security

Analysis runs locally by default and VRAVEN adds no telemetry. Full
Python-pickled models are blocked unless trusted loading is explicitly enabled.
Never load a pickle from an untrusted source.

## Project status

VRAVEN is experimental research software. APIs, report schemas and supported
operations may change before a stable 1.0 release. Contributions and reproducible
bug reports are welcome; see [`CONTRIBUTING.md`](CONTRIBUTING.md).

Licensed under Apache-2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
