# jessevig/bertviz architecture

> Architecture diagram of the GitHub repository jessevig/bertviz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jessevig/bertviz
- Repository: https://github.com/jessevig/bertviz

## Overview

##### Project type and purpose
- BertViz is a Python library – an interactive visualization tool for Transformer‐based NLP models (e.g. BERT, GPT-2, T5).
- Its purpose is to expose and display attention weights and neuron activations in Jupyter/Colab notebooks via simple Python API calls.

##### File structure
- Top-level files and directories:
- setup.py, MANIFEST.in, LICENSE, README.md – packaging & documentation
- bertviz/ – core package
- bertviz/tests/ – unit tests + fixtures
- bertviz/transformers_neuron_view/ – custom‐patched Huggingface model and tokenizer code for neuron view
- notebooks/ – example notebooks demonstrating head/model/neuron views
- images/ – animated GIFs and screenshots for docs
- Core modules in bertviz/:
- head_view.py + head_view.js
- model_view.py + model_view.js
- neuron_view.py + neuron_view.js
- util.py – shared helper functions
- Configuration & deployment:
- setup.py – pip install & package metadata
- .gitignore, LICENSE – project hygiene & licensing

##### README for additional insights
- Describes three “views” (Head, Model, Neuron) each backed by a Python function that:
a. loads a Huggingface model with output_attentions=True
b. computes attention (and for neuron view, custom query/key retrieval via patched models)
c. renders an HTML/JS widget inside Jupyter using ipywidgets and embedded .js visualization code
- Mentions dependencies: Transformers library, Jupyter Notebook, ipywidgets

