Recipes¶

Short, runnable patterns. Every python block runs in CI, in order, in one namespace.

Faker pools¶

Faker is slow per value; RandSpecs.faker_pool draws a pool once and returns a distincts spec. Install the optional extra first: pip install "rand-engine[faker]". It accepts a Faker provider such as name or email, a locale (default en_US), a positive pool_size (default 100), and an optional seed. The seed fixes the materialized pool, then NumPy samples that pool for every row. Invalid pool sizes, unavailable Faker, unsupported locales/providers, provider failures and non-scalar provider values raise RandEngineError.

from rand_engine import DataGenerator, RandSpecs

name_spec = RandSpecs.faker_pool("name", locale="pt_BR", pool_size=500, seed=0)
people = DataGenerator({
    "name": name_spec,
    "email": RandSpecs.faker_pool("email", pool_size=500, seed=0),
}, seed=1).size(2_000).get_df()
assert people["name"].isin(name_spec["kwargs"]["distincts"]).all()

from rand_engine.validators.exceptions import RandEngineError

try:
    RandSpecs.faker_pool("name", pool_size=0)
except RandEngineError:
    pass
else:
    raise AssertionError("expected positive pool_size")

Spec from an Arrow schema¶

RandSpecs.from_schema maps Arrow metadata to a validated RandSpec. Boolean fields become booleans(true_prob=0.5); integer fields become integers(min=0, max=min(100, type maximum), int_type=<Arrow type>); floating fields become floats(0..1, decimals=2); string and large-string fields become uuid4; date fields become dates(2000-01-01..2030-12-31); timezone-naive timestamps become second-resolution dates; string, large-string, date and timestamp fields generate string[pyarrow] columns; and null fields become constant(None), an object column. Nullable fields retain the same recipe: Arrow nullability does not add a RandSpec modifier.

For an override, kwargs merge into the default recipe. An override containing method replaces the whole field recipe. The builder refuses non-schemas, unknown fields, duplicate schema names, non-dict overrides, unsupported Arrow families without a complete method replacement, and any resulting invalid RandSpec with SpecValidationError.

import pyarrow as pa
from rand_engine.validators.exceptions import SpecValidationError

schema = pa.schema([
    ("active", pa.bool_()), ("id", pa.int64()), ("score", pa.float64()),
    ("label", pa.string()), ("note", pa.large_string()), ("day", pa.date32()),
    ("at", pa.timestamp("s")), ("missing", pa.null()),
])
spec = RandSpecs.from_schema(schema, overrides={
    "score": {"kwargs": {"min": 0, "max": 10}},
    "label": {"method": "distincts", "kwargs": {"distincts": ["trial", "paid"]}},
})
df = DataGenerator(spec, seed=1).size(500).get_df()
assert list(spec) == list(schema.names) and df["score"].between(0, 10).all()
assert spec["label"] == {"method": "distincts", "kwargs": {"distincts": ["trial", "paid"]}}

try:
    RandSpecs.from_schema(pa.schema([("amount", pa.decimal128(10, 2))]))
except SpecValidationError:
    pass
else:
    raise AssertionError("expected unsupported Arrow type")

try:
    RandSpecs.from_schema(pa.schema([("id", pa.int32())]), overrides={"missing": {}})
except SpecValidationError:
    pass
else:
    raise AssertionError("expected unknown override")

Ready-made specifications¶

RandSpecs is the top-level alias for CommonRandSpecs: its ten factories work with both DataGenerator and SparkGenerator. AdvancedRandSpecs has ten factories for DataGenerator only; they demonstrate correlated and template methods. Use the factory pages as a compact inventory, then run a returned spec with the generator that family supports.

Cross-compatible specification examples for DataGenerator and SparkGenerator.

All specs use the unified API with date_format parameter.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> df = DataGenerator(RandSpecs.customers(), seed=42).size(100).get_df()
>>> list(df.columns)
['customer_id', 'age', 'city', 'total_spent', 'is_premium', 'registration_date']
>>> len(df)
100

Source code in rand_engine/examples/common_rand_specs.py

