fraudtwin.domain#

Stable domain records for entities, payments, fraud, and labels.

Status: Stable

Classes#

`fraudtwin.domain.Account`	A synthetic customer account held at an institution.
`fraudtwin.domain.BehaviorProfile`	A deterministic, synthetic latent profile for one customer.
`fraudtwin.domain.CampaignActorMembershipChange`
`fraudtwin.domain.CampaignIntensityDecision`
`fraudtwin.domain.CampaignLineage`
`fraudtwin.domain.CampaignPhaseChange`
`fraudtwin.domain.CampaignSourceSnapshot`
`fraudtwin.domain.CampaignStateSnapshot`
`fraudtwin.domain.CampaignTopologyMutation`
`fraudtwin.domain.CampaignTransition`
`fraudtwin.domain.Card`	A synthetic card associated with an account and its customer.
`fraudtwin.domain.CaseReopening`	An immutable reopening event in an observation history.
`fraudtwin.domain.Customer`	A synthetic customer and its valid-time metadata.
`fraudtwin.domain.CustomerDispute`	A customer-submitted dispute event with the common event envelope.
`fraudtwin.domain.DelayedFraudLabel`	A fraud label exposed only after the configured operational evidence.
`fraudtwin.domain.Device`	A synthetic device fingerprint associated with payment activity.
`fraudtwin.domain.EntityStateChange`	Effective-dated state history for reconstructing entity status.
`fraudtwin.domain.FinalObservedLabel`	The final observed projection, without oracle-only history fields.
`fraudtwin.domain.FraudAlert`	An automated alert causally raised from one M6 fraud record.
`fraudtwin.domain.FraudCase`	An investigation opened from an alert and its delayed label state.
`fraudtwin.domain.FraudCaseConfirmation`	A case decision, recorded separately from the fraud ground truth.
`fraudtwin.domain.FraudRecord`	One scenario-linked truth record, including legitimate lookalikes.
`fraudtwin.domain.GraphCampaign`	Oracle descriptor for one deterministic scenario instance.
`fraudtwin.domain.GraphCampaignMembership`	Oracle membership for one generated graph-fraud campaign.
`fraudtwin.domain.GraphEvidence`	Normalized lineage for a derived relationship.
`fraudtwin.domain.GraphHyperedge`	Optional higher-order campaign incidence record.
`fraudtwin.domain.GraphHyperedgeMembership`	Membership of an entity in a higher-order graph relationship.
`fraudtwin.domain.GraphPattern`	A deterministic structural pattern descriptor.
`fraudtwin.domain.Institution`	A synthetic bank, PSP, issuer, or acquirer.
`fraudtwin.domain.LabelCorrection`	An immutable correction from one observed label version to another.
`fraudtwin.domain.LabelObservation`	A complete append-only observation history for one fraud record.
`fraudtwin.domain.LabelVersion`	One immutable version of the operational label visible at a time.
`fraudtwin.domain.LedgerEntry`	A posted, double-entry-compatible ledger record.
`fraudtwin.domain.Merchant`	A synthetic merchant acquired by an institution.
`fraudtwin.domain.NetworkEndpoint`	An opt-in synthetic network endpoint; absent from legacy runs.
`fraudtwin.domain.ObservationProvenance`	Reproducibility metadata for one observation policy application.
`fraudtwin.domain.Payment`	The business object represented by one payment.
`fraudtwin.domain.PaymentEvent`	A common event envelope for a generated payment event.
`fraudtwin.domain.PixKey`	A synthetic PIX-like payment key.

Functions#

`fraudtwin.domain.validate_card_lifecycle`	Reject card event sequences that cannot occur in the card rail.
`fraudtwin.domain.validate_fraud_workflow`	Validate M7 references, causal chains, and temporal availability rules.
`fraudtwin.domain.validate_ledger`	Validate posted transfer entries against payments and account balances.
`fraudtwin.domain.validate_payment_lifecycle`	Validate the lifecycle for whichever supported rail owns a payment.
`fraudtwin.domain.validate_pix_lifecycle`	Reject PIX event sequences that cannot occur on the PIX rail.

Constants and protocols#

Name	Reference
`CARD_LIFECYCLE_EVENT_TYPES`	`fraudtwin.domain.CARD_LIFECYCLE_EVENT_TYPES`
`CardLifecycleEventType`	`fraudtwin.domain.CardLifecycleEventType`
`FraudRecordType`	`fraudtwin.domain.FraudRecordType`
`FraudScenarioType`	`fraudtwin.domain.FraudScenarioType`
`FraudSignalEventType`	`fraudtwin.domain.FraudSignalEventType`
`FraudWorkflowEventType`	`fraudtwin.domain.FraudWorkflowEventType`
`GraphPatternType`	`fraudtwin.domain.GraphPatternType`
`InvestigationOutcome`	`fraudtwin.domain.InvestigationOutcome`
`LabelState`	`fraudtwin.domain.LabelState`
`ObservedLabelValue`	`fraudtwin.domain.ObservedLabelValue`
`PAYMENT_EVENT_CONTRACT_VERSION`	`fraudtwin.domain.PAYMENT_EVENT_CONTRACT_VERSION`
`PIX_LIFECYCLE_EVENT_TYPES`	`fraudtwin.domain.PIX_LIFECYCLE_EVENT_TYPES`
`PaymentEventType`	`fraudtwin.domain.PaymentEventType`
`PaymentRail`	`fraudtwin.domain.PaymentRail`
`PaymentType`	`fraudtwin.domain.PaymentType`
`PixLifecycleEventType`	`fraudtwin.domain.PixLifecycleEventType`

Detailed API#

Immutable domain entities used by the simulator.

class fraudtwin.domain.Account(**data)[source][source]

Bases: _EntityModel

A synthetic customer account held at an institution.

Parameters:

account_id (str)
customer_id (str)
institution_id (str)
account_type (Literal['CHECKING', 'PAYMENT_ACCOUNT', 'CREDIT_CARD_ACCOUNT', 'SAVINGS', 'PERSONAL_LOAN', 'BUSINESS_ACCOUNT'])
currency (str)
opening_date (datetime)
closing_date (datetime | None)
status (Literal['PENDING', 'ACTIVE', 'RESTRICTED', 'BLOCKED', 'CLOSED'])
credit_limit (float)
available_balance (float)
ledger_balance (float)
overdraft_limit (float)
created_at (datetime)
updated_at (datetime)
valid_from (datetime)
valid_to (datetime | None)
system_from (datetime)
system_to (datetime | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CampaignActorMembershipChange(**data)[source][source]

Bases: _EntityModel

Parameters:

membership_change_id (str)
campaign_id (str)
actor_id (str)
actor_type (Literal['ACCOUNT', 'CUSTOMER', 'CARD', 'DEVICE', 'MERCHANT'])
role (str)
action (Literal['JOIN', 'LEAVE', 'ROTATE_IN', 'ROTATE_OUT'])
occurred_at (datetime)
valid_from (datetime)
valid_to (datetime | None)
source_entity_id (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CampaignIntensityDecision(**data)[source][source]

Bases: _EntityModel

Parameters:

intensity_decision_id (str)
campaign_id (str)
phase (Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'])
decision_at (datetime)
event_rate (float)
mark (float)
model_name (str)
stream_id (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CampaignLineage(**data)[source][source]

Bases: _EntityModel

Parameters:

lineage_id (str)
campaign_id (str)
parent_campaign_ids (tuple[str, ...])
source_entity_ids (tuple[str, ...])
source_event_ids (tuple[str, ...])
source_payment_ids (tuple[str, ...])
derived_entity_ids (tuple[str, ...])
derived_event_ids (tuple[str, ...])
derived_payment_ids (tuple[str, ...])
derived_at (datetime)
reason (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CampaignPhaseChange(**data)[source][source]

Bases: _EntityModel

Parameters:

phase_change_id (str)
campaign_id (str)
transition_id (str)
phase (Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'])
valid_from (datetime)
valid_to (datetime | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CampaignSourceSnapshot(**data)[source][source]

Bases: _EntityModel

Parameters:

source_snapshot_id (str)
campaign_id (str)
source_run_id (str)
captured_at (datetime)
source_campaign_ids (tuple[str, ...])
source_entity_ids (tuple[str, ...])
source_event_ids (tuple[str, ...])
source_payment_ids (tuple[str, ...])
configuration_hash (str)
schema_fingerprint (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CampaignStateSnapshot(**data)[source][source]

Bases: _EntityModel

Parameters:

snapshot_id (str)
campaign_id (str)
phase (Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'])
intensity (float)
active_actor_ids (tuple[str, ...])
active_device_ids (tuple[str, ...])
valid_from (datetime)
valid_to (datetime | None)
transition_id (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CampaignTopologyMutation(**data)[source][source]

Bases: _EntityModel

Parameters:

topology_mutation_id (str)
campaign_id (str)
mutation_type (Literal['MULE_ROTATION', 'DEVICE_ROTATION', 'RING_SPLIT', 'RING_MERGE', 'CROSS_RAIL', 'HYPEREDGE_ADD'])
occurred_at (datetime)
source_member_ids (tuple[str, ...])
derived_member_ids (tuple[str, ...])
source_payment_ids (tuple[str, ...])
derived_payment_ids (tuple[str, ...])
reason (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CampaignTransition(**data)[source][source]

Bases: _EntityModel

Parameters:

transition_id (str)
campaign_id (str)
from_phase (Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'])
to_phase (Literal['compromise', 'setup', 'transfer', 'cash_out', 'dormant', 'closed'])
occurred_at (datetime)
reason (str)
model_name (str)
source_snapshot_id (str | None)
stream_id (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.Card(**data)[source][source]

Bases: _EntityModel

A synthetic card associated with an account and its customer.

Parameters:

card_id (str)
account_id (str)
customer_id (str)
scheme (Literal['VISA', 'MASTERCARD', 'OTHER'])
card_type (Literal['DEBIT', 'CREDIT', 'PREPAID'])
status (Literal['PENDING', 'ACTIVE', 'BLOCKED', 'EXPIRED', 'CLOSED'])
issued_at (datetime)
expires_at (datetime)
country (str)
network_token_enabled (bool)
contactless_enabled (bool)
online_enabled (bool)
international_enabled (bool)
daily_limit (float)
transaction_limit (float)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.Customer(**data)[source][source]

Bases: _EntityModel

A synthetic customer and its valid-time metadata.

Parameters:

customer_id (str)
customer_type (Literal['PERSONAL', 'BUSINESS'])
customer_status (Literal['PENDING', 'ACTIVE', 'RESTRICTED', 'BLOCKED', 'INACTIVE', 'CLOSED'])
date_of_birth (date)
country (str)
city (str)
registration_date (datetime)
risk_segment (str)
income_band (str)
occupation_category (str)
preferred_channels (tuple[str, ...])
created_at (datetime)
updated_at (datetime)
valid_from (datetime)
valid_to (datetime | None)
system_from (datetime)
system_to (datetime | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.Device(**data)[source][source]

Bases: _EntityModel

A synthetic device fingerprint associated with payment activity.

Parameters:

device_id (str)
device_type (Literal['MOBILE', 'DESKTOP', 'TABLET', 'POS_TERMINAL', 'ATM'])
os_family (str)
browser_family (str)
first_seen_at (datetime)
last_seen_at (datetime)
trusted (bool)
device_fingerprint (str)
risk_score (float)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.EntityStateChange(**data)[source][source]

Bases: _EntityModel

Effective-dated state history for reconstructing entity status.

Parameters:

entity_id (str)
entity_type (Literal['CUSTOMER', 'ACCOUNT'])
from_status (str)
to_status (str)
effective_at (datetime)
system_from (datetime)
system_to (datetime | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.Institution(**data)[source][source]

Bases: _EntityModel

A synthetic bank, PSP, issuer, or acquirer.

Parameters:

institution_id (str)
institution_type (Literal['BANK', 'PSP', 'ISSUER', 'ACQUIRER', 'DIGITAL_BANK', 'PAYMENT_INSTITUTION'])
country (str)
institution_code (str)
risk_profile (str)
processing_latency_profile (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.Merchant(**data)[source][source]

Bases: _EntityModel

A synthetic merchant acquired by an institution.

Parameters:

merchant_id (str)
merchant_name (str)
merchant_category_code (str)
country (str)
city (str)
risk_segment (str)
acquirer_id (str)
online_only (bool)
created_at (datetime)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.PixKey(**data)[source][source]

Bases: _EntityModel

A synthetic PIX-like payment key.

Parameters:

pix_key_id (str)
account_id (str)
customer_id (str)
institution_id (str)
key_type (Literal['CPF_LIKE', 'PHONE', 'EMAIL', 'RANDOM', 'BUSINESS_ID_LIKE'])
key_hash_or_synthetic_value (str)
created_at (datetime)
status (Literal['ACTIVE', 'INACTIVE', 'BLOCKED'])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.BehaviorProfile(**data)[source][source]

Bases: _EntityModel

A deterministic, synthetic latent profile for one customer.

Parameters:

behavior_profile_id (str)
customer_id (str)
spending_level (Literal['LOW', 'MEDIUM', 'HIGH'])
typical_payment_hours (tuple[int, ...])
hour_weights (tuple[float, ...])
weekday_weights (tuple[float, ...])
typical_countries (tuple[str, ...])
merchant_category_preferences (tuple[str, ...])
merchant_category_weights (tuple[float, ...])
monthly_income (float)
monthly_spending_budget (float)
card_vs_transfer_preference (float)
online_purchase_rate (float)
travel_frequency (float)
preferred_device_ids (tuple[str, ...])
trusted_device_count (int)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.FraudRecord(**data)[source][source]

Bases: _EntityModel

One scenario-linked truth record, including legitimate lookalikes.

Parameters:

fraud_record_id (str)
record_type (Literal['FRAUD', 'HARD_NEGATIVE'])
scenario_id (str)
scenario_type (str)
fraud_truth (bool)
trigger (str)
reason (str)
customer_id (str)
account_id (str | None)
card_id (str | None)
device_id (str | None)
merchant_id (str | None)
payment_id (str)
event_id (str)
occurred_at (datetime)
amount (float)
currency (str)
correlation_id (str)
causation_id (str | None)
affected_entity_ids (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.NetworkEndpoint(**data)[source][source]

Bases: _EntityModel

An opt-in synthetic network endpoint; absent from legacy runs.

Parameters:

endpoint_id (str)
endpoint_type (Literal['IP', 'NETWORK'])
address_hash (str)
first_seen_at (datetime)
last_seen_at (datetime)
valid_from (datetime)
valid_to (datetime | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.GraphCampaignMembership(**data)[source][source]

Bases: _EntityModel

Oracle membership for one generated graph-fraud campaign.

Parameters:

campaign_id (str)
pattern_type (Literal['MULE_NETWORK', 'CYCLIC_RING', 'BENEFICIARY_NETWORK', 'SHARED_DEVICE_INFRASTRUCTURE', 'SHARED_IP_INFRASTRUCTURE', 'FAN_IN', 'FAN_OUT', 'SHORT_MONEY_DWELL', 'DENSE_CAMPAIGN', 'MERCHANT_CUSTOMER_COMMUNITY', 'BIPARTITE_NETWORK', 'STACKED_NETWORK', 'SCATTER_GATHER', 'GATHER_SCATTER', 'RANDOM_ALERT_CONTROL'])
member_id (str)
member_type (str)
role (str)
valid_from (datetime)
valid_to (datetime | None)
source_event_id (str | None)
payment_id (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.GraphCampaign(**data)[source][source]

Bases: _EntityModel

Oracle descriptor for one deterministic scenario instance.

Parameters:

campaign_id (str)
scenario_type (Literal['MULE_NETWORK', 'CYCLIC_RING', 'BENEFICIARY_NETWORK', 'SHARED_DEVICE_INFRASTRUCTURE', 'SHARED_IP_INFRASTRUCTURE', 'FAN_IN', 'FAN_OUT', 'SHORT_MONEY_DWELL', 'DENSE_CAMPAIGN', 'MERCHANT_CUSTOMER_COMMUNITY', 'BIPARTITE_NETWORK', 'STACKED_NETWORK', 'SCATTER_GATHER', 'GATHER_SCATTER', 'RANDOM_ALERT_CONTROL'])
scenario_code (str)
truth_label (Literal['FRAUD', 'CONTROL'])
valid_from (datetime)
valid_to (datetime)
participant_ids (tuple[str, ...])
modifiers (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.GraphEvidence(**data)[source][source]

Bases: _EntityModel

Normalized lineage for a derived relationship.

Parameters:

evidence_id (str)
edge_id (str | None)
evidence_type (str)
resource_id (str | None)
source_event_id (str | None)
payment_id (str | None)
observed_at (datetime)
available_at (datetime | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.GraphHyperedge(**data)[source][source]

Bases: _EntityModel

Optional higher-order campaign incidence record.

Parameters:

hyperedge_id (str)
hyperedge_type (Literal['STRUCTURAL', 'SEMANTIC'])
campaign_id (str | None)
pattern_id (str | None)
valid_from (datetime)
valid_to (datetime | None)
source_event_ids (tuple[str, ...])
payment_ids (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.GraphHyperedgeMembership(**data)[source][source]

Bases: _EntityModel

Membership of an entity in a higher-order graph relationship.

Parameters:

hyperedge_id (str)
member_id (str)
member_type (str)
role (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.GraphPattern(**data)[source][source]

Bases: _EntityModel

A deterministic structural pattern descriptor.

Parameters:

pattern_id (str)
pattern_type (Literal['MULE_NETWORK', 'CYCLIC_RING', 'BENEFICIARY_NETWORK', 'SHARED_DEVICE_INFRASTRUCTURE', 'SHARED_IP_INFRASTRUCTURE', 'FAN_IN', 'FAN_OUT', 'SHORT_MONEY_DWELL', 'DENSE_CAMPAIGN', 'MERCHANT_CUSTOMER_COMMUNITY', 'BIPARTITE_NETWORK', 'STACKED_NETWORK', 'SCATTER_GATHER', 'GATHER_SCATTER', 'RANDOM_ALERT_CONTROL'])
campaign_id (str | None)
detected_at (datetime)
window_from (datetime)
window_to (datetime)
member_ids (tuple[str, ...])
source_event_ids (tuple[str, ...])
payment_ids (tuple[str, ...])
threshold (int | None)
observed_value (float | None)
invariant_status (Literal['PASS', 'UNAVAILABLE', 'FAIL'])
truth_label (Literal['FRAUD', 'CONTROL'])
scenario_code (str | None)
reason (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.FraudAlert(**data)[source][source]

Bases: _EntityModel

An automated alert causally raised from one M6 fraud record.

Parameters:

fraud_alert_id (str)
alert_type (Literal['AUTOMATED_SCENARIO_ALERT'])
severity (Literal['LOW', 'MEDIUM', 'HIGH'])
customer_id (str)
account_id (str | None)
card_id (str | None)
device_id (str | None)
merchant_id (str | None)
payment_id (str)
event_id (str)
fraud_record_id (str)
scenario_id (str)
scenario_type (str)
trigger (str)
reason (str)
alert_created_at (datetime)
amount (float)
currency (str)
correlation_id (str)
causation_id (str)
simulation_run_id (str | None)
affected_entity_ids (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.FraudCase(**data)[source][source]

Bases: _EntityModel

An investigation opened from an alert and its delayed label state.

Parameters:

fraud_case_id (str)
fraud_alert_id (str)
customer_id (str)
account_id (str | None)
card_id (str | None)
device_id (str | None)
merchant_id (str | None)
payment_id (str)
event_id (str)
fraud_record_id (str)
scenario_id (str)
scenario_type (str)
fraud_truth (bool | None)
fraud_occurred_at (datetime)
alert_created_at (datetime)
case_opened_at (datetime)
case_closed_at (datetime | None)
fraud_confirmed_at (datetime | None)
label_available_at (datetime | None)
investigation_outcome (Literal['CONFIRMED_FRAUD', 'FALSE_POSITIVE', 'CUSTOMER_DISPUTE', 'UNRESOLVED', 'LEGITIMATE'])
loss_amount (float)
recovered_amount (float)
amount (float)
currency (str)
correlation_id (str)
causation_id (str)
simulation_run_id (str | None)
affected_entity_ids (tuple[str, ...])
case_reopened_at (datetime | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.FraudCaseConfirmation(**data)[source][source]

Bases: _EntityModel

A case decision, recorded separately from the fraud ground truth.

Parameters:

confirmation_id (str)
fraud_case_id (str)
fraud_alert_id (str)
customer_id (str)
payment_id (str)
event_id (str)
fraud_record_id (str)
scenario_id (str)
scenario_type (str)
fraud_truth (bool | None)
confirmed_at (datetime)
investigation_outcome (Literal['CONFIRMED_FRAUD', 'FALSE_POSITIVE', 'CUSTOMER_DISPUTE', 'UNRESOLVED', 'LEGITIMATE'])
amount (float)
currency (str)
correlation_id (str)
causation_id (str)
simulation_run_id (str | None)
affected_entity_ids (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CustomerDispute(**data)[source][source]

Bases: _EntityModel

A customer-submitted dispute event with the common event envelope.

Parameters:

event_id (str)
event_type (Literal['CUSTOMER_DISPUTE_SUBMITTED'])
event_version (int)
fraud_case_id (str)
fraud_alert_id (str)
fraud_record_id (str)
underlying_event_id (str)
payment_id (str)
customer_id (str)
account_id (str | None)
card_id (str | None)
device_id (str | None)
merchant_id (str | None)
event_time (datetime)
source_created_at (datetime)
source_available_at (datetime)
ingested_at (datetime)
processed_at (datetime)
producer (str)
source_system (str)
schema_version (str)
correlation_id (str)
causation_id (str)
simulation_run_id (str | None)
scenario_id (str)
scenario_type (str)
payment_rail (str)
payment_type (str)
amount (float)
currency (str)
affected_entity_ids (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.DelayedFraudLabel(**data)[source][source]

Bases: _EntityModel

A fraud label exposed only after the configured operational evidence.

Parameters:

label_id (str)
fraud_case_id (str)
fraud_alert_id (str)
fraud_record_id (str)
customer_id (str)
payment_id (str)
event_id (str)
scenario_id (str)
scenario_type (str)
label (Literal['FRAUD', 'LEGITIMATE'])
fraud_truth (bool | None)
fraud_occurred_at (datetime)
fraud_confirmed_at (datetime | None)
dispute_event_at (datetime | None)
label_available_at (datetime)
investigation_outcome (Literal['CONFIRMED_FRAUD', 'FALSE_POSITIVE', 'CUSTOMER_DISPUTE', 'UNRESOLVED', 'LEGITIMATE'])
amount (float)
currency (str)
correlation_id (str)
causation_id (str)
simulation_run_id (str | None)
affected_entity_ids (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.LedgerEntry(**data)[source][source]

Bases: _EntityModel

A posted, double-entry-compatible ledger record.

Parameters:

ledger_entry_id (str)
account_id (str)
payment_id (str)
entry_type (Literal['DEBIT', 'CREDIT'])
amount (float)
currency (str)
occurred_at (datetime)
event_id (str)
effective_at (datetime)
posted_at (datetime)
balance_after (float)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.Payment(**data)[source][source]

Bases: _EntityModel

The business object represented by one payment.

Parameters:

payment_id (str)
payment_rail (Literal['CARD', 'PIX', 'ACCOUNT_TRANSFER'])
payment_type (Literal['PURCHASE', 'TRANSFER'])
payer_account_id (str)
payee_account_id (str | None)
merchant_id (str | None)
card_id (str | None)
amount (float)
currency (str)
initiated_at (datetime)
current_status (Literal['AUTHORIZED', 'DECLINED', 'CAPTURED', 'CLEARED', 'SETTLED', 'REVERSED', 'REFUNDED', 'COMPLETED', 'REJECTED', 'TIMED_OUT', 'RECEIVED', 'RETURNED', 'CHARGEBACK_RESOLVED'])
payer_institution_id (str | None)
payee_institution_id (str | None)
payer_pix_key_id (str | None)
payee_pix_key_id (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.PaymentEvent(**data)[source][source]

Bases: _EntityModel

A common event envelope for a generated payment event.

Parameters:

event_id (str)
event_type (Literal['CARD_PAYMENT_INITIATED', 'CARD_AUTHORIZATION_REQUESTED', 'CARD_AUTHORIZED', 'CARD_DECLINED', 'CARD_REVERSED', 'CARD_CAPTURED', 'CARD_CLEARED', 'CARD_SETTLED', 'CARD_REFUNDED', 'CARD_CHARGEBACK_CREATED', 'CARD_CHARGEBACK_RESOLVED', 'PIX_INITIATED', 'PIX_VALIDATED', 'PIX_AUTHORIZED', 'PIX_SUBMITTED', 'PIX_TIMEOUT', 'PIX_SETTLED', 'PIX_RECEIVED', 'PIX_REJECTED', 'PIX_RETURN_REQUESTED', 'PIX_RETURNED', 'FRAUD_AUTHENTICATION_SUSPICIOUS', 'FRAUD_PROFILE_CHANGED', 'FRAUD_BENEFICIARY_ADDED', 'TRANSFER_COMPLETED'])
event_version (int)
payment_id (str)
customer_id (str)
account_id (str)
event_time (datetime)
source_created_at (datetime)
source_available_at (datetime)
ingested_at (datetime)
processed_at (datetime)
producer (str)
source_system (str)
schema_version (str)
correlation_id (str)
causation_id (str | None)
simulation_run_id (str)
scenario_id (str | None)
payment_rail (Literal['CARD', 'PIX', 'ACCOUNT_TRANSFER'])
payment_type (Literal['PURCHASE', 'TRANSFER'])
payee_account_id (str | None)
merchant_id (str | None)
card_id (str | None)
device_id (str | None)
ip_id (str | None)
transport_partition (int | None)
online (bool)
amount (float)
currency (str)
scenario_type (str | None)
scenario_trigger (str | None)
scenario_reason (str | None)
fraud_record_id (str | None)
affected_entity_ids (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

fraudtwin.domain.validate_card_lifecycle(payment, events)[source][source]

Reject card event sequences that cannot occur in the card rail.

Return type:

None

Parameters:

payment (Payment)
events (tuple[PaymentEvent, ...])

fraudtwin.domain.validate_pix_lifecycle(payment, events)[source][source]

Reject PIX event sequences that cannot occur on the PIX rail.

Return type:

None

Parameters:

payment (Payment)
events (tuple[PaymentEvent, ...])

fraudtwin.domain.validate_payment_lifecycle(payment, events)[source][source]

Validate the lifecycle for whichever supported rail owns a payment.

Return type:

None

Parameters:

payment (Payment)
events (tuple[PaymentEvent, ...])

fraudtwin.domain.validate_ledger(accounts, payments, events, entries)[source][source]

Validate posted transfer entries against payments and account balances.

The ledger uses each account’s opening ledger balance as its deterministic starting point and checks every subsequent running balance.

Return type:

None

Parameters:

accounts (tuple[Account, ...])
payments (tuple[Payment, ...])
events (tuple[PaymentEvent, ...])
entries (tuple[LedgerEntry, ...])

fraudtwin.domain.validate_fraud_workflow(alerts, cases, confirmations, disputes, labels, *, customer_ids=frozenset(), account_ids=frozenset(), card_ids=frozenset(), device_ids=frozenset(), merchant_ids=frozenset(), payment_ids=frozenset(), event_ids=frozenset(), fraud_record_ids=frozenset(), all_entity_ids=frozenset(), fraud_truth_by_record=None, fraud_records_by_id=None)[source][source]

Validate M7 references, causal chains, and temporal availability rules.

Return type:

None

Parameters:

alerts (tuple[FraudAlert, ...])
cases (tuple[FraudCase, ...])
confirmations (tuple[FraudCaseConfirmation, ...])
disputes (tuple[CustomerDispute, ...])
labels (tuple[DelayedFraudLabel, ...])
customer_ids (frozenset[str])
account_ids (frozenset[str])
card_ids (frozenset[str])
device_ids (frozenset[str])
merchant_ids (frozenset[str])
payment_ids (frozenset[str])
event_ids (frozenset[str])
fraud_record_ids (frozenset[str])
all_entity_ids (frozenset[str])
fraud_truth_by_record (Mapping[str, bool] | None)
fraud_records_by_id (Mapping[str, FraudRecord] | None)

class fraudtwin.domain.FinalObservedLabel(**data)[source][source]

Bases: _EntityModel

The final observed projection, without oracle-only history fields.

Parameters:

observation_id (str)
fraud_record_id (str)
payment_id (str)
observed_label (Literal['FRAUD', 'LEGITIMATE'] | None)
label_state (Literal['UNOBSERVED', 'PRELIMINARY', 'CONFIRMED', 'CORRECTED', 'REOPENED'])
label_version (int)
label_available_at (datetime | None)
label_corrected_at (datetime | None)
case_reopened_at (datetime | None)
investigation_selected (bool)
simulation_run_id (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.CaseReopening(**data)[source][source]

Bases: _EntityModel

An immutable reopening event in an observation history.

Parameters:

reopening_id (str)
observation_id (str)
label_version (int)
reopened_at (datetime)
reason (str)
causation_id (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.LabelCorrection(**data)[source][source]

Bases: _EntityModel

An immutable correction from one observed label version to another.

Parameters:

correction_id (str)
observation_id (str)
from_version (int)
to_version (int)
corrected_at (datetime)
observed_label (Literal['FRAUD', 'LEGITIMATE'])
truth_label (bool)
causation_id (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.LabelObservation(**data)[source][source]

Bases: _EntityModel

A complete append-only observation history for one fraud record.

Parameters:

observation_id (str)
fraud_record_id (str)
payment_id (str)
truth_label (bool)
investigation_selected (bool)
versions (tuple[LabelVersion, ...])
final_label_version (int)
policy_hash (str)
stream_ids (tuple[str, ...])
simulation_run_id (str | None)
corrections (tuple[LabelCorrection, ...])
reopenings (tuple[CaseReopening, ...])
provenance (ObservationProvenance | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.LabelVersion(**data)[source][source]

Bases: _EntityModel

One immutable version of the operational label visible at a time.

Parameters:

label_version_id (str)
fraud_record_id (str)
payment_id (str)
case_id (str | None)
truth_label (bool)
observed_label (Literal['FRAUD', 'LEGITIMATE'] | None)
label_state (Literal['UNOBSERVED', 'PRELIMINARY', 'CONFIRMED', 'CORRECTED', 'REOPENED'])
investigation_selected (bool)
label_version (int)
label_available_at (datetime | None)
label_corrected_at (datetime | None)
case_reopened_at (datetime | None)
reason (str)
causation_id (str)
simulation_run_id (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.domain.ObservationProvenance(**data)[source][source]

Bases: _EntityModel

Reproducibility metadata for one observation policy application.

Parameters:

policy_hash (str)
stream_ids (tuple[str, ...])
source_run_id (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].