Configuration

Configuration is strict, typed, and part of a run’s identity. Unknown fields and invalid ranges fail validation before generation.

SimulationRunConfig

Top-level configuration accepted by the CLI.

Field	Required	Type	Default	Constraints	Description
simulation	yes	SimulationConfig	—	—	Clock, seed, duration, and execution speed.
population	yes	PopulationConfig	—	—	Requested entity population sizes.
payments	yes	PaymentsConfig	—	—	Payment volume and payment-rail weights.
behavior	no	BehaviorConfig	—	—	Customer behavior and legitimate payment controls.
card_lifecycle	no	CardLifecycleConfig	—	—	Card authorization, settlement, refund, and chargeback timing.
pix_lifecycle	no	PixLifecycleConfig	—	—	PIX-like validation, settlement, timeout, and return timing.
fraud	yes	FraudConfig	—	—	Fraud scenario selection and prevalence controls.
fraud_workflow	no	FraudWorkflowConfig	—	—	Alert, case, dispute, confirmation, and label timing.
labels	no	LabelObservationConfig	—	—	Selection-dependent observed-label and correction behavior.
scale	no	ScaleConfig	—	—	Optional deterministic sharding, chunking, and checkpoint controls.
quality	yes	QualityConfig	—	—	Optional deterministic data-quality faults.
outputs	yes	OutputsConfig	—	—	Parquet and optional sink output policy.
kafka	no	KafkaConfig	—	—	Optional Kafka publication settings.
lakehouse	no	LakehouseConfig	—	—	Optional Iceberg lakehouse materialization settings.
dataset	no	PointInTimeDatasetConfig	—	—	Point-in-time feature, label, and temporal split settings.
backtest	no	BacktestConfig	—	—	Rolling backtest windows, regimes, and benchmark settings.
graph	no	GraphConfig	—	—	Fraud-network campaign and graph export settings.
benchmark	no	BenchmarkConfig	—	—	Difficulty and benchmark stress controls.
stress	no	StressConfig	—	—	Camouflage controls for feature and relation stress.
counterfactual	no	CounterfactualConfig	—	—	Minimum-change counterfactual trajectory settings.
campaign_dynamics	no	CampaignDynamicsConfig	—	—	Optional phase-based campaign evolution settings.
calibration	no	CalibrationConfig	—	—	Optional reference-derived aggregate calibration settings.
extensions	no	ExtensionsConfig	—	—	Optional installed extension selections.

SimulationConfig

Field	Required	Type	Default	Constraints	Description
seed	yes	integer	—	>= 0
start	yes	string	—	—
duration_days	yes	integer	—	> 0
speed	no	string	batch	allowed: batch, real_time, accelerated

PopulationConfig

Field	Required	Type	Default	Constraints	Description
customers	yes	integer	—	>= 0
institutions	yes	integer	—	>= 0
accounts	yes	integer	—	>= 0
cards	yes	integer	—	>= 0
merchants	yes	integer	—	>= 0
devices	yes	integer	—	>= 0
pix_keys	yes	integer	—	>= 0

PaymentsConfig

Field	Required	Type	Default	Constraints	Description
daily_target	yes	integer	—	>= 0
rails	yes	dict[str, number]	—	—

BehaviorConfig

Field	Required	Type	Default	Constraints	Description
amount_min	no	number	1.0	> 0
amount_max	no	number	5000.0	> 0
active_hours	no	list[integer]	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]	min items 1
weekday_weights	no	list[number]	[1.0, 1.0, 1.0, 1.0, 1.0, 0.85, 0.7]	—
merchant_preference_count	no	integer	3	>= 1
preferred_device_limit	no	integer	3	>= 0
spending_level_weights	no	list[object]	[0.3, 0.5, 0.2]	min items 3; max items 3
payday_days	no	list[integer]	[1, 15]	—
payday_weight	no	number	1.25	>= 0
beginning_of_month_weight	no	number	1.0	>= 0
end_of_month_weight	no	number	1.0	>= 0
holiday_dates	no	list[string]	[]	—
holiday_weight	no	number	1.0	>= 0
travel_period_months	no	list[integer]	[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]	—
merchant_active_hours	no	list[integer]	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]	—
state_change_probability	no	number	0.0	>= 0; <= 1

