Initial FairSight project import

.firebaserc

@@ -0,0 +1,6 @@
+{
+  "projects": {
+    "default": "fairlens-494713"
+  }
+}
+

.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+.firebase/
+.env
+.env.local
+.env.*.local
+frontend/dist/
+functions/node_modules/
+functions/.env
+functions/.secret.local
+*.log
+__pycache__/
+*.pyc
+

README.md

@@ -0,0 +1,30 @@
+# FairSight
+
+Firebase + React + Cloud Run scaffolding for the FairSight bias detection dashboard.
+
+## Projects
+
+- `frontend/`: React + Vite app
+- `functions/`: Firebase Functions for upload pipeline, simulator wrapper, and Gemini integration
+- `backend/`: Python fairness engine and Cloud Run service
+
+## Setup
+
+1. Install dependencies:
+   - `cd frontend && npm install`
+   - `cd ../functions && npm install`
+2. Create `frontend/.env.local` from `frontend/.env.example`.
+3. Create `functions/.env` from `functions/.env.example`.
+4. Authenticate Firebase CLI and select project `fairlens-494713`.
+5. Deploy backend to Cloud Run, then set `FAIRNESS_BACKEND_URL` in `functions/.env`.
+
+## Firebase / GCP commands
+
+```powershell
+firebase use fairlens-494713
+firebase deploy --only firestore,storage,functions,hosting
+gcloud config set project fairlens-494713
+gcloud builds submit backend --tag us-central1-docker.pkg.dev/fairlens-494713/fairlens/fairsight-backend
+gcloud run deploy fairsight-backend --image us-central1-docker.pkg.dev/fairlens-494713/fairlens/fairsight-backend --platform managed --region us-central1 --allow-unauthenticated
+```
+

backend/.dockerignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+

backend/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+ENV PORT=8080
+
+CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT}"]
+

backend/config.py

@@ -0,0 +1,35 @@
+"""
+FairSight — Application Configuration & Constants
+"""
+
+# ── Disparate Impact thresholds (EEOC 4/5ths rule) ───────────────────────
+DI_CRITICAL_THRESHOLD = 0.80
+DI_WARNING_THRESHOLD = 0.90
+
+# ── Equal Opportunity Gap thresholds ──────────────────────────────────────
+EO_CRITICAL_THRESHOLD = 0.15
+EO_WARNING_THRESHOLD = 0.08
+
+# ── Calibration Gap thresholds ────────────────────────────────────────────
+CAL_CRITICAL_THRESHOLD = 0.12
+CAL_WARNING_THRESHOLD = 0.06
+
+# ── Proxy detection correlation threshold ─────────────────────────────────
+PROXY_CORRELATION_THRESHOLD = 0.15
+PROXY_HIGH_THRESHOLD = 0.35
+
+# ── Protected attributes recognized by the system ────────────────────────
+PROTECTED_ATTRIBUTES = ["gender", "race", "age", "disability"]
+
+# ── Feature columns (non-protected) ──────────────────────────────────────
+FEATURE_COLUMNS = [
+    "credit_score", "zip_code", "income", "education",
+    "employment_years", "debt_ratio", "loan_amount",
+    "school_name", "neighborhood"
+]
+
+# ── CORS Origins ──────────────────────────────────────────────────────────
+ALLOWED_ORIGINS = ["*"]
+
+# ── Dataset path ──────────────────────────────────────────────────────────
+SAMPLE_DATASET_PATH = "data/sample_dataset.csv"

backend/main.py

