Metadata-Version: 2.4
Name: attnview
Version: 0.2.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` mostra padrões de atenção de Transformers no terminal ou em um HTML
interativo. A entrada é uma camada no formato `[n_heads, query_length, key_length]`:
linhas são **queries**; colunas são **keys**.

## Comece aqui — dois comandos

```bash
pip install --upgrade attnview
```

Quer saber se está funcionando? Rode exatamente isto:

```bash
attnview demo
```

Você verá os pesos de uma query, com tokens e posições explícitos. Para gerar o relatório HTML:

```bash
attnview demo --output attention.html
```

O comando informa o caminho do arquivo. Abra `attention.html` no navegador; não
há servidor para iniciar nem URL para procurar.

## Use com sua atenção real

```python
import attnview

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

# Cria o arquivo HTML e informa onde ele foi salvo.
attnview.show(attention, tokens=tokens, output="attention.html")
```

Se seus dados já estão em JSON, você também pode renderizá-los diretamente:

```bash
attnview render attention.json --tokens tokens.json
attnview render attention.json --tokens tokens.json --output attention.html
```

`attention.json` contém a matriz `[heads, queries, keys]`; `tokens.json` é uma
lista como `["[BOS]", "The", "cat", "sat", "."]`.

## Como ler a tela

A versão 0.2 começa pela pergunta: **para quais keys esta query distribui atenção?**
Escolha `query=2` na API ou `--query 2` no terminal. No HTML, clique no token;
trocar de head preserva essa seleção. Todos os índices começam em zero.

Os destinos aparecem na ordem da sequência, acompanhados do peso bruto. No HTML,
você pode ordenar a tabela por peso ou abrir a matriz completa. Barras representam
magnitude relativa ao maior peso absoluto da query; os dados não são normalizados.
O terminal imprime um relatório estático, inclusive sem cores; não é uma TUI.

- **Rows are queries**: the token doing the attending.
- **Columns are keys**: the token being attended to.
- Repeated tokens are distinguished by their sequence positions.
- Weight displays use six significant digits; the expanded HTML matrix exposes
  the stored numeric values.

## API Python

```python
attnview.show(
    attention,
    tokens=None,
    query_tokens=None,
    key_tokens=None,
    head=0,
    query=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
