Metadata-Version: 2.4
Name: profilefoundry
Version: 1.0.1
Summary: Generate deterministic, linked, temporally coherent synthetic Person Objects.
Author: Sriram Selvam
License-Expression: LicenseRef-ProfileFoundry-Citation-1.0
Project-URL: Homepage, https://github.com/selvamsriram/ProfileFoundry
Project-URL: Issues, https://github.com/selvamsriram/ProfileFoundry/issues
Keywords: synthetic-data,pii,person-object,linkage,evaluation,privacy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.6
Requires-Dist: faker>=24.0
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: pyarrow>=15.0
Requires-Dist: click>=8.1
Requires-Dist: rapidfuzz>=3.6
Requires-Dist: pybloom-live>=4.0
Requires-Dist: requests>=2.31
Requires-Dist: tqdm>=4.66
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ipython>=8.20; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Requires-Dist: seaborn>=0.13; extra == "viz"
Requires-Dist: plotly>=5.20; extra == "viz"
Provides-Extra: hf
Requires-Dist: datasets>=2.18; extra == "hf"
Requires-Dist: huggingface-hub>=0.23; extra == "hf"
Dynamic: license-file

# ProfileFoundry

[GitHub: selvamsriram/ProfileFoundry](https://github.com/selvamsriram/ProfileFoundry) ·
[Hugging Face dataset: srirxml/ProfileFoundry-Core-100K](https://huggingface.co/datasets/srirxml/ProfileFoundry-Core-100K)

ProfileFoundry is a Python package for generating structured, deterministic
synthetic Person Objects. It is built for tests, demos, evaluations, and data
pipelines that need realistic-looking people with internally consistent
identity, address, employment, education, finance, health, contact, household,
relationship, and event-history fields.

The generator supports eight locales and can emit single profiles, linked
households, JSONL batches, or normalized parquet datasets.

## Install

```bash
pip install profilefoundry
```

For development from a checkout:

```bash
pip install -e ".[dev,hf]"
```

## Quick Start

Check that the installed package can generate every supported locale:

```bash
profilefoundry verify
```

Generate one profile as JSON:

```bash
profilefoundry person --locale US --seed 4321 --profile-seq 1
```

Generate a linked household. Household members share household IDs, addresses,
family edges, emergency contacts, and spouse/parent/child/sibling references
where applicable:

```bash
profilefoundry household --locale UK --seed 4321 --seq 7
```

Generate 1,000 flat JSONL profiles:

```bash
profilefoundry scale --n 1000 --locale CA --out /tmp/ca_profiles.jsonl
```

Generate 500 linked households as JSONL:

```bash
profilefoundry scale-households \
  --n 500 \
  --locale AU \
  --seed 4321 \
  --out /tmp/au_households.jsonl
```

Run validation on a small generated sample:

```bash
profilefoundry validate \
  --n 300 \
  --locales US,UK,IN \
  --skip-hibp
```

Export a normalized multi-locale dataset with JSONL, parquet tables, a dataset
card, and a manifest:

```bash
profilefoundry export \
  --out /tmp/profilefoundry_core \
  --n-per-locale 1000 \
  --generation-date 2026-05-24 \
  --exported-at 2026-05-24T00:00:00Z \
  --skip-hibp
```

Time generation at multiple scales:

```bash
profilefoundry scale-smoke --locale US --sizes 1000,10000
```

## What It Generates

Each Person Object includes:

- Stable IDs and deterministic generation metadata
- Identity fields such as name, date of birth, gender, nationality, and birthplace
- Current and historical addresses
- Contact details using reserved `profilefoundry.example` domains
- Education and employment records
- Household and family links
- Finance and health attributes
- Replayable non-credit event timelines

The same seed and pinned generation date reproduce the same generated content.

## Dataset

The public 100K-profile dataset is available on Hugging Face:

[srirxml/ProfileFoundry-Core-100K](https://huggingface.co/datasets/srirxml/ProfileFoundry-Core-100K)

The Hugging Face release includes canonical JSONL, a complete
`person_objects.parquet` viewer table, normalized relational parquet files,
a manifest with file hashes, validation reports, and leakage-audit summaries.

## CLI Reference

| Command | Purpose | Example |
|---|---|---|
| `profilefoundry verify` | Generate one profile per supported locale as a smoke test. | `profilefoundry verify` |
| `profilefoundry person` | Print one deterministic Person Object as JSON. | `profilefoundry person --locale US --seed 4321 --profile-seq 1` |
| `profilefoundry household` | Print one linked household as JSON. | `profilefoundry household --locale UK --seed 4321 --seq 7` |
| `profilefoundry scale` | Generate flat JSONL profiles for one locale. | `profilefoundry scale --n 1000 --locale CA --out /tmp/ca.jsonl` |
| `profilefoundry scale-households` | Generate linked household members as JSONL. | `profilefoundry scale-households --n 500 --locale AU --out /tmp/au_households.jsonl` |
| `profilefoundry validate` | Run distributional, leakage, replay, and consistency checks. | `profilefoundry validate --n 300 --locales US,UK,IN --skip-hibp` |
| `profilefoundry export` | Write JSONL, parquet tables, manifest, and dataset card. | `profilefoundry export --out /tmp/pf_core --n-per-locale 1000 --skip-hibp` |
| `profilefoundry scale-smoke` | Time the generator at several sizes. | `profilefoundry scale-smoke --sizes 1000,10000,100000` |

## Python API

```python
from datetime import date

from profilefoundry.generate.factory import make_person
from profilefoundry.linkage.orchestrator import iter_households

person = make_person(locale="US", profile_seq=1, global_seed=4321, today=date(2026, 5, 24))
print(person.model_dump_json(indent=2))

household = next(iter_households("US", n_households=1, global_seed=4321, today=date(2026, 5, 24)))
print([p.profile_id for p in household.persons])
```

Write a small JSONL file from Python:

```python
from datetime import date
from pathlib import Path

from profilefoundry.generate.factory import make_person

out = Path("/tmp/us_profiles.jsonl")
with out.open("w", encoding="utf-8") as handle:
    for seq in range(1, 101):
        person = make_person(
            locale="US",
            profile_seq=seq,
            global_seed=4321,
            today=date(2026, 5, 24),
        )
        handle.write(person.model_dump_json() + "\n")
```

## Validation And Reproducibility

ProfileFoundry ships with reference-data loaders, deterministic seed
derivation, release report checks, and invariant tests for schema shape,
age-gating, addresses, education, employment, household/family linkage,
timeline replay, leakage checks, normalized export integrity, and
reproducibility.

From a checkout:

```bash
python -m pytest tests/
python scripts/verify_reproducibility.py
python scripts/verify_hf_release_current.py
```

## Limitations

These limitations describe the current package behavior:

- Generated profiles are adults-only; the generator does not emit children as
  standalone Person Objects.
- The core generator is structured-data only. It does not generate documents,
  biographies, messages, images, or other free-text content.
- Supported locales are `US`, `UK`, `CA`, `AU`, `NZ`, `IE`, `IN`, and `PH`.
- Full distributional validation is implemented for `US`, `UK`, `IN`, `CA`,
  and `AU`; `IE`, `NZ`, and `PH` use the same generation pipeline but have
  lighter validation coverage.
- Family linkage is household-local. Cross-household extended-family edges are
  not generated.
- Emails use reserved `profilefoundry.example` domains. They are suitable for
  test data and should not be treated as deliverable addresses.
- Financial, health, education, and employment fields are synthetic
  approximations for testing and evaluation, not claims about real people.
- The package includes compact reference tables needed by the generator; richer
  upstream reference refreshes are handled by repository scripts, not at import
  time.

## License

- Code and SDK: **ProfileFoundry Citation License 1.0**. Public uses and
  redistributions must cite the ProfileFoundry paper when available, or this
  repository until then. Machine-readable citation metadata is in
  `CITATION.cff`.
- Generated dataset: **CC-BY-4.0**.
- Embedded reference data retains its upstream license; see
  `data/reference/MANIFEST.md`.
