attnview

attnview is a small, terminal-first viewer for transformer attention patterns. It accepts a single attention layer shaped [n_heads, query_length, key_length], keeps query and key axes explicit, and renders either a readable terminal heatmap or a self-contained interactive HTML report.

pip install attnview

import attnview

# `attention` can be a NumPy array, a PyTorch tensor, or nested Python sequences.
attnview.show(attention, tokens=["[BOS]", "The", "cat", "sat", "."])

# Write a standalone report that can be opened or shared without a server.
attnview.show(attention, tokens=tokens, output="attention.html")

Reading the view

• Rows are queries: the token doing the attending.
• Columns are keys: the token being attended to.
• The selected head is rendered in the main heatmap; the HTML report also offers one-click head selection through miniature maps.
• Amber marks high attention, teal marks moderate attention, and the darkest cells are near zero. This deliberately avoids a rainbow palette that makes magnitude difficult to read.

API

attnview.show(
    attention,
    tokens=None,
    query_tokens=None,
    key_tokens=None,
    head=0,
    output=None,
    top_k=3,
    title="Attention Explorer",
)

Pass tokens for self-attention. For cross-attention, pass query_tokens and key_tokens independently. With output=None (the default), show prints to the current terminal. With an .html path, it writes a standalone HTML document and returns its Path.

render_html(...) returns the standalone HTML string when embedding it elsewhere.

Requirements

Python 3.10+ and Rich. NumPy and PyTorch are not required: if they are installed, their arrays/tensors are accepted directly.

Development

python -m pip install -e '.[dev]'
python -m pytest
python -m build
python -m twine check dist/*

License

MIT