# facebookresearch/llm-transparency-tool architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/llm-transparency-tool
- Repository: https://github.com/facebookresearch/llm-transparency-tool

## Overview

The LLM Transparency Tool lets a user choose a model and prompt, run inference, and inspect token-level contribution graphs and model representations. The Streamlit app coordinates model loading and analysis; TransformerLens supplies cached model state, while graph routes compute attention and FFN contributions. Users can explore selected edges, heads, FFN blocks, neurons, and vocabulary projections. The frontend and several detail-view paths are documented, but their full wiring is not visible in the excerpts, so uncertain links are omitted or marked unverified.

Main entry points: [`llm_transparency_tool/server/app.py`](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/app.py) (Streamlit app), [`llm_transparency_tool/components/frontend/src/ContributionGraph.tsx`](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/frontend/src/ContributionGraph.tsx) (Contribution graph UI), [`llm_transparency_tool/models/tlens_model.py`](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/models/tlens_model.py) (TransformerLens model), [`llm_transparency_tool/components/__init__.py`](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/__init__.py) (Streamlit component bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application"]
  node_app["Streamlit app<br/>[app.py]"]
  node_utils["Runtime utilities<br/>[utils.py]"]
  node_config["Model configuration<br/>[local.json]"]
  node_selection["Selection parser<br/>[graph_selection.py]"]
  node_monitor["Run monitor<br/>[monitor.py]"]
  node_styles["App styling<br/>[styles.py]"]
end

subgraph group_model["Model runtime"]
  node_model_api["Transparent LLM API<br/>[transparent_llm.py]"]
  node_tlens["TransformerLens model<br/>[tlens_model.py]"]
end

subgraph group_analysis["Contribution analysis"]
  node_graph_builder["Graph builder<br/>[graph.py]"]
  node_contributions["Contribution metrics<br/>[contributions.py]"]
  node_graph_types["Graph node types<br/>[graph_node.py]"]
  node_attention_detail["Attention head details<br/>[app.py]"]
  node_representation_detail["Representation inspection<br/>[app.py]"]
end

subgraph group_interface["Interactive interface"]
  node_component_bridge["Streamlit component bridge<br/>[__init__.py]"]
  node_graph_ui["Contribution graph UI"]
  node_selector_ui["Model and prompt selectors<br/>[Selector.tsx]"]
  node_ui_types["UI geometry types<br/>[common.tsx]"]
  node_frontend_entry["Frontend entry<br/>[index.tsx]"]
end

node_user(("Analyst"))

node_user -->|"chooses and runs"| node_app
node_config -->|"configures"| node_app
node_app -->|"loads and runs"| node_utils
node_utils -->|"creates"| node_tlens
node_tlens -->|"implements"| node_model_api
node_app -->|"requests graph"| node_graph_builder
node_graph_builder -->|"computes with"| node_contributions
node_app -->|"renders components"| node_component_bridge
node_component_bridge -.->|"provides graph component"| node_graph_ui
node_component_bridge -.->|"provides selector component"| node_selector_ui
node_frontend_entry -->|"imports"| node_graph_ui
node_frontend_entry -->|"imports"| node_selector_ui
node_graph_ui -->|"uses types"| node_ui_types
node_selector_ui -->|"uses types"| node_ui_types
node_graph_ui -.->|"returns selections"| node_user
node_app -->|"parses graph selection"| node_selection
node_selection -->|"parses node types"| node_graph_types
node_app -->|"shows head details"| node_attention_detail
node_app -->|"inspects representations"| node_representation_detail
node_tlens -.->|"provides model state"| node_representation_detail
node_app -.->|"monitors runs"| node_monitor
node_app -->|"applies styling"| node_styles

click node_app "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/app.py"
click node_utils "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/utils.py"
click node_config "https://github.com/facebookresearch/llm-transparency-tool/blob/main/config/local.json"
click node_model_api "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/models/transparent_llm.py"
click node_tlens "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/models/tlens_model.py"
click node_graph_builder "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/routes/graph.py"
click node_contributions "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/routes/contributions.py"
click node_graph_types "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/routes/graph_node.py"
click node_selection "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/graph_selection.py"
click node_component_bridge "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/__init__.py"
click node_graph_ui "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/frontend/src/ContributionGraph.tsx"
click node_selector_ui "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/frontend/src/Selector.tsx"
click node_ui_types "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/frontend/src/common.tsx"
click node_frontend_entry "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/frontend/src/index.tsx"
click node_attention_detail "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/app.py"
click node_representation_detail "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/app.py"
click node_monitor "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/monitor.py"
click node_styles "https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/styles.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_app,node_utils,node_config,node_selection,node_monitor,node_styles toneBlue
class node_model_api,node_tlens toneAmber
class node_graph_builder,node_contributions,node_graph_types,node_attention_detail,node_representation_detail toneMint
class node_component_bridge,node_graph_ui,node_selector_ui,node_ui_types,node_frontend_entry toneRose
class node_user toneIndigo
```

## Components

### Application

- [Streamlit app](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/app.py): `llm_transparency_tool/server/app.py`
- [Runtime utilities](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/utils.py): `llm_transparency_tool/server/utils.py`
- [Model configuration](https://github.com/facebookresearch/llm-transparency-tool/blob/main/config/local.json): `config/local.json`
- [Selection parser](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/graph_selection.py): `llm_transparency_tool/server/graph_selection.py`
- [Run monitor](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/monitor.py): `llm_transparency_tool/server/monitor.py`
- [App styling](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/styles.py): `llm_transparency_tool/server/styles.py`

### Model runtime

- [Transparent LLM API](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/models/transparent_llm.py): `llm_transparency_tool/models/transparent_llm.py`
- [TransformerLens model](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/models/tlens_model.py): `llm_transparency_tool/models/tlens_model.py`

### Contribution analysis

- [Graph builder](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/routes/graph.py): `llm_transparency_tool/routes/graph.py`
- [Contribution metrics](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/routes/contributions.py): `llm_transparency_tool/routes/contributions.py`
- [Graph node types](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/routes/graph_node.py): `llm_transparency_tool/routes/graph_node.py`
- [Attention head details](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/app.py): `llm_transparency_tool/server/app.py`
- [Representation inspection](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/server/app.py): `llm_transparency_tool/server/app.py`

### Interactive interface

- [Streamlit component bridge](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/__init__.py): `llm_transparency_tool/components/__init__.py`
- [Contribution graph UI](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/frontend/src/ContributionGraph.tsx): `llm_transparency_tool/components/frontend/src/ContributionGraph.tsx`
- [Model and prompt selectors](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/frontend/src/Selector.tsx): `llm_transparency_tool/components/frontend/src/Selector.tsx`
- [UI geometry types](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/frontend/src/common.tsx): `llm_transparency_tool/components/frontend/src/common.tsx`
- [Frontend entry](https://github.com/facebookresearch/llm-transparency-tool/blob/main/llm_transparency_tool/components/frontend/src/index.tsx): `llm_transparency_tool/components/frontend/src/index.tsx`

### Other components

- **Analyst**

## Connections

- Analyst → Streamlit app: chooses and runs (evidence: `README.md`)
- Model configuration → Streamlit app: configures (evidence: `README.md`)
- Streamlit app → Runtime utilities: loads and runs (evidence: `llm_transparency_tool/server/app.py`)
- Runtime utilities → TransformerLens model: creates (evidence: `llm_transparency_tool/server/utils.py`)
- TransformerLens model → Transparent LLM API: implements (evidence: `llm_transparency_tool/models/tlens_model.py`)
- Streamlit app → Graph builder: requests graph (evidence: `llm_transparency_tool/server/app.py`)
- Graph builder → Contribution metrics: computes with (evidence: `llm_transparency_tool/routes/graph.py`)
- Streamlit app → Streamlit component bridge: renders components (evidence: `llm_transparency_tool/server/app.py`)
- Streamlit component bridge → Contribution graph UI: provides graph component
- Streamlit component bridge → Model and prompt selectors: provides selector component
- Frontend entry → Contribution graph UI: imports (evidence: `llm_transparency_tool/components/frontend/src/index.tsx`)
- Frontend entry → Model and prompt selectors: imports (evidence: `llm_transparency_tool/components/frontend/src/index.tsx`)
- Contribution graph UI → UI geometry types: uses types (evidence: `llm_transparency_tool/components/frontend/src/ContributionGraph.tsx`)
- Model and prompt selectors → UI geometry types: uses types (evidence: `llm_transparency_tool/components/frontend/src/Selector.tsx`)
- Contribution graph UI → Analyst: returns selections
- Streamlit app → Selection parser: parses graph selection (evidence: `llm_transparency_tool/server/app.py`)
- Selection parser → Graph node types: parses node types (evidence: `llm_transparency_tool/server/graph_selection.py`)
- Streamlit app → Attention head details: shows head details (evidence: `llm_transparency_tool/server/app.py`)
- Streamlit app → Representation inspection: inspects representations (evidence: `llm_transparency_tool/server/app.py`)
- TransformerLens model → Representation inspection: provides model state (evidence: `llm_transparency_tool/server/app.py`)
- Streamlit app → Run monitor: monitors runs (evidence: `llm_transparency_tool/server/app.py`)
- Streamlit app → App styling: applies styling (evidence: `llm_transparency_tool/server/app.py`)
