fraudtwin.domain.graph#

Domain records for graph nodes, edges, and evidence.

Status: Stable

Classes#

fraudtwin.domain.graph.GraphCampaign

Oracle descriptor for one deterministic scenario instance.

fraudtwin.domain.graph.GraphCampaignMembership

Oracle membership for one generated graph-fraud campaign.

fraudtwin.domain.graph.GraphEvidence

Normalized lineage for a derived relationship.

fraudtwin.domain.graph.GraphHyperedge

Optional higher-order campaign incidence record.

fraudtwin.domain.graph.GraphHyperedgeMembership

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

fraudtwin.domain.graph.GraphPattern

A deterministic structural pattern descriptor.

fraudtwin.domain.graph.NetworkEndpoint

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

Constants and protocols#

Name

Reference

GraphPatternType

fraudtwin.domain.graph.GraphPatternType

Detailed API#

Domain records used by the optional graph layer.

class fraudtwin.domain.graph.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.graph.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.graph.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.graph.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.graph.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.graph.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 (Annotated[int | None, Ge(ge=1)])

  • 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.graph.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].