class CommonRandSpecs:
    """
    Cross-compatible specification examples for DataGenerator and SparkGenerator.

    All specs use the unified API with date_format parameter.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> df = DataGenerator(RandSpecs.customers(), seed=42).size(100).get_df()
    >>> list(df.columns)
    ['customer_id', 'age', 'city', 'total_spent', 'is_premium', 'registration_date']
    >>> len(df)
    100
    """

    @classmethod
    def faker_pool(
        cls,
        provider: str,
        locale: str = "en_US",
        pool_size: int = 100,
        seed: int | None = None,
    ) -> Dict[str, Any]:
        """
        Build one materialized distincts spec with a local Faker instance.

        Parameters
        ----------
        provider : str
            Faker provider method, such as ``"name"`` or ``"city"``.
        locale : str, default "en_US"
            Faker locale; an unsupported locale raises RandEngineError.
        pool_size : int, default 100
            Number of values to materialize; a positive integer.
        seed : int, optional
            Seed of the Faker instance; the same seed gives the same pool.

        Returns
        -------
        dict
            A ``distincts`` RandSpec whose ``distincts`` list holds the pool.

        Raises
        ------
        RandEngineError
            If ``pool_size`` is not a positive integer, Faker is not installed, the locale
            or provider is unsupported or not callable, the provider fails, or a value is
            not scalar.

        Examples
        --------
        >>> from rand_engine import RandSpecs
        >>> spec = RandSpecs.faker_pool("city", pool_size=5, seed=1)
        >>> spec["method"]
        'distincts'
        >>> len(spec["kwargs"]["distincts"])
        5
        """
        if isinstance(pool_size, bool) or not isinstance(pool_size, int) or pool_size < 1:
            raise RandEngineError("pool_size must be a positive integer")

        try:
            from faker import Faker
        except ImportError as error:
            raise RandEngineError(
                "Faker is an optional dependency; install rand-engine[faker]"
            ) from error

        try:
            faker = Faker(locale)
        except Exception as error:
            raise RandEngineError("locale is not supported by Faker") from error

        try:
            faker.seed_instance(seed)
            factory = getattr(faker, provider)
        except (AttributeError, TypeError, ValueError) as error:
            raise RandEngineError("provider is not supported by Faker") from error
        if not callable(factory):
            raise RandEngineError("provider is not callable")

        try:
            values = [factory() for _ in range(pool_size)]
        except Exception as error:
            raise RandEngineError("provider failed while constructing the pool") from error
        if any(not is_declared_scalar(value) for value in values):
            raise RandEngineError("provider outputs must be scalar values")

        return {"method": "distincts", "kwargs": {"distincts": values}}

    @classmethod
    def from_schema(
        cls,
        schema: pa.Schema,
        overrides: dict[str, dict[str, Any]] | None = None,
    ) -> Dict[str, Any]:
        """
        Build a validated RandSpec from Arrow field metadata only.

        Parameters
        ----------
        schema : pyarrow.Schema
            Arrow schema; each field's type picks a default generation recipe.
        overrides : dict, optional
            Per-field overrides keyed by field name. A ``method`` key replaces the recipe; ``kwargs`` merge into it.

        Returns
        -------
        dict
            RandSpec with one entry per schema field, validated before return.

        Raises
        ------
        SpecValidationError
            If ``schema`` is not a ``pyarrow.Schema``; ``overrides`` or one of its values is not
            a dict, or an override's ``kwargs`` is not a dict; the schema has duplicate fields;
            an override names a missing field; a field type has no default recipe and no
            override with ``method``; or the resulting spec fails validation.

        Examples
        --------
        >>> import pyarrow as pa
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> schema = pa.schema([("id", pa.int32()), ("active", pa.bool_())])
        >>> spec = RandSpecs.from_schema(schema, {"id": {"kwargs": {"max": 9}}})
        >>> {name: column["method"] for name, column in spec.items()}
        {'id': 'integers', 'active': 'booleans'}
        >>> DataGenerator(spec, seed=1).size(5).get_df().shape
        (5, 2)
        """
        if not isinstance(schema, pa.Schema):
            raise SpecValidationError("from_schema requires a pyarrow.Schema")
        if overrides is None:
            overrides = {}
        if not isinstance(overrides, dict):
            raise SpecValidationError("overrides must be a dictionary")
        if any(not isinstance(value, dict) for value in overrides.values()):
            raise SpecValidationError("each field override must be a dictionary")

        names = schema.names
        duplicate_names = sorted({name for name in names if names.count(name) > 1})
        if duplicate_names:
            details = ", ".join(
                f"{name} ({', '.join(str(field.type) for field in schema if field.name == name)})"
                for name in duplicate_names
            )
            raise SpecValidationError(
                f"duplicate schema fields: {details}; rename or remove each duplicate"
            )

        unknown = sorted(set(overrides) - set(names))
        if unknown:
            raise SpecValidationError(
                f"override names missing schema fields: {', '.join(unknown)}"
            )

        copied_overrides = copy.deepcopy(overrides)
        result: Dict[str, Any] = {}
        for field in schema:
            override = copied_overrides.get(field.name, {})
            if "method" in override:
                result[field.name] = override
                continue

            recipe = cls._schema_recipe(field.type)
            if recipe is None:
                raise SpecValidationError(
                    f"field '{field.name}' type '{field.type}' requires a complete override with method"
                )

            column = copy.deepcopy(recipe)
            override_kwargs = override.get("kwargs", {})
            if not isinstance(override_kwargs, dict):
                raise SpecValidationError(
                    f"field '{field.name}' override kwargs must be a dictionary"
                )
            column["kwargs"].update(override_kwargs)
            column.update({key: value for key, value in override.items() if key != "kwargs"})
            result[field.name] = column

        AdvancedValidator.validate_and_raise(result)
        return result

    @staticmethod
    def _schema_recipe(arrow_type: pa.DataType) -> Dict[str, Any] | None:
        if pa.types.is_boolean(arrow_type):
            return {"method": "booleans", "kwargs": {"true_prob": 0.5}}
        if pa.types.is_integer(arrow_type):
            return {
                "method": "integers",
                "kwargs": {
                    "min": 0,
                    "max": min(100, 2 ** arrow_type.bit_width - 1),
                    "int_type": str(arrow_type),
                },
            }
        if pa.types.is_floating(arrow_type):
            return {
                "method": "floats",
                "kwargs": {"min": 0, "max": 1, "decimals": 2},
            }
        if pa.types.is_string(arrow_type) or pa.types.is_large_string(arrow_type):
            return {"method": "uuid4", "kwargs": {}}
        if pa.types.is_date(arrow_type):
            return {
                "method": "dates",
                "kwargs": {
                    "start": "2000-01-01",
                    "end": "2030-12-31",
                    "date_format": "%Y-%m-%d",
                },
            }
        if pa.types.is_timestamp(arrow_type) and arrow_type.tz is None:
            return {
                "method": "dates",
                "kwargs": {
                    "start": "2000-01-01",
                    "end": "2030-12-31",
                    "date_format": "%Y-%m-%d %H:%M:%S",
                },
            }
        if pa.types.is_null(arrow_type):
            return {"method": "constant", "kwargs": {"value": None}}
        return None

    @classmethod
    def customers(cls) -> Dict[str, Any]:
        """
        Return the customer profiles RandSpec (6 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 6 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.customers(), seed=1).size(5).get_df().columns)
        ['customer_id', 'age', 'city', 'total_spent', 'is_premium', 'registration_date']
        """
        return {
            "customer_id": {"method": "uuid4", "kwargs": {}},
            "age": {"method": "integers", "kwargs": {"min": 18, "max": 80, "int_type": "int32"}},
            "city": {
                "method": "distincts",
                "kwargs": {
                    "distincts": ["São Paulo", "Rio de Janeiro", "Belo Horizonte",
                                "Salvador", "Brasília", "Curitiba", "Porto Alegre"]
                }
            },
            "total_spent": {"method": "floats_normal", "kwargs": {"mean": 1500.0, "std": 500.0, "decimals": 2}},
            "is_premium": {"method": "booleans", "kwargs": {"true_prob": 0.15}},
            "registration_date": {
                "method": "dates",
                "kwargs": {"start": "2020-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            }
        }

    @classmethod
    def products(cls) -> Dict[str, Any]:
        """
        Return the product catalog RandSpec (7 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 7 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.products(), seed=1).size(5).get_df().columns)
        ['product_id', 'sku', 'name', 'price', 'stock_quantity', 'category', 'is_active']
        """
        return {
            "product_id": {"method": "uuid4", "kwargs": {}},
            "sku": {"method": "int_zfilled", "kwargs": {"length": 8}},
            "name": {
                "method": "distincts",
                "kwargs": {
                    "distincts": ["Laptop Pro", "Wireless Mouse", "USB-C Cable",
                                "Mechanical Keyboard", "Monitor 27inch", "Webcam HD",
                                "Headset Gaming", "SSD 1TB", "RAM 16GB", "Charger USB"]
                }
            },
            "price": {"method": "floats", "kwargs": {"min": 9.99, "max": 2999.99, "decimals": 2}},
            "stock_quantity": {"method": "integers", "kwargs": {"min": 0, "max": 500, "int_type": "int32"}},
            "category": {
                "method": "distincts_prop",
                "kwargs": {
                    "distincts": {"Electronics": 40, "Accessories": 30, "Computers": 20, "Peripherals": 10}
                }
            },
            "is_active": {"method": "booleans", "kwargs": {"true_prob": 0.85}}
        }

    @classmethod
    def orders(cls) -> Dict[str, Any]:
        """
        Return the e-commerce orders RandSpec (6 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 6 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.orders(), seed=1).size(5).get_df().columns)
        ['order_id', 'customer_id', 'amount', 'order_timestamp', 'status', 'payment_method']
        """
        return {
            "order_id": {"method": "uuid4", "kwargs": {}},
            "customer_id": {"method": "uuid4", "kwargs": {}},
            "amount": {"method": "floats_normal", "kwargs": {"mean": 200.0, "std": 100.0, "decimals": 2}},
            "order_timestamp": {
                "method": "unix_timestamps",
                "kwargs": {"start": "2025-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            },
            "status": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"completed": 70, "pending": 20, "cancelled": 10}}
            },
            "payment_method": {
                "method": "distincts",
                "kwargs": {"distincts": ["credit_card", "debit_card", "pix", "boleto"]}
            }
        }

    @classmethod
    def transactions(cls) -> Dict[str, Any]:
        """
        Return the financial transactions RandSpec (7 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 7 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.transactions(), seed=1).size(5).get_df().columns)
        ['transaction_id', 'account_id', 'amount', 'transaction_type', 'timestamp', 'is_approved', 'fee']
        """
        return {
            "transaction_id": {"method": "uuid4", "kwargs": {}},
            "account_id": {"method": "uuid4", "kwargs": {}},
            "amount": {"method": "floats", "kwargs": {"min": 10.0, "max": 5000.0, "decimals": 2}},
            "transaction_type": {
                "method": "distincts",
                "kwargs": {"distincts": ["deposit", "withdrawal", "transfer", "payment"]}
            },
            "timestamp": {
                "method": "unix_timestamps",
                "kwargs": {"start": "2025-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            },
            "is_approved": {"method": "booleans", "kwargs": {"true_prob": 0.90}},
            "fee": {"method": "floats", "kwargs": {"min": 0.0, "max": 50.0, "decimals": 2}}
        }

    @classmethod
    def employees(cls) -> Dict[str, Any]:
        """
        Return the employee records RandSpec (8 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 8 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.employees(), seed=1).size(5).get_df().columns)
        ['employee_id', 'department', 'position', 'salary', 'hire_date', 'age', 'is_remote', 'performance_score']
        """
        return {
            "employee_id": {"method": "uuid4", "kwargs": {}},
            "department": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"Engineering": 50, "Product": 20, "Data": 15, "Operations": 15}}
            },
            "position": {
                "method": "distincts",
                "kwargs": {
                    "distincts": ["Software Engineer", "Data Analyst", "Product Manager",
                                "DevOps Engineer", "QA Engineer", "Designer"]
                }
            },
            "salary": {"method": "floats_normal", "kwargs": {"mean": 50000.0, "std": 15000.0, "decimals": 2}},
            "hire_date": {
                "method": "dates",
                "kwargs": {"start": "2018-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            },
            "age": {"method": "integers", "kwargs": {"min": 22, "max": 65, "int_type": "int32"}},
            "is_remote": {"method": "booleans", "kwargs": {"true_prob": 0.30}},
            "performance_score": {"method": "floats", "kwargs": {"min": 0.0, "max": 10.0, "decimals": 1}}
        }

    @classmethod
    def sensors(cls) -> Dict[str, Any]:
        """
        Return the IoT sensor readings RandSpec (7 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 7 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.sensors(), seed=1).size(5).get_df().columns)
        ['sensor_id', 'device_name', 'temperature', 'humidity', 'battery_level', 'timestamp', 'is_online']
        """
        return {
            "sensor_id": {"method": "uuid4", "kwargs": {}},
            "device_name": {"method": "int_zfilled", "kwargs": {"length": 6}},
            "temperature": {"method": "floats_normal", "kwargs": {"mean": 25.0, "std": 5.0, "decimals": 1}},
            "humidity": {"method": "floats", "kwargs": {"min": 30.0, "max": 90.0, "decimals": 1}},
            "battery_level": {"method": "integers", "kwargs": {"min": 0, "max": 100, "int_type": "int32"}},
            "timestamp": {
                "method": "unix_timestamps",
                "kwargs": {"start": "2025-10-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            },
            "is_online": {"method": "booleans", "kwargs": {"true_prob": 0.95}}
        }

    @classmethod
    def users(cls) -> Dict[str, Any]:
        """
        Return the application users RandSpec (7 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 7 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.users(), seed=1).size(5).get_df().columns)
        ['user_id', 'username', 'signup_date', 'login_count', 'subscription_plan', 'is_active', 'engagement_score']
        """
        return {
            "user_id": {"method": "uuid4", "kwargs": {}},
            "username": {"method": "int_zfilled", "kwargs": {"length": 10}},
            "signup_date": {
                "method": "dates",
                "kwargs": {"start": "2023-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            },
            "login_count": {"method": "integers", "kwargs": {"min": 0, "max": 1000, "int_type": "int32"}},
            "subscription_plan": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"free": 60, "basic": 25, "premium": 10, "enterprise": 5}}
            },
            "is_active": {"method": "booleans", "kwargs": {"true_prob": 0.80}},
            "engagement_score": {"method": "floats", "kwargs": {"min": 0.0, "max": 100.0, "decimals": 1}}
        }

    @classmethod
    def events(cls) -> Dict[str, Any]:
        """
        Return the system event logs RandSpec (6 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 6 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.events(), seed=1).size(5).get_df().columns)
        ['event_id', 'event_type', 'timestamp', 'duration_ms', 'is_error', 'severity']
        """
        return {
            "event_id": {"method": "uuid4", "kwargs": {}},
            "event_type": {
                "method": "distincts",
                "kwargs": {
                    "distincts": ["user_login", "user_logout", "page_view",
                                "api_call", "database_query", "file_upload"]
                }
            },
            "timestamp": {
                "method": "unix_timestamps",
                "kwargs": {"start": "2025-10-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            },
            "duration_ms": {"method": "integers", "kwargs": {"min": 0, "max": 5000, "int_type": "int32"}},
            "is_error": {"method": "booleans", "kwargs": {"true_prob": 0.10}},
            "severity": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"info": 70, "warning": 20, "error": 8, "critical": 2}}
            }
        }

    @classmethod
    def sales(cls) -> Dict[str, Any]:
        """
        Return the sales records RandSpec (8 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 8 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.sales(), seed=1).size(5).get_df().columns)
        ['transaction_id', 'sale_id', 'product_id', 'amount', 'quantity', 'sales_rep', 'sale_date', 'is_wholesale']
        """
        return {
            "transaction_id": {"method": "uuid4", "kwargs": {}},
            "sale_id": {"method": "int_zfilled", "kwargs": {"length": 10}},
            "product_id": {"method": "int_zfilled", "kwargs": {"length": 8}},
            "amount": {"method": "floats_normal", "kwargs": {"mean": 500.0, "std": 200.0, "decimals": 2}},
            "quantity": {"method": "integers", "kwargs": {"min": 1, "max": 50, "int_type": "int32"}},
            "sales_rep": {
                "method": "distincts",
                "kwargs": {
                    "distincts": ["Alice Smith", "Bob Johnson", "Carol Williams",
                                "David Brown", "Emma Davis", "Frank Miller"]
                }
            },
            "sale_date": {
                "method": "dates",
                "kwargs": {"start": "2025-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            },
            "is_wholesale": {"method": "booleans", "kwargs": {"true_prob": 0.20}}
        }

    @classmethod
    def devices(cls) -> Dict[str, Any]:
        """
        Return the device inventory RandSpec (7 Fields).

        Returns
        -------
        dict
            RandSpec mapping each of the 7 fields to its method and kwargs.

        Examples
        --------
        >>> from rand_engine import DataGenerator, RandSpecs
        >>> list(DataGenerator(RandSpecs.devices(), seed=1).size(5).get_df().columns)
        ['device_id', 'serial_number', 'firmware_version', 'uptime_hours', 'status', 'is_critical', 'last_seen']
        """
        return {
            "device_id": {"method": "uuid4", "kwargs": {}},
            "serial_number": {"method": "int_zfilled", "kwargs": {"length": 12}},
            "firmware_version": {
                "method": "distincts",
                "kwargs": {"distincts": ["v1.0.0", "v1.1.0", "v1.2.0", "v2.0.0", "v2.1.0"]}
            },
            "uptime_hours": {"method": "floats_normal", "kwargs": {"mean": 500.0, "std": 200.0, "decimals": 1}},
            "status": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"online": 80, "offline": 10, "maintenance": 7, "error": 3}}
            },
            "is_critical": {"method": "booleans", "kwargs": {"true_prob": 0.15}},
            "last_seen": {
                "method": "unix_timestamps",
                "kwargs": {"start": "2025-10-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            }
        }

`customers()` `classmethod` ¶

Return the customer profiles RandSpec (6 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 6 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.customers(), seed=1).size(5).get_df().columns)
['customer_id', 'age', 'city', 'total_spent', 'is_premium', 'registration_date']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def customers(cls) -> Dict[str, Any]:
    """
    Return the customer profiles RandSpec (6 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 6 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.customers(), seed=1).size(5).get_df().columns)
    ['customer_id', 'age', 'city', 'total_spent', 'is_premium', 'registration_date']
    """
    return {
        "customer_id": {"method": "uuid4", "kwargs": {}},
        "age": {"method": "integers", "kwargs": {"min": 18, "max": 80, "int_type": "int32"}},
        "city": {
            "method": "distincts",
            "kwargs": {
                "distincts": ["São Paulo", "Rio de Janeiro", "Belo Horizonte",
                            "Salvador", "Brasília", "Curitiba", "Porto Alegre"]
            }
        },
        "total_spent": {"method": "floats_normal", "kwargs": {"mean": 1500.0, "std": 500.0, "decimals": 2}},
        "is_premium": {"method": "booleans", "kwargs": {"true_prob": 0.15}},
        "registration_date": {
            "method": "dates",
            "kwargs": {"start": "2020-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        }
    }

`devices()` `classmethod` ¶

Return the device inventory RandSpec (7 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 7 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.devices(), seed=1).size(5).get_df().columns)
['device_id', 'serial_number', 'firmware_version', 'uptime_hours', 'status', 'is_critical', 'last_seen']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def devices(cls) -> Dict[str, Any]:
    """
    Return the device inventory RandSpec (7 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 7 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.devices(), seed=1).size(5).get_df().columns)
    ['device_id', 'serial_number', 'firmware_version', 'uptime_hours', 'status', 'is_critical', 'last_seen']
    """
    return {
        "device_id": {"method": "uuid4", "kwargs": {}},
        "serial_number": {"method": "int_zfilled", "kwargs": {"length": 12}},
        "firmware_version": {
            "method": "distincts",
            "kwargs": {"distincts": ["v1.0.0", "v1.1.0", "v1.2.0", "v2.0.0", "v2.1.0"]}
        },
        "uptime_hours": {"method": "floats_normal", "kwargs": {"mean": 500.0, "std": 200.0, "decimals": 1}},
        "status": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"online": 80, "offline": 10, "maintenance": 7, "error": 3}}
        },
        "is_critical": {"method": "booleans", "kwargs": {"true_prob": 0.15}},
        "last_seen": {
            "method": "unix_timestamps",
            "kwargs": {"start": "2025-10-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        }
    }

`employees()` `classmethod` ¶

Return the employee records RandSpec (8 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 8 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.employees(), seed=1).size(5).get_df().columns)
['employee_id', 'department', 'position', 'salary', 'hire_date', 'age', 'is_remote', 'performance_score']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def employees(cls) -> Dict[str, Any]:
    """
    Return the employee records RandSpec (8 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 8 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.employees(), seed=1).size(5).get_df().columns)
    ['employee_id', 'department', 'position', 'salary', 'hire_date', 'age', 'is_remote', 'performance_score']
    """
    return {
        "employee_id": {"method": "uuid4", "kwargs": {}},
        "department": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"Engineering": 50, "Product": 20, "Data": 15, "Operations": 15}}
        },
        "position": {
            "method": "distincts",
            "kwargs": {
                "distincts": ["Software Engineer", "Data Analyst", "Product Manager",
                            "DevOps Engineer", "QA Engineer", "Designer"]
            }
        },
        "salary": {"method": "floats_normal", "kwargs": {"mean": 50000.0, "std": 15000.0, "decimals": 2}},
        "hire_date": {
            "method": "dates",
            "kwargs": {"start": "2018-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        },
        "age": {"method": "integers", "kwargs": {"min": 22, "max": 65, "int_type": "int32"}},
        "is_remote": {"method": "booleans", "kwargs": {"true_prob": 0.30}},
        "performance_score": {"method": "floats", "kwargs": {"min": 0.0, "max": 10.0, "decimals": 1}}
    }

`events()` `classmethod` ¶

Return the system event logs RandSpec (6 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 6 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.events(), seed=1).size(5).get_df().columns)
['event_id', 'event_type', 'timestamp', 'duration_ms', 'is_error', 'severity']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def events(cls) -> Dict[str, Any]:
    """
    Return the system event logs RandSpec (6 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 6 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.events(), seed=1).size(5).get_df().columns)
    ['event_id', 'event_type', 'timestamp', 'duration_ms', 'is_error', 'severity']
    """
    return {
        "event_id": {"method": "uuid4", "kwargs": {}},
        "event_type": {
            "method": "distincts",
            "kwargs": {
                "distincts": ["user_login", "user_logout", "page_view",
                            "api_call", "database_query", "file_upload"]
            }
        },
        "timestamp": {
            "method": "unix_timestamps",
            "kwargs": {"start": "2025-10-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        },
        "duration_ms": {"method": "integers", "kwargs": {"min": 0, "max": 5000, "int_type": "int32"}},
        "is_error": {"method": "booleans", "kwargs": {"true_prob": 0.10}},
        "severity": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"info": 70, "warning": 20, "error": 8, "critical": 2}}
        }
    }