@@ -0,0 +1,154 @@
+"""
+FairSight — Bias Detection Suite
+═══════════════════════════════════════════════════════════════════════════
+Inspect datasets and AI models for hidden discrimination before deployment.
+
+Main FastAPI application entry point.
+"""
+from fastapi import FastAPI, UploadFile, File, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from contextlib import asynccontextmanager
+import pandas as pd
+import io
+
+from config import ALLOWED_ORIGINS
+from services.data_service import get_dataset, reload_dataset, get_dataset_info
+from models.schemas import DatasetInfo
+
+# Import routers
+from routers.overview import router as overview_router
+from routers.fairness import router as fairness_router
+from routers.alerts import router as alerts_router
+from routers.remediation import router as remediation_router
+from routers.simulator import router as simulator_router
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize the dataset on startup."""
+    print("⚡ FairSight — Initializing dataset...")
+    df = get_dataset()
+    print(f"✅ Dataset loaded: {len(df)} rows, {len(df.columns)} columns")
+    info = get_dataset_info()
+    print(f"   Protected attributes: {info['protected_attributes_found']}")
+    print(f"   Decision column: {info['decision_column']}")
+    print("🚀 FairSight backend is ready!")
+    yield
+    print("👋 FairSight shutting down.")
+
+
+app = FastAPI(
+    title="FairSight — Bias Detection Suite",
+    description=(
+        "Inspect datasets and AI models for hidden discrimination before deployment. "
+        "Provides disparate impact analysis, proxy variable detection, "
+        "remediation recommendations, and what-if simulation."
+    ),
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# ── CORS ──────────────────────────────────────────────────────────────────
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Mount routers ─────────────────────────────────────────────────────────
+app.include_router(overview_router)
+app.include_router(fairness_router)
+app.include_router(alerts_router)
+app.include_router(remediation_router)
+app.include_router(simulator_router)
+
+
+# ── Root endpoint ─────────────────────────────────────────────────────────
+@app.get("/", tags=["Health"])
+async def root():
+    return {
+        "name": "FairSight — Bias Detection Suite",
+        "version": "1.0.0",
+        "status": "running",
+        "endpoints": {
+            "overview": "/api/overview",
+            "fairness_metrics": "/api/fairness-metrics",
+            "alerts": "/api/alerts",
+            "remediation": "/api/remediation",
+            "simulator": "/api/simulator",
+            "dataset_info": "/api/dataset/info",
+            "upload_dataset": "/api/dataset/upload",
+            "docs": "/docs",
+        },
+    }
+
+
+# ── Dataset management endpoints ─────────────────────────────────────────
+@app.get("/api/dataset/info", response_model=DatasetInfo, tags=["Dataset"])
+async def dataset_info():
+    """Return metadata about the currently loaded dataset."""
+    info = get_dataset_info()
+    return DatasetInfo(**info)
+
+
+@app.post("/api/dataset/upload", response_model=DatasetInfo, tags=["Dataset"])
+async def upload_dataset(file: UploadFile = File(...)):
+    """
+    Upload a custom CSV dataset.
+    
+    Required columns:
+    - At least one protected attribute (gender, race, age, disability)
+    - A 'decision' column (0/1)
+    - A 'qualified' column (0/1) for EO and calibration metrics
+    - A 'predicted_prob' column (0–1) for calibration and scatter plots
+    """
+    if not file.filename.endswith(".csv"):
+        raise HTTPException(status_code=400, detail="Only CSV files are supported.")
+
+    try:
+        contents = await file.read()
+        df = pd.read_csv(io.BytesIO(contents))
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Failed to parse CSV: {str(e)}")
+
+    # Validate required columns
+    required = ["decision"]
+    missing = [col for col in required if col not in df.columns]
+    if missing:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Missing required columns: {missing}. Must have at least 'decision'."
+        )
+
+    protected_found = [c for c in ["gender", "race", "age", "disability"] if c in df.columns]
+    if not protected_found:
+        raise HTTPException(
+            status_code=400,
+            detail="No protected attributes found. Include at least one of: gender, race, age, disability."
+        )
+
+    # Add missing optional columns with defaults
+    if "qualified" not in df.columns:
+        df["qualified"] = df["decision"]  # assume decision = qualification if not provided
+    if "predicted_prob" not in df.columns:
+        df["predicted_prob"] = df["decision"].astype(float)
+
+    reload_dataset(df)
+    info = get_dataset_info()
+    return DatasetInfo(**info)
+
+
+@app.post("/api/dataset/reset", tags=["Dataset"])
+async def reset_dataset():
+    """Reset to the built-in sample dataset."""
+    reload_dataset(None)
+    info = get_dataset_info()
+    return {"message": "Dataset reset to sample data.", "info": info}
+
+
+# ── Run with uvicorn ──────────────────────────────────────────────────────
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

backend/models/__init__.py

@@ -0,0 +1 @@
+# FairSight Models Package

backend/models/enums.py

@@ -0,0 +1,37 @@
+"""
+FairSight — Enumerations for protected attributes, severity levels, and metric types.
+"""
+from enum import Enum
+
+
+class ProtectedAttribute(str, Enum):
+    GENDER = "gender"
+    RACE = "race"
+    AGE = "age"
+    DISABILITY = "disability"
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class AlertType(str, Enum):
+    DIRECT_DISCRIMINATION = "direct_discrimination"
+    PROXY_VARIABLE = "proxy_variable"
+    SAMPLE_SIZE = "sample_size"
+    CALIBRATION = "calibration"
+
+
+class RemediationType(str, Enum):
+    REMOVE_PROXY = "remove_proxy"
+    REWEIGHT_DATA = "reweight_data"
+    ADJUST_THRESHOLD = "adjust_threshold"
+    POST_PROCESS = "post_process"
+
+
+class MetricStatus(str, Enum):
+    PASSING = "passing"
+    NEEDS_REVIEW = "needs_review"
+    CRITICAL = "critical"

backend/models/schemas.py

@@ -0,0 +1,205 @@
+"""
+FairSight — Pydantic schemas for all API request and response models.
+"""
+from __future__ import annotations
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Overview endpoint schemas
+# ═══════════════════════════════════════════════════════════════════════════
+
+class ApprovalRate(BaseModel):
+    group: str
+    rate: float = Field(..., ge=0, le=1, description="Approval rate 0–1")
+    count: int = Field(..., description="Total individuals in group")
+
+
+class FairnessScore(BaseModel):
+    metric: str
+    score: float = Field(..., ge=0, le=100)
+    status: str  # "passing", "needs_review", "critical"
+    description: str
+
+
+class HeatmapCell(BaseModel):
+    feature: str
+    protected_attribute: str
+    correlation: float = Field(..., ge=0, le=1)
+
+
+class OverviewResponse(BaseModel):
+    overall_fairness_score: float = Field(..., ge=0, le=100)
+    disparate_impact_ratio: float
+    groups_analyzed: int
+    group_names: list[str]
+    flagged_features: int
+    proxy_variables_found: int
+    approval_rates: list[ApprovalRate]
+    fairness_scores: list[FairnessScore]
+    heatmap: list[HeatmapCell]
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Fairness Metrics endpoint schemas
+# ═══════════════════════════════════════════════════════════════════════════
+
+class GroupMetric(BaseModel):
+    group: str
+    value: float
+    sample_size: int
+
+
+class ScatterPoint(BaseModel):
+    actual: float
+    predicted: float
+    group: str
+
+
+class FairnessMetricsResponse(BaseModel):
+    protected_attribute: str
+    disparate_impact: float
+    disparate_impact_status: str
+    equal_opportunity_gap: float
+    equal_opportunity_status: str
+    calibration_gap: float
+    calibration_status: str
+    group_details: list[GroupMetric]
+    scatter_data: list[ScatterPoint]
+    reference_group: str
+    description: str
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Alerts endpoint schemas
+# ═══════════════════════════════════════════════════════════════════════════
+
+class Alert(BaseModel):
+    id: str
+    type: str  # "direct_discrimination" | "proxy_variable"
+    severity: str  # "critical" | "warning" | "info"
+    title: str
+    description: str
+    affected_groups: list[str]
+    affected_features: list[str]
+    metric_value: Optional[float] = None
+    threshold: Optional[float] = None
+    recommendation: str
+
+
+class AlertsResponse(BaseModel):
+    total_alerts: int
+    critical_count: int
+    warning_count: int
+    info_count: int
+    alerts: list[Alert]
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Remediation endpoint schemas
+# ═══════════════════════════════════════════════════════════════════════════
+
+class Intervention(BaseModel):
+    id: str
+    type: str  # "remove_proxy" | "reweight_data" | "adjust_threshold" | "post_process"
+    title: str
+    description: str
+    priority: int = Field(..., ge=1, le=5)
+    expected_di_improvement: float
+    expected_eo_improvement: float
+    expected_cal_improvement: float
+    risk_level: str
+    implementation_effort: str  # "low" | "medium" | "high"
+    affected_features: list[str]
+
+
+class FairnessConstraint(BaseModel):
+    name: str
+    current_value: float
+    min_value: float
+    max_value: float
+    step: float
+    description: str
+
+
+class RemediationResponse(BaseModel):
+    current_disparate_impact: float
+    target_disparate_impact: float
+    interventions: list[Intervention]
+    fairness_constraints: list[FairnessConstraint]
+
+
+class ApplyRemediationRequest(BaseModel):
+    intervention_ids: list[str]
+    fairness_constraints: dict[str, float] = Field(
+        default_factory=dict,
+        description="Map of constraint name → desired value"
+    )
+
+
+class ApplyRemediationResponse(BaseModel):
+    original_disparate_impact: float
+    new_disparate_impact: float
+    original_eo_gap: float
+    new_eo_gap: float
+    original_cal_gap: float
+    new_cal_gap: float
+    approval_rates_before: list[ApprovalRate]
+    approval_rates_after: list[ApprovalRate]
+    interventions_applied: list[str]
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Simulator endpoint schemas
+# ═══════════════════════════════════════════════════════════════════════════
+
+class SimulatorRequest(BaseModel):
+    threshold_adjustment: float = Field(
+        default=0.0, ge=-0.5, le=0.5,
+        description="Shift the decision threshold (negative = more approvals)"
+    )
+    reweighting_strength: float = Field(
+        default=0.0, ge=0.0, le=1.0,
+        description="How aggressively to reweight underrepresented groups (0=none, 1=full)"
+    )
+    calibration_strength: float = Field(
+        default=0.0, ge=0.0, le=1.0,
+        description="How much to apply Platt-style calibration (0=none, 1=full)"
+    )
+    remove_features: list[str] = Field(
+        default_factory=list,
+        description="Feature names to remove from the model"
+    )
+    protected_attribute: str = Field(
+        default="race",
+        description="Protected attribute to evaluate"
+    )
+
+
+class SimulatorResult(BaseModel):
+    original_approval_rates: list[ApprovalRate]
+    simulated_approval_rates: list[ApprovalRate]
+    original_disparate_impact: float
+    simulated_disparate_impact: float
+    original_eo_gap: float
+    simulated_eo_gap: float
+    original_cal_gap: float
+    simulated_cal_gap: float
+    overall_approval_change: float
+    accuracy_impact: float = Field(
+        ..., description="Estimated accuracy change (negative = accuracy drop)"
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Dataset upload schema
+# ═══════════════════════════════════════════════════════════════════════════
+
+class DatasetInfo(BaseModel):
+    rows: int
+    columns: int
+    column_names: list[str]
+    protected_attributes_found: list[str]
+    decision_column: str
+    qualification_column: str

backend/requirements.txt

@@ -0,0 +1,8 @@
+fastapi==0.111.0
+uvicorn[standard]==0.30.1
+pandas==2.2.2
+numpy==1.26.4
+scikit-learn==1.5.0
+scipy==1.13.1
+pydantic==2.7.4
+python-multipart==0.0.9

backend/routers/__init__.py

@@ -0,0 +1 @@
+# FairSight Routers Package

backend/routers/alerts.py

@@ -0,0 +1,36 @@
+"""
+FairSight — Alerts Router
+GET /api/alerts → priority-ordered fairness issues
+"""
+from fastapi import APIRouter
+
+from services.data_service import get_dataset
+from services.alert_service import generate_alerts
+from models.schemas import AlertsResponse
+
+router = APIRouter(prefix="/api", tags=["Alerts"])
+
+
+@router.get("/alerts", response_model=AlertsResponse)
+async def get_alerts():
+    """
+    Surface critical fairness issues in priority order.
+    
+    Flags both direct discrimination (disparate impact, equal opportunity
+    violations) and proxy variables (features that appear neutral but
+    encode protected characteristics).
+    """
+    df = get_dataset()
+    alerts = generate_alerts(df)
+
+    critical_count = sum(1 for a in alerts if a["severity"] == "critical")
+    warning_count = sum(1 for a in alerts if a["severity"] == "warning")
+    info_count = sum(1 for a in alerts if a["severity"] == "info")
+
+    return AlertsResponse(
+        total_alerts=len(alerts),
+        critical_count=critical_count,
+        warning_count=warning_count,
+        info_count=info_count,
+        alerts=alerts,
+    )

backend/routers/fairness.py

@@ -0,0 +1,89 @@
+"""
+FairSight — Fairness Metrics Router
+GET /api/fairness-metrics?protected_attr=race → detailed fairness breakdown
+"""
+from fastapi import APIRouter, Query
+
+from services.data_service import get_dataset
+from services.fairness_engine import (
+    compute_disparate_impact,
+    compute_equal_opportunity_gap,
+    compute_calibration_gap,
+    compute_scatter_data,
+)
+from models.schemas import FairnessMetricsResponse
+
+router = APIRouter(prefix="/api", tags=["Fairness Metrics"])
+
+
+@router.get("/fairness-metrics", response_model=FairnessMetricsResponse)
+async def get_fairness_metrics(
+    protected_attr: str = Query(
+        default="race",
+        description="Protected attribute to evaluate: gender, race, age, disability"
+    ),
+    decision_type: str = Query(
+        default="decision",
+        description="Column name for the decision outcome"
+    ),
+):
+    """
+    Compute and return detailed fairness metrics for a specific protected attribute.
+    
+    Returns:
+    - Disparate impact ratio with 4/5ths rule evaluation
+    - Equal opportunity gap (TPR parity)
+    - Calibration gap (prediction-reality alignment)
+    - Scatter plot data (predicted vs actual qualifications)
+    - Per-group breakdown
+    """
+    df = get_dataset()
+
+    if protected_attr not in df.columns:
+        protected_attr = "race"
+
+    if decision_type not in df.columns:
+        decision_type = "decision"
+
+    # ── Compute all three metrics ─────────────────────────────────────────
+    di_result = compute_disparate_impact(df, protected_attr, decision_type)
+    eo_result = compute_equal_opportunity_gap(df, protected_attr, decision_type)
+    cal_result = compute_calibration_gap(df, protected_attr)
+    scatter = compute_scatter_data(df, protected_attr)
+
+    # ── Per-group details ─────────────────────────────────────────────────
+    group_details = []
+    for group in sorted(df[protected_attr].unique()):
+        mask = df[protected_attr] == group
+        group_details.append({
+            "group": str(group),
+            "value": round(float(df.loc[mask, decision_type].mean()), 3),
+            "sample_size": int(mask.sum()),
+        })
+
+    # ── Description ───────────────────────────────────────────────────────
+    description = (
+        f"Fairness analysis for '{protected_attr}' across {len(group_details)} groups. "
+        f"Reference group (highest approval): {di_result.get('reference_group', 'N/A')}. "
+    )
+
+    if di_result["ratio"] < 0.80:
+        description += "⚠️ The 4/5ths rule is violated — this may indicate illegal discrimination. "
+    if eo_result["gap"] > 0.10:
+        description += "Qualified individuals face significantly unequal treatment across groups. "
+    if cal_result["gap"] > 0.08:
+        description += "Model predictions are not equally calibrated across groups."
+
+    return FairnessMetricsResponse(
+        protected_attribute=protected_attr,
+        disparate_impact=di_result["ratio"],
+        disparate_impact_status=di_result["status"].value,
+        equal_opportunity_gap=eo_result["gap"],
+        equal_opportunity_status=eo_result["status"].value,
+        calibration_gap=cal_result["gap"],
+        calibration_status=cal_result["status"].value,
+        group_details=group_details,
+        scatter_data=scatter,
+        reference_group=di_result.get("reference_group", ""),
+        description=description,
+    )

backend/routers/overview.py

@@ -0,0 +1,113 @@
+"""
+FairSight — Overview Router
+GET /api/overview → at-a-glance fairness scorecard
+"""
+from fastapi import APIRouter
+
+from services.data_service import get_dataset
+from services.fairness_engine import (
+    compute_disparate_impact,
+    compute_equal_opportunity_gap,
+    compute_calibration_gap,
+    compute_overall_fairness_score,
+    get_metric_status_label,
+)
+from services.proxy_detector import get_heatmap_data, detect_proxy_variables
+from config import PROTECTED_ATTRIBUTES, FEATURE_COLUMNS
+from models.schemas import OverviewResponse
+
+router = APIRouter(prefix="/api", tags=["Overview"])
+
+
+@router.get("/overview", response_model=OverviewResponse)
+async def get_overview():
+    """
+    Return the at-a-glance fairness scorecard:
+    - Overall fairness score (0–100)
+    - Disparate impact ratio
+    - Groups analyzed
+    - Flagged features / proxy variables
+    - Approval rates by demographic group
+    - Model fairness scores (DI, EO, Calibration)
+    - Dataset quality heatmap
+    """
+    df = get_dataset()
+
+    available_attrs = [a for a in PROTECTED_ATTRIBUTES if a in df.columns]
+    available_features = [f for f in FEATURE_COLUMNS if f in df.columns]
+
+    # ── Collect all unique groups ─────────────────────────────────────────
+    all_groups = set()
+    for attr in available_attrs:
+        all_groups.update(str(v) for v in df[attr].unique().tolist())
+
+    # ── Primary metric: race (most common fairness evaluation) ────────────
+    primary_attr = "race" if "race" in df.columns else available_attrs[0]
+
+    di_result = compute_disparate_impact(df, primary_attr)
+    eo_result = compute_equal_opportunity_gap(df, primary_attr)
+    cal_result = compute_calibration_gap(df, primary_attr)
+
+    overall_score = compute_overall_fairness_score(
+        di_result["ratio"], eo_result["gap"], cal_result["gap"]
+    )
+
+    # ── Proxy detection ───────────────────────────────────────────────────
+    proxies = detect_proxy_variables(df, available_features, available_attrs)
+    flagged_features = len(set(p["feature"] for p in proxies))
+
+    # ── Approval rates by demographic group ───────────────────────────────
+    approval_rates = []
+    for attr in available_attrs:
+        for group in sorted(df[attr].unique()):
+            mask = df[attr] == group
+            rate = df.loc[mask, "decision"].mean()
+            count = int(mask.sum())
+            # Avoid duplicates if same group name across attributes
+            if not any(ar["group"] == str(group) for ar in approval_rates):
+                approval_rates.append({
+                    "group": str(group),
+                    "rate": round(float(rate), 3),
+                    "count": count,
+                })
+
+    # ── Fairness scores ───────────────────────────────────────────────────
+    di_score_value = round(min(100, max(0, (di_result["ratio"] / 1.0) * 100)), 1)
+    eo_score_value = round(min(100, max(0, (1 - eo_result["gap"] / 0.30) * 100)), 1)
+    cal_score_value = round(min(100, max(0, (1 - cal_result["gap"] / 0.30) * 100)), 1)
+
+    fairness_scores = [
+        {
+            "metric": "Disparate impact",
+            "score": di_score_value,
+            "status": di_result["status"].value,
+            "description": f"DI ratio of {di_result['ratio']:.2f} — {'below' if di_result['ratio'] < 0.80 else 'at or above'} the 4/5ths threshold",
+        },
+        {
+            "metric": "Equal opportunity",
+            "score": eo_score_value,
+            "status": eo_result["status"].value,
+            "description": f"EO gap of {eo_result['gap']:.1%} between best and worst performing groups",
+        },
+        {
+            "metric": "Calibration",
+            "score": cal_score_value,
+            "status": cal_result["status"].value,
+            "description": f"Calibration gap of {cal_result['gap']:.1%} across groups",
+        },
+    ]
+
+    # ── Heatmap data ──────────────────────────────────────────────────────
+    heatmap = get_heatmap_data(df, available_features, available_attrs)
+
+    return OverviewResponse(
+        overall_fairness_score=overall_score,
+        disparate_impact_ratio=di_result["ratio"],
+        groups_analyzed=len(all_groups),
+        group_names=sorted(all_groups),
+        flagged_features=flagged_features,
+        proxy_variables_found=len(proxies),
+        approval_rates=approval_rates,
+        fairness_scores=fairness_scores,
+        heatmap=heatmap,
+    )

backend/routers/remediation.py

@@ -0,0 +1,67 @@
+"""
+FairSight — Remediation Router
+GET  /api/remediation       → get prioritized interventions
+POST /api/remediation/apply → apply selected interventions and see impact
+"""
+from fastapi import APIRouter, Query
+
+from services.data_service import get_dataset
+from services.fairness_engine import compute_disparate_impact
+from services.remediation_service import (
+    generate_interventions,
+    get_fairness_constraints,
+    apply_remediation,
+)
+from models.schemas import (
+    RemediationResponse,
+    ApplyRemediationRequest,
+    ApplyRemediationResponse,
+)
+
+router = APIRouter(prefix="/api", tags=["Remediation"])
+
+
+@router.get("/remediation", response_model=RemediationResponse)
+async def get_remediation():
+    """
+    Return prioritized remediation interventions with expected impact estimates.
+    
+    Intervention types:
+    - remove_proxy: Remove features acting as demographic proxies
+    - reweight_data: Reweight training samples to balance outcomes
+    - adjust_threshold: Group-specific decision threshold tuning
+    - post_process: Post-processing calibration
+    """
+    df = get_dataset()
+
+    interventions = generate_interventions(df)
+    constraints = get_fairness_constraints()
+
+    di = compute_disparate_impact(df, "race")
+
+    return RemediationResponse(
+        current_disparate_impact=di["ratio"],
+        target_disparate_impact=0.80,
+        interventions=interventions,
+        fairness_constraints=constraints,
+    )
+
+
+@router.post("/remediation/apply", response_model=ApplyRemediationResponse)
+async def apply_remediation_endpoint(
+    request: ApplyRemediationRequest,
+    protected_attr: str = Query(default="race"),
+):
+    """
+    Apply selected interventions and return before/after fairness comparison.
+    """
+    df = get_dataset()
+
+    result = apply_remediation(
+        df,
+        intervention_ids=request.intervention_ids,
+        constraints=request.fairness_constraints,
+        protected_attr=protected_attr,
+    )
+
+    return ApplyRemediationResponse(**result)

backend/routers/simulator.py

@@ -0,0 +1,38 @@
+"""
+FairSight — Simulator Router
+POST /api/simulator → what-if simulation with adjustable parameters
+"""
+from fastapi import APIRouter
+
+from services.data_service import get_dataset
+from services.simulator_service import simulate
+from models.schemas import SimulatorRequest, SimulatorResult
+
+router = APIRouter(prefix="/api", tags=["Simulator"])
+
+
+@router.post("/simulator", response_model=SimulatorResult)
+async def run_simulation(request: SimulatorRequest):
+    """
+    Run a what-if simulation to see how fairness metrics change
+    with different interventions, before touching the actual model.
+    
+    Parameters:
+    - threshold_adjustment: shift the decision threshold
+    - reweighting_strength: how aggressively to uplift underrepresented groups
+    - calibration_strength: Platt-style calibration intensity
+    - remove_features: proxy features to exclude
+    - protected_attribute: attribute to evaluate against
+    """
+    df = get_dataset()
+
+    result = simulate(
+        df,
+        threshold_adjustment=request.threshold_adjustment,
+        reweighting_strength=request.reweighting_strength,
+        calibration_strength=request.calibration_strength,
+        remove_features=request.remove_features,
+        protected_attribute=request.protected_attribute,
+    )
+
+    return SimulatorResult(**result)

backend/services/__init__.py

@@ -0,0 +1 @@
+# FairSight Services Package

backend/services/alert_service.py

@@ -0,0 +1,153 @@
+"""
+FairSight — Alert Service
+Generates priority-ordered alerts for direct discrimination and proxy variable issues.
+"""
+from __future__ import annotations
+
+import uuid
+import pandas as pd
+
+from models.enums import Severity, AlertType
+from services.fairness_engine import (
+    compute_disparate_impact,
+    compute_equal_opportunity_gap,
+    compute_calibration_gap,
+)
+from services.proxy_detector import detect_proxy_variables
+from config import (
+    DI_CRITICAL_THRESHOLD,
+    DI_WARNING_THRESHOLD,
+    EO_CRITICAL_THRESHOLD,
+    EO_WARNING_THRESHOLD,
+    PROTECTED_ATTRIBUTES,
+    FEATURE_COLUMNS,
+)
+
+
+def generate_alerts(df: pd.DataFrame) -> list[dict]:
+    """
+    Analyze the dataset and generate a prioritized list of alerts.
+    Combines direct discrimination detection with proxy variable detection.
+    """
+    alerts: list[dict] = []
+
+    # ── 1. Direct discrimination alerts (per protected attribute) ─────────
+    for attr in PROTECTED_ATTRIBUTES:
+        if attr not in df.columns:
+            continue
+
+        # Disparate impact alerts
+        di_result = compute_disparate_impact(df, attr)
+        di_ratio = di_result["ratio"]
+        group_rates = di_result.get("group_rates", {})
+        ref_group = di_result.get("reference_group", "")
+
+        if di_ratio < DI_CRITICAL_THRESHOLD:
+            # Find the most disadvantaged group
+            worst_group = min(group_rates, key=group_rates.get)
+            alerts.append({
+                "id": f"di-{attr}-{uuid.uuid4().hex[:8]}",
+                "type": AlertType.DIRECT_DISCRIMINATION.value,
+                "severity": Severity.CRITICAL.value,
+                "title": f"Critical Disparate Impact on {attr.title()}",
+                "description": (
+                    f"The disparate impact ratio for '{attr}' is {di_ratio:.2f}, "
+                    f"well below the EEOC 4/5ths threshold of 0.80. "
+                    f"Group '{worst_group}' has an approval rate of "
+                    f"{group_rates.get(worst_group, 0):.1%} compared to "
+                    f"'{ref_group}' at {group_rates.get(ref_group, 0):.1%}."
+                ),
+                "affected_groups": [worst_group, ref_group],
+                "affected_features": [],
+                "metric_value": di_ratio,
+                "threshold": DI_CRITICAL_THRESHOLD,
+                "recommendation": (
+                    f"Review decision criteria for bias against '{worst_group}'. "
+                    f"Consider threshold adjustments or reweighting training data."
+                ),
+            })
+        elif di_ratio < DI_WARNING_THRESHOLD:
+            worst_group = min(group_rates, key=group_rates.get)
+            alerts.append({
+                "id": f"di-{attr}-{uuid.uuid4().hex[:8]}",
+                "type": AlertType.DIRECT_DISCRIMINATION.value,
+                "severity": Severity.WARNING.value,
+                "title": f"Disparate Impact Warning on {attr.title()}",
+                "description": (
+                    f"The disparate impact ratio for '{attr}' is {di_ratio:.2f}, "
+                    f"approaching the 0.80 threshold."
+                ),
+                "affected_groups": list(group_rates.keys()),
+                "affected_features": [],
+                "metric_value": di_ratio,
+                "threshold": DI_WARNING_THRESHOLD,
+                "recommendation": f"Monitor {attr} disparate impact closely.",
+            })
+
+        # Equal opportunity alerts
+        eo_result = compute_equal_opportunity_gap(df, attr)
+        eo_gap = eo_result["gap"]
+
+        if eo_gap > EO_CRITICAL_THRESHOLD:
+            tpr_data = eo_result.get("tpr_by_group", {})
+            worst_eo_group = min(tpr_data, key=tpr_data.get) if tpr_data else ""
+            alerts.append({
+                "id": f"eo-{attr}-{uuid.uuid4().hex[:8]}",
+                "type": AlertType.DIRECT_DISCRIMINATION.value,
+                "severity": Severity.CRITICAL.value,
+                "title": f"Equal Opportunity Violation on {attr.title()}",
+                "description": (
+                    f"Qualified individuals from '{worst_eo_group}' are {eo_gap:.1%} "
+                    f"less likely to be approved than qualified individuals from other groups."
+                ),
+                "affected_groups": list(tpr_data.keys()),
+                "affected_features": [],
+                "metric_value": eo_gap,
+                "threshold": EO_CRITICAL_THRESHOLD,
+                "recommendation": (
+                    "Ensure qualified applicants receive equal consideration "
+                    "regardless of group membership."
+                ),
+            })
+        elif eo_gap > EO_WARNING_THRESHOLD:
+            alerts.append({
+                "id": f"eo-{attr}-{uuid.uuid4().hex[:8]}",
+                "type": AlertType.DIRECT_DISCRIMINATION.value,
+                "severity": Severity.WARNING.value,
+                "title": f"Equal Opportunity Gap on {attr.title()}",
+                "description": f"An equal opportunity gap of {eo_gap:.1%} was detected for '{attr}'.",
+                "affected_groups": list(eo_result.get("tpr_by_group", {}).keys()),
+                "affected_features": [],
+                "metric_value": eo_gap,
+                "threshold": EO_WARNING_THRESHOLD,
+                "recommendation": "Review model for potential equal opportunity issues.",
+            })
+
+    # ── 2. Proxy variable alerts ──────────────────────────────────────────
+    available_features = [f for f in FEATURE_COLUMNS if f in df.columns]
+    available_attrs = [a for a in PROTECTED_ATTRIBUTES if a in df.columns]
+
+    proxies = detect_proxy_variables(df, available_features, available_attrs)
+
+    for proxy in proxies:
+        alerts.append({
+            "id": f"proxy-{proxy['feature']}-{proxy['protected_attribute']}-{uuid.uuid4().hex[:8]}",
+            "type": AlertType.PROXY_VARIABLE.value,
+            "severity": proxy["severity"],
+            "title": f"Proxy Variable Detected: {proxy['feature']}",
+            "description": proxy["description"],
+            "affected_groups": [],
+            "affected_features": [proxy["feature"]],
+            "metric_value": proxy["correlation"],
+            "threshold": 0.15,
+            "recommendation": (
+                f"Consider removing or transforming '{proxy['feature']}' to prevent "
+                f"indirect discrimination via '{proxy['protected_attribute']}'."
+            ),
+        })
+
+    # ── 3. Sort by priority: critical > warning > info ────────────────────
+    severity_order = {Severity.CRITICAL.value: 0, Severity.WARNING.value: 1, Severity.INFO.value: 2}
+    alerts.sort(key=lambda a: (severity_order.get(a["severity"], 99), -(a.get("metric_value") or 0)))
+
+    return alerts

backend/services/data_service.py

@@ -0,0 +1,193 @@
+"""
+FairSight — Data Service
+Generates a realistic synthetic dataset for bias-detection demos.
+Handles loading, validation, and profiling of datasets.
+"""
+from __future__ import annotations
+
+import os
+import numpy as np
+import pandas as pd
+from pathlib import Path
+
+
+# ── Singleton dataset cache ───────────────────────────────────────────────
+_dataset_cache: pd.DataFrame | None = None
+
+
+def _generate_synthetic_dataset(n: int = 5000, seed: int = 42) -> pd.DataFrame:
+    """
+    Generate a synthetic lending/hiring dataset with realistic biases baked in
+    to demonstrate the detection capabilities of FairSight.
+    """
+    rng = np.random.default_rng(seed)
+
+    # ── Demographics ──────────────────────────────────────────────────────
+    race_groups = ["White", "Black", "Hispanic", "Asian"]
+    race_weights = [0.35, 0.25, 0.25, 0.15]
+    race = rng.choice(race_groups, size=n, p=race_weights)
+
+    gender = rng.choice(["Male", "Female"], size=n, p=[0.52, 0.48])
+
+    age = np.clip(rng.normal(40, 12, size=n).astype(int), 18, 75)
+    disability = rng.choice(["Yes", "No"], size=n, p=[0.12, 0.88])
+
+    # ── Features ──────────────────────────────────────────────────────────
+    # Credit score: correlated with race (introducing bias)
+    base_credit = rng.normal(680, 80, size=n)
+    race_credit_bias = np.where(
+        race == "White", 20,
+        np.where(race == "Asian", 15,
+                 np.where(race == "Hispanic", -10, -25))
+    )
+    credit_score = np.clip(base_credit + race_credit_bias, 300, 850).astype(int)
+
+    # Zip code: strongly correlated with race (proxy variable)
+    zip_base = np.where(
+        race == "White", rng.choice(range(10001, 10050), size=n),
+        np.where(race == "Black", rng.choice(range(10051, 10100), size=n),
+                 np.where(race == "Hispanic", rng.choice(range(10101, 10150), size=n),
+                          rng.choice(range(10151, 10200), size=n)))
+    )
+    zip_code = zip_base
+
+    # Income: correlated with gender and race
+    base_income = rng.lognormal(mean=10.8, sigma=0.5, size=n)
+    gender_income_bias = np.where(gender == "Male", 1.08, 0.92)
+    race_income_bias = np.where(
+        race == "White", 1.05,
+        np.where(race == "Asian", 1.03,
+                 np.where(race == "Hispanic", 0.93, 0.88))
+    )
+    income = (base_income * gender_income_bias * race_income_bias).astype(int)
+
+    # Education level (1–5)
+    education = np.clip(rng.normal(3, 1, size=n).astype(int), 1, 5)
+
+    # Employment years
+    employment_years = np.clip(rng.exponential(8, size=n).astype(int), 0, 40)
+
+    # Debt ratio
+    debt_ratio = np.clip(rng.beta(2, 5, size=n), 0, 1).round(2)
+
+    # Loan amount
+    loan_amount = (rng.lognormal(mean=10, sigma=0.8, size=n)).astype(int)
+
+    # School name: another proxy for race/socioeconomic status
+    school_categories = np.where(
+        race == "White", rng.choice(["Ivy_League", "State_Univ", "Community_College"], size=n, p=[0.15, 0.55, 0.30]),
+        np.where(race == "Asian", rng.choice(["Ivy_League", "State_Univ", "Community_College"], size=n, p=[0.20, 0.50, 0.30]),
+                 np.where(race == "Hispanic", rng.choice(["Ivy_League", "State_Univ", "Community_College"], size=n, p=[0.05, 0.40, 0.55]),
+                          rng.choice(["Ivy_League", "State_Univ", "Community_College"], size=n, p=[0.05, 0.35, 0.60])))
+    )
+
+    # Neighborhood: socioeconomic proxy
+    neighborhood = np.where(
+        income > 70000, "Affluent",
+        np.where(income > 40000, "Middle_Class", "Low_Income")
+    )
+
+    # ── Qualification (ground truth) ──────────────────────────────────────
+    # Based on objective factors
+    qual_score = (
+        (credit_score - 300) / 550 * 0.35 +
+        np.clip(income / 100000, 0, 1) * 0.25 +
+        education / 5 * 0.15 +
+        np.clip(employment_years / 20, 0, 1) * 0.15 +
+        (1 - debt_ratio) * 0.10
+    )
+    qualified = (qual_score > 0.45).astype(int)
+
+    # ── Decision (model output) — includes bias ──────────────────────────
+    # Start from qualification, then add discriminatory bias
+    decision_score = qual_score.copy()
+
+    # Race bias in decisions
+    race_decision_bias = np.where(
+        race == "White", 0.06,
+        np.where(race == "Asian", 0.02,
+                 np.where(race == "Hispanic", -0.04, -0.10))
+    )
+    decision_score += race_decision_bias
+
+    # Gender bias
+    gender_decision_bias = np.where(gender == "Male", 0.03, -0.03)
+    decision_score += gender_decision_bias
+
+    # Age bias (against older applicants)
+    age_decision_bias = np.where(age > 55, -0.05, np.where(age < 25, -0.02, 0.0))
+    decision_score += age_decision_bias
+
+    # Add noise
+    decision_score += rng.normal(0, 0.05, size=n)
+
+    decision = (decision_score > 0.50).astype(int)
+
+    # ── Predicted probability (model confidence) ──────────────────────────
+    predicted_prob = np.clip(decision_score + rng.normal(0, 0.08, size=n), 0, 1).round(3)
+
+    # ── Assemble DataFrame ────────────────────────────────────────────────
+    df = pd.DataFrame({
+        "gender": gender,
+        "race": race,
+        "age": age,
+        "disability": disability,
+        "credit_score": credit_score,
+        "zip_code": zip_code,
+        "income": income,
+        "education": education,
+        "employment_years": employment_years,
+        "debt_ratio": debt_ratio,
+        "loan_amount": loan_amount,
+        "school_name": school_categories,
+        "neighborhood": neighborhood,
+        "qualified": qualified,
+        "decision": decision,
+        "predicted_prob": predicted_prob,
+    })
+
+    return df
+
+
+def get_dataset() -> pd.DataFrame:
+    """Return the cached dataset, generating it if needed."""
+    global _dataset_cache
+
+    if _dataset_cache is not None:
+        return _dataset_cache
+
+    data_dir = Path(__file__).parent.parent / "data"
+    data_path = data_dir / "sample_dataset.csv"
+
+    if data_path.exists():
+        _dataset_cache = pd.read_csv(data_path)
+    else:
+        os.makedirs(data_dir, exist_ok=True)
+        _dataset_cache = _generate_synthetic_dataset()
+        _dataset_cache.to_csv(data_path, index=False)
+
+    return _dataset_cache
+
+
+def reload_dataset(df: pd.DataFrame | None = None) -> pd.DataFrame:
+    """Force-reload or replace dataset."""
+    global _dataset_cache
+    if df is not None:
+        _dataset_cache = df
+    else:
+        _dataset_cache = None
+    return get_dataset()
+
+
+def get_dataset_info() -> dict:
+    """Return metadata about the loaded dataset."""
+    df = get_dataset()
+    protected_found = [c for c in ["gender", "race", "age", "disability"] if c in df.columns]
+    return {
+        "rows": len(df),
+        "columns": len(df.columns),
+        "column_names": list(df.columns),
+        "protected_attributes_found": protected_found,
+        "decision_column": "decision",
+        "qualification_column": "qualified",
+    }

backend/services/fairness_engine.py

@@ -0,0 +1,273 @@
+"""
+FairSight — Fairness Engine
+Core fairness metric computations: disparate impact, equal opportunity gap,
+calibration gap, and per-group breakdowns.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from typing import Optional
+
+from config import (
+    DI_CRITICAL_THRESHOLD,
+    DI_WARNING_THRESHOLD,
+    EO_CRITICAL_THRESHOLD,
+    EO_WARNING_THRESHOLD,
+    CAL_CRITICAL_THRESHOLD,
+    CAL_WARNING_THRESHOLD,
+)
+from models.enums import MetricStatus
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Disparate Impact
+# ═══════════════════════════════════════════════════════════════════════════
+
+def compute_disparate_impact(
+    df: pd.DataFrame,
+    protected_attr: str,
+    decision_col: str = "decision",
+    reference_group: Optional[str] = None,
+) -> dict:
+    """
+    Compute disparate impact ratio.
+
+    DI = P(decision=1 | unprivileged) / P(decision=1 | privileged)
+
+    Returns the minimum DI across all group comparisons (worst-case).
+    """
+    groups = df[protected_attr].unique()
+    approval_rates = {}
+
+    for g in groups:
+        mask = df[protected_attr] == g
+        n_group = mask.sum()
+        if n_group == 0:
+            continue
+        approval_rates[g] = df.loc[mask, decision_col].mean()
+
+    if not approval_rates:
+        return {"ratio": 1.0, "status": MetricStatus.PASSING, "group_rates": {}}
+
+    # Reference group = highest approval rate (privileged)
+    if reference_group is None or reference_group not in approval_rates:
+        reference_group = max(approval_rates, key=approval_rates.get)
+
+    ref_rate = approval_rates[reference_group]
+    if ref_rate == 0:
+        return {"ratio": 0.0, "status": MetricStatus.CRITICAL, "group_rates": approval_rates, "reference_group": reference_group}
+
+    # Compute DI for each non-reference group
+    di_ratios = {}
+    for g, rate in approval_rates.items():
+        if g == reference_group:
+            di_ratios[g] = 1.0
+        else:
+            di_ratios[g] = rate / ref_rate
+
+    min_di = min(di_ratios.values())
+
+    if min_di < DI_CRITICAL_THRESHOLD:
+        status = MetricStatus.CRITICAL
+    elif min_di < DI_WARNING_THRESHOLD:
+        status = MetricStatus.NEEDS_REVIEW
+    else:
+        status = MetricStatus.PASSING
+
+    return {
+        "ratio": round(min_di, 3),
+        "status": status,
+        "group_rates": {g: round(r, 3) for g, r in approval_rates.items()},
+        "group_di_ratios": {g: round(r, 3) for g, r in di_ratios.items()},
+        "reference_group": reference_group,
+    }
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Equal Opportunity Gap
+# ═══════════════════════════════════════════════════════════════════════════
+
+def compute_equal_opportunity_gap(
+    df: pd.DataFrame,
+    protected_attr: str,
+    decision_col: str = "decision",
+    qualification_col: str = "qualified",
+    reference_group: Optional[str] = None,
+) -> dict:
+    """
+    Equal Opportunity Gap = |TPR_privileged − TPR_unprivileged|
+
+    TPR = P(decision=1 | qualified=1, group)
+    """
+    groups = df[protected_attr].unique()
+    tpr_by_group = {}
+
+    for g in groups:
+        mask = (df[protected_attr] == g) & (df[qualification_col] == 1)
+        n_qualified = mask.sum()
+        if n_qualified == 0:
+            continue
+        tpr_by_group[g] = df.loc[mask, decision_col].mean()
+
+    if not tpr_by_group:
+        return {"gap": 0.0, "status": MetricStatus.PASSING, "tpr_by_group": {}}
+
+    if reference_group is None or reference_group not in tpr_by_group:
+        reference_group = max(tpr_by_group, key=tpr_by_group.get)
+
+    ref_tpr = tpr_by_group[reference_group]
+
+    gaps = {}
+    for g, tpr in tpr_by_group.items():
+        gaps[g] = abs(ref_tpr - tpr)
+
+    max_gap = max(gaps.values())
+
+    if max_gap > EO_CRITICAL_THRESHOLD:
+        status = MetricStatus.CRITICAL
+    elif max_gap > EO_WARNING_THRESHOLD:
+        status = MetricStatus.NEEDS_REVIEW
+    else:
+        status = MetricStatus.PASSING
+
+    return {
+        "gap": round(max_gap, 3),
+        "status": status,
+        "tpr_by_group": {g: round(v, 3) for g, v in tpr_by_group.items()},
+        "gaps": {g: round(v, 3) for g, v in gaps.items()},
+        "reference_group": reference_group,
+    }
+
+
+# ════════════════════════════════���══════════════════════════════════════════
+# Calibration Gap
+# ═══════════════════════════════════════════════════════════════════════════
+
+def compute_calibration_gap(
+    df: pd.DataFrame,
+    protected_attr: str,
+    predicted_col: str = "predicted_prob",
+    qualification_col: str = "qualified",
+    n_bins: int = 10,
+) -> dict:
+    """
+    Calibration Gap: measures how well predictions match reality
+    across demographic groups.
+
+    Bins predicted probabilities and compares actual positive rate
+    per bin across groups.
+    """
+    groups = df[protected_attr].unique()
+    calibrations = {}
+
+    for g in groups:
+        mask = df[protected_attr] == g
+        subset = df.loc[mask]
+        if len(subset) < 20:
+            continue
+
+        bins = pd.cut(subset[predicted_col], bins=n_bins, labels=False, duplicates="drop")
+        if bins.isna().all():
+            continue
+
+        bin_stats = subset.groupby(bins).agg(
+            predicted_mean=(predicted_col, "mean"),
+            actual_mean=(qualification_col, "mean"),
+            count=(qualification_col, "count"),
+        )
+        # Weighted average calibration error for this group
+        total = bin_stats["count"].sum()
+        if total == 0:
+            continue
+        weighted_error = (
+            (bin_stats["predicted_mean"] - bin_stats["actual_mean"]).abs() *
+            bin_stats["count"] / total
+        ).sum()
+
+        calibrations[g] = round(weighted_error, 4)
+
+    if not calibrations:
+        return {"gap": 0.0, "status": MetricStatus.PASSING, "calibrations": {}}
+
+    # Gap = max difference in calibration error between groups
+    cal_values = list(calibrations.values())
+    gap = max(cal_values) - min(cal_values)
+
+    if gap > CAL_CRITICAL_THRESHOLD:
+        status = MetricStatus.CRITICAL
+    elif gap > CAL_WARNING_THRESHOLD:
+        status = MetricStatus.NEEDS_REVIEW
+    else:
+        status = MetricStatus.PASSING
+
+    return {
+        "gap": round(gap, 4),
+        "status": status,
+        "calibrations": calibrations,
+    }
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Scatter Plot Data (predicted vs actual)
+# ═══════════════════════════════════════════════════════════════════════════
+
+def compute_scatter_data(
+    df: pd.DataFrame,
+    protected_attr: str,
+    predicted_col: str = "predicted_prob",
+    qualification_col: str = "qualified",
+    sample_size: int = 300,
+) -> list[dict]:
+    """
+    Produce scatter-plot data: predicted probability vs. actual qualification,
+    color-coded by group.  Downsample for frontend performance.
+    """
+    sampled = df.sample(n=min(sample_size, len(df)), random_state=42)
+
+    points = []
+    for _, row in sampled.iterrows():
+        points.append({
+            "actual": float(row[qualification_col]),
+            "predicted": float(row[predicted_col]),
+            "group": str(row[protected_attr]),
+        })
+
+    return points
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Aggregate Fairness Score (0–100)
+# ═══════════════════════════════════════════════════════════════════════════
+
+def compute_overall_fairness_score(
+    di_ratio: float,
+    eo_gap: float,
+    cal_gap: float,
+) -> float:
+    """
+    Combine the three metrics into a single 0-100 score.
+
+    Weights: DI=40%, EO=35%, Calibration=25%
+    Each sub-score is scaled so that threshold-passing = 90+
+    """
+    # DI score: 1.0 → 100, 0.80 → 70, 0.60 → 40
+    di_score = min(100, max(0, (di_ratio / 1.0) * 100))
+
+    # EO score: 0.0 gap → 100, 0.15 gap → 50
+    eo_score = min(100, max(0, (1 - eo_gap / 0.30) * 100))
+
+    # Cal score: 0.0 gap → 100, 0.12 gap → 60
+    cal_score = min(100, max(0, (1 - cal_gap / 0.30) * 100))
+
+    overall = di_score * 0.40 + eo_score * 0.35 + cal_score * 0.25
+    return round(overall, 1)
+
+
+def get_metric_status_label(status: MetricStatus) -> str:
+    """Convert MetricStatus enum to display label."""
+    return {
+        MetricStatus.PASSING: "Passing",
+        MetricStatus.NEEDS_REVIEW: "Needs review",
+        MetricStatus.CRITICAL: "Critical issue",
+    }[status]

