NeMo Safe Synthesizer Tutorial: Time-Series Financial Transactions¶
What you'll learn¶
In this notebook, we'll explore how to use NeMo Safe Synthesizer for generating a financial transaction time series: loading an account-level transaction dataset, configuring the synthesizer for grouped temporal data, generating synthetic transaction histories, and checking whether the synthetic data preserves privacy and transaction patterns.
We will answer two questions:
- Does the synthetic data avoid direct memorization of transaction rows?
- Does it preserve the data structure and behavioral patterns that matter for financial analytics?
A full run takes about 20 minutes on an A100. If you have not yet completed the Safe Synthesizer 101 tutorial, consider starting there first.
Prerequisites¶
This notebook requires:
- A Linux machine with an NVIDIA GPU (H100 recommended, A100 minimum) and CUDA 12.9+. It will not run on macOS, Windows, or Apple Silicon.
- The
docs/tutorials/datasets/financial_transactions_DD_0526.csvdataset.
Install Safe Synthesizer¶
Run the cell below to install NeMo Safe Synthesizer with the engine and CUDA 12.9 extras.
If NeMo Safe Synthesizer is already installed in your notebook environment, you can skip this cell. The cell requires uv.
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
import sys
# The override resolves a flashinfer-python pin conflict between vLLM and NeMo Safe Synthesizer.
!echo "flashinfer-python==0.7.0.post1" | uv pip install --python "{sys.executable}" \
"nemo-safe-synthesizer[engine,cu129]==0.2.0" \
-c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/v0.2.0/constraints.txt \
--overrides - \
--find-links https://flashinfer.ai/whl/cu129/flashinfer-jit-cache/ \
--find-links https://flashinfer.ai/whl/flashinfer-cubin/ \
--find-links https://wheels.vllm.ai/0.32.0/cu129/vllm/ \
--find-links https://download.pytorch.org/whl/cu129/torch/ \
--find-links https://download.pytorch.org/whl/cu129/torchaudio/ \
--find-links https://download.pytorch.org/whl/cu129/torchvision/ \
--find-links https://download.pytorch.org/whl/cu129/torchcodec/ \
--find-links https://download.pytorch.org/whl/cu129/torchao/ \
--find-links https://download.pytorch.org/whl/cu129/triton/
from __future__ import annotations
import hashlib
import html
from pathlib import Path
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
from matplotlib.colors import LinearSegmentedColormap
from IPython.display import Markdown, display
NVIDIA_GREEN = "#76B900"
NVIDIA_DARK = "#111111"
NVIDIA_GRAY = "#7A7A7A"
NVIDIA_HEATMAP = LinearSegmentedColormap.from_list(
"nvidia_heatmap",
["#F7F7F7", "#D7F2B0", NVIDIA_GREEN, "#254A00"],
)
plt.rcParams.update({
"figure.figsize": (11, 5),
"axes.grid": True,
"grid.alpha": 0.25,
"axes.spines.top": False,
"axes.spines.right": False,
"axes.prop_cycle": plt.cycler(color=[NVIDIA_GREEN, NVIDIA_DARK, NVIDIA_GRAY]),
})
pd.set_option("display.max_columns", 80)
pd.set_option("display.width", 160)
Load the Financial Transactions Dataset¶
Load financial_transactions_DD_0526.csv and confirm the expected row and column counts. The dataset is already in the long format that NeMo Safe Synthesizer expects for time-series synthesis: rows sharing the same acct_id form one transaction sequence, and timestamp provides the chronological ordering within each account. Note that different transaction sequences have different numbers of rows, and the intervals between transactions are highly variable. NeMo Safe Synthesizer directly supports these and outputs synthetic data in the same format.
ORIGINAL_CSV = "https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/docs/tutorials/datasets/financial_transactions_DD_0526.csv"
ARTIFACT_ROOT = "safe-synthesizer-artifacts/time-series-financial-transactions"
source_df = pd.read_csv(ORIGINAL_CSV)
pd.DataFrame(
[{
"input": "Original CSV",
"path": ORIGINAL_CSV,
"rows": len(source_df),
"columns": len(source_df.columns),
}]
)
Preview the Original Dataset¶
The source data is a transaction ledger with repeated account-level fields, merchant category/name, timestamp, and amount. Transaction timestamps provide chronological order, while each account retains its naturally varying sequence length. Direct identifiers such as acct_id and cardholder are useful for demonstrating privacy checks, but should be treated carefully in production synthetic-data workflows.
display(source_df.head(5))
display(pd.DataFrame({
"column": source_df.columns,
"dtype": source_df.dtypes.astype(str).values,
"non_null": source_df.notna().sum().values,
"unique_values": source_df.nunique(dropna=True).values,
}))
Configure and Run Safe Synthesizer¶
Create the Safe Synthesizer builder and configure it for financial transaction time-series synthesis:
with_replace_pii(enable=False)turns off PII replacement for this dataset, so the model trains on the original account IDs and cardholder names, and the synthetic data reuses them.with_evaluate(pii_replay_enabled=False)turns off the PII replay check, which would only confirm that and would otherwise start a separate LLM to find PII columns. The other privacy and quality checks in the evaluation report still run.with_time_seriesenables time-series mode and usestimestampas the chronological column.with_datatells the synthesizer that rows sharing the sameacct_idbelong to one account history, ordered bytimestamp.with_trainsets demo-specific training hyperparameters for theHuggingFaceTB/SmolLM3-3Bbase model.
Because account histories have different lengths and time ranges, Safe Synthesizer automatically selects flexible time-series processing. During training it adds an internal sequence index and final-row marker; generation uses those controls to learn when each account history ends, then removes them from the returned data. No padding or user-managed transaction index is required.
In time-series mode, generation follows the learned group and sequence structure rather than treating num_records as a row-count target.
Refer to the configuration docs for the full list of options.
from nemo_safe_synthesizer.sdk.library_builder import SafeSynthesizer
builder = (
SafeSynthesizer(save_path=ARTIFACT_ROOT)
.with_data_source(source_df)
.with_replace_pii(enable=False)
.with_evaluate(pii_replay_enabled=False)
.with_time_series(
is_timeseries=True,
timestamp_column="timestamp",
)
.with_data(
holdout=0,
group_training_examples_by="acct_id",
order_training_examples_by="timestamp",
)
.with_train(
pretrained_model="HuggingFaceTB/SmolLM3-3B",
num_input_records_to_sample=50000,
learning_rate=5.0e-4,
lora_r=32,
)
)
builder.run()
results = builder.results
RUN_PATH = Path(builder._workdir.generate.path).parent
pd.DataFrame(
[{
"artifact": "Safe Synthesizer run path",
"path": str(RUN_PATH),
"synthetic_rows": len(results.synthetic_data),
}]
)
Review the Built-In Evaluation Report¶
Safe Synthesizer generates a built-in evaluation report as part of builder.run(). Review this first for the standard quality and privacy assessment before moving into the transaction-specific analysis below.
report_html = results.evaluation_report_html
if report_html:
# srcdoc, not a data: URL: Chrome blanks data: URLs over 2 MB, and the base keeps the report's #section links in the frame.
report_doc = report_html.replace("<head>", '<head><base href="about:srcdoc">', 1)
frame = (
f'<iframe srcdoc="{html.escape(report_doc)}" sandbox="allow-scripts allow-popups" '
'width="100%" height="800"></iframe>'
)
# Raw display: HTML() warns about a bare <iframe>, and IFrame() cannot take srcdoc.
display({"text/html": frame}, raw=True)
else:
display(Markdown("Safe Synthesizer did not return an HTML evaluation report for this run."))