# centerforaisafety/harmbench architecture

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

- Interactive diagram: https://gitdiagram.com/centerforaisafety/harmbench
- Repository: https://github.com/centerforaisafety/harmbench

## Overview

##### Project type and purpose
- HarmBench is an open-source evaluation framework for automated red teaming of LLMs and robust refusal.
- It provides a standardized, plug-and-play pipeline to generate test cases (attacks), produce model completions, and evaluate the harmfulness of outputs.

##### File structure
- Top-level:
- scripts/ – orchestration of pipeline steps (run_pipeline.py, shell wrappers)
- baselines/ – all red-teaming method implementations (AutoPrompt, PEZ, TAP, etc.)
- configs/ – YAML definitions for methods, models, and pipeline runs
- data/ – static assets: behavior datasets, classifier validation sets, optimizer targets, images
- multimodalmodels/ – adapters for multimodal LLM APIs (GPT-4V, InstructBLIP, Qwen, etc.)
- adversarial_training/ – optional adversarial fine-tuning code and recipes
- notebooks/ – exploratory analysis and tutorials
- eval_utils.py, generate_completions.py, evaluate_completions.py, generate_test_cases.py, merge_test_cases.py – core Python modules for each pipeline stage

##### README for architectural clues
- The evaluation pipeline has 4 steps:
1) generate_test_cases
1.5) merge_test_cases
2) generate_completions
3) evaluate_completions
- run_pipeline.py abstracts these steps and can dispatch to Slurm, local, or local_parallel.
- New methods plug in by adding a subfolder in baselines and a matching YAML in configs/method_configs.
- New models plug in by editing configs/model_configs/models.yaml or adding adapter code in multimodalmodels/.

