fraudtwin.config#

Typed configuration models, loading, and validation.

Status: Stable

Classes#

fraudtwin.config.BacktestConfig

Rolling PIT backtest and source-history regime settings.

fraudtwin.config.BehaviorConfig

Settings used by the customer behavior and legitimate payment engine.

fraudtwin.config.BenchmarkConfig

Opt-in M12 fraud-difficulty controls.

fraudtwin.config.BeneficiaryNetworkScenario

fraudtwin.config.BipartiteNetworkScenario

fraudtwin.config.CalibrationConfig

Strict opt-in controls for reference calibration.

fraudtwin.config.CamouflageCohortConfig

Deterministic legitimate peer selection for M13.

fraudtwin.config.CamouflageFamilyConfig

Optional M13 controls for the fraud or graph generator family.

fraudtwin.config.CampaignDynamicsBinding

One deterministic M15 profile applied to every matching M11 campaign.

fraudtwin.config.CampaignDynamicsConfig

Strict opt-in controls for campaign evolution.

fraudtwin.config.CardLifecycleConfig

Deterministic probabilities and delays for card payment lifecycles.

fraudtwin.config.CounterfactualConfig

Strict, opt-in counterfactual controls.

fraudtwin.config.CounterfactualDimensionConfig

Cost and mutability controls for one counterfactual dimension.

fraudtwin.config.CounterfactualRequestConfig

One deterministic counterfactual objective request.

fraudtwin.config.CounterfactualScopeConfig

Global, family, or objective-level M14 overrides.

fraudtwin.config.CyclicRingScenario

fraudtwin.config.DenseCampaignScenario

fraudtwin.config.DifficultyControls

Optional per-dimension M12 difficulty overrides.

fraudtwin.config.ExtensionsConfig

Opt-in installed extension selections.

fraudtwin.config.FanOutScenario

fraudtwin.config.FraudConfig

Explicit scenario settings for the first fraud release.

fraudtwin.config.FraudRegimeConfig

A declared fraud regime applied only while generating source history.

fraudtwin.config.FraudScenarioSettings

Bounds and prevalence controls shared by one M6 scenario.

fraudtwin.config.FraudWorkflowConfig

Operational fraud alert, case, dispute, and label timing controls.

fraudtwin.config.GatherScatterScenario

fraudtwin.config.GraphConfig

Strict controls for M11 graph construction and export (schema v2).

fraudtwin.config.GraphScenarioConfig

One discriminated, deterministic M11 scenario specification.

fraudtwin.config.KafkaConfig

Delivery controls for the optional native Kafka sink.

fraudtwin.config.LabelDelayConfig

Distribution used for observation delays.

fraudtwin.config.LabelObservationCondition

Optional exact-match/range override for an observation probability.

fraudtwin.config.LabelObservationConfig

Explicit deterministic label-observation policy.

fraudtwin.config.LakehouseConfig

Optional Iceberg lakehouse publication controls.

fraudtwin.config.MerchantCustomerCommunityScenario

fraudtwin.config.MuleNetworkScenario

fraudtwin.config.OutageConfig

A deterministic source-boundary outage used by M8.

fraudtwin.config.OutputsConfig

Output sinks enabled for optional integrations.

fraudtwin.config.PaymentsConfig

Payment-volume and rail-mix settings.

fraudtwin.config.PixLifecycleConfig

Deterministic probabilities and delays for PIX payment lifecycles.

fraudtwin.config.PointInTimeDatasetConfig

Configuration for the local M9 historical dataset builder.

fraudtwin.config.PopulationConfig

Requested population sizes.

fraudtwin.config.QualityConfig

Deterministic M8 data-quality fault controls.

fraudtwin.config.RandomAlertControlScenario

fraudtwin.config.ScaleConfig

Opt-in deterministic large-run execution controls.

fraudtwin.config.ScatterGatherScenario

fraudtwin.config.SchemaChangeConfig

A scheduled event-schema change with optional compatibility metadata.

fraudtwin.config.SharedDeviceScenario

fraudtwin.config.SharedIPScenario

fraudtwin.config.SimulationConfig

