ProfileFoundry

Project site · GitHub: selvamsriram/ProfileFoundry · Hugging Face dataset: srirxml/ProfileFoundry-Synthetic-Person-Objects

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

pip install profilefoundry

For development from a checkout:

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

Quick Start

Check that the installed package can generate every supported locale:

profilefoundry verify

Generate one profile as JSON:

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:

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

Generate 1,000 flat JSONL profiles:

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

Generate 500 linked households as JSONL:

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

Run validation on a small generated sample:

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:

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:

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-Synthetic-Person-Objects

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

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:

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:

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.