Contributor guide

Develop VRAVEN from a Git checkout.

Most users should install VRAVEN from PyPI and use the vraven command. Clone the repository when you want to change the package, run its test suite, or regenerate research fixtures.

Choose the right path

Using VRAVEN

Install from PyPI, prepare a model bundle, then run vraven analyse. You do not need the repository scripts.

Install and start →

Developing VRAVEN

Clone the source, install it in editable mode, and use scripts only for tests, documentation, or research-fixture generation.

Clone and install

git clone https://github.com/vraven-ai/vraven.git
cd vraven
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Editable installation still provides the same public command. Confirm the environment before changing code:

vraven --version
vraven doctor
python -m pytest

Analyse your own model folder

Use the installed CLI even inside a checkout:

vraven bundle ./my-model
vraven analyse ./my-model \
  --task explain \
  --preset standard \
  --format html \
  --output vraven-report.html

The model-folder guide explains the required manifest, weights, input, and architecture factory.

Regenerate the research fixture

The documentation example named image_pattern_cnn2d is generated data, not a file shipped by PyPI or committed to Git. Contributors can build it locally, then run the comprehensive artifact pipeline:

python scripts/train_vraven_novel_probes.py
python scripts/run_vraven_artifact.py Models/image_pattern_cnn2d

Contributor workflowThe training command creates several synthetic probe models and can take substantially longer than a normal CLI analysis. The artifact runner produces a broad research and documentation suite, while vraven analyse intentionally produces one requested report at a time.

Rebuild the documentation reference

python scripts/build_docs_reference.py
python scripts/check_docs_site.py

The reference builder reads the checked-out Python API and CLI parser so command pages stay aligned with the implementation.