Metadata-Version: 2.4
Name: attnview
Version: 0.5.1
Summary: A beautiful, notebook-first HTML explorer 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
Project-URL: Documentation, https://github.com/pegruk/attnview#readme
Keywords: attention,transformers,interpretability,visualization,jupyter
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
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: notebook
Requires-Dist: ipython>=8.0; extra == "notebook"
Dynamic: license-file

# attnview

**A notebook-first, dark HTML atlas for Transformer attention patterns.**

`attnview` turns attention matrices into a focused research view: choose a layer,
head, and query position; inspect the strongest destinations; then open the exact
row or full matrix when you need to verify a detail. It is designed for
mechanistic-interpretability work in Jupyter.

![Attention Atlas screenshot](docs/assets/attention-atlas.png)

## Install

```bash
pip install -U attnview
```

For notebooks, install the optional IPython extra when IPython is not already
available:

```bash
pip install -U "attnview[notebook]"
```

## Quick start

`attention` has shape `[n_heads, query_length, key_length]`. The first sequence
axis is the query (destination) position; the second is the key (source) position.

```python
import attnview

view = attnview.display(
    attention,
    tokens=tokens,
    title="My attention study",
)
view
```

The result is a self-contained HTML object rendered inline by Jupyter. Long prompts
stay readable through a local token window and search, while the complete values
remain available in the exact-matrix panel.

## TransformerLens integration

Pass the `ActivationCache` returned by `run_with_cache`. `attnview` finds canonical
`blocks.{layer}.attn.hook_pattern` entries, ignores unrelated activations, and
combines all discovered layers into one atlas.

```python
import attnview

tokens = model.to_tokens(prompt)
logits, cache = model.run_with_cache(tokens)

view = attnview.display_cache(
    cache,
    tokens=model.to_str_tokens(tokens),
)
view
```

Export the same report as a portable artifact:

```python
attnview.export_cache(
    cache,
    "attention-atlas.html",
    tokens=model.to_str_tokens(tokens),
)
```

TransformerLens is not a runtime dependency. The adapter accepts any mapping-like
cache exposing the same pattern keys, which makes saved fixtures and small
experiments easy to inspect.

## Cross-attention and explicit labels

For encoder-decoder or other cross-attention experiments, pass query and key labels
separately:

```python
attnview.display(
    cross_attention,
    query_tokens=decoder_tokens,
    key_tokens=encoder_tokens,
)
```

## A reproducible research workflow

See the [TransformerLens research guide](docs/research-guide.md) for a complete
notebook recipe, a small attention-concentration study, interpretation cautions,
and primary-literature references.

## API at a glance

| Function | Use |
| --- | --- |
| `display` | Render one pattern or an `AttentionStudy` inline in Jupyter |
| `render_html` | Return the HTML string for custom notebook pipelines |
| `export_html` | Write one pattern to a `.html` file |
| `from_cache` | Build an `AttentionStudy` from a TransformerLens-style cache |
| `display_cache` | Render every attention layer from a cache inline |
| `export_cache` | Export a cache-backed atlas to a `.html` file |

## Development

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

Contributions and bug reports are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md)
and the [Code of Conduct](CODE_OF_CONDUCT.md) first.

## License

MIT. See [LICENSE](LICENSE).