backend/services/proxy_detector.py

@@ -0,0 +1,140 @@
+"""
+FairSight — Proxy Variable Detector
+Identifies features that appear neutral but encode protected characteristics
+(e.g. ZIP code acting as a racial proxy, school name encoding socioeconomic status).
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy.stats import chi2_contingency
+from sklearn.preprocessing import LabelEncoder
+
+from config import PROXY_CORRELATION_THRESHOLD, PROXY_HIGH_THRESHOLD
+
+
+def _cramers_v(x: pd.Series, y: pd.Series) -> float:
+    """
+    Compute Cramér's V statistic for two categorical variables.
+    Returns a value between 0 (no association) and 1 (perfect association).
+    """
+    # Build a contingency table
+    contingency = pd.crosstab(x, y)
+
+    if contingency.shape[0] < 2 or contingency.shape[1] < 2:
+        return 0.0
+
+    chi2, _, _, _ = chi2_contingency(contingency)
+    n = contingency.sum().sum()
+
+    min_dim = min(contingency.shape[0], contingency.shape[1]) - 1
+    if min_dim == 0 or n == 0:
+        return 0.0
+
+    return float(np.sqrt(chi2 / (n * min_dim)))
+
+
+def _point_biserial_like(feature: pd.Series, protected: pd.Series) -> float:
+    """
+    For a numeric feature and a categorical protected attribute,
+    compute a normalized between-group variance measure (eta-squared).
+    """
+    groups = protected.unique()
+    grand_mean = feature.mean()
+
+    ss_between = 0.0
+    ss_total = ((feature - grand_mean) ** 2).sum()
+
+    for g in groups:
+        mask = protected == g
+        group_mean = feature[mask].mean()
+        n_g = mask.sum()
+        ss_between += n_g * (group_mean - grand_mean) ** 2
+
+    if ss_total == 0:
+        return 0.0
+
+    eta_sq = ss_between / ss_total
+    return float(np.sqrt(eta_sq))  # return sqrt for a correlation-like scale
+
+
+def compute_feature_correlations(
+    df: pd.DataFrame,
+    feature_cols: list[str],
+    protected_attrs: list[str],
+) -> list[dict]:
+    """
+    Compute correlation between each feature and each protected attribute.
+    Uses Cramér's V for categorical-categorical and eta for numeric-categorical.
+    
+    Returns a list of dicts: {feature, protected_attribute, correlation}
+    """
+    results = []
+
+    for feat in feature_cols:
+        if feat not in df.columns:
+            continue
+
+        for attr in protected_attrs:
+            if attr not in df.columns:
+                continue
+
+            feat_series = df[feat].copy()
+            attr_series = df[attr].copy()
+
+            # Determine if feature is numeric or categorical
+            if pd.api.types.is_numeric_dtype(feat_series):
+                corr = _point_biserial_like(feat_series, attr_series)
+            else:
+                corr = _cramers_v(feat_series, attr_series)
+
+            results.append({
+                "feature": feat,
+                "protected_attribute": attr,
+                "correlation": round(corr, 2),
+            })
+
+    return results
+
+
+def detect_proxy_variables(
+    df: pd.DataFrame,
+    feature_cols: list[str],
+    protected_attrs: list[str],
+    threshold: float = PROXY_CORRELATION_THRESHOLD,
+) -> list[dict]:
+    """
+    Identify proxy variables — features whose correlation with a protected
+    attribute exceeds the threshold.
+
+    Returns list of {feature, protected_attribute, correlation, severity}
+    sorted by correlation descending.
+    """
+    all_corrs = compute_feature_correlations(df, feature_cols, protected_attrs)
+
+    proxies = []
+    for item in all_corrs:
+        if item["correlation"] >= threshold:
+            severity = "critical" if item["correlation"] >= PROXY_HIGH_THRESHOLD else "warning"
+            proxies.append({
+                **item,
+                "severity": severity,
+                "description": (
+                    f"'{item['feature']}' has a {item['correlation']:.2f} correlation "
+                    f"with '{item['protected_attribute']}', potentially acting as a proxy."
+                ),
+            })
+
+    proxies.sort(key=lambda x: x["correlation"], reverse=True)
+    return proxies
+
+
+def get_heatmap_data(
+    df: pd.DataFrame,
+    feature_cols: list[str],
+    protected_attrs: list[str],
+) -> list[dict]:
+    """
+    Return heatmap data (feature × protected attribute correlation matrix).
+    """
+    return compute_feature_correlations(df, feature_cols, protected_attrs)

backend/services/remediation_service.py

@@ -0,0 +1,302 @@
+"""
+FairSight — Remediation Service
+Generates prioritized, concrete interventions with expected impact estimates.
+"""
+from __future__ import annotations
+
+import uuid
+import numpy as np
+import pandas as pd
+
+from services.data_service import get_dataset
+from services.fairness_engine import (
+    compute_disparate_impact,
+    compute_equal_opportunity_gap,
+    compute_calibration_gap,
+)
+from services.proxy_detector import detect_proxy_variables
+from config import PROTECTED_ATTRIBUTES, FEATURE_COLUMNS
+
+
+def _estimate_proxy_removal_impact(
+    df: pd.DataFrame,
+    proxy_feature: str,
+    protected_attr: str,
+    correlation: float,
+) -> dict:
+    """Estimate the DI/EO/Cal improvement from removing a proxy feature."""
+    # Higher correlation → larger expected improvement
+    di_improvement = min(0.15, correlation * 0.25)
+    eo_improvement = min(0.10, correlation * 0.15)
+    cal_improvement = min(0.05, correlation * 0.08)
+
+    return {
+        "di": round(di_improvement, 3),
+        "eo": round(eo_improvement, 3),
+        "cal": round(cal_improvement, 3),
+    }
+
+
+def _estimate_reweight_impact(df: pd.DataFrame, protected_attr: str) -> dict:
+    """Estimate impact of reweighting training data for a protected attribute."""
+    di = compute_disparate_impact(df, protected_attr)
+    gap_from_parity = max(0, 1.0 - di["ratio"])
+
+    # Reweighting typically recovers 40–60% of the gap
+    di_improvement = round(gap_from_parity * 0.50, 3)
+    eo_improvement = round(gap_from_parity * 0.35, 3)
+    cal_improvement = round(gap_from_parity * 0.10, 3)
+
+    return {"di": di_improvement, "eo": eo_improvement, "cal": cal_improvement}
+
+
+def _estimate_threshold_impact(df: pd.DataFrame, protected_attr: str) -> dict:
+    """Estimate impact of group-specific threshold adjustment."""
+    di = compute_disparate_impact(df, protected_attr)
+    gap = max(0, 1.0 - di["ratio"])
+
+    di_improvement = round(gap * 0.70, 3)
+    eo_improvement = round(gap * 0.20, 3)
+    cal_improvement = round(gap * 0.05, 3)
+
+    return {"di": di_improvement, "eo": eo_improvement, "cal": cal_improvement}
+
+
+def generate_interventions(df: pd.DataFrame) -> list[dict]:
+    """
+    Generate a prioritized list of remediation interventions.
+    """
+    interventions: list[dict] = []
+    priority_counter = 1
+
+    available_features = [f for f in FEATURE_COLUMNS if f in df.columns]
+    available_attrs = [a for a in PROTECTED_ATTRIBUTES if a in df.columns]
+
+    # ── 1. Proxy removal recommendations ──────────────────────────────────
+    proxies = detect_proxy_variables(df, available_features, available_attrs)
+
+    for proxy in proxies:
+        impact = _estimate_proxy_removal_impact(
+            df, proxy["feature"], proxy["protected_attribute"], proxy["correlation"]
+        )
+        interventions.append({
+            "id": f"rem-proxy-{proxy['feature']}-{uuid.uuid4().hex[:8]}",
+            "type": "remove_proxy",
+            "title": f"Remove proxy feature: {proxy['feature']}",
+            "description": (
+                f"'{proxy['feature']}' correlates {proxy['correlation']:.2f} with "
+                f"'{proxy['protected_attribute']}'. Removing or transforming this feature "
+                f"would reduce indirect discrimination."
+            ),
+            "priority": priority_counter,
+            "expected_di_improvement": impact["di"],
+            "expected_eo_improvement": impact["eo"],
+            "expected_cal_improvement": impact["cal"],
+            "risk_level": "low" if proxy["correlation"] < 0.30 else "medium",
+            "implementation_effort": "low",
+            "affected_features": [proxy["feature"]],
+        })
+        priority_counter += 1
+
+    # ── 2. Reweighting recommendations (per protected attr) ───────────────
+    for attr in available_attrs:
+        di = compute_disparate_impact(df, attr)
+        if di["ratio"] < 0.90:
+            impact = _estimate_reweight_impact(df, attr)
+            interventions.append({
+                "id": f"rem-reweight-{attr}-{uuid.uuid4().hex[:8]}",
+                "type": "reweight_data",
+                "title": f"Reweight training data for {attr}",
+                "description": (
+                    f"Apply sample weights to balance representation and outcomes "
+                    f"across '{attr}' groups. This adjusts the training objective without "
+                    f"changing the feature set."
+                ),
+                "priority": priority_counter,
+                "expected_di_improvement": impact["di"],
+                "expected_eo_improvement": impact["eo"],
+                "expected_cal_improvement": impact["cal"],
+                "risk_level": "medium",
+                "implementation_effort": "medium",
+                "affected_features": [],
+            })
+            priority_counter += 1
+
+    # ── 3. Threshold adjustment recommendations ─────���────────────────────
+    for attr in available_attrs:
+        di = compute_disparate_impact(df, attr)
+        if di["ratio"] < 0.85:
+            impact = _estimate_threshold_impact(df, attr)
+            interventions.append({
+                "id": f"rem-threshold-{attr}-{uuid.uuid4().hex[:8]}",
+                "type": "adjust_threshold",
+                "title": f"Adjust decision thresholds for {attr}",
+                "description": (
+                    f"Apply group-specific decision thresholds to equalize approval rates "
+                    f"across '{attr}' groups. This is a post-processing intervention."
+                ),
+                "priority": priority_counter,
+                "expected_di_improvement": impact["di"],
+                "expected_eo_improvement": impact["eo"],
+                "expected_cal_improvement": impact["cal"],
+                "risk_level": "high",
+                "implementation_effort": "low",
+                "affected_features": [],
+            })
+            priority_counter += 1
+
+    # ── 4. Post-processing calibration ────────────────────────────────────
+    for attr in available_attrs:
+        cal = compute_calibration_gap(df, attr)
+        if cal["gap"] > 0.05:
+            interventions.append({
+                "id": f"rem-calibrate-{attr}-{uuid.uuid4().hex[:8]}",
+                "type": "post_process",
+                "title": f"Calibrate predictions across {attr} groups",
+                "description": (
+                    f"Apply Platt scaling or isotonic regression per '{attr}' group "
+                    f"to ensure predicted probabilities match actual outcomes equally."
+                ),
+                "priority": priority_counter,
+                "expected_di_improvement": 0.02,
+                "expected_eo_improvement": 0.03,
+                "expected_cal_improvement": round(cal["gap"] * 0.60, 3),
+                "risk_level": "low",
+                "implementation_effort": "medium",
+                "affected_features": [],
+            })
+            priority_counter += 1
+
+    return interventions
+
+
+def get_fairness_constraints() -> list[dict]:
+    """
+    Return adjustable fairness constraint sliders.
+    """
+    return [
+        {
+            "name": "min_disparate_impact",
+            "current_value": 0.80,
+            "min_value": 0.50,
+            "max_value": 1.00,
+            "step": 0.05,
+            "description": "Minimum acceptable disparate impact ratio (EEOC 4/5ths rule = 0.80)",
+        },
+        {
+            "name": "max_equal_opportunity_gap",
+            "current_value": 0.10,
+            "min_value": 0.00,
+            "max_value": 0.30,
+            "step": 0.01,
+            "description": "Maximum acceptable equal opportunity gap between groups",
+        },
+        {
+            "name": "max_calibration_gap",
+            "current_value": 0.08,
+            "min_value": 0.00,
+            "max_value": 0.20,
+            "step": 0.01,
+            "description": "Maximum acceptable calibration gap between groups",
+        },
+        {
+            "name": "min_accuracy",
+            "current_value": 0.75,
+            "min_value": 0.50,
+            "max_value": 0.95,
+            "step": 0.01,
+            "description": "Minimum acceptable overall model accuracy after remediation",
+        },
+    ]
+
+
+def apply_remediation(
+    df: pd.DataFrame,
+    intervention_ids: list[str],
+    constraints: dict[str, float],
+    protected_attr: str = "race",
+) -> dict:
+    """
+    Simulate the effect of applying selected interventions.
+    Returns before/after comparison.
+    """
+    # Current metrics
+    di_before = compute_disparate_impact(df, protected_attr)
+    eo_before = compute_equal_opportunity_gap(df, protected_attr)
+    cal_before = compute_calibration_gap(df, protected_attr)
+
+    # Simulate the remediation
+    df_remediated = df.copy()
+
+    # Parse which types of interventions are selected
+    has_proxy_removal = any("proxy" in iid for iid in intervention_ids)
+    has_reweighting = any("reweight" in iid for iid in intervention_ids)
+    has_threshold = any("threshold" in iid for iid in intervention_ids)
+    has_calibration = any("calibrate" in iid for iid in intervention_ids)
+
+    # Apply simulated effects
+    if has_threshold or has_reweighting:
+        # Shift decisions for underprivileged groups
+        groups = df_remediated[protected_attr].unique()
+        rates = {g: df_remediated.loc[df_remediated[protected_attr] == g, "decision"].mean() for g in groups}
+        max_rate = max(rates.values())
+
+        for g, rate in rates.items():
+            if rate < max_rate * 0.90:
+                mask = (df_remediated[protected_attr] == g) & (df_remediated["decision"] == 0)
+                n_to_flip = int(mask.sum() * 0.3)  # flip ~30% of rejections
+                if has_threshold:
+                    n_to_flip = int(mask.sum() * 0.5)
+                flip_indices = df_remediated[mask].sample(n=min(n_to_flip, mask.sum()), random_state=42).index
+                df_remediated.loc[flip_indices, "decision"] = 1
+
+    if has_proxy_removal:
+        # Simulate removing proxy influence by adding noise to decisions
+        # that were affected by proxy variables
+        rng = np.random.default_rng(42)
+        noise = rng.choice([0, 1], size=len(df_remediated), p=[0.95, 0.05])
+        decisions = df_remediated["decision"].values.copy()
+        # Only flip some denials to approvals for disadvantaged groups
+        groups = df_remediated[protected_attr].unique()
+        rates = {g: df_remediated.loc[df_remediated[protected_attr] == g, "decision"].mean() for g in groups}
+        max_rate = max(rates.values())
+
+        for g, rate in rates.items():
+            if rate < max_rate * 0.95:
+                flip_prob = min(0.15, (max_rate - rate) * 0.5)
+                mask = (df_remediated[protected_attr] == g) & (df_remediated["decision"] == 0)
+                n_flip = int(mask.sum() * flip_prob)
+                if n_flip > 0:
+                    flip_idx = df_remediated[mask].sample(n=n_flip, random_state=42).index
+                    df_remediated.loc[flip_idx, "decision"] = 1
+
+    # Compute after metrics
+    di_after = compute_disparate_impact(df_remediated, protected_attr)
+    eo_after = compute_equal_opportunity_gap(df_remediated, protected_attr)
+    cal_after = compute_calibration_gap(df_remediated, protected_attr)
+
+    # Build approval rates before/after
+    groups = df[protected_attr].unique()
+
+    def get_approval_rates(data: pd.DataFrame, attr: str) -> list[dict]:
+        rates = []
+        for g in sorted(data[attr].unique()):
+            mask = data[attr] == g
+            rates.append({
+                "group": str(g),
+                "rate": round(float(data.loc[mask, "decision"].mean()), 3),
+                "count": int(mask.sum()),
+            })
+        return rates
+
+    return {
+        "original_disparate_impact": di_before["ratio"],
+        "new_disparate_impact": di_after["ratio"],
+        "original_eo_gap": eo_before["gap"],
+        "new_eo_gap": eo_after["gap"],
+        "original_cal_gap": cal_before["gap"],
+        "new_cal_gap": cal_after["gap"],
+        "approval_rates_before": get_approval_rates(df, protected_attr),
+        "approval_rates_after": get_approval_rates(df_remediated, protected_attr),
+        "interventions_applied": intervention_ids,
+    }

backend/services/simulator_service.py

@@ -0,0 +1,167 @@
+"""
+FairSight — Simulator Service
+What-if simulation engine: adjust thresholds, reweighting, calibration,
+and feature removal to see real-time impact on fairness metrics.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from services.fairness_engine import (
+    compute_disparate_impact,
+    compute_equal_opportunity_gap,
+    compute_calibration_gap,
+)
+from config import PROTECTED_ATTRIBUTES
+
+
+def simulate(
+    df: pd.DataFrame,
+    threshold_adjustment: float = 0.0,
+    reweighting_strength: float = 0.0,
+    calibration_strength: float = 0.0,
+    remove_features: list[str] | None = None,
+    protected_attribute: str = "race",
+) -> dict:
+    """
+    Run a what-if simulation with the given parameters.
+    
+    Parameters:
+    - threshold_adjustment: Shift the decision boundary (negative = more approvals)
+    - reweighting_strength: 0-1, how aggressively to uplift underrepresented groups
+    - calibration_strength: 0-1, Platt-style calibration adjustment
+    - remove_features: list of feature names to exclude (proxy removal simulation)
+    - protected_attribute: which attribute to evaluate fairness against
+    
+    Returns before/after metrics and approval rates.
+    """
+    if protected_attribute not in df.columns:
+        protected_attribute = "race"
+
+    rng = np.random.default_rng(42)
+    df_sim = df.copy()
+
+    # ── Original metrics ──────────────────────────────────────────────────
+    orig_di = compute_disparate_impact(df, protected_attribute)
+    orig_eo = compute_equal_opportunity_gap(df, protected_attribute)
+    orig_cal = compute_calibration_gap(df, protected_attribute)
+
+    # ── 1. Threshold adjustment ───────────────────────────────────────────
+    if threshold_adjustment != 0.0:
+        # Shift the effective threshold on predicted_prob
+        # Negative adjustment → lower threshold → more approvals
+        new_threshold = 0.50 + threshold_adjustment
+        if "predicted_prob" in df_sim.columns:
+            df_sim["decision"] = (df_sim["predicted_prob"] >= new_threshold).astype(int)
+
+    # ── 2. Feature removal (proxy removal) ────────────────────────────────
+    if remove_features:
+        # Simulate feature removal by reducing the correlation between
+        # the feature and the decision.  We do this by re-computing decisions
+        # without the proxy influence.
+        for feature in remove_features:
+            if feature in df_sim.columns:
+                groups = df_sim[protected_attribute].unique()
+                approval_rates = {
+                    g: df_sim.loc[df_sim[protected_attribute] == g, "decision"].mean()
+                    for g in groups
+                }
+                max_rate = max(approval_rates.values())
+
+                for g, rate in approval_rates.items():
+                    if rate < max_rate:
+                        gap = max_rate - rate
+                        # Remove a portion of the gap proportional to feature removal
+                        target_improvement = gap * 0.40
+                        mask_denied = (df_sim[protected_attribute] == g) & (df_sim["decision"] == 0)
+                        n_flip = int(mask_denied.sum() * target_improvement)
+                        if n_flip > 0:
+                            flip_idx = df_sim[mask_denied].sample(
+                                n=min(n_flip, mask_denied.sum()), random_state=42
+                            ).index
+                            df_sim.loc[flip_idx, "decision"] = 1
+
+    # ── 3. Reweighting ────────────────────────────────────────────────────
+    if reweighting_strength > 0:
+        groups = df_sim[protected_attribute].unique()
+        approval_rates = {
+            g: df_sim.loc[df_sim[protected_attribute] == g, "decision"].mean()
+            for g in groups
+        }
+        max_rate = max(approval_rates.values())
+
+        for g, rate in approval_rates.items():
+            if rate < max_rate:
+                gap = max_rate - rate
+                improvement = gap * reweighting_strength * 0.6
+                mask_denied = (df_sim[protected_attribute] == g) & (df_sim["decision"] == 0)
+                n_flip = int(mask_denied.sum() * improvement)
+                if n_flip > 0:
+                    flip_idx = df_sim[mask_denied].sample(
+                        n=min(n_flip, mask_denied.sum()), random_state=42
+                    ).index
+                    df_sim.loc[flip_idx, "decision"] = 1
+
+    # ── 4. Calibration ────────────────────────────────────────────────────
+    if calibration_strength > 0 and "predicted_prob" in df_sim.columns:
+        groups = df_sim[protected_attribute].unique()
+
+        for g in groups:
+            mask = df_sim[protected_attribute] == g
+            subset = df_sim.loc[mask]
+
+            # Move predicted probabilities toward actual qualification rates
+            actual_rate = subset["qualified"].mean()
+            predicted_mean = subset["predicted_prob"].mean()
+            adjustment = (actual_rate - predicted_mean) * calibration_strength
+
+            df_sim.loc[mask, "predicted_prob"] = np.clip(
+                df_sim.loc[mask, "predicted_prob"] + adjustment, 0, 1
+            )
+
+        # Re-threshold after calibration
+        df_sim["decision"] = (df_sim["predicted_prob"] >= 0.50 + threshold_adjustment).astype(int)
+
+    # ── Simulated metrics ─────────────────────────────────────────────────
+    sim_di = compute_disparate_impact(df_sim, protected_attribute)
+    sim_eo = compute_equal_opportunity_gap(df_sim, protected_attribute)
+    sim_cal = compute_calibration_gap(df_sim, protected_attribute)
+
+    # ── Approval rates ────────────────────────────────────────────────────
+    def build_rates(data: pd.DataFrame) -> list[dict]:
+        rates = []
+        for g in sorted(data[protected_attribute].unique()):
+            mask = data[protected_attribute] == g
+            rates.append({
+                "group": str(g),
+                "rate": round(float(data.loc[mask, "decision"].mean()), 3),
+                "count": int(mask.sum()),
+            })
+        return rates
+
+    original_rates = build_rates(df)
+    simulated_rates = build_rates(df_sim)
+
+    # ── Accuracy impact ───────────────────────────────────────────────────
+    original_accuracy = (df["decision"] == df["qualified"]).mean()
+    simulated_accuracy = (df_sim["decision"] == df_sim["qualified"]).mean()
+    accuracy_impact = round(simulated_accuracy - original_accuracy, 4)
+
+    # ── Overall approval change ───────────────────────────────────────────
+    original_approval = df["decision"].mean()
+    simulated_approval = df_sim["decision"].mean()
+    overall_change = round(simulated_approval - original_approval, 4)
+
+    return {
+        "original_approval_rates": original_rates,
+        "simulated_approval_rates": simulated_rates,
+        "original_disparate_impact": orig_di["ratio"],
+        "simulated_disparate_impact": sim_di["ratio"],
+        "original_eo_gap": orig_eo["gap"],
+        "simulated_eo_gap": sim_eo["gap"],
+        "original_cal_gap": orig_cal["gap"],
+        "simulated_cal_gap": sim_cal["gap"],
+        "overall_approval_change": overall_change,
+        "accuracy_impact": accuracy_impact,
+    }

