fraudtwin.generation

Deterministic standard and scale run generation.

Status: Stable

Classes

fraudtwin.generation.GeneratedData	Generated FraudTwin data kept in memory.
fraudtwin.generation.GeneratedRun	Metadata and paths for a generated run written to disk.

Functions

fraudtwin.generation.generate	Generate a deterministic FraudTwin run.
fraudtwin.generation.generate_scale	Run an explicitly requested scale job using the scale manifest path.
fraudtwin.generation.iter_scale_records	Stream canonical entities, profiles, payments, events, and ledger rows.
fraudtwin.generation.iter_scale_run	Yield scale records from a producer or an existing partitioned run.
fraudtwin.generation.resume_generation	Resume a scale run from a validated checkpoint manifest.

Detailed API

High-level Python API for generating deterministic FraudTwin runs.

class fraudtwin.generation.GeneratedData(manifest, entities, behavior, dataset=None, stage_timings=<factory>)

Bases: object

Generated FraudTwin data kept in memory.

Parameters:

• manifest (RunManifest)

• entities (EntityDataset)

• behavior (BehaviorDataset)

• dataset (PointInTimeDataset | None)

• stage_timings (dict[str, dict[str, float]])

property run_id: str

Return the deterministic identifier for this generated run.

require_dataset()

Return the point-in-time dataset, or explain how to enable it.

generate only builds a dataset when config.dataset.enabled is true. This typed accessor keeps notebook and application code concise while preserving the optional dataset for lightweight simulations.

Raises:

RuntimeError – If the supplied configuration did not enable the point-in-time dataset builder.

Return type:

PointInTimeDataset

class fraudtwin.generation.GeneratedRun(manifest, run_dir, manifest_path, dataset_path=None, dataset_manifest_path=None, stage_timings=<factory>)

Bases: object

Metadata and paths for a generated run written to disk.

Parameters:

• manifest (RunManifest)

• run_dir (Path)

• manifest_path (Path)

• dataset_path (Path | None)

• dataset_manifest_path (Path | None)

• stage_timings (dict[str, dict[str, float]])

property run_id: str

Return the deterministic identifier for this generated run.

load_data()

Load the typed entities and behavior behind this written run.

A written run intentionally returns metadata and paths so large runs are not retained in memory. Call this method when a graph, dataset builder, or publisher needs the persisted domain records.

Raises:

ValueError – If the run directory is missing or has an invalid manifest or artifact.

Return type:

GeneratedData

fraudtwin.generation.generate(config=None, *, write=False, output_dir='runs', profile=None, seed=None, workers=None, checkpoint_dir=None)

Generate a deterministic FraudTwin run.

If config is omitted, the built-in minimal configuration is used. By default, generated data is returned in memory without writing files. Set write=True to preserve the CLI’s Parquet and manifest output layout.

Return type:

GeneratedData | GeneratedRun

Parameters:

• config (str | Path | SimulationRunConfig | None)

• write (bool)

• output_dir (str | Path)

• profile (str | Path | CalibrationProfile | None)

• seed (int | None)

• workers (int | None)

• checkpoint_dir (str | Path | None)

fraudtwin.generation.generate_scale(config, *, output_dir='runs', checkpoint_dir=None, profile=None, seed=None, workers=None)

Run an explicitly requested scale job using the scale manifest path.

This entry point preserves the established generation semantics while making scale execution explicit. Large profiles should be run through this API/CLI; the compatibility generate API remains available for small in-memory callers.

Return type:

GeneratedRun

Parameters:

• config (str | Path | SimulationRunConfig)

• output_dir (str | Path)

• checkpoint_dir (str | Path | None)

• profile (str | Path | CalibrationProfile | None)

• seed (int | None)

• workers (int | None)

fraudtwin.generation.iter_scale_run(config=None, *, entities=None, run_dir=None, simulation_run_id=None)

Yield scale records from a producer or an existing partitioned run.

Supplying run_dir reads one Parquet chunk at a time. Supplying entities exposes the canonical producer stream for integrations that already own an entity source. Exactly one source must be provided.

Return type:

Iterator[dict[str, object]]

Parameters:

• config (SimulationRunConfig | None)

• entities (EntityDataset | None)

• run_dir (str | Path | None)

• simulation_run_id (str | None)

fraudtwin.generation.iter_scale_records(config, entities, *, simulation_run_id, stage_timings=None)

Stream canonical entities, profiles, payments, events, and ledger rows.

This iterator is the scale writer’s producer-facing API. It deliberately keeps only generator state and account balances; records are never accumulated into a BehaviorDataset. Advanced fraud/graph stages still use the compatibility generator until their own streaming implementations are available.

Return type:

Iterator[dict[str, object]]

Parameters:

• config (SimulationRunConfig)

• entities (EntityDataset)

• simulation_run_id (str)

• stage_timings (dict[str, dict[str, float]] | None)

fraudtwin.generation.resume_generation(checkpoint)

Resume a scale run from a validated checkpoint manifest.

Canonical partition artifacts are idempotently regenerated from the stored resolved configuration. Completed partition fingerprints are checked by the caller/consumer through the resulting manifest and checkpoint.

Return type:

GeneratedRun

Parameters:

checkpoint (str | Path)