demoparity

Counterfactual demographic auditing for LLM prompts. Swap protected attributes (sex, race, residency, or anything you define) into an otherwise identical prompt, send every variant to the same model, and test statistically whether the response changes with the attribute.

This work is a generalised, reusable version of the paired-prompt audit design from my Bachelor Thesis "Breaking the Bias: Addressing the Social Biases in Artificial Natural Language Models for Neuroscientific and Medical Implementation" (Steward, 2023; presented at the 3rd Connected Learning Symposium (2024), and the Black Scholar and Expert Conference (2023)). My original thesis built a "NeuroAnalyser" tool around a ChatGPT-3.5 use case.

demoparity keeps the same statistical design (descriptive stats, an enter-method OLS regression, Pearson's correlations with Fisher's z) but detaches it from one use case, so it works for multiple uses.

Motivation

Common design for LLM bias checks look at some example outputs or run a static benchmark dataset once. This design also wants to assess why a model's behaviour may differ, or whether different responses show a pattern that is distinguishable from noise.

Install

```bash
pip install demoparity
pip install demoparity[litellm]   # call a model

How it works

1. build_design crosses every scenario with every attribute-level combination.
2. run_design sends each prompt through a model, concurrently, via litellm (OpenAI, Anthropic, Gemini, Bedrock, Ollama, 100+ providers, one model-string convention). Each provider's key comes from its standard environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...).
3. annotate extracts response length and attribute-mention counts.
4. run_audit runs descriptive stats, an enter-method OLS regression, and Pearson correlations, and returns a report you can save to Markdown/CSV.

import demoparity as dp

design = dp.build_design(
    [dp.Scenario("c1", "A {sex} patient reports a headache. Advise.")],
    [dp.Attribute("sex", ["neutral", "male", "female"])],
)
results = dp.run_design(design, dp.litellm_generator(model="gpt-4o-mini"))
results = dp.annotate(results)
report = dp.run_audit(results, outcomes=["word_count"], predictors=["sex"])
print(report.to_markdown())

See examples/ for full worked audits with mention-tracking, checkpointing, and saved output.

Examples

Require a real API key (see Install above)

• examples/hiring_screen_audit.py is a resume screener, sex/name-origin/location
• examples/clinical_triage_audit.py mirrors clinical triage, sex/race/residency (my thesis study)

export OPENAI_API_KEY=sk-..
python examples/hiring_screen_audit.py --model gpt-4o-mini

Concurrency and checkpointing

run_design sends requests concurrently (concurrency=, default 5) and, with checkpoint_path=, writes each completed trial to a JSONL file as it finishes. Re-running with the same checkpoint path resumes and skips already-completed trials.

Saving output

from demoparity.persistence import save_results, save_report

save_results(results, "results.csv")
save_report(report, "report_dir")   # report.md + descriptives.csv + correlations.csv + one CSV per regression

Command line

demoparity design spec.json --out design.csv
demoparity run design.csv --model gpt-4o-mini --checkpoint run.jsonl --out results.csv
demoparity report results.csv --outcomes word_count --predictors sex --save-dir report_dir

License

MIT. See LICENSE.