Metadata-Version: 2.4
Name: attnview
Version: 0.1.0
Summary: Beautiful terminal and HTML views for transformer attention patterns.
Author-email: Pedro Gustavo <pedrogustavosilva3060@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pegruk/attnview
Project-URL: Issues, https://github.com/pegruk/attnview/issues
Keywords: attention,transformers,interpretability,visualization,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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.

```bash
pip install attnview
```

```python
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

```python
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](https://github.com/Textualize/rich). NumPy and PyTorch are
not required: if they are installed, their arrays/tensors are accepted directly.

## Development

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

## License

MIT