cloudbuild.yaml

@@ -0,0 +1,34 @@
+steps:
+  - name: node:20
+    entrypoint: npm
+    args: ["install"]
+    dir: frontend
+  - name: node:20
+    entrypoint: npm
+    args: ["run", "build"]
+    dir: frontend
+  - name: gcr.io/firebase-ci/firebase
+    entrypoint: firebase
+    args: ["deploy", "--only", "hosting", "--project", "fairlens-494713"]
+  - name: gcr.io/cloud-builders/docker
+    args: ["build", "-t", "us-central1-docker.pkg.dev/fairlens-494713/fairlens/fairsight-backend", "./backend"]
+  - name: gcr.io/cloud-builders/docker
+    args: ["push", "us-central1-docker.pkg.dev/fairlens-494713/fairlens/fairsight-backend"]
+  - name: gcr.io/google.com/cloudsdktool/cloud-sdk
+    entrypoint: gcloud
+    args:
+      [
+        "run",
+        "deploy",
+        "fairsight-backend",
+        "--image",
+        "us-central1-docker.pkg.dev/fairlens-494713/fairlens/fairsight-backend",
+        "--region",
+        "us-central1",
+        "--platform",
+        "managed",
+        "--allow-unauthenticated"
+      ]
+
+images:
+  - us-central1-docker.pkg.dev/fairlens-494713/fairlens/fairsight-backend

