# safety-research/circuit-tracer architecture

> Architecture diagram of the GitHub repository safety-research/circuit-tracer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/safety-research/circuit-tracer
- Repository: https://github.com/safety-research/circuit-tracer

## Overview

##### High-level breakdown of the file structure
- Top-level:
- pyproject.toml, README.md, LICENSE, .gitignore
- circuit_tracer/ (core package)
- demos/ (Jupyter notebooks + helper scripts for tutorials)
- tests/ (unit tests for attribution, graph-creation, utils)
- circuit_tracer/:
- __main__.py: CLI entrypoint (console_scripts)
- attribution.py: orchestration of the 3-step pipeline (attribution → prune → graph files)
- replacement_model.py, graph.py: core data structures and algorithms for constructing the raw and pruned graph
- configs/*.yaml: predefined transcoder sets (Gemma, Llama, custom)
- transcoder/: code for loading and applying transcoder models & activation functions
- utils/: various helpers (disk offloading, HF model loading, graph file creation)
- frontend/: web server + data models for serving static assets + JSON endpoints
– local_server.py: minimal HTTP server to serve HTML/JS/CSS and JSON graph data
– assets/: HTML, CSS, JS modules for interactive visualization (attribution graphs, feature-view, etc.)

##### Key insights from README
- The workflow is a “3-step” pipeline:
1. Attribution: compute direct effects between features, error nodes, tokens, logits
2. Graph file creation: prune nodes/edges, emit JSON for visualization
3. Local server: serve static frontend + JSON to browser UI
- Supports three usage modes:
- Notebook/API
- CLI only (attribute → save .pt raw graph)
- CLI + --server (attribute → JSON → launch web UI)

##### Main components
a. User interfaces
1. Command-Line Interface (“circuit-tracer attribute … [--server]”)
2. Python API / Notebook (demos/*.ipynb import circuit_tracer.*)
3. Browser UI (HTML/JS/CSS assets)
b. Backend services
1. CLI entrypoint (__main__.py)
2. Attribution Engine (attribution.py + transcoder modules)
3. Graph Model & Pruner (graph.py, utils/create_graph_files.py)
4. Configuration Loader (configs/*.yaml)
5. HF Model Loader (utils/hf_utils.py)
6. Local Web Server (frontend/local_server.py)
c. Data stores / file artifacts
1. Raw attribution graph (.pt)
2. Pruned JSON graph files (graph_file_dir/*.json)
3. Config YAML files
4. Static assets (frontend/assets/*.html, .js, .css)
d. External dependencies
1. Hugging Face model hub (download pretrained models & transcoders)
2. Flask or built-in HTTP server library (for local_server)
3. Browser (renders the frontend)

##### Relationships and data flows
- CLI / Python API → loads config & HF models → runs Attribution Engine → produces Raw Graph (.pt)
→ Graph Pruner → exports JSON files
→ (if --server) Local Server reads JSON + static assets
→ serves HTTP endpoints → Browser UI fetches index.html, JS, CSS, then graph JSON → renders interactive graphs
- In notebook mode: Python API returns in-memory graph objects for further analysis or intervention
- External → HF utilities fetch pretrained transcoders & model weights; disk_offload for large feature sets

##### Architectural patterns and design principles
- Three-tier separation:
1. Presentation layer (Browser UI static assets)
2. Application layer (Python backend: attribution + server)
3. Data layer (graph files, config YAML, model weights)
- Modular design: separate modules for transcoder logic, graph construction, utilities, and frontend
- Configuration-driven: YAML presets for different model/transcoder sets

##### Technology stack
- Python 3.8+
- PyTorch / Transformer model loading (via HF utils)
- YAML for config files
- Built-in HTTP server or Flask for local_server.py
- JavaScript, HTML, CSS (vanilla + small utility scripts) for the frontend visuals
- Jupyter notebooks & demos for interactive tutorials

##### Diagramming recommendations
- Config → Attribution Engine → Raw Graph → Graph Pruner → JSON Graph → Local Server → Browser
- Blue: Backend processing modules
- Green: Data/artifact stores (YAML, .pt, JSON)
- Orange: Web layer (local_server, static assets, browser)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces
    subgraph "User Interfaces"
        CLI["CLI Entry Point"]:::interface
        API["Python API / Notebook"]:::interface
        Browser["Browser UI"]:::web
        Demos["Notebooks & Demos"]:::interface
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph "Core Backend Modules"
            Attribution["Attribution Engine"]:::backend
            GraphCore["Graph Data Structures"]:::backend
            JSONExporter["JSON Graph File Creation"]:::backend
            ConfigLoader["Configuration Loader"]:::backend
            HFLoader["Hugging Face Model Loader"]:::backend
            DiskOff["Disk Offloading Utility"]:::backend
            Replacement["Replacement Model Logic"]:::backend
            TranscoderAF["Activation Functions"]:::backend
            TranscoderSL["Single Layer Transcoder"]:::backend
        end
        subgraph "Frontend Server"
            LocalServer["Local Web Server"]:::web
            DataModels["Frontend Data Models"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data / Artifacts"
        ConfigFiles["Config YAML Files"]:::data
        RawGraph["Raw Graph (.pt)"]:::data
        JSONGraph["Pruned JSON Graphs"]:::data
        StaticAssets["Static Assets (HTML/CSS/JS)"]:::data
    end

    %% External Services
    subgraph "External Dependencies"
        HFHub["Hugging Face Model Hub"]:::external
        HTTPLib["HTTP Server Library"]:::external
    end

    %% Relationships
    CLI -->|"invoke"| ConfigLoader
    CLI -->|"invoke"| HFLoader
    CLI -->|"invoke"| Attribution
    API -->|"calls"| Attribution
    Demos -->|"imports"| API

    ConfigLoader -->|"loads YAML"| Attribution
    ConfigFiles -->|"contains presets"| ConfigLoader

    HFLoader -->|"loads models"| Attribution
    HFHub -->|"provides weights"| HFLoader

    DiskOff -->|"offloads data"| Attribution

    TranscoderAF -->|"used by"| Attribution
    TranscoderSL -->|"used by"| Attribution
    Replacement -->|"provides model logic"| Attribution

    Attribution -->|"emit .pt"| RawGraph
    RawGraph -->|"input"| GraphCore
    GraphCore -->|"construct graph"| JSONExporter
    JSONExporter -->|"export JSON"| JSONGraph

    JSONGraph -->|"served by"| LocalServer
    StaticAssets -->|"served by"| LocalServer
    HTTPLib -->|"powers"| LocalServer

    LocalServer -->|"HTTP endpoints"| Browser
    Browser -->|"fetch JSON"| JSONGraph
    Browser -->|"fetch assets"| StaticAssets
    JSONGraph -->|"used by"| DataModels
    DataModels -->|"feeds UI"| Browser

    API -->|"returns in-memory graph"| GraphCore

    %% Click Events
    click CLI "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/__main__.py"
    click Attribution "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/attribution.py"
    click GraphCore "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/graph.py"
    click JSONExporter "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/utils/create_graph_files.py"
    click ConfigLoader "https://github.com/safety-research/circuit-tracer/tree/main/circuit_tracer/configs/"
    click HFLoader "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/utils/hf_utils.py"
    click DiskOff "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/utils/disk_offload.py"
    click Replacement "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/replacement_model.py"
    click TranscoderAF "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/transcoder/activation_functions.py"
    click TranscoderSL "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/transcoder/single_layer_transcoder.py"
    click LocalServer "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/frontend/local_server.py"
    click DataModels "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/frontend/graph_models.py"
    click DataModels "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/frontend/feature_models.py"
    click DataModels "https://github.com/safety-research/circuit-tracer/blob/main/circuit_tracer/frontend/utils.py"
    click StaticAssets "https://github.com/safety-research/circuit-tracer/tree/main/circuit_tracer/frontend/assets/"
    click Demos "https://github.com/safety-research/circuit-tracer/tree/main/demos/"

    %% Styles
    classDef backend fill:#add8e6,stroke:#333,stroke-width:1px
    classDef data fill:#90ee90,stroke:#333,stroke-width:1px
    classDef web fill:#ffa500,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef interface fill:#ffe4b5,stroke:#333,stroke-width:1px
```