`faker_pool(provider, locale='en_US', pool_size=100, seed=None)` `classmethod` ¶

Build one materialized distincts spec with a local Faker instance.

Parameters:

Name	Type	Description	Default
`provider`	`str`	Faker provider method, such as `"name"` or `"city"`.	required
`locale`	`str`	Faker locale; an unsupported locale raises RandEngineError.	`"en_US"`
`pool_size`	`int`	Number of values to materialize; a positive integer.	`100`
`seed`	`int`	Seed of the Faker instance; the same seed gives the same pool.	`None`

Returns:

Type	Description
`dict`	A `distincts` RandSpec whose `distincts` list holds the pool.

Raises:

Type	Description
`RandEngineError`	If `pool_size` is not a positive integer, Faker is not installed, the locale or provider is unsupported or not callable, the provider fails, or a value is not scalar.

Examples:

>>> from rand_engine import RandSpecs
>>> spec = RandSpecs.faker_pool("city", pool_size=5, seed=1)
>>> spec["method"]
'distincts'
>>> len(spec["kwargs"]["distincts"])
5

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def faker_pool(
    cls,
    provider: str,
    locale: str = "en_US",
    pool_size: int = 100,
    seed: int | None = None,
) -> Dict[str, Any]:
    """
    Build one materialized distincts spec with a local Faker instance.

    Parameters
    ----------
    provider : str
        Faker provider method, such as ``"name"`` or ``"city"``.
    locale : str, default "en_US"
        Faker locale; an unsupported locale raises RandEngineError.
    pool_size : int, default 100
        Number of values to materialize; a positive integer.
    seed : int, optional
        Seed of the Faker instance; the same seed gives the same pool.

    Returns
    -------
    dict
        A ``distincts`` RandSpec whose ``distincts`` list holds the pool.

    Raises
    ------
    RandEngineError
        If ``pool_size`` is not a positive integer, Faker is not installed, the locale
        or provider is unsupported or not callable, the provider fails, or a value is
        not scalar.

    Examples
    --------
    >>> from rand_engine import RandSpecs
    >>> spec = RandSpecs.faker_pool("city", pool_size=5, seed=1)
    >>> spec["method"]
    'distincts'
    >>> len(spec["kwargs"]["distincts"])
    5
    """
    if isinstance(pool_size, bool) or not isinstance(pool_size, int) or pool_size < 1:
        raise RandEngineError("pool_size must be a positive integer")

    try:
        from faker import Faker
    except ImportError as error:
        raise RandEngineError(
            "Faker is an optional dependency; install rand-engine[faker]"
        ) from error

    try:
        faker = Faker(locale)
    except Exception as error:
        raise RandEngineError("locale is not supported by Faker") from error

    try:
        faker.seed_instance(seed)
        factory = getattr(faker, provider)
    except (AttributeError, TypeError, ValueError) as error:
        raise RandEngineError("provider is not supported by Faker") from error
    if not callable(factory):
        raise RandEngineError("provider is not callable")

    try:
        values = [factory() for _ in range(pool_size)]
    except Exception as error:
        raise RandEngineError("provider failed while constructing the pool") from error
    if any(not is_declared_scalar(value) for value in values):
        raise RandEngineError("provider outputs must be scalar values")

    return {"method": "distincts", "kwargs": {"distincts": values}}

`from_schema(schema, overrides=None)` `classmethod` ¶

Build a validated RandSpec from Arrow field metadata only.

Parameters:

Name	Type	Description	Default
`schema`	`Schema`	Arrow schema; each field's type picks a default generation recipe.	required
`overrides`	`dict`	Per-field overrides keyed by field name. A `method` key replaces the recipe; `kwargs` merge into it.	`None`

Returns:

Type	Description
`dict`	RandSpec with one entry per schema field, validated before return.

Raises:

Type	Description
`SpecValidationError`	If `schema` is not a `pyarrow.Schema`; `overrides` or one of its values is not a dict, or an override's `kwargs` is not a dict; the schema has duplicate fields; an override names a missing field; a field type has no default recipe and no override with `method`; or the resulting spec fails validation.

Examples:

>>> import pyarrow as pa
>>> from rand_engine import DataGenerator, RandSpecs
>>> schema = pa.schema([("id", pa.int32()), ("active", pa.bool_())])
>>> spec = RandSpecs.from_schema(schema, {"id": {"kwargs": {"max": 9}}})
>>> {name: column["method"] for name, column in spec.items()}
{'id': 'integers', 'active': 'booleans'}
>>> DataGenerator(spec, seed=1).size(5).get_df().shape
(5, 2)

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def from_schema(
    cls,
    schema: pa.Schema,
    overrides: dict[str, dict[str, Any]] | None = None,
) -> Dict[str, Any]:
    """
    Build a validated RandSpec from Arrow field metadata only.

    Parameters
    ----------
    schema : pyarrow.Schema
        Arrow schema; each field's type picks a default generation recipe.
    overrides : dict, optional
        Per-field overrides keyed by field name. A ``method`` key replaces the recipe; ``kwargs`` merge into it.

    Returns
    -------
    dict
        RandSpec with one entry per schema field, validated before return.

    Raises
    ------
    SpecValidationError
        If ``schema`` is not a ``pyarrow.Schema``; ``overrides`` or one of its values is not
        a dict, or an override's ``kwargs`` is not a dict; the schema has duplicate fields;
        an override names a missing field; a field type has no default recipe and no
        override with ``method``; or the resulting spec fails validation.

    Examples
    --------
    >>> import pyarrow as pa
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> schema = pa.schema([("id", pa.int32()), ("active", pa.bool_())])
    >>> spec = RandSpecs.from_schema(schema, {"id": {"kwargs": {"max": 9}}})
    >>> {name: column["method"] for name, column in spec.items()}
    {'id': 'integers', 'active': 'booleans'}
    >>> DataGenerator(spec, seed=1).size(5).get_df().shape
    (5, 2)
    """
    if not isinstance(schema, pa.Schema):
        raise SpecValidationError("from_schema requires a pyarrow.Schema")
    if overrides is None:
        overrides = {}
    if not isinstance(overrides, dict):
        raise SpecValidationError("overrides must be a dictionary")
    if any(not isinstance(value, dict) for value in overrides.values()):
        raise SpecValidationError("each field override must be a dictionary")

    names = schema.names
    duplicate_names = sorted({name for name in names if names.count(name) > 1})
    if duplicate_names:
        details = ", ".join(
            f"{name} ({', '.join(str(field.type) for field in schema if field.name == name)})"
            for name in duplicate_names
        )
        raise SpecValidationError(
            f"duplicate schema fields: {details}; rename or remove each duplicate"
        )

    unknown = sorted(set(overrides) - set(names))
    if unknown:
        raise SpecValidationError(
            f"override names missing schema fields: {', '.join(unknown)}"
        )

    copied_overrides = copy.deepcopy(overrides)
    result: Dict[str, Any] = {}
    for field in schema:
        override = copied_overrides.get(field.name, {})
        if "method" in override:
            result[field.name] = override
            continue

        recipe = cls._schema_recipe(field.type)
        if recipe is None:
            raise SpecValidationError(
                f"field '{field.name}' type '{field.type}' requires a complete override with method"
            )

        column = copy.deepcopy(recipe)
        override_kwargs = override.get("kwargs", {})
        if not isinstance(override_kwargs, dict):
            raise SpecValidationError(
                f"field '{field.name}' override kwargs must be a dictionary"
            )
        column["kwargs"].update(override_kwargs)
        column.update({key: value for key, value in override.items() if key != "kwargs"})
        result[field.name] = column

    AdvancedValidator.validate_and_raise(result)
    return result

`orders()` `classmethod` ¶

Return the e-commerce orders RandSpec (6 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 6 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.orders(), seed=1).size(5).get_df().columns)
['order_id', 'customer_id', 'amount', 'order_timestamp', 'status', 'payment_method']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def orders(cls) -> Dict[str, Any]:
    """
    Return the e-commerce orders RandSpec (6 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 6 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.orders(), seed=1).size(5).get_df().columns)
    ['order_id', 'customer_id', 'amount', 'order_timestamp', 'status', 'payment_method']
    """
    return {
        "order_id": {"method": "uuid4", "kwargs": {}},
        "customer_id": {"method": "uuid4", "kwargs": {}},
        "amount": {"method": "floats_normal", "kwargs": {"mean": 200.0, "std": 100.0, "decimals": 2}},
        "order_timestamp": {
            "method": "unix_timestamps",
            "kwargs": {"start": "2025-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        },
        "status": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"completed": 70, "pending": 20, "cancelled": 10}}
        },
        "payment_method": {
            "method": "distincts",
            "kwargs": {"distincts": ["credit_card", "debit_card", "pix", "boleto"]}
        }
    }

`products()` `classmethod` ¶

Return the product catalog RandSpec (7 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 7 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.products(), seed=1).size(5).get_df().columns)
['product_id', 'sku', 'name', 'price', 'stock_quantity', 'category', 'is_active']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def products(cls) -> Dict[str, Any]:
    """
    Return the product catalog RandSpec (7 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 7 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.products(), seed=1).size(5).get_df().columns)
    ['product_id', 'sku', 'name', 'price', 'stock_quantity', 'category', 'is_active']
    """
    return {
        "product_id": {"method": "uuid4", "kwargs": {}},
        "sku": {"method": "int_zfilled", "kwargs": {"length": 8}},
        "name": {
            "method": "distincts",
            "kwargs": {
                "distincts": ["Laptop Pro", "Wireless Mouse", "USB-C Cable",
                            "Mechanical Keyboard", "Monitor 27inch", "Webcam HD",
                            "Headset Gaming", "SSD 1TB", "RAM 16GB", "Charger USB"]
            }
        },
        "price": {"method": "floats", "kwargs": {"min": 9.99, "max": 2999.99, "decimals": 2}},
        "stock_quantity": {"method": "integers", "kwargs": {"min": 0, "max": 500, "int_type": "int32"}},
        "category": {
            "method": "distincts_prop",
            "kwargs": {
                "distincts": {"Electronics": 40, "Accessories": 30, "Computers": 20, "Peripherals": 10}
            }
        },
        "is_active": {"method": "booleans", "kwargs": {"true_prob": 0.85}}
    }

`sales()` `classmethod` ¶

