Protegrity Synthetic Data

• 1: Introduction
• 2: Understanding the Architecture and Components
• 3: Prerequisites for Deployment
• 4: Server Installation
• 5: Upgrading Protegrity Synthetic Data
• 6: User Creation in PPC
• 7: Using Synthetic Data
• 7.1: Python SDK Installation
• 7.2: Python SDK Reference
• 8: Uninstalling and Cleanup
• 9: Troubleshooting

1 - Introduction

This section explains why organizations use Synthetic Data and how Protegrity Synthetic Data preserves statistical utility while reducing privacy risk.

Organizations need realistic datasets for model training, testing, and cross-team collaboration without exposing sensitive information. Traditional methods such as masking and redaction can reduce data utility for analytics and machine learning.

Protegrity Synthetic Data learns patterns and distributions from source data. It then generates new records that reflect these patterns without reproducing the original personal records.

Synthetic data enables safer data sharing, faster development and validation, and compliance with regulations such as GDPR and HIPAA.

2 - Understanding the Architecture and Components

Protegrity Synthetic Data generates realistic, privacy-safe synthetic datasets using machine learning models. It learns patterns and distributions from real data, then produces new records with similar statistical properties.

Protegrity Synthetic Data uses Kubernetes for scalable Synthetic Data generation and supports deployment on AWS EKS.

Component Diagram

The following diagram shows the deployment architecture and communication between components.

graph TD
    User([User / Client Application]) -->|HTTPS :443| GW[PPC Gateway]
    User --> SDK[Synthetic Data Python SDK]
    SDK -->|HTTPS :443| GW

    GW -->|:8000  /pty/syntheticdata/v2| App[Synthetic Data
REST Server + ML Engine]

    App -->|:5432  jobstatedb + mlopsdb| DB[(PostgreSQL)]

    subgraph EKS [EKS Cluster · synthetic-data-ns]
        GW
        App
        DB
    end

    subgraph AWS
        S3[(S3 Bucket
Data Storage)]
        IAM[IAM Role
Pod Identity]
    end

    App -.->|assumes| IAM
    IAM -.->|grants access| S3
    App <-->|read / write| S3

Communication Ports

Components

• PPC Gateway: Exposes the external HTTPS endpoint and routes requests to the Synthetic Data REST API.

• Synthetic Data REST Server: Exposes the /pty/syntheticdata/v2 API and runs ML models such as VineCopula, TabDiff, TabularGAN, and SMOTE in-process to produce synthetic datasets. It stores job metadata in PostgreSQL, reads input data from the S3 bucket and writes output data to it.

• PostgreSQL: Hosts two logical databases. jobstatedb stores job metadata, including generation parameters, job status, and result references. mlopsdb stores MLOps model contracts, training runs, metrics, and artifact references managed by the MLOps library.

• S3 Storage: Stores input datasets and generated synthetic datasets.

• IAM Role with EKS Pod Identity: Grants the Synthetic Data REST Server secure access to the S3 bucket without static AWS credentials.

• Python SDK: Provides programmatic access to the REST API. For more information about the Python SDK, refer to the Python SDK Installation section.

3 - Prerequisites for Deployment

Ensure the following prerequisites are met:

Tools

Install and configure the following tools on the jumpbox:

• opentofu 1.10 or later. Refer to OpenTofu Installation.
• helm 3.12+, kubectl 1.27+, and aws CLI v2 with access to the Protegrity Provisioned Cluster (PPC).

AWS Setup

Ensure that the following AWS requirements are met:

• A Protegrity Provisioned Cluster (PPC) is available. For more information, refer to Protegrity Provisioned Cluster.

• AWS CLI credentials are configured by using aws configure.

• The AWS credentials have permission to provision IAM roles, S3 buckets, EKS Pod Identity associations, and Karpenter node resources. If you encounter AccessDenied errors, refer to IAM Permissions for Installation.