Clock and execution settings for a simulation.

fraudtwin.config.SimulationRunConfig

Top-level configuration accepted by the CLI.

fraudtwin.config.StackedNetworkScenario

fraudtwin.config.StressConfig

Opt-in M13 camouflage controls.

fraudtwin.config.TemporalSplitConfig

Deterministic, chronological train/validation/test split settings.

Functions#

fraudtwin.config.config_hash

Return a stable SHA-256 hash of the validated configuration.

fraudtwin.config.graph_account_capacity

Return the number of distinct accounts required by one scenario instance.

fraudtwin.config.load_config

Load and validate a YAML configuration file.

Detailed API#

class fraudtwin.config.SimulationConfig(**data)[source][source]

Bases: _StrictModel

Clock and execution settings for a simulation.

Parameters:

  • seed (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • start (datetime)

  • duration_days (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Gt(gt=0)])])

  • speed (Literal['batch', 'real_time', 'accelerated'])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.PopulationConfig(**data)[source][source]

Bases: _StrictModel

Requested population sizes.

Parameters:

  • customers (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • institutions (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • accounts (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • cards (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • merchants (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • devices (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • pix_keys (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

relationships_have_required_pools()[source][source]

Reject populations that cannot satisfy the entity relationships.

Return type:

PopulationConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.PaymentsConfig(**data)[source][source]

Bases: _StrictModel

Payment-volume and rail-mix settings.

Parameters:

  • daily_target (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • rails (dict[Literal['CARD', 'PIX', 'ACCOUNT_TRANSFER'], ~typing.Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])]])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.BehaviorConfig(**data)[source][source]

Bases: _StrictModel

Settings used by the customer behavior and legitimate payment engine.

Parameters:

  • amount_min (float)

  • amount_max (float)

  • active_hours (tuple[int, ...])

  • weekday_weights (tuple[float, ...])

  • merchant_preference_count (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

  • preferred_device_limit (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • spending_level_weights (tuple[float, float, float])

  • payday_days (tuple[int, ...])

  • payday_weight (float)

  • beginning_of_month_weight (float)

  • end_of_month_weight (float)

  • holiday_dates (tuple[str, ...])

  • holiday_weight (float)

  • travel_period_months (tuple[int, ...])

  • merchant_active_hours (tuple[int, ...])

  • state_change_probability (float)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CardLifecycleConfig(**data)[source][source]

Bases: _StrictModel

Deterministic probabilities and delays for card payment lifecycles.

Parameters:

  • authorization_approval_probability (float)

  • reversal_probability (float)

  • refund_probability (float)

  • chargeback_probability (float)

  • authorization_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • capture_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • clearing_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • settlement_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • reversal_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • refund_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • chargeback_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • chargeback_resolution_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

property maximum_delay_seconds: int

Return the largest possible lifecycle delay before envelope timing.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.PixLifecycleConfig(**data)[source][source]

Bases: _StrictModel

Deterministic probabilities and delays for PIX payment lifecycles.

Parameters:

  • authorization_approval_probability (float)

  • rejection_probability (float)

  • timeout_probability (float)

  • return_probability (float)

  • validation_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • authorization_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • submission_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • timeout_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • settlement_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • receipt_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • return_request_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • return_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

property maximum_delay_seconds: int

Return the longest possible PIX path, including a return.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.FraudScenarioSettings(**data)[source][source]

Bases: _StrictModel

Bounds and prevalence controls shared by one M6 scenario.

Parameters:

  • enabled (bool)

  • weight (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • count (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • amount_min (float | None)

  • amount_max (float | None)

  • duration_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • attempt_count (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

  • window_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Gt(gt=0)])])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.FraudConfig(**data)[source][source]

Bases: _StrictModel

Explicit scenario settings for the first fraud release.

Parameters:

  • enabled (bool)

  • target_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])])

  • scenario_count (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • hard_negative_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])])

  • scenarios (dict[Literal['F01', 'F02', 'F03', 'F04', 'F05'], ~fraudtwin.config.FraudScenarioSettings])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.FraudWorkflowConfig(**data)[source][source]

Bases: _StrictModel

