When Does Span-Guided Detoxification Help?

Research code for testing when harmful-span guidance improves text detoxification—and when unconstrained rewriting is preferable. The central comparison holds the generator and decoding setup fixed while varying whether gold harmful spans are supplied as an explicit editing constraint.

Resource	Status
Paper	Public archival link pending
Code	Paired generation, evaluation, and sensitivity analysis available
Data	Not redistributed; local schema documented in DATA.md
License	MIT for code; upstream terms apply to data and models

Study design

same source text + same generator
├── unguided rewrite
└── span-guided rewrite
        ↓
toxicity reduction × meaning preservation × human preference

The analysis treats guidance as a conditional intervention rather than a monotonic improvement. In particular, it supports breakdowns by source severity and sensitivity to the weight assigned to toxicity reduction versus semantic preservation.

Repository map

Path	Purpose
src/generate_pairs.py	Produce matched guided and unguided rewrites
src/evaluate_pairs.py	Evaluate toxicity reduction and BERTScore
scripts/lambda_sensitivity.py	Audit preference across metric weights
scripts/recompute_preferences.py	Recompute aggregate preference summaries

Setup

git clone https://github.com/cosmic4dev/span-guided-detoxification.git
cd span-guided-detoxification
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run

Generate paired rewrites:

python src/generate_pairs.py \
  --input_csv /path/to/local/input.csv \
  --output_csv outputs/pairs.csv \
  --generator_model_name Qwen/Qwen3-8B

Evaluate them with Perspective toxicity and BERTScore:

export PERSPECTIVE_API_KEY=your_key
python src/evaluate_pairs.py \
  --input_csv outputs/pairs.csv \
  --output_json outputs/evaluation.json \
  --output_csv outputs/evaluation.csv

Run the preregisterable metric-weight sensitivity analysis:

python scripts/lambda_sensitivity.py \
  --input_json outputs/evaluation.json \
  --output_json outputs/lambda_sensitivity.json

See DATA.md for the expected local schema and release boundary.

Interpretation

Automatic toxicity scores and semantic similarity are diagnostics, not substitutes for human judgment. Results should not be read as showing that span guidance is universally beneficial; the intended contribution is identifying the conditions under which guidance changes the toxicity–meaning trade-off.

Related project

The multilingual detector and structured guidance framework is available in AEGIS.

License

Code is released under the MIT License. External datasets, models, and APIs retain their own terms.

Citation

Archival citation metadata will be added when a public paper record is available. Until then, please reference this repository by its title and URL.