Getting Started

Welcome to the Fairness Pipeline Development Toolkit! This guide will help you get started quickly.

Installation

Install the toolkit using pip:

pip install fairpipe

For development installation:

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

Quick Start

Basic Usage

from fairpipe.metrics import FairnessAnalyzer
import numpy as np

# Create analyzer
fa = FairnessAnalyzer(min_group_size=30, backend="native")

# Accepts np.ndarray, pd.Series, or list — no .to_numpy() required
y_pred = np.array([0, 1, 1, 0, 1, 0, 1, 1])
sensitive = np.array(["A", "A", "B", "B", "A", "B", "A", "B"])

# Compute demographic parity difference
result = fa.demographic_parity_difference(y_pred, sensitive)

print(f"Demographic Parity Difference: {result.value:.4f}")
print(f"95% CI: {result.ci}")

DataFrame Proxy

If your data is already in a DataFrame, bind a proxy to avoid repeating column names:

import pandas as pd
from fairpipe.metrics import FairnessAnalyzer

df = pd.read_csv("predictions.csv")
proxy = FairnessAnalyzer.from_dataframe(
    df, y_pred_col="y_pred", sensitive_col="gender", y_true_col="y_true"
)

dpd = proxy.demographic_parity_difference(with_ci=True)
eod = proxy.equalized_odds_difference()

Loading Data (CSV or Parquet)

from fairpipe.io import load_data

df = load_data("data.csv")      # CSV
df = load_data("data.parquet")  # Parquet — same API, auto-detected

CLI Usage

# Validate fairness from CSV
fairpipe validate \
    --csv data.csv \
    --y-true y_true \
    --y-pred y_pred \
    --sensitive group \
    --threshold 0.05 \
    --out report.md

REST API Server

Start a local HTTP server with Swagger UI — useful for non-Python stacks or demos:

pip install fairpipe[api]
fairpipe serve --host 127.0.0.1 --port 8000

Then open http://127.0.0.1:8000/docs in your browser, or call the API directly:

curl -X POST http://localhost:8000/validate \
  -H "Content-Type: application/json" \
  -d '{
    "y_pred": [1, 0, 1, 0, 1, 0],
    "sensitive": ["A", "A", "A", "B", "B", "B"],
    "threshold": 0.05,
    "min_group_size": 1
  }'

Docker:

# From the repo root
docker build -t fairpipe-api .
docker run -p 8000:8000 fairpipe-api
# or: docker compose up

Next Steps