Return the sales records RandSpec (8 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 8 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.sales(), seed=1).size(5).get_df().columns)
['transaction_id', 'sale_id', 'product_id', 'amount', 'quantity', 'sales_rep', 'sale_date', 'is_wholesale']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def sales(cls) -> Dict[str, Any]:
    """
    Return the sales records RandSpec (8 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 8 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.sales(), seed=1).size(5).get_df().columns)
    ['transaction_id', 'sale_id', 'product_id', 'amount', 'quantity', 'sales_rep', 'sale_date', 'is_wholesale']
    """
    return {
        "transaction_id": {"method": "uuid4", "kwargs": {}},
        "sale_id": {"method": "int_zfilled", "kwargs": {"length": 10}},
        "product_id": {"method": "int_zfilled", "kwargs": {"length": 8}},
        "amount": {"method": "floats_normal", "kwargs": {"mean": 500.0, "std": 200.0, "decimals": 2}},
        "quantity": {"method": "integers", "kwargs": {"min": 1, "max": 50, "int_type": "int32"}},
        "sales_rep": {
            "method": "distincts",
            "kwargs": {
                "distincts": ["Alice Smith", "Bob Johnson", "Carol Williams",
                            "David Brown", "Emma Davis", "Frank Miller"]
            }
        },
        "sale_date": {
            "method": "dates",
            "kwargs": {"start": "2025-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        },
        "is_wholesale": {"method": "booleans", "kwargs": {"true_prob": 0.20}}
    }

`sensors()` `classmethod` ¶

Return the IoT sensor readings RandSpec (7 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 7 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.sensors(), seed=1).size(5).get_df().columns)
['sensor_id', 'device_name', 'temperature', 'humidity', 'battery_level', 'timestamp', 'is_online']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def sensors(cls) -> Dict[str, Any]:
    """
    Return the IoT sensor readings RandSpec (7 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 7 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.sensors(), seed=1).size(5).get_df().columns)
    ['sensor_id', 'device_name', 'temperature', 'humidity', 'battery_level', 'timestamp', 'is_online']
    """
    return {
        "sensor_id": {"method": "uuid4", "kwargs": {}},
        "device_name": {"method": "int_zfilled", "kwargs": {"length": 6}},
        "temperature": {"method": "floats_normal", "kwargs": {"mean": 25.0, "std": 5.0, "decimals": 1}},
        "humidity": {"method": "floats", "kwargs": {"min": 30.0, "max": 90.0, "decimals": 1}},
        "battery_level": {"method": "integers", "kwargs": {"min": 0, "max": 100, "int_type": "int32"}},
        "timestamp": {
            "method": "unix_timestamps",
            "kwargs": {"start": "2025-10-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        },
        "is_online": {"method": "booleans", "kwargs": {"true_prob": 0.95}}
    }

`transactions()` `classmethod` ¶

Return the financial transactions RandSpec (7 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 7 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.transactions(), seed=1).size(5).get_df().columns)
['transaction_id', 'account_id', 'amount', 'transaction_type', 'timestamp', 'is_approved', 'fee']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def transactions(cls) -> Dict[str, Any]:
    """
    Return the financial transactions RandSpec (7 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 7 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.transactions(), seed=1).size(5).get_df().columns)
    ['transaction_id', 'account_id', 'amount', 'transaction_type', 'timestamp', 'is_approved', 'fee']
    """
    return {
        "transaction_id": {"method": "uuid4", "kwargs": {}},
        "account_id": {"method": "uuid4", "kwargs": {}},
        "amount": {"method": "floats", "kwargs": {"min": 10.0, "max": 5000.0, "decimals": 2}},
        "transaction_type": {
            "method": "distincts",
            "kwargs": {"distincts": ["deposit", "withdrawal", "transfer", "payment"]}
        },
        "timestamp": {
            "method": "unix_timestamps",
            "kwargs": {"start": "2025-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        },
        "is_approved": {"method": "booleans", "kwargs": {"true_prob": 0.90}},
        "fee": {"method": "floats", "kwargs": {"min": 0.0, "max": 50.0, "decimals": 2}}
    }

`users()` `classmethod` ¶

Return the application users RandSpec (7 Fields).

Returns:

Type	Description
`dict`	RandSpec mapping each of the 7 fields to its method and kwargs.

Examples:

>>> from rand_engine import DataGenerator, RandSpecs
>>> list(DataGenerator(RandSpecs.users(), seed=1).size(5).get_df().columns)
['user_id', 'username', 'signup_date', 'login_count', 'subscription_plan', 'is_active', 'engagement_score']

Source code in rand_engine/examples/common_rand_specs.py

@classmethod
def users(cls) -> Dict[str, Any]:
    """
    Return the application users RandSpec (7 Fields).

    Returns
    -------
    dict
        RandSpec mapping each of the 7 fields to its method and kwargs.

    Examples
    --------
    >>> from rand_engine import DataGenerator, RandSpecs
    >>> list(DataGenerator(RandSpecs.users(), seed=1).size(5).get_df().columns)
    ['user_id', 'username', 'signup_date', 'login_count', 'subscription_plan', 'is_active', 'engagement_score']
    """
    return {
        "user_id": {"method": "uuid4", "kwargs": {}},
        "username": {"method": "int_zfilled", "kwargs": {"length": 10}},
        "signup_date": {
            "method": "dates",
            "kwargs": {"start": "2023-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        },
        "login_count": {"method": "integers", "kwargs": {"min": 0, "max": 1000, "int_type": "int32"}},
        "subscription_plan": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"free": 60, "basic": 25, "premium": 10, "enterprise": 5}}
        },
        "is_active": {"method": "booleans", "kwargs": {"true_prob": 0.80}},
        "engagement_score": {"method": "floats", "kwargs": {"min": 0.0, "max": 100.0, "decimals": 1}}
    }

Advanced specification examples showcasing PyCore-exclusive methods for DataGenerator.

AdvancedRandSpecs demonstrates sophisticated data generation patterns using methods that are currently only available in DataGenerator (not yet in SparkGenerator). These specs focus on correlated data, complex patterns, and hierarchical relationships.

PyCore-Exclusive Methods:

distincts_map: Generate correlated pairs (e.g., currency-country)
distincts_multi_map: Generate hierarchical correlations (3+ levels)
distincts_map_prop: Weighted correlated pairs with nested probabilities
complex_distincts: Pattern-based generation with template replacement

Available Specs:

products: Product catalog with complex SKU patterns
orders: E-commerce orders with currency-country correlations
employees: Employee hierarchy with department-level-role correlations
devices: IoT devices with status-priority weighted correlations
invoices: Invoice records with pattern-based numbering
shipments: Shipping data with carrier-destination correlations
network_devices: Network infrastructure with IP patterns
vehicles: Vehicle fleet with make-model-year correlations
real_estate: Property listings with location-type correlations
healthcare: Patient records with diagnosis-treatment patterns

Usage Examples:

Basic usage¶

from rand_engine import DataGenerator from rand_engine.examples.advanced_rand_specs import AdvancedRandSpecs

df = DataGenerator(AdvancedRandSpecs.products(), seed=42).size(1000).get_df() print(df.head())

Exploring correlations¶

df = DataGenerator(AdvancedRandSpecs.employees(), seed=42).size(500).get_df() print(df[['department', 'level', 'role']].drop_duplicates())

Pattern-based generation¶

df = DataGenerator(AdvancedRandSpecs.network_devices(), seed=42).size(100).get_df() print(df['ip_address'].unique()[:5]) # Shows generated IPs like "192.168.1.45"

Notes:

These specs work ONLY with DataGenerator (pandas)
For cross-compatible specs, use CommonRandSpecs from common_rand_specs.py
Static class - no instantiation required
Each spec demonstrates 1-2 advanced patterns
Specs range from 5-8 fields for realistic complexity

Source code in rand_engine/examples/advanced_rand_specs.py

class AdvancedRandSpecs:
    """
    Advanced specification examples showcasing PyCore-exclusive methods for DataGenerator.

    AdvancedRandSpecs demonstrates sophisticated data generation patterns using methods
    that are currently only available in DataGenerator (not yet in SparkGenerator).
    These specs focus on correlated data, complex patterns, and hierarchical relationships.

    PyCore-Exclusive Methods:
    ------------------------
    - distincts_map: Generate correlated pairs (e.g., currency-country)
    - distincts_multi_map: Generate hierarchical correlations (3+ levels)
    - distincts_map_prop: Weighted correlated pairs with nested probabilities
    - complex_distincts: Pattern-based generation with template replacement

    Available Specs:
    ---------------
    - products: Product catalog with complex SKU patterns
    - orders: E-commerce orders with currency-country correlations
    - employees: Employee hierarchy with department-level-role correlations
    - devices: IoT devices with status-priority weighted correlations
    - invoices: Invoice records with pattern-based numbering
    - shipments: Shipping data with carrier-destination correlations
    - network_devices: Network infrastructure with IP patterns
    - vehicles: Vehicle fleet with make-model-year correlations
    - real_estate: Property listings with location-type correlations
    - healthcare: Patient records with diagnosis-treatment patterns

    Usage Examples:
    --------------

    # Basic usage
    >>> from rand_engine import DataGenerator
    >>> from rand_engine.examples.advanced_rand_specs import AdvancedRandSpecs
    >>> 
    >>> df = DataGenerator(AdvancedRandSpecs.products(), seed=42).size(1000).get_df()
    >>> print(df.head())

    # Exploring correlations
    >>> df = DataGenerator(AdvancedRandSpecs.employees(), seed=42).size(500).get_df()
    >>> print(df[['department', 'level', 'role']].drop_duplicates())

    # Pattern-based generation
    >>> df = DataGenerator(AdvancedRandSpecs.network_devices(), seed=42).size(100).get_df()
    >>> print(df['ip_address'].unique()[:5])  # Shows generated IPs like "192.168.1.45"

    Notes:
    ------
    - These specs work ONLY with DataGenerator (pandas)
    - For cross-compatible specs, use CommonRandSpecs from common_rand_specs.py
    - Static class - no instantiation required
    - Each spec demonstrates 1-2 advanced patterns
    - Specs range from 5-8 fields for realistic complexity
    """

    @classmethod
    def products(cls) -> Dict[str, Any]:
        """
        Product catalog with complex SKU patterns.

        **Advanced Pattern**: complex_distincts for SKU generation (PRD-XXXX format)

        Fields (6):
        ----------
        - sku: Pattern-based SKU "PRD-1234" using complex_distincts
        - product_name: Random product names
        - category: Weighted categories (Electronics 50%, Clothing 30%, Food 20%)
        - price: Product prices 5-500
        - stock: Inventory levels 0-1000
        - rating: Normally distributed ratings (mean=4.0, std=0.8)

        Key Learning:
        ------------
        - complex_distincts: Pattern "PRD-x" where x is replaced by template (integers 1000-9999)
        - Templates use "kwargs" dict for parameters
        - Useful for generating codes, IDs, serial numbers

        Returns:
        -------
        Dict[str, Any]: Specification for advanced product catalog
        """
        return {
            "sku": {
                "method": "complex_distincts",
                "kwargs": {
                    "pattern": "PRD-x",
                    "replacement": "x",
                    "templates": [
                        {"method": "integers", "kwargs": {"min": 1000, "max": 9999, "int_type": "int32"}}
                    ]
                }
            },
            "product_name": {
                "method": "distincts",
                "kwargs": {
                    "distincts": ["Laptop", "Smartphone", "T-Shirt", "Jeans", "Coffee", "Bread"]
                }
            },
            "category": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"Electronics": 50, "Clothing": 30, "Food": 20}}
            },
            "price": {
                "method": "floats",
                "kwargs": {"min": 5.0, "max": 500.0, "decimals": 2}
            },
            "stock": {
                "method": "integers",
                "kwargs": {"min": 0, "max": 1000, "int_type": "int32"}
            },
            "rating": {
                "method": "floats_normal",
                "kwargs": {"mean": 4.0, "std": 0.8, "decimals": 1}
            }
        }

    @classmethod
    def orders(cls) -> Dict[str, Any]:
        """
        E-commerce orders with currency-country correlations.

        **Advanced Pattern**: distincts_map for currency-country pairs

        Fields (7):
        ----------
        - order_id: UUID4 unique identifiers
        - order_date: Unix timestamps from 2023
        - amount: Order amounts 10-5000
        - status: Order status (Pending 20%, Completed 70%, Cancelled 10%)
        - payment_method: Payment types
        - currency, country: Correlated pairs via distincts_map (splits into 2 columns)

        Key Learning:
        ------------
        - distincts_map: Maps countries to currencies (US→USD, DE→EUR, BR→BRL, JP→JPY)
        - splitable=True: Generates single column then splits into multiple
        - sep=";": Delimiter for splitting
        - cols=[]: Resulting column names after split

        Returns:
        -------
        Dict[str, Any]: Specification for orders with currency-country correlation
        """
        return {
            "order_id": {
                "method": "uuid4",
                "kwargs": {}
            },
            "order_date": {
                "method": "unix_timestamps",
                "kwargs": {"start": "2023-01-01", "end": "2024-12-31", "date_format": "%Y-%m-%d"}
            },
            "amount": {
                "method": "floats",
                "kwargs": {"min": 10.0, "max": 5000.0, "decimals": 2}
            },
            "status": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"Pending": 20, "Completed": 70, "Cancelled": 10}}
            },
            "payment_method": {
                "method": "distincts",
                "kwargs": {"distincts": ["Credit Card", "Debit Card", "PayPal", "Crypto"]}
            },
            "currency_country": {
                "method": "distincts_map",
                "cols": ["country", "currency"],
                "kwargs": {
                    "distincts": {
                        "US": ["USD"],
                        "DE": ["EUR"],
                        "BR": ["BRL"],
                        "JP": ["JPY"]
                    }
                }
            }
        }

    @classmethod
    def employees(cls) -> Dict[str, Any]:
        """
        Employee records with department-level-role hierarchical correlations.

        **Advanced Pattern**: distincts_multi_map for 3-level cartesian product

        Fields (6):
        ----------
        - employee_id: Zero-padded IDs (6 digits)
        - hire_date: Employment start dates
        - salary: Normally distributed salaries (mean=6500, std=2000)
        - department, level, role: 3-level hierarchy via distincts_multi_map
        - is_remote: Remote work flag
        - performance_score: Performance ratings 1-5

        Key Learning:
        ------------
        - distincts_multi_map: Cartesian product of nested lists
        - Engineering→[Junior,Senior]×[Developer,QA] = 4 combinations
        - Sales→[Junior,Senior]×[Rep,Manager] = 4 combinations
        - Generates all valid combinations respecting hierarchy

        Returns:
        -------
        Dict[str, Any]: Specification for employees with hierarchical roles
        """
        return {
            "employee_id": {
                "method": "int_zfilled",
                "kwargs": {"length": 6}
            },
            "hire_date": {
                "method": "dates",
                "kwargs": {"start": "2015-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            },
            "salary": {
                "method": "floats_normal",
                "kwargs": {"mean": 6500.0, "std": 2000.0, "decimals": 2}
            },
            "department_level_role": {
                "method": "distincts_multi_map",
                "cols": ["department", "level", "role"],
                "kwargs": {
                    "distincts": {
                        "Engineering": [
                            ["Junior", "Senior"],
                            ["Developer", "QA"]
                        ],
                        "Sales": [
                            ["Junior", "Senior"],
                            ["Rep", "Manager"]
                        ],
                        "Marketing": [
                            ["Junior", "Mid", "Senior"],
                            ["Analyst", "Coordinator"]
                        ]
                    }
                }
            },
            "is_remote": {
                "method": "booleans",
                "kwargs": {"true_prob": 0.4}
            },
            "performance_score": {
                "method": "floats",
                "kwargs": {"min": 1.0, "max": 5.0, "decimals": 1}
            }
        }

    @classmethod
    def devices(cls) -> Dict[str, Any]:
        """
        IoT devices with status-priority weighted correlations.

        **Advanced Pattern**: distincts_map_prop for weighted correlated pairs

        Fields (7):
        ----------
        - device_id: UUID4 unique identifiers
        - device_type: Device types (Sensor 50%, Gateway 30%, Controller 20%)
        - status, priority: Weighted pairs via distincts_map_prop (splits into 2)
        - temperature: Temperature readings 15-45°C
        - battery_level: Battery percentage 0-100
        - last_ping: Last communication timestamp

        Key Learning:
        ------------
        - distincts_map_prop: Maps status to priority with nested weights
        - Online→[(Low,70%), (Medium,20%), (High,10%)]
        - Offline→[(Low,30%), (Medium,40%), (High,30%)]
        - Allows realistic conditional distributions

        Returns:
        -------
        Dict[str, Any]: Specification for IoT devices with conditional priorities
        """
        return {
            "device_id": {
                "method": "uuid4",
                "kwargs": {}
            },
            "device_type": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"Sensor": 50, "Gateway": 30, "Controller": 20}}
            },
            "status_priority": {
                "method": "distincts_map_prop",
                "cols": ["status", "priority"],
                "kwargs": {
                    "distincts": {
                        "Online": [("Low", 70), ("Medium", 20), ("High", 10)],
                        "Offline": [("Low", 30), ("Medium", 40), ("High", 30)]
                    }
                }
            },
            "temperature": {
                "method": "floats",
                "kwargs": {"min": 15.0, "max": 45.0, "decimals": 1}
            },
            "battery_level": {
                "method": "integers",
                "kwargs": {"min": 0, "max": 100, "int_type": "int16"}
            },
            "last_ping": {
                "method": "unix_timestamps",
                "kwargs": {"start": "2025-10-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
            }
        }

    @classmethod
    def invoices(cls) -> Dict[str, Any]:
        """
        Invoice records with pattern-based invoice numbering.

        **Advanced Pattern**: complex_distincts with multiple templates (INV-YYYY-XXXXX)

        Fields (6):
        ----------
        - invoice_number: Pattern "INV-2023-00001" using 2 templates
        - issue_date: Invoice issue date
        - due_date: Payment due date
        - amount: Invoice amount 100-50000
        - status: Payment status (Paid 60%, Pending 30%, Overdue 10%)
        - tax_rate: Tax percentage 0-25%

        Key Learning:
        ------------
        - complex_distincts: Pattern "INV-x-x" with 2 replacements
        - First x→year (2023 or 2024)
        - Second x→5-digit zero-filled number
        - Templates processed left-to-right in order

        Returns:
        -------
        Dict[str, Any]: Specification for invoices with structured numbering
        """
        return {
            "invoice_number": {
                "method": "complex_distincts",
                "kwargs": {
                    "pattern": "INV-x-x",
                    "replacement": "x",
                    "templates": [
                        {"method": "distincts", "kwargs": {"distincts": ["2023", "2024"]}},
                        {"method": "int_zfilled", "kwargs": {"length": 5}}
                    ]
                }
            },
            "issue_date": {
                "method": "dates",
                "kwargs": {"start": "2023-01-01", "end": "2023-12-31", "date_format": "%Y-%m-%d"}
            },
            "due_date": {
                "method": "dates",
                "kwargs": {"start": "2024-01-01", "end": "2024-12-31", "date_format": "%Y-%m-%d"}
            },
            "amount": {
                "method": "floats",
                "kwargs": {"min": 100.0, "max": 50000.0, "decimals": 2}
            },
            "status": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"Paid": 60, "Pending": 30, "Overdue": 10}}
            },
            "tax_rate": {
                "method": "floats",
                "kwargs": {"min": 0.0, "max": 25.0, "decimals": 2}
            }
        }

    @classmethod
    def shipments(cls) -> Dict[str, Any]:
        """
        Shipping records with carrier-destination correlations.

        **Advanced Pattern**: distincts_map for carrier routing rules

        Fields (7):
        ----------
        - tracking_number: Pattern "TRK-XXXXXXXXXX" (10 digits)
        - carrier, destination: Correlated via distincts_map (FedEx→US/CA only)
        - weight: Package weight 0.1-50 kg
        - status: Shipping status (In Transit 40%, Delivered 50%, Exception 10%)
        - ship_date: Shipment date
        - estimated_delivery: Expected delivery date

        Key Learning:
        ------------
        - distincts_map: Models real-world constraints (carriers serve specific regions)
        - FedEx→[US,CA], DHL→[EU,UK], USPS→[US], UPS→[US,MX]
        - Ensures generated data respects business rules

        Returns:
        -------
        Dict[str, Any]: Specification for shipments with routing rules
        """
        return {
            "tracking_number": {
                "method": "complex_distincts",
                "kwargs": {
                    "pattern": "TRK-x",
                    "replacement": "x",
                    "templates": [
                        {"method": "int_zfilled", "kwargs": {"length": 10}}
                    ]
                }
            },
            "carrier_destination": {
                "method": "distincts_map",
                "cols": ["carrier", "destination"],
                "kwargs": {
                    "distincts": {
                        "FedEx": ["US", "CA"],
                        "DHL": ["EU", "UK"],
                        "USPS": ["US"],
                        "UPS": ["US", "MX"]
                    }
                }
            },
            "weight": {
                "method": "floats",
                "kwargs": {"min": 0.1, "max": 50.0, "decimals": 2}
            },
            "status": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"In Transit": 40, "Delivered": 50, "Exception": 10}}
            },
            "ship_date": {
                "method": "dates",
                "kwargs": {"start": "2024-01-01", "end": "2024-10-01", "date_format": "%Y-%m-%d"}
            },
            "estimated_delivery": {
                "method": "dates",
                "kwargs": {"start": "2024-01-05", "end": "2024-10-18", "date_format": "%Y-%m-%d"}
            }
        }

    @classmethod
    def network_devices(cls) -> Dict[str, Any]:
        """
        Network infrastructure devices with IP address patterns.

        **Advanced Pattern**: complex_distincts for IP address generation (x.x.x.x)

        Fields (7):
        ----------
        - device_id: UUID4 unique identifiers
        - hostname: Zero-padded hostname IDs
        - ip_address: Pattern "192.168.x.x" using 4 templates
        - subnet: Network subnet addresses
        - device_type: Network device types (Router, Switch, Firewall, AP)
        - uptime_hours: Hours since last reboot
        - is_active: Device active status

        Key Learning:
        ------------
        - complex_distincts: Pattern "x.x.x.x" with 4 replacements
        - First two octets: Fixed (192, 168)
        - Last two octets: Random integers 0-255
        - Generates realistic private IP addresses

        Returns:
        -------
        Dict[str, Any]: Specification for network devices with IP patterns
        """
        return {
            "device_id": {
                "method": "uuid4",
                "kwargs": {}
            },
            "hostname": {
                "method": "int_zfilled",
                "kwargs": {"length": 6}
            },
            "ip_address": {
                "method": "complex_distincts",
                "kwargs": {
                    "pattern": "x.x.x.x",
                    "replacement": "x",
                    "templates": [
                        {"method": "distincts", "kwargs": {"distincts": ["192", "172", "10"]}},
                        {"method": "distincts", "kwargs": {"distincts": ["168", "16", "0"]}},
                        {"method": "integers", "kwargs": {"min": 0, "max": 255, "int_type": "int16"}},
                        {"method": "integers", "kwargs": {"min": 1, "max": 254, "int_type": "int16"}}
                    ]
                }
            },
            "subnet": {
                "method": "distincts",
                "kwargs": {"distincts": ["255.255.255.0", "255.255.0.0", "255.0.0.0"]}
            },
            "device_type": {
                "method": "distincts",
                "kwargs": {"distincts": ["Router", "Switch", "Firewall", "Access Point"]}
            },
            "uptime_hours": {
                "method": "floats_normal",
                "kwargs": {"mean": 720.0, "std": 200.0, "decimals": 1}
            },
            "is_active": {
                "method": "booleans",
                "kwargs": {"true_prob": 0.95}
            }
        }

    @classmethod
    def vehicles(cls) -> Dict[str, Any]:
        """
        Vehicle fleet with make-model-year correlations.

        **Advanced Pattern**: distincts_multi_map for vehicle hierarchy

        Fields (8):
        ----------
        - vehicle_id: UUID4 unique identifiers
        - license_plate: Pattern "XXX-XXXX" (letters-numbers)
        - make, model, year: Correlated hierarchy via distincts_multi_map
        - mileage: Odometer reading
        - fuel_type: Fuel types (Gasoline 60%, Diesel 30%, Electric 10%)
        - is_active: Fleet active status

        Key Learning:
        ------------
        - distincts_multi_map: Make→Model→Year hierarchy
        - Toyota→[Corolla,Camry]×[2020,2021,2022]
        - Ford→[F150,Mustang]×[2019,2020,2021]
        - Ensures only valid make-model-year combinations

        Returns:
        -------
        Dict[str, Any]: Specification for vehicle fleet with valid combinations
        """
        return {
            "vehicle_id": {
                "method": "uuid4",
                "kwargs": {}
            },
            "license_plate": {
                "method": "complex_distincts",
                "kwargs": {
                    "pattern": "x-x",
                    "replacement": "x",
                    "templates": [
                        {"method": "distincts", "kwargs": {"distincts": ["ABC", "DEF", "GHI", "JKL"]}},
                        {"method": "int_zfilled", "kwargs": {"length": 4}}
                    ]
                }
            },
            "make_model_year": {
                "method": "distincts_multi_map",
                "cols": ["make", "model", "year"],
                "kwargs": {
                    "distincts": {
                        "Toyota": [
                            ["Corolla", "Camry", "RAV4"],
                            ["2020", "2021", "2022", "2023"]
                        ],
                        "Ford": [
                            ["F150", "Mustang", "Explorer"],
                            ["2019", "2020", "2021", "2022"]
                        ],
                        "Honda": [
                            ["Civic", "Accord", "CR-V"],
                            ["2020", "2021", "2022"]
                        ]
                    }
                }
            },
            "mileage": {
                "method": "integers",
                "kwargs": {"min": 0, "max": 200000, "int_type": "int32"}
            },
            "fuel_type": {
                "method": "distincts_prop",
                "kwargs": {"distincts": {"Gasoline": 60, "Diesel": 30, "Electric": 10}}
            },
            "is_active": {
                "method": "booleans",
                "kwargs": {"true_prob": 0.9}
            }
        }

    @classmethod
    def real_estate(cls) -> Dict[str, Any]:
        """
        Property listings with location-type correlations.

        **Advanced Pattern**: distincts_map_prop for location-based pricing

        Fields (8):
        ----------
        - property_id: UUID4 unique identifiers
        - address: Property street addresses
        - city, type: Correlated via distincts_map (city determines available types)
        - bedrooms: Number of bedrooms 1-5
        - bathrooms: Number of bathrooms 1-4
        - price: Property price (normal distribution by type)
        - is_available: Availability status

        Key Learning:
        ------------
        - distincts_map: City→PropertyTypes mapping
        - Manhattan→[Apartment,Condo], Brooklyn→[Apartment,Townhouse]
        - Models geographic constraints on property types

        Returns:
        -------
        Dict[str, Any]: Specification for real estate with location constraints
        """
        return {
            "property_id": {
                "method": "uuid4",
                "kwargs": {}
            },
            "address": {
                "method": "int_zfilled",
                "kwargs": {"length": 4}
            },
            "city_type": {
                "method": "distincts_map",
                "cols": ["city", "type"],
                "kwargs": {
                    "distincts": {
                        "Manhattan": ["Apartment", "Condo"],
                        "Brooklyn": ["Apartment", "Townhouse"],
                        "Queens": ["House", "Apartment"],
                        "Bronx": ["House", "Apartment"]
                    }
                }
            },
            "bedrooms": {
                "method": "integers",
                "kwargs": {"min": 1, "max": 5, "int_type": "int16"}
            },
            "bathrooms": {
                "method": "integers",
                "kwargs": {"min": 1, "max": 4, "int_type": "int16"}
            },
            "square_feet": {
                "method": "integers",
                "kwargs": {"min": 500, "max": 5000, "int_type": "int32"}
            },
            "price": {
                "method": "floats_normal",
                "kwargs": {"mean": 500000.0, "std": 150000.0, "decimals": 2}
            },
            "is_available": {
                "method": "booleans",
                "kwargs": {"true_prob": 0.3}
            }
        }

    @classmethod
    def healthcare(cls) -> Dict[str, Any]:
        """
        Patient records with diagnosis-treatment patterns.

        **Advanced Pattern**: distincts_map_prop for diagnosis-treatment correlations

        Fields (7):
        ----------
        - patient_id: UUID4 unique identifiers
        - age: Patient age 0-100
        - diagnosis, treatment: Correlated via distincts_map_prop (weighted by diagnosis)
        - admission_date: Hospital admission date
        - discharge_date: Hospital discharge date
        - bill_amount: Medical bill amount
        - is_emergency: Emergency admission flag

        Key Learning:
        ------------
        - distincts_map_prop: Diagnosis→Treatment with probabilities
        - Flu→[(Medication,80%), (Hospitalization,20%)]
        - Fracture→[(Surgery,60%), (Cast,40%)]
        - Models medical decision patterns

        Returns:
        -------
        Dict[str, Any]: Specification for healthcare with realistic treatment paths
        """
        return {
            "patient_id": {
                "method": "uuid4",
                "kwargs": {}
            },
            "age": {
                "method": "integers",
                "kwargs": {"min": 0, "max": 100, "int_type": "int16"}
            },
            "diagnosis_treatment": {
                "method": "distincts_map_prop",
                "cols": ["diagnosis", "treatment"],
                "kwargs": {
                    "distincts": {
                        "Flu": [("Medication", 80), ("Hospitalization", 20)],
                        "Fracture": [("Surgery", 60), ("Cast", 40)],
                        "Hypertension": [("Medication", 90), ("Lifestyle", 10)],
                        "Diabetes": [("Insulin", 50), ("Medication", 40), ("Diet", 10)]
                    }
                }
            },
            "admission_date": {
                "method": "dates",
                "kwargs": {"start": "2024-01-01", "end": "2024-10-01", "date_format": "%Y-%m-%d"}
            },
            "discharge_date": {
                "method": "dates",
                "kwargs": {"start": "2024-01-05", "end": "2024-10-30", "date_format": "%Y-%m-%d"}
            },
            "bill_amount": {
                "method": "floats_normal",
                "kwargs": {"mean": 5000.0, "std": 2000.0, "decimals": 2}
            },
            "is_emergency": {
                "method": "booleans",
                "kwargs": {"true_prob": 0.25}
            }
        }