Operational fraud alert, case, dispute, and label timing controls.

Parameters:

  • enabled (bool)

  • alert_probability (float)

  • case_open_probability (float)

  • confirmation_probability (float)

  • customer_dispute_probability (float)

  • alert_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • case_open_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • confirmation_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • customer_dispute_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • label_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.LabelDelayConfig(**data)[source][source]

Bases: _StrictModel

Distribution used for observation delays.

A bare lognormal value is accepted by LabelObservationConfig and resolves to these deterministic defaults.

Parameters:

  • distribution (Literal['fixed', 'lognormal'])

  • median_seconds (float)

  • sigma (float)

  • minimum_seconds (float)

  • maximum_seconds (float | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.LabelObservationCondition(**data)[source][source]

Bases: _StrictModel

Optional exact-match/range override for an observation probability.

Parameters:

  • amount_min (float | None)

  • amount_max (float | None)

  • payment_rail (str | None)

  • fraud_type (str | None)

  • customer_segment (str | None)

  • alert_severity (str | None)

  • campaign_id (str | None)

  • investigation_rate (float | None)

  • delay (LabelDelayConfig | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.LabelObservationConfig(**data)[source][source]

Bases: _StrictModel

Explicit deterministic label-observation policy.

Parameters:

  • enabled (bool)

  • investigation_rate (float)

  • missing_fraud_rate (float)

  • preliminary_error_rate (float)

  • correction_rate (float)

  • reopening_rate (float)

  • confirmation_delay (LabelDelayConfig)

  • correction_delay (LabelDelayConfig)

  • reopening_delay (LabelDelayConfig)

  • conditions (tuple[LabelObservationCondition, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.ScaleConfig(**data)[source][source]

Bases: _StrictModel

Opt-in deterministic large-run execution controls.

Parameters:

  • profile (Literal['dev', 'small', 'medium', 'large', 'xlarge', 'billion'] | None)

  • target_payments (Annotated[int | None, FieldInfo(annotation=NoneType, required=False, default=None, metadata=[Ge(ge=1)])])

  • shard_count (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

  • chunk_size (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

  • worker_count (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

  • output_batch_size (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

  • checkpoint_frequency_chunks (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

  • partition_mapping (Literal['stable_hash_v1'])

  • features (tuple[Literal['entities', 'behavior', 'payments', 'lifecycle', 'ledger', 'fraud', 'labels', 'graph', 'pit', 'backtest'], ...])

  • storage_backend (Literal['local', 'fsspec'])

  • storage_uri (str | None)

  • state_backend (Literal['duckdb'])

  • manifest_version (str)

property resolved_target_payments: int | None

Return the configured payment target for this scale run.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.OutageConfig(**data)[source][source]

Bases: _StrictModel

A deterministic source-boundary outage used by M8.

Parameters:

  • source (str)

  • from_time (datetime)

  • to_time (datetime)

  • behavior (Literal['DROP', 'BUFFER_AND_FLUSH', 'DELAY', 'PARTIAL_REJECT', 'UNAVAILABLE'])

  • delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • reject_probability (float)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.SchemaChangeConfig(**data)[source][source]

Bases: _StrictModel

A scheduled event-schema change with optional compatibility metadata.

Parameters:

  • at (datetime)

  • event (str)

  • version (str)

  • change (dict[str, object])

  • compatibility (Literal['BACKWARD_COMPATIBLE', 'FORWARD_COMPATIBLE', 'FULLY_COMPATIBLE', 'BREAKING'] | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.QualityConfig(**data)[source][source]

Bases: _StrictModel

Deterministic M8 data-quality fault controls.

None values use the selected profile’s defaults. Explicit values are useful for testing one fault in isolation without changing the other quality dimensions.

Parameters:

  • profile (Literal['clean', 'realistic', 'hostile'])

  • duplicate_record_probability (float | None)

  • duplicate_event_probability (float | None)

  • missing_optional_probability (float | None)

  • invalid_value_probability (float | None)

  • invalid_enum_probability (float | None)

  • invalid_reference_probability (float | None)

  • negative_amount_probability (float | None)

  • corrupted_timestamp_probability (float | None)

  • timezone_error_probability (float | None)

  • schema_mismatch_probability (float | None)

  • extreme_value_probability (float | None)

  • encoding_error_probability (float | None)

  • partition_skew_probability (float | None)

  • late_event_probability (float | None)

  • out_of_order_probability (float | None)

  • fraud_spike_probability (float | None)

  • traffic_spike_probability (float | None)

  • late_event_delay_seconds (int)

  • source_delay_seconds (int)

  • fraud_spike_multiplier (int)

  • traffic_spike_multiplier (int)

  • outages (tuple[OutageConfig, ...])

  • schema_changes (tuple[SchemaChangeConfig, ...])

probability(fault_name)[source][source]

Return an explicit probability or the selected profile default.

Return type:

float

Parameters:

fault_name (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.OutputsConfig(**data)[source][source]

Bases: _StrictModel

Output sinks enabled for optional integrations.

Parameters:

  • parquet (bool)

  • postgres (bool)

  • kafka (bool)

  • iceberg (bool)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.KafkaConfig(**data)[source][source]

Bases: _StrictModel

Delivery controls for the optional native Kafka sink.

Parameters:

  • topic_prefix (str)

  • max_events_per_second (float | None)

  • delivery_timeout_seconds (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Gt(gt=0)])])

  • accelerated_time_multiplier (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.LakehouseConfig(**data)[source][source]

Bases: _StrictModel

Optional Iceberg lakehouse publication controls.

Connection details are deliberately not configuration fields: the catalog, object-store endpoint, and credentials are supplied through the environment by the lakehouse adapter.

Parameters:

  • catalog_name (str)

  • namespace_prefix (str)

  • include_oracle (bool)

  • checkpoint_location (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.TemporalSplitConfig(**data)[source][source]

Bases: _StrictModel

Deterministic, chronological train/validation/test split settings.

Parameters:

  • train_fraction (float)

  • validation_fraction (float)

  • test_fraction (float)

  • label_delay_gap_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])] | None)

  • train_end (datetime | None)

  • validation_end (datetime | None)

  • test_end (datetime | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.PointInTimeDatasetConfig(**data)[source][source]

Bases: _StrictModel

Configuration for the local M9 historical dataset builder.

Parameters:

  • enabled (bool)

  • start (datetime | None)

  • end (datetime | None)

  • prediction_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • feature_windows (dict[Literal['transaction_count_1m', 'transaction_count_5m', 'transaction_count_1h', 'transaction_count_24h', 'transaction_count_7d', 'transaction_count_30d', 'transaction_amount_1h', 'transaction_amount_24h', 'transaction_amount_7d', 'avg_transaction_amount_30d', 'max_transaction_amount_7d', 'distinct_merchants_1d', 'distinct_merchants_30d', 'merchant_fraud_rate_historical', 'distinct_countries_24h', 'device_customer_count_30d', 'customers_per_device_24h', 'confirmed_fraud_count_90d', 'fraud_loss_365d', 'days_since_last_confirmed_fraud'], ~typing.Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Gt(gt=0)])]])

  • label_delay_seconds (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])] | None)

  • unresolved_labels (Literal['exclude', 'include'])

  • splits (TemporalSplitConfig)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.FraudRegimeConfig(**data)[source][source]

Bases: _StrictModel

A declared fraud regime applied only while generating source history.

Parameters:

  • id (str)

  • from_time (datetime)

  • to_time (datetime)

  • prevalence_multiplier (float)

  • scenario_mix (dict[Literal['F01', 'F02', 'F03', 'F04', 'F05'], ~typing.Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])]])

  • amount_multiplier (float)

  • timing_multiplier (float)

  • camouflage (float)

  • campaign_intensity (float)

  • payment_rail_mix (dict[Literal['CARD', 'PIX', 'ACCOUNT_TRANSFER'], ~typing.Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])]] | None)

  • label_observation_policy (Literal['original', 'unobserved'])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.BacktestConfig(**data)[source][source]

