fraudtwin.difficulty#

Scenario difficulty plans and resolvers.

Status: Experimental

Classes#

fraudtwin.difficulty.ResolvedDifficulty

Complete, hashable M12 difficulty configuration.

fraudtwin.difficulty.ScenarioDifficultyPlan

Resolved transformations for one fraud or graph scenario.

Functions#

fraudtwin.difficulty.apply_difficulty

Apply resolved controls to one scenario without changing its objective.

fraudtwin.difficulty.resolve_difficulty

Resolve a level and its optional per-dimension replacements.

Constants and protocols#

Name

Reference

DIFFICULTY_DIMENSIONS

fraudtwin.difficulty.DIFFICULTY_DIMENSIONS

DIFFICULTY_RESOLVER_VERSION

fraudtwin.difficulty.DIFFICULTY_RESOLVER_VERSION

GRAPH_SCENARIO_CODES

fraudtwin.difficulty.GRAPH_SCENARIO_CODES

GRAPH_SCENARIO_IDS

fraudtwin.difficulty.GRAPH_SCENARIO_IDS

Detailed API#

Deterministic M12 fraud-difficulty resolution and scenario plans.

The difficulty engine intentionally contains no business or ledger logic. It turns a requested level and optional normalized overrides into explicit, auditable parameters consumed by the existing M6 and M11 generators.

class fraudtwin.difficulty.ResolvedDifficulty(**data)[source][source]

Bases: BaseModel

Complete, hashable M12 difficulty configuration.

Parameters:

  • enabled (bool)

  • resolver_version (str)

  • requested_difficulty (int | None)

  • requested_controls (dict[str, float | None])

  • resolved_controls (dict[str, float])

  • scenario_transformations (dict[str, dict[str, object]])

  • effective_configuration_hash (str)

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

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

property level: int | None

Return the requested level for convenient API consumers.

plan(scenario)[source][source]

Return the immutable plan for one scenario.

Return type:

ScenarioDifficultyPlan

Parameters:

scenario (str)

class fraudtwin.difficulty.ScenarioDifficultyPlan(**data)[source][source]

Bases: BaseModel

Resolved transformations for one fraud or graph scenario.

Parameters:

  • scenario (str)

  • amount_similarity (float)

  • behavior_similarity (float)

  • merchant_similarity (float)

  • device_similarity (float)

  • channel_similarity (float)

  • geography_similarity (float)

  • scenario_subtlety (float)

  • noise_hard_negatives (float)

  • prevalence (float)

  • temporal_irregularity (float)

  • graph_structural_subtlety (float)

  • amount_multiplier (float)

  • timing_multiplier (float)

  • hard_negative_multiplier (float)

  • parameter_transformations (dict[str, object])

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

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

fraudtwin.difficulty.apply_difficulty(resolved, scenario, context=None)[source][source]

Apply resolved controls to one scenario without changing its objective.

context is accepted for extension compatibility and is intentionally excluded from the plan hash; all stochastic choices use generator-owned M12 stream names.

Return type:

ScenarioDifficultyPlan

Parameters:
fraudtwin.difficulty.resolve_difficulty(config)[source][source]

Resolve a level and its optional per-dimension replacements.

Return type:

ResolvedDifficulty

Parameters:

config (SimulationRunConfig)