`devices()` `classmethod` ¶

IoT devices with status-priority weighted correlations.

Advanced Pattern: distincts_map_prop for weighted correlated pairs

Fields (7):

device_id: UUID4 unique identifiers
device_type: Device types (Sensor 50%, Gateway 30%, Controller 20%)
status, priority: Weighted pairs via distincts_map_prop (splits into 2)
temperature: Temperature readings 15-45°C
battery_level: Battery percentage 0-100
last_ping: Last communication timestamp

Key Learning:

distincts_map_prop: Maps status to priority with nested weights
Online→[(Low,70%), (Medium,20%), (High,10%)]
Offline→[(Low,30%), (Medium,40%), (High,30%)]
Allows realistic conditional distributions

Returns:

Dict[str, Any]: Specification for IoT devices with conditional priorities

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def devices(cls) -> Dict[str, Any]:
    """
    IoT devices with status-priority weighted correlations.

    **Advanced Pattern**: distincts_map_prop for weighted correlated pairs

    Fields (7):
    ----------
    - device_id: UUID4 unique identifiers
    - device_type: Device types (Sensor 50%, Gateway 30%, Controller 20%)
    - status, priority: Weighted pairs via distincts_map_prop (splits into 2)
    - temperature: Temperature readings 15-45°C
    - battery_level: Battery percentage 0-100
    - last_ping: Last communication timestamp

    Key Learning:
    ------------
    - distincts_map_prop: Maps status to priority with nested weights
    - Online→[(Low,70%), (Medium,20%), (High,10%)]
    - Offline→[(Low,30%), (Medium,40%), (High,30%)]
    - Allows realistic conditional distributions

    Returns:
    -------
    Dict[str, Any]: Specification for IoT devices with conditional priorities
    """
    return {
        "device_id": {
            "method": "uuid4",
            "kwargs": {}
        },
        "device_type": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"Sensor": 50, "Gateway": 30, "Controller": 20}}
        },
        "status_priority": {
            "method": "distincts_map_prop",
            "cols": ["status", "priority"],
            "kwargs": {
                "distincts": {
                    "Online": [("Low", 70), ("Medium", 20), ("High", 10)],
                    "Offline": [("Low", 30), ("Medium", 40), ("High", 30)]
                }
            }
        },
        "temperature": {
            "method": "floats",
            "kwargs": {"min": 15.0, "max": 45.0, "decimals": 1}
        },
        "battery_level": {
            "method": "integers",
            "kwargs": {"min": 0, "max": 100, "int_type": "int16"}
        },
        "last_ping": {
            "method": "unix_timestamps",
            "kwargs": {"start": "2025-10-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        }
    }

`employees()` `classmethod` ¶

Employee records with department-level-role hierarchical correlations.

Advanced Pattern: distincts_multi_map for 3-level cartesian product

Fields (6):

employee_id: Zero-padded IDs (6 digits)
hire_date: Employment start dates
salary: Normally distributed salaries (mean=6500, std=2000)
department, level, role: 3-level hierarchy via distincts_multi_map
is_remote: Remote work flag
performance_score: Performance ratings 1-5

Key Learning:

distincts_multi_map: Cartesian product of nested lists
Engineering→[Junior,Senior]×[Developer,QA] = 4 combinations
Sales→[Junior,Senior]×[Rep,Manager] = 4 combinations
Generates all valid combinations respecting hierarchy

Returns:

Dict[str, Any]: Specification for employees with hierarchical roles

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def employees(cls) -> Dict[str, Any]:
    """
    Employee records with department-level-role hierarchical correlations.

    **Advanced Pattern**: distincts_multi_map for 3-level cartesian product

    Fields (6):
    ----------
    - employee_id: Zero-padded IDs (6 digits)
    - hire_date: Employment start dates
    - salary: Normally distributed salaries (mean=6500, std=2000)
    - department, level, role: 3-level hierarchy via distincts_multi_map
    - is_remote: Remote work flag
    - performance_score: Performance ratings 1-5

    Key Learning:
    ------------
    - distincts_multi_map: Cartesian product of nested lists
    - Engineering→[Junior,Senior]×[Developer,QA] = 4 combinations
    - Sales→[Junior,Senior]×[Rep,Manager] = 4 combinations
    - Generates all valid combinations respecting hierarchy

    Returns:
    -------
    Dict[str, Any]: Specification for employees with hierarchical roles
    """
    return {
        "employee_id": {
            "method": "int_zfilled",
            "kwargs": {"length": 6}
        },
        "hire_date": {
            "method": "dates",
            "kwargs": {"start": "2015-01-01", "end": "2025-10-30", "date_format": "%Y-%m-%d"}
        },
        "salary": {
            "method": "floats_normal",
            "kwargs": {"mean": 6500.0, "std": 2000.0, "decimals": 2}
        },
        "department_level_role": {
            "method": "distincts_multi_map",
            "cols": ["department", "level", "role"],
            "kwargs": {
                "distincts": {
                    "Engineering": [
                        ["Junior", "Senior"],
                        ["Developer", "QA"]
                    ],
                    "Sales": [
                        ["Junior", "Senior"],
                        ["Rep", "Manager"]
                    ],
                    "Marketing": [
                        ["Junior", "Mid", "Senior"],
                        ["Analyst", "Coordinator"]
                    ]
                }
            }
        },
        "is_remote": {
            "method": "booleans",
            "kwargs": {"true_prob": 0.4}
        },
        "performance_score": {
            "method": "floats",
            "kwargs": {"min": 1.0, "max": 5.0, "decimals": 1}
        }
    }

`healthcare()` `classmethod` ¶

Patient records with diagnosis-treatment patterns.

Advanced Pattern: distincts_map_prop for diagnosis-treatment correlations

Fields (7):

patient_id: UUID4 unique identifiers
age: Patient age 0-100
diagnosis, treatment: Correlated via distincts_map_prop (weighted by diagnosis)
admission_date: Hospital admission date
discharge_date: Hospital discharge date
bill_amount: Medical bill amount
is_emergency: Emergency admission flag

Key Learning:

distincts_map_prop: Diagnosis→Treatment with probabilities
Flu→[(Medication,80%), (Hospitalization,20%)]
Fracture→[(Surgery,60%), (Cast,40%)]
Models medical decision patterns

Returns:

Dict[str, Any]: Specification for healthcare with realistic treatment paths

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def healthcare(cls) -> Dict[str, Any]:
    """
    Patient records with diagnosis-treatment patterns.

    **Advanced Pattern**: distincts_map_prop for diagnosis-treatment correlations

    Fields (7):
    ----------
    - patient_id: UUID4 unique identifiers
    - age: Patient age 0-100
    - diagnosis, treatment: Correlated via distincts_map_prop (weighted by diagnosis)
    - admission_date: Hospital admission date
    - discharge_date: Hospital discharge date
    - bill_amount: Medical bill amount
    - is_emergency: Emergency admission flag

    Key Learning:
    ------------
    - distincts_map_prop: Diagnosis→Treatment with probabilities
    - Flu→[(Medication,80%), (Hospitalization,20%)]
    - Fracture→[(Surgery,60%), (Cast,40%)]
    - Models medical decision patterns

    Returns:
    -------
    Dict[str, Any]: Specification for healthcare with realistic treatment paths
    """
    return {
        "patient_id": {
            "method": "uuid4",
            "kwargs": {}
        },
        "age": {
            "method": "integers",
            "kwargs": {"min": 0, "max": 100, "int_type": "int16"}
        },
        "diagnosis_treatment": {
            "method": "distincts_map_prop",
            "cols": ["diagnosis", "treatment"],
            "kwargs": {
                "distincts": {
                    "Flu": [("Medication", 80), ("Hospitalization", 20)],
                    "Fracture": [("Surgery", 60), ("Cast", 40)],
                    "Hypertension": [("Medication", 90), ("Lifestyle", 10)],
                    "Diabetes": [("Insulin", 50), ("Medication", 40), ("Diet", 10)]
                }
            }
        },
        "admission_date": {
            "method": "dates",
            "kwargs": {"start": "2024-01-01", "end": "2024-10-01", "date_format": "%Y-%m-%d"}
        },
        "discharge_date": {
            "method": "dates",
            "kwargs": {"start": "2024-01-05", "end": "2024-10-30", "date_format": "%Y-%m-%d"}
        },
        "bill_amount": {
            "method": "floats_normal",
            "kwargs": {"mean": 5000.0, "std": 2000.0, "decimals": 2}
        },
        "is_emergency": {
            "method": "booleans",
            "kwargs": {"true_prob": 0.25}
        }
    }

`invoices()` `classmethod` ¶

Invoice records with pattern-based invoice numbering.

Advanced Pattern: complex_distincts with multiple templates (INV-YYYY-XXXXX)

Fields (6):

invoice_number: Pattern "INV-2023-00001" using 2 templates
issue_date: Invoice issue date
due_date: Payment due date
amount: Invoice amount 100-50000
status: Payment status (Paid 60%, Pending 30%, Overdue 10%)
tax_rate: Tax percentage 0-25%

Key Learning:

complex_distincts: Pattern "INV-x-x" with 2 replacements
First x→year (2023 or 2024)
Second x→5-digit zero-filled number
Templates processed left-to-right in order

Returns:

Dict[str, Any]: Specification for invoices with structured numbering

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def invoices(cls) -> Dict[str, Any]:
    """
    Invoice records with pattern-based invoice numbering.

    **Advanced Pattern**: complex_distincts with multiple templates (INV-YYYY-XXXXX)

    Fields (6):
    ----------
    - invoice_number: Pattern "INV-2023-00001" using 2 templates
    - issue_date: Invoice issue date
    - due_date: Payment due date
    - amount: Invoice amount 100-50000
    - status: Payment status (Paid 60%, Pending 30%, Overdue 10%)
    - tax_rate: Tax percentage 0-25%

    Key Learning:
    ------------
    - complex_distincts: Pattern "INV-x-x" with 2 replacements
    - First x→year (2023 or 2024)
    - Second x→5-digit zero-filled number
    - Templates processed left-to-right in order

    Returns:
    -------
    Dict[str, Any]: Specification for invoices with structured numbering
    """
    return {
        "invoice_number": {
            "method": "complex_distincts",
            "kwargs": {
                "pattern": "INV-x-x",
                "replacement": "x",
                "templates": [
                    {"method": "distincts", "kwargs": {"distincts": ["2023", "2024"]}},
                    {"method": "int_zfilled", "kwargs": {"length": 5}}
                ]
            }
        },
        "issue_date": {
            "method": "dates",
            "kwargs": {"start": "2023-01-01", "end": "2023-12-31", "date_format": "%Y-%m-%d"}
        },
        "due_date": {
            "method": "dates",
            "kwargs": {"start": "2024-01-01", "end": "2024-12-31", "date_format": "%Y-%m-%d"}
        },
        "amount": {
            "method": "floats",
            "kwargs": {"min": 100.0, "max": 50000.0, "decimals": 2}
        },
        "status": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"Paid": 60, "Pending": 30, "Overdue": 10}}
        },
        "tax_rate": {
            "method": "floats",
            "kwargs": {"min": 0.0, "max": 25.0, "decimals": 2}
        }
    }