##### Details to capture
- The plugin interfaces: BaselineMethod (in baseline.py), MultimodalModel class
- The config hierarchy: method_configs → pipeline_configs → model_configs
- Execution modes: slurm vs local vs local_parallel
- Optional adversarial training sub-pipeline under adversarial_training

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        CLI["run_pipeline.py\n(User CLI)"]:::orchestration
        step1["step1.sh\n(generate_test_cases)"]:::orchestration
        step1_5["step1.5.sh\n(merge_test_cases)"]:::orchestration
        step2["step2.sh\n(generate_completions)"]:::orchestration
        step3["step3.sh\n(evaluate_completions)"]:::orchestration
        util["eval_utils.py"]:::orchestration
        gtc["generate_test_cases.py"]:::orchestration
        merge["merge_test_cases.py"]:::orchestration
        gencomp["generate_completions.py"]:::orchestration
        evalcomp["evaluate_completions.py"]:::orchestration
    end

    %% Plugins
    subgraph "Red-Teaming Plugins" 
        direction TB
        baselines_dir["baselines/"]:::plugin
        baseline_py["baseline.py"]:::plugin
        model_utils["model_utils.py"]:::plugin
    end

    %% Model Adapters
    subgraph "Model Adapters"
        direction TB
        multimodal_base["multimodalmodel.py"]:::plugin
        gpt4v["gpt4v_model.py"]:::plugin
        ibl["instructblip_model.py"]:::plugin
        llava["llava_model.py"]:::plugin
        qwen_dir["qwen/"]:::plugin
    end

    %% Configurations
    subgraph "Pipeline Configs" 
        direction TB
        pipe_cfg["run_pipeline.yaml"]:::config
    end
    subgraph "Method Configs"
        direction TB
        method_cfg["method_configs/"]:::config
    end
    subgraph "Model Configs"
        direction TB
        model_cfg["models.yaml"]:::config
    end

    %% Data Store
    data_store["Data Store\n(data/)"]:::data

    %% Adversarial Training
    adv["adversarial_training/"]:::adv

    %% Results
    results["Results & Analysis\n(notebooks/)"]:::results

    %% Flows
    CLI -->|reads pipeline config| pipe_cfg
    CLI --> step1
    step1 -->|loads method configs| method_cfg
    step1 --> gtc
    gtc -->|calls plugins| baselines_dir
    gtc --> data_store
    step1_5 -->|reads test cases| data_store
    step1_5 --> merge
    merge --> data_store
    step2 -->|reads test cases| data_store
    step2 --> gencomp
    gencomp -->|uses model adapters| multimodal_base
    gencomp --> data_store
    step3 -->|reads completions| data_store
    step3 --> evalcomp
    evalcomp -->|computes metrics| data_store
    evalcomp --> results

    CLI -.->|dispatch modes| util

    %% Adversarial pipeline
    baselines_dir -->|optional fine-tune| adv
    adv -->|updates adapters| model_cfg
    adv -->|updates adapters| multimodal_base

    %% Extension points
    baselines_dir --> method_cfg
    multimodal_base --> model_cfg

    %% Click events
    click CLI "https://github.com/centerforaisafety/harmbench/blob/main/scripts/run_pipeline.py"
    click step1 "https://github.com/centerforaisafety/harmbench/blob/main/scripts/step1.sh"
    click step1_5 "https://github.com/centerforaisafety/harmbench/blob/main/scripts/step1.5.sh"
    click step2 "https://github.com/centerforaisafety/harmbench/blob/main/scripts/step2.sh"
    click step3 "https://github.com/centerforaisafety/harmbench/blob/main/scripts/step3.sh"
    click util "https://github.com/centerforaisafety/harmbench/blob/main/eval_utils.py"
    click gtc "https://github.com/centerforaisafety/harmbench/blob/main/generate_test_cases.py"
    click merge "https://github.com/centerforaisafety/harmbench/blob/main/merge_test_cases.py"
    click gencomp "https://github.com/centerforaisafety/harmbench/blob/main/generate_completions.py"
    click evalcomp "https://github.com/centerforaisafety/harmbench/blob/main/evaluate_completions.py"
    click baselines_dir "https://github.com/centerforaisafety/harmbench/tree/main/baselines/"
    click baseline_py "https://github.com/centerforaisafety/harmbench/blob/main/baselines/baseline.py"
    click model_utils "https://github.com/centerforaisafety/harmbench/blob/main/baselines/model_utils.py"
    click multimodal_base "https://github.com/centerforaisafety/harmbench/blob/main/multimodalmodels/multimodalmodel.py"
    click gpt4v "https://github.com/centerforaisafety/harmbench/blob/main/multimodalmodels/gpt4v/gpt4v_model.py"
    click ibl "https://github.com/centerforaisafety/harmbench/blob/main/multimodalmodels/instructblip/instructblip_model.py"
    click llava "https://github.com/centerforaisafety/harmbench/blob/main/multimodalmodels/llava/llava_model.py"
    click qwen_dir "https://github.com/centerforaisafety/harmbench/tree/main/multimodalmodels/qwen/"
    click pipe_cfg "https://github.com/centerforaisafety/harmbench/blob/main/configs/pipeline_configs/run_pipeline.yaml"
    click method_cfg "https://github.com/centerforaisafety/harmbench/tree/main/configs/method_configs/"
    click model_cfg "https://github.com/centerforaisafety/harmbench/blob/main/configs/model_configs/models.yaml"
    click data_store "https://github.com/centerforaisafety/harmbench/tree/main/data/"
    click adv "https://github.com/centerforaisafety/harmbench/tree/main/adversarial_training/"
    click results "https://github.com/centerforaisafety/harmbench/tree/main/notebooks/"

    %% Styles
    classDef orchestration fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef plugin fill:#DFFFE0,stroke:#228B22,color:#228B22
    classDef config fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00
    classDef data fill:#F0F0F0,stroke:#696969,color:#696969,stroke-dasharray: 5 5
    classDef adv fill:#F3E5FF,stroke:#800080,color:#800080
    classDef results fill:#E0FFFF,stroke:#20B2AA,color:#20B2AA
```
