---
title: "Employment AI Bias Audit with AIGovernance"
author: "Subir Hait, Michigan State University"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Employment AI Bias Audit with AIGovernance}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

> **Disclaimer:** `AIGovernance` provides statistical auditing and
> documentation support tools only. It does not provide legal advice and
> does not certify compliance with any law or regulation. Users should seek
> qualified legal counsel for all compliance determinations.

## Overview

`AIGovernance` helps organisations document, audit, and report on the
fairness and governance properties of employment AI systems — specifically
Automated Employment Decision Tools (AEDTs). Version 0.1.0 covers three
frameworks:

| Framework | Jurisdiction | Nature |
|---|---|---|
| **EEOC Uniform Guidelines** (4/5ths rule) | US Federal | Regulatory |
| **NYC Local Law 144** | New York City | Mandatory (employers using AEDTs) |
| **NIST AI RMF 1.0** | US Federal | Voluntary / best practice |
| **EU AI Act** (risk classification only) | European Union | Regulatory |

---

## 1. Load Package and Data

```{r load}
library(AIGovernance)

data(hiring_sim)
head(hiring_sim)
```

The built-in `hiring_sim` dataset contains 500 synthetic job applicants
processed by a hypothetical resume-screening tool.

```{r summary}
table(hiring_sim$race_ethnicity, hiring_sim$selected)
```

---

## 2. Build the Governance Object

`aigov_build()` is the entry point. Specify the data, binary outcome,
protected-class column, and reference group.

```{r build}
gov <- aigov_build(
  data        = hiring_sim,
  outcome     = selected,
  group       = race_ethnicity,
  ref_group   = "White",
  frameworks  = c("EEOC", "NYC_LL144", "NIST_RMF"),
  org_name    = "Acme Corporation",
  system_name = "ResumeAI v1.0"
)

print(gov)
```

---

## 3. Check Which Laws Apply

```{r scope}
aigov_scope(gov, domain = "employment", us_state = "NY")
```

---

## 4. EEOC Adverse Impact Analysis (4/5ths Rule)

```{r eeoc}
gov <- aigov_adverse_impact(gov)
gov$results$adverse_impact$table
```

The Adverse Impact Ratio (AIR) compares each group's selection rate to the
reference group (White). Groups with AIR < 0.80 are flagged under the EEOC
4/5ths rule.

---

## 5. NYC Local Law 144 Bias Audit

NYC LL144 uses a slightly different denominator — the *most-selected
category* — rather than a user-defined reference group.

```{r nyc}
gov <- aigov_audit_nyc(gov)
gov$results$nyc_ll144$disclosure_table
```

The disclosure table is formatted to match the public posting requirements
under NYC LL144.

---

## 6. NIST AI RMF Checklist

Supply your organisation's confirmed governance practices as a named list:

```{r nist}
gov <- aigov_audit_nist(gov, responses = list(
  GOVERN_1_1 = TRUE,   # Risk policy documented
  GOVERN_1_2 = TRUE,   # Roles defined
  GOVERN_1_3 = FALSE,  # Leadership oversight not yet formalised
  MAP_1_1    = TRUE,   # System purpose documented
  MAP_1_2    = TRUE,   # Affected populations identified
  MAP_1_3    = TRUE,   # Regulatory requirements identified
  MAP_2_1    = TRUE,   # Harms identified
  MEASURE_1_1 = TRUE,  # Fairness metrics defined
  MANAGE_2_1  = FALSE  # Human review not yet in place
))

gov$results$nist_rmf$scores
gov$results$nist_rmf$verdict
```

Use `aigov_checklist(gov, "NIST_RMF")` to see all item names.

---

## 7. Risk Classification

```{r classify}
gov <- aigov_classify(
  gov,
  domain               = "employment",
  makes_final_decision = TRUE,
  human_oversight      = FALSE
)
```

Employment AI that makes or substantially influences hiring decisions falls
under **Annex III (High Risk)** of the EU AI Act.

---

## 8. Generate an Audit Report

```{r report, eval=FALSE}
# Produces a self-contained HTML report
aigov_report(gov, format = "html", open = TRUE)
```

The report includes:

- Organisation and system metadata
- EEOC adverse impact table with AIR values
- NYC LL144 disclosure table and procedural checklist
- NIST AI RMF function scores
- EU AI Act risk tier and key obligations
- Full disclaimer

---

## 9. Checklist Reference

```{r checklist}
aigov_checklist(gov, "NYC_LL144")
```

---

## References

- EEOC (1978). Uniform Guidelines on Employee Selection Procedures.
  *Federal Register*, 43(166), 38295–38309.
- New York City Local Law 144 (2021, effective 2023). NYC DCWP.
  <https://www.nyc.gov/site/dca/about/automated-employment-decision-tools.page>
- NIST (2023). *AI Risk Management Framework (AI RMF 1.0)*.
  <https://doi.org/10.6028/NIST.AI.100-1>
- European Parliament and Council (2024). Regulation (EU) 2024/1689
  (EU AI Act). <https://digital-strategy.ec.europa.eu/en/policies/regulatory-framework-ai>