`network_devices()` `classmethod` ¶

Network infrastructure devices with IP address patterns.

Advanced Pattern: complex_distincts for IP address generation (x.x.x.x)

Fields (7):

device_id: UUID4 unique identifiers
hostname: Zero-padded hostname IDs
ip_address: Pattern "192.168.x.x" using 4 templates
subnet: Network subnet addresses
device_type: Network device types (Router, Switch, Firewall, AP)
uptime_hours: Hours since last reboot
is_active: Device active status

Key Learning:

complex_distincts: Pattern "x.x.x.x" with 4 replacements
First two octets: Fixed (192, 168)
Last two octets: Random integers 0-255
Generates realistic private IP addresses

Returns:

Dict[str, Any]: Specification for network devices with IP patterns

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def network_devices(cls) -> Dict[str, Any]:
    """
    Network infrastructure devices with IP address patterns.

    **Advanced Pattern**: complex_distincts for IP address generation (x.x.x.x)

    Fields (7):
    ----------
    - device_id: UUID4 unique identifiers
    - hostname: Zero-padded hostname IDs
    - ip_address: Pattern "192.168.x.x" using 4 templates
    - subnet: Network subnet addresses
    - device_type: Network device types (Router, Switch, Firewall, AP)
    - uptime_hours: Hours since last reboot
    - is_active: Device active status

    Key Learning:
    ------------
    - complex_distincts: Pattern "x.x.x.x" with 4 replacements
    - First two octets: Fixed (192, 168)
    - Last two octets: Random integers 0-255
    - Generates realistic private IP addresses

    Returns:
    -------
    Dict[str, Any]: Specification for network devices with IP patterns
    """
    return {
        "device_id": {
            "method": "uuid4",
            "kwargs": {}
        },
        "hostname": {
            "method": "int_zfilled",
            "kwargs": {"length": 6}
        },
        "ip_address": {
            "method": "complex_distincts",
            "kwargs": {
                "pattern": "x.x.x.x",
                "replacement": "x",
                "templates": [
                    {"method": "distincts", "kwargs": {"distincts": ["192", "172", "10"]}},
                    {"method": "distincts", "kwargs": {"distincts": ["168", "16", "0"]}},
                    {"method": "integers", "kwargs": {"min": 0, "max": 255, "int_type": "int16"}},
                    {"method": "integers", "kwargs": {"min": 1, "max": 254, "int_type": "int16"}}
                ]
            }
        },
        "subnet": {
            "method": "distincts",
            "kwargs": {"distincts": ["255.255.255.0", "255.255.0.0", "255.0.0.0"]}
        },
        "device_type": {
            "method": "distincts",
            "kwargs": {"distincts": ["Router", "Switch", "Firewall", "Access Point"]}
        },
        "uptime_hours": {
            "method": "floats_normal",
            "kwargs": {"mean": 720.0, "std": 200.0, "decimals": 1}
        },
        "is_active": {
            "method": "booleans",
            "kwargs": {"true_prob": 0.95}
        }
    }

