Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Antisource/heronaisec/llms.txt
Use this file to discover all available pages before exploring further.
All scientific variables for the baseline experiment live in configs/baseline.yaml. Implementation details — training loops, dataset loading, metric calculations — belong in Python code. The YAML file is the single source of truth for what an experiment does, not how it does it. Changing any parameter in this file and re-running python main.py is sufficient to produce a new, fully reproducible experiment.
Full configuration file
# ============================================================================
# Baseline Experiment Configuration
# Project: Beyond Binary Evaluation of Backdoor Inheritance
#
# This file defines a single reproducible experiment.
# Implementation details belong in Python code.
# Scientific variables belong here.
# ============================================================================
experiment:
name: baseline
seed: 42
output_dir: results/
checkpoint_dir: checkpoints/
# ----------------------------------------------------------------------------
# Dataset
# ----------------------------------------------------------------------------
dataset:
name: glue
subset: sst2
# ----------------------------------------------------------------------------
# Model
# ----------------------------------------------------------------------------
model:
name: distilbert-base-uncased
num_labels: 2
# ----------------------------------------------------------------------------
# Backdoor Attack
# ----------------------------------------------------------------------------
attack:
type: badnet
trigger: "cf"
poison_rate: 0.15
target_label: 1
# ----------------------------------------------------------------------------
# Initial Backdoor Training
# ----------------------------------------------------------------------------
training:
epochs: 3
learning_rate: 2.0e-5
batch_size: 32
weight_decay: 0.01
# ----------------------------------------------------------------------------
# Progressive Clean Fine-Tuning
# ----------------------------------------------------------------------------
intervention:
clean_ratios:
- 0.0
- 0.2
- 0.4
- 0.6
- 0.8
- 1.0
epochs: 2
# ----------------------------------------------------------------------------
# Reviewer Intervention
# ----------------------------------------------------------------------------
reviewer:
enabled: true
checkpoint_ratio: 0.4
model: prajjwal1/bert-tiny
epochs: 2
# ----------------------------------------------------------------------------
# Evaluation
# ----------------------------------------------------------------------------
evaluation:
metrics:
- attack_success_rate
- clean_accuracy
- trigger_confidence
- retention_ratio
# ----------------------------------------------------------------------------
# Visualization
# ----------------------------------------------------------------------------
visualization:
save_figures: true
dpi: 300
Configuration sections
experiment
Top-level identifiers and directory paths shared across the entire run.
| Key | Default | Description |
|---|
name | baseline | A short label embedded in the output directory name. run_baseline() creates results/<name>_<timestamp>/ using this value. |
seed | 42 | Global random seed for reproducibility. Passed to seed_everything(), which calls accelerate.utils.set_seed() to seed Python, NumPy, and PyTorch simultaneously. |
output_dir | results/ | Root directory under which each timestamped run directory is created. |
checkpoint_dir | checkpoints/ | Root directory declared for checkpoints. Checkpoint paths inside experiments/baseline.py are constructed relative to the run directory rather than this key directly, but this value is available for future use. |
dataset
Identifies the Hugging Face dataset used as the clean training and evaluation corpus.
| Key | Default | Description |
|---|
name | glue | Hugging Face dataset repository name, passed directly to load_dataset() in src/data.py. |
subset | sst2 | Dataset configuration (the second positional argument to load_dataset()). The framework validates that the loaded dataset contains sentence and label columns — any subset that satisfies this schema is compatible. |
The framework’s validate_dataset() function enforces that every split contains both a sentence column and a label column. If you switch to a different dataset or subset that uses different column names, validate_dataset() will raise a ValueError before any training begins. Rename or remap your columns to match the expected schema before changing this section.
model
Selects the pretrained transformer backbone and its classification head configuration.
| Key | Default | Description |
|---|
name | distilbert-base-uncased | Any Hugging Face model identifier compatible with AutoModelForSequenceClassification. Passed to both build_model() in src/models.py and build_tokenizer() in src/data.py. |
num_labels | 2 | Number of output classes. Set to 2 for binary sentiment classification on SST-2. Increase this if using a multi-class dataset. |
To swap the model backbone, replace model.name with any Hugging Face sequence classification model identifier. For example:model:
name: bert-base-uncased
num_labels: 2
model:
name: roberta-base
num_labels: 2
AutoModelForSequenceClassification.from_pretrained() and AutoTokenizer.from_pretrained() handle the rest.
attack
Defines the backdoor attack injected into the training data by apply_attack() in src/attacks.py.
| Key | Default | Description |
|---|
type | badnet | Attack type string used by the apply_attack() dispatcher. Currently only "badnet" is supported — passing any other string raises a ValueError. |
trigger | "cf" | The trigger token prepended to poisoned sentences by inject_trigger(). This rare token is the backdoor signal. |
poison_rate | 0.15 | Fraction of training examples that are poisoned (15 % by default). Controls how many examples are transformed by poison_dataset(). |
target_label | 1 | The attacker’s target class index. Poisoned examples have their label replaced with this value. In SST-2, label 1 corresponds to positive. |
training
Hyperparameters for the initial backdoor training phase. These values are passed directly to build_trainer() in src/train.py, which configures a Hugging Face Trainer with TrainingArguments.
| Key | Default | Description |
|---|
epochs | 3 | Number of training epochs for the initial backdoor training pass. |
learning_rate | 2.0e-5 | AdamW optimizer learning rate. Cast to float before being passed to TrainingArguments. |
batch_size | 32 | Per-device batch size used for both training (per_device_train_batch_size) and evaluation inference. |
weight_decay | 0.01 | L2 regularization coefficient applied to the AdamW optimizer. |
intervention
Controls the progressive clean fine-tuning study that measures how the backdoor degrades as more clean data is introduced.
| Key | Default | Description |
|---|
clean_ratios | [0.0, 0.2, 0.4, 0.6, 0.8, 1.0] | List of clean-data fractions to evaluate at. 0.0 is the unmodified baseline; 1.0 represents fine-tuning on the entire clean training set. Each non-zero ratio triggers a call to apply_clean_intervention(). |
epochs | 2 | Number of fine-tuning epochs applied at each intervention stage. |
To increase intervention granularity and produce a smoother degradation curve, add more values to clean_ratios. For example:intervention:
clean_ratios:
- 0.0
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
- 0.6
- 0.7
- 0.8
- 0.9
- 1.0
reviewer
Configuration for the reviewer intervention visualization. This section controls how plot_reviewer_intervention() annotates the persistence curve with a specific checkpoint marker. The reviewer model itself is scaffolded but not yet active — see the Extending the Framework guide for details.
| Key | Default | Description |
|---|
enabled | true | Whether to generate the reviewer_intervention.png figure. When false, only persistence_curve.png is produced. |
checkpoint_ratio | 0.4 | The clean_ratio value to mark as the reviewer’s checkpoint on the figure — corresponds to the 40 % intervention stage by default. |
model | prajjwal1/bert-tiny | Reviewer model identifier reserved for the Phase 2 reviewer intervention implementation. |
epochs | 2 | Reviewer training epochs — reserved for future implementation. |
evaluation
Declares which metrics are recorded at each intervention stage. The actual computation is performed by the corresponding functions in src/evaluation.py; this list serves as documentation of the intended metric set.
| Metric | Computed by | Description |
|---|
attack_success_rate | compute_attack_success_rate() | Fraction of fully-triggered test examples classified as the attacker’s target_label. |
clean_accuracy | compute_clean_accuracy() | Standard classification accuracy on the clean (untriggered) test split. |
trigger_confidence | compute_trigger_confidence() | Mean softmax probability assigned to target_label on triggered inputs. |
retention_ratio | compute_retention_ratio() | Normalized backdoor persistence: ASR(t) / ASR(0), where ASR(0) is the baseline attack success rate before any intervention. |
visualization
Controls figure generation at the end of the experiment.
| Key | Default | Description |
|---|
save_figures | true | When true, save_results() calls plot_backdoor_persistence() and (if reviewer.enabled) plot_reviewer_intervention() to write PNG files into results/<run>/figures/. Set to false to skip figure generation. |
dpi | 300 | Figure resolution in dots per inch, suitable for publication-quality output. |