# vaniseth/ggas architecture

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

- Interactive diagram: https://gitdiagram.com/vaniseth/ggas
- Repository: https://github.com/vaniseth/ggas

## Overview

GGAS is a research system for detecting multi-turn jailbreak risk in language-model conversations and applying activation steering. Its principal workflow generates attack and benign transcripts, extracts per-turn activations and attention, trains a probe, computes cumulative graph-based risk, calibrates a threshold and steering strength, then evaluates defended behavior. Separate capabilities provide baseline guards, evaluation tables, and graph snapshots/visualization. The README is only a title, so workflow detail comes from sampled source and the source index; unsampled subsystem links are included only where that index documents references.

Main entry points: [`ggas/pipeline.py`](https://github.com/vaniseth/ggas/blob/main/ggas/pipeline.py) (Pipeline stages), [`ggas/extract.py`](https://github.com/vaniseth/ggas/blob/main/ggas/extract.py) (Extracted features), [`ggas/probe.py`](https://github.com/vaniseth/ggas/blob/main/ggas/probe.py) (Risk probe), [`ggas/steer.py`](https://github.com/vaniseth/ggas/blob/main/ggas/steer.py) (Steered target)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["Experiment orchestration"]
  node_pipeline["Pipeline stages<br/>[pipeline.py]"]
  node_config["Shared config<br/>[config.py]"]
  node_loaders["Dataset loaders<br/>[data_loaders.py]"]
  node_harness["Attack harness<br/>[attack_harness.py]"]
  node_transcripts["Conversation transcripts<br/>[pipeline.py]"]
end

subgraph group_signals["Risk signals"]
  node_features["Extracted features<br/>[extract.py]"]
  node_compat["HF compatibility<br/>[hf_compat.py]"]
  node_probe["Risk probe<br/>[probe.py]"]
end

subgraph group_defense["Detection and defense"]
  node_detection["RDS detector<br/>[detect.py]"]
  node_calibration["Calibration<br/>[calibrate.py]"]
  node_steering["Steered target<br/>[steer.py]"]
  node_responder["GGAS responder<br/>[ggas_responder.py]"]
  node_swap["Model swapping<br/>[swap_runnner.py]"]
end

subgraph group_evaluation["Evaluation and visualization"]
  node_evalsuite["Evaluation suite<br/>[eval_suite.py]"]
  node_evaltable["Evaluation table<br/>[eval_table.py]"]
  node_guard["LlamaGuard baseline"]
  node_graphstate["Graph snapshots<br/>[state.py]"]
  node_capture["Graph capture<br/>[capture.py]"]
  node_render["Graph rendering<br/>[render.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs stages"| node_pipeline
node_pipeline -->|"reads settings"| node_config
node_pipeline -->|"loads seeds"| node_loaders
node_pipeline -->|"runs conversations"| node_harness
node_harness -->|"produces"| node_transcripts
node_pipeline -->|"writes transcripts"| node_transcripts
node_pipeline -->|"extracts features"| node_features
node_features -->|"normalizes model outputs"| node_compat
node_features -->|"uses target"| node_harness
node_pipeline -->|"trains probe"| node_probe
node_probe -->|"reads activations"| node_features
node_pipeline -->|"calibrates defense"| node_calibration
node_calibration -->|"scores candidates"| node_probe
node_calibration -->|"tunes threshold"| node_detection
node_calibration -->|"tunes strength"| node_steering
node_pipeline -->|"configures steering"| node_steering
node_detection -->|"scores nodes"| node_probe
node_detection -->|"uses attention graph"| node_features
node_steering -->|"detects risk"| node_detection
node_steering -->|"uses probe"| node_probe
node_steering -->|"extracts current features"| node_features
node_steering -->|"normalizes model outputs"| node_compat
node_responder -->|"uses target"| node_harness
node_responder -->|"extracts features"| node_features
node_responder -->|"detects risk"| node_detection
node_responder -->|"scores nodes"| node_probe
node_swap -->|"uses attack harness"| node_harness
node_swap -->|"loads datasets"| node_loaders
node_pipeline -->|"runs evaluation"| node_evalsuite
node_evalsuite -->|"uses probe"| node_probe
node_evalsuite -->|"scores turns"| node_detection
node_evalsuite -->|"extracts features"| node_features
node_evaltable -->|"runs model phases"| node_harness
node_evaltable -->|"loads evaluation sets"| node_loaders
node_evaltable -->|"compares baseline"| node_guard
node_evaltable -->|"evaluates defense"| node_steering
node_capture -->|"builds snapshots"| node_graphstate
node_graphstate -->|"extracts snapshot features"| node_features
node_graphstate -->|"scores snapshot"| node_detection
node_graphstate -->|"uses risk probe"| node_probe

click node_pipeline "https://github.com/vaniseth/ggas/blob/main/ggas/pipeline.py"
click node_config "https://github.com/vaniseth/ggas/blob/main/ggas/config.py"
click node_loaders "https://github.com/vaniseth/ggas/blob/main/ggas/data_loaders.py"
click node_harness "https://github.com/vaniseth/ggas/blob/main/ggas/attack_harness.py"
click node_transcripts "https://github.com/vaniseth/ggas/blob/main/ggas/pipeline.py"
click node_features "https://github.com/vaniseth/ggas/blob/main/ggas/extract.py"
click node_compat "https://github.com/vaniseth/ggas/blob/main/ggas/hf_compat.py"
click node_probe "https://github.com/vaniseth/ggas/blob/main/ggas/probe.py"
click node_detection "https://github.com/vaniseth/ggas/blob/main/ggas/detect.py"
click node_calibration "https://github.com/vaniseth/ggas/blob/main/ggas/calibrate.py"
click node_steering "https://github.com/vaniseth/ggas/blob/main/ggas/steer.py"
click node_responder "https://github.com/vaniseth/ggas/blob/main/ggas/ggas_responder.py"
click node_swap "https://github.com/vaniseth/ggas/blob/main/ggas/swap_runnner.py"
click node_evalsuite "https://github.com/vaniseth/ggas/blob/main/ggas/eval_suite.py"
click node_evaltable "https://github.com/vaniseth/ggas/blob/main/ggas/eval_table.py"
click node_guard "https://github.com/vaniseth/ggas/blob/main/ggas/llamaguard_baseline.py"
click node_graphstate "https://github.com/vaniseth/ggas/blob/main/ggas/graphviz/state.py"
click node_capture "https://github.com/vaniseth/ggas/blob/main/ggas/graphviz/capture.py"
click node_render "https://github.com/vaniseth/ggas/blob/main/ggas/graphviz/render.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_pipeline,node_config,node_loaders,node_harness,node_transcripts toneBlue
class node_features,node_compat,node_probe toneAmber
class node_detection,node_calibration,node_steering,node_responder,node_swap toneMint
class node_evalsuite,node_evaltable,node_guard,node_graphstate,node_capture,node_render toneRose
class node_researcher toneIndigo
```

## Components

### Experiment orchestration

- [Pipeline stages](https://github.com/vaniseth/ggas/blob/main/ggas/pipeline.py): `ggas/pipeline.py`
- [Shared config](https://github.com/vaniseth/ggas/blob/main/ggas/config.py): `ggas/config.py`
- [Dataset loaders](https://github.com/vaniseth/ggas/blob/main/ggas/data_loaders.py): `ggas/data_loaders.py`
- [Attack harness](https://github.com/vaniseth/ggas/blob/main/ggas/attack_harness.py): `ggas/attack_harness.py`
- [Conversation transcripts](https://github.com/vaniseth/ggas/blob/main/ggas/pipeline.py): `ggas/pipeline.py`

### Risk signals

- [Extracted features](https://github.com/vaniseth/ggas/blob/main/ggas/extract.py): `ggas/extract.py`
- [HF compatibility](https://github.com/vaniseth/ggas/blob/main/ggas/hf_compat.py): `ggas/hf_compat.py`
- [Risk probe](https://github.com/vaniseth/ggas/blob/main/ggas/probe.py): `ggas/probe.py`

### Detection and defense

- [RDS detector](https://github.com/vaniseth/ggas/blob/main/ggas/detect.py): `ggas/detect.py`
- [Calibration](https://github.com/vaniseth/ggas/blob/main/ggas/calibrate.py): `ggas/calibrate.py`
- [Steered target](https://github.com/vaniseth/ggas/blob/main/ggas/steer.py): `ggas/steer.py`
- [GGAS responder](https://github.com/vaniseth/ggas/blob/main/ggas/ggas_responder.py): `ggas/ggas_responder.py`
- [Model swapping](https://github.com/vaniseth/ggas/blob/main/ggas/swap_runnner.py): `ggas/swap_runnner.py`

### Evaluation and visualization

- [Evaluation suite](https://github.com/vaniseth/ggas/blob/main/ggas/eval_suite.py): `ggas/eval_suite.py`
- [Evaluation table](https://github.com/vaniseth/ggas/blob/main/ggas/eval_table.py): `ggas/eval_table.py`
- [LlamaGuard baseline](https://github.com/vaniseth/ggas/blob/main/ggas/llamaguard_baseline.py): `ggas/llamaguard_baseline.py`
- [Graph snapshots](https://github.com/vaniseth/ggas/blob/main/ggas/graphviz/state.py): `ggas/graphviz/state.py`
- [Graph capture](https://github.com/vaniseth/ggas/blob/main/ggas/graphviz/capture.py): `ggas/graphviz/capture.py`
- [Graph rendering](https://github.com/vaniseth/ggas/blob/main/ggas/graphviz/render.py): `ggas/graphviz/render.py`

### Other components

- **Researcher**

## Connections

- Researcher → Pipeline stages: runs stages (evidence: `ggas/pipeline.py`)
- Pipeline stages → Shared config: reads settings (evidence: `ggas/pipeline.py`)
- Pipeline stages → Dataset loaders: loads seeds (evidence: `ggas/pipeline.py`)
- Pipeline stages → Attack harness: runs conversations (evidence: `ggas/pipeline.py`)
- Attack harness → Conversation transcripts: produces (evidence: `ggas/pipeline.py`)
- Pipeline stages → Conversation transcripts: writes transcripts (evidence: `ggas/pipeline.py`)
- Pipeline stages → Extracted features: extracts features (evidence: `ggas/pipeline.py`)
- Extracted features → HF compatibility: normalizes model outputs (evidence: `ggas/extract.py`)
- Extracted features → Attack harness: uses target (evidence: `ggas/extract.py`)
- Pipeline stages → Risk probe: trains probe (evidence: `ggas/pipeline.py`)
- Risk probe → Extracted features: reads activations (evidence: `ggas/probe.py`)
- Pipeline stages → Calibration: calibrates defense (evidence: `ggas/pipeline.py`)
- Calibration → Risk probe: scores candidates (evidence: `ggas/calibrate.py`)
- Calibration → RDS detector: tunes threshold (evidence: `ggas/calibrate.py`)
- Calibration → Steered target: tunes strength (evidence: `ggas/calibrate.py`)
- Pipeline stages → Steered target: configures steering (evidence: `ggas/pipeline.py`)
- RDS detector → Risk probe: scores nodes (evidence: `ggas/detect.py`)
- RDS detector → Extracted features: uses attention graph (evidence: `ggas/detect.py`)
- Steered target → RDS detector: detects risk (evidence: `ggas/steer.py`)
- Steered target → Risk probe: uses probe (evidence: `ggas/steer.py`)
- Steered target → Extracted features: extracts current features (evidence: `ggas/steer.py`)
- Steered target → HF compatibility: normalizes model outputs (evidence: `ggas/steer.py`)
- GGAS responder → Attack harness: uses target (evidence: `ggas/ggas_responder.py`)
- GGAS responder → Extracted features: extracts features (evidence: `ggas/ggas_responder.py`)
- GGAS responder → RDS detector: detects risk (evidence: `ggas/ggas_responder.py`)
- GGAS responder → Risk probe: scores nodes (evidence: `ggas/ggas_responder.py`)
- Model swapping → Attack harness: uses attack harness (evidence: `ggas/swap_runnner.py`)
- Model swapping → Dataset loaders: loads datasets (evidence: `ggas/swap_runnner.py`)
- Pipeline stages → Evaluation suite: runs evaluation (evidence: `ggas/pipeline.py`)
- Evaluation suite → Risk probe: uses probe (evidence: `ggas/eval_suite.py`)
- Evaluation suite → RDS detector: scores turns (evidence: `ggas/eval_suite.py`)
- Evaluation suite → Extracted features: extracts features (evidence: `ggas/eval_suite.py`)
- Evaluation table → Attack harness: runs model phases (evidence: `ggas/eval_table.py`)
- Evaluation table → Dataset loaders: loads evaluation sets (evidence: `ggas/eval_table.py`)
- Evaluation table → LlamaGuard baseline: compares baseline (evidence: `ggas/eval_table.py`)
- Evaluation table → Steered target: evaluates defense (evidence: `ggas/eval_table.py`)
- Graph capture → Graph snapshots: builds snapshots (evidence: `ggas/graphviz/capture.py`)
- Graph snapshots → Extracted features: extracts snapshot features (evidence: `ggas/graphviz/state.py`)
- Graph snapshots → RDS detector: scores snapshot (evidence: `ggas/graphviz/state.py`)
- Graph snapshots → Risk probe: uses risk probe (evidence: `ggas/graphviz/state.py`)