Introduction

Nucleus Edge is the on-premise component you install to work with your data inside your own environment. This section is a practical guide to installing and using it. Every option is listed in the Reference Manual.

Overview

Nucleus Edge gives you a small set of Python functions:

The typical synthetic-data flow is: train with synthesizer(...) → obtain a synthesizer file → upload it to the platform → generate data locally with sample(...) or online in the Cloud. You can also anonymize documents, images, and audio directly with anonymize(...). In every case, your raw data never leaves your environment.

Installation

Nucleus Edge is delivered as a Python package and must be installed in a Python 3 environment. Python 3.11 is recommended; 3.9 and 3.10 are also supported.

# Create and activate an isolated environment (recommended)

python -m venv .venv

source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install the Nucleus package provided by Dedomena

pip install nucleus-4.10.2-DEV.tar.gz

GPU (optional). Training and generation run on CPU by default. To use a GPU, install on a machine with a compatible NVIDIA GPU and pass cuda=True to the functions. Working with free-text columns benefits most from a GPU.

Connecting to IBM Db2 (optional). To read from Db2, download the JDBC driver and place it in the DB2Driver folder inside your Nucleus installation path (see Supported Data Sources).

System and hardware requirements

Software

• Operating system: Linux (x86-64) is recommended and is required for the GPU-based features. Tabular work (synthetic data and table anonymization) also runs on CPU under Windows and macOS.

• Python: 3.9–3.11 (3.11 recommended).

• GPU driver: for any GPU feature, an up-to-date NVIDIA driver supporting CUDA 12.1 or later.

What each task needs

GPU specification — required for anonymizing documents, images, and audio (and for free-text handling)

These features rely on AI models that run on the GPU. Use an NVIDIA GPU with:

• Architecture: Ampere or newer — CUDA Compute Capability 8.0 or higher (e.g., NVIDIA A100, L4, L40S, RTX A6000, RTX 6000 Ada, or newer Hopper/Blackwell cards).

• Video memory (VRAM): 24 GB minimum; 48 GB or more recommended, especially for high-resolution documents and images, where a vision model and a text model run at the same time.

• CUDA: an NVIDIA driver compatible with CUDA 12.1 or later.

• System RAM: 32 GB or more.

• Disk: keep at least 30 GB free for the model files, which are downloaded and cached the first time you use these features (a one-time download).

Pass cuda=True to the Edge functions to run on the GPU.

> If no compatible GPU is available, you can still use Nucleus Edge for synthetic data and table anonymization on CPU. Anonymizing documents, images, and audio — and transforming free text — requires a GPU.

Authentication

Every Edge function requires a token provided by Dedomena. The token authorizes the component and is passed on each call:

from nucleus.synthesizer import synthesizer

TOKEN = "your-dedomena-token"

synthesizer(

    token=TOKEN,

    data_format="CSV",

    data_dir="data/customers.csv",

    # ...

)

Keep the token out of source control (use an environment variable or a secrets manager). The same token is used by all Edge functions.

Supported Data Sources

Edge reads data through the data_format and data_dir options. Four input formats are supported:

Databases. When data_format="DATABASE", set data_dir to the connection URL and use query to name a table or provide a full SQL query. For IBM Db2, download the JDBC driver, place it in the DB2Driver folder within your Nucleus installation path, and use a URL of the form:

jdbc:db2://\<host\>:\<port\>/\<database_name\>:sslConnection=true;user=\<userid\>;password=\<password\>;

Db2 JDBC drivers: https://www.ibm.com/support/pages/db2-jdbc-driver-versions-and-downloads

Output formats (sample): CSV, EXCEL, PARQUET, or DATAFRAME (return the result directly in memory as a pandas DataFrame).

Anonymization

Anonymization and synthetic data are separate operations with different inputs and results, so they are described separately.

With Edge you can anonymize tables and unstructured files (documents, images, and audio) directly on your machine — in every case the output is a new anonymized file, ready to use. You can also protect sensitive columns of a table while you train a synthesizer.

Anonymizing tables

