fairpipe

Fairness measurement, mitigation, monitoring, and pipeline tooling for ML workflows.
PyPI package: fairpipe · License: Apache-2.0 · Python 3.10+

Fairlearn and AIF360 provide individual pre/in/post-processing components; fairpipe provides a YAML-configured baseline→transform→validate workflow with CI/CD exit codes.

Install

pip install fairpipe

Optional extras: pip install 'fairpipe[api]' · 'fairpipe[training]' · 'fairpipe[monitoring]' · 'fairpipe[adapters]' · 'fairpipe[llm]'
(REST API, PyTorch training helpers, dashboards/drift, Fairlearn/Aequitas backends, LLM provider SDKs.) Full detail is in the documentation below—not duplicated here.

Setting LLM provider credentials

LLM fairness evaluation (see fairpipe.llm_evals) uses provider SDKs installed via the optional extra:

pip install 'fairpipe[llm]'

Credentials are read from environment variables only — never from YAML config files or CLI flags:

Toxicity/sentiment disparity uses a lexical scorer by default (no moderation API key). Plug in an external scorer via ToxicitySentimentEvaluator.run_async(scorer=...).

Example:

export OPENAI_API_KEY="sk-..."
# or
export ANTHROPIC_API_KEY="..."

When using the CLI, run fairpipe llm-eval --dry-run to estimate request volume and approximate cost before making live provider calls. Live HTTP is forbidden by default; set FAIRPIPE_LLM_ALLOW_LIVE=1 on CLI, REST, Jupyter, or CI jobs that should call a provider (same flag — see Environment Variables). Replay-from-cache_dir does not need it.

fairpipe llm-eval --config llm_eval.yml --dry-run
fairpipe llm-eval --config llm_eval.yml --report-md artifacts/llm_report.md --with-ci
fairpipe llm-eval --config llm_eval.yml --metric counterfactual_fairness_divergence --threshold 0.25

See docs/llm_evals_intro.md for configuration, REST POST /llm-eval, and sampling production logs into the existing tracker.

Documentation

Start here (hosted): Documentation — SvrusIO.github.io/fAIr
Built from this repo’s Sphinx sources; includes getting started, user guide, API reference, integration, performance, and security links.

In-repo references (for browsing on GitHub or a checkout):

Quick start

CLI

fairpipe validate \
  --csv data.csv \
  --y-true y_true \
  --y-pred y_pred \
  --sensitive gender \
  --with-ci

fairpipe run-pipeline --config config.yml --csv data.csv --output-dir artifacts/

Python

from fairpipe import load_data
from fairpipe.metrics import FairnessAnalyzer

df = load_data("data.csv")
analyzer = FairnessAnalyzer(min_group_size=30)
result = analyzer.demographic_parity_difference(
    y_pred=df["y_pred"],
    sensitive=df["gender"],
    with_ci=True,
)
print(result.value, result.ci)

CLI commands, YAML configuration, workflow orchestration, training, monitoring, and the optional REST API are documented on the docs site and in docs/api.md.

CI/CD Integration

Add fairness validation to every pull request with the companion GitHub Action:

# .github/workflows/fairness-check.yml
name: Fairness Check
on: [pull_request]

jobs:
  fairness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SvrusIO/fairpipe-action@v1
        with:
          csv: data/predictions.csv
          y-true: y_true
          y-pred: y_pred
          sensitive: gender
          threshold: "0.05"
          metric: "equalized_odds_difference"
          fail-on-violation: "true"

Point csv at your predictions file. If equalized odds difference exceeds 0.05, the PR is blocked. A full fairness report is written to the Actions job summary — metric values, confidence intervals, group breakdowns — permanently attached to the commit.

Gate LLM fairness evals the same way. Live provider HTTP is forbidden by default (LiveLLMCallForbidden); a job that should call a provider must set FAIRPIPE_LLM_ALLOW_LIVE=1 — that is the correct safe default, not a workaround. Replay-from-cache_dir jobs do not need the flag.

# .github/workflows/llm-fairness-check.yml
name: LLM Fairness Check
on: [pull_request]

jobs:
  llm-fairness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SvrusIO/fairpipe-action@v1
        env:
          FAIRPIPE_LLM_ALLOW_LIVE: "1"
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          config: llm_eval.yml
          metric: "counterfactual_fairness_divergence"
          threshold: "0.25"
          fail-on-violation: "true"

A red check can be decoded without opening the report:

llm-fairness-check mode in the Action is a companion-repo follow-up (BL-010). This package already exposes the same with: keys via fairpipe llm-eval --threshold / --metric and run_llm_fairness_check().

→ SvrusIO/fairpipe-action

Development

git clone https://github.com/SvrusIO/fAIr.git
cd fAIr
pip install -e ".[dev]"
pytest -q

See CONTRIBUTING.md and SECURITY.md.

Case Studies

Real-world bias audits demonstrating fairpipe's full pipeline — from measurement and detection through mitigation and CI/CD integration.

LLM Counterfactual Fairness

Measures gender-coded divergence in LLM hiring recommendations using the counterfactual fairness probe with committed live-recorded Anthropic responses replayed from cache (no API key required). Select kernel Python (fairpipe .venv) if imports fail.

• Part A — n=1 per group → nan at default min_group_size=5 (guard demonstration)
• Part B — n=9 per group → divergence ≈ 0.196 (95% CI ≈ 0.185–0.205) on lexical features; this is not “19.6% of candidates treated unfairly”
• YAML config → run_llm_eval() → MetricResult (see docs/llm_evals_intro.md). Phase 2 refusal/toxicity/BBQ demo caches are labeled via MetricResult.caveat until BL-009; they are not part of this notebook.

COMPAS Recidivism Bias Analysis

Reproduces ProPublica's 2016 Machine Bias investigation on the COMPAS recidivism algorithm used in US courtrooms.

• DPD = 0.2451 — Black defendants 24.5 percentage points more likely to be flagged high-risk than white defendants
• EOD = 0.2116 — among defendants who will not reoffend, Black defendants are 21 percentage points more likely to be incorrectly labelled high-risk
• 53.9% reduction in EOD via Instance Reweighting
• 28 features with statistically significant racial disparities detected
• 23 proxy variables identified — removing the race column alone would not fix this model

AI Hiring Bias — ACS Employment Analysis

Demonstrates the type of bias audit now required under NYC Local Law 144 and the EU AI Act, framed around Mobley v. Workday — the 2025 class action alleging AI hiring tools discriminated against millions of applicants by age, race, and disability.

• DPD = 0.1046 — white candidates selected at 32.3% vs Black candidates at 21.8%, a 10.5 percentage point gap with no race feature in the model
• EOD = 0.1022 — 76.8% of qualified Black candidates incorrectly rejected vs 66.6% of white candidates
• All 5 prediction features show statistically significant racial disparity — removing the race column alone would not fix this model
• 47.6% reduction in EOD via Instance Reweighting, closing to within 0.0036 of the 0.05 compliance threshold
• Dataset: ACS 2018 1-Year California (196,604 individuals, folktables)

Project links

License

Apache License 2.0 — see LICENSE.