fairness-training 0.1.0

Guaranteed fairness constraints for PyTorch neural networks via differentiable optimization layers.

fairness_training

Guaranteed fairness constraints for PyTorch neural networks

Why fairness_training?

Most fairness methods either encourage fairness (soft penalties) or correct predictions after training (post-hoc). Both leave the door open for violations.

fairness_training uses a differentiable convex optimization layer appended to any neural network. This layer projects predictions onto the set satisfying your fairness constraints — making violations mathematically impossible on every batch.

Approach	Guarantee	Differentiable	Works with any architecture
Penalty / regularization	No	Yes	Yes
Post-hoc calibration	No	No	Yes
fairness_training	Yes	Yes	Yes

---

Features

• Hard constraints — fairness gaps are bounded by your chosen ε on every training batch
• Drop-in wrapper — FairModel.wrap(your_model, ...) works with any nn.Module
• Online inference — primal-dual algorithm provides aggregate guarantees for streaming / small-batch deployment
• Three built-in metrics — demographic parity, mean residual fairness, equalized odds
• Extensible — subclass FairnessMetric to define custom affine fairness constraints

---

Installation

pip install fairness_training[train,verify]       # training + fairness layer (recommended)
pip install fairness_training[train,verify,viz]   # + matplotlib visualization utilities
pip install fairness_training[full]               # everything

---

Quick Example

import torch.nn as nn
import torch.optim as optim
from fairness_training import FairModel, FairTrainer, create_stratified_dataloaders

# Any standard PyTorch backbone
backbone = nn.Sequential(
    nn.Linear(20, 64), nn.ReLU(),
    nn.Linear(64, 32), nn.ReLU(),
    nn.Linear(32, 1), nn.Sigmoid(),
)

# Wrap with fairness constraints — bounds inferred automatically
model = FairModel.wrap(
    backbone,
    protected_attr_idx=0,       # column index of protected attribute in X
    fairness_tolerance=0.05,    # ε: max allowed group mean prediction gap
    fairness_metric='mean_pred',
)

# Stratified batching keeps group ratios constant → per-batch constraints = aggregate fairness
train_loader, val_loader, test_loader = create_stratified_dataloaders(
    X_train, y_train, X_val, y_val, X_test, y_test,
    protected_attr_idx=0, batch_size_train=256,
)

trainer = FairTrainer(model, nn.BCELoss(), optim.Adam(model.parameters()))
history = trainer.fit(train_loader, val_loader, epochs=50)

metrics = trainer.evaluate(test_loader)
print(f"Test loss:    {metrics['test_loss']:.4f}")
print(f"Fairness gap: {metrics['weighted_avg_fairness_gap']:.4f}  (target ≤ 0.05)")

---

Supported Fairness Metrics

Metric	Constraint	String alias
Mean Prediction Parity	`	E[ŷ
Mean Residual Fairness	`	E[y−ŷ
Equalized Odds	`	E[ŷ
Custom	Subclass FairnessMetric	—

---

Documentation

Full documentation — concepts, API reference, and end-to-end examples — is available at the project's GitHub Pages site.

---

Citation

If you use fairness_training in your research, please cite:

@inproceedings{troxell2026fairness,
  title     = {Differentiable Optimization Layers for Guaranteed Fairness in Deep Learning},
  author    = {Troxell, David and Roemer, Noah and Mont{\'u}far, Guido},
  booktitle = {Proceedings of the 43rd International Conference on Machine Learning},
  year      = {2026},
  note      = {To appear}
}

This library builds on the excellent cvxpylayers package:

@inproceedings{agrawal2019differentiable,
  title={Differentiable Convex Optimization Layers},
  author={Agrawal, Akshay and Amos, Brandon and Barratt, Shane and Boyd, Stephen and Diamond, Steven and Kolter, Zico},
  booktitle={Advances in Neural Information Processing Systems},
  volume={32},
  year={2019}
}

---

License

MIT