Metadata-Version: 2.4
Name: attnview
Version: 0.4.2
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
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

`attnview` é um explorador HTML para pesquisa de atenção em Transformers. A
interface foi feita para notebooks: ela começa com uma pergunta (`query`), mostra
os tokens que essa posição consulta e deixa a matriz completa como inspeção
secundária.

## O caso normal: uma célula de notebook

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

```python
import attnview

# attention: [n_heads, query_length, key_length]
attnview.display(attention, tokens=tokens)
```

O resultado é um relatório interativo dentro do notebook. Você pode trocar
camada, head e query; procurar um token; ver os maiores destinos; ordenar todos
os pesos; e abrir a matriz exata quando precisar conferir um detalhe.

## Prompts longos

O relatório não tenta colocar todos os tokens em uma linha. Ele mostra uma janela
ao redor da query selecionada, com um campo de busca para saltar diretamente para
qualquer posição. Nenhum valor é descartado: a tabela e a matriz completa ficam
disponíveis abaixo.

## TransformerLens

Passe o `ActivationCache` retornado por `model.run_with_cache(...)`. O adaptador
procura automaticamente os padrões `("pattern", layer)` e reúne todas as camadas
em um único relatório.

```python
import attnview

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

Para salvar o mesmo relatório:

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

TransformerLens não é uma dependência obrigatória. A integração aceita qualquer
objeto com a mesma interface de cache; para dados sem cache, use `display`.

## Exportar um padrão

```python
attnview.export_html(attention, "attention.html", tokens=tokens)
```

Use `query_tokens` e `key_tokens` separadamente para cross-attention. Os pesos
exibidos são os valores brutos fornecidos; o relatório não os normaliza e não
afirma causalidade a partir deles.

## Instalação para notebooks

Jupyter normalmente já instala IPython. Se necessário:

```bash
pip install 'attnview[notebook]'
```

## Desenvolvimento

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

## Licença

MIT
