fair-seldonian 2.0.0

Fairness-constrained machine learning using Seldonian algorithms with confidence bound optimizations

Fair-Seldonian

Fairness-constrained machine learning with high-confidence guarantees

---

A Python framework implementing the Quasi-Seldonian Algorithm (QSA) for training ML models that provably satisfy fairness constraints. Given a behavioral constraint and a confidence level δ, the algorithm either returns a model satisfying the constraint with probability ≥ 1 − δ, or returns No Solution Found — never an unsafe model.

Built on the Seldonian algorithm framework by Thomas et al. (2019), with extensions for tighter confidence bounds through constant-aware delta allocation, union bound optimization, and decomposed candidate-safety intervals.

Quick links

Documentation	parulgupta1004.github.io/fair-seldonian
Repository	github.com/parulgupta1004/fair-seldonian
Paper	Thomas et al., Science 366 (2019) — doi:10.1126/science.aag3311

Installation

git clone https://github.com/parulgupta1004/fair-seldonian.git
cd fair-seldonian
uv sync                          # core dependencies
uv sync --extra experiments      # + Ray for parallel experiments
uv sync --extra plots            # + matplotlib for visualization

Or with pip:

pip install fair-seldonian
pip install "fair-seldonian[experiments,plots]"

Usage

from fair_seldonian.algorithms import QSA
from fair_seldonian.models import eval_ghat
from fair_seldonian.data import get_data, data_split

data = get_data(N=10000, features=5, t_ratio=0.4,
                tp0_ratio=0.4, tp1_ratio=0.6, random_seed=42)
X_te, Y_te, T_te, X_tr, Y_tr, T_tr = data_split(
    frac=0.5, All=data, random_state=1, mTest=0.2)

theta, theta1, passed = QSA(X_tr, Y_tr, T_tr, "opt", None, None)

if passed:
    print("Upper bound:", eval_ghat(theta, theta1, X_te, Y_te, T_te, "opt"))
else:
    print("No Solution Found")

Custom configuration:

from fair_seldonian.config import SeldonianConfig
from fair_seldonian.constraints.inequalities import Inequality

config = SeldonianConfig(delta=0.01, inequality=Inequality.T_TEST, candidate_ratio=0.5)
theta, theta1, passed = QSA(X_tr, Y_tr, T_tr, "opt", None, None, config)

Algorithm variants

Mode	Description
base	Standard Hoeffding bound, uniform δ-splitting
mod	Decomposed candidate/safety estimation error
const	Constant-aware δ allocation
bound	Union bound optimization for repeated variables
opt	All optimizations combined

uv run python -m fair_seldonian.experiments.runner opt
uv run python -m fair_seldonian.experiments.plots

Citation

@software{fair_seldonian,
  author = {Parul Gupta},
  title  = {Fair Seldonian Framework},
  year   = {2020}
}

This work builds on:

Thomas, P.S., da Silva, B.C., Barto, A.G., Giguere, S., Brun, Y., & Brunskill, E. (2019). "Preventing undesirable behavior of intelligent machines." Science, 366(6468), 999–1004.

License

MIT

---

Author: Parul Gupta · Initially developed under the guidance of Dr. Philip S. Thomas, University of Massachusetts Amherst.