Use anonymize() to anonymize a structured table too. Just like training a synthesizer, you point it at a table (a file or a database connection); the difference is what comes out — training produces a reusable model, while anonymization produces a new file with your data already protected. You pass a configuration that maps each sensitive column to the method to apply; Edge transforms those columns and leaves the rest untouched.

from nucleus.anonymize import anonymize

anonymize(

    token=TOKEN,

    data_format="CSV",

    data_dir="data/customers.csv",

    config=\{

        "full_name":   "simulation",  # string column

        "email":       "mask",        # string column

        "national_id": "hash",        # string column

        "salary":      "perturb",     # numeric column

        "birth_date":  "generalize",  # datetime column

    \},

    output_filename="customers_anonymized.csv",

    output_format="CSV",

)

The configuration works exactly as for files: the key is the column name and the value is the method (short form) or \{"method": ..., "type": ...\} (extended form). The method must be valid for the column’s data type — numeric columns accept perturb, generalize, shuffle, mask, hash; string/categorical columns accept mask, simulation, pseudonym, coding, hash, shuffle; and so on (see Anonymization Methods). Pass config="auto" to apply the default method to every sensitive column detected during analysis. Tables can be read from CSV, PARQUET, or a DATABASE connection, and written back as CSV, EXCEL, or PARQUET.

Anonymizing documents, images, and audio

Use anonymize() to protect an unstructured file. You pass the path to the file and a configuration that says, for each sensitive element, which method to apply. Edge analyzes the file, detects the sensitive elements it contains, and applies the method you chose to every element of that type — leaving the rest of the file untouched. The anonymized file is written to the output path you specify.

from nucleus.anonymize import anonymize

anonymize(

    token=TOKEN,

    data_dir="documents/id_card.png",

    config=\{

        "face":        "blur",       # visual element

        "signature":   "redact",     # visual element

        "person_name": "mask",       # text element

        "id_number":   "coding",     # text element

        "birth_date":  "generalize", # text element

    \},

    output_filename="id_card_anonymized.png",

    cuda=True,

)

The configuration dictionary. Each key is the name of a sensitive element and each value is the method to apply to it. Use the short form ("face": "blur") when the method needs no options, or the extended form when you want to pass options — for example, the variable type for simulation:

config=\{

    "person_name": \{"method": "simulation", "type": "name"\},

    "email":       \{"method": "simulation", "type": "email"\},

    "id_number":   \{"method": "mask"\},

\}

The method you choose must be valid for the element’s channel — visual elements accept blur, pixelate, redact; text elements accept mask, coding, simulation, pseudonym, hash; audio elements accept beep, silence, remove (see Anonymization Methods and Consistent anonymization across related assets). To let Edge anonymize every detected element with its default method, pass config="auto".

Documents (PDF):

anonymize(

    token=TOKEN,

    data_dir="documents/contract.pdf",

    config=\{

        "person_name": "pseudonym",

        "address":     "mask",

        "iban":        "hash",

    \},

    output_filename="contract_anonymized.pdf",

)

Audio:

anonymize(

    token=TOKEN,

    data_dir="calls/support_call.mp3",

    config=\{

        "person_name":  "beep",

        "phone_number": "beep",

        "address":      "silence",

    \},

    output_filename="support_call_anonymized.mp3",

)

Automatic mode — detect everything and apply the default method for each element:

anonymize(

    token=TOKEN,

    data_dir="documents/id_card.png",

    config="auto",

    output_filename="id_card_anonymized.png",

)

Supported inputs:

Parameters:

> Reversibility. Methods that keep a mapping (pseudonym, simulation, mask, generalize) also write a mapping file, so an authorized administrator can reverse them later. The other methods are irreversible. See Anonymization Methods.

Synthetic Data Generation

Generating synthetic data with Edge is a two-step process: train a synthesizer, then generate rows from it.

Step 1 — Train (synthesizer). Produces a synthesizer file in output_dir.

from nucleus.synthesizer import synthesizer