`orders()` `classmethod` ¶

E-commerce orders with currency-country correlations.

Advanced Pattern: distincts_map for currency-country pairs

Fields (7):

order_id: UUID4 unique identifiers
order_date: Unix timestamps from 2023
amount: Order amounts 10-5000
status: Order status (Pending 20%, Completed 70%, Cancelled 10%)
payment_method: Payment types
currency, country: Correlated pairs via distincts_map (splits into 2 columns)

Key Learning:

distincts_map: Maps countries to currencies (US→USD, DE→EUR, BR→BRL, JP→JPY)
splitable=True: Generates single column then splits into multiple
sep=";": Delimiter for splitting
cols=[]: Resulting column names after split

Returns:

Dict[str, Any]: Specification for orders with currency-country correlation

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def orders(cls) -> Dict[str, Any]:
    """
    E-commerce orders with currency-country correlations.

    **Advanced Pattern**: distincts_map for currency-country pairs

    Fields (7):
    ----------
    - order_id: UUID4 unique identifiers
    - order_date: Unix timestamps from 2023
    - amount: Order amounts 10-5000
    - status: Order status (Pending 20%, Completed 70%, Cancelled 10%)
    - payment_method: Payment types
    - currency, country: Correlated pairs via distincts_map (splits into 2 columns)

    Key Learning:
    ------------
    - distincts_map: Maps countries to currencies (US→USD, DE→EUR, BR→BRL, JP→JPY)
    - splitable=True: Generates single column then splits into multiple
    - sep=";": Delimiter for splitting
    - cols=[]: Resulting column names after split

    Returns:
    -------
    Dict[str, Any]: Specification for orders with currency-country correlation
    """
    return {
        "order_id": {
            "method": "uuid4",
            "kwargs": {}
        },
        "order_date": {
            "method": "unix_timestamps",
            "kwargs": {"start": "2023-01-01", "end": "2024-12-31", "date_format": "%Y-%m-%d"}
        },
        "amount": {
            "method": "floats",
            "kwargs": {"min": 10.0, "max": 5000.0, "decimals": 2}
        },
        "status": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"Pending": 20, "Completed": 70, "Cancelled": 10}}
        },
        "payment_method": {
            "method": "distincts",
            "kwargs": {"distincts": ["Credit Card", "Debit Card", "PayPal", "Crypto"]}
        },
        "currency_country": {
            "method": "distincts_map",
            "cols": ["country", "currency"],
            "kwargs": {
                "distincts": {
                    "US": ["USD"],
                    "DE": ["EUR"],
                    "BR": ["BRL"],
                    "JP": ["JPY"]
                }
            }
        }
    }

`products()` `classmethod` ¶

Product catalog with complex SKU patterns.

Advanced Pattern: complex_distincts for SKU generation (PRD-XXXX format)

Fields (6):

sku: Pattern-based SKU "PRD-1234" using complex_distincts
product_name: Random product names
category: Weighted categories (Electronics 50%, Clothing 30%, Food 20%)
price: Product prices 5-500
stock: Inventory levels 0-1000
rating: Normally distributed ratings (mean=4.0, std=0.8)

Key Learning:

complex_distincts: Pattern "PRD-x" where x is replaced by template (integers 1000-9999)
Templates use "kwargs" dict for parameters
Useful for generating codes, IDs, serial numbers

Returns:

Dict[str, Any]: Specification for advanced product catalog

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def products(cls) -> Dict[str, Any]:
    """
    Product catalog with complex SKU patterns.

    **Advanced Pattern**: complex_distincts for SKU generation (PRD-XXXX format)

    Fields (6):
    ----------
    - sku: Pattern-based SKU "PRD-1234" using complex_distincts
    - product_name: Random product names
    - category: Weighted categories (Electronics 50%, Clothing 30%, Food 20%)
    - price: Product prices 5-500
    - stock: Inventory levels 0-1000
    - rating: Normally distributed ratings (mean=4.0, std=0.8)

    Key Learning:
    ------------
    - complex_distincts: Pattern "PRD-x" where x is replaced by template (integers 1000-9999)
    - Templates use "kwargs" dict for parameters
    - Useful for generating codes, IDs, serial numbers

    Returns:
    -------
    Dict[str, Any]: Specification for advanced product catalog
    """
    return {
        "sku": {
            "method": "complex_distincts",
            "kwargs": {
                "pattern": "PRD-x",
                "replacement": "x",
                "templates": [
                    {"method": "integers", "kwargs": {"min": 1000, "max": 9999, "int_type": "int32"}}
                ]
            }
        },
        "product_name": {
            "method": "distincts",
            "kwargs": {
                "distincts": ["Laptop", "Smartphone", "T-Shirt", "Jeans", "Coffee", "Bread"]
            }
        },
        "category": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"Electronics": 50, "Clothing": 30, "Food": 20}}
        },
        "price": {
            "method": "floats",
            "kwargs": {"min": 5.0, "max": 500.0, "decimals": 2}
        },
        "stock": {
            "method": "integers",
            "kwargs": {"min": 0, "max": 1000, "int_type": "int32"}
        },
        "rating": {
            "method": "floats_normal",
            "kwargs": {"mean": 4.0, "std": 0.8, "decimals": 1}
        }
    }

`real_estate()` `classmethod` ¶

Property listings with location-type correlations.

Advanced Pattern: distincts_map_prop for location-based pricing

Fields (8):

property_id: UUID4 unique identifiers
address: Property street addresses
city, type: Correlated via distincts_map (city determines available types)
bedrooms: Number of bedrooms 1-5
bathrooms: Number of bathrooms 1-4
price: Property price (normal distribution by type)
is_available: Availability status

Key Learning:

distincts_map: City→PropertyTypes mapping
Manhattan→[Apartment,Condo], Brooklyn→[Apartment,Townhouse]
Models geographic constraints on property types