CardLifecycleConfig

Field	Required	Type	Default	Constraints	Description
authorization_approval_probability	no	number	0.9	>= 0; <= 1
reversal_probability	no	number	0.05	>= 0; <= 1
refund_probability	no	number	0.1	>= 0; <= 1
chargeback_probability	no	number	0.0	>= 0; <= 1
authorization_delay_seconds	no	integer	1	>= 0
capture_delay_seconds	no	integer	5	>= 0
clearing_delay_seconds	no	integer	30	>= 0
settlement_delay_seconds	no	integer	60	>= 0
reversal_delay_seconds	no	integer	10	>= 0
refund_delay_seconds	no	integer	60	>= 0
chargeback_delay_seconds	no	integer	86400	>= 0
chargeback_resolution_delay_seconds	no	integer	86400	>= 0

PixLifecycleConfig

Field	Required	Type	Default	Constraints	Description
authorization_approval_probability	no	number	0.98	>= 0; <= 1
rejection_probability	no	number	0.02	>= 0; <= 1
timeout_probability	no	number	0.0	>= 0; <= 1
return_probability	no	number	0.05	>= 0; <= 1
validation_delay_seconds	no	integer	1	>= 0
authorization_delay_seconds	no	integer	1	>= 0
submission_delay_seconds	no	integer	1	>= 0
timeout_delay_seconds	no	integer	1	>= 0
settlement_delay_seconds	no	integer	1	>= 0
receipt_delay_seconds	no	integer	1	>= 0
return_request_delay_seconds	no	integer	60	>= 0
return_delay_seconds	no	integer	60	>= 0

FraudConfig

Field	Required	Type	Default	Constraints	Description
enabled	no	boolean	false	—
target_rate	yes	number	—	>= 0; <= 1
scenario_count	no	integer	5	>= 0
hard_negative_rate	no	number	1.0	>= 0; <= 1
scenarios	no	dict[str, FraudScenarioSettings]	—	—

FraudWorkflowConfig

Field	Required	Type	Default	Constraints	Description
enabled	no	boolean	true	—
alert_probability	no	number	1.0	>= 0; <= 1
case_open_probability	no	number	1.0	>= 0; <= 1
confirmation_probability	no	number	1.0	>= 0; <= 1
customer_dispute_probability	no	number	1.0	>= 0; <= 1
alert_delay_seconds	no	integer	60	>= 0
case_open_delay_seconds	no	integer	300	>= 0
confirmation_delay_seconds	no	integer	86400	>= 0
customer_dispute_delay_seconds	no	integer	172800	>= 0
label_delay_seconds	no	integer	3600	>= 0

LabelObservationConfig

Field	Required	Type	Default	Constraints	Description
enabled	no	boolean	false	—
investigation_rate	no	number	0.7	>= 0; <= 1
missing_fraud_rate	no	number	0.05	>= 0; <= 1
preliminary_error_rate	no	number	0.02	>= 0; <= 1
correction_rate	no	number	0.01	>= 0; <= 1
reopening_rate	no	number	0.0	>= 0; <= 1
confirmation_delay	no	LabelDelayConfig	—	—
correction_delay	no	LabelDelayConfig	—	—
reopening_delay	no	LabelDelayConfig	—	—
conditions	no	list[LabelObservationCondition]	[]	—

ScaleConfig

Field	Required	Type	Default	Constraints	Description
profile	no	string | null	—	—
target_payments	no	integer | null	—	—
shard_count	no	integer	1	>= 1
chunk_size	no	integer	10000	>= 1
worker_count	no	integer	1	>= 1
output_batch_size	no	integer	10000	>= 1
checkpoint_frequency_chunks	no	integer	1	>= 1
partition_mapping	no	string	stable_hash_v1	—
features	no	list[string]	[“entities”, “behavior”, “payments”, “lifecycle”, “ledger”, “fraud”, “labels”]	—
storage_backend	no	string	local	allowed: local, fsspec
storage_uri	no	string | null	—	—
state_backend	no	string	duckdb	—
manifest_version	no	string	M18-scale-1	—

QualityConfig

