Metadata-Version: 2.4
Name: fraudstruct
Version: 1.0.1
Summary: Research prototype for streaming transaction structuring detection and graph risk features
Author-email: "Chidiebere V. Christopher" <vchidiebere.vc@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/93Chidiebere/Fraudstruct-Library
Project-URL: Repository, https://github.com/93Chidiebere/Fraudstruct-Library
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: scikit-learn>=1.2
Requires-Dist: fastapi>=0.95.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: networkx>=2.8
Provides-Extra: spark
Requires-Dist: pyspark>=3.4; extra == "spark"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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:

```text
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

```bash
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.

```powershell
$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.