Bases: _StrictModel

Rolling PIT backtest and source-history regime settings.

Parameters:

  • train_mode (Literal['fixed', 'expanding'])

  • train_window_seconds (int | None)

  • validation_window_seconds (int | None)

  • test_window_seconds (int)

  • label_maturity_gap_seconds (int)

  • step_seconds (int)

  • minimum_label_maturity_policy (Literal['exclude', 'include_unresolved'])

  • regimes (tuple[FraudRegimeConfig, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CalibrationConfig(**data)[source][source]

Bases: _StrictModel

Strict opt-in controls for reference calibration.

Parameters:

  • enabled (bool)

  • profile (Path | None)

  • model_names (tuple[str, ...])

  • summary_names (tuple[Literal['amount_distribution', 'inter_arrival', 'seasonality', 'merchant_frequency', 'customer_activity', 'feature_dependencies', 'account_balance', 'transaction_count', 'graph_statistics', 'campaign_statistics'], ...])

  • weights (dict[Literal['amount_distribution', 'inter_arrival', 'seasonality', 'merchant_frequency', 'customer_activity', 'feature_dependencies', 'account_balance', 'transaction_count', 'graph_statistics', 'campaign_statistics'], float])

  • minimum_scores (dict[str, float])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CounterfactualDimensionConfig(**data)[source][source]

Bases: _StrictModel

Cost and mutability controls for one counterfactual dimension.

Parameters:

  • enabled (bool)

  • cost (float)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CounterfactualScopeConfig(**data)[source][source]

Bases: _StrictModel

Global, family, or objective-level M14 overrides.

Parameters:

  • enabled (bool | None)

  • budget (float | None)

  • dimensions (dict[Literal['beneficiary', 'device', 'timing', 'amount', 'merchant', 'geography', 'payment_rail', 'graph_relationships'], ~fraudtwin.config.CounterfactualDimensionConfig])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CounterfactualRequestConfig(**data)[source][source]

Bases: _StrictModel

One deterministic counterfactual objective request.

Parameters:

  • objective (Literal['F01', 'F02', 'F03', 'F04', 'F05', 'MULE_NETWORK', 'CYCLIC_RING', 'BENEFICIARY_NETWORK', 'FAN_OUT', 'BIPARTITE_NETWORK', 'STACKED_NETWORK', 'SCATTER_GATHER', 'GATHER_SCATTER', 'SHARED_DEVICE_INFRASTRUCTURE', 'SHARED_IP_INFRASTRUCTURE', 'DENSE_CAMPAIGN', 'MERCHANT_CUSTOMER_COMMUNITY', 'RANDOM_ALERT_CONTROL'] | None)

  • scenario (Literal['F01', 'F02', 'F03', 'F04', 'F05', 'MULE_NETWORK', 'CYCLIC_RING', 'BENEFICIARY_NETWORK', 'FAN_OUT', 'BIPARTITE_NETWORK', 'STACKED_NETWORK', 'SCATTER_GATHER', 'GATHER_SCATTER', 'SHARED_DEVICE_INFRASTRUCTURE', 'SHARED_IP_INFRASTRUCTURE', 'DENSE_CAMPAIGN', 'MERCHANT_CUSTOMER_COMMUNITY', 'RANDOM_ALERT_CONTROL'] | None)

  • count (int)

  • enabled (bool | None)

  • budget (float | None)

  • max_distance (float | None)

  • dimensions (dict[Literal['beneficiary', 'device', 'timing', 'amount', 'merchant', 'geography', 'payment_rail', 'graph_relationships'], ~fraudtwin.config.CounterfactualDimensionConfig])

  • graph_template (Literal['MULE_NETWORK', 'CYCLIC_RING', 'BENEFICIARY_NETWORK', 'FAN_OUT', 'BIPARTITE_NETWORK', 'STACKED_NETWORK', 'SCATTER_GATHER', 'GATHER_SCATTER', 'SHARED_DEVICE_INFRASTRUCTURE', 'SHARED_IP_INFRASTRUCTURE', 'DENSE_CAMPAIGN', 'MERCHANT_CUSTOMER_COMMUNITY', 'RANDOM_ALERT_CONTROL'] | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CounterfactualConfig(**data)[source][source]

Bases: _StrictModel

Strict, opt-in counterfactual controls.

Parameters:

  • enabled (bool)

  • budget (float)

  • distance_function (str)

  • source_strategy (Literal['chronological_first', 'stable_hash'])

  • allow_source_reuse (bool)

  • include_enabled_objectives (bool)

  • dimensions (dict[Literal['beneficiary', 'device', 'timing', 'amount', 'merchant', 'geography', 'payment_rail', 'graph_relationships'], ~fraudtwin.config.CounterfactualDimensionConfig])

  • families (dict[Literal['fraud', 'graph'], ~fraudtwin.config.CounterfactualScopeConfig])

  • scenarios (dict[Literal['F01', 'F02', 'F03', 'F04', 'F05', 'MULE_NETWORK', 'CYCLIC_RING', 'BENEFICIARY_NETWORK', 'FAN_OUT', 'BIPARTITE_NETWORK', 'STACKED_NETWORK', 'SCATTER_GATHER', 'GATHER_SCATTER', 'SHARED_DEVICE_INFRASTRUCTURE', 'SHARED_IP_INFRASTRUCTURE', 'DENSE_CAMPAIGN', 'MERCHANT_CUSTOMER_COMMUNITY', 'RANDOM_ALERT_CONTROL'], ~fraudtwin.config.CounterfactualScopeConfig])

  • requests (tuple[CounterfactualRequestConfig, ...])

property active: bool

Whether M14 changes generation or artifacts.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.DifficultyControls(**data)[source][source]

Bases: _StrictModel

Optional per-dimension M12 difficulty overrides.

Values are normalized strengths: zero is the level profile’s easiest setting and one is its most difficult setting. A supplied value replaces only that dimension of the requested benchmark level.

Parameters:

  • fraud_legitimate_overlap (float | None)

  • behavioral_deviation (float | None)

  • scenario_subtlety (float | None)

  • noise_hard_negatives (float | None)

  • prevalence (float | None)

  • temporal_irregularity (float | None)

  • graph_structural_subtlety (float | None)

property active: bool

Whether at least one dimension was explicitly overridden.

values()[source][source]

Return all normalized override values in stable field order.

Return type:

dict[str, float | None]

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.BenchmarkConfig(**data)[source][source]

Bases: _StrictModel

Opt-in M12 fraud-difficulty controls.

property enabled: bool

Whether M12 should alter generation or artifacts.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CamouflageCohortConfig(**data)[source][source]

Bases: _StrictModel

Deterministic legitimate peer selection for M13.

Parameters:

  • strategy (Literal['same_rail_and_profile', 'same_rail', 'global_legitimate'])

  • profile_dimensions (tuple[Literal['spending_level', 'country', 'merchant_category', 'typical_payment_hour', 'trusted_device'], ...])

  • minimum_size (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

  • fallback (Literal['same_rail', 'global_legitimate', 'reject'])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CamouflageFamilyConfig(**data)[source][source]

Bases: _StrictModel

Optional M13 controls for the fraud or graph generator family.

Parameters:

  • camouflage (float | None)

  • feature_camouflage (float | None)

  • relation_camouflage (float | None)

  • features (dict[Literal['amount', 'timing', 'merchant', 'device', 'geography', 'frequency'], ~typing.Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])]])

  • relations (dict[Literal['transferred_to', 'transacted_with', 'shares_device', 'shares_ip'], ~typing.Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])]])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.StressConfig(**data)[source][source]