Returns:

Dict[str, Any]: Specification for real estate with location constraints

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def real_estate(cls) -> Dict[str, Any]:
    """
    Property listings with location-type correlations.

    **Advanced Pattern**: distincts_map_prop for location-based pricing

    Fields (8):
    ----------
    - property_id: UUID4 unique identifiers
    - address: Property street addresses
    - city, type: Correlated via distincts_map (city determines available types)
    - bedrooms: Number of bedrooms 1-5
    - bathrooms: Number of bathrooms 1-4
    - price: Property price (normal distribution by type)
    - is_available: Availability status

    Key Learning:
    ------------
    - distincts_map: City→PropertyTypes mapping
    - Manhattan→[Apartment,Condo], Brooklyn→[Apartment,Townhouse]
    - Models geographic constraints on property types

    Returns:
    -------
    Dict[str, Any]: Specification for real estate with location constraints
    """
    return {
        "property_id": {
            "method": "uuid4",
            "kwargs": {}
        },
        "address": {
            "method": "int_zfilled",
            "kwargs": {"length": 4}
        },
        "city_type": {
            "method": "distincts_map",
            "cols": ["city", "type"],
            "kwargs": {
                "distincts": {
                    "Manhattan": ["Apartment", "Condo"],
                    "Brooklyn": ["Apartment", "Townhouse"],
                    "Queens": ["House", "Apartment"],
                    "Bronx": ["House", "Apartment"]
                }
            }
        },
        "bedrooms": {
            "method": "integers",
            "kwargs": {"min": 1, "max": 5, "int_type": "int16"}
        },
        "bathrooms": {
            "method": "integers",
            "kwargs": {"min": 1, "max": 4, "int_type": "int16"}
        },
        "square_feet": {
            "method": "integers",
            "kwargs": {"min": 500, "max": 5000, "int_type": "int32"}
        },
        "price": {
            "method": "floats_normal",
            "kwargs": {"mean": 500000.0, "std": 150000.0, "decimals": 2}
        },
        "is_available": {
            "method": "booleans",
            "kwargs": {"true_prob": 0.3}
        }
    }

`shipments()` `classmethod` ¶

Shipping records with carrier-destination correlations.

Advanced Pattern: distincts_map for carrier routing rules

Fields (7):

tracking_number: Pattern "TRK-XXXXXXXXXX" (10 digits)
carrier, destination: Correlated via distincts_map (FedEx→US/CA only)
weight: Package weight 0.1-50 kg
status: Shipping status (In Transit 40%, Delivered 50%, Exception 10%)
ship_date: Shipment date
estimated_delivery: Expected delivery date

Key Learning:

distincts_map: Models real-world constraints (carriers serve specific regions)
FedEx→[US,CA], DHL→[EU,UK], USPS→[US], UPS→[US,MX]
Ensures generated data respects business rules

Returns:

Dict[str, Any]: Specification for shipments with routing rules

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def shipments(cls) -> Dict[str, Any]:
    """
    Shipping records with carrier-destination correlations.

    **Advanced Pattern**: distincts_map for carrier routing rules

    Fields (7):
    ----------
    - tracking_number: Pattern "TRK-XXXXXXXXXX" (10 digits)
    - carrier, destination: Correlated via distincts_map (FedEx→US/CA only)
    - weight: Package weight 0.1-50 kg
    - status: Shipping status (In Transit 40%, Delivered 50%, Exception 10%)
    - ship_date: Shipment date
    - estimated_delivery: Expected delivery date

    Key Learning:
    ------------
    - distincts_map: Models real-world constraints (carriers serve specific regions)
    - FedEx→[US,CA], DHL→[EU,UK], USPS→[US], UPS→[US,MX]
    - Ensures generated data respects business rules

    Returns:
    -------
    Dict[str, Any]: Specification for shipments with routing rules
    """
    return {
        "tracking_number": {
            "method": "complex_distincts",
            "kwargs": {
                "pattern": "TRK-x",
                "replacement": "x",
                "templates": [
                    {"method": "int_zfilled", "kwargs": {"length": 10}}
                ]
            }
        },
        "carrier_destination": {
            "method": "distincts_map",
            "cols": ["carrier", "destination"],
            "kwargs": {
                "distincts": {
                    "FedEx": ["US", "CA"],
                    "DHL": ["EU", "UK"],
                    "USPS": ["US"],
                    "UPS": ["US", "MX"]
                }
            }
        },
        "weight": {
            "method": "floats",
            "kwargs": {"min": 0.1, "max": 50.0, "decimals": 2}
        },
        "status": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"In Transit": 40, "Delivered": 50, "Exception": 10}}
        },
        "ship_date": {
            "method": "dates",
            "kwargs": {"start": "2024-01-01", "end": "2024-10-01", "date_format": "%Y-%m-%d"}
        },
        "estimated_delivery": {
            "method": "dates",
            "kwargs": {"start": "2024-01-05", "end": "2024-10-18", "date_format": "%Y-%m-%d"}
        }
    }

`vehicles()` `classmethod` ¶

Vehicle fleet with make-model-year correlations.

Advanced Pattern: distincts_multi_map for vehicle hierarchy

Fields (8):

vehicle_id: UUID4 unique identifiers
license_plate: Pattern "XXX-XXXX" (letters-numbers)
make, model, year: Correlated hierarchy via distincts_multi_map
mileage: Odometer reading
fuel_type: Fuel types (Gasoline 60%, Diesel 30%, Electric 10%)
is_active: Fleet active status

Key Learning:

distincts_multi_map: Make→Model→Year hierarchy
Toyota→[Corolla,Camry]×[2020,2021,2022]
Ford→[F150,Mustang]×[2019,2020,2021]
Ensures only valid make-model-year combinations

Returns:

Dict[str, Any]: Specification for vehicle fleet with valid combinations

Source code in rand_engine/examples/advanced_rand_specs.py

@classmethod
def vehicles(cls) -> Dict[str, Any]:
    """
    Vehicle fleet with make-model-year correlations.

    **Advanced Pattern**: distincts_multi_map for vehicle hierarchy

    Fields (8):
    ----------
    - vehicle_id: UUID4 unique identifiers
    - license_plate: Pattern "XXX-XXXX" (letters-numbers)
    - make, model, year: Correlated hierarchy via distincts_multi_map
    - mileage: Odometer reading
    - fuel_type: Fuel types (Gasoline 60%, Diesel 30%, Electric 10%)
    - is_active: Fleet active status

    Key Learning:
    ------------
    - distincts_multi_map: Make→Model→Year hierarchy
    - Toyota→[Corolla,Camry]×[2020,2021,2022]
    - Ford→[F150,Mustang]×[2019,2020,2021]
    - Ensures only valid make-model-year combinations

    Returns:
    -------
    Dict[str, Any]: Specification for vehicle fleet with valid combinations
    """
    return {
        "vehicle_id": {
            "method": "uuid4",
            "kwargs": {}
        },
        "license_plate": {
            "method": "complex_distincts",
            "kwargs": {
                "pattern": "x-x",
                "replacement": "x",
                "templates": [
                    {"method": "distincts", "kwargs": {"distincts": ["ABC", "DEF", "GHI", "JKL"]}},
                    {"method": "int_zfilled", "kwargs": {"length": 4}}
                ]
            }
        },
        "make_model_year": {
            "method": "distincts_multi_map",
            "cols": ["make", "model", "year"],
            "kwargs": {
                "distincts": {
                    "Toyota": [
                        ["Corolla", "Camry", "RAV4"],
                        ["2020", "2021", "2022", "2023"]
                    ],
                    "Ford": [
                        ["F150", "Mustang", "Explorer"],
                        ["2019", "2020", "2021", "2022"]
                    ],
                    "Honda": [
                        ["Civic", "Accord", "CR-V"],
                        ["2020", "2021", "2022"]
                    ]
                }
            }
        },
        "mileage": {
            "method": "integers",
            "kwargs": {"min": 0, "max": 200000, "int_type": "int32"}
        },
        "fuel_type": {
            "method": "distincts_prop",
            "kwargs": {"distincts": {"Gasoline": 60, "Diesel": 30, "Electric": 10}}
        },
        "is_active": {
            "method": "booleans",
            "kwargs": {"true_prob": 0.9}
        }
    }

Kafka or any queue¶

stream_dict yields Python record dicts at a bounded rate; send them with your client. After normalization, every microbatch uses pandas records so its public Python representation is retained.

import json
from itertools import islice

events = DataGenerator({
    "event_id": {"method": "pk", "kwargs": {"start": 1}},
    "kind": {"method": "distincts", "kwargs": {"distincts": ["click", "view"]}},
}, seed=1).size(100)

records = [json.dumps(r).encode() for r in islice(events.stream_dict(min_throughput=500, max_throughput=1000), 20)]
assert json.loads(records[0])["event_id"] == 1

With kafka-python (not a test dependency, so this block is not executed):

from kafka import KafkaProducer

producer = KafkaProducer(bootstrap_servers="localhost:9092")
for record in events.stream_dict(min_throughput=10, max_throughput=50):
    producer.send("events", json.dumps(record).encode())

Parquet lake¶

One folder per partition value, several files each.

import pandas as pd

for day in ["2024-01-01", "2024-01-02"]:
    sales = DataGenerator({
        "sale_id": {"method": "pk", "kwargs": {"start": 1, "format": day.replace("-", "") + "{:06d}"}},
        "amount": {"method": "floats", "kwargs": {"min": 1, "max": 500}},
    }, seed=int(day[-2:])).size(1_000)
    sales.write.format("parquet").options(numFiles=2, compression="zstd").save(f"lake/sales/day={day}")

lake = pd.read_parquet("lake/sales")
assert len(lake) == 2_000 and lake["sale_id"].is_unique

Share the parent's pk spec with the child's fk; see 4_CONSTRAINTS.md.

customer_pk = {"method": "pk", "kwargs": {"start": 1, "format": "C{:05d}"}}
order_pk = {"method": "pk", "kwargs": {"start": 1}}

customers = DataGenerator({"customer_id": customer_pk}, seed=1).size(500).get_df()
orders = DataGenerator({
    "order_id": order_pk,
    "customer_id": {"method": "fk", "kwargs": {"parent": customer_pk, "parent_size": 500, "skew": 1.0}},
}, seed=2).size(2_000).get_df()
items = DataGenerator({
    "order_id": {"method": "fk", "kwargs": {"parent": order_pk, "parent_size": 2_000}},
    "qty": {"method": "integers", "kwargs": {"min": 1, "max": 5}},
}, seed=3).size(3_000).get_df()

assert orders.merge(customers, on="customer_id").shape[0] == 2_000
assert items.merge(orders, on="order_id").shape[0] == 3_000

Recipes¶

Faker pools¶

Spec from an Arrow schema¶

Ready-made specifications¶

customers() classmethod ¶

devices() classmethod ¶

employees() classmethod ¶

events() classmethod ¶

faker_pool(provider, locale='en_US', pool_size=100, seed=None) classmethod ¶

from_schema(schema, overrides=None) classmethod ¶

orders() classmethod ¶

products() classmethod ¶

sales() classmethod ¶

sensors() classmethod ¶

transactions() classmethod ¶

users() classmethod ¶

Basic usage¶

Exploring correlations¶

Pattern-based generation¶

devices() classmethod ¶

employees() classmethod ¶

healthcare() classmethod ¶

invoices() classmethod ¶

network_devices() classmethod ¶

orders() classmethod ¶

products() classmethod ¶

real_estate() classmethod ¶

shipments() classmethod ¶

vehicles() classmethod ¶

Kafka or any queue¶

Parquet lake¶

Related tables¶

`customers()` `classmethod` ¶

`devices()` `classmethod` ¶

`employees()` `classmethod` ¶

`events()` `classmethod` ¶

`faker_pool(provider, locale='en_US', pool_size=100, seed=None)` `classmethod` ¶

`from_schema(schema, overrides=None)` `classmethod` ¶

`orders()` `classmethod` ¶

`products()` `classmethod` ¶

`sales()` `classmethod` ¶

`sensors()` `classmethod` ¶

`transactions()` `classmethod` ¶

`users()` `classmethod` ¶

`devices()` `classmethod` ¶

`employees()` `classmethod` ¶

`healthcare()` `classmethod` ¶

`invoices()` `classmethod` ¶

`network_devices()` `classmethod` ¶

`orders()` `classmethod` ¶

`products()` `classmethod` ¶

`real_estate()` `classmethod` ¶

`shipments()` `classmethod` ¶

`vehicles()` `classmethod` ¶