firebase.json

@@ -0,0 +1,27 @@
+{
+  "firestore": {
+    "rules": "firestore.rules",
+    "indexes": "firestore.indexes.json"
+  },
+  "storage": {
+    "rules": "storage.rules"
+  },
+  "functions": {
+    "source": "functions"
+  },
+  "hosting": {
+    "public": "frontend/dist",
+    "ignore": [
+      "firebase.json",
+      "**/.*",
+      "**/node_modules/**"
+    ],
+    "rewrites": [
+      {
+        "source": "**",
+        "destination": "/index.html"
+      }
+    ]
+  }
+}
+

firestore.indexes.json

@@ -0,0 +1,32 @@
+{
+  "indexes": [
+    {
+      "collectionGroup": "analyses",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "orgId", "order": "ASCENDING" },
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "alerts",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "orgId", "order": "ASCENDING" },
+        { "fieldPath": "severity", "order": "ASCENDING" },
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "remediations",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "orgId", "order": "ASCENDING" },
+        { "fieldPath": "analysisId", "order": "ASCENDING" },
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}
+

firestore.rules

@@ -0,0 +1,65 @@
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    function signedIn() {
+      return request.auth != null;
+    }
+
+    function isAdmin() {
+      return signedIn() && request.auth.token.admin == true;
+    }
+
+    function orgMatches(resourceOrgId) {
+      return signedIn() && request.auth.token.orgId != null && request.auth.token.orgId == resourceOrgId;
+    }
+
+    function canReadOrgData() {
+      return isAdmin() || orgMatches(resource.data.orgId);
+    }
+
+    function canWriteOrgData() {
+      return isAdmin() || (
+        signedIn() &&
+        request.resource.data.orgId == request.auth.token.orgId &&
+        request.resource.data.createdByUid == request.auth.uid
+      );
+    }
+
+    match /analyses/{docId} {
+      allow read: if canReadOrgData();
+      allow create, update: if canWriteOrgData();
+      allow delete: if isAdmin();
+    }
+
+    match /alerts/{docId} {
+      allow read: if canReadOrgData();
+      allow create, update: if canWriteOrgData();
+      allow delete: if isAdmin();
+    }
+
+    match /datasets/{docId} {
+      allow read: if canReadOrgData();
+      allow create, update: if canWriteOrgData();
+      allow delete: if isAdmin();
+    }
+
+    match /remediations/{docId} {
+      allow read: if canReadOrgData();
+      allow create, update: if canWriteOrgData();
+      allow delete: if isAdmin();
+    }
+
+    match /auditLogs/{docId} {
+      allow read: if isAdmin();
+      allow create: if signedIn();
+      allow update, delete: if false;
+    }
+
+    match /users/{uid} {
+      allow read: if signedIn() && (request.auth.uid == uid || isAdmin());
+      allow create, update: if signedIn() && request.auth.uid == uid;
+      allow delete: if false;
+    }
+  }
+}
+

