# yaojin17/unlearning_llm architecture

> Architecture diagram of the GitHub repository yaojin17/unlearning_llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yaojin17/unlearning_llm
- Repository: https://github.com/yaojin17/unlearning_llm

## Overview

##### Project Type and Purpose
- This is a research and experimentation framework for exploring “machine unlearning” in pre-trained LLMs.
- The README, along with file names (e.g., ascent_plus_descent, gradient_ascent, etc.), shows that the system provides several methods to “unlearn” specific data from a model.
- It also supports evaluation pipelines (including membership inference attack evaluation) and tokenization utilities for preparing datasets.

##### File Structure
- Top-Level Files: The repo has common software files such as .gitignore, LICENSE, README.md, requirements.txt, and setup.py.
- Main Application Directory: “llm_unlearn” contains the core code.
– Subdirectory “methods”: This contains different unlearning strategies such as gradient_ascent, ascent_plus_descent, ascent_plus_KLdivergence, and unlearning_argument.
– Subdirectory “utils”: This hosts various helper scripts for tokenization, dataset preparation, evaluation (MIA evaluation, top-k sampling), and common utilities.
– Script Files (run_unlearn.py, run_eval.py, run_mia.py): These are the main entry points for unlearning experiments, evaluation runs, and membership inference attacks, respectively.
- The file structure clearly separates unlearning methods from utilities, hinting at a modular design.

##### README for Additional Insights
- The README explains the experimental framework, external dependencies (like the Yi-6B model and the unlearn_dataset from Hugging Face), and detailed steps to run tokenization, unlearning, evaluation, and membership inference experiments.

a. Main Components:
– External Dependencies:
▪ Pre-trained Yi-6B model (downloaded separately; an external component).
▪ Unlearn Dataset (fetched via Hugging Face).
– Data Preparation & Tokenization:
▪ Tokenized dataset creation using utilities (e.g., save_tokenized_dataset.py, ascent_plus_descent_tokenizer.py).
– Unlearning Engine:
▪ Core experiment runner from run_unlearn.py which orchestrates the unlearning pipeline.
▪ Unlearning Methods Module: Contains individual strategy implementations (gradient_ascent, ascent_plus_descent, etc.).
– Evaluation Subsystem:
▪ run_eval.py which evaluates unlearned models.
– Membership Inference Attack (MIA) Module:
▪ run_mia.py and associated utilities (mia_eval.py) that evaluate privacy risks.
– Utility/Helper Functions:
▪ Additional utilities for tokenization, embedding resize, and top-k sampling.

b. Relationships and Interactions:
– The “External Dependencies” (pre-trained model and dataset) feed into the “Data Preparation & Tokenization” module.
– Prepared data then flows into the “Unlearning Engine”, where one of several “Unlearning Methods” is applied.
– The output model from unlearning feeds into the “Evaluation Subsystem” (for model performance) and the “MIA Module” (for membership inference attack evaluation).
– Utility functions support these processes throughout, ensuring smooth tokenization, sampling, and data transformation.

c. Architectural Patterns or Design Principles:
– Modularity: Separation into distinct directories (methods vs. utils) to encapsulate different functionalities.
– Configurability: The unlearning method is parameterized (via command-line arguments) to select among multiple strategies.
– Pipeline Flow: A clear sequential data flow from dataset preparation to experiment execution, evaluation, and attack assessment.

d. Relevant Technologies, Frameworks, or Libraries:
– PyTorch (as indicated by the use of torchrun and specific GPU-related settings).
– Hugging Face Datasets (for loading the unlearn_dataset).
– WandB is referenced (for logging, as indicated by the need to replace the wandb key) and possibly other experimental tracking tools.
– Python’s argparse-based command line interfaces are implied in the runner scripts.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "External Dependencies"
        ext1("Pre-trained Yi-6B Model"):::external
        ext2("Unlearn Dataset (HuggingFace)"):::external
    end

    subgraph "Data Preparation & Tokenization"
        a1("AscentPlusDescentTokenizer"):::tokenizer
        a2("SaveTokenizedDataset"):::tokenizer
        a3("LLMTokenizeWithChunk"):::tokenizer
        a4("SmartTokenizerAndEmbeddingResize"):::tokenizer
        a5("TopKpSample"):::tokenizer
    end

    T("Tokenized Data"):::tokenizer

    UE("Unlearning Engine"):::engine
    UM("Unlearning Methods"):::method
    EE("Evaluation Engine"):::evaluation
    MIA("MIA Module"):::evaluation
    UF("Utility Functions"):::utility

    ext1 -->|"feeds"| T
    ext2 -->|"feeds"| T

    a1 --> T
    a2 --> T
    a3 --> T
    a4 --> T
    a5 --> T

    UF -->|"supports"| T

    T -->|"input"| UE
    UE -->|"selects(--unlearn_method)"| UM
    UE -->|"outputs"| EE
    UE -->|"outputs"| MIA

    click a1 "https://github.com/yaojin17/unlearning_llm/blob/main/llm_unlearn/utils/ascent_plus_descent_tokenizer.py"
    click a2 "https://github.com/yaojin17/unlearning_llm/blob/main/llm_unlearn/utils/save_tokenized_dataset.py"
    click a3 "https://github.com/yaojin17/unlearning_llm/blob/main/llm_unlearn/utils/llm_tokenize_with_chunk.py"
    click a4 "https://github.com/yaojin17/unlearning_llm/blob/main/llm_unlearn/utils/smart_tokenizer_and_embedding_resize.py"
    click a5 "https://github.com/yaojin17/unlearning_llm/blob/main/llm_unlearn/utils/top_kp_sample.py"
    click UE "https://github.com/yaojin17/unlearning_llm/blob/main/llm_unlearn/run_unlearn.py"
    click UM "https://github.com/yaojin17/unlearning_llm/tree/main/llm_unlearn/methods/"
    click EE "https://github.com/yaojin17/unlearning_llm/blob/main/llm_unlearn/run_eval.py"
    click MIA "https://github.com/yaojin17/unlearning_llm/blob/main/llm_unlearn/run_mia.py"
    click UF "https://github.com/yaojin17/unlearning_llm/blob/main/llm_unlearn/utils/utils.py"

    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef tokenizer fill:#bbf,stroke:#333,stroke-width:2px;
    classDef engine fill:#ccf,stroke:#333,stroke-width:2px;
    classDef method fill:#cfc,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#fc9,stroke:#333,stroke-width:2px;
    classDef utility fill:#cff,stroke:#333,stroke-dasharray: 5,5,stroke-width:2px;
```
