# shauli-ravfogel/lm-counterfactuals architecture

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

- Interactive diagram: https://gitdiagram.com/shauli-ravfogel/lm-counterfactuals
- Repository: https://github.com/shauli-ravfogel/lm-counterfactuals

## Overview

##### Project type and purpose
- This is an open-source research tool (Python package + scripts + notebooks) for generating “true” counterfactual strings from an input string using pre-trained LMs via the Gumbel-Max trick. It is neither a web app nor a full-stack product, but rather a command-line + notebook pipeline for data → model → counterfactual generation → analysis.

##### File structure
- Top-level scripts:
- run.py, run_mimic.py – main entry points to generate counterfactuals on different datasets
- .py, analyze_edit.py – compute statistics or evaluate generated counterfactuals
- sampling.py – encapsulates the Gumbel sampling / noise-injection logic
- mimic.py – implements the intervention routines (“hindsight sampling”)
- utils.py – helper routines (I/O, logging, configuration)
- Data directory:
- counterfactuals/ – precomputed .pkl outputs for various models/datasets
- Notebooks:
- example.ipynb, memit-analysis.ipynb, print.ipynb – demonstrations and exploratory analysis
- Configuration:
- requirements.txt – dependencies
- README.md – project overview, setup, usage

##### Key insights from the README
- Core workflow:
a. Load a dataset (Wikipedia or Bios)
b. Load a language model (via HuggingFace)
c. Forward pass: separate deterministic logits computation from sampling noise
d. Gumbel noise vector responsible for the observed output
e. Reuse that noise under an intervention to generate a counterfactual string
f. Save results to counterfactuals/*.pkl
- Two CLI scripts for different intervention experiments

##### Main components
a. Data Sources
- Wikipedia Dataset
- Bios Dataset
b. Runner / CLI Layer
- run.py
- run_mimic.py
c. Core Library
- sampling.py (Gumbel-Max trick)
- mimic.py (intervention logic)
- utils.py (I/O, formatting, caching)
d. Model Layer
- Pretrained LMs (GPT-2, Llama variants) loaded via HuggingFace
e. Output Storage
- counterfactuals/*.pkl files
f. Analysis Layer
- .py / analyze_edit.py
- Notebooks (example.ipynb, memit-analysis.ipynb, print.ipynb)
g. Environment & Config
- requirements.txt
- virtual environment

##### Relationships and interactions
- Data Sources → Runner scripts
- Runner scripts call utils.load_dataset() → returns input strings
- Runner → sampling.generate_gumbel_noise() → calls model.forward()
- generate_gumbel_noise() + mimic.intervene() → produce counterfactual outputs
- Counterfactual outputs → utils.save_pickle() → .pkl in counterfactuals/
- Analysis scripts / Notebooks → utils.load_pickle() → compute metrics / visualizations

##### Architectural patterns
- Pipeline architecture: clear separation of data ingestion → transformation (sampling + intervention) → storage → analysis
- Modular library: core logic separated into sampling.py, mimic.py, utils.py for reusability
- CLI layer orchestrates the pipeline

##### Technologies & frameworks
- Python 3
- PyTorch + HuggingFace Transformers
- Gumbel-Max trick implementation in sampling.py
- Notebook ecosystem (Jupyter) for analysis

- Clear component labels (e.g., “Gumbel Sampler (sampling.py)”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Python Environment & Config"
        env1["requirements.txt"]:::config
        env2["README.md"]:::config
    end

    subgraph "Data Sources"
        wiki["Wikipedia Dataset"]:::data
        bios["Bios Dataset"]:::data
    end

    subgraph "Runner / CLI Layer"
        run["run.py"]:::cli
        runmimic["run_mimic.py"]:::cli
    end

    subgraph "Core Library"
        samp["Gumbel Sampler (sampling.py)"]:::lib
        mimic["Intervention Logic (mimic.py)"]:::lib
        utils["Utilities (utils.py)"]:::lib
    end

    subgraph "Model Layer"
        model["Pretrained LMs (HuggingFace)"]:::model
    end

    counter["counterfactuals/"]:::output

    subgraph "Analysis Layer"
        ana["analyze.py"]:::analysis
        ana_edit["analyze_edit.py"]:::analysis
        nb1["example.ipynb"]:::analysis
        nb2["memit-analysis.ipynb"]:::analysis
        nb3["print.ipynb"]:::analysis
    end

    %% Data to Runner
    wiki -->|"load_dataset"| run
    bios -->|"load_dataset"| run
    wiki -->|"load_dataset"| runmimic
    bios -->|"load_dataset"| runmimic

    %% Runner to Core
    run -->|"uses utils"| utils
    runmimic -->|"uses utils"| utils
    run -->|"generate_gumbel_noise"| samp
    runmimic -->|"generate_gumbel_noise"| samp

    %% Core to Model and Output
    samp -->|"forward_pass"| model
    samp -->|"intervene"| mimic
    mimic -->|"produces outputs"| counter
    utils -->|"save_pickle/load_pickle"| counter

    %% Output to Analysis
    counter -->|"load_pickle"| ana
    counter -->|"load_pickle"| ana_edit
    counter -->|"load_pickle"| nb1
    counter -->|"load_pickle"| nb2
    counter -->|"load_pickle"| nb3

    %% Analysis uses utils
    ana -->|"compute_metrics"| utils
    ana_edit -->|"compute_metrics"| utils
    nb1 -->|"visualize"| utils
    nb2 -->|"visualize"| utils
    nb3 -->|"visualize"| utils

    click run "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/run.py"
    click runmimic "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/run_mimic.py"
    click samp "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/sampling.py"
    click mimic "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/mimic.py"
    click utils "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/utils.py"
    click counter "https://github.com/shauli-ravfogel/lm-counterfactuals/tree/main/counterfactuals/"
    click ana "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/analyze.py"
    click ana_edit "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/analyze_edit.py"
    click nb1 "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/example.ipynb"
    click nb2 "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/memit-analysis.ipynb"
    click nb3 "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/print.ipynb"
    click env1 "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/requirements.txt"
    click env2 "https://github.com/shauli-ravfogel/lm-counterfactuals/blob/main/README.md"

    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef lib fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px
    classDef output fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef analysis fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef model fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#000,stroke-width:1px
```