frontend/.env.example

@@ -0,0 +1,8 @@
+VITE_FIREBASE_API_KEY=
+VITE_FIREBASE_AUTH_DOMAIN=fairlens-494713.firebaseapp.com
+VITE_FIREBASE_PROJECT_ID=fairlens-494713
+VITE_FIREBASE_STORAGE_BUCKET=fairlens-494713.firebasestorage.app
+VITE_FIREBASE_MESSAGING_SENDER_ID=884728849298
+VITE_FIREBASE_APP_ID=
+VITE_FIREBASE_FUNCTIONS_REGION=us-central1
+

frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>FairSight</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+  </html>
+

frontend/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "fairsight-frontend",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "firebase": "^11.7.1",
+    "papaparse": "^5.5.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.30.0",
+    "recharts": "^2.15.3"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.4.1",
+    "vite": "^5.4.19"
+  }
+}
+

frontend/src/App.jsx

@@ -0,0 +1,48 @@
+import { Navigate, Route, Routes } from "react-router-dom";
+import { useAuth } from "./contexts/AuthContext";
+import AppShell from "./components/AppShell";
+import DashboardPage from "./pages/DashboardPage";
+import MetricsPage from "./pages/MetricsPage";
+import AlertsPage from "./pages/AlertsPage";
+import SimulatorPage from "./pages/SimulatorPage";
+import UploadPage from "./pages/UploadPage";
+import RemediationPage from "./pages/RemediationPage";
+import LoginPage from "./pages/LoginPage";
+
+function ProtectedRoute({ children }) {
+  const { user, loading } = useAuth();
+
+  if (loading) {
+    return <div className="screen-center">Loading...</div>;
+  }
+
+  if (!user) {
+    return <Navigate to="/login" replace />;
+  }
+
+  return children;
+}
+
+export default function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<LoginPage />} />
+      <Route
+        path="/"
+        element={
+          <ProtectedRoute>
+            <AppShell />
+          </ProtectedRoute>
+        }
+      >
+        <Route index element={<DashboardPage />} />
+        <Route path="metrics" element={<MetricsPage />} />
+        <Route path="alerts" element={<AlertsPage />} />
+        <Route path="simulator" element={<SimulatorPage />} />
+        <Route path="upload" element={<UploadPage />} />
+        <Route path="remediations" element={<RemediationPage />} />
+      </Route>
+    </Routes>
+  );
+}
+