• The jumpbox can connect to the required registry. If you are not already authenticated, log in to it.

  • To authenticate to the Protegrity Container Registry (PCR), use the following command with credentials from the My.Protegrity portal during account creation:

  echo "<password>" | helm registry login registry.protegrity.com --username "<username>" --password-stdin
  

  • For a local registry, use your credentials and local registry endpoint as required.

EKS Cluster Requirements

Ensure that the EKS cluster meets the following requirements:

• Kubernetes 1.27 or later is installed.
• The default StorageClass is used unless you override it. Verify the StorageClass with kubectl get storageclass.
• The EKS Pod Identity Agent add-on is enabled on the cluster.
• Karpenter 1.0 or later is installed and configured on the cluster.

IAM Permissions for Installation

The AWS credentials used during installation require the following permissions. You can reduce these permissions after installation is complete.

4 - Server Installation

Note: This guide uses version 2.1.0 throughout. Replace 2.1.0 with the version you are installing, including in the Python SDK Installation section.

This section describes how to deploy Protegrity Synthetic Data on Amazon EKS as part of Protegrity AI Team Edition.
It uses OpenTofu to provision cloud infrastructure, such as S3, IAM, and Karpenter. It also generates the syntheticdata-values.yaml file that Helm uses to deploy Kubernetes workloads.

Deployment Steps

1. Provision Cloud Infrastructure with OpenTofu

The OpenTofu module creates the S3 bucket, IAM role, EKS Pod Identity association, and Karpenter NodePool. It also writes syntheticdata-values.yaml with cloud-specific Helm overrides.

Option A - You already have a root module

Add the following module block to your existing root module:

module "synthetic_data" {
  source = "oci://registry.protegrity.com/synthetic-data/synthetic-data-server/opentofu/synthetic-data?tag=aws-2.1.0"

  cluster_name  = "<CLUSTER_NAME>"
  bucket_name   = "<globally-unique-s3-bucket-name>"
  oci_host      = "registry.protegrity.com"
  environment   = "production"
  chart_version = "2.1.0"
}

Then run the following commands:

tofu init
tofu plan
tofu apply

Option B - You do not have a root module

Create a new directory with a single main.tf:

terraform {
  required_version = "~> 1.10"

  required_providers {
    aws = {
      source  = "registry.opentofu.org/hashicorp/aws"
      version = "~> 5.0"
    }
    kubernetes = {
      source  = "registry.opentofu.org/hashicorp/kubernetes"
      version = "~> 2.35"
    }
  }
}

variable "cluster_name" {
  type        = string
  description = "EKS cluster name."
}

variable "environment" {
  type    = string
  default = "production"
}

data "aws_eks_cluster" "this" {
  name = var.cluster_name
}

data "aws_eks_cluster_auth" "this" {
  name = var.cluster_name
}

provider "kubernetes" {
  host                   = data.aws_eks_cluster.this.endpoint
  cluster_ca_certificate = base64decode(data.aws_eks_cluster.this.certificate_authority[0].data)
  token                  = data.aws_eks_cluster_auth.this.token
}

module "synthetic_data" {
  source = "oci://registry.protegrity.com/synthetic-data/synthetic-data-server/opentofu/synthetic-data?tag=aws-2.1.0"

  cluster_name  = var.cluster_name
  bucket_name   = "<globally-unique-s3-bucket-name>"
  oci_host      = "registry.protegrity.com"
  environment   = var.environment
  chart_version = "2.1.0"
}

output "helm_install" {
  value = module.synthetic_data.helm_install
}

Then run the following commands:

tofu init
tofu plan -var="cluster_name=<CLUSTER_NAME>"
tofu apply -var="cluster_name=<CLUSTER_NAME>"

Note: tofu output -raw helm_install prints a ready-to-run Helm command with the correct version and namespace.

2. Deploy with Helm

The OpenTofu module writes a syntheticdata-values.yaml file in your working directory. Passwords are required only for the first installation. They are preserved automatically for later upgrades.

export MLOPS_PASSWORD=<MLOPS_PASSWORD>
export JOBSTATE_PASSWORD=<JOBSTATE_PASSWORD>