Bases: _StrictModel

Opt-in M13 camouflage controls.

Parameters:

  • camouflage (float | None)

  • feature_camouflage (float | None)

  • relation_camouflage (float | None)

  • cohort (CamouflageCohortConfig)

  • families (dict[Literal['fraud', 'graph'], ~fraudtwin.config.CamouflageFamilyConfig])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.GraphScenarioConfig(**data)[source][source]

Bases: _StrictModel

One discriminated, deterministic M11 scenario specification.

Parameters:

  • type (Literal['MULE_NETWORK', 'CYCLIC_RING', 'BENEFICIARY_NETWORK', 'FAN_OUT', 'BIPARTITE_NETWORK', 'STACKED_NETWORK', 'SCATTER_GATHER', 'GATHER_SCATTER', 'SHARED_DEVICE_INFRASTRUCTURE', 'SHARED_IP_INFRASTRUCTURE', 'DENSE_CAMPAIGN', 'MERCHANT_CUSTOMER_COMMUNITY', 'RANDOM_ALERT_CONTROL'])

  • count (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

  • member_count (int | None)

  • source_count (int | None)

  • destination_count (int | None)

  • originator_count (int | None)

  • intermediary_count (int | None)

  • beneficiary_count (int | None)

  • customer_count (int | None)

  • merchant_count (int | None)

  • edge_count (int | None)

  • repeat_count (int | None)

  • min_amount (float | None)

  • max_amount (float | None)

  • window_seconds (int | None)

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (float)

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.MuleNetworkScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['MULE_NETWORK'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CyclicRingScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['CYCLIC_RING'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.BeneficiaryNetworkScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['BENEFICIARY_NETWORK'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.FanOutScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['FAN_OUT'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.BipartiteNetworkScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['BIPARTITE_NETWORK'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.StackedNetworkScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['STACKED_NETWORK'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.ScatterGatherScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['SCATTER_GATHER'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.GatherScatterScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['GATHER_SCATTER'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.SharedDeviceScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['SHARED_DEVICE_INFRASTRUCTURE'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.SharedIPScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['SHARED_IP_INFRASTRUCTURE'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.DenseCampaignScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['DENSE_CAMPAIGN'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.MerchantCustomerCommunityScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['MERCHANT_CUSTOMER_COMMUNITY'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.RandomAlertControlScenario(**data)[source][source]

Bases: GraphScenarioConfig

Parameters:

  • type (Literal['RANDOM_ALERT_CONTROL'])

  • count (Annotated[int, Ge(ge=0)])

  • member_count (Annotated[int | None, Ge(ge=2)])

  • source_count (Annotated[int | None, Ge(ge=1)])

  • destination_count (Annotated[int | None, Ge(ge=1)])

  • originator_count (Annotated[int | None, Ge(ge=1)])

  • intermediary_count (Annotated[int | None, Ge(ge=1)])

  • beneficiary_count (Annotated[int | None, Ge(ge=1)])

  • customer_count (Annotated[int | None, Ge(ge=1)])

  • merchant_count (Annotated[int | None, Ge(ge=1)])

  • edge_count (Annotated[int | None, Ge(ge=1)])

  • repeat_count (Annotated[int | None, Ge(ge=1)])

  • min_amount (Annotated[float | None, Gt(gt=0)])

  • max_amount (Annotated[float | None, Gt(gt=0)])

  • window_seconds (Annotated[int | None, Gt(gt=0)])

  • institution_scope (Literal['ANY', 'SINGLE_INSTITUTION', 'CROSS_INSTITUTION'])

  • density_threshold (Annotated[float, Ge(ge=0), Le(le=1)])

  • modifiers (tuple[Literal['SHORT_DWELL', 'CROSS_INSTITUTION', 'CAMOUFLAGE_RELATION', 'CAMOUFLAGE_FEATURE', 'STRUCTURAL_HYPEREDGE', 'SEMANTIC_HYPEREDGE'], ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

fraudtwin.config.graph_account_capacity(scenario)[source][source]

Return the number of distinct accounts required by one scenario instance.

Return type:

int

Parameters:

scenario (GraphScenarioConfig)

class fraudtwin.config.GraphConfig(**data)[source][source]

Bases: _StrictModel

Strict controls for M11 graph construction and export (schema v2).

Parameters:

  • schema_version (Literal['2'])

  • enabled (bool)

  • scenarios (tuple[GraphScenario, ...])

  • relationship_window_seconds (int)

  • pattern_window_seconds (int)

  • ring_min_size (int)

  • ring_max_size (int)

  • fan_threshold (int)

  • shared_threshold (int)

  • dwell_threshold_seconds (int)

  • amount_retention_tolerance (float)

  • export_policy (Literal['observable', 'oracle', 'both'])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CampaignDynamicsBinding(**data)[source][source]

Bases: _StrictModel

One deterministic M15 profile applied to every matching M11 campaign.

Parameters:

  • profile (Literal['linear', 'rotating_ring', 'adaptive_network', 'custom'])

  • template (Literal['MULE_NETWORK', 'CYCLIC_RING', 'BENEFICIARY_NETWORK', 'FAN_OUT', 'BIPARTITE_NETWORK', 'STACKED_NETWORK', 'SCATTER_GATHER', 'GATHER_SCATTER', 'SHARED_DEVICE_INFRASTRUCTURE', 'SHARED_IP_INFRASTRUCTURE', 'DENSE_CAMPAIGN', 'MERCHANT_CUSTOMER_COMMUNITY', 'RANDOM_ALERT_CONTROL'] | None)

  • transition_model (str)

  • intensity_model (str)

  • phases (tuple[Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'], ...])

  • phase_durations (dict[Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'], int])

  • transition_probabilities (dict[Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'], dict[~typing.Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'], float]])

  • allowed_rails (tuple[Literal['CARD', 'PIX', 'ACCOUNT_TRANSFER'], ...])

  • max_actions (int)

  • max_actor_joins (int)

  • max_actor_leaves (int)

  • max_mule_rotations (int)

  • max_device_rotations (int)

  • max_splits (int)

  • max_merges (int)

  • max_active_members (int)

  • hawkes_baseline (float)

  • hawkes_excitation (float)

  • hawkes_decay (float)

  • phase_marks (dict[Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'], float])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.CampaignDynamicsConfig(**data)[source][source]

Bases: _StrictModel

Strict opt-in controls for campaign evolution.

Parameters:

  • enabled (bool)

  • bindings (tuple[CampaignDynamicsBinding, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.ExtensionsConfig(**data)[source][source]

Bases: _StrictModel

Opt-in installed extension selections.

Discovery remains local to the process; the configuration stores only stable IDs so source-run hashes do not depend on import paths.

Parameters:

  • enabled (bool)

  • selected (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.config.SimulationRunConfig(**data)[source][source]

Bases: _StrictModel

Top-level configuration accepted by the CLI.

Parameters:

  • simulation (SimulationConfig)

  • population (PopulationConfig)

  • payments (PaymentsConfig)

  • behavior (BehaviorConfig)

  • card_lifecycle (CardLifecycleConfig)

  • pix_lifecycle (PixLifecycleConfig)

  • fraud (FraudConfig)

  • fraud_workflow (FraudWorkflowConfig)

  • labels (LabelObservationConfig)

  • scale (ScaleConfig)

  • quality (QualityConfig)

  • outputs (OutputsConfig)

  • kafka (KafkaConfig)

  • lakehouse (LakehouseConfig)

  • dataset (PointInTimeDatasetConfig)

  • backtest (BacktestConfig)

  • graph (GraphConfig)

  • benchmark (BenchmarkConfig)

  • stress (StressConfig)

  • counterfactual (CounterfactualConfig)

  • campaign_dynamics (CampaignDynamicsConfig)

  • calibration (CalibrationConfig)

  • extensions (ExtensionsConfig)

effective_label_delay_seconds()[source][source]

Return the dataset label delay, falling back to workflow settings.

Return type:

int

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

fraudtwin.config.load_config(path, *, calibration_profile_override=None)[source][source]

Load and validate a YAML configuration file.

Return type:

SimulationRunConfig

Parameters:

  • path (str | Path)

  • calibration_profile_override (Path | None)

fraudtwin.config.config_hash(config, *, include_card_lifecycle=True, include_pix_lifecycle=True, include_dataset=False, include_scale_execution=True)[source][source]

Return a stable SHA-256 hash of the validated configuration.

The optional compatibility modes keep the base payment stream identity unchanged when only lifecycle or M9 dataset settings differ.

Return type:

str

Parameters:

  • config (SimulationRunConfig)

  • include_card_lifecycle (bool)

  • include_pix_lifecycle (bool)

  • include_dataset (bool)

  • include_scale_execution (bool)