Fraudstruct

Fraudstruct is a Python research prototype for transaction-monitoring rules, graph-derived features, and controlled AML scenario generation. The current release is not a production banking authorization service. It has no external feature store, deployment hardening, concurrency benchmark, or verified end-to-end bank SLA.

S/K/W streaming detector

StreamingStructuringDetector incrementally looks for a two-hop flow:

source ── split transfers ──> K mule accounts ── onward transfers ──> beneficiary

An alert requires all configured conditions: at least min_mules distinct intermediaries, a source-to-mule total at or above minimum_total_amount (S), transactions inside window_seconds (W), each counted leg no larger than max_leg_amount, and source-to-mule versus mule-to-beneficiary totals within flow_conservation_tolerance. Optionally, target_total_amount requires the observed S to be within target_amount_tolerance of a known target. These are research parameters; set values for the relevant currency, jurisdiction, and operating policy.

The detector retains only active-window edge events and requires nondecreasing event timestamps. It raises a capacity error instead of silently dropping evidence when max_tracked_pairs or max_active_events is reached. The streaming API updates a bounded recent graph for later training, but does not recompute graph features or run a model for each transaction. Account risk scores produced by cold-path work are looked up from an in-memory cache and must be refreshed explicitly.

Local installation

pip install -e .

Configure and run the API

The defaults below are demonstration values in the transaction amount's units. They are not regulatory thresholds or validated bank settings.

$env:FRAUDSTRUCT_WINDOW_SECONDS = "3600"
$env:FRAUDSTRUCT_MIN_MULES = "3"
$env:FRAUDSTRUCT_MIN_TOTAL_AMOUNT = "300000"
$env:FRAUDSTRUCT_MAX_LEG_AMOUNT = "100000"
$env:FRAUDSTRUCT_FLOW_TOLERANCE = "0.10"
uvicorn fraudstruct.stream.api:app --host 127.0.0.1 --port 8000

POST /v1/evaluate accepts transaction_id, source_account, destination_account, amount, and an optional ISO-8601 timestamp. Events must arrive in nondecreasing event-time order. A full pattern is reported when the second-hop evidence is observed; this does not imply that the source's earlier transfers were blocked before the full path existed. /health exposes the active configuration and bounded-state counts. /v1/train is a cold-path demonstration that trains on the recent graph and caches resulting account scores; it is not an online learning loop.

Scenario generation and offline augmentation

simulate_graph_splitting generates a labeled two-hop scenario. The first-hop amounts sum to S to the cent; by default, the onward amounts conserve the same total. A seeded run is reproducible. Use outflow_ratio to create an explicit flow-loss case. Generated records are synthetic scenario data and must be identified as such in any experiment.

adversarial_fit is an offline helper. Its attack_fn must return generated features and their explicit binary labels (or a labeled DataFrame). It rejects misaligned or missing labels rather than copying labels from unrelated rows.

Graph model

The graph classifier is an SGC-style feature propagation model followed by NumPy logistic regression; it is not a deep end-to-end GNN. Propagation uses an edge-list implementation to avoid dense quadratic adjacency allocation. Graph features and model scores are computed in the cold path, then scores are retrieved from a cache in constant time by the streaming request handler.

Scope and evaluation

The detector is a research prototype, not a finding of criminality. It is a two-hop source–mule–beneficiary pattern matcher with explicit thresholds; it does not establish intent, beneficial ownership, or whether an alert is a true crime. The API's reported latency is an in-process handler measurement and excludes network, deployment, queueing, concurrency, and bank authorization infrastructure. No end-to-end SLA claim is made by this repository.

For research comparisons, use the label semantics of each public dataset, chronological splits, and transaction or episode metrics appropriate to the claim. Keep simulator-generated benchmarks identified as simulator-generated and report their limitations. The bundled demonstration and stress scripts are not empirical evidence of generalization or production performance.

License

MIT. Dataset licenses and terms are separate and must be checked at the source.