# baturaysaglam/instant-alignment architecture

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

- Interactive diagram: https://gitdiagram.com/baturaysaglam/instant-alignment
- Repository: https://github.com/baturaysaglam/instant-alignment

## Overview

Test-Time Safety Alignment is a research implementation for steering instruction-tuned LLM responses at inference time, without retraining. The documented workflow starts in the cookbook: load a model, generate a baseline response, then iteratively perturb prompt embeddings, score generated text with moderation, and update the embedding. The repository also includes HarmBench and WildJailbreak prompts and saved responses across model and defense variants. The README documents the end-to-end example; dataset-to-response wiring is not shown in the sampled source, so those artifacts are not linked as a pipeline.

Main entry points: [`cookbook.ipynb`](https://github.com/baturaysaglam/instant-alignment/blob/main/cookbook.ipynb) (Example workflow), [`utils/tsa.py`](https://github.com/baturaysaglam/instant-alignment/blob/main/utils/tsa.py) (Embedding optimizer), [`utils/moderator.py`](https://github.com/baturaysaglam/instant-alignment/blob/main/utils/moderator.py) (Safety scoring), [`utils/model.py`](https://github.com/baturaysaglam/instant-alignment/blob/main/utils/model.py) (Model utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Safety workflow"]
  node_cookbook["Example workflow<br/>[cookbook.ipynb]"]
  node_model["Model utilities<br/>[model.py]"]
  node_tsa["Embedding optimizer<br/>[tsa.py]"]
  node_moderator["Safety scoring<br/>[moderator.py]"]
end

subgraph group_benchmarks["Benchmark data"]
  node_wildjb["WildJailbreak prompts"]
  node_harmbench["HarmBench prompts"]
end

subgraph group_artifacts["Saved responses"]
  node_saved_responses["Model responses"]
  node_tsa_config["TSA parameters"]
end

node_user(("Researcher"))
node_moderation_api["OpenAI Moderation"]

node_user -->|"runs example"| node_cookbook
node_cookbook -->|"loads model"| node_model
node_cookbook -->|"runs optimization"| node_tsa
node_tsa -->|"generates samples"| node_model
node_tsa -->|"scores samples"| node_moderator
node_moderator -->|"requests scores"| node_moderation_api

click node_cookbook "https://github.com/baturaysaglam/instant-alignment/blob/main/cookbook.ipynb"
click node_model "https://github.com/baturaysaglam/instant-alignment/blob/main/utils/model.py"
click node_tsa "https://github.com/baturaysaglam/instant-alignment/blob/main/utils/tsa.py"
click node_moderator "https://github.com/baturaysaglam/instant-alignment/blob/main/utils/moderator.py"
click node_wildjb "https://github.com/baturaysaglam/instant-alignment/tree/main/datasets/wildjb/eval"
click node_harmbench "https://github.com/baturaysaglam/instant-alignment/blob/main/datasets/harmbench/vanilla_harmful.csv"
click node_saved_responses "https://github.com/baturaysaglam/instant-alignment/tree/main/responses"
click node_tsa_config "https://github.com/baturaysaglam/instant-alignment/tree/main/responses/tsa"

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_cookbook,node_model,node_tsa,node_moderator toneBlue
class node_wildjb,node_harmbench toneAmber
class node_saved_responses,node_tsa_config toneMint
class node_user,node_moderation_api toneIndigo
```

## Components

### Safety workflow

- [Example workflow](https://github.com/baturaysaglam/instant-alignment/blob/main/cookbook.ipynb): `cookbook.ipynb`
- [Model utilities](https://github.com/baturaysaglam/instant-alignment/blob/main/utils/model.py): `utils/model.py`
- [Embedding optimizer](https://github.com/baturaysaglam/instant-alignment/blob/main/utils/tsa.py): `utils/tsa.py`
- [Safety scoring](https://github.com/baturaysaglam/instant-alignment/blob/main/utils/moderator.py): `utils/moderator.py`

### Benchmark data

- [WildJailbreak prompts](https://github.com/baturaysaglam/instant-alignment/tree/main/datasets/wildjb/eval): `datasets/wildjb/eval`
- [HarmBench prompts](https://github.com/baturaysaglam/instant-alignment/blob/main/datasets/harmbench/vanilla_harmful.csv): `datasets/harmbench/vanilla_harmful.csv`

### Saved responses

- [Model responses](https://github.com/baturaysaglam/instant-alignment/tree/main/responses): `responses`
- [TSA parameters](https://github.com/baturaysaglam/instant-alignment/tree/main/responses/tsa): `responses/tsa`

### Other components

- **Researcher**
- **OpenAI Moderation**

## Connections

- Researcher → Example workflow: runs example (evidence: `README.md`)
- Example workflow → Model utilities: loads model (evidence: `README.md`)
- Example workflow → Embedding optimizer: runs optimization (evidence: `README.md`)
- Embedding optimizer → Model utilities: generates samples (evidence: `utils/tsa.py`)
- Embedding optimizer → Safety scoring: scores samples (evidence: `utils/tsa.py`)
- Safety scoring → OpenAI Moderation: requests scores (evidence: `utils/moderator.py`)
