# sabertooth-123/llm_instrumentation_tracing_replay architecture

> Architecture diagram of the GitHub repository sabertooth-123/llm_instrumentation_tracing_replay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sabertooth-123/llm_instrumentation_tracing_replay
- Repository: https://github.com/sabertooth-123/llm_instrumentation_tracing_replay

## Overview

Transformer Inspector loads Hugging Face causal language models, repeatedly runs inference, and captures layer-level activity for interactive inspection. The main path is CLI configuration → model loading and hook registration → inference and analysis → bounded snapshot storage → terminal or browser views. Analysis includes activation metrics and anomalies, attention, residual-stream and token-prediction features, and optional head ablation; the web mode also supports comparing two models. The README documents these modes, but the web page source and some runtime code were not sampled, so uncertain frontend and inference-call details are omitted.

Main entry points: [`transformer_inspector/tui/app.py`](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/app.py) (Terminal app), [`transformer_inspector/web/server.py`](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/web/server.py) (Web server and API), [`transformer_inspector/main.py`](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/main.py) (CLI entry point), [`transformer_inspector/hooks/interceptor.py`](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/hooks/interceptor.py) (Forward-hook interceptor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Startup and models"]
  node_main["CLI entry point<br/>[main.py]"]
  node_loader["Model loader<br/>[loader.py]"]
  node_model["Causal language model"]
end

subgraph group_capture["Capture and analysis"]
  node_interceptor["Forward-hook interceptor<br/>[interceptor.py]"]
  node_metrics["Metric calculations<br/>[metrics.py]"]
  node_buffer[("Snapshot ring buffer<br/>[ring_buffer.py]")]
end

subgraph group_web["Web dashboard"]
  node_server["Web server and API<br/>[server.py]"]
  node_webpage["Dashboard page<br/>[index.html]"]
end

subgraph group_tui["Terminal dashboard"]
  node_tuiapp["Terminal app<br/>[app.py]"]
  node_topology["Layer topology<br/>[topology.py]"]
  node_stream["Snapshot stream<br/>[stream.py]"]
  node_attention["Attention view<br/>[attention.py]"]
  node_metricspanel["Layer metrics view<br/>[metrics_panel.py]"]
  node_anomaly["Anomaly ledger<br/>[anomaly.py]"]
end

node_operator(("Operator"))
node_browser(("Browser user"))
node_hf(("Hugging Face models"))

node_operator -->|"starts with options"| node_main
node_main -->|"loads model"| node_loader
node_loader -->|"fetches model"| node_hf
node_loader -->|"returns model"| node_model
node_main -->|"registers hooks"| node_interceptor
node_interceptor -->|"hooks forward pass"| node_model
node_interceptor -->|"computes statistics"| node_metrics
node_interceptor -->|"stores snapshots"| node_buffer
node_main -->|"starts web mode"| node_server
node_main -->|"starts terminal mode"| node_tuiapp
node_tuiapp -->|"reads snapshots"| node_buffer
node_tuiapp -->|"renders topology"| node_topology
node_tuiapp -->|"refreshes events"| node_stream
node_tuiapp -->|"loads attention"| node_attention
node_tuiapp -->|"loads metrics"| node_metricspanel
node_tuiapp -->|"adds warnings"| node_anomaly
node_server -->|"reads snapshots"| node_buffer
node_server -->|"reads analysis state"| node_interceptor
node_server -->|"serves page"| node_webpage
node_browser -->|"requests updates"| node_server
node_server -->|"streams dashboard data"| node_browser

click node_main "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/main.py"
click node_loader "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/model/loader.py"
click node_interceptor "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/hooks/interceptor.py"
click node_metrics "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/hooks/metrics.py"
click node_buffer "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/buffer/ring_buffer.py"
click node_server "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/web/server.py"
click node_webpage "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/web/static/index.html"
click node_tuiapp "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/app.py"
click node_topology "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/topology.py"
click node_stream "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/stream.py"
click node_attention "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/attention.py"
click node_metricspanel "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/metrics_panel.py"
click node_anomaly "https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/anomaly.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_loader,node_model,node_browser toneBlue
class node_interceptor,node_metrics,node_buffer toneAmber
class node_server,node_webpage toneMint
class node_tuiapp,node_topology,node_stream,node_attention,node_metricspanel,node_anomaly toneRose
class node_operator,node_hf toneIndigo
```

## Components

### Startup and models

- [CLI entry point](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/main.py): `transformer_inspector/main.py`
- [Model loader](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/model/loader.py): `transformer_inspector/model/loader.py`
- **Causal language model**

### Capture and analysis

- [Forward-hook interceptor](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/hooks/interceptor.py): `transformer_inspector/hooks/interceptor.py`
- [Metric calculations](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/hooks/metrics.py): `transformer_inspector/hooks/metrics.py`
- [Snapshot ring buffer](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/buffer/ring_buffer.py): `transformer_inspector/buffer/ring_buffer.py`

### Web dashboard

- [Web server and API](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/web/server.py): `transformer_inspector/web/server.py`
- [Dashboard page](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/web/static/index.html): `transformer_inspector/web/static/index.html`

### Terminal dashboard

- [Terminal app](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/app.py): `transformer_inspector/tui/app.py`
- [Layer topology](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/topology.py): `transformer_inspector/tui/widgets/topology.py`
- [Snapshot stream](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/stream.py): `transformer_inspector/tui/widgets/stream.py`
- [Attention view](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/attention.py): `transformer_inspector/tui/widgets/attention.py`
- [Layer metrics view](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/metrics_panel.py): `transformer_inspector/tui/widgets/metrics_panel.py`
- [Anomaly ledger](https://github.com/sabertooth-123/llm_instrumentation_tracing_replay/blob/main/transformer_inspector/tui/widgets/anomaly.py): `transformer_inspector/tui/widgets/anomaly.py`

### Other components

- **Operator**
- **Browser user**
- **Hugging Face models**

## Connections

- Operator → CLI entry point: starts with options
- CLI entry point → Model loader: loads model
- Model loader → Hugging Face models: fetches model
- Model loader → Causal language model: returns model
- CLI entry point → Forward-hook interceptor: registers hooks
- Forward-hook interceptor → Causal language model: hooks forward pass
- Forward-hook interceptor → Metric calculations: computes statistics
- Forward-hook interceptor → Snapshot ring buffer: stores snapshots
- CLI entry point → Web server and API: starts web mode
- CLI entry point → Terminal app: starts terminal mode
- Terminal app → Snapshot ring buffer: reads snapshots
- Terminal app → Layer topology: renders topology
- Terminal app → Snapshot stream: refreshes events
- Terminal app → Attention view: loads attention
- Terminal app → Layer metrics view: loads metrics
- Terminal app → Anomaly ledger: adds warnings
- Web server and API → Snapshot ring buffer: reads snapshots
- Web server and API → Forward-hook interceptor: reads analysis state
- Web server and API → Dashboard page: serves page
- Browser user → Web server and API: requests updates
- Web server and API → Browser user: streams dashboard data