Field	Required	Type	Default	Constraints	Description
profile	no	string	clean	allowed: clean, realistic, hostile
duplicate_record_probability	no	number | null	—	—
duplicate_event_probability	no	number | null	—	—
missing_optional_probability	no	number | null	—	—
invalid_value_probability	no	number | null	—	—
invalid_enum_probability	no	number | null	—	—
invalid_reference_probability	no	number | null	—	—
negative_amount_probability	no	number | null	—	—
corrupted_timestamp_probability	no	number | null	—	—
timezone_error_probability	no	number | null	—	—
schema_mismatch_probability	no	number | null	—	—
extreme_value_probability	no	number | null	—	—
encoding_error_probability	no	number | null	—	—
partition_skew_probability	no	number | null	—	—
late_event_probability	no	number | null	—	—
out_of_order_probability	no	number | null	—	—
fraud_spike_probability	no	number | null	—	—
traffic_spike_probability	no	number | null	—	—
late_event_delay_seconds	no	integer	3600	>= 0
source_delay_seconds	no	integer	0	>= 0
fraud_spike_multiplier	no	integer	2	>= 1
traffic_spike_multiplier	no	integer	2	>= 1
outages	no	list[OutageConfig]	[]	—
schema_changes	no	list[SchemaChangeConfig]	[]	—

OutputsConfig

Field	Required	Type	Default	Constraints	Description
parquet	no	boolean	false	—
postgres	no	boolean	false	—
kafka	no	boolean	false	—
iceberg	no	boolean	false	—

KafkaConfig

Field	Required	Type	Default	Constraints	Description
topic_prefix	no	string	fraudsim	min length 1; max length 128
max_events_per_second	no	number | null	—	—
delivery_timeout_seconds	no	number	120.0	> 0
accelerated_time_multiplier	no	number	100.0	>= 1

LakehouseConfig

Field	Required	Type	Default	Constraints	Description
catalog_name	no	string	fraudtwin	—
namespace_prefix	no	string	fraudtwin	—
include_oracle	no	boolean	false	—
checkpoint_location	no	string	./runs/iceberg-checkpoints	—

PointInTimeDatasetConfig

Field	Required	Type	Default	Constraints	Description
enabled	no	boolean	true	—
start	no	string | null	—	—
end	no	string | null	—	—
prediction_delay_seconds	no	integer	0	>= 0
feature_windows	no	dict[str, integer]	—	—
label_delay_seconds	no	integer | null	—	—
unresolved_labels	no	string	exclude	allowed: exclude, include
splits	no	TemporalSplitConfig	—	—

BacktestConfig

Field	Required	Type	Default	Constraints	Description
train_mode	no	string	expanding	allowed: fixed, expanding
train_window_seconds	no	integer | null	—	—
validation_window_seconds	no	integer | null	—	—
test_window_seconds	no	integer	2592000	—
label_maturity_gap_seconds	no	integer	1209600	—
step_seconds	no	integer	2592000	—
minimum_label_maturity_policy	no	string	exclude	allowed: exclude, include_unresolved
regimes	no	list[FraudRegimeConfig]	[]	—

GraphConfig

Field	Required	Type	Default	Constraints	Description
schema_version	no	string	2	—
enabled	no	boolean	false	—
scenarios	no	list[GraphScenario]	[]	—
relationship_window_seconds	no	integer	2592000	> 0
pattern_window_seconds	no	integer	86400	> 0
ring_min_size	no	integer	3	>= 3; <= 7
ring_max_size	no	integer	7	>= 3; <= 7
fan_threshold	no	integer	3	>= 2
shared_threshold	no	integer	2	>= 2
dwell_threshold_seconds	no	integer	3600	> 0
amount_retention_tolerance	no	number	0.2	>= 0; < 1
export_policy	no	string	both	allowed: observable, oracle, both

BenchmarkConfig

Field	Required	Type	Default	Constraints	Description
difficulty	no	integer | null	—	—
controls	no	DifficultyControls	—	—
camouflage	no	number | null	—	—
feature_camouflage	no	number | null	—	—
relation_camouflage	no	number | null	—	—
camouflage_cohort	no	CamouflageCohortConfig	—	—
camouflage_families	no	dict[str, CamouflageFamilyConfig]	—	—

StressConfig

