creforge 0.1.0__tar.gz

creforge-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: python -m pytest -m "not slow"
+
+  calibration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -m slow

creforge-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+# Publishes to PyPI when a GitHub release is published. Uses PyPI trusted
+# publishing (OIDC), so no API token is stored in the repository.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

creforge-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+/out/
+/bureau/
+dist/

creforge-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

creforge-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: creforge
+Version: 0.1.0
+Summary: PII-safe synthetic credit bureau data from explicit behavioural rules.
+Project-URL: Homepage, https://github.com/chowkuanlaw/creforge
+Author: creforge contributors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: credit-bureau,credit-risk,privacy,synthetic-data,test-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: polars>=1.0
+Requires-Dist: pyarrow>=14
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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.
+
+```console
+$ pip install creforge
+$ creforge generate --subjects 1000000 --months 36 --seed 42 --out ./bureau --workers 4
+$ creforge validate ./bureau --strict
+```
+
+## Why not SDV / Faker?
+
+| | Faker-style | Fit-to-real (SDV, GAN, ...) | **creforge** |
+|---|---|---|---|
+| Needs real data | No | **Yes**: privacy review, leakage risk | No |
+| Delinquency dynamics | None | Learned; can break the rules | Explicit Markov model |
+| Can a loan jump from current to 90+? | n/a | Yes | **Never** (tested invariant) |
+| Referential integrity across tables | Manual | Often approximate | Guaranteed and validated |
+| Reproducible | Mostly | Rarely byte-identical | **Byte-identical per seed**, any worker count |
+| Explainable parameters | n/a | No | Every probability is in a commented YAML file |
+
+## The data
+
+| Table | One row per | Highlights |
+|---|---|---|
+| `subject` | borrower | Latent `risk_grade` A–E is exported, so it doubles as ground truth for testing scorecards. No names, IDs or addresses. |
+| `inquiry` | credit application | Approval odds fall as a borrower makes more applications ("credit hungry" behaviour). |
+| `account` | credit facility | `credit_card`, `personal_loan`, `mortgage`, `auto_loan`, `overdraft`, `bnpl`. New accounts link to their approved inquiry. Older accounts start part-way through their life. |
+| `account_month` | account × month | Balance, amount due, amount paid, DPD bucket (`0` … `120+`), months in arrears, status. |
+
+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:
+
+| Product | 30+ DPD share | Annual write-off rate |
+|---|---|---|
+| credit_card | 3.9% | 3.7% |
+| personal_loan | 4.6% | 3.8% |
+| mortgage | 1.1% | 0.4% |
+| auto_loan | 3.1% | 2.2% |
+| overdraft | 2.9% | 2.5% |
+| bnpl | 6.3% | 0.8% |
+
+12-month bad rate by grade: A 0.03% · B 0.5% · C 1.2% · D 6.7% · E 18%.
+
+## Python API
+
+```python
+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:
+
+```yaml
+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
+
+| Run | Time | Peak memory per worker | Parquet size |
+|---|---|---|---|
+| 200k subjects × 36 months, 1 worker | 15 s | < 1 GB | 0.16 GB |
+| 1M subjects × 36 months, 4 workers | 24 s | 0.9 GB | 0.78 GB |
+
+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
+
+```console
+$ 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`](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

creforge-0.1.0/README.md

@@ -0,0 +1,154 @@
+# 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.
+
+```console
+$ pip install creforge
+$ creforge generate --subjects 1000000 --months 36 --seed 42 --out ./bureau --workers 4
+$ creforge validate ./bureau --strict
+```
+
+## Why not SDV / Faker?
+
+| | Faker-style | Fit-to-real (SDV, GAN, ...) | **creforge** |
+|---|---|---|---|
+| Needs real data | No | **Yes**: privacy review, leakage risk | No |
+| Delinquency dynamics | None | Learned; can break the rules | Explicit Markov model |
+| Can a loan jump from current to 90+? | n/a | Yes | **Never** (tested invariant) |
+| Referential integrity across tables | Manual | Often approximate | Guaranteed and validated |
+| Reproducible | Mostly | Rarely byte-identical | **Byte-identical per seed**, any worker count |
+| Explainable parameters | n/a | No | Every probability is in a commented YAML file |
+
+## The data
+
+| Table | One row per | Highlights |
+|---|---|---|
+| `subject` | borrower | Latent `risk_grade` A–E is exported, so it doubles as ground truth for testing scorecards. No names, IDs or addresses. |
+| `inquiry` | credit application | Approval odds fall as a borrower makes more applications ("credit hungry" behaviour). |
+| `account` | credit facility | `credit_card`, `personal_loan`, `mortgage`, `auto_loan`, `overdraft`, `bnpl`. New accounts link to their approved inquiry. Older accounts start part-way through their life. |
+| `account_month` | account × month | Balance, amount due, amount paid, DPD bucket (`0` … `120+`), months in arrears, status. |
+
+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:
+
+| Product | 30+ DPD share | Annual write-off rate |
+|---|---|---|
+| credit_card | 3.9% | 3.7% |
+| personal_loan | 4.6% | 3.8% |
+| mortgage | 1.1% | 0.4% |
+| auto_loan | 3.1% | 2.2% |
+| overdraft | 2.9% | 2.5% |
+| bnpl | 6.3% | 0.8% |
+
+12-month bad rate by grade: A 0.03% · B 0.5% · C 1.2% · D 6.7% · E 18%.
+
+## Python API
+
+```python
+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:
+
+```yaml
+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
+
+| Run | Time | Peak memory per worker | Parquet size |
+|---|---|---|---|
+| 200k subjects × 36 months, 1 worker | 15 s | < 1 GB | 0.16 GB |
+| 1M subjects × 36 months, 4 workers | 24 s | 0.9 GB | 0.78 GB |
+
+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
+
+```console
+$ 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`](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

creforge-0.1.0/benchmarks/bench_generate.py

@@ -0,0 +1,39 @@
+"""Throughput benchmark: python benchmarks/bench_generate.py --subjects 1000000 --workers 8"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import tempfile
+import time
+from pathlib import Path
+
+import creforge as cf
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--subjects", type=int, default=200_000)
+    ap.add_argument("--months", type=int, default=36)
+    ap.add_argument("--workers", type=int, default=1)
+    ap.add_argument("--chunk-size", type=int, default=50_000)
+    ap.add_argument("--keep", type=Path, help="Write here instead of a temp dir")
+    args = ap.parse_args()
+
+    out = args.keep or Path(tempfile.mkdtemp(prefix="creforge-bench-"))
+    cfg = cf.Config.from_profile("baseline", subjects=args.subjects, months=args.months,
+                                 seed=1, chunk_size=args.chunk_size)
+    t0 = time.perf_counter()
+    manifest = cf.write_dataset(cfg, out, workers=args.workers)
+    secs = time.perf_counter() - t0
+    rows = manifest["row_counts"]["account_month"]
+    size = sum(p.stat().st_size for p in out.rglob("*.parquet"))
+    print(f"subjects={args.subjects:,} months={args.months} workers={args.workers}")
+    print(f"account_month rows={rows:,}  time={secs:.1f}s  rows/s={rows / secs:,.0f}  "
+          f"parquet={size / 1e9:.2f} GB")
+    if not args.keep:
+        shutil.rmtree(out)
+
+
+if __name__ == "__main__":
+    main()