Metadata-Version: 2.4
Name: demoparity
Version: 0.2.0
Summary: A Python package for counterfactual demographic auditing of LLM prompts.
Author: Cindy Steward
License: MIT
Project-URL: Homepage, https://github.com/cindysteward/demoparity
Project-URL: Repository, https://github.com/cindysteward/demoparity
Project-URL: Issues, https://github.com/cindysteward/demoparity/issues
Keywords: llm,nlp,fairness,bias,auditing,counterfactual,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: statsmodels>=0.14
Requires-Dist: tabulate>=0.9
Provides-Extra: litellm
Requires-Dist: litellm>=1.50; extra == "litellm"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Dynamic: license-file

# 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
```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](https://docs.litellm.ai) (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.

```python
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)

```bash
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

```python
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

```bash
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](LICENSE).