helm upgrade --install synthetic-data \
  oci://registry.protegrity.com/synthetic-data/helm/synthetic-data \
  --version 2.1.0 \
  --namespace synthetic-data-ns --create-namespace \
  --values syntheticdata-values.yaml \
  --set database.auth.mlopsPassword=$MLOPS_PASSWORD \
  --set database.auth.jobstatePassword=$JOBSTATE_PASSWORD

Note: Ensure that the “<JOBSTATE_PASSWORD>” contains only alphanumeric characters.

For upgrades, omit the --set flags because the passwords are already stored in the cluster secret:

helm upgrade synthetic-data \
  oci://registry.protegrity.com/synthetic-data/helm/synthetic-data \
  --version 2.1.0 \
  --namespace synthetic-data-ns \
  --values syntheticdata-values.yaml

3. Monitor

1. Monitor the deployment process using the following command.

   kubectl get pods -n synthetic-data-ns
   

   Verify that all pods are in the Running state. The following is a sample output.

   NAME                                       READY   STATUS    RESTARTS   AGE
   synthetic-data-<hash>-<hash>               1/1     Running   0          3m20s
   synthetic-data-db-0                        1/1     Running   0          3m20s
   

2. Verify that the Synthetic Data service is deployed.

   kubectl get svc -n synthetic-data-ns
   

   The following is the sample output.

   NAME                  TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
   synthetic-data-svc    ClusterIP   172.20.xxx.xxx   <none>        8000/TCP   61s
   

   For more information about the Python SDK, refer to Python SDK Reference.

5 - Upgrading Protegrity Synthetic Data

This section describes how to upgrade Protegrity Synthetic Data to the latest version.

Note: If upgrading across major versions, review the release notes for any breaking changes before proceeding.

1. Upgrade Protegrity Synthetic Data by running helm upgrade with the new --version value.

   Note: Passwords are preserved during upgrades. Omit the --set database.auth.* flags.

   helm upgrade synthetic-data \
     oci://registry.protegrity.com/synthetic-data/helm/synthetic-data \
     --version <NEW_VERSION> \
     --namespace synthetic-data-ns \
     --values <VALUES_FILE>
   

2. After upgrading, verify that all pods are in the Running state:

   kubectl get pods -n synthetic-data-ns
   

6 - User Creation in PPC

Warning: Use the -k flag only in development or trusted internal environments. Do not use it in production, where valid certificates must be configured.

Role Update and User Creation

After deployment, update the default syntheticdata_administrator role to include can_create_token permission. Then create a user with this role.

1. Update syntheticdata_administrator role permission

export GATEWAY_URL="https://$(kubectl get configmap/nfa-config -n default -o jsonpath='{.data.FQDN}')"

# 1. Obtain an Authentication Token
TOKEN=$(curl -sk -X POST "${GATEWAY_URL}/api/v1/auth/login/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'loginname=admin&password=Admin123!' \
  -D - -o /dev/null | grep -i 'pty_access_jwt_token' | awk '{print $2}' | tr -d '\r\n')

curl -sk -X PUT \
  "${GATEWAY_URL}/pty/v1/auth/roles" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "syntheticdata_administrator",
    "description": "Administrator role",
    "permissions": [
      "can_create_token",
      "syntheticdata_operations_admin"
    ]
  }'

2. Create a user with the syntheticdata_administrator role attached

Use the following request payload when creating the user:

{
  "username": "syntheticdata_admin",
  "email": "synthadmin@example.com",
  "firstName": "Synth",
  "lastName": "<USERNAME>",
  "password": "<PASSWORD>",
  "roles": [
    "syntheticdata_administrator"
  ]
}

Note: Replace default credentials and URLs for production environments. For example, for <USERNAME>, enter User and for <PASSWORD>, enter StrongPassword123!.

Create the user with the following API call:

curl -sk -X POST \
  "${GATEWAY_URL}/pty/v1/auth/users" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "syntheticdata_admin",
    "email": "synthadmin@example.com",
    "firstName": "Synth",
    "lastName": "<USERNAME>",
    "password": "<PASSWORD>",
    "roles": [
      "syntheticdata_administrator"
    ]
  }'

