README.md

---
title: Transformers Architecture Inspector
emoji: 🔍
colorFrom: gray
colorTo: yellow
sdk: static
app_file: index.html
pinned: false
short_description: Inspect the semantic architecture IR of Transformers models
---

# Transformers Architecture Viewer

An interactive, web-based viewer for the **Transformers Architecture IR** — a
compact, semantic, config-parametric representation of a model architecture.

The viewer consumes the IR artifacts directly (it never inspects Transformers
Python code, never loads checkpoint weights, and never instantiates a model).
The graph layout is derived entirely from the IR: semantic components become
nodes, symbolic repeats become collapsible blocks, and coarse dataflow becomes
typed edges.

> This is a **UI prototype** for a standalone Hugging Face Space, not the final
> production Hub integration.

## What it shows

- **Semantic components** as nodes, colour-coded by kind (attention, feed-forward,
  normalization, embedding, position, …).
- **Symbolic repeats** as collapsible blocks, labelled e.g. `Decoder Layer × 32`
  (resolved against a config) or, in **config-agnostic** mode,
  `Decoder Layer × num_hidden_layers` — expanding a repeat then draws a stacked
  "deck" with a `⋯ repeated ⋯` hint to convey the fully-deployed model without
  unrolling all N instances.
- **Hub checkpoints**: a dropdown lists the most-downloaded public models on the
  Hugging Face Hub that use this architecture; picking one loads its real
  `config.json` and re-resolves every repeat count live.
- **Hierarchy** as containment boxes and **coarse dataflow** as arrows, rendered
  separately.
- **Edge kinds** as visually distinct arrows: `data`, `residual`, `mask`,
  `position`, `cross_attention` — each toggleable.
- **Provenance**, per-component **attributes** (semantic facts), model-level
  **architecture facts**, and config-derived values for the selected component.
- **On-node captions**: each node shows a shape/attribute line derived from the
  IR — e.g. `[B, S, 4096]` (observed dataflow, config-resolved) or
  `head dim 128 · n heads 32` (attributes). Toggle with *Show shapes & attributes*.
- **Colour-by-role** node fills (attention / feed-forward / normalization / …).
- **Manual repositioning**: drag any node/group to declutter edges.

### Comparison mode

The **⇄ Compare** button opens a two-architecture diff. It picks a comparison
regime from the data and renders accordingly:

- **Step 0 — regime**: if one model `extends` the other (or `modularity`
  names a parent) → *same lineage* (align by stable id). Otherwise it measures
  stable-id overlap: high → *shared ids* (align by id); low → *cross-lineage*
  (align by semantic **kind lanes**). A `modular_graph.json` forest file would
  let this also suggest lineage comparisons — the code reads lineage from each
  artifact's `extends`/`modularity` today.
- **Step 1 — headline**: the `architecture` facts side-by-side
  (`decoder · MHA · rope` vs `enc_dec · MHA · relative`), diffs highlighted.
- **Step 3 — structure**: matched nodes' `attributes` diffed (e.g. GQA shows up
  as `n_kv_heads 32 → 8`); added / removed nodes flagged. Cross-lineage pairs
  fall back to kind lanes (counts + representative attribute deltas per kind).
- **Step 4 — scale**: hidden size, resolved depth (`repeats` × `config`),
  intermediate size, vocab. Pick a Hub checkpoint per side to make it concrete.
- **Step 5 — topology**: edge-kind presence — surfaces `cross_attention`
  (enc-dec) and `cache_*` (decoder KV cache) that attribute diffs miss.

**Side-by-side graphs**: both architectures render in synced panels (pan/zoom
move together). Components present in **both** models — matched by stable id —
get a green "shared" outline in each panel, so common structure pops out while
the differences stand alone. Below the graphs sits the full textual diff report.