frontend/src/components/AppShell.jsx

@@ -0,0 +1,70 @@
+import { NavLink, Outlet } from "react-router-dom";
+import { useState } from "react";
+import { useAuth } from "../contexts/AuthContext";
+import { httpsCallable } from "firebase/functions";
+import { functions } from "../lib/firebase";
+import GeminiChat from "./GeminiChat";
+
+const navItems = [
+  ["Dashboard", "/"],
+  ["Metrics", "/metrics"],
+  ["Alerts", "/alerts"],
+  ["Simulator", "/simulator"],
+  ["Upload", "/upload"],
+  ["Remediations", "/remediations"]
+];
+
+export default function AppShell() {
+  const { user, logout } = useAuth();
+  const [starting, setStarting] = useState(false);
+
+  const startServer = async () => {
+    setStarting(true);
+    try {
+      const callable = httpsCallable(functions, "startServer");
+      const response = await callable({});
+      alert("Server started successfully!");
+    } catch (error) {
+      alert("Failed to start server: " + error.message);
+    } finally {
+      setStarting(false);
+    }
+  };
+
+  return (
+    <div className="app-shell">
+      <aside className="sidebar">
+        <div>
+          <p className="eyebrow">FairSight</p>
+          <h1>Bias review workspace</h1>
+        </div>
+        <nav className="nav-list">
+          {navItems.map(([label, path]) => (
+            <NavLink
+              key={path}
+              to={path}
+              end={path === "/"}
+              className={({ isActive }) => `nav-link ${isActive ? "active" : ""}`}
+            >
+              {label}
+            </NavLink>
+          ))}
+        </nav>
+        <div className="user-card">
+          <div>{user?.email}</div>
+          <button className="secondary-button" onClick={startServer} disabled={starting}>
+            {starting ? "Starting..." : "START Server"}
+          </button>
+          <button className="secondary-button" onClick={logout}>
+            Sign out
+          </button>
+        </div>
+      </aside>
+      <main className="content">
+        <Outlet />
+      </main>
+      <GeminiChat />
+    </div>
+  );
+}
+

frontend/src/components/Charts.jsx

@@ -0,0 +1,74 @@
+import {
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Line,
+  LineChart,
+  PolarAngleAxis,
+  PolarGrid,
+  Radar,
+  RadarChart,
+  ResponsiveContainer,
+  Scatter,
+  ScatterChart,
+  Tooltip,
+  XAxis,
+  YAxis
+} from "recharts";
+
+export function ApprovalRatesChart({ data }) {
+  return (
+    <ResponsiveContainer width="100%" height={280}>
+      <BarChart data={data}>
+        <CartesianGrid strokeDasharray="3 3" />
+        <XAxis dataKey="group" />
+        <YAxis />
+        <Tooltip />
+        <Bar dataKey="rate" fill="#2563eb" />
+      </BarChart>
+    </ResponsiveContainer>
+  );
+}
+
+export function FairnessRadar({ data }) {
+  return (
+    <ResponsiveContainer width="100%" height={280}>
+      <RadarChart data={data}>
+        <PolarGrid />
+        <PolarAngleAxis dataKey="metric" />
+        <Radar dataKey="score" stroke="#0f766e" fill="#14b8a6" fillOpacity={0.4} />
+        <Tooltip />
+      </RadarChart>
+    </ResponsiveContainer>
+  );
+}
+
+export function CalibrationScatter({ data }) {
+  return (
+    <ResponsiveContainer width="100%" height={300}>
+      <ScatterChart>
+        <CartesianGrid strokeDasharray="3 3" />
+        <XAxis dataKey="predicted" name="Predicted" />
+        <YAxis dataKey="actual" name="Actual" />
+        <Tooltip cursor={{ strokeDasharray: "3 3" }} />
+        <Scatter data={data} fill="#7c3aed" />
+      </ScatterChart>
+    </ResponsiveContainer>
+  );
+}
+
+export function BeforeAfterLine({ data }) {
+  return (
+    <ResponsiveContainer width="100%" height={280}>
+      <LineChart data={data}>
+        <CartesianGrid strokeDasharray="3 3" />
+        <XAxis dataKey="group" />
+        <YAxis />
+        <Tooltip />
+        <Line type="monotone" dataKey="before" stroke="#475569" />
+        <Line type="monotone" dataKey="after" stroke="#16a34a" />
+      </LineChart>
+    </ResponsiveContainer>
+  );
+}
+

frontend/src/components/GeminiChat.jsx

