README.md

---
license: apache-2.0
language:
  - en
library_name: transformers
pipeline_tag: token-classification
base_model: bert-base-uncased
tags:
  - bias-detection
  - social-bias
  - token-classification
  - gus-net
  - fairness
  - interpretability
datasets:
  - ethical-spectacle/gus-dataset-v1
metrics:
  - f1
---

# GUS-Net (BERT)

Token-level **social-bias detector** built on `bert-base-uncased`. Given a
sentence, it tags each token with one of four bias categories following a 7-label
BIO scheme, so a downstream system can highlight *which words* carry bias, not just
whether a sentence is biased.

This is the flagship / default checkpoint of the **Attention Atlas** project (a
master's thesis on interpretable bias detection through transformer attention).
This published checkpoint is the **sparsity-regularised** training run.

- **Base model:** `bert-base-uncased`
- **Task:** multi-label token classification (per-token sigmoid, thresholded)
- **Language:** English
- **Related models:** [`pinthoz/gus-net-bert-large`](https://huggingface.co/pinthoz/gus-net-bert-large), [`pinthoz/gus-net-gpt2`](https://huggingface.co/pinthoz/gus-net-gpt2), [`pinthoz/gus-net-gpt2-medium`](https://huggingface.co/pinthoz/gus-net-gpt2-medium)

## Label scheme

The model outputs 7 BIO labels. `STEREO`, `GEN` and `UNFAIR` are the three bias
categories; `O` is "no bias".

| Index | Label     | Category                          |
|-------|-----------|-----------------------------------|
| 0     | O         | none                              |
| 1     | B-STEREO  | Stereotype (span start)           |
| 2     | I-STEREO  | Stereotype (span inside)          |
| 3     | B-GEN     | Generalisation (span start)       |
| 4     | I-GEN     | Generalisation (span inside)      |
| 5     | B-UNFAIR  | Unfair language (span start)      |
| 6     | I-UNFAIR  | Unfair language (span inside)     |

- **GEN** — a blanket generalisation about a group.
- **UNFAIR** — unfair / disparaging language toward a group.
- **STEREO** — a stereotype attributed to a group.

## Important: multi-label + per-label thresholds

Outputs are **per-token sigmoid probabilities** (multi-label), not a softmax.
Predictions are obtained by thresholding each label. The F1-optimised thresholds
for this checkpoint (order `[O, B-STEREO, I-STEREO, B-GEN, I-GEN, B-UNFAIR, I-UNFAIR]`) are:

```
[0.4265, 0.4071, 0.3938, 0.3462, 0.3669, 0.3184, 0.3630]
```

Using a flat 0.5 threshold will under-detect bias — use the values above.

## Usage

```python
import torch
from transformers import BertTokenizerFast, BertForTokenClassification

model_id = "pinthoz/gus-net-bert"
tok = BertTokenizerFast.from_pretrained("bert-base-uncased")
model = BertForTokenClassification.from_pretrained(model_id).eval()

CATEGORY_INDICES = {"STEREO": [1, 2], "GEN": [3, 4], "UNFAIR": [5, 6]}
THRESHOLDS = [0.4265, 0.4071, 0.3938, 0.3462, 0.3669, 0.3184, 0.3630]

text = "Women are naturally worse at driving."
enc = tok(text, return_tensors="pt")
with torch.no_grad():
    probs = torch.sigmoid(model(input_ids=enc["input_ids"],
                                attention_mask=enc["attention_mask"]).logits)[0]

tokens = tok.convert_ids_to_tokens(enc["input_ids"][0])
for i, tokn in enumerate(tokens):
    if tokn in ("[CLS]", "[SEP]", "[PAD]"):
        continue
    fired = {cat: float(probs[i, idxs].max())
             for cat, idxs in CATEGORY_INDICES.items()
             if any(probs[i, j] > THRESHOLDS[j] for j in idxs)}
    if fired:
        print(f"{tokn:15s} -> {fired}")
```

## Training data

Fine-tuned on the **GUS-Net dataset** — a token-level social-bias corpus
annotated for **G**eneralisations, **U**nfairness and **S**tereotypes, from which
this model's 7-label scheme is derived
([`ethical-spectacle/gus-dataset-v1`](https://huggingface.co/datasets/ethical-spectacle/gus-dataset-v1)).

**Difference from the original GUS-Net dataset and models:** in the raw corpus
punctuation is mostly **fused to the preceding word** rather than tokenised
separately, so a comma or full stop falling inside a labelled span inherits that
span's categories — the sentence-final mark carries a bias label in 1,942 of the
3,739 sentences, and an in-span comma in 270. The data used here **splits each
mark into a token of its own and labels it non-bias `O`**, repairing the BIO
sequence where the split interrupts a span, since punctuation is not a
social-bias carrier. On a held-out sample this checkpoint labels the
sentence-final mark as bias in **0 of 741 sentences (0.0 %)**, matching the
cleaned gold.

## Evaluation

### StereoSet (intersentence split, 2123 examples)

| Metric | Score |
|--------|-------|
| LMS (language-modeling score, higher is better) | **71.81** |
| SS (stereotype score, **50 = ideal**)           | **53.09** |
| ICAT (bias-adjusted quality)                     | **67.38** |

Per-category SS: gender 58.68 · race 50.10 · religion 46.15 · profession 55.62.

### Token classification (GUS-Net held-out test set)

Held-out partition (747 sentences) of the stratified cross-validation fold this
checkpoint was trained against — `StratifiedKFold(n_splits=5, shuffle=True,
random_state=42)` over the **cleaned** corpus (see *Training data*), fold 4 —
scored with the per-label thresholds above. Each category aggregates its B-/I-
labels; the micro average covers the three bias categories and excludes the
majority `O` class. Label alignment mirrors training (secondary subtokens masked).

| Category | Precision | Recall | F1 |
|----------|-----------|--------|----|
| O (non-bias) | 0.887 | 0.936 | 0.911 |
| GEN      | 0.812 | 0.682 | 0.741 |
| UNFAIR   | 0.413 | 0.497 | 0.451 |
| STEREO   | 0.759 | 0.708 | 0.733 |
| **Micro-avg** | 0.727 | 0.676 | 0.701 |

`UNFAIR` is the weakest category on this checkpoint: treat unfair-language spans
as candidates to review, not as detections.

**The sparsity penalty costs recall.** Measured against an otherwise identical
run without the penalty, on the same corpus and the same fold, this checkpoint
holds similar precision (0.727 vs 0.726) but recalls less (0.676 vs 0.829), for
~7 points of micro-F1. That is the intended trade: `LAMBDA_SPARSE` concentrates
attention mass on fewer tokens, yielding tighter, more conservative spans.

## Limitations & intended use

- **Research / auditing tool**, not a content-moderation oracle. Predictions
  reflect a specific operationalisation of bias (clear generalisations,
  unfairness and stereotypes about a group); subtle, implicit or
  context-dependent bias may be missed.
- English only.
- Labels are not error-free; treat spans as evidence to review, not ground truth.
- Do **not** use for automated decisions about individuals.

## Citation

If you use these models, please cite the GUS-Net dataset and benchmark:

```bibtex
@article{powers2024gusnet,
  title   = {GUS-Net: Social Bias Classification in Text with Generalizations, Unfairness, and Stereotypes},
  author  = {Powers, Maximus and Raza, Shaina and Chang, Alex and Riaz, Rehana and Mavani, Umang and Jonala, Harshitha Reddy and Tiwari, Ansh and Wei, Hua},
  journal = {arXiv preprint arXiv:2410.08388},
  year    = {2024}
}
```

## License

Weights released under **Apache-2.0** (matching the `bert-base-uncased` base
model). The Attention Atlas code is MIT-licensed.