a. Main components
1. User Notebook (Jupyter/Colab)
2. bertviz Python API
– head_view(), model_view(), neuron_view.show()
3. Transformers model loader (Huggingface)
4. Custom neuron‐view adapters (bertviz/transformers_neuron_view)
5. Attention data structures (Python lists/arrays of attention weights)
6. Front-end visualization engine (head_view.js, model_view.js, neuron_view.js + ipywidgets)
7. External Model Hub (Huggingface)
8. Test harness & fixtures
9. Packaging (setup.py → pip distribution)
b. Relationships & data flow
c. Architectural patterns & design principles
- Separation of concerns:
- Data retrieval (model loading & attention extraction)
- View rendering (JS & HTML embedded in notebooks)
- Custom adapters for unsupported features (neuron‐view) isolated in subpackage
- Plugin/adapter pattern: custom `transformers_neuron_view` modules extend Huggingface base classes
- MVC‐like layering:
- Model = Transformer models & attention matrices
- View = JS modules (visualizations)
- Controller = Python API glue (head_view.py, model_view.py, neuron_view.py)
- Test‐driven development: fixtures & tests ensure correctness across backends
d. Key technologies, frameworks, libraries
- Python 3.x, Jupyter Notebook / JupyterLab, ipywidgets
- Huggingface Transformers
- D3.js or similar front-end JS graphing used in .js files
- pytest or unittest for tests
- pip / setuptools for packaging

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Documentation
    UserNotebook["User Notebook\n(Jupyter/Colab)"]:::doc
    click UserNotebook "https://github.com/jessevig/bertviz/tree/master/notebooks/"
    README["README.md\n(Usage & Examples)"]:::docs
    click README "https://github.com/jessevig/bertviz/blob/master/README.md"
    Images["Documentation Images\n(images/)"]:::docs
    click Images "https://github.com/jessevig/bertviz/tree/master/images/"

    %% External Services
    HuggingfaceHub[("Huggingface Model Hub")]:::external
    PipRepo[(“pip” Repository)]:::external

    %% bertviz Package
    subgraph "bertviz package"
        direction TB
        util["util.py\n(Shared Utilities)"]:::backend
        click util "https://github.com/jessevig/bertviz/blob/master/bertviz/util.py"

        subgraph "Controllers\n(Python API)" 
            direction TB
            head_ctrl["head_view.py\n(Head View Controller)"]:::backend
            click head_ctrl "https://github.com/jessevig/bertviz/blob/master/bertviz/head_view.py"
            model_ctrl["model_view.py\n(Model View Controller)"]:::backend
            click model_ctrl "https://github.com/jessevig/bertviz/blob/master/bertviz/model_view.py"
            neuron_ctrl["neuron_view.py\n(Neuron View Controller)"]:::backend
            click neuron_ctrl "https://github.com/jessevig/bertviz/blob/master/bertviz/neuron_view.py"
        end

        subgraph "Front-end Widgets\n(JS & HTML)" 
            direction TB
            head_js(("head_view.js")):::frontend
            click head_js "https://github.com/jessevig/bertviz/blob/master/bertviz/head_view.js"
            model_js(("model_view.js")):::frontend
            click model_js "https://github.com/jessevig/bertviz/blob/master/bertviz/model_view.js"
            neuron_js(("neuron_view.js")):::frontend
            click neuron_js "https://github.com/jessevig/bertviz/blob/master/bertviz/neuron_view.js"
        end

        subgraph "Neuron View Adapters\n(transformers_neuron_view)" 
            direction TB
            adapters_dir["transformers_neuron_view/"]:::backend
            click adapters_dir "https://github.com/jessevig/bertviz/tree/master/bertviz/transformers_neuron_view/"
            file_utils["file_utils.py"]:::backend
            click file_utils "https://github.com/jessevig/bertviz/blob/master/bertviz/transformers_neuron_view/file_utils.py"
            bert_adapter["modeling_bert.py"]:::backend
            click bert_adapter "https://github.com/jessevig/bertviz/blob/master/bertviz/transformers_neuron_view/modeling_bert.py"
            gpt2_adapter["modeling_gpt2.py"]:::backend
            click gpt2_adapter "https://github.com/jessevig/bertviz/blob/master/bertviz/transformers_neuron_view/modeling_gpt2.py"
        end
    end

    %% Data and Models
    ModelWeights[(Transformer Model Weights)]:::data
    AttentionData[(Attention & Neuron Arrays)]:::data

    %% Tests & Fixtures
    subgraph "Test Harness & Fixtures"
        direction TB
        tests["bertviz/tests/"]:::test
        click tests "https://github.com/jessevig/bertviz/tree/master/bertviz/tests/"
        fixtures["bertviz/tests/fixtures/"]:::test
        click fixtures "https://github.com/jessevig/bertviz/tree/master/bertviz/tests/fixtures/"
        unit_tests["test_attention.py"]:::test
        click unit_tests "https://github.com/jessevig/bertviz/blob/master/bertviz/tests/test_attention.py"
    end

    %% Packaging
    setup["setup.py\n& Metadata"]:::external
    click setup "https://github.com/jessevig/bertviz/blob/master/setup.py"
    LICENSE["LICENSE"]:::external
    click LICENSE "https://github.com/jessevig/bertviz/tree/master/LICENSE"
    Gitignore[".gitignore"]:::external
    click Gitignore "https://github.com/jessevig/bertviz/blob/master/.gitignore"
    Manifest["MANIFEST.in"]:::external
    click Manifest "https://github.com/jessevig/bertviz/blob/master/MANIFEST.in"

    %% Flows
    UserNotebook -->|"invokes"| head_ctrl
    UserNotebook -->|"invokes"| model_ctrl
    UserNotebook -->|"invokes"| neuron_ctrl

    head_ctrl -->|"loads model"| HuggingfaceHub
    model_ctrl -->|"loads model"| HuggingfaceHub
    neuron_ctrl -->|"loads model via adapters"| adapters_dir

    adapters_dir -->|"uses"| bert_adapter
    adapters_dir -->|"uses"| gpt2_adapter
    adapters_dir -->|"uses"| file_utils

    head_ctrl -->|"extracts data"| AttentionData
    model_ctrl -->|"extracts data"| AttentionData
    neuron_ctrl -->|"extracts data"| AttentionData

    head_ctrl -->|"assembles payload"| head_js
    model_ctrl -->|"assembles payload"| model_js
    neuron_ctrl -->|"assembles payload"| neuron_js

    head_js -->|"renders via ipywidgets"| UserNotebook
    model_js -->|"renders via ipywidgets"| UserNotebook
    neuron_js -->|"renders via ipywidgets"| UserNotebook

    AttentionData -->|"visualized by"| head_js
    AttentionData -->|"visualized by"| model_js
    AttentionData -->|"visualized by"| neuron_js

    UserNotebook -->|"examples & docs"| README
    UserNotebook -->|"displays images"| Images

    head_ctrl --> util
    model_ctrl --> util
    neuron_ctrl --> util

    tests --> head_ctrl
    tests --> model_ctrl
    tests --> neuron_ctrl

    setup -->|"publishes"| PipRepo

    %% Styles
    classDef backend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef frontend fill:#FCF3CF,stroke:#7D6608,color:#4E342E
    classDef external fill:#FADBD8,stroke:#922B21,color:#641E16
    classDef data fill:#D5F5E3,stroke:#186A3B,color:#145A32
    classDef test fill:#E8DAEF,stroke:#6C3483,color:#4A235A
    classDef docs fill:#F2D7D5,stroke:#AF601A,color:#784212
    classDef doc fill:#FDEDEC,stroke:#C0392B,color:#78281F
```
