---

name: bertviz description: "Route BertViz Transformer attention visualization, neuron-view, notebook, and HTML export workflows." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

BertViz

Use this repo skill when a task involves BertViz, Transformer attention visualization, head/model view rendering, neuron-level query/key inspection, or saving BertViz notebook visualizations as HTML.

Install and quick check

For ordinary use:

pip install bertviz

For interactive notebooks also install and enable a notebook frontend such as JupyterLab plus widgets:

pip install jupyterlab ipywidgets

Minimal package/API check:

python - <<'PY'
from bertviz import head_view, model_view
from bertviz.neuron_view import get_attention
print("bertviz import ok", head_view.__name__, model_view.__name__, get_attention.__name__)
PY

For a stronger no-network check, run scripts/check_bertviz_environment.py.

Route by task

User need	Read next
Visualize standard self-attention tensors from Hugging Face or another Transformer model.	sub-skills/attention-views/SKILL.md
Render sentence-pair head/model views with sentence_b_start.	sub-skills/attention-views/SKILL.md
Render encoder, decoder, or cross-attention for sequence-to-sequence models.	sub-skills/attention-views/SKILL.md
Save BertViz output as standalone HTML or use it outside a notebook display call.	sub-skills/attention-views/SKILL.md, or sub-skills/neuron-view/SKILL.md for neuron view
Inspect query/key neuron contributions using BertViz's modified model classes.	sub-skills/neuron-view/SKILL.md
Diagnose package installation, notebook display, PyTorch/IPython dependency, or JS asset issues.	references/troubleshooting.md
Check whether this skill matches the current BertViz checkout/version.	references/repo-provenance.md

Core distinctions

• head_view and model_view consume attention tensors. They are the right choice when the model can return Hugging Face-style attention weights with output_attentions=True.
• neuron_view.show computes a visualization payload from BertViz's modified BERT/GPT-2/RoBERTa/XLNet classes because neuron view needs query and key vectors, not only attention probabilities.
• BertViz is a visualization tool, not a model explanation guarantee. It helps inspect attention patterns but should not be presented as proving causal feature attribution.

Repo-level references and scripts

• references/environment-and-install.md explains dependencies, notebook frontend expectations, backend assumptions, and offline validation strategy.
• references/troubleshooting.md covers cross-cutting install/import/display/runtime symptoms.
• references/repo-provenance.md records the source snapshot and evidence paths used to build this skill.
• scripts/check_bertviz_environment.py checks imports, function signatures, packaged JavaScript assets, and optional neuron-view imports without downloading models.

Safety defaults

• Do not run public notebooks or from_pretrained(...) examples automatically when network/model downloads are not explicitly allowed.
• Prefer bundled no-network helpers for validation: the root environment check, attention-views/scripts/render_synthetic_attention.py, and neuron-view/scripts/validate_toy_bert_attention.py.
• Keep generated outputs and saved HTML in user-chosen working directories; BertViz does not require modifying its installed package files.