7 - Using Synthetic Data

This section provides a consolidated view of Python SDK usage and API capabilities. It covers client configuration patterns and core synthetic data workflows such as health checks, quasi-identifier detection, and risk analysis.

7.1 - Python SDK Installation

Use this section to install, configure, and validate the Python SDK for Protegrity Synthetic Data.

Prerequisites

Ensure one of the following is met:

• pip is available in your active Python virtual environment.
• A conda environment is activated.

Overview

The Synthetic Data service can be accessed programmatically using the Python SDK.

1. Install the Synthetic Data Python SDK

Install the SDK from PyPI or conda using the version that matches the deployed Synthetic Data service.

Using pip:

pip install protegrity-synthetic-data-sdk==2.1.0

Using conda:

conda install -c protegrity protegrity-synthetic-data-sdk==2.1.0

2. Configure the SDK

Create a client configuration pointing to your PPC gateway. The gateway URL can be obtained using:

export GATEWAY_URL="https://$(kubectl get configmap/nfa-config -n default -o jsonpath='{.data.FQDN}')"

Then configure the client in Python:

from synthetic_data_sdk.config import ClientConfig

config = ClientConfig(
    base_url="<GATEWAY_URL>/pty/syntheticdata/v2",
    username="<USERNAME>",
    password="<PASSWORD>",
    verify_ssl=True,
)

Note: Replace default credentials and URLs for production environments. For example, for <USERNAME>, enter syntheticdata_admin and for <PASSWORD>, enter StrongPassword123!.

3. Test the Synthetic Data Python SDK

from synthetic_data_sdk import SyntheticDataClient
from synthetic_data_sdk.config import ClientConfig

config = ClientConfig(
    base_url="<GATEWAY_URL>/pty/syntheticdata/v2",
    username="<USERNAME>",
    password="<PASSWORD>",
    verify_ssl=True,
)

with SyntheticDataClient(config=config) as client:
    print("Connection established successfully.")

The connection is established successfully. If the connection fails, an error message is displayed.

7.2 - Python SDK Reference

Protegrity AI (Developer or TEAM) Editions - This section documents all classes and methods available in Protegrity Synthetic Data TEAMS and later. Methods marked as (TEAMS) are available only in the AI TEAM edition and above.

ClientConfig

Configuration dataclass for all Synthetic Data SDK clients.

from synthetic_data_sdk import ClientConfig

Attributes:

• endpoint (str) - Base URL of the Synthetic Data API (e.g. "<GATEWAY_URL>/pty/syntheticdata/v2").
• timeout (int, default 300) - Request timeout in seconds.
• max_retries (int, default 3) - Retry attempts on connection failure.
• verify_ssl (bool, default True) - Set to False for self-signed certificates.
• api_key (str | None, default None) - API key for authentication if required.
• headers (dict, default {}) - Additional HTTP headers for every request.

Single-Table Synthesizers

All single-table synthesizers share the same fit / transform / fit_transform / evaluate / summary interface, inherited from a shared base class.

RemoteVineCopula

Single-table vine copula synthesizer. Available in all tiers.

from synthetic_data_sdk import RemoteVineCopula

synth = RemoteVineCopula(
    endpoint="<GATEWAY_URL>/pty/syntheticdata/v2",
    categorical_cols=["city", "product"],
)

Constructor parameters:

• endpoint (str) - API endpoint URL. Not required when config is provided.
• model_version (str, optional) - Version identifier for model persistence. Reuse to avoid refitting.
• config (ClientConfig, optional) - Advanced client configuration.
• mlops_config (dict, optional) - Per-request MLOps tracking override.
• **parameters - Model-specific hyper-parameters (e.g. categorical_cols, vine_type).

RemoteSMOTE

SMOTE-based oversampling synthesizer. Useful for augmenting minority classes in imbalanced datasets. Available in all tiers.

from synthetic_data_sdk import RemoteSMOTE

synth = RemoteSMOTE(
    endpoint="<GATEWAY_URL>/pty/syntheticdata/v2",
    categorical_cols=["class"],
    k=5,
)