The viewer owns all alignment + delta math; there is no shipped pairwise-diff.
Same-lineage overlay rendering (ghosted base + highlighted patches on a single
graph) is the next step; today the side-by-side view already highlights shared
components. Current samples (llama/bert/t5) are standalone and cross-family, so
they share few components — the shared outline lights up for lineage pairs
(e.g. gemma vs llama) once those artifacts exist.

### How close can it get to a hand-drawn architecture poster?

The *visual language* (nested dashed containers, class-name headers, `× N`
badges, colour-by-role, shape/attribute captions, config-resolved dims) is fully
IR-driven and rendered generically. Two things in a richly hand-drawn diagram
are **not** reachable from the current IR without either deepening the generator
or hardcoding one architecture:

- **Sub-module detail** — `q/k/v/o_proj`, `gate/up/down_proj`, the SDPA box:
  `LlamaAttention` / `LlamaMLP` are leaves (`children: []`) in the IR. If the
  generator descends into them (and annotates dims/attributes), the viewer shows
  them automatically — no viewer change needed.
- **Task-head / runtime extras** — LM head, softmax, logits, tokenizer chips,
  the causal-mask heatmap: the artifact is the base model (`LlamaModel`), and
  tokens/masks are runtime, not architecture. These would need new IR content
  (e.g. a `…ForCausalLM` artifact) or a separate data source.

### IR spec

The viewer conforms to the current `architecture-template-v0` artifacts (as
emitted by the generator into `ir/`). It does not carry any legacy shims —
regenerate the artifacts and the viewer follows.

- **Config block**: reads `config.referenced_fields` (authoritative parametric
  surface) + `config.salient_fields` (curated scalars), merged (referenced wins)
  to drive the resolver and the editable config. The full `config.fields` blob
  is intentionally no longer produced or read.
- **Edge kinds** are discovered from the artifact, so `cache_read` / `cache_write`
  (and any future kind) get a colour, an arrowhead and a legend toggle. Kinds
  not in the known set fall back to a deterministic palette colour.
- **Pseudo endpoints**: `input:*` (e.g. attention mask) and `state:*` (e.g. the
  KV cache) render as distinct source/sink pills so cache-read/write arrows have
  visible endpoints.
- **Semantic facts**: model-level `architecture` (family / view / positional /
  attention variant / MoE) shows as a sidebar summary and on the model node;
  per-component `attributes` and the `moe` kind appear in the inspector.
- **Observed dataflow**: the `dataflow` block's per-stage symbolized shapes
  (e.g. `[B, S, config.hidden_size]`) are shown in the inspector — whole-model
  input/output on the model node, and in/out shapes on each captured component.
- **Modular inheritance**: when `modularity.is_modular` is set, the sidebar
  shows the parent model, patch count and `diff_size`.

## Tech choices

Zero-build, dependency-free **static site** (vanilla JS + SVG):

- No npm install, no bundler, no CDN — so it is CSP-safe and trivial to host on a
  `sdk: static` Space.
- Runs by serving the folder with any static file server.
- The layout engine (`js/layout.js`) is a small nested/layered graph layout; the
  resolver (`js/ir.js`) is a tiny client-side evaluator for repeat count
  expressions such as `config.num_hidden_layers`.

## Run locally

Any static server works (a server is needed because the app uses `fetch` +
ES modules, which browsers block on `file://`):

```bash
# from the repository root
python3 -m http.server 8000
# then open http://localhost:8000
```

or

```bash
npx serve .        # http://localhost:3000
```

## Deploy as a Hugging Face Space

One command pushes the app + everything under `ir/` to a static Space
(creates it on first run, then re-uploads on each call):

```bash
./deploy.sh                                  # → lysandre/transformers-architecture-inspector
./deploy.sh <owner>/<space-name>             # → your own Space
```

Requires the `hf` CLI (`pip install -U huggingface_hub`) and a logged-in session
(`hf auth login`). The script runs `hf repo create --type space --space-sdk static`
then `hf upload . .` (excluding `.git`, `.idea`, `deploy.sh`). The Space serves
`index.html` at the root and the app fetches `ir/manifest.json` + its artifacts.

## How it loads IR artifacts

The app reads the generator's output directly — **`ir/` is the single source of
truth, there is no copy step**. Point your generator's export at `ir/` and a
reload picks up the new files.

- On load it fetches **`ir/manifest.json`** and populates the **architecture
  selector** from `manifest.architectures[]` (currently `llama`, `bert`, `t5`).
- Manifest artifact paths (e.g. `artifacts/llama.json`) are resolved relative to
  the manifest, i.e. `ir/artifacts/llama.json`.
- **Hierarchy reconstruction**: most artifacts link submodules via `children`,
  but some (multimodal models like gemma3/internvl/qwen2_5_vl/siglip2) leave
  `model.children` empty and encode the tree only in dotted `path_pattern`s. The
  viewer detects orphaned components/repeats and reattaches them by path,
  synthesizing intermediate containers (`vision_tower`, `language_model`, …) so
  every model is spreadable. Well-linked models are untouched.
- You can also **upload** an IR JSON file or **paste** artifact JSON directly.
- You can **paste / edit a config** (the merged referenced + salient fields) and
  click *Apply & resolve* to re-resolve all symbolic repeat counts live.
- Or pick a **Hub checkpoint** from the dropdown to fetch its `config.json`
  (both the Hub models API and `resolve/main/config.json` are called directly
  from the browser — no backend; they return permissive CORS headers). Gated or
  private checkpoints report a clear message instead of loading.

### Where to export from the generator

Write straight to **`ir/`** (its current output dir):

```
ir/manifest.json           # architecture index
ir/artifacts/<model>.json  # one artifact per architecture
```

The `IR_BASE` constant at the top of `js/app.js` controls this location; change
it there if you want the app to read from somewhere else.

## Project layout

```
index.html          # app shell: header, sidebar, canvas, inspector
style.css           # Hugging Face-flavoured styling
js/ir.js            # IR model + client-side repeat-count resolver
js/layout.js        # nested layered graph layout derived from the IR
js/graph.js         # SVG renderer + pan/zoom/select/collapse
js/app.js           # wiring: loading, sidebar controls, inspector (IR_BASE here)
ir/manifest.json    # architecture index — the generator writes here
ir/artifacts/*.json # IR artifacts — the app reads these directly
```

## Controls

- **Scroll** to zoom, **drag the canvas** to pan, **Fit** to recenter.
- **Drag a node** to reposition it (dragging a group box moves its whole
  subtree); edges follow live. **Reset layout** clears manual positions.
- **◐** toggles light / dark theme (defaults to the HF dark palette).
- **Click** a node to inspect it; click an edge entry in the inspector to jump.
- **⊕ / ⊖** on a repeat block expands / collapses it (repeats are **expanded by
  default**). *Collapse / Expand repeats* toggle all at once.
- Sidebar: architecture selector, Hub-checkpoint dropdown, config editor,
  edge-kind toggles, config-agnostic and provenance options.

## Known limitations (prototype)

- Layout is a lightweight custom layered algorithm; very large/expanded graphs
  are readable but not crossing-optimal (no ELK/Sugiyama ordering pass).
- Expanded repeats render one representative body instance (plus a stacked-deck
  hint in config-agnostic mode), not N unrolled copies — matching the IR.
- Edge routing is straight bezier (no orthogonal routing / obstacle avoidance).
- Non-repeat containers are always expanded; only symbolic repeats collapse.
- The Hub dropdown filters by the `model_type` tag, top 30 by downloads — not an
  exhaustive search; gated checkpoints can't expose their config to the browser.
- No search / filter across components yet.

## Next steps

- Optional ELK.js layout backend for large expanded graphs.
- Component search + "focus subtree" navigation.
- Deep-link state (selected node, expand set, config) in the URL.
- Hub integration: load the IR artifact itself by `model_id` (today only the
  `config.json` is fetched from the Hub; the IR still comes from `ir/`).
- Diff view between two configs (e.g. base vs. resolved layer counts).