financial_patterns

sqllocks_spindle.simulation.financial_patterns

Financial transaction stream patterns — reversals, fraud bursts, settlement events.

Generates realistic financial streaming data anomalies that can be layered on top of base Financial domain data produced by the generator.

Usage::

from sqllocks_spindle.simulation.financial_patterns import (
    FinancialStreamSimulator, FinancialStreamConfig,
)

cfg = FinancialStreamConfig(duration_hours=24)
result = FinancialStreamSimulator(transactions_df=txns, accounts_df=accounts, config=cfg).run()

Classes

FinancialStreamConfig dataclass

Configuration for :class:FinancialStreamSimulator.

Parameters:

Name	Type	Description	Default
duration_hours	float	Total simulation window in hours.	24.0
reversal_enabled	bool	Whether to generate transaction reversals.	True
reversal_probability	float	Fraction of transactions that get reversed.	0.03
reversal_delay_hours_max	float	Maximum delay between original transaction and its reversal.	48.0
fraud_burst_enabled	bool	Whether to generate fraud burst events.	True
fraud_burst_probability	float	Per-hour probability of a fraud burst occurring.	0.01
fraud_burst_count	int	Number of transactions per fraud burst.	15
fraud_burst_amount_range	tuple[float, float]	(min, max) dollar range for fraud transactions.	(500.0, 10000.0)
settlement_enabled	bool	Whether to generate settlement batch records.	True
settlement_batch_hours	float	Settlement runs every N hours.	4.0
settlement_success_rate	float	Fraction of settlements that succeed.	0.98
seed	int	Random seed for reproducibility.	42

FinancialStreamResult dataclass

Result of a :meth:FinancialStreamSimulator.run execution.

Attributes:

Name	Type	Description
transactions	DataFrame	Combined DataFrame — original transactions plus any generated reversals and fraud events.
reversals	DataFrame	DataFrame containing only reversal records.
fraud_events	DataFrame	DataFrame containing only fraud burst records.
settlements	DataFrame	DataFrame containing settlement batch results.
stats	dict[str, Any]	Summary statistics for the simulation run.

FinancialStreamSimulator

Generate financial transaction stream anomalies.

Layers reversals, fraud bursts, and settlement events on top of pre-generated transaction and account DataFrames.

Parameters:

Name	Type	Description	Default
transactions_df	DataFrame | None	Base transactions DataFrame. Expected to contain at least transaction_id, account_id, amount, and transaction_time columns.	None
accounts_df	DataFrame | None	Accounts DataFrame. Expected to contain at least account_id.	None
config	FinancialStreamConfig | None	:class:FinancialStreamConfig (uses defaults if None).	None

Example::

cfg = FinancialStreamConfig(duration_hours=24, seed=99)
sim = FinancialStreamSimulator(txns, accounts, cfg)
result = sim.run()
print(result.stats)

Methods:

run()

Execute the simulation and return a :class:FinancialStreamResult.