# debdev25/ledd architecture

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

- Interactive diagram: https://gitdiagram.com/debdev25/ledd
- Repository: https://github.com/debdev25/ledd

## Overview

LEDD is a research toolkit for detecting diffusion-generated images, with a dual-stream image classifier and evaluation/explanation workflows. The documented path is to prepare and leak-check an image archive, split and load it, train the staged detector, then evaluate and explain it; baseline comparisons and efficiency measurement are additional capabilities. Source excerpts show key model, data, training, and attribution dependencies. Some documented CLI capabilities are represented at their package directory because their implementation files were not sampled.

Main entry points: [`ledd/engine/train.py`](https://github.com/debdev25/ledd/blob/main/ledd/engine/train.py) (Staged trainer), [`ledd/models/detector.py`](https://github.com/debdev25/ledd/blob/main/ledd/models/detector.py) (Dual-stream detector), [`ledd/engine/evaluate.py`](https://github.com/debdev25/ledd/blob/main/ledd/engine/evaluate.py) (Evaluation protocol), [`ledd/models/frequency.py`](https://github.com/debdev25/ledd/blob/main/ledd/models/frequency.py) (Frequency stream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data pipeline"]
  node_prepare["Archive preparation<br/>[prepare.py]"]
  node_leak["Leak check<br/>[leak_check.py]"]
  node_splits["Generator splits<br/>[splits.py]"]
  node_dataset["Dataset and loaders<br/>[dataset.py]"]
  node_degradations["Image degradations<br/>[degradations.py]"]
end

subgraph group_model["Detection model"]
  node_detector["Dual-stream detector<br/>[detector.py]"]
  node_spatial["Spatial stream<br/>[spatial.py]"]
  node_frequency["Frequency stream<br/>[frequency.py]"]
  node_fft["Spectrum and bands<br/>[fft.py]"]
  node_fusion["Stream fusion<br/>[fusion.py]"]
  node_attention["Recorded attention<br/>[attention.py]"]
end

subgraph group_train["Training"]
  node_train["Staged trainer<br/>[train.py]"]
  node_losses["Training objectives"]
end

subgraph group_analysis["Evaluation and explanation"]
  node_evaluate["Evaluation protocol<br/>[evaluate.py]"]
  node_metrics["Classification metrics<br/>[metrics.py]"]
  node_explain["Attribution and faithfulness"]
  node_chefer["Attention relevance<br/>[chefer.py]"]
  node_efficiency["Efficiency measurement<br/>[efficiency.py]"]
  node_calibration["Threshold calibration"]
end

subgraph group_compare["Comparisons"]
  node_baselines["Baseline models<br/>[simple.py]"]
  node_external["External baselines<br/>[external.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"builds archive"| node_prepare
node_researcher -->|"checks leakage"| node_leak
node_researcher -->|"trains stages"| node_train
node_researcher -->|"runs protocol"| node_evaluate
node_researcher -->|"requests explanations"| node_explain
node_researcher -->|"measures cost"| node_efficiency
node_researcher -->|"compares models"| node_baselines
node_train -->|"creates splits"| node_splits
node_train -->|"builds loaders"| node_dataset
node_train -->|"builds model"| node_detector
node_train -->|"uses objectives"| node_losses
node_dataset -->|"applies augmentation"| node_degradations
node_detector -->|"uses stream"| node_spatial
node_detector -->|"uses stream"| node_frequency
node_detector -->|"fuses streams"| node_fusion
node_frequency -->|"extracts bands"| node_fft
node_frequency -->|"encodes tokens"| node_attention
node_fusion -->|"cross-attends"| node_attention
node_evaluate -->|"builds loaders"| node_dataset
node_evaluate -->|"loads partitions"| node_splits
node_evaluate -->|"computes scores"| node_metrics
node_explain -->|"computes relevance"| node_chefer
node_chefer -->|"reads attention"| node_attention
node_explain -->|"evaluates faithfulness"| node_metrics
node_baselines -->|"offers adapters"| node_external

click node_prepare "https://github.com/debdev25/ledd/blob/main/ledd/data/prepare.py"
click node_leak "https://github.com/debdev25/ledd/blob/main/ledd/data/leak_check.py"
click node_splits "https://github.com/debdev25/ledd/blob/main/ledd/data/splits.py"
click node_dataset "https://github.com/debdev25/ledd/blob/main/ledd/data/dataset.py"
click node_degradations "https://github.com/debdev25/ledd/blob/main/ledd/data/degradations.py"
click node_detector "https://github.com/debdev25/ledd/blob/main/ledd/models/detector.py"
click node_spatial "https://github.com/debdev25/ledd/blob/main/ledd/models/spatial.py"
click node_frequency "https://github.com/debdev25/ledd/blob/main/ledd/models/frequency.py"
click node_fft "https://github.com/debdev25/ledd/blob/main/ledd/models/fft.py"
click node_fusion "https://github.com/debdev25/ledd/blob/main/ledd/models/fusion.py"
click node_attention "https://github.com/debdev25/ledd/blob/main/ledd/models/attention.py"
click node_train "https://github.com/debdev25/ledd/blob/main/ledd/engine/train.py"
click node_losses "https://github.com/debdev25/ledd/tree/main/ledd/losses"
click node_evaluate "https://github.com/debdev25/ledd/blob/main/ledd/engine/evaluate.py"
click node_metrics "https://github.com/debdev25/ledd/blob/main/ledd/engine/metrics.py"
click node_explain "https://github.com/debdev25/ledd/tree/main/ledd/explain"
click node_chefer "https://github.com/debdev25/ledd/blob/main/ledd/explain/chefer.py"
click node_efficiency "https://github.com/debdev25/ledd/blob/main/ledd/efficiency.py"
click node_calibration "https://github.com/debdev25/ledd/blob/main/scripts/calibrate_threshold.py"
click node_baselines "https://github.com/debdev25/ledd/blob/main/ledd/baselines/simple.py"
click node_external "https://github.com/debdev25/ledd/blob/main/ledd/baselines/external.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_prepare,node_leak,node_splits,node_dataset,node_degradations toneBlue
class node_detector,node_spatial,node_frequency,node_fft,node_fusion,node_attention toneAmber
class node_train,node_losses toneMint
class node_evaluate,node_metrics,node_explain,node_chefer,node_efficiency,node_calibration toneRose
class node_baselines,node_external,node_researcher toneIndigo
```

## Components

### Data pipeline

- [Archive preparation](https://github.com/debdev25/ledd/blob/main/ledd/data/prepare.py): `ledd/data/prepare.py`
- [Leak check](https://github.com/debdev25/ledd/blob/main/ledd/data/leak_check.py): `ledd/data/leak_check.py`
- [Generator splits](https://github.com/debdev25/ledd/blob/main/ledd/data/splits.py): `ledd/data/splits.py`
- [Dataset and loaders](https://github.com/debdev25/ledd/blob/main/ledd/data/dataset.py): `ledd/data/dataset.py`
- [Image degradations](https://github.com/debdev25/ledd/blob/main/ledd/data/degradations.py): `ledd/data/degradations.py`

### Detection model

- [Dual-stream detector](https://github.com/debdev25/ledd/blob/main/ledd/models/detector.py): `ledd/models/detector.py`
- [Spatial stream](https://github.com/debdev25/ledd/blob/main/ledd/models/spatial.py): `ledd/models/spatial.py`
- [Frequency stream](https://github.com/debdev25/ledd/blob/main/ledd/models/frequency.py): `ledd/models/frequency.py`
- [Spectrum and bands](https://github.com/debdev25/ledd/blob/main/ledd/models/fft.py): `ledd/models/fft.py`
- [Stream fusion](https://github.com/debdev25/ledd/blob/main/ledd/models/fusion.py): `ledd/models/fusion.py`
- [Recorded attention](https://github.com/debdev25/ledd/blob/main/ledd/models/attention.py): `ledd/models/attention.py`

### Training

- [Staged trainer](https://github.com/debdev25/ledd/blob/main/ledd/engine/train.py): `ledd/engine/train.py`
- [Training objectives](https://github.com/debdev25/ledd/tree/main/ledd/losses): `ledd/losses`

### Evaluation and explanation

- [Evaluation protocol](https://github.com/debdev25/ledd/blob/main/ledd/engine/evaluate.py): `ledd/engine/evaluate.py`
- [Classification metrics](https://github.com/debdev25/ledd/blob/main/ledd/engine/metrics.py): `ledd/engine/metrics.py`
- [Attribution and faithfulness](https://github.com/debdev25/ledd/tree/main/ledd/explain): `ledd/explain`
- [Attention relevance](https://github.com/debdev25/ledd/blob/main/ledd/explain/chefer.py): `ledd/explain/chefer.py`
- [Efficiency measurement](https://github.com/debdev25/ledd/blob/main/ledd/efficiency.py): `ledd/efficiency.py`
- [Threshold calibration](https://github.com/debdev25/ledd/blob/main/scripts/calibrate_threshold.py): `scripts/calibrate_threshold.py`

### Comparisons

- [Baseline models](https://github.com/debdev25/ledd/blob/main/ledd/baselines/simple.py): `ledd/baselines/simple.py`
- [External baselines](https://github.com/debdev25/ledd/blob/main/ledd/baselines/external.py): `ledd/baselines/external.py`

### Other components

- **Researcher**

## Connections

- Researcher → Archive preparation: builds archive (evidence: `README.md`)
- Researcher → Leak check: checks leakage (evidence: `README.md`)
- Researcher → Staged trainer: trains stages (evidence: `README.md`)
- Researcher → Evaluation protocol: runs protocol (evidence: `README.md`)
- Researcher → Attribution and faithfulness: requests explanations (evidence: `README.md`)
- Researcher → Efficiency measurement: measures cost (evidence: `README.md`)
- Researcher → Baseline models: compares models (evidence: `README.md`)
- Staged trainer → Generator splits: creates splits (evidence: `ledd/engine/train.py`)
- Staged trainer → Dataset and loaders: builds loaders (evidence: `ledd/engine/train.py`)
- Staged trainer → Dual-stream detector: builds model (evidence: `ledd/engine/train.py`)
- Staged trainer → Training objectives: uses objectives (evidence: `ledd/engine/train.py`)
- Dataset and loaders → Image degradations: applies augmentation (evidence: `ledd/data/dataset.py`)
- Dual-stream detector → Spatial stream: uses stream (evidence: `ledd/models/detector.py`)
- Dual-stream detector → Frequency stream: uses stream (evidence: `ledd/models/detector.py`)
- Dual-stream detector → Stream fusion: fuses streams (evidence: `ledd/models/detector.py`)
- Frequency stream → Spectrum and bands: extracts bands (evidence: `ledd/models/frequency.py`)
- Frequency stream → Recorded attention: encodes tokens (evidence: `ledd/models/frequency.py`)
- Stream fusion → Recorded attention: cross-attends (evidence: `ledd/models/fusion.py`)
- Evaluation protocol → Dataset and loaders: builds loaders (evidence: `ledd/engine/evaluate.py`)
- Evaluation protocol → Generator splits: loads partitions (evidence: `ledd/engine/evaluate.py`)
- Evaluation protocol → Classification metrics: computes scores (evidence: `ledd/engine/evaluate.py`)
- Attribution and faithfulness → Attention relevance: computes relevance (evidence: `ledd/explain/__init__.py`)
- Attention relevance → Recorded attention: reads attention (evidence: `ledd/explain/chefer.py`)
- Attribution and faithfulness → Classification metrics: evaluates faithfulness (evidence: `ledd/explain/faithfulness.py`)
- Baseline models → External baselines: offers adapters (evidence: `ledd/baselines/__init__.py`)