Field	Required	Type	Default	Constraints	Description
camouflage	no	number | null	—	—
feature_camouflage	no	number | null	—	—
relation_camouflage	no	number | null	—	—
cohort	no	CamouflageCohortConfig	—	—
families	no	dict[str, CamouflageFamilyConfig]	—	—

CounterfactualConfig

Field	Required	Type	Default	Constraints	Description
enabled	no	boolean	false	—
budget	no	number	4.0	>= 0
distance_function	no	string	weighted_changed_dimensions_v1	—
source_strategy	no	string	chronological_first	allowed: chronological_first, stable_hash
allow_source_reuse	no	boolean	false	—
include_enabled_objectives	no	boolean	false	—
dimensions	no	dict[str, CounterfactualDimensionConfig]	—	—
families	no	dict[str, CounterfactualScopeConfig]	—	—
scenarios	no	dict[str, CounterfactualScopeConfig]	—	—
requests	no	list[CounterfactualRequestConfig]	[]	—

CampaignDynamicsConfig

Field	Required	Type	Default	Constraints	Description
enabled	no	boolean	false	—
bindings	no	list[CampaignDynamicsBinding]	[]	—

CalibrationConfig

Field	Required	Type	Default	Constraints	Description
enabled	no	boolean	false	—
profile	no	string | null	—	—
model_names	no	list[string]	[“builtin”]	—
summary_names	no	list[string]	[“amount_distribution”, “inter_arrival”, “seasonality”, “merchant_frequency”, “customer_activity”, “feature_dependencies”, “account_balance”, “transaction_count”, “graph_statistics”, “campaign_statistics”]	—
weights	no	dict[str, number]	—	—
minimum_scores	no	dict[str, number]	—	—

ExtensionsConfig

Field	Required	Type	Default	Constraints	Description
enabled	no	boolean	false	—
selected	no	list[string]	[]	—

LabelDelayConfig

Field	Required	Type	Default	Constraints	Description
distribution	no	string	lognormal	allowed: fixed, lognormal
median_seconds	no	number	86400.0	> 0
sigma	no	number	0.5	>= 0
minimum_seconds	no	number	0.0	>= 0
maximum_seconds	no	number | null	—	—

TemporalSplitConfig

Field	Required	Type	Default	Constraints	Description
train_fraction	no	number	0.7	> 0; < 1
validation_fraction	no	number	0.15	> 0; < 1
test_fraction	no	number	0.15	> 0; < 1
label_delay_gap_seconds	no	integer | null	—	—
train_end	no	string | null	—	—
validation_end	no	string | null	—	—
test_end	no	string | null	—	—

DifficultyControls

Field	Required	Type	Default	Constraints	Description
fraud_legitimate_overlap	no	number | null	—	—
behavioral_deviation	no	number | null	—	—
scenario_subtlety	no	number | null	—	—
noise_hard_negatives	no	number | null	—	—
prevalence	no	number | null	—	—
temporal_irregularity	no	number | null	—	—
graph_structural_subtlety	no	number | null	—	—

CamouflageCohortConfig

Field	Required	Type	Default	Constraints	Description
strategy	no	string	same_rail_and_profile	allowed: same_rail_and_profile, same_rail, global_legitimate
profile_dimensions	no	list[string]	[“spending_level”, “country”, “merchant_category”, “typical_payment_hour”, “trusted_device”]	—
minimum_size	no	integer	3	>= 1
fallback	no	string	same_rail	allowed: same_rail, global_legitimate, reject

Loading and hashing

fraudtwin.config.load_config	Load and validate a YAML configuration file.
fraudtwin.config.config_hash	Return a stable SHA-256 hash of the validated configuration.

Configuration model classes

fraudtwin.config.SimulationRunConfig	Top-level configuration accepted by the CLI.
fraudtwin.config.SimulationConfig	Clock and execution settings for a simulation.
fraudtwin.config.PopulationConfig	Requested population sizes.
fraudtwin.config.PaymentsConfig	Payment-volume and rail-mix settings.
fraudtwin.config.FraudConfig	Explicit scenario settings for the first fraud release.
fraudtwin.config.PointInTimeDatasetConfig	Configuration for the local M9 historical dataset builder.
fraudtwin.config.GraphConfig	Strict controls for M11 graph construction and export (schema v2).
fraudtwin.config.BenchmarkConfig	Opt-in M12 fraud-difficulty controls.