attnview 0.1.0__tar.gz

attnview-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Gustavo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

attnview-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+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

attnview-0.1.0/README.md

@@ -0,0 +1,70 @@
+# 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

attnview-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "attnview"
+version = "0.1.0"
+description = "Beautiful terminal and HTML views for transformer attention patterns."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Pedro Gustavo", email = "pedrogustavosilva3060@gmail.com"}]
+keywords = ["attention", "transformers", "interpretability", "visualization", "terminal"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["rich>=13.7"]
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8.0", "twine>=5.0"]
+
+[project.urls]
+Homepage = "https://github.com/pegruk/attnview"
+Issues = "https://github.com/pegruk/attnview/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

attnview-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

attnview-0.1.0/src/attnview/__init__.py

@@ -0,0 +1,7 @@
+"""A focused, terminal-first viewer for transformer attention patterns."""
+
+from .api import render_html, show
+from .model import AttentionPattern, AttentionShapeError
+
+__all__ = ["AttentionPattern", "AttentionShapeError", "render_html", "show"]
+__version__ = "0.1.0"

attnview-0.1.0/src/attnview/api.py

@@ -0,0 +1,66 @@
+"""Public API for terminal and standalone HTML attention visualizations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Sequence
+
+from rich.console import Console
+
+from .html import build_html
+from .model import AttentionPattern
+from .terminal import build_terminal
+
+
+def show(
+    attention: Any,
+    *,
+    tokens: Sequence[str] | None = None,
+    query_tokens: Sequence[str] | None = None,
+    key_tokens: Sequence[str] | None = None,
+    head: int = 0,
+    output: str | Path | None = None,
+    top_k: int = 3,
+    title: str = "Attention Explorer",
+    console: Console | None = None,
+) -> Path | None:
+    """Show `[heads, queries, keys]` attention in the terminal or write HTML.
+
+    `output=None` prints a Rich-rendered view. Pass a path ending in `.html` to
+    write a portable interactive report. The return value is that path for HTML
+    output and `None` for terminal output.
+    """
+    pattern = AttentionPattern.from_data(
+        attention, tokens=tokens, query_tokens=query_tokens, key_tokens=key_tokens
+    )
+    pattern.head(head)
+    if top_k < 1:
+        raise ValueError("top_k must be at least 1")
+    if output is None:
+        (console or Console()).print(build_terminal(pattern, head=head, top_k=top_k, title=title))
+        return None
+    path = Path(output)
+    if path.suffix.lower() != ".html":
+        raise ValueError("output must be an .html path")
+    path.write_text(build_html(pattern, head=head, top_k=top_k, title=title), encoding="utf-8")
+    return path
+
+
+def render_html(
+    attention: Any,
+    *,
+    tokens: Sequence[str] | None = None,
+    query_tokens: Sequence[str] | None = None,
+    key_tokens: Sequence[str] | None = None,
+    head: int = 0,
+    top_k: int = 3,
+    title: str = "Attention Explorer",
+) -> str:
+    """Return a self-contained interactive HTML report as a string."""
+    pattern = AttentionPattern.from_data(
+        attention, tokens=tokens, query_tokens=query_tokens, key_tokens=key_tokens
+    )
+    pattern.head(head)
+    if top_k < 1:
+        raise ValueError("top_k must be at least 1")
+    return build_html(pattern, head=head, top_k=top_k, title=title)

attnview-0.1.0/src/attnview/html.py

@@ -0,0 +1,75 @@
+"""Standalone, dependency-free HTML report generation."""
+
+from __future__ import annotations
+
+import html
+import json
+
+from .model import AttentionPattern
+
+
+_DOCUMENT = '''<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>__TITLE__</title><style>
+:root{--ink:#0b141d;--surface:#121f2b;--line:#294253;--muted:#91a9b8;--paper:#e8f0f3;--cyan:#51c5c1;--amber:#f2b84b}
+*{box-sizing:border-box}body{margin:0;background:var(--ink);color:var(--paper);font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:1240px;margin:auto;padding:42px 28px 64px}header{display:flex;justify-content:space-between;align-items:end;border-bottom:1px solid var(--line);padding-bottom:22px;margin-bottom:28px;gap:20px}
+h1{font-size:clamp(1.7rem,4vw,2.8rem);letter-spacing:-.045em;margin:0}header p{margin:7px 0 0;color:var(--muted)}select{background:var(--surface);color:var(--paper);border:1px solid var(--line);border-radius:7px;padding:10px 12px;font:inherit}
+.workspace{display:grid;grid-template-columns:minmax(0,1fr) 270px;gap:22px}.plot,.detail,.heads{background:var(--surface);border:1px solid var(--line);border-radius:12px}.plot{padding:22px;overflow:auto}.axis{color:var(--muted);font-size:.82rem;margin-bottom:10px}
+.heatmap{display:grid;gap:2px;min-width:500px;width:min(100%,720px)}.cell{aspect-ratio:1;border:0;border-radius:2px;cursor:pointer;min-width:12px}.cell:hover,.cell.selected{outline:2px solid var(--paper);outline-offset:1px;z-index:1}.labels{display:grid;gap:2px;min-width:396px;width:calc(min(100% - 104px,616px));margin-left:104px;margin-bottom:5px}.label{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;text-align:center;color:#bbcad3;font:12px ui-monospace,SFMono-Regular,Menlo,monospace}
+.side{display:grid;gap:22px;align-content:start}.detail{padding:20px}.detail h2,.heads h2{font-size:.95rem;margin:0 0 16px;color:#c9d8df}.pair{font:600 1.15rem ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--amber);margin:6px 0 16px}.metric{display:flex;justify-content:space-between;padding:8px 0;border-top:1px solid var(--line);color:var(--muted)}.metric strong{color:var(--paper);font-weight:600}
+.heads{padding:18px;margin-top:22px}.head-list{display:flex;gap:10px;overflow:auto}.mini{min-width:88px;background:#0d1923;border:1px solid #254153;border-radius:7px;padding:7px;cursor:pointer;color:var(--muted);font-size:.77rem}.mini.active{border-color:var(--cyan);color:var(--paper)}.mini-grid{display:grid;grid-template-columns:repeat(6,1fr);gap:1px;height:48px;margin-bottom:6px}.mini-cell{display:block;border-radius:1px}
+footer{color:var(--muted);font-size:.84rem;margin-top:25px}@media(max-width:780px){main{padding:24px 14px}header{align-items:start;flex-direction:column}.workspace{grid-template-columns:1fr}.side{grid-template-columns:1fr 1fr}.heads{margin-top:16px}}@media(max-width:520px){.side{grid-template-columns:1fr}}
+</style></head><body><main><header><div><h1>__TITLE__</h1><p>Attention as a map: query rows, key columns.</p></div><label>Head <select id="head"></select></label></header><section class="workspace"><div class="plot"><div class="axis">K · attended-to token →</div><div id="key-labels" class="labels"></div><div class="axis">Q · attending token ↓</div><div id="heatmap" class="heatmap" role="grid" aria-label="Attention heatmap"></div></div><aside class="side"><section class="detail"><h2>Selected relation</h2><div id="pair" class="pair"></div><div class="metric"><span>Attention</span><strong id="weight"></strong></div><div class="metric"><span>Rank within query</span><strong id="rank"></strong></div><div class="metric"><span>Top keys</span><strong id="top"></strong></div></section></aside></section><section class="heads"><h2>All heads</h2><div id="head-list" class="head-list"></div></section><footer>Amber indicates high attention; teal indicates moderate attention. Click a cell to inspect it.</footer></main>
+<script>
+const data = __DATA__;
+let selected = {h: data.head, q: 0, k: 0};
+const $ = id => document.getElementById(id);
+const max = array => Math.max(...array.flat(2));
+function color(value, maximum) {
+  const ratio = Math.max(0, Math.min(1, value / (maximum || 1)));
+  const stops = [[11,20,32],[20,56,75],[46,146,151],[242,184,75]];
+  const position = ratio * (stops.length - 1), index = Math.min(Math.floor(position), stops.length - 2), mix = position - index;
+  const a = stops[index], b = stops[index + 1];
+  return `rgb(${Math.round(a[0]*(1-mix)+b[0]*mix)},${Math.round(a[1]*(1-mix)+b[1]*mix)},${Math.round(a[2]*(1-mix)+b[2]*mix)})`;
+}
+function drawHeads(maximum) {
+  const list = $('head-list'); list.innerHTML = '';
+  data.heads.forEach((rows, head) => {
+    const button = document.createElement('button'); button.className = 'mini' + (head === selected.h ? ' active' : '');
+    const values = rows.flat(), sample = Array.from({length: 36}, (_, index) => values[Math.floor(index * values.length / 36)]);
+    button.innerHTML = `<div class="mini-grid">${sample.map(value => `<i class="mini-cell" style="background:${color(value, maximum)}"></i>`).join('')}</div>Head ${head + 1}`;
+    button.onclick = () => { selected = {h: head, q: 0, k: 0}; draw(); }; list.append(button);
+  });
+}
+function draw() {
+  const rows = data.heads[selected.h], maximum = max(data.heads), count = data.keys.length;
+  $('head').value = selected.h;
+  const labels = $('key-labels'); labels.style.gridTemplateColumns = `repeat(${count}, 1fr)`;
+  labels.innerHTML = data.keys.map(key => `<div class="label" title="${key}">${key}</div>`).join('');
+  const grid = $('heatmap'); grid.style.gridTemplateColumns = `96px repeat(${count}, 1fr)`; grid.innerHTML = '';
+  rows.forEach((row, query) => {
+    const label = document.createElement('div'); label.className = 'label'; label.style.textAlign = 'right'; label.style.paddingRight = '10px'; label.textContent = data.queries[query]; grid.append(label);
+    row.forEach((value, key) => {
+      const cell = document.createElement('button'); cell.className = 'cell' + (query === selected.q && key === selected.k ? ' selected' : '');
+      cell.style.background = color(value, maximum); cell.title = `${data.queries[query]} → ${data.keys[key]}: ${value.toFixed(4)}`;
+      cell.onclick = () => { selected.q = query; selected.k = key; draw(); }; grid.append(cell);
+    });
+  });
+  const values = rows[selected.q], value = values[selected.k], rank = values.filter(item => item > value).length + 1;
+  const top = [...values.keys()].sort((a,b) => values[b] - values[a]).slice(0, data.topK).map(index => data.keys[index]).join(', ');
+  $('pair').textContent = `${data.queries[selected.q]} → ${data.keys[selected.k]}`; $('weight').textContent = value.toFixed(4); $('rank').textContent = '#' + rank; $('top').textContent = top;
+  drawHeads(maximum);
+}
+data.heads.forEach((_, index) => $('head').insertAdjacentHTML('beforeend', `<option value="${index}">Head ${index + 1}</option>`));
+$('head').onchange = event => { selected = {h: +event.target.value, q: 0, k: 0}; draw(); };
+draw();
+</script></body></html>'''
+
+
+def build_html(pattern: AttentionPattern, *, head: int, top_k: int, title: str) -> str:
+    payload = json.dumps(
+        {"heads": pattern.values, "queries": pattern.query_tokens, "keys": pattern.key_tokens, "head": head, "topK": top_k},
+        ensure_ascii=False,
+    ).replace("</", "<\\/")
+    return _DOCUMENT.replace("__DATA__", payload).replace("__TITLE__", html.escape(title))

attnview-0.1.0/src/attnview/model.py

@@ -0,0 +1,115 @@
+"""Input normalization and validation for attention patterns."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isfinite
+from typing import Any, Sequence
+
+
+class AttentionShapeError(ValueError):
+    """Raised when an object cannot represent a 3D attention pattern."""
+
+
+def _to_nested_list(value: Any) -> list[Any]:
+    """Accept NumPy/PyTorch-like values without making either a dependency."""
+    if hasattr(value, "detach"):
+        value = value.detach()
+    if hasattr(value, "cpu"):
+        value = value.cpu()
+    if hasattr(value, "tolist"):
+        value = value.tolist()
+    if not isinstance(value, (list, tuple)):
+        raise AttentionShapeError("attention must be a 3D sequence or array")
+    return list(value)
+
+
+def _float(value: Any) -> float:
+    try:
+        number = float(value)
+    except (TypeError, ValueError) as error:
+        raise AttentionShapeError("attention values must be numeric") from error
+    if not isfinite(number):
+        raise AttentionShapeError("attention values must be finite")
+    return number
+
+
+def _labels(values: Sequence[str] | None, length: int, prefix: str) -> tuple[str, ...]:
+    if values is None:
+        return tuple(f"{prefix}{index}" for index in range(length))
+    labels = tuple(str(value) for value in values)
+    if len(labels) != length:
+        raise AttentionShapeError(
+            f"expected {length} {prefix.lower()} token labels, received {len(labels)}"
+        )
+    return labels
+
+
+@dataclass(frozen=True)
+class AttentionPattern:
+    """A validated `[heads, queries, keys]` attention tensor."""
+
+    values: tuple[tuple[tuple[float, ...], ...], ...]
+    query_tokens: tuple[str, ...]
+    key_tokens: tuple[str, ...]
+
+    @classmethod
+    def from_data(
+        cls,
+        attention: Any,
+        *,
+        tokens: Sequence[str] | None = None,
+        query_tokens: Sequence[str] | None = None,
+        key_tokens: Sequence[str] | None = None,
+    ) -> "AttentionPattern":
+        if tokens is not None and (query_tokens is not None or key_tokens is not None):
+            raise AttentionShapeError("use `tokens` or explicit query/key tokens, not both")
+        data = _to_nested_list(attention)
+        if not data:
+            raise AttentionShapeError("attention must contain at least one head")
+        heads: list[tuple[tuple[float, ...], ...]] = []
+        query_length: int | None = None
+        key_length: int | None = None
+        for head in data:
+            if not isinstance(head, (list, tuple)) or not head:
+                raise AttentionShapeError("every head must contain at least one query row")
+            rows: list[tuple[float, ...]] = []
+            for row in head:
+                if not isinstance(row, (list, tuple)) or not row:
+                    raise AttentionShapeError("every query row must contain at least one key")
+                values = tuple(_float(item) for item in row)
+                if key_length is None:
+                    key_length = len(values)
+                elif len(values) != key_length:
+                    raise AttentionShapeError("all query rows must have the same key length")
+                rows.append(values)
+            if query_length is None:
+                query_length = len(rows)
+            elif len(rows) != query_length:
+                raise AttentionShapeError("all heads must have the same query length")
+            heads.append(tuple(rows))
+        assert query_length is not None and key_length is not None
+        if tokens is not None and query_length != key_length:
+            raise AttentionShapeError("`tokens` is only valid when query and key lengths match")
+        return cls(
+            values=tuple(heads),
+            query_tokens=_labels(tokens if tokens is not None else query_tokens, query_length, "Q"),
+            key_tokens=_labels(tokens if tokens is not None else key_tokens, key_length, "K"),
+        )
+
+    @property
+    def head_count(self) -> int:
+        return len(self.values)
+
+    @property
+    def query_length(self) -> int:
+        return len(self.values[0])
+
+    @property
+    def key_length(self) -> int:
+        return len(self.values[0][0])
+
+    def head(self, index: int) -> tuple[tuple[float, ...], ...]:
+        if not 0 <= index < self.head_count:
+            raise IndexError(f"head must be in [0, {self.head_count - 1}], received {index}")
+        return self.values[index]

attnview-0.1.0/src/attnview/terminal.py

@@ -0,0 +1,65 @@
+"""Rich terminal rendering."""
+
+from __future__ import annotations
+
+from rich import box
+from rich.columns import Columns
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .model import AttentionPattern
+
+
+def _colour(value: float, maximum: float) -> str:
+    ratio = 0 if maximum <= 0 else max(0.0, min(1.0, value / maximum))
+    # Ink -> deep blue -> teal -> amber. Designed for dark terminals.
+    stops = ((11, 20, 32), (20, 56, 75), (46, 146, 151), (242, 184, 75))
+    position = ratio * (len(stops) - 1)
+    left = min(int(position), len(stops) - 2)
+    mix = position - left
+    rgb = tuple(round(stops[left][i] * (1 - mix) + stops[left + 1][i] * mix) for i in range(3))
+    return "#%02x%02x%02x" % rgb
+
+
+def _short(label: str, width: int = 9) -> str:
+    return label if len(label) <= width else label[: width - 1] + "…"
+
+
+def build_terminal(pattern: AttentionPattern, *, head: int, top_k: int, title: str) -> Panel:
+    matrix = pattern.head(head)
+    maximum = max(value for row in matrix for value in row)
+    table = Table(box=box.SIMPLE_HEAVY, pad_edge=False, show_header=True, header_style="bold #b9c9d7")
+    table.add_column("Q ↓ / K →", style="#b9c9d7", no_wrap=True)
+    for token in pattern.key_tokens:
+        table.add_column(_short(token), justify="center", width=3, no_wrap=True)
+    for token, row in zip(pattern.query_tokens, matrix):
+        cells = [
+            Text("██", style=f"{_colour(value, maximum)} on {_colour(value, maximum)}")
+            for value in row
+        ]
+        table.add_row(_short(token), *cells)
+
+    strongest = max(range(pattern.query_length), key=lambda index: max(matrix[index]))
+    ranking = sorted(enumerate(matrix[strongest]), key=lambda item: item[1], reverse=True)[:top_k]
+    summary = Table.grid(padding=(0, 1))
+    summary.add_column(style="bold #f2b84b")
+    summary.add_column(justify="right", style="#e6edf3")
+    for index, value in ranking:
+        summary.add_row(_short(pattern.key_tokens[index], 16), f"{value:.3f}")
+    sidebar = Panel(
+        summary,
+        title=f"Top keys for {_short(pattern.query_tokens[strongest], 16)}",
+        subtitle="strongest query",
+        border_style="#27626a",
+        padding=(1, 1),
+    )
+    layout = Columns([table, sidebar], expand=False, padding=(2, 0))
+    caption = "Rows are queries; columns are keys.  Use `head=` to inspect another head."
+    return Panel(
+        layout,
+        title=f"[bold #e6edf3]{title}[/]  [#6f93a8]head {head + 1}/{pattern.head_count} · {pattern.query_length} Q × {pattern.key_length} K[/]",
+        subtitle=f"[#76d4d4]{caption}[/]",
+        border_style="#315166",
+        padding=(1, 1),
+    )

attnview-0.1.0/src/attnview.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+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

attnview-0.1.0/src/attnview.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/attnview/__init__.py
+src/attnview/api.py
+src/attnview/html.py
+src/attnview/model.py
+src/attnview/terminal.py
+src/attnview.egg-info/PKG-INFO
+src/attnview.egg-info/SOURCES.txt
+src/attnview.egg-info/dependency_links.txt
+src/attnview.egg-info/requires.txt
+src/attnview.egg-info/top_level.txt
+tests/test_attnview.py

attnview-0.1.0/src/attnview.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

attnview-0.1.0/src/attnview.egg-info/requires.txt

@@ -0,0 +1,6 @@
+rich>=13.7
+
+[dev]
+build>=1.2
+pytest>=8.0
+twine>=5.0

attnview-0.1.0/src/attnview.egg-info/top_level.txt

@@ -0,0 +1 @@
+attnview

attnview-0.1.0/tests/test_attnview.py

@@ -0,0 +1,69 @@
+from pathlib import Path
+
+import pytest
+from rich.console import Console
+
+import attnview
+
+
+ATTENTION = [
+    [[0.05, 0.85, 0.10], [0.20, 0.30, 0.50], [0.70, 0.20, 0.10]],
+    [[0.30, 0.20, 0.50], [0.60, 0.30, 0.10], [0.15, 0.70, 0.15]],
+]
+TOKENS = ["The", "cat", "sat"]
+
+
+def test_pattern_accepts_self_attention_tokens():
+    pattern = attnview.AttentionPattern.from_data(ATTENTION, tokens=TOKENS)
+    assert pattern.head_count == 2
+    assert pattern.query_length == pattern.key_length == 3
+    assert pattern.query_tokens == pattern.key_tokens == tuple(TOKENS)
+
+
+def test_pattern_accepts_cross_attention_labels():
+    pattern = attnview.AttentionPattern.from_data(
+        [[[0.2, 0.8], [0.7, 0.3]]], query_tokens=["decode", "next"], key_tokens=["a", "b"]
+    )
+    assert pattern.query_tokens == ("decode", "next")
+    assert pattern.key_tokens == ("a", "b")
+
+
+@pytest.mark.parametrize(
+    "data, message",
+    [([], "at least one head"), ([[[1.0], [0.3, 0.7]]], "same key length"), ([[[float('nan')]]], "finite")],
+)
+def test_invalid_shapes_are_explained(data, message):
+    with pytest.raises(attnview.AttentionShapeError, match=message):
+        attnview.AttentionPattern.from_data(data)
+
+
+def test_terminal_show_renders_tokens_and_axis_labels():
+    console = Console(record=True, width=120, force_terminal=False)
+    result = attnview.show(ATTENTION, tokens=TOKENS, head=1, console=console)
+    output = console.export_text()
+    assert result is None
+    assert "Attention Explorer" in output
+    assert "The" in output and "cat" in output
+    assert "Top keys" in output
+
+
+def test_html_output_is_standalone_and_interactive(tmp_path: Path):
+    target = tmp_path / "report.html"
+    returned = attnview.show(ATTENTION, tokens=TOKENS, output=target, title="My map")
+    report = target.read_text(encoding="utf-8")
+    assert returned == target
+    assert "My map" in report
+    assert "Selected relation" in report
+    assert "data.heads.forEach" in report
+    assert "Head ${index + 1}" in report
+    assert "The" in report
+
+
+def test_render_html_rejects_non_positive_top_k():
+    with pytest.raises(ValueError, match="at least 1"):
+        attnview.render_html(ATTENTION, tokens=TOKENS, top_k=0)
+
+
+def test_output_requires_html_suffix(tmp_path: Path):
+    with pytest.raises(ValueError, match=".html"):
+        attnview.show(ATTENTION, tokens=TOKENS, output=tmp_path / "report.txt")