# wollschlager/geometry-of-refusal architecture

> Architecture diagram of the GitHub repository wollschlager/geometry-of-refusal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wollschlager/geometry-of-refusal
- Repository: https://github.com/wollschlager/geometry-of-refusal

## Overview

This research codebase computes and evaluates refusal-related directions and subspaces in language-model activations. The main workflow loads harmful/harmless instruction splits, constructs a supported model wrapper, derives and selects DIM directions, then applies interventions and evaluates generated responses. A separate RDO workflow trains directions, orthogonal or DIM-independent variants, and refusal cones; evaluation supports saved runs and cone samples. The graph includes documented capabilities whose wiring is not fully visible in the excerpts; unsampled implementation details are not expanded.

Main entry points: [`refusal_direction/pipeline/run_pipeline.py`](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/run_pipeline.py) (DIM runner), [`refusal_direction/pipeline/model_utils/model_factory.py`](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/model_factory.py) (Model factory), [`refusal_direction/pipeline/run_rdo_pipeline.py`](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/run_rdo_pipeline.py) (RDO evaluator), [`rdo.py`](https://github.com/wollschlager/geometry-of-refusal/blob/main/rdo.py) (RDO training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Datasets"]
  node_splits["SaladBench splits"]
  node_dataset_loader["Dataset loader<br/>[load_dataset.py]"]
  node_dataset_builder["Dataset preparation"]
end

subgraph group_dim["DIM Pipeline"]
  node_dim_entry["DIM runner<br/>[run_pipeline.py]"]
  node_dim_generate["Generate directions"]
  node_dim_select["Select direction"]
end

subgraph group_rdo["RDO Experiments"]
  node_rdo_train["RDO training<br/>[rdo.py]"]
  node_rdo_eval["RDO evaluator"]
  node_rdo_samples["Cone samples<br/>[run_rdo_samples.py]"]
end

subgraph group_runtime["Model Runtime"]
  node_model_factory["Model factory<br/>[model_factory.py]"]
  node_model_base["Model interface<br/>[model_base.py]"]
  node_gemma["Gemma adapter<br/>[gemma_model.py]"]
  node_llama["Llama adapter<br/>[llama3_model.py]"]
  node_qwen["Qwen adapter<br/>[qwen_model.py]"]
  node_hooks["Activation hooks<br/>[hook_utils.py]"]
end

subgraph group_analysis["Evaluation and Analysis"]
  node_completion_eval["Jailbreak evaluation"]
  node_loss_eval["Loss evaluation<br/>[evaluate_loss.py]"]
  node_scoring["Scoring utilities<br/>[scoring.py]"]
  node_similarity["Cosine analysis"]
  node_plots["Experiment plots<br/>[plots.py]"]
end

node_researcher(("Researcher"))
node_wandb[("Weights &amp; Biases")]
node_hf_models[("Hugging Face models")]
node_strongreject["StrongREJECT"]

node_researcher -->|"runs DIM"| node_dim_entry
node_researcher -->|"trains variants"| node_rdo_train
node_researcher -->|"evaluates run"| node_rdo_eval
node_researcher -->|"evaluates samples"| node_rdo_samples
node_dataset_builder -->|"prepares data"| node_splits
node_dim_entry -->|"loads splits"| node_dataset_loader
node_dim_entry -->|"constructs model"| node_model_factory
node_dim_entry -->|"generates candidates"| node_dim_generate
node_dim_entry -->|"selects candidate"| node_dim_select
node_dim_entry -->|"evaluates responses"| node_completion_eval
node_dim_entry -->|"evaluates loss"| node_loss_eval
node_rdo_train -->|"loads data"| node_dataset_loader
node_rdo_train -->|"loads model"| node_model_factory
node_rdo_train -->|"logs experiment"| node_wandb
node_rdo_eval -->|"constructs model"| node_model_factory
node_rdo_eval -->|"selects direction"| node_dim_select
node_rdo_eval -->|"scores completions"| node_completion_eval
node_rdo_eval -->|"retrieves run"| node_wandb
node_rdo_samples -->|"retrieves run"| node_wandb
node_model_factory -->|"creates wrapper"| node_model_base
node_model_factory -->|"selects adapter"| node_gemma
node_model_factory -->|"selects adapter"| node_llama
node_model_factory -->|"selects adapter"| node_qwen
node_gemma -->|"loads weights"| node_hf_models
node_llama -->|"loads weights"| node_hf_models
node_qwen -->|"loads weights"| node_hf_models
node_dim_select -->|"tests interventions"| node_hooks
node_rdo_eval -->|"applies interventions"| node_hooks
node_completion_eval -.->|"scores responses"| node_strongreject
node_researcher -->|"analyzes vectors"| node_similarity
node_researcher -->|"summarizes results"| node_plots
node_plots -->|"queries runs"| node_wandb

click node_splits "https://github.com/wollschlager/geometry-of-refusal/tree/main/data/saladbench_splits"
click node_dataset_loader "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/dataset/load_dataset.py"
click node_dataset_builder "https://github.com/wollschlager/geometry-of-refusal/blob/main/data/generate_datasets.py"
click node_dim_entry "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/run_pipeline.py"
click node_dim_generate "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/submodules/generate_directions.py"
click node_dim_select "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/submodules/select_direction.py"
click node_rdo_train "https://github.com/wollschlager/geometry-of-refusal/blob/main/rdo.py"
click node_rdo_eval "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/run_rdo_pipeline.py"
click node_rdo_samples "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/run_rdo_samples.py"
click node_model_factory "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/model_factory.py"
click node_model_base "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/model_base.py"
click node_gemma "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/gemma_model.py"
click node_llama "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/llama3_model.py"
click node_qwen "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/qwen_model.py"
click node_hooks "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/utils/hook_utils.py"
click node_completion_eval "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/submodules/evaluate_jailbreak.py"
click node_loss_eval "https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/submodules/evaluate_loss.py"
click node_scoring "https://github.com/wollschlager/geometry-of-refusal/blob/main/scoring.py"
click node_similarity "https://github.com/wollschlager/geometry-of-refusal/blob/main/cosinesim_analysis.py"
click node_plots "https://github.com/wollschlager/geometry-of-refusal/blob/main/plots.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_splits,node_dataset_loader,node_dataset_builder toneBlue
class node_dim_entry,node_dim_generate,node_dim_select,node_wandb,node_hf_models toneAmber
class node_rdo_train,node_rdo_eval,node_rdo_samples toneMint
class node_model_factory,node_model_base,node_gemma,node_llama,node_qwen,node_hooks toneRose
class node_completion_eval,node_loss_eval,node_scoring,node_similarity,node_plots,node_researcher,node_strongreject toneIndigo
```

## Components

### Datasets

- [SaladBench splits](https://github.com/wollschlager/geometry-of-refusal/tree/main/data/saladbench_splits): `data/saladbench_splits`
- [Dataset loader](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/dataset/load_dataset.py): `refusal_direction/dataset/load_dataset.py`
- [Dataset preparation](https://github.com/wollschlager/geometry-of-refusal/blob/main/data/generate_datasets.py): `data/generate_datasets.py`

### DIM Pipeline

- [DIM runner](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/run_pipeline.py): `refusal_direction/pipeline/run_pipeline.py`
- [Generate directions](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/submodules/generate_directions.py): `refusal_direction/pipeline/submodules/generate_directions.py`
- [Select direction](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/submodules/select_direction.py): `refusal_direction/pipeline/submodules/select_direction.py`

### RDO Experiments

- [RDO training](https://github.com/wollschlager/geometry-of-refusal/blob/main/rdo.py): `rdo.py`
- [RDO evaluator](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/run_rdo_pipeline.py): `refusal_direction/pipeline/run_rdo_pipeline.py`
- [Cone samples](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/run_rdo_samples.py): `refusal_direction/pipeline/run_rdo_samples.py`

### Model Runtime

- [Model factory](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/model_factory.py): `refusal_direction/pipeline/model_utils/model_factory.py`
- [Model interface](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/model_base.py): `refusal_direction/pipeline/model_utils/model_base.py`
- [Gemma adapter](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/gemma_model.py): `refusal_direction/pipeline/model_utils/gemma_model.py`
- [Llama adapter](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/llama3_model.py): `refusal_direction/pipeline/model_utils/llama3_model.py`
- [Qwen adapter](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/model_utils/qwen_model.py): `refusal_direction/pipeline/model_utils/qwen_model.py`
- [Activation hooks](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/utils/hook_utils.py): `refusal_direction/pipeline/utils/hook_utils.py`

### Evaluation and Analysis

- [Jailbreak evaluation](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/submodules/evaluate_jailbreak.py): `refusal_direction/pipeline/submodules/evaluate_jailbreak.py`
- [Loss evaluation](https://github.com/wollschlager/geometry-of-refusal/blob/main/refusal_direction/pipeline/submodules/evaluate_loss.py): `refusal_direction/pipeline/submodules/evaluate_loss.py`
- [Scoring utilities](https://github.com/wollschlager/geometry-of-refusal/blob/main/scoring.py): `scoring.py`
- [Cosine analysis](https://github.com/wollschlager/geometry-of-refusal/blob/main/cosinesim_analysis.py): `cosinesim_analysis.py`
- [Experiment plots](https://github.com/wollschlager/geometry-of-refusal/blob/main/plots.py): `plots.py`

### Other components

- **Researcher**
- **Weights & Biases**
- **Hugging Face models**
- **StrongREJECT**

## Connections

- Researcher → DIM runner: runs DIM
- Researcher → RDO training: trains variants
- Researcher → RDO evaluator: evaluates run
- Researcher → Cone samples: evaluates samples
- Dataset preparation → SaladBench splits: prepares data
- DIM runner → Dataset loader: loads splits
- DIM runner → Model factory: constructs model
- DIM runner → Generate directions: generates candidates
- DIM runner → Select direction: selects candidate
- DIM runner → Jailbreak evaluation: evaluates responses
- DIM runner → Loss evaluation: evaluates loss
- RDO training → Dataset loader: loads data
- RDO training → Model factory: loads model
- RDO training → Weights & Biases: logs experiment
- RDO evaluator → Model factory: constructs model
- RDO evaluator → Select direction: selects direction
- RDO evaluator → Jailbreak evaluation: scores completions
- RDO evaluator → Weights & Biases: retrieves run
- Cone samples → Weights & Biases: retrieves run
- Model factory → Model interface: creates wrapper
- Model factory → Gemma adapter: selects adapter
- Model factory → Llama adapter: selects adapter
- Model factory → Qwen adapter: selects adapter
- Gemma adapter → Hugging Face models: loads weights
- Llama adapter → Hugging Face models: loads weights
- Qwen adapter → Hugging Face models: loads weights
- Select direction → Activation hooks: tests interventions
- RDO evaluator → Activation hooks: applies interventions
- Jailbreak evaluation → StrongREJECT: scores responses
- Researcher → Cosine analysis: analyzes vectors
- Researcher → Experiment plots: summarizes results
- Experiment plots → Weights & Biases: queries runs