Constructor parameters: Same as RemoteVineCopula. Model-specific parameters: categorical_cols, k, noise_scale.

RemoteTabDiff (TEAMS)

Diffusion-based single-table synthesizer. Ideal for GPU-intensive synthesis without local GPU resources. Requires TEAMS.

from synthetic_data_sdk import RemoteTabDiff

synth = RemoteTabDiff(
    endpoint="<GATEWAY_URL>/pty/syntheticdata/v2",
    categorical_cols=["city", "product"],
    epochs=1000,
)

Constructor parameters: Same as RemoteVineCopula. Model-specific parameters: categorical_cols, epochs.

RemoteTabularGAN (TEAMS)

TabularGAN (CTABGAN architecture) synthesizer with mode-specific normalization for mixed continuous/categorical columns. Requires TEAMS.

from synthetic_data_sdk import RemoteTabularGAN

synth = RemoteTabularGAN(
    endpoint="<GATEWAY_URL>/pty/syntheticdata/v2",
    categorical_cols=["city", "product"],
    epochs=300,
)

Constructor parameters: Same as RemoteVineCopula. Model-specific parameters: categorical_cols, epochs.

Shared Methods (all single-table synthesizers)

fit

def fit(df: pd.DataFrame | str | Path) -> Self

Fit the model on training data. The fitted model is stored on the server using the configured model_version.

Parameters:

• df (DataFrame | str | Path) - Training data as a DataFrame, local file path, or cloud URI (s3://, gs://, azure://, minio://). Cloud URIs (s3://, gs://, azure://) require TEAMS.

Returns: Self (for method chaining).

Raises:

• SynthesisAPIError - If fitting fails.

transform

def transform(n: int) -> pd.DataFrame

Generate synthetic data using a fitted model.

Parameters:

• n (int) - Number of synthetic samples to generate.

Returns: DataFrame - Synthetic data with the same schema as the training data.

Raises:

• RuntimeError - If the model has not been fitted and no model_version exists on the server.
• SynthesisAPIError - If generation fails.

fit_transform

def fit_transform(df: pd.DataFrame, n: int) -> pd.DataFrame

Fit the model and generate synthetic data in a single call.

Parameters:

• df (DataFrame) - Training data.
• n (int) - Number of synthetic samples to generate.

Returns: DataFrame - Synthetic data.

evaluate

def evaluate(
    real_data: pd.DataFrame | str,
    synthetic_data: pd.DataFrame | str,
    categorical_cols: list[str] | None = None,
    target_col: str | None = None,
    task_type: str | None = None,
    eval_params: dict[str, Any] | None = None,
) -> dict[str, Any]

Evaluate synthetic data quality against the real data.

Parameters:

• real_data (DataFrame | str) - Real training data.
• synthetic_data (DataFrame | str) - Synthetic data to evaluate.
• categorical_cols (list[str], optional) - Categorical column names.
• target_col (str, optional) - Target column for TSTR/TRTR evaluation.
• task_type (str, optional) - "classification" or "regression" for predictive evaluation.
• eval_params (dict, optional) - Additional FidelityEvaluator configuration.

Returns: dict - Evaluation metrics. Basic metrics (distributional, column-level utility, memorization) are available in all tiers. Advanced metrics (privacy attacks, causal fidelity, certification, rare-population) require TEAMS.

summary

def summary() -> dict[str, Any]

Get summary statistics from a fitted model.

Returns: dict - Model summary with statistics and metadata.

Raises:

• RuntimeError - If the model has not been fitted.

transform_conditional (TEAMS - RemoteVineCopula only)

def transform_conditional(
    df: pd.DataFrame,
    n: int,
    conditions: dict[str, Any] | None = None,
    amplify_patterns: float | None = None,
    inject_drift: dict[str, float] | None = None,
    random_state: int | None = None,
) -> pd.DataFrame

Generate synthetic data matching specific conditional scenarios. Requires TEAMS (generation:conditional).

Parameters:

• df (DataFrame) - Training data to fit on.
• n (int) - Number of synthetic samples to generate.
• conditions (dict, optional) - Column filter conditions:
  • Exact match: {"fraud": 1, "status": "active"}
  • Comparison: {"age": ">65", "income": "<=50000"}
  • Range: {"age": "between(30,50)"}
  • Membership: {"city": "in(NYC,LA,Chicago)"}
• amplify_patterns (float, optional) - Multiplier for conditional pattern amplification (e.g. 1.5 for 50% increase).
• inject_drift (dict, optional) - Column drift shifts (e.g. {"income": -20000} for recession scenario).
• random_state (int, optional) - Random seed for reproducibility.

Returns: DataFrame - Synthetic data matching the specified conditions.

Multi-Table Synthesizer

RemoteMultiTableVineCopula

Multi-table vine copula synthesizer. Preserves foreign-key relationships across tables. Available in all tiers.

from synthetic_data_sdk import RemoteMultiTableVineCopula

synth = RemoteMultiTableVineCopula(
    endpoint="<GATEWAY_URL>/pty/syntheticdata/v2",
    relationships=[
        ("customers", "customer_id", "orders", "customer_id"),
        ("orders", "order_id", "items", "order_id"),
    ],
)
tables = {"customers": customers_df, "orders": orders_df, "items": items_df}
synth.fit(tables)
synthetic = synth.transform(n=500)

Exposes the same fit, transform, fit_transform, evaluate, summary, and validate_relationships workflow as RemoteVineCopula, but accepts and returns dict[str, DataFrame] instead of DataFrame.

Evaluation Clients (TEAMS)

The following evaluation clients require TEAMS and provide advanced quality and privacy assessments beyond the metrics returned by evaluate().

PrivacyEvaluator (TEAMS)

Evaluates privacy risks in synthetic data using membership inference attacks, sensitive attribute reconstruction, and linkage attack risk analysis.

from synthetic_data_sdk import PrivacyEvaluator

evaluator = PrivacyEvaluator(endpoint="<GATEWAY_URL>/pty/syntheticdata/v2")
results = evaluator.evaluate(
    train_real_data=train_df,
    test_real_data=test_df,
    synthetic_data=synthetic_df,
    sensitive_columns=["ssn", "salary", "diagnosis"],
)
print(f"Overall Risk: {results['overall_risk']}")

evaluate(train_real_data, test_real_data, synthetic_data, sensitive_columns, k_values, config) → dict

• train_real_data - Real training data used to generate synthetic data.
• test_real_data - Held-out real data (not seen during training).
• synthetic_data - Synthetic data to evaluate.
• sensitive_columns (list[str], optional) - Columns to test for attribute inference.
• k_values (list[int], optional) - K values for linkage attack evaluation.
• config (dict, optional) - Attack configuration (e.g. {"shadow_models": 10, "attack_model": "xgboost"}).

Returns: dict - Contains overall_risk, attacks list, and summary with successful_attacks.

CertificationClient (TEAMS)

Produces a comprehensive certification score (0–100) with letter grade (A+ to F) by aggregating fidelity, privacy, utility, and completeness metrics.

Score components: Fidelity 40% · Privacy 30% · Utility 20% · Completeness 10%.

from synthetic_data_sdk import CertificationClient

cert = CertificationClient(endpoint="<GATEWAY_URL>/pty/syntheticdata/v2")
result = cert.certify(
    real_data=real_df,
    synthetic_data=synthetic_df,
    categorical_cols=["city", "gender"],
    target_col="income",
    task_type="regression",
)
print(f"Grade: {result['grade']}  Score: {result['overall_score']:.1f}/100")

certify(real_data, synthetic_data, categorical_cols, target_col, task_type, include_privacy_attacks, ...) → dict

Returns: dict - Contains grade (A+ to F), overall_score (0–100), risk_level, summary, and recommendations.

CausalEvaluator (TEAMS)

Evaluates whether synthetic data preserves causal relationships, decision boundaries, and fairness properties from the original real data.

from synthetic_data_sdk import CausalEvaluator

evaluator = CausalEvaluator(endpoint="<GATEWAY_URL>/pty/syntheticdata/v2")
results = evaluator.evaluate(
    real_data=real_df,
    synthetic_data=synthetic_df,
    treatment_col="received_treatment",
    outcome_col="recovery_time",
    covariates=["age", "severity"],
)
print(f"Preservation Rate: {results['summary']['preservation_rate']:.1%}")

evaluate(real_data, synthetic_data, treatment_col, outcome_col, target_col, feature_cols, task_type, sensitive_attr, covariates) → dict

Returns: dict - Contains overall_preserved, evaluations list, and summary.

Low-Level Client

SynthesisClient

Low-level client for direct API interaction. Most users should prefer the high-level synthesizer classes above.

synthesize

def synthesize(
    model_name: str,
    action: str,
    training_data: str | None = None,
    training_data_path: str | None = None,
    training_data_tables: dict[str, str] | None = None,
    n_samples: int | None = None,
    model_version: str | None = None,
    parameters: dict[str, Any] | None = None,
    output_uri: str | None = None,
    mlops_config: dict[str, Any] | None = None,
) -> dict[str, Any]

Send a synthesis request (synchronous - waits for completion).

Parameters:

• model_name (str) - Model type. "vine", "vine_multitable", "smote" are available in all tiers. "tabdiff" and "tabulargan" require TEAMS.
• action (str) - Action: "fit", "transform", or "fit_transform".
• training_data (str, optional) - Base64-encoded CSV for single-table inline data.
• training_data_path (str, optional) - Cloud URI or local path. s3://, azure://, gcs:// require TEAMS; minio:// is available in all tiers.
• training_data_tables (dict[str, str], optional) - Table name → path/URI mapping for multi-table synthesis.
• n_samples (int, optional) - Number of synthetic samples to generate.
• model_version (str, optional) - Version identifier for model persistence.
• parameters (dict, optional) - Model-specific hyper-parameters.
• output_uri (str, optional) - Cloud URI for output. Same tier rules as training_data_path.
• mlops_config (dict, optional) - Per-request MLOps tracking configuration.

Returns: dict - API response with status, data, and metadata.

Raises:

• SynthesisAPIError - If the request fails.

synthesize_async

Same parameters as synthesize(). Returns immediately with {"job_id": "...", "status": "queued"}.

generate_conditional (TEAMS)

def generate_conditional(
    real_data: str | pd.DataFrame,
    model_name: str,
    n_samples: int,
    conditions: dict[str, Any] | None = None,
    amplify_patterns: float | None = None,
    inject_drift: dict[str, float] | None = None,
    categorical_cols: list[str] | None = None,
    random_state: int | None = None,
) -> dict[str, Any]

Generate conditional synthetic data via the low-level client. Requires TEAMS (generation:conditional).

Parameters:

• real_data (str | DataFrame) - Training data.
• model_name (str) - One of "vine", "smote", "tabdiff" (TEAMS), "tabulargan" (TEAMS).
• n_samples (int) - Samples to generate.
• conditions (dict, optional) - Column filter conditions (see transform_conditional).
• amplify_patterns (float, optional) - Pattern amplification multiplier.
• inject_drift (dict, optional) - Column drift shifts.
• categorical_cols (list[str], optional) - Categorical columns.
• random_state (int, optional) - Random seed.

Returns: dict - Contains success, n_samples, synthetic_data (base64 CSV), conditions_applied, drift_applied, warnings, and metadata.

Job Management

get_job_status

def get_job_status(job_id: str) -> dict[str, Any]

Get the current status of an asynchronous job.

Parameters:

• job_id (str) - Job identifier returned by synthesize_async().

Returns: dict - Contains job_id, status (pending, running, completed, failed, cancelled), progress, step, message, error, synth_data_uri, and timestamps.

wait_for_job

def wait_for_job(
    job_id: str,
    poll_interval: float = 2.0,
    timeout: float = 600.0,
    callback: Any | None = None,
) -> dict[str, Any]

Block until a job reaches a terminal state.

Parameters:

• job_id (str) - Job identifier.
• poll_interval (float, default 2.0) - Seconds between status polls.
• timeout (float, default 600.0) - Maximum seconds to wait.
• callback (callable, optional) - Called with the current status dict after each poll.

Returns: dict - Final job status.

Raises:

• TimeoutError - If the job does not complete within timeout.

list_jobs

def list_jobs(
    status: str | None = None,
    limit: int = 100,
    offset: int = 0,
) -> dict[str, Any]

List jobs with optional status filter and pagination.

Parameters:

• status (str, optional) - Filter by status: "pending", "running", "completed", "failed", "cancelled".
• limit (int, default 100) - Page size (1–1000).
• offset (int, default 0) - Page offset.

Returns: dict - Contains jobs list, total, limit, and offset.

get_job_history

def get_job_history(job_id: str) -> list[dict[str, Any]]

Get the full state-transition audit trail for a job.

Parameters:

• job_id (str) - Job identifier.

Returns: list[dict] - Each entry contains sequence, status, progress, step, and changed_at.

delete_job

def delete_job(job_id: str) -> None

Delete a job record, or cancel it if still running.

Parameters:

• job_id (str) - Job identifier.

Exceptions (SynthesisAPIError) are importable from synthetic_data_sdk.exceptions.

8 - Uninstalling and Cleanup

To remove the Synthetic Data service and all associated Kubernetes and AWS resources:

1. Uninstall the Helm release

# Removes all chart resources. PVC data is RETAINED by default (retentionPolicy: whenDeleted=Retain).
helm uninstall synthetic-data -n synthetic-data-ns

# To also delete the database PVC:
kubectl delete pvc -n synthetic-data-ns -l app.kubernetes.io/name=synthetic-data

Optionally, delete the namespace after all resources are deleted:

kubectl delete namespace synthetic-data-ns

2. Destroy OpenTofu infrastructure

# Destroys Karpenter nodes, IAM role, Pod Identity association, and S3 bucket.
tofu destroy -var="cluster_name=<CLUSTER_NAME>"

Note: By default, tofu destroy prompts for confirmation before deleting resources. Add -auto-approve to skip the prompt.

9 - Troubleshooting

Diagnostic Flowchart

Use the following flowchart to identify the cause of common issues.

flowchart TD
    Start[Problem?] --> ServerRunning{Server pods Running?}
    ServerRunning -->|No| PodIssue[Check pod logs<br/>kubectl logs -n synthetic-data-ns]
    ServerRunning -->|Yes| APIWorks{Does API respond?}
    APIWorks -->|No| NetworkIssue[Check Service and Gateway<br/>kubectl get svc -n synthetic-data-ns]
    APIWorks -->|Yes| ValidationFails{Request fails?}
    ValidationFails -->|Yes| ConfigIssue[Review request config<br/>Check model and data parameters]
    ValidationFails -->|No| OtherIssue[Check logs or open a support ticket]
    style Start fill:#e1f5ff

Common Issues

Pods not reach the Running state

kubectl describe pod -n synthetic-data-ns <POD_NAME>
kubectl logs -n synthetic-data-ns <POD_NAME>

Check that the Karpenter NodePool provisioned the required nodes. Ensure that OpenTofu created the S3 bucket and IAM role.

API returns 401 Unauthorized

Ensure that the login token is valid and has not expired. Re-authenticate using the login endpoint and update the Authorization header.

API returns 403 Forbidden

Verify that the user’s role includes the can_create_token permission. Follow the User Creation in PPC steps to confirm role configuration.

OpenTofu errors on tofu apply

• AccessDenied: The AWS credentials used during installation do not have the required IAM permissions. For more information about permissions, refer to the IAM Permissions for Installation section.
• BucketAlreadyExists: An S3 bucket with the same name already exists. Choose a unique bucket name or import the existing bucket into the OpenTofu state.

Helm upgrade fails with immutable field error

Delete the existing release, then re-run the install command from Server Installation:

helm uninstall synthetic-data -n synthetic-data-ns
# Re-run the install command

For more troubleshooting guidance, refer to Protegrity Support.