@@ -0,0 +1,61 @@
+import { httpsCallable } from "firebase/functions";
+import { useState } from "react";
+import { functions } from "../lib/firebase";
+
+export default function GeminiChat() {
+  const [open, setOpen] = useState(false);
+  const [question, setQuestion] = useState("");
+  const [messages, setMessages] = useState([]);
+  const [loading, setLoading] = useState(false);
+
+  const ask = async () => {
+    if (!question.trim()) return;
+    setLoading(true);
+    const nextQuestion = question;
+    setMessages((current) => [...current, { role: "user", text: nextQuestion }]);
+    setQuestion("");
+
+    try {
+      const callable = httpsCallable(functions, "geminiExplain");
+      const result = await callable({ question: nextQuestion });
+      setMessages((current) => [...current, { role: "assistant", text: result.data.answer }]);
+    } catch (error) {
+      setMessages((current) => [
+        ...current,
+        { role: "assistant", text: error.message || "Explanation service unavailable." }
+      ]);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className={`chat-widget ${open ? "open" : ""}`}>
+      <button className="chat-toggle" onClick={() => setOpen((current) => !current)}>
+        Explainability Bot
+      </button>
+      {open && (
+        <div className="chat-panel">
+          <div className="chat-messages">
+            {messages.map((message, index) => (
+              <div key={`${message.role}-${index}`} className={`chat-bubble ${message.role}`}>
+                {message.text}
+              </div>
+            ))}
+          </div>
+          <div className="chat-input-row">
+            <input
+              value={question}
+              onChange={(event) => setQuestion(event.target.value)}
+              placeholder="Why is my disparate impact score low?"
+            />
+            <button onClick={ask} disabled={loading}>
+              Send
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+

frontend/src/contexts/AuthContext.jsx

@@ -0,0 +1,45 @@
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+import {
+  GoogleAuthProvider,
+  createUserWithEmailAndPassword,
+  onAuthStateChanged,
+  signInWithEmailAndPassword,
+  signInWithPopup,
+  signOut
+} from "firebase/auth";
+import { auth } from "../lib/firebase";
+
+const AuthContext = createContext(null);
+const provider = new GoogleAuthProvider();
+
+export function AuthProvider({ children }) {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const unsub = onAuthStateChanged(auth, (nextUser) => {
+      setUser(nextUser);
+      setLoading(false);
+    });
+    return unsub;
+  }, []);
+
+  const value = useMemo(
+    () => ({
+      user,
+      loading,
+      signInWithGoogle: () => signInWithPopup(auth, provider),
+      signInWithEmail: (email, password) => signInWithEmailAndPassword(auth, email, password),
+      signUpWithEmail: (email, password) => createUserWithEmailAndPassword(auth, email, password),
+      logout: () => signOut(auth)
+    }),
+    [user, loading]
+  );
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+export function useAuth() {
+  return useContext(AuthContext);
+}
+

frontend/src/hooks/useOrgCollection.js

@@ -0,0 +1,39 @@
+import { collection, onSnapshot, orderBy, query, where } from "firebase/firestore";
+import { useEffect, useState } from "react";
+import { db } from "../lib/firebase";
+import { useAuth } from "../contexts/AuthContext";
+
+export function useOrgCollection(collectionName, extraConstraints = []) {
+  const { user } = useAuth();
+  const [data, setData] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    if (!user) {
+      setData([]);
+      setLoading(false);
+      return;
+    }
+
+    const orgId = user?.reloadUserInfo?.customAttributes
+      ? JSON.parse(user.reloadUserInfo.customAttributes).orgId
+      : "demo-org";
+
+    const q = query(
+      collection(db, collectionName),
+      where("orgId", "==", orgId),
+      ...extraConstraints,
+      orderBy("createdAt", "desc")
+    );
+
+    const unsub = onSnapshot(q, (snapshot) => {
+      setData(snapshot.docs.map((doc) => ({ id: doc.id, ...doc.data() })));
+      setLoading(false);
+    });
+
+    return unsub;
+  }, [collectionName, extraConstraints, user]);
+
+  return { data, loading };
+}
+

frontend/src/lib/firebase.js

@@ -0,0 +1,25 @@
+import { initializeApp } from "firebase/app";
+import { getAuth } from "firebase/auth";
+import { getFirestore } from "firebase/firestore";
+import { getFunctions } from "firebase/functions";
+import { getStorage } from "firebase/storage";
+
+const firebaseConfig = {
+  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
+  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
+  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
+  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
+  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
+  appId: import.meta.env.VITE_FIREBASE_APP_ID
+};
+
+const app = initializeApp(firebaseConfig);
+
+export const auth = getAuth(app);
+export const db = getFirestore(app);
+export const storage = getStorage(app);
+export const functions = getFunctions(
+  app,
+  import.meta.env.VITE_FIREBASE_FUNCTIONS_REGION || "us-central1"
+);
+

frontend/src/main.jsx

@@ -0,0 +1,17 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import App from "./App";
+import { AuthProvider } from "./contexts/AuthContext";
+import "./styles/app.css";
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <AuthProvider>
+        <App />
+      </AuthProvider>
+    </BrowserRouter>
+  </React.StrictMode>
+);
+

frontend/src/pages/AlertsPage.jsx

@@ -0,0 +1,26 @@
+import { useOrgCollection } from "../hooks/useOrgCollection";
+
+export default function AlertsPage() {
+  const { data: alerts, loading } = useOrgCollection("alerts");
+
+  if (loading) {
+    return <div className="panel">Loading alerts...</div>;
+  }
+
+  return (
+    <div className="page-grid">
+      {alerts.map((alert) => (
+        <section key={alert.id} className="panel">
+          <div className="row-between">
+            <h3>{alert.title}</h3>
+            <span className={`chip ${alert.severity}`}>{alert.severity}</span>
+          </div>
+          <p>{alert.description}</p>
+          <p className="muted">Affected features: {(alert.affectedFeatures || []).join(", ") || "None"}</p>
+          <p className="muted">Recommended action: {alert.recommendation}</p>
+        </section>
+      ))}
+    </div>
+  );
+}
+

frontend/src/pages/DashboardPage.jsx

@@ -0,0 +1,54 @@
+import { useMemo } from "react";
+import { ApprovalRatesChart, FairnessRadar } from "../components/Charts";
+import { useOrgCollection } from "../hooks/useOrgCollection";
+
+export default function DashboardPage() {
+  const { data: analyses, loading } = useOrgCollection("analyses");
+  const latest = analyses[0];
+
+  const radar = useMemo(() => latest?.fairnessScores || [], [latest]);
+
+  if (loading) {
+    return <div className="panel">Loading dashboard...</div>;
+  }
+
+  return (
+    <div className="page-grid">
+      <section className="panel summary-grid">
+        <div>
+          <p className="eyebrow">Overall fairness score</p>
+          <div className="metric-xl">{latest?.overallFairnessScore ?? "--"}</div>
+        </div>
+        <div>
+          <p className="eyebrow">Groups analyzed</p>
+          <div className="metric-xl">{latest?.groupsAnalyzed ?? 0}</div>
+        </div>
+        <div>
+          <p className="eyebrow">Flagged features</p>
+          <div className="metric-xl">{latest?.flaggedFeatures ?? 0}</div>
+        </div>
+      </section>
+      <section className="panel">
+        <h3>Approval rates by group</h3>
+        <ApprovalRatesChart data={latest?.approvalRates || []} />
+      </section>
+      <section className="panel">
+        <h3>Fairness profile</h3>
+        <FairnessRadar data={radar} />
+      </section>
+      <section className="panel">
+        <h3>Proxy heatmap</h3>
+        <div className="heatmap">
+          {(latest?.heatmap || []).map((cell) => (
+            <div key={`${cell.feature}-${cell.protected_attribute}`} className="heatmap-row">
+              <span>{cell.feature}</span>
+              <span>{cell.protected_attribute}</span>
+              <span>{cell.correlation}</span>
+            </div>
+          ))}
+        </div>
+      </section>
+    </div>
+  );
+}
+

frontend/src/pages/LoginPage.jsx

@@ -0,0 +1,51 @@
+import { useState } from "react";
+import { Navigate } from "react-router-dom";
+import { useAuth } from "../contexts/AuthContext";
+
+export default function LoginPage() {
+  const { user, signInWithEmail, signInWithGoogle, signUpWithEmail } = useAuth();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [createMode, setCreateMode] = useState(false);
+
+  if (user) {
+    return <Navigate to="/" replace />;
+  }
+
+  const submit = async (event) => {
+    event.preventDefault();
+    if (createMode) {
+      await signUpWithEmail(email, password);
+    } else {
+      await signInWithEmail(email, password);
+    }
+  };
+
+  return (
+    <div className="screen-center">
+      <form className="panel auth-panel" onSubmit={submit}>
+        <p className="eyebrow">FairSight</p>
+        <h2>Sign in</h2>
+        <input value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
+        <input
+          type="password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          placeholder="Password"
+        />
+        <button type="submit">{createMode ? "Create account" : "Sign in"}</button>
+        <button type="button" className="secondary-button" onClick={() => signInWithGoogle()}>
+          Continue with Google
+        </button>
+        <button
+          type="button"
+          className="link-button"
+          onClick={() => setCreateMode((current) => !current)}
+        >
+          {createMode ? "Already have an account?" : "Need an account?"}
+        </button>
+      </form>
+    </div>
+  );
+}
+

frontend/src/pages/MetricsPage.jsx

@@ -0,0 +1,54 @@
+import { useState } from "react";
+import { CalibrationScatter } from "../components/Charts";
+import { useOrgCollection } from "../hooks/useOrgCollection";
+
+export default function MetricsPage() {
+  const { data: analyses } = useOrgCollection("analyses");
+  const [attribute, setAttribute] = useState("race");
+  const latest = analyses.find((item) => item.protectedAttribute === attribute) || analyses[0];
+
+  return (
+    <div className="page-grid">
+      <section className="panel toolbar">
+        <h2>Fairness metrics</h2>
+        <select value={attribute} onChange={(event) => setAttribute(event.target.value)}>
+          <option value="race">Race</option>
+          <option value="gender">Gender</option>
+          <option value="age">Age</option>
+          <option value="disability">Disability</option>
+        </select>
+      </section>
+      <section className="panel metrics-grid">
+        <div>
+          <p className="eyebrow">Disparate impact</p>
+          <div className="metric-lg">{latest?.disparateImpactRatio ?? "--"}</div>
+        </div>
+        <div>
+          <p className="eyebrow">Equal opportunity gap</p>
+          <div className="metric-lg">{latest?.equalOpportunityGap ?? "--"}</div>
+        </div>
+        <div>
+          <p className="eyebrow">Calibration gap</p>
+          <div className="metric-lg">{latest?.calibrationGap ?? "--"}</div>
+        </div>
+      </section>
+      <section className="panel">
+        <h3>Group outcomes</h3>
+        <div className="list">
+          {(latest?.groupDetails || []).map((item) => (
+            <div key={item.group} className="list-row">
+              <span>{item.group}</span>
+              <span>{item.value}</span>
+              <span>{item.sample_size}</span>
+            </div>
+          ))}
+        </div>
+      </section>
+      <section className="panel">
+        <h3>Predicted vs actual</h3>
+        <CalibrationScatter data={latest?.scatterData || []} />
+      </section>
+    </div>
+  );
+}
+

frontend/src/pages/RemediationPage.jsx

@@ -0,0 +1,21 @@
+import { useOrgCollection } from "../hooks/useOrgCollection";
+
+export default function RemediationPage() {
+  const { data: remediations } = useOrgCollection("remediations");
+
+  return (
+    <div className="page-grid">
+      {remediations.map((item) => (
+        <section key={item.id} className="panel">
+          <div className="row-between">
+            <h3>{item.title}</h3>
+            <span className="chip info">{item.type}</span>
+          </div>
+          <p>{item.description}</p>
+          <p className="muted">Expected DI improvement: {item.expectedDiImprovement}</p>
+        </section>
+      ))}
+    </div>
+  );
+}
+

frontend/src/pages/SimulatorPage.jsx

@@ -0,0 +1,76 @@
+import { httpsCallable } from "firebase/functions";
+import { useState } from "react";
+import { BeforeAfterLine } from "../components/Charts";
+import { functions } from "../lib/firebase";
+
+export default function SimulatorPage() {
+  const [thresholdAdjustment, setThresholdAdjustment] = useState(0);
+  const [reweightingStrength, setReweightingStrength] = useState(0.2);
+  const [calibrationStrength, setCalibrationStrength] = useState(0.1);
+  const [result, setResult] = useState(null);
+
+  const runSimulation = async () => {
+    const callable = httpsCallable(functions, "runSimulator");
+    const response = await callable({
+      thresholdAdjustment,
+      reweightingStrength,
+      calibrationStrength,
+      removeFeatures: [],
+      protectedAttribute: "race"
+    });
+    setResult(response.data);
+  };
+
+  const chartData = (result?.originalApprovalRates || []).map((row, index) => ({
+    group: row.group,
+    before: row.rate,
+    after: result?.simulatedApprovalRates?.[index]?.rate ?? row.rate
+  }));
+
+  return (
+    <div className="page-grid">
+      <section className="panel">
+        <h2>What-if simulator</h2>
+        <label>
+          Threshold
+          <input
+            type="range"
+            min="-0.5"
+            max="0.5"
+            step="0.05"
+            value={thresholdAdjustment}
+            onChange={(e) => setThresholdAdjustment(Number(e.target.value))}
+          />
+        </label>
+        <label>
+          Reweighting
+          <input
+            type="range"
+            min="0"
+            max="1"
+            step="0.05"
+            value={reweightingStrength}
+            onChange={(e) => setReweightingStrength(Number(e.target.value))}
+          />
+        </label>
+        <label>
+          Calibration
+          <input
+            type="range"
+            min="0"
+            max="1"
+            step="0.05"
+            value={calibrationStrength}
+            onChange={(e) => setCalibrationStrength(Number(e.target.value))}
+          />
+        </label>
+        <button onClick={runSimulation}>Run simulation</button>
+      </section>
+      <section className="panel">
+        <h3>Approval rate change</h3>
+        <BeforeAfterLine data={chartData} />
+      </section>
+    </div>
+  );
+}
+

frontend/src/pages/UploadPage.jsx

@@ -0,0 +1,63 @@
+import Papa from "papaparse";
+import { getDownloadURL, ref, uploadBytes } from "firebase/storage";
+import { useState } from "react";
+import { storage } from "../lib/firebase";
+import { useAuth } from "../contexts/AuthContext";
+
+export default function UploadPage() {
+  const { user } = useAuth();
+  const [preview, setPreview] = useState([]);
+  const [columns, setColumns] = useState([]);
+  const [status, setStatus] = useState("");
+
+  const handleFile = async (file) => {
+    setStatus("Uploading...");
+
+    Papa.parse(file, {
+      header: true,
+      preview: 5,
+      complete: async (results) => {
+        setPreview(results.data);
+        setColumns(results.meta.fields || []);
+      }
+    });
+
+    const orgId = "demo-org";
+    const objectRef = ref(storage, `uploads/${orgId}/${Date.now()}-${file.name}`);
+    await uploadBytes(objectRef, file, {
+      contentType: file.type || "text/csv",
+      customMetadata: {
+        uploadedByUid: user?.uid || "",
+        orgId
+      }
+    });
+
+    await getDownloadURL(objectRef);
+    setStatus("Upload complete. Analysis trigger queued.");
+  };
+
+  return (
+    <div className="page-grid">
+      <section className="panel">
+        <h2>Dataset upload</h2>
+        <input type="file" accept=".csv" onChange={(e) => handleFile(e.target.files[0])} />
+        <p className="muted">{status}</p>
+        <div className="list">
+          {columns.map((column) => (
+            <div key={column} className="list-row">
+              <span>{column}</span>
+              <span>
+                {["race", "gender", "age", "disability"].includes(column) ? "Protected attribute" : "Feature"}
+              </span>
+            </div>
+          ))}
+        </div>
+      </section>
+      <section className="panel">
+        <h3>Preview</h3>
+        <pre className="code-block">{JSON.stringify(preview, null, 2)}</pre>
+      </section>
+    </div>
+  );
+}
+

frontend/src/styles/app.css

@@ -0,0 +1,227 @@
+:root {
+  color-scheme: light;
+  font-family: Inter, Arial, sans-serif;
+  color: #0f172a;
+  background: #f8fafc;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+}
+
+button,
+input,
+select {
+  font: inherit;
+}
+
+button {
+  border: 0;
+  border-radius: 8px;
+  background: #2563eb;
+  color: white;
+  padding: 10px 14px;
+  cursor: pointer;
+}
+
+input,
+select {
+  width: 100%;
+  border: 1px solid #cbd5e1;
+  border-radius: 8px;
+  padding: 10px 12px;
+}
+
+.secondary-button {
+  background: #e2e8f0;
+  color: #0f172a;
+}
+
+.link-button {
+  background: transparent;
+  color: #2563eb;
+  padding: 0;
+}
+
+.app-shell {
+  display: grid;
+  grid-template-columns: 260px 1fr;
+  min-height: 100vh;
+}
+
+.sidebar {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  padding: 24px;
+  background: #0f172a;
+  color: white;
+}
+
+.nav-list {
+  display: grid;
+  gap: 8px;
+  margin-top: 24px;
+}
+
+.nav-link {
+  color: #cbd5e1;
+  text-decoration: none;
+  padding: 10px 12px;
+  border-radius: 8px;
+}
+
+.nav-link.active {
+  background: #1d4ed8;
+  color: white;
+}
+
+.content {
+  padding: 24px;
+}
+
+.page-grid {
+  display: grid;
+  gap: 20px;
+}
+
+.panel {
+  background: white;
+  border: 1px solid #e2e8f0;
+  border-radius: 8px;
+  padding: 20px;
+}
+
+.summary-grid,
+.metrics-grid {
+  display: grid;
+  gap: 16px;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+}
+
+.toolbar,
+.row-between,
+.list-row,
+.chat-input-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.list,
+.heatmap {
+  display: grid;
+  gap: 10px;
+}
+
+.eyebrow,
+.muted {
+  color: #64748b;
+}
+
+.metric-xl {
+  font-size: 44px;
+  font-weight: 700;
+}
+
+.metric-lg {
+  font-size: 28px;
+  font-weight: 700;
+}
+
+.screen-center {
+  min-height: 100vh;
+  display: grid;
+  place-items: center;
+}
+
+.auth-panel {
+  width: min(420px, calc(100vw - 32px));
+  display: grid;
+  gap: 12px;
+}
+
+.user-card {
+  display: grid;
+  gap: 12px;
+}
+
+.chip {
+  padding: 4px 10px;
+  border-radius: 999px;
+  font-size: 12px;
+  text-transform: capitalize;
+  background: #e2e8f0;
+}
+
+.chip.critical {
+  background: #fee2e2;
+  color: #b91c1c;
+}
+
+.chip.warning {
+  background: #fef3c7;
+  color: #b45309;
+}
+
+.chip.info {
+  background: #dbeafe;
+  color: #1d4ed8;
+}
+
+.code-block {
+  overflow: auto;
+  max-height: 300px;
+  background: #0f172a;
+  color: #e2e8f0;
+  border-radius: 8px;
+  padding: 12px;
+}
+
+.chat-widget {
+  position: fixed;
+  right: 20px;
+  bottom: 20px;
+}
+
+.chat-panel {
+  width: 320px;
+  background: white;
+  border: 1px solid #cbd5e1;
+  border-radius: 8px;
+  padding: 12px;
+  margin-top: 10px;
+}
+
+.chat-messages {
+  display: grid;
+  gap: 8px;
+  max-height: 260px;
+  overflow: auto;
+  margin-bottom: 12px;
+}
+
+.chat-bubble {
+  padding: 10px;
+  border-radius: 8px;
+}
+
+.chat-bubble.user {
+  background: #dbeafe;
+}
+
+.chat-bubble.assistant {
+  background: #f1f5f9;
+}
+
+@media (max-width: 900px) {
+  .app-shell {
+    grid-template-columns: 1fr;
+  }
+}
+

frontend/vite.config.js

@@ -0,0 +1,10 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173
+  }
+});
+

functions/.env.example

@@ -0,0 +1,5 @@
+FAIRNESS_BACKEND_URL=
+GEMINI_API_KEY=
+VERTEX_AI_ENDPOINT=
+GOOGLE_CLOUD_PROJECT=fairlens-494713
+