Add evaluation harness and hardness knob for detector benchmarking

The README frames this generator as a way to benchmark fraud detectors, but it
ships no scoring and the default data is easy to separate by trivial heuristics
(single sentinel fraud amount, disjoint rings, no legitimate cycles).

This change is additive and backward compatible (low hardness reproduces the
original behaviour exactly):

- evaluate.py + gen-fraud-graph-evaluate CLI: precision/recall/F1 at account and
  ring level against fraud_cases.csv, with a confusion summary.
- --hardness {low,medium,high}: jitters fraud amounts, overlaps rings, and
  injects decoy legitimate high-value cycles so amount-thresholding and
  cycle-topology each fail.
- tests/test_evaluate.py: 12 tests (exact metrics on a fixture, ring threshold,
  loaders, hardness presets, generator smoke test). Full suite 54 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: fabio-rovai

pyproject.toml

@@ -70,6 +70,7 @@ Changelog = "https://github.com/SantanderAI/gen-fraud-graph/blob/main/CHANGELOG.
 
 [project.scripts]
 gen-fraud-graph = "gen_fraud_graph.cli:main"
+gen-fraud-graph-evaluate = "gen_fraud_graph.evaluate:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

src/gen_fraud_graph/cli.py

@@ -79,6 +79,16 @@ def main(argv: list[str] | None = None) -> None:
         default=False,
         help="Skip account generation (useful when resuming).",
     )
+    parser.add_argument(
+        "--hardness",
+        type=str,
+        choices=["low", "medium", "high"],
+        default="low",
+        help="Difficulty preset controlling how hard the fraud data is to "
+        "separate by trivial heuristics. 'low' (default) is backward "
+        "compatible. 'medium'/'high' jitter fraud amounts, overlap rings, and "
+        "inject decoy legitimate high-value cycles. Default: low.",
+    )
 
     args = parser.parse_args(argv)
 
@@ -91,6 +101,7 @@ def main(argv: list[str] | None = None) -> None:
         output_format=args.format,
         compress=args.compress,
         output_dir=args.output,
+        hardness=args.hardness,
     )
 
     generator = FraudGraphGenerator(cfg)

src/gen_fraud_graph/config.py

@@ -6,6 +6,24 @@
 from dataclasses import dataclass, field
 from typing import Literal
 
+Hardness = Literal["low", "medium", "high"]
+
+# Difficulty presets controlling how hard the data is to separate by trivial
+# heuristics.  ``low`` reproduces the original behaviour exactly (a single
+# sentinel fraud amount, disjoint rings, no decoy cycles), so defaults are
+# backward compatible.
+_HARDNESS_PRESETS: dict[str, dict[str, float]] = {
+    # amount_jitter:   relative +/- jitter applied to the fraud sentinel amount
+    #                  (0.0 means every fraud edge keeps the exact sentinel).
+    # ring_overlap:    probability that a new ring reuses (shares) an account
+    #                  from an existing ring, creating overlapping rings.
+    # decoy_ratio:     number of decoy legitimate high-value cycles to inject,
+    #                  expressed as a fraction of the fraud-ring count.
+    "low": {"amount_jitter": 0.0, "ring_overlap": 0.0, "decoy_ratio": 0.0},
+    "medium": {"amount_jitter": 0.25, "ring_overlap": 0.25, "decoy_ratio": 0.5},
+    "high": {"amount_jitter": 0.5, "ring_overlap": 0.5, "decoy_ratio": 1.0},
+}
+
 
 @dataclass
 class Config:
@@ -26,6 +44,13 @@ class Config:
             bulk-load headers).
         compress: Whether to ZIP the output CSV files.
         output_dir: Destination directory for generated files.
+        hardness: Difficulty preset (``"low"``, ``"medium"`` or ``"high"``)
+            controlling how hard the fraud data is to separate by trivial
+            heuristics.  ``"low"`` (the default) is backward compatible: fraud
+            edges keep a single sentinel amount, rings are disjoint, and no
+            decoy cycles are injected.  Higher levels jitter fraud amounts,
+            overlap rings, and inject legitimate high-value (decoy) cycles so
+            that pure amount-thresholding and pure cycle-topology each fail.
     """
 
     scale_factor: float = 1.0
@@ -38,13 +63,26 @@ class Config:
     output_format: Literal["csv", "neptune"] = "csv"
     compress: bool = False
     output_dir: str = "data"
+    hardness: Hardness = "low"
 
     # Derived — computed in __post_init__
     num_accounts: int = field(init=False)
     num_transactions: int = field(init=False)
+    amount_jitter: float = field(init=False)
+    ring_overlap: float = field(init=False)
+    decoy_ratio: float = field(init=False)
 
     def __post_init__(self) -> None:
         self.num_accounts = int(10_000_000 * self.scale_factor)
         self.num_transactions = int(90_000_000 * self.scale_factor)
         if self.num_fraud_rings is None:
             self.num_fraud_rings = max(10, int(1000 * self.scale_factor))
+
+        if self.hardness not in _HARDNESS_PRESETS:
+            raise ValueError(
+                f"hardness must be one of {sorted(_HARDNESS_PRESETS)}, got {self.hardness!r}"
+            )
+        preset = _HARDNESS_PRESETS[self.hardness]
+        self.amount_jitter = preset["amount_jitter"]
+        self.ring_overlap = preset["ring_overlap"]
+        self.decoy_ratio = preset["decoy_ratio"]