synthesizer(

    token=TOKEN,

    data_format="CSV",

    data_dir="data/transactions.csv",

    algorithm="generic",

    epochs=200,

    batch_size=256,

    amplify="quality",              # boost fidelity (needs epochs \>= 150)

    categorical_columns=["category", "channel"],

    integer_columns=["age"],

    float_columns=["amount"],

    date_columns=\{"txn_date": "%Y-%m-%d"\},

    id_columns=\{"customer_id": r"ID_\d\{4\}"\},

    target="category",

    output_dir="results",

    synthesizer_name="tx_v1",

    synthesizer_description="Transactions synthesizer, quality mode",

)

Step 2 — Generate (sample). Loads the synthesizer and writes synthetic rows.

from nucleus.sample import sample

sample(

    token=TOKEN,

    model_dir="results/tx_v1.zip",

    n_rows=100_000,

    output_filename="synthetic_transactions.parquet",

    output_format="PARQUET",

)

Conditional generation. Pass ratios to shape the output (see Synthetic Data in the Cloud Guide and Generation Parameters):

sample(

    token=TOKEN,

    model_dir="results/tx_v1.zip",

    n_rows=50_000,

    ratios=\{"gender": \{"F": 1, "M": 0\}, "is_fraud": \{"1": 1, "0": 0\}\},  # Female AND fraud only

    output_format="DATAFRAME",

)

Uploading Synthesizers

The synthesizer file produced by synthesizer() (and retrain_synthesizer()) is what you send to the platform. Because it contains everything needed to generate data — and is protected — it can be transferred and stored safely.

1. Train locally with synthesizer(...); note the file written to output_dir.

2. Upload the file to the platform (through the web app or the API).

3. Once uploaded, the synthesizer is available for generating synthetic data via the web app and the API — and no raw data ever left your environment.

4. To keep a synthesizer current as your source data changes, retrain it (below) and upload the new file.

Retraining (retrain_synthesizer) continues training an existing synthesizer with new data. The forgetfulness_factor controls how much of the previous training is kept (0 = keep everything, 1 = start over):

from nucleus.retrain_synthesizer import retrain_synthesizer

retrain_synthesizer(

    token=TOKEN,

    model_dir="results/tx_v1.zip",

    data_dir="data/transactions_new_month.csv",

    data_format="CSV",

    epochs=250,

    forgetfulness_factor=0.0,       # keep everything learned so far

    output_dir="results",

)

Evaluation

Training already runs the automatic evaluation and includes the report with the synthesizer. Edge also lets you evaluate any pair of real and synthetic datasets on demand and produce the report yourself.

Single table (synthesizer_evaluations):

from nucleus.evaluations import synthesizer_evaluations

privacy, quality, utility = synthesizer_evaluations(

    token=TOKEN,

    real_data="data/real.parquet",

    synthetic_data="data/synth.parquet",

    data_format_real="PARQUET",

    data_format_synth="PARQUET",

    categorical_columns=["city", "category"],

    integer_columns=["age"],

    float_columns=["amount"],

    date_columns=["txn_date"],

    target="category",

    output_dir="report",            # writes report/report.html

    synthesizer_name="tx_v1",

    verbose=True,

)

print(privacy, quality, utility)

The function returns the three scores and writes an HTML report to output_dir. A table with fewer than three usable columns is skipped.

Multiple tables (synthesizer_evaluations_multitable) takes a per-table configuration and produces a single combined report; see Evaluation Parameters.

Python Examples

A. Transactional synthesizer with description anonymization

from nucleus.synthesizer import synthesizer

from nucleus.sample import sample

TOKEN = "your-dedomena-token"

synthesizer(

    token=TOKEN,

    data_format="PARQUET",

    data_dir="data/bank_tx.parquet",

    algorithm="transactional",

    epochs=250,

    batch_size=256,

    columns_mapping=\{

        "user_id": "client_id",

        "concept": "description",

        "amount": "amount_eur",

        "txn_date": "date",

        "balance": "balance_eur",

    \},

    balance_updated=True,

    transform_descriptions="level2",   # anonymize names/addresses/cities in text

    date_columns=\{"date": "%Y-%m-%d"\},

    float_columns=["amount_eur", "balance_eur"],

    categorical_columns=["category"],

    datasets_country="Spain",

    output_dir="results",

    synthesizer_name="bank_tx_v1",

)

sample(token=TOKEN, model_dir="results/bank_tx_v1.zip",

       n_rows=200_000, output_filename="synth_bank_tx.parquet")

B. Time-series synthesizer

from nucleus.synthesizer import synthesizer

synthesizer(

    token=TOKEN,

    data_format="CSV",

    data_dir="data/sensor_series.csv",

    algorithm="timeseries",

    epochs=300,

    time_step="D",                 # one observation per day

    series_length=365,             # 365 daily steps per series

    static_columns=["device_type", "region"],

    float_columns=["temperature", "humidity"],

    date_columns=["timestamp"],

    columns_mapping=\{"user_id": "device_id", "txn_date": "timestamp"\},

    output_dir="results",

    synthesizer_name="sensors_v1",

)

C. Relational (multi-table) synthesizer

from nucleus.synthesizer import synthesizer

datasets_config = \{

    "customers": \{

        "data_dir": "data/customers.csv", "data_format": "CSV",

        "algorithm": "generic",

        "categorical_columns": ["segment"], "integer_columns": ["age"],

        "primary_key": "customer_id", "foreign_key": \{\},

        "sensitive": \{"name": "name"\},

    \},

    "orders": \{

        "data_dir": "data/orders.parquet", "data_format": "PARQUET",

        "algorithm": "transactional",

        "columns_mapping": \{"user_id": "customer_id", "txn_date": "order_date",

                            "concept": "item", "amount": "total"\},

        "date_columns": ["order_date"], "float_columns": ["total"],

        "primary_key": "order_id", "foreign_key": \{"customer_id": "customers"\},

    \},

\}

synthesizer(

    token=TOKEN, algorithm="relational",

    datasets_config=datasets_config,

    epochs=200, datasets_country="Spain",

    output_dir="results", synthesizer_name="shop_v1",

)

D. Generate to an in-memory DataFrame

from nucleus.sample import sample

df = sample(token=TOKEN, model_dir="results/shop_v1.zip",

            n_rows=10_000, output_format="DATAFRAME")

print(df.head())

Reference Manual

This manual lists the options available in Nucleus Edge, grouped by purpose. The same options are available when you train and generate in the Cloud.

Common Parameters

Options shared by synthesizer(), sample(), retrain_synthesizer(), anonymize(), and the evaluation functions.

Generic Parameters

Core training options for generic (and shared by transactional and timeseries where they apply).

Constraint syntax (constraints):

Transactional Parameters

Extra options for algorithm="transactional".

transform_descriptions levels:

• None — descriptions are kept as they are.

• level1 — replaces dates, card numbers, account numbers (IBANs), and amounts in the text.

• level2 — everything in level1, plus names of people, addresses, and cities.

• level3 — everything in level2, plus merchant names, replaced with plausible alternatives from a similar industry (e.g., McDonald’s → Burger King; Iberia → Air Europa).

Time Series Parameters

Extra options for algorithm="timeseries".

Relational Parameters

For algorithm="relational", describe your tables with datasets_config: a dictionary with one entry per table.

NUCLEUS keeps the links between tables consistent so keys still match in the synthetic result. Relational training needs 150 or more training passes.

Generation Parameters

Options for sample() and retrain_synthesizer().

sample()

retrain_synthesizer() (in addition to the common parameters)

Evaluation Parameters

synthesizer_evaluations() (single table)

Returns the three scores: (privacy, quality, utility).

synthesizer_evaluations_multitable() takes a configuration with one entry per table (each with its real and synthetic data, column types, optional sensitive columns, and target) and produces a single combined report with overall scores.

Anonymization Parameters

Options for anonymize(), which anonymizes a table, document, image, or audio file. The output is a new anonymized file (not a model). See Anonymization in the Nucleus Edge section for examples.

Supported inputs: tables (CSV, Parquet, database connection), images (PNG, JPG/JPEG, TIFF, BMP), documents (PDF, DOCX), and audio (WAV, MP3, M4A, FLAC).