AI Model X-Ray analyzes the structural health of transformer models by
examining how attention heads relate to each other. It reveals which
layers are structurally redundant (safe to compress) and which are
critical (removing heads would break the model).
The metrics
Coherence Ratio (ρ)
Measures how much triangular redundancy exists in each layer's attention
graph. Range 0 to 1.
ρ close to 1.0: heads share backup paths. High redundancy.
ρ close to 0.5: moderate redundancy. Prune with caution.
ρ below 0.5: low redundancy. Each head is critical.
n/a: not enough triangular structure to measure.
Fragility Index (FI)
Percentage of connections that have NO triangular backup. Lower is
stronger. FI = 0% means every connection has a backup path.
Structural Integrity
Overall health score (0–100), computed from the global FI.
100 = fully redundant. Below 50 = structurally fragile.
The risk map
Each card represents one layer of the model.
🟢 Immune (green): ρ > 0.8, FI = 0. Safe to prune heads here.
🟡 Buffer (amber): ρ 0.5–0.8. Prune with caution.
🔴 Critical (red): ρ < 0.5. Do not remove heads from this layer.
⬜ n/a: insufficient triangular structure to classify.
The science
Based on the spectral simplicial hierarchy
λ₂(T(G)) ≤ λ₂(G):
algebraic connectivity can only decrease when moving from the edge graph
to the triangle graph. Validated on 45,000+ graphs with zero violations.
Formally verified in Lean 4.
In practice: if a layer's attention heads form many triangles (groups of
3 mutually correlated heads), the layer has structural backup. If they
don't, each head is a single point of failure.
Built by Cognitive Engineering 🇨🇭
cognitive-engineering.dev
"""
# ===========================================================================
# Small formatting helpers
# ===========================================================================
def _fnum(x, d=3):
return "—" if x is None else f"{x:.{d}f}"
def _params_to_millions(params):
"""'110M' -> 110.0, '1.1B' -> 1100.0, None -> None."""
if not params:
return None
s = params.strip().upper()
try:
if s.endswith("B"):
return float(s[:-1]) * 1000.0
if s.endswith("M"):
return float(s[:-1])
return float(s) / 1e6
except ValueError:
return None
# ===========================================================================
# Renderers (pure: result/summary -> HTML)
# ===========================================================================
def render_gauge(score, label, color):
"""270-degree arc gauge for the structural-integrity score."""
r = 80
cx = cy = 100
arc = 0.75 # fraction of the full circle drawn (270 deg)
c = 2 * math.pi * r
track_dash = f"{arc * c:.1f} {c:.1f}"
val_len = arc * c * max(0.0, min(100.0, score)) / 100.0
val_dash = f"{val_len:.1f} {c:.1f}"
# rotate so the 90-degree gap sits centred at the bottom
rot = "transform:rotate(135deg);transform-origin:100px 100px;"
return (
"
"
)
cells = []
for rec in result["per_layer"]:
L = rec["layer"]
regime = ax.classify_regime(rec)
color = REGIME_COLOR[regime]
rho = rec.get("rho")
rho_s = "n/a" if rho is None else f"{rho:.2f}"
sel = " sel" if selected == L else ""
cells.append(
f"
"
f""
f"
LAYER {L}
"
f"
{rho_s}
"
f"
{regime}
"
"
"
)
return pills + "
" + "".join(cells) + "
"
def render_spectral(result):
"""Horizontal ρ-per-layer bars. Each bar is colored by regime and scaled
0..1 (so ρ=0.56 is ~56% width); layers where ρ is undefined show a thin gray
'n/a' bar. The ρ value is printed inside the bar, left-aligned."""
rows = []
for rec in result["per_layer"]:
L = rec["layer"]
rho = rec.get("rho")
if rho is None:
color = "#3a3d50" # gray — ρ undefined (T(G) disconnected)
width = 14.0 # thin stub so n/a never reads as a full bar
label = "n/a"
else:
color = REGIME_COLOR[ax.classify_regime(rec)]
width = max(4.0, min(1.0, rho) * 100.0) # 0..1 scale, tiny floor
label = f"{rho:.2f}"
rows.append(
"
"
f"L{L}"
"
"
f""
f"{label}"
"
"
)
return "
" + "".join(rows) + "
"
def render_layer_detail(result, selected):
if selected is None or selected >= len(result["per_layer"]):
return ("
Click a layer card in the "
"risk map (or use the selector above) to inspect it.
")
rec = result["per_layer"][selected]
regime = ax.classify_regime(rec)
meta = ax.REGIME_META[regime]
color = meta["color"]
rho = rec.get("rho")
l2tg = "—" if not rec["eligible"] else _fnum(rec["l2TG"])
elig = "yes" if rec["eligible"] else "no"
fi_pct = (rec.get("fi") or 0.0) * 100.0
return (
"
ρ = λ₂(T)/λ₂(G)"
f"{'n/a' if rho is None else f'{rho:.3f}'}
"
f"
λ₂(G){_fnum(rec['l2G'])}
"
f"
λ₂(T(G)){l2tg}
"
f"
Fragility (FI){fi_pct:.2f}%
"
f"
Edges in graph{rec['edges']}
"
f"
Heads{result['n_heads']}
"
f"
Eligible{elig}
"
"
"
)
def render_comparison(result, summary):
rows = ax.reference_rows()
body = []
for r in rows:
body.append(
"
" + html.escape(r["model"]) + "
"
f"
{_fnum(r['rho_mean'],2)}
"
f"
{_fnum(r['fi_base'],3)}
"
f"
{html.escape(r['modality'].title())}
"
)
rho = summary["rho_mean"]
me = (
"
→ " + html.escape(result["label"]) + "
"
f"
{'n/a' if rho is None else f'{rho:.2f}'}
"
f"
{summary['fi_head']:.3f}
"
f"
{html.escape(result['modality'].title())}
"
)
return (
"
"
"
Model
ρ mean
FI
Type
"
+ "".join(body) + me + "
"
)
def render_pruning(result, summary):
immune = [r for r in result["per_layer"] if ax.classify_regime(r) == "immune"]
critical = [r for r in result["per_layer"] if ax.classify_regime(r) == "critical"]
n_heads = result["n_heads"]
total_heads = result["n_layers"] * n_heads
immune_heads = len(immune) * n_heads
pct = (immune_heads / total_heads * 100.0) if total_heads else 0.0
# Rough fp32 memory estimate: immune fraction of total parameters.
pm = _params_to_millions(result.get("params"))
mem = ""
if pm is not None and result["n_layers"]:
frac = len(immune) / result["n_layers"]
saved_mb = pm * 1e6 * frac * 4 / 1e6 # fp32 bytes -> MB
mem = (f"
Estimated savings: "
f"~{saved_mb:.0f} MB (fp32, "
f"{frac*100:.0f}% of weights)
")
items = "".join(
f"
Layer {r['layer']}"
f"{n_heads} heads
" for r in immune
) or "
No fully-immune layers
"
if critical:
crit_labels = ", ".join(f"L{r['layer']}" for r in critical)
warn = (f"
⚠ Do NOT prune layers: {crit_labels} "
"(low redundancy — structurally load-bearing).
")
else:
warn = ("
✓ No critical layers — this model has "
"no structurally load-bearing bottlenecks at ρ < 0.5.
")
return (
"
"
f"
{pct:.0f}%
"
f"
of heads ({immune_heads}/{total_heads}) sit in immune "
"layers — safe to prune.
"
+ mem +
"
" + items + "
"
+ warn +
"
"
)
# Empty-state placeholders
EMPTY = "
Run a scan to populate this panel.
"
def empty_bundle():
return (EMPTY, render_gauge(0, "—", FG2), EMPTY, EMPTY, EMPTY, EMPTY, EMPTY, EMPTY)
# ===========================================================================
# Event handlers
# ===========================================================================
# Only the genuine live scan (forward passes) goes through the GPU decorator.
# The cached path — including the BERT auto-load — never touches it, so the app
# works on any hardware (cpu-basic, ZeroGPU) for the pre-loaded models.
@GPU
def _live_scan(model_id):
return ax.scan_model(model_id)
def on_scan(dropdown_id, custom_id, force_rescan):
"""Resolve the model id, scan (cached or live), render every panel."""
model_id = (custom_id or "").strip() or dropdown_id
if not model_id:
gr.Warning("Select a model or enter a HuggingFace model ID.")
return (None, *empty_bundle(), gr.update())
custom = bool((custom_id or "").strip())
want_live = force_rescan or custom
try:
result = None if want_live else ax.cached_result(model_id)
if result is None:
result = _live_scan(model_id)
except Exception as e: # surface a friendly error, keep the app alive
traceback.print_exc()
gr.Warning(f"Scan failed for '{model_id}': {e}")
return (None, *empty_bundle(), gr.update())
summary = ax.summarize(result)
n = result["n_layers"]
layer_choices = [(f"Layer {i}", i) for i in range(n)]
return (
result,
render_model_info(result),
render_integrity(summary),
render_metrics(summary),
render_riskmap(result, summary, None),
render_spectral(result),
render_layer_detail(result, None),
render_comparison(result, summary),
render_pruning(result, summary),
gr.update(choices=layer_choices, value=None),
)
def on_select_dropdown(result, layer_idx):
if result is None or layer_idx is None:
return gr.update(), gr.update()
summary = ax.summarize(result)
return (render_layer_detail(result, int(layer_idx)),
render_riskmap(result, summary, int(layer_idx)))
def on_relay(result, relay_value):
"""Hidden-textbox relay from a risk-map cell click (':')."""
if result is None or not relay_value:
return gr.update(), gr.update(), gr.update()
try:
idx = int(str(relay_value).split(":")[0])
except (ValueError, IndexError):
return gr.update(), gr.update(), gr.update()
summary = ax.summarize(result)
return (render_layer_detail(result, idx),
render_riskmap(result, summary, idx),
gr.update(value=idx))
# ===========================================================================
# App
# ===========================================================================
def build_app():
with gr.Blocks(css=CSS, head=HEAD_JS, title="AI Model X-Ray",
theme=gr.themes.Base()) as demo:
state = gr.State(None)
# ----- top bar ----- #
with gr.Row(elem_id="xr-topbar"):
with gr.Column(elem_id="tb-logo-col"):
gr.HTML("
🔬 "
"AI Model X-Ray
"
"
Structural Health Scanner
")
gr.HTML("Built by Cognitive Engineering "
"🇨🇭")
guide_btn = gr.Button("?", elem_id="guide-btn", scale=0, min_width=44)
with gr.Row():
# ===================== LEFT (25%) ===================== #
with gr.Column(scale=25, elem_id="xr-controls"):
gr.HTML("
1. Select model
")
dropdown = gr.Dropdown(
choices=DROPDOWN_CHOICES, value="bert-base-uncased",
label="Pre-loaded models", interactive=True)
custom = gr.Textbox(
label="...or a custom HuggingFace model ID", lines=1,
placeholder="e.g. roberta-base, microsoft/deberta-v3-small")
force = gr.Checkbox(label="Force live re-scan (ignore cache)", value=False)
scan_btn = gr.Button("\U0001F52C SCAN MODEL", elem_id="scan-btn")
gr.HTML("