fix: make CE entity generation deterministic when seeded (#117)

- rework RNG plumbing across person, insurance, finance, public-sector
generators so seeded runs replay deterministically while unseeded runs
stay random
- expand CE datasets (countries, ecommerce currencies, product vocab,
shipping/payment tables) for ES/FR/GB coverage and align integration
descriptors with new data
- rebuild CE integration suite around local descriptors (no EE
references) and add reproducibility assertions with rngSeed fixtures
- add regression tests ensuring unseeded generators still emit varied
data and “other” gender nobility titles remain strings
- clean up Faker RNG wiring, bank currency sampling, and adapter
services to satisfy mypy/ruff and keep tasks deterministic
- document WHY blocks in descriptors/scripts for future maintainers and
seed ledger helper for deterministic finance scripts
- verified with `uv run pytest -q
tests_ce/integration_tests/test_entity`, `uv run pytest
tests_ce/unit_tests/test_generator/test_person_generator_randomness.py`,
and `mypy datamimic_ce`

Author: ake2l

datamimic_ce/domains/common/generators/person_generator.py

@@ -57,19 +57,55 @@ def __init__(
             and resolved_config.age_min > resolved_config.age_max
         ):
             raise ValueError("age_min cannot be greater than age_max")
-        self._gender_generator = GenderGenerator(female_quota=female_quota, other_gender_quota=other_gender_quota)
-        self._given_name_generator = GivenNameGenerator(dataset=self._dataset)
-        self._family_name_generator = FamilyNameGenerator(dataset=self._dataset)
-        self._email_generator = EmailAddressGenerator(dataset=self._dataset)
-        self._phone_generator = PhoneNumberGenerator(dataset=self._dataset)
-        self._address_generator = AddressGenerator(dataset=self._dataset)
+        # Fan out deterministic RNG copies so rngSeed descriptors yield reproducible composite attributes.
+        self._gender_generator = GenderGenerator(
+            female_quota=female_quota,
+            other_gender_quota=other_gender_quota,
+            rng=self._derive_rng() if rng is not None else None,
+        )
+        self._given_name_generator = GivenNameGenerator(
+            dataset=self._dataset,
+            rng=self._derive_rng() if rng is not None else None,
+        )
+        self._family_name_generator = FamilyNameGenerator(
+            dataset=self._dataset,
+            rng=self._derive_rng() if rng is not None else None,
+        )
+        self._email_generator = EmailAddressGenerator(
+            dataset=self._dataset,
+            rng=self._derive_rng() if rng is not None else None,
+        )
+        self._phone_generator = PhoneNumberGenerator(
+            dataset=self._dataset,
+            rng=self._derive_rng() if rng is not None else None,
+        )
+        self._address_generator = AddressGenerator(
+            dataset=self._dataset,
+            rng=self._derive_rng() if rng is not None else None,
+        )
         self._demographic_config = resolved_config
         birth_min = self._demographic_config.age_min if self._demographic_config.age_min is not None else min_age
         birth_max = self._demographic_config.age_max if self._demographic_config.age_max is not None else max_age
         # Clamp birthdate sampling to caller-provided bounds without scattering defaults.
-        self._birthdate_generator = BirthdateGenerator(min_age=birth_min, max_age=birth_max)
-        self._academic_title_generator = AcademicTitleGenerator(dataset=self._dataset, quota=academic_title_quota)
-        self._nobility_title_generator = NobilityTitleGenerator(dataset=self._dataset, noble_quota=noble_quota)
+        self._birthdate_generator = BirthdateGenerator(
+            min_age=birth_min,
+            max_age=birth_max,
+            rng=self._derive_rng() if rng is not None else None,
+        )
+        self._academic_title_generator = AcademicTitleGenerator(
+            dataset=self._dataset,
+            quota=academic_title_quota,
+            rng=self._derive_rng() if rng is not None else None,
+        )
+        self._nobility_title_generator = NobilityTitleGenerator(
+            dataset=self._dataset,
+            noble_quota=noble_quota,
+            rng=self._derive_rng() if rng is not None else None,
+        )
+
+    def _derive_rng(self) -> Random:
+        # Spawn child RNGs from the base seed so seeded descriptors replay without entangling independent draws.
+        return Random(self._rng.randrange(2**63)) if isinstance(self._rng, Random) else Random()
 
     @property
     def gender_generator(self) -> GenderGenerator:

datamimic_ce/domains/common/literal_generators/birthdate_generator.py

@@ -5,6 +5,7 @@
 # For questions and support, contact: info@rapiddweller.com
 
 from datetime import datetime, timedelta
+from random import Random
 
 from datamimic_ce.domains.common.literal_generators.datetime_generator import DateTimeGenerator
 from datamimic_ce.domains.domain_core.base_literal_generator import BaseLiteralGenerator
@@ -31,6 +32,7 @@ def __init__(
         self,
         min_age: int = 1,
         max_age: int = 100,
+        rng: Random | None = None,
     ) -> None:
         """
         Parameters:
@@ -48,8 +50,14 @@ def __init__(
             today = datetime(today.year, 2, 28)
         self._min_birthdate = datetime(today.year - max_age - 1, today.month, today.day) + timedelta(days=1)
         self._max_birthdate = datetime(today.year - min_age, today.month, today.day)
+        base_rng = rng or Random()
+        # Derive a dedicated RNG for date sampling so seeded runs stay reproducible without cross-coupling streams.
+        date_rng = Random(base_rng.randrange(2**63)) if rng is not None else Random()
         self._date_generator = DateTimeGenerator(
-            min=str(self._min_birthdate), max=str(self._max_birthdate), random=True
+            min=str(self._min_birthdate),
+            max=str(self._max_birthdate),
+            random=True,
+            rng=date_rng,
         )
 
     def generate(self) -> datetime:

datamimic_ce/domains/common/literal_generators/data_faker_generator.py

@@ -4,14 +4,19 @@
 # See LICENSE file for the full text of the license.
 # For questions and support, contact: info@rapiddweller.com
 
-from typing import Any
+import random
+from typing import Any, Protocol, cast
 
 from faker import Faker
 
 from datamimic_ce.domains.domain_core.base_literal_generator import BaseLiteralGenerator
 from datamimic_ce.enums.faker_enums import UnsupportedMethod
 
 
+class _SupportsRandom(Protocol):
+    random: random.Random
+
+
 class DataFakerGenerator(BaseLiteralGenerator):
     """
     This is an implement of Python Faker
@@ -23,12 +28,17 @@ def __init__(
         method: str,
         locale: str | None = "en_US",
         *args,
+        rng: random.Random | None = None,
         **kwargs,
     ) -> None:
         # validation support methods
         if method in UnsupportedMethod._value2member_map_ or method.startswith("_"):
             raise ValueError(f"Faker method '{method}' is not supported")
         self._faker = Faker(locale)
+        if rng is not None:
+            # WHY: faker.Faker exposes a dynamic `random` attribute; cast to a protocol so mypy accepts the assignment.
+            faker_with_random = cast(_SupportsRandom, self._faker)
+            faker_with_random.random = rng
         self._method = method
         self._locale = locale
         self._args = args

datamimic_ce/domains/common/literal_generators/datetime_generator.py

@@ -44,9 +44,10 @@ def __init__(
         minute_granularity: int | None = None,
         second_granularity: int | None = None,
         seed: int | None = None,
+        rng: _random.Random | None = None,
     ):
-        # private RNG for determinism
-        self._rng = _random.Random(seed)
+        # Allow callers to inject their rng so rngSeed descriptors replay deterministically.
+        self._rng = rng or _random.Random(seed)
 
         # format and weights
         self._input_format = input_format if input_format else "%Y-%m-%d %H:%M:%S"

datamimic_ce/domains/common/literal_generators/domain_generator.py

@@ -27,7 +27,8 @@ def __init__(self, dataset: str | None = None, rng: random.Random | None = None)
         self._tld_dataset = FileUtil.read_wgt_file(tld_path)
 
         self._company_name: str | None = None
-        self._company_name_generator = CompanyNameGenerator()
+        # Share the deterministic RNG so seeded email/domain combos remain reproducible end-to-end.
+        self._company_name_generator = CompanyNameGenerator(rng=self._rng)
 
     def generate(self) -> str:
         """

datamimic_ce/domains/common/literal_generators/email_address_generator.py

@@ -24,15 +24,25 @@ def __init__(
         dataset: str | None = None,
         given_name: str | None = None,
         family_name: str | None = None,
+        rng: random.Random | None = None,
     ):
         self._dataset = (dataset or "US").upper()  #  align downstream generators with ISO-based datasets
-        self._rng: random.Random = random.Random()
+        self._rng: random.Random = rng or random.Random()
+
+        def _derive_rng() -> random.Random:
+            # Split deterministic streams so rngSeed descriptors do not couple email joins with domain picks.
+            return random.Random(self._rng.randrange(2**63)) if rng is not None else random.Random()
+
         self._given_name = given_name
-        self._given_name_generator = GivenNameGenerator(dataset=self._dataset) if given_name is None else None
+        self._given_name_generator = (
+            GivenNameGenerator(dataset=self._dataset, rng=_derive_rng()) if given_name is None else None
+        )
         self._family_name = family_name
-        self._family_name_generator = FamilyNameGenerator(dataset=self._dataset) if family_name is None else None
+        self._family_name_generator = (
+            FamilyNameGenerator(dataset=self._dataset, rng=_derive_rng()) if family_name is None else None
+        )
         self._company_name: str | None = None
-        self._domain_generator = DomainGenerator(dataset=self._dataset)
+        self._domain_generator = DomainGenerator(dataset=self._dataset, rng=_derive_rng())
 
     def generate(self) -> str:
         """

datamimic_ce/domains/common/literal_generators/nobility_title_generator.py

@@ -43,31 +43,43 @@ def __init__(
         self._male_values, self._male_weights = FileUtil.read_wgt_file(file_path=male_file_path)
         self._female_values, self._female_weights = FileUtil.read_wgt_file(file_path=female_file_path)
 
-    def generate(self) -> str | None:
+    def generate(self) -> str:
         """
         Generate random nobility title
             Returns:
                 Optional[str]: Returns a string if successful, otherwise returns None.
         """
         if self._gender in ["male", "female", "other"]:
             return self.generate_with_gender(self._gender)
-        else:
-            return ""
+        return ""
 
-    def generate_with_gender(self, gender: str):
+    def generate_with_gender(self, gender: str) -> str:
         """
         Generate random nobility title
             Returns:
                 Optional[str]: Returns a string if successful, otherwise returns None.
         """
-        if self._rng.random() < self._noble_quota:
-            if gender == "male":
-                return self._male_values and self._rng.choices(self._male_values, self._male_weights, k=1)[0] or None
-            elif gender == "female":
-                return (
-                    self._female_values and self._rng.choices(self._female_values, self._female_weights, k=1)[0] or None
-                )
-            else:
-                """"""
+        if self._rng.random() >= self._noble_quota:
+            return ""
+
+        values: list[str]
+        weights: list[float]
+        if gender == "male":
+            values = list(self._male_values)
+            weights = list(self._male_weights)
+        elif gender == "female":
+            values = list(self._female_values)
+            weights = list(self._female_weights)
         else:
+            # WHY: Merge available titles for non-binary genders instead of returning None when quota triggers.
+            values = list(self._male_values) + list(self._female_values)
+            weights = list(self._male_weights) + list(self._female_weights)
+
+        if not values:
             return ""
+
+        # Align weight vector with values; default to uniform if source data is missing.
+        if not weights or len(weights) != len(values):
+            weights = [1.0 for _ in values]
+
+        return self._rng.choices(values, weights=weights, k=1)[0]

datamimic_ce/domains/common/models/person.py

@@ -49,7 +49,7 @@ def given_name(self) -> str:
         Returns:
             The first name of the person.
         """
-        return self._person_generator.given_name_generator.generate()
+        return self._person_generator.given_name_generator.generate_with_gender(self.gender)
 
     @given_name.setter
     def given_name(self, value: str) -> None:
@@ -195,7 +195,7 @@ def academic_title(self) -> str | None:
     @property_cache
     def nobility_title(self) -> str | None:
         """Get the nobility title of the person."""
-        return self._person_generator.nobility_title_generator.generate()
+        return self._person_generator.nobility_title_generator.generate_with_gender(self.gender)
 
     @property
     @property_cache

datamimic_ce/domains/common/services/person_service.py

@@ -28,6 +28,8 @@ def __init__(
         other_gender_quota: float = 0.0,
         demographic_config: DemographicConfig | None = None,
         rng: Random | None = None,
+        noble_quota: float = 0.001,
+        academic_title_quota: float = 0.5,
     ):
         resolved_config = (demographic_config or DemographicConfig()).with_defaults(
             default_age_min=min_age,
@@ -45,6 +47,9 @@ def __init__(
                 other_gender_quota=other_gender_quota,
                 demographic_config=resolved_config,
                 rng=rng,
+                # Thread descriptor-level overrides for noble/title quotas into the generator for determinism.
+                noble_quota=noble_quota,
+                academic_title_quota=academic_title_quota,
             ),
             Person,
         )

datamimic_ce/domains/domain_data/common/country_ES.csv

@@ -0,0 +1,4 @@
+ES,es_ES,34,6[0-9],España,47500000,comunidad autónoma,provincia,municipio
+AD,ca_AD,376,6[0-9],Andorra,79000,parròquia,,parròquia
+GI,en_GI,350,5[6-9][0-9],Gibraltar,33700,district,,town
+EA,es_EA,34,6[0-9],Ceuta y Melilla,170000,ciudad autónoma,barriada,barrio