creforge

PII-safe synthetic credit bureau data, generated from explicit behavioural rules.

creforge generates realistic, linked credit-bureau-shaped datasets: borrowers, credit inquiries, accounts and monthly payment histories. The data has real delinquency dynamics, vintage curves and stress scenarios, and no real data ever goes in. There is no model fitted to real records, so there is nothing to memorise or leak.

Use it to test credit data pipelines, demo dashboards, teach credit-risk analytics, benchmark warehouses, or give contractors and vendors a realistic dataset without a data-sharing agreement.

$ pip install creforge
$ creforge generate --subjects 1000000 --months 36 --seed 42 --out ./bureau --workers 4
$ creforge validate ./bureau --strict

Why not SDV / Faker?

The data

Output is one Parquet or CSV part file per chunk per table, plus a manifest.json recording the version, seed, full resolved config and its SHA-256.

How it works

Every month, each open account draws one event: roll (miss a payment, move one bucket worse), cure (pay all arrears), back (pay one installment of arrears), restructure, close, or stay. The probabilities are

base[product, state] × grade multiplier × seasoning(months on book) × macro(month)

The DPD bucket is derived from months in arrears. Balances and payments are derived from the event. So an account can never skip a bucket, pay while rolling forward, or show a DPD that disagrees with its arrears. Accounts that already exist when the window opens start in a state drawn from the model's own age-conditional distribution, so the first month shows no warm-up artefact.

Validation

creforge validate reports:

• Integrity (hard guarantees; any failure is a bug): unique ids, every foreign key resolves, the account opens on or after its approved inquiry, month histories are contiguous and end at closure, no rows after write-off, no skipped buckets, no payment on a roll-forward, no negative amounts.
• Calibration (against the profile's targets): 30+ DPD share and annual write-off rate per product; 12-month bad rate increasing across grades; the seasoning peak falls at 6–35 months on book; no artefact at the start of the window.
• Privacy statement, with the config hash, to attach to data-handling approvals.

Baseline, 50k subjects × 36 months:

12-month bad rate by grade: A 0.03% · B 0.5% · C 1.2% · D 6.7% · E 18%.

Python API

import creforge as cf

cfg = cf.Config.from_profile("stressed", subjects=100_000, months=48, seed=7)
ds = cf.generate(cfg)                  # in memory; ds.account_month is a polars DataFrame
report = cf.validate(ds)
print(report.to_markdown())

cf.write_dataset(cfg, "out/", workers=4)   # streaming, bounded memory, for big runs

Profiles

baseline (flat economy) and stressed (roll rates ramp to 1.8× around month 15, then recover) are built in. creforge profiles show baseline prints every parameter. To make your own, write a YAML file that starts with extends: baseline and override only what you need:

extends: baseline
name: subprime_cards
grades:
  E: {share: 0.20}     # fields merge; this assumes you rebalance the other shares

All built-in parameters are illustrative. They are hand-set to land in the right order of magnitude compared with publicly published aggregate statistics (sources are cited in the YAML). They do not describe any real lender's or bureau's portfolio.

Performance

Measured on a 4-vCPU Linux container. Run python benchmarks/bench_generate.py to measure your own machine.

Roadmap

1. v1.1: guarantor and joint-account links (account_party), including contingent liabilities.
2. Business subjects, directors and shareholding graphs.
3. Collateral and legal/litigation records.
4. Clearly marked synthetic PII for UI testing.
5. Calibration to published aggregate statistics.
6. Scripted scenarios (moratoria, rate shocks).
7. DuckDB/Postgres/Iceberg loaders; dbt and Glue catalog integration.
8. Country flavour packs built only from public specifications.

Contributing

$ pip install -e ".[dev]"
$ ruff check . && pytest -m "not slow"   # fast suite
$ pytest -m slow                         # calibration suite

CI runs on Linux, macOS and Windows with Python 3.10–3.13. Design notes are in docs/superpowers/specs.

Clean-room rule: contributions must not contain parameters, code sets or schemas derived from any employer's or institution's non-public systems or data.

License

Apache-2.0