# facebookresearch/advprompter architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/advprompter
- Repository: https://github.com/facebookresearch/advprompter

## Overview

##### Project Type & Purpose
- This is a research/ML experimentation framework (“AdvPrompter”) for generating adversarial prompts (suffixes) to probe or attack large language models (LLMs).
- It uses Hydra for flexible configuration, supports training and evaluation pipelines, and optionally logs to Weights & Biases.

##### Main Components
a. Configuration Manager (Hydra)
b. Orchestrator (main.py)
c. Data Pipeline
· Dataset Loader (CSV, harmful_behaviors, prefixes)
· Suffix Dataset Writer
d. AdvPrompter Module
· Sequence Optimizer (advprompteropt.py & sequence.py)
· LoRA Wrappers (for finetuning)
e. Target LLM Module (llm.py)
· Model Interface (HuggingFace, PEFT checkpointing)
f. Evaluation Module
· Metrics & Loss Computation
· Suffix‐level evaluation (eval, eval_suffix_dataset flows)
g. Training Module
· Training Loop (including intermittent evaluation & checkpointing)
h. Logging & Experiment Tracking
· File System (exp/... directories)
· Optional: Weights & Biases API
i. Utilities (utils.py)

##### Relationships & Data Flow
- Orchestrator → Data Pipeline for loading train/test CSVs
- Data Pipeline → AdvPrompter: provides prompts to optimize
- AdvPrompter → Sequence Optimizer: generates candidate suffixes
- Sequence Optimizer ↔ Target LLM: queries model for outputs & gradients
- Target LLM → Evaluation Module: returns scores/loss
- Evaluation Module → Logging (WandB/file system)
- Training Loop: connects AdvPrompter ↔ Target LLM ↔ Evaluation ↔ Checkpointing
- Evaluation-only flow: skip Training Loop, produce suffix_dataset → Evaluation Module → Logging

##### Architectural Patterns & Design Principles
- Modular design: each concern (config, data, model, eval, logging) is a separate package/file.
- Plug-and-play with Hydra: drop-in new LLMs or prompters via YAML.
- Separation of training vs. evaluation workflows configured by Hydra.
- Use of PEFT/LoRA for efficient finetuning.
- File‐based experiment tracking (exp/…), with optional external service (WandB).

##### Technologies & Frameworks
- Python 3.11, Hydra (config management)
- HuggingFace Transformers + PEFT/LoRA
- Pandas/CSV for data loading
- PyTorch for model training
- WandB (optional)
- Singularity/Conda for reproducible environments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration"
        CM["Configuration Manager (Hydra)"]:::config
    end

    %% Orchestrator
    ORC["Orchestrator (main.py)"]:::config

    %% Data Pipeline Layer
    subgraph "Data Pipeline"
        DL1["Prefix Dataset Loader"]:::data
        DL2["Behavior Dataset Loader"]:::data
        SDW["Suffix Dataset Writer"]:::data
    end

    %% AdvPrompter Module
    subgraph "AdvPrompter Module"
        SO["Sequence Optimizer"]:::model
        LO["LoRA Wrappers"]:::model
    end

    %% Target LLM Module
    subgraph "Target LLM Module"
        LLM["Model Interface"]:::model
    end

    %% Evaluation Module
    subgraph "Evaluation Module"
        EM["Metrics & Loss Computation"]:::eval
        EFS["Suffix-level Evaluation"]:::eval
    end

    %% Training Module
    subgraph "Training Module"
        TL["Training Loop & Checkpointing"]:::train
    end

    %% Logging & Experiment Tracking
    subgraph "Logging & Experiment Tracking"
        FS["File System (exp/)"]:::logging
        WB["Weights & Biases API"]:::logging
    end

    %% Utilities
    U["Utilities (utils.py)"]:::util

    %% Relationships & Data Flow
    CM -->|provides params| ORC
    ORC -->|load CSVs| DL1
    ORC -->|load CSVs| DL2
    DL1 -->|provides prefixes| SDW
    DL2 -->|provides data| SDW
    SDW -->|prompts| SO
    SO -->|candidates| LO
    LO -->|apply LoRA| LLM
    SO <-->|queries model| LLM
    LLM -->|outputs & grads| EM
    EM -->|scores| TL
    TL -->|checkpoints| FS
    TL -->|intermittent eval| EFS
    EFS -->|suffix_dataset| FS
    EM -->|logs metrics| WB
    WB -->|optional| FS
    U -->|IO & metrics| DL1
    U -->|IO & metrics| DL2
    U -->|evaluation utils| EM
    U -->|WandB hooks| WB

    %% Click Events
    click CM "https://github.com/facebookresearch/advprompter/tree/main/conf/"
    click ORC "https://github.com/facebookresearch/advprompter/blob/main/main.py"
    click DL1 "https://github.com/facebookresearch/advprompter/blob/main/data/affirmative_prefixes.csv"
    click DL2 "https://github.com/facebookresearch/advprompter/tree/main/data/harmful_behaviors/dataset"
    click SDW "https://github.com/facebookresearch/advprompter/blob/main/utils.py"
    click SO "https://github.com/facebookresearch/advprompter/blob/main/advprompteropt.py"
    click LO "https://github.com/facebookresearch/advprompter/blob/main/llm.py"
    click LLM "https://github.com/facebookresearch/advprompter/blob/main/llm.py"
    click EM "https://github.com/facebookresearch/advprompter/blob/main/utils.py"
    click EFS "https://github.com/facebookresearch/advprompter/blob/main/advprompteropt.py"
    click TL "https://github.com/facebookresearch/advprompter/blob/main/advprompteropt.py"
    click FS "https://github.com/facebookresearch/advprompter/tree/main/exp/"
    click WB "https://github.com/facebookresearch/advprompter/blob/main/utils.py"
    click U "https://github.com/facebookresearch/advprompter/blob/main/utils.py"

    %% Styles
    classDef config fill:#AED6F1,stroke:#21618C,color:#1B4F72;
    classDef data fill:#A9DFBF,stroke:#196F3D,color:#145A32;
    classDef model fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef eval fill:#F5B7B1,stroke:#943126,color:#641E16;
    classDef train fill:#FAD7A0,stroke:#B9770E,color:#6E2C00;
    classDef logging fill:#D5D8DC,stroke:#566573,color:#1C2833;
    classDef util fill:#E8DAEF,stroke:#7D3C98,color:#4A235A;
```
