Run fairness-aware search

QuOptuna can search for models that stay accurate AND equitable across a protected attribute. You supply a categorical sensitive_feature column; multiclass problems also need a favorable_class.

Modes

Set fairness_mode:

Mode	Behavior
`off` (default)	No fairness handling.
`constrained`	TPE feasibility constraint — every trial must satisfy a disparity threshold `fairness_threshold`.
`multi_objective`	Pareto front of F1 vs disparity. Pruning is disabled in this mode.

Metrics

Set fairness_metric:

Metric	Notes
`equal_opportunity_difference` (default)	Difference in true-positive rate across groups.
`disparate_impact`	Ratio-based four-fifths rule: feasible when the ratio is at or above the threshold (default `0.8`).
`demographic_parity_difference`	Difference in positive-prediction rate across groups.

For the difference metrics, fairness_threshold defaults to 0.1 (feasible when disparity is at or below it). constrained mode requires sampler="tpe" (the API returns 422 otherwise); multi_objective mode forces the pruner to none.

Fairness search is available via POST /api/v1/optimize, the Optimizer, and the CLI (--sensitive-feature, --fairness-mode, --fairness-metric, --fairness-threshold, --favorable-class).

Constrained search (CLI)

Keep every kept trial within a disparity budget:

quoptuna optimize --csv data.csv --target label \
  --sampler tpe \
  --sensitive-feature sex \
  --fairness-mode constrained \
  --fairness-metric equal_opportunity_difference \
  --fairness-threshold 0.1

Only trials whose disparity is within 0.1 are treated as feasible; TPE steers toward the feasible region and best_trial comes from it.

Multi-objective search (CLI)

Explore the trade-off instead of committing to one threshold:

quoptuna optimize --csv data.csv --target label \
  --sensitive-feature sex \
  --fairness-mode multi_objective \
  --fairness-metric equal_opportunity_difference

Read a Pareto front

multi_objective produces a set of non-dominated trials — each is optimal for some balance of F1 vs disparity, and none strictly beats another on both. There is no single “best”: you pick the operating point. Plot F1 against disparity across the front and choose the trial whose trade-off matches your governance requirements (for example, the highest-F1 trial whose disparity stays under your acceptable ceiling).