fraudtwin.domain.labels#

Domain records for label maturity and observation.

Status: Stable

Classes#

fraudtwin.domain.labels.CaseReopening

An immutable reopening event in an observation history.

fraudtwin.domain.labels.FinalObservedLabel

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

fraudtwin.domain.labels.LabelCorrection

An immutable correction from one observed label version to another.

fraudtwin.domain.labels.LabelObservation

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

fraudtwin.domain.labels.LabelVersion

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

fraudtwin.domain.labels.ObservationProvenance

Reproducibility metadata for one observation policy application.

Constants and protocols#

Name

Reference

LabelState

fraudtwin.domain.labels.LabelState

ObservedLabelValue

fraudtwin.domain.labels.ObservedLabelValue

Detailed API#

Immutable label-observation records.

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

  • 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.labels.CaseReopening(**data)[source][source]

Bases: _EntityModel

An immutable reopening event in an observation history.

Parameters:

  • reopening_id (str)

  • observation_id (str)

  • label_version (Annotated[int, Ge(ge=1)])

  • 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.labels.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 (Annotated[int, Ge(ge=0)])

  • to_version (Annotated[int, Ge(ge=1)])

  • 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.labels.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 (Annotated[int, Ge(ge=0)])

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

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

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