Protegrity AI Developer Edition Features

• 1: Data Discovery
• 1.1: Data Discovery Architecture
• 1.2: What's New
• 1.3: Prerequisites for Data Discovery
• 1.4: Setting up Data Discovery
• 1.5: Running the Data Discovery samples
• 1.6: Using the Data Discovery APIs
• 1.7: Uninstalling Data Discovery
• 2: Semantic Guardrails
• 2.1: Semantic Guardrails Architecture
• 2.2: Prerequisites for Semantic Guardrails
• 2.3: Setting up Semantic Guardrails
• 2.4: Running the Semantic Guardrails samples
• 2.5: Using the Semantic Guardrails APIs
• 2.6: Uninstalling Semantic Guardrails
• 3: Synthetic Data Generation
• 3.1: Synthetic Data Architecture
• 3.2: Prerequisites for Synthetic Data
• 3.3: Setting up Synthetic Data
• 3.4: Running the Synthetic Data samples
• 3.5: Using the Synthetic Data APIs
• 3.6: Uninstalling Synthetic Data
• 4: Anonymization
• 4.1: Anonymization Architecture
• 4.2: Prerequisites for Anonymization
• 4.3: Setting up Anonymization
• 4.4: Running the Anonymization samples
• 4.5: Using the Anonymization APIs
• 4.6: Uninstalling Anonymization
• 5: Data Protection
• 5.1: Prerequisites for Data Protection
• 5.2: Setting up Data Protection Features
• 5.2.1: Building the Python Modules
• 5.2.2: Building the Java Libraries
• 5.3: Running the Data Protection samples
• 5.4: Using the Application Protector Python APIs
• 5.5: Using the Application Protector Java APIs
• 5.6: Uninstalling Data Protection

1 - Data Discovery

Data Discovery is a powerful feature that helps organizations identify and classify sensitive data across their entire data estate. By leveraging AI-powered scanning and classification, Data Discovery enables organizations to gain visibility into their data landscape, understand where sensitive data resides, and take appropriate actions to protect it.

The documentation here for Data Discovery covers its specific requirements and relationship with AI Developer Edition. For more information, refer to the complete body of the Data Discovery documentation.

1.1 - Data Discovery Architecture

Data Discovery is a powerful, developer-friendly feature. For more information, refer to the complete body of the Data Discovery documentation.

Overview

Data Discovery Text Classification service advances data discovery and classification. It specializes in the detection of Personally Identifiable Information (PII), Protected Health Information (PHI), and Payment Card Information (PCI) within plain text and free-text inputs. Unlike traditional structured data tools, it excels in dynamic, unstructured environments such as chatbot conversations, call transcripts, and Generative AI (GenAI) outputs.

Architecture

For more information about the general architecture and working of Data Discovery, refer to General architecture of Data Discovery.

1.2 - What's New

Data Discovery

• Standardized v2 APIs for Classify for Text and Tabular data, and Transform.
• New endpoints added for API docs, log level management, and version info.
• Improved Context Provider and Pattern Provider AI models.
• Updated Classify API default threshold to 0.7. The default threshold for v1.1 remains at 0.0 for compatibility.
• Added usage metrics and per‑language accuracy metrics.
• Extended PII detection to multiple Markdown dialects.
  

For more details, refer to What’s New in Data Discovery.

Major Changes

• Added Jupyter notebooks examples
  • data-discovery/samples/jupyter/sample-classification-jupyter-text.ipynb
  • data-discovery/samples/jupyter/sample-classification-jupyter-tabular.ipynb
  • data-discovery/samples/jupyter/sample-redaction-jupyter-text.ipynb
    

For more information on these examples, refer to Notebooks.

1.3 - Prerequisites for Data Discovery

Ensure that the following prerequisites are met before running these examples for Data Discovery:

• Docker CLI, Docker Compose, and Python are installed. For more information, refer to AI Developer Edition, Pre-requisites Guide.
• For shell samples: Bash version greater than or equal to 5.1.8 and curl version greater than or equal to 7.76.1.
• For notebook samples: JupyterLab version greater than or equal to 4.5.6.

1.4 - Setting up Data Discovery

Use the containers to set up the Data Discovery components required for identifying sensitive data.

• Fresh setup
• Upgrade

1.5 - Running the Data Discovery samples

Use the information in this section to run the Data Discovery samples provided in the data-discovery/samples folder. These samples demonstrate how to use the Data Discovery API for classification and redaction of sensitive information in text and tabular data.

Running Data Discovery

The example scripts under the data-discovery/ folder demonstrate classification and redaction using the Data Discovery v2 API. For more information about the Data Discovery APIs, refer to the section Data Discovery APIs.

Note: A dedicated data-discovery/docker-compose.yml is provided to start only the Data Discovery service.

1. Open a command prompt.

2. Navigate to the directory where AI Developer Edition is cloned.

3. Launch data-discovery services. Refer to the docker compose setup page to know how to set up the package.

4. Run any of the example scripts from the data-discovery/ directory:

   Classification - text input

   python data-discovery/samples/python/sample-classification-python-text.py
   bash data-discovery/samples/bash/sample-classification-bash-text.sh
   

   Classification - tabular (CSV) input

   python data-discovery/samples/python/sample-classification-python-tabular.py
   bash data-discovery/samples/bash/sample-classification-bash-tabular.sh
   

   Redaction

   python data-discovery/samples/python/sample-redaction-python.py
   bash data-discovery/samples/bash/sample-redaction-bash.sh
   

5. View the output of the files processed on the screen. The output displays the classification labels or redacted text returned by the Data Discovery service.

Using Notebooks for Classifying and Redacting unstructured documents

The notebook demonstrates how to use the Data Discovery API with Python’s requests library to classify and redact sensitive information in unstructured text and tabular data. It submits sample data containing sensitive information to a local Data Discovery service for classification. It also shows how the Transform API replaces detected PII entities with standardized labels, for example, [PERSON] or [SOCIAL_SECURITY_ID].

1. Make sure you have the Jupyter notebook installed in your system.

2. Navigate to the directory where AI Developer Edition is cloned.

3. Run the following command to start Jupyter Lab.

   jupyter lab
   

4. Copy the URL displayed and navigate to the site from a web browser. Ensure that localhost is replaced with the IP address of the system where the AI Developer Edition is set up.

5. Open the example at:

   • data-discovery/samples/jupyter/sample-classification-jupyter-text.ipynb
   • data-discovery/samples/jupyter/sample-classification-jupyter-tabular.ipynb
   • data-discovery/samples/jupyter/sample-redaction-jupyter-text.ipynb

6. Run all cells and see the results of the execution interactively.

1.6 - Using the Data Discovery APIs

Data Discovery has three types of API Endpoints:

• Classify to identify, classify, and locate sensitive data.
• Transform to identify, classify, and transform sensitive data.
• Common APIs, the standard operational endpoints available on the service.

For more information about Data Discovery APIs, refer to the complete body of the Data Discovery documentation.

1.7 - Uninstalling Data Discovery

1. Open a command prompt.

2. Navigate to the cloned repository location.

3. Uninstall Semantic Guardrails if it is installed. For complete instructions, refer to Uninstalling Semantic Guardrails.

4. Navigate to the data-discovery directory.

   cd data-discovery
   

5. Run the following command to remove the containers and images.

   docker compose down --rmi all
   

2 - Semantic Guardrails

Semantic Guardrails evaluates and mitigates risks in AI-generated content by scanning conversations for policy violations, sensitive data exposure, and off-topic responses. It enables organizations to enforce data protection policies, monitor data usage, and ensure compliance with regulatory requirements.

2.1 - Semantic Guardrails Architecture

Protegrity’s GenAI Security Semantic Guardrails solution is a security guardrail engine for AI systems. It evaluates risks in GenAI chatbots, workflows, and agents through advanced semantic analytics and intent classification to detect potentially malicious messages. PII detection can also be leveraged for comprehensive security coverage.

The documentation here for Semantic Guardrails covers its specific requirements and relationship with AI Developer Edition. For more information, refer to the complete body of the Semantic Guardrails documentation.

Overview

Semantic Guardrails is trained on synthetic customer-service AI chatbot datasets. The system performs best when analyzing conversations expected to match the training domain, that is, English-language-based customer service interactions involving orders, tickets, and purchases.

For domain-specific and user-specific applications requiring high detection accuracy, fine-tuning is necessary to completely leverage the model’s ability. This helps the model to learn from expected conversation patterns and message structures in both the inputs and outputs of protected GenAI systems.

The system operates by analyzing conversations between participants. These participants are users and AI systems, such as LLMs, agents, or contextual information sources. Furthermore, the system utilizes Protegrity’s Data Discovery, if present in the same network environment, to leverage PII detection in its internal decision algorithm.

The solution provides individual message risk scores and classifications, and cumulative conversation risk scores and classifications. This dual-scoring approach ensures that while individual messages may appear benign, potentially risky cumulative conversation patterns are identified. This significantly enhances detection of sophisticated attack vectors, including LLM jailbreaks and prompt injection attempts.

Architecture

For more information about the general architecture and working of Semantic Guardrails, refer to General architecture of Semantic Guardrails.

2.2 - Prerequisites for Semantic Guardrails

Ensure that the following prerequisites are met before running these examples for Semantic Guardrails:

• Docker CLI, Docker Compose, and Python are installed. For more information, refer to AI Developer Edition, Pre-requisites Guide.
• For shell samples: Bash version greater than or equal to 5.1.8 and curl version greater than or equal to 7.76.1.
• For notebook samples: JupyterLab version greater than or equal to 4.5.6.

2.3 - Setting up Semantic Guardrails

Use the containers to set up Semantic Guardrails components required for identifying sensitive data.

• Fresh setup
• Upgrade

docker compose logs

2.4 - Running the Semantic Guardrails samples

The example scripts under the semantic-guardrail/ folder demonstrate the usage of Semantic Guardrails APIs. For more information about the Semantic Guardrails APIs, refer to the section Semantic Guardrails APIs.

Note: A dedicated semantic-guardrail/docker-compose.yml is provided to start the Data Discovery and the Semantic Guardrails services.

1. Open a command prompt.

2. Navigate to the directory where AI Developer Edition is cloned.

3. Run the following command to test Semantic Guardrails using Python scripts. The following command submits a multi-turn conversation for analysis. One for semantic and a second one for PII processing.

   python semantic-guardrail/samples/python/sample-guardrail-python.py
   

4. Run the following command to start Jupyter Lab for running Semantic Guardrails.

   jupyter lab
   

5. Copy the URL displayed and navigate to the site from a web browser. Ensure that localhost is replaced with the IP address of the system where the AI Developer Edition is set up.

6. In the left pane of the Jupyter Lab, navigate to semantic-guardrail/samples/python/sample-app-semantic-guardrails.

7. Open the Sample Application.ipynb file.

8. Click the Play icon and follow the prompts in the Jupyter Lab.

2.5 - Using the Semantic Guardrails APIs

Semantic Guardrails has the following types of API Endpoints:

• Scan API to scan and classify sensitive data.
• Domain Model API to view the domain models available.

For more information about Semantic Guardrails APIs, refer to the complete body of the Semantic Guardrails documentation.

2.6 - Uninstalling Semantic Guardrails

1. Open a command prompt.

2. Navigate to the cloned repository location.

3. Navigate to the semantic-guardrails directory.

   cd semantic-guardrail
   

4. Run the following command to remove the containers and images.

   docker compose down --rmi all
   

3 - Synthetic Data Generation

Synthetic Data Generation is a powerful feature that helps organizations create realistic synthetic data for testing and development without exposing real sensitive information. By leveraging AI, Synthetic Data Generation enables organizations to generate high-quality synthetic data that maintains the statistical properties of the original data while ensuring privacy and compliance.

3.1 - Synthetic Data Architecture

Protegrity’s Synthetic Data solution is a Synthetic Data generator which generates artificial data that is realistic, statistically accurate, and privacy-safe. This data unlocks the full potential of AI and analytics. By creating entirely new data that mirrors the patterns of your original datasets but contains no sensitive information, you can train and test AI models without risk. You can also scale these models without exposure or compliance violations.

An overview of the communication is shown in the following figure.

The Synthetic Data system includes the following core components:

Key Pods and Services

• Synthetic Data App Pod

  • Orchestrates Synthetic Data generation.

• MLFlow Pod

  • Captures model training and evaluation.
  • Hosted in containers for scalability.

• MinIO Pod

  • Stores models, model artifacts, and generated reports.
  • Used by both MLFlow and Synthetic Data App pods.

• SQL Database Server Pod

  • Provides storage for MLFlow experiments metadata.

Data Generation Interfaces

Synthetic Data can be generated using:

• REST APIs
• Swagger UI

These interfaces allow developers and data scientists to interact with the system programmatically or visually.

Access and Networking

Users access the Protegrity Synthetic Data using HTTP over default port 8095 and other services using the following ports:

Cloud Hosting Options

The entire Synthetic Data API can be hosted using any cloud-provided Kubernetes service, including:

• Amazon Elastic Kubernetes Service (EKS)
• Google Kubernetes Engine (GKE)
• Microsoft Azure Kubernetes Service (AKS)
• Red Hat OpenShift
• Other Kubernetes platforms

This flexibility allows organizations to scale Synthetic Data generation securely across environments.

3.2 - Prerequisites for Synthetic Data

Ensure that the following prerequisites are met before running these examples for Synthetic Data:

• Docker CLI, Docker Compose, and Python are installed. For more information, refer to AI Developer Edition, Pre-requisites Guide.
• For shell samples: Bash version greater than or equal to 5.1.8 and curl version greater than or equal to 7.76.1.
• For notebook samples: JupyterLab version greater than or equal to 4.5.6.

3.3 - Setting up Synthetic Data

Use the containers to set up the Synthetic Data feature for data generation.

• Fresh setup
• Upgrade

3.4 - Running the Synthetic Data samples

The example scripts under the synthetic-data/ folder demonstrate the usage of Synthetic Data APIs. For more information about the Synthetic Data APIs, refer to the section Synthetic Data APIs.

Note: A dedicated synthetic-data/docker-compose.yml is provided to start the Synthetic Data services.

1. Open a command prompt.

2. Navigate to the directory where AI Developer Edition is cloned.

3. Run the following command to start Jupyter Lab.

   jupyter lab
   

4. Copy the URL displayed and navigate to the site from a web browser. Ensure that localhost is replaced with the IP address of the system where the AI Developer Edition is set up.

5. In the left pane of the Jupyter Lab, navigate to synthetic-data/samples/python/sample-app-synthetic-data.

6. Open the synthetic_data.ipynb file.

7. Click the Play icon and follow the prompts in the Jupyter Lab.

3.5 - Using the Synthetic Data APIs

base

Base HTTP client for SDK communication

Provides low-level HTTP communication utilities shared across all SDK clients. Handles request construction, response parsing, error handling, and retries.

dataframe_to_base64

def dataframe_to_base64(df: pd.DataFrame) -> str

Convert DataFrame to base64-encoded CSV string for inline data transfer.

Arguments:

• df - DataFrame to encode.

Returns:

• str - Base64-encoded CSV string.

Examples:

```
df = pd.DataFrame({"a": [1, 2], "b": [3, 4]})
encoded = dataframe_to_base64(df)
print(encoded[:20])
YSxiCjEsMwoyLDQK
```

BaseClient

class BaseClient()

Base HTTP client with common request/response logic.

Provides methods for making HTTP requests to the synthesis API with automatic retry, error handling, and response parsing.

Arguments:

• config ClientConfig - Client configuration with endpoint and settings.

Examples:

```python
config = ClientConfig(endpoint="http://localhost:8000")
client = BaseClient(config)
response = client._request("POST", "/pty/syntheticdata/v2/synthesize", data=payload)
```

__init__

def __init__(config: ClientConfig)

Initialize base client.

Arguments:

• config - Client configuration.

client

Remote synthesizer clients for the Synthetic Data SDK

Provides client classes that mirror the local synthesizer interface but delegate computation to a remote REST API. Enables distributed synthesis workflows without local compute resources.

Classes: SynthesisClient: Low-level API client for direct endpoint access. RemoteVineCopula: Remote single-table vine copula synthesizer. RemoteMultiTableVineCopula: Remote multi-table synthesizer.

Examples:

Single-table synthesis:

```python
from synthetic_data_sdk import RemoteVineCopula
import pandas as pd

# Initialize client
synth = RemoteVineCopula(
    endpoint="http://api.example.com:8000", categorical_cols=["city", "product"]
)

# Fit on training data
df = pd.read_csv("customers.csv")
synth.fit(df)

# Generate synthetic data
synthetic = synth.transform(n=10000)
synthetic.to_csv("synthetic_customers.csv", index=False)
```

Multi-table synthesis:

```python
from synthetic_data_sdk import RemoteMultiTableVineCopula

synth = RemoteMultiTableVineCopula(
    endpoint="http://api.example.com:8000",
    relationships=[
        ("customers", "customer_id", "orders", "customer_id"),
        ("orders", "order_id", "items", "order_id"),
    ],
    synthesizer_params={
        "customers": {"categorical_cols": ["city"]},
        "orders": {"categorical_cols": ["status"]},
    },
)

tables = {"customers": customers_df, "orders": orders_df, "items": items_df}
synth.fit(tables)
synthetic_tables = synth.transform(n=500)
```

Model persistence:

```python
# Fit and save on server
synth = RemoteVineCopula(endpoint="http://api.example.com:8000", model_version="prod_v2")
synth.fit(training_data)

# Later: load and use
synth = RemoteVineCopula(endpoint="http://api.example.com:8000", model_version="prod_v2")
synthetic = synth.transform(n=5000)  # No refitting needed
```

SynthesisClient

class SynthesisClient(BaseClient)

Low-level client for direct API interaction.

Provides a thin wrapper around the synthesis endpoint for applications that need fine-grained control over request payloads. Most users should use RemoteVineCopula or RemoteMultiTableVineCopula instead.

Arguments:

• config ClientConfig - Client configuration.

Examples:

```python
from synthetic_data_sdk import SynthesisClient, ClientConfig

config = ClientConfig(endpoint="http://localhost:8000")
client = SynthesisClient(config)

# Manual request construction
response = client.synthesize(
    model_name="vine",
    action="fit_transform",
    training_data="data/customers.csv",
    n_samples=1000,
    parameters={"categorical_cols": ["city"]},
)
print(response["status"])
success
```

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 synthesis request to API.

Arguments:

• model_name - Model type (‘vine’ or ‘vine_multitable’).
• action - Action to perform (‘fit’, ’transform’, ‘fit_transform’).
• training_data - Base64-encoded CSV string for single-table inline data.
• training_data_path - Cloud URI or local path to single-table training data CSV.
• training_data_tables - Dict mapping table names to local paths/file:// URIs or cloud URIs for multi-table. All tables must use the same input kind; mixing raises ValueError.
• n_samples - Number of synthetic samples to generate.
• model_version - Version identifier for model persistence.
• parameters - Model-specific parameters.
• output_uri - Cloud URI to write synthetic data to (e.g. ‘s3://bucket/out.csv’). When omitted, synthetic data is returned inline in the response. Supported schemes: s3://, gs://, azure://, minio://.
• mlops_config - Per-request MLOps tracking configuration. When provided, overrides the server’s default MLOps settings for this request only. All keys are optional and fall back to the server configuration when omitted. Useful for multi-tenant MLOps setups where each caller tracks to their own Postgres / artifact store. Accepted keys (all optional):
  • database_dsn: connection string for the MLOps DB.
  • storage_dsn: artifact storage URI (s3://, local://, gs://, azure://, minio://).
  • experiment_prefix: defaults to ‘synthetic-data’.

Example:

• {"database_dsn" - “postgresql://user:pw@host:5432/mlops”,
• "storage_dsn" - “s3://key:secret@us-east-1/bucket/mlops/”}

Returns:

• dict - API response with status, data, and metadata.

Raises:

• SynthesisAPIError - If request fails.

Examples:

```python
response = client.synthesize(
    model_name="vine",
    action="fit_transform",
    training_data_path="s3://key:secret@region/bucket/data.csv",
    n_samples=1000,
    parameters={"categorical_cols": ["city"]},
    mlops_config={"database_dsn": "postgresql://user:pw@host:5432/mlops"},
)
data_synthesis = response["data"]
```

list_models

def list_models(model_type: str | None = None,
                all_metrics: bool = False) -> list[dict[str, Any]]

List model versions currently in Production.

Arguments:

• model_type - Filter by algorithm class (e.g. "vine").
• all_metrics - When False (default), metrics contains only the promotion metric. When True, all logged metrics are returned.

Returns:

List of dicts with model_name, model_type, model_version, semantic_version, stage, input_schema, metrics, registered_at.

synthesize_async

def synthesize_async(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) -> dict[str, Any]

Submit a synthesis request for background execution.

Returns immediately with a job_id that can be polled via :meth:get_job_status.

Arguments:

• model_name - Model type (‘vine’ or ‘vine_multitable’).
• action - Action to perform (‘fit’, ’transform’, ‘fit_transform’).
• training_data - Base64-encoded CSV string for single-table inline data.
• training_data_path - Cloud URI or local path to single-table training data CSV.
• training_data_tables - Dict mapping table names to local paths/file:// URIs or cloud URIs for multi-table. All tables must use the same input kind; mixing raises ValueError.
• n_samples - Number of synthetic samples to generate.
• model_version - Version identifier for model persistence.
• parameters - Model-specific parameters.
• output_uri - Cloud URI to write synthetic data to. None means inline response.

Returns:

• dict - {"job_id": "...", "status": "queued", ...}

get_job_status

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

Get the current status of a job.

Arguments:

• job_id - Unique job identifier returned by :meth:synthesize_async.

Returns:

• dict - Job status including job_id, status, progress, step, message, error, synth_data_uri, timestamps.

list_jobs

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

List jobs with optional filtering and pagination.

Arguments:

• status - Filter by status (pending, running, completed, failed, cancelled).
• limit - Page size (1-1000).
• offset - Page offset.

Returns:

• dict - {"jobs": [...], "total": int, "limit": int, "offset": int}

get_job_history

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

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

Arguments:

• job_id - Unique job identifier.

Returns:

• list - List of history entry dicts with sequence, status, progress, step, changed_at, etc.

delete_job

def delete_job(job_id: str) -> None

Delete a job record (or cancel if running).

Arguments:

• job_id - Unique job identifier.

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]

Poll a job until it reaches a terminal state.

Arguments:

• job_id - Unique job identifier.
• poll_interval - Seconds between polls (default 2s).
• timeout - Maximum seconds to wait (default 600s / 10 min).
• callback - Optional callable (status_dict) -> None invoked on each poll.

Returns:

• dict - Final job status.

Raises:

• TimeoutError - If job doesn’t complete within timeout.

generate_conditional

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 synthetic data matching conditional scenarios.

Fits a synthesizer on real data and generates synthetic samples matching specific conditions (filters), with optional pattern amplification and distribution drift injection. Useful for scenario testing, edge case generation, and what-if analysis.

Arguments:

• real_data - Path to CSV file or DataFrame containing training data.
• model_name - Model type (‘vine’, ‘smote’, ’tabdiff’, ’tabulargan’).
• n_samples - Number of synthetic samples to generate.
• conditions - Dictionary of column conditions. Examples:
  • Exact match: {‘fraud’: 1, ‘status’: ‘active’}
  • Comparison: {‘age’: ‘>65’, ‘income’: ‘<=50000’}
  • Range: {‘age’: ‘between(30,50)’}
  • Membership: {‘city’: ‘in(NYC,LA,Chicago)’}
• amplify_patterns - Multiplier for conditional pattern amplification (e.g., 1.5 for 50% increase).
• inject_drift - Dictionary of column drift shifts. Examples:
  • {‘income’: -20000, ‘age’: -5} # Recession scenario
  • {‘credit_score’: -50} # Credit deterioration
• categorical_cols - List of categorical column names for proper encoding.
• random_state - Random seed for reproducibility.

Returns:

• dict - Response containing:
  • success (bool): Whether generation succeeded.
  • n_samples (int): Number of samples generated.
  • synthetic_data (str): Base64-encoded CSV data.
  • conditions_applied (dict): Conditions that were applied.
  • drift_applied (dict): Drift shifts that were applied.
  • warnings (List[str]): Any warnings from generation.
  • metadata (dict): Model and column information.

Raises:

• SynthesisAPIError - If request fails.

Examples:

Fraud scenario - generate high-risk fraud cases:

```python
from synthetic_data_sdk import SynthesisClient, ClientConfig
import pandas as pd

config = ClientConfig(endpoint="http://localhost:8000")
client = SynthesisClient(config)

response = client.generate_conditional(
    real_data="data/transactions.csv",
    model_name="vine",
    n_samples=1000,
    conditions={"fraud": 1, "age": ">65"},
    categorical_cols=["status", "fraud"],
)

# Decode synthetic data
import base64, io
decoded = base64.b64decode(response["synthetic_data"])
synthetic = pd.read_csv(io.StringIO(decoded.decode("utf-8")))
print(f"Generated {len(synthetic)} fraud cases")
```

Recession scenario - income and employment impact:

```python
response = client.generate_conditional(
    real_data=customer_df,  # Can pass DataFrame directly
    model_name="vine",
    n_samples=5000,
    conditions={"age": ">55"},  # Focus on older customers
    inject_drift={
        "income": -20000,  # $20k income decrease
        "credit_score": -50,  # 50-point credit drop
    },
    categorical_cols=["status", "region"],
)
print(response["drift_applied"])
{'income': -20000, 'credit_score': -50}
```

Edge case generation - extreme values:

```python
response = client.generate_conditional(
    real_data="data/loans.csv",
    model_name="vine",
    n_samples=500,
    conditions={"loan_amount": ">100000", "credit_score": "<600"},
    amplify_patterns=2.0,  # 2x amplification for extreme patterns
    random_state=42,
)
```

_RemoteSingleTableSynthesizer

class _RemoteSingleTableSynthesizer()

Base class for remote single-table synthesizers.

Eliminates code duplication across RemoteVineCopula, RemoteTabDiff, RemoteSMOTE, and RemoteTabularGAN. Subclasses need only set _model_name and _version_prefix class attributes. Model-specific methods (e.g. transform_conditional) can be added in the subclass.

__init__

def __init__(endpoint: str | None = None,
             model_version: str | None = None,
             config: ClientConfig | None = None,
             mlops_config: dict[str, Any] | None = None,
             **parameters)

Initialize a remote single-table synthesizer.

Arguments:

• endpoint - API endpoint URL. Not required if config is provided.
• model_version - Version identifier for model persistence.
• config - Advanced client configuration (timeouts, auth, etc.).
• mlops_config - Per-request MLOps tracking configuration. When provided, overrides the server’s default MLOps settings for this request only. All keys are optional and fall back to the server configuration when omitted. Accepted keys: database_dsn, storage_dsn, experiment_prefix, auto_promote, promotion_metric, promotion_direction.
• **parameters - Model-specific hyper-parameters forwarded to the synthesizer constructor.

list_models

def list_models(all_metrics: bool = False) -> list[dict[str, Any]]

List Production model versions for this model type.

Calls the shared models endpoint with model_type=<_model_name> and returns all versions currently in the Production stage.

Arguments:

• all_metrics - When False (default), metrics contains only the promotion metric. When True, all logged metrics are returned.

Returns:

List of dicts with model_name, model_type, model_version, semantic_version, stage, input_schema, metrics, registered_at.

fit

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

Fit model on training data.

Uploads training data to the API and triggers model fitting. The fitted model is stored on the server using the configured model_version.

Arguments:

• df - Training data as DataFrame, local file path, or cloud URI.

Returns:

Self (for method chaining).

Raises:

• SynthesisAPIError - If fitting fails.

transform

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

Generate synthetic data using a fitted model.

Arguments:

• n - Number of synthetic samples to generate.

Returns:

Synthetic data with the same schema as the training data.

Raises:

• RuntimeError - If model is not fitted.
• SynthesisAPIError - If generation fails.

fit_transform

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

Fit model and generate synthetic data in one call.

Arguments:

• df - Training data.
• n - Number of synthetic samples to generate.

Returns:

Synthetic data.

Raises:

• SynthesisAPIError - If operation fails.

summary

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

Get summary statistics from a fitted model.

Returns:

Model summary with statistics and metadata.

Raises:

• RuntimeError - If model is not fitted.
• SynthesisAPIError - If request fails.

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 real data.

Computes comprehensive quality metrics including univariate distributions, correlation preservation, mutual information, predictive performance, and privacy metrics.

Arguments:

• real_data - Real training data.
• synthetic_data - Synthetic data to evaluate.
• categorical_cols - Categorical column names.
• target_col - Target column for TSTR/TRTR evaluation.
• task_type - 'classification' or 'regression' for TSTR.
• eval_params - Additional FidelityEvaluator configuration.

Returns:

Evaluation metrics dictionary.

Raises:

• SynthesisAPIError - If evaluation fails.

RemoteVineCopula

class RemoteVineCopula(_RemoteSingleTableSynthesizer)

Remote client for single-table vine copula synthesis.

Mirrors the interface of the local VineCopula class but delegates all computation to a remote REST API. Provides the same fit/transform workflow without requiring local compute resources.

In addition to the shared single-table methods (fit, transform, fit_transform, evaluate, summary), this class exposes transform_conditional for scenario-based generation.

Arguments:

• endpoint - Base URL of the synthesis API.
• model_version - Version identifier for model persistence.
• config - Advanced client configuration.
• storage_config - Artifact storage credentials/configuration.
• **parameters - Model parameters (categorical_cols, vine_type, etc.).

Examples:

```python
synth = RemoteVineCopula(
    endpoint="http://localhost:8000",
    categorical_cols=["city", "product"],
    vine_type="cvine",
)
synth.fit(df)
synthetic = synth.transform(n=1000)
```

transform_conditional

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 conditional synthetic data matching specific scenarios.

Fits a vine copula on the provided data and generates synthetic samples matching specified conditions, with optional pattern amplification and distribution drift.

Arguments:

• df - Training data to fit the model on.
• n - Number of synthetic samples to generate.
• conditions - Column conditions (exact, comparison, range, membership).
• amplify_patterns - Multiplier for conditional pattern amplification.
• inject_drift - Column drift shifts (e.g. {'income': -20000}).
• random_state - Random seed for reproducibility.

Returns:

Synthetic data matching specified conditions.

Raises:

• SynthesisAPIError - If generation fails.

RemoteMultiTableVineCopula

class RemoteMultiTableVineCopula()

Remote client for multi-table vine copula synthesis.

Mirrors the interface of MultiTableVineCopula but delegates computation to a remote API. Preserves foreign key relationships across tables.

Arguments:

• endpoint str - Base URL of the synthesis API.
• relationships List[Tuple[str, str, str, str]] - Foreign key relationships.
• model_version Optional[str] - Version identifier for model persistence.
• config Optional[ClientConfig] - Advanced client configuration.
• synthesizer_params Optional[Dict[str, Dict]] - Per-table parameters.

Examples:

Multi-table synthesis:

```python
from synthetic_data_sdk import RemoteMultiTableVineCopula

synth = RemoteMultiTableVineCopula(
    endpoint="http://localhost:8000",
    relationships=[("customers", "customer_id", "orders", "customer_id")],
    synthesizer_params={"customers": {"categorical_cols": ["city", "segment"]}},
)

tables = {"customers": customers_df, "orders": orders_df}
synth.fit(tables)
synthetic = synth.transform(n=100)
print(synthetic.keys())
dict_keys(['customers', 'orders'])
```

__init__

def __init__(relationships: list[tuple[str, str, str, str]],
             endpoint: str | None = None,
             model_version: str | None = None,
             config: ClientConfig | None = None,
             synthesizer_params: dict[str, dict[str, Any]] | None = None,
             primary_keys: dict[str, str] | None = None,
             mlops_config: dict[str, Any] | None = None)

Initialize remote multi-table client.

Arguments:

• relationships - List of (parent_table, parent_col, child_table, child_col).
• endpoint - API endpoint URL. Not required if config is provided.
• model_version - Version identifier for persistence.
• config - Advanced client configuration. If provided, endpoint can be omitted.
• synthesizer_params - Per-table parameters (categorical_cols, etc.).
• primary_keys - Optional mapping of table name -> primary-key column name for tables that are not inferred automatically (e.g. leaf tables).
• Example - {"order_items": "item_id"}.
• mlops_config - Per-request MLOps tracking configuration. When provided, overrides the server’s default MLOps settings for this request only. All keys are optional and fall back to the server configuration when omitted. Accepted keys: database_dsn, storage_dsn, experiment_prefix, auto_promote, promotion_metric, promotion_direction.

list_models

def list_models(all_metrics: bool = False) -> list[dict[str, Any]]

List Production model versions for multi-table vine copula.

Calls the shared models endpoint with model_type=vine_multitable and returns all versions currently in the Production stage.

Arguments:

• all_metrics - When False (default), metrics contains only the promotion metric. When True, all logged metrics are returned.

Returns:

List of dicts with model_name, model_type, model_version, semantic_version, stage, input_schema, metrics, registered_at.

fit

def fit(
    tables: dict[str, pd.DataFrame] | dict[str, str] | dict[str, Path]
) -> "RemoteMultiTableVineCopula"

Fit multi-table model on training data.

Dual-Mode Data Loading: The SDK automatically detects your input type for EACH table and selects the appropriate loading mode:

1. Dict of DataFrames → Inline Base64:

• Each DataFrame encoded as base64
• All tables sent in HTTP body as dict
• Server decodes using explicit is_inline=True flag

2. Dict of Local Files → Inline Base64:

• SDK reads each file on client side
• Converts to dict of base64 strings
• Server decodes using explicit is_inline=True flag

3. Dict of Cloud URIs → Server Load:

• URIs passed directly (no data transfer in HTTP)
• Server loads each table from cloud storage
• Uses explicit is_inline=False flag

Mixed modes are NOT supported - all tables must use same mode.

Arguments:

• tables - Training tables keyed by name. Each value can be:
  • DataFrame (mode 1)
  • Local file path (mode 2)
  • Cloud URI with supported scheme (mode 3) All tables must be the same type.

Returns:

• RemoteMultiTableVineCopula - Self (for method chaining).

Raises:

• SynthesisAPIError - If fitting fails.
• ValueError - If tables use mixed modes (e.g., DataFrame + cloud URI).
• FileNotFoundError - If any local file path doesn’t exist.

Examples:

```python
synth = RemoteMultiTableVineCopula(
    endpoint="http://localhost:8000",
    relationships=[{"parent": "customers", "child": "orders"}],
)

# Mode 1: Dict of DataFrames (auto-detects → inline base64)
tables = {"customers": customers_df, "orders": orders_df}
synth.fit(tables)

# Mode 2: Dict of local files (SDK reads → inline base64)
tables = {"customers": "./data/customers.csv", "orders": "./data/orders.csv"}
synth.fit(tables)

# Mode 3: Dict of cloud URIs (passes URIs → server loads)
tables = {
    "customers": "s3://bucket/customers.csv",
    "orders": "s3://bucket/orders.csv",
}
synth.fit(tables)
```

transform

def transform(n: int, **kwargs) -> dict[str, pd.DataFrame]

Generate synthetic multi-table data.

Arguments:

• n int - Number of parent table samples.
• **kwargs - Additional generation parameters.

Returns:

Dict[str, pd.DataFrame]: Synthetic tables keyed by name.

Raises:

• RuntimeError - If model not fitted.
• SynthesisAPIError - If generation fails.

Examples:

```python
synth.fit(tables)
synthetic = synth.transform(n=100)
print(f"Customers: {len(synthetic['customers'])} rows")
print(f"Orders: {len(synthetic['orders'])} rows")
```

fit_transform

def fit_transform(tables: dict[str, pd.DataFrame], n: int,
                  **kwargs) -> dict[str, pd.DataFrame]

Fit model and generate synthetic data in one call.

Arguments:

• tables Dict[str, pd.DataFrame] - Training tables.
• n int - Number of parent table samples.
• **kwargs - Additional parameters.

Returns:

Dict[str, pd.DataFrame]: Synthetic tables.

Raises:

• SynthesisAPIError - If operation fails.

Examples:

```python
synth = RemoteMultiTableVineCopula(
    endpoint="http://localhost:8000",
    relationships=[("customers", "id", "orders", "customer_id")],
)
synthetic = synth.fit_transform(tables, n=100)
```

summary

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

Get summary statistics from fitted model.

Returns:

• dict - Model summary with statistics and metadata.

Raises:

• RuntimeError - If model not fitted.
• SynthesisAPIError - If request fails.

validate_relationships

def validate_relationships(tables: dict[str, pd.DataFrame]) -> dict[str, Any]

Validate foreign key relationships in multi-table data.

Arguments:

• tables Dict[str, pd.DataFrame] - Tables to validate.

Returns:

• dict - Validation results with ‘valid’ boolean and ‘violations’ list.

Raises:

• RuntimeError - If model not fitted.
• SynthesisAPIError - If request fails.

relational_score

def relational_score(real_tables: dict[str, pd.DataFrame],
                     synth_tables: dict[str, pd.DataFrame]) -> dict[str, Any]

Compute relational fidelity score comparing real and synthetic data.

Evaluates relational integrity metrics:

• Foreign key violation rate
• Cardinality preservation (child count distributions)
• Join distribution similarity (cross-table correlations)
• Overall composite relational score

Arguments:

• real_tables Dict[str, pd.DataFrame] - Real multi-table data.
• synth_tables Dict[str, pd.DataFrame] - Synthetic multi-table data.

Returns:

• dict - Relational fidelity scores with structure: {
• 'fk_violation_rate' - float,
• 'fk_violations' - list,
• 'cardinality_preservation' - {
• 'mean_error' - float,
• 'max_error' - float,
• 'details' - list },
• 'join_distribution_similarity' - float,
• 'join_details' - list,
• 'overall_relational_score' - float (0-1),
• 'interpretation' - str }

Raises:

• RuntimeError - If model not fitted.
• SynthesisAPIError - If request fails.

Example:

```python
    # After fitting and generating synthetic data
    client = RemoteMultiTableVineCopula(...)
    client.fit(real_tables)
    synthetic = client.transform(n=1000)
    scores = client.relational_score(real_tables, synthetic)
    print(f"Overall score: {scores['overall_relational_score']:.2f}")
    print(f"FK violations: {scores['fk_violation_rate']:.2%}")
    print(f"Interpretation: {scores['interpretation']}")
```

get_table_order

def get_table_order() -> list[str]

Get the topological order of tables for sampling.

Returns:

• list - List of table names in sampling order.

Raises:

• RuntimeError - If model not fitted.
• SynthesisAPIError - If request fails.

evaluate

def evaluate(real_tables: dict[str, pd.DataFrame],
             synthetic_tables: dict[str, pd.DataFrame],
             categorical_cols: dict[str, 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 multi-table synthetic data quality.

Evaluates each table individually and returns per-table metrics.

Arguments:

• real_tables Dict[str, pd.DataFrame] - Real training tables.
• synthetic_tables Dict[str, pd.DataFrame] - Synthetic tables to evaluate.
• categorical_cols Dict[str, List[str]], optional - Per-table categorical columns.
• target_col str, optional - Target column for TSTR/TRTR.
• task_type str, optional - ‘classification’ or ‘regression’.
• eval_params dict, optional - FidelityEvaluator configuration.

Returns:

• dict - Per-table evaluation metrics.

Raises:

• SynthesisAPIError - If evaluation fails.

Examples:

```python
synth.fit(real_tables)
synthetic = synth.transform(n=100)

metrics = synth.evaluate(
    real_tables, synthetic, categorical_cols={"customers": ["city"]}
)
print(metrics["customers"]["correlation_error"])
```

RemoteTabDiff

class RemoteTabDiff(_RemoteSingleTableSynthesizer)

Remote client for TabDiff diffusion-based synthesis.

Mirrors the interface of the local TabDiff class but delegates all computation to a remote REST API. Ideal for GPU-intensive synthesis without local GPU resources.

Inherits fit, transform, fit_transform, evaluate, and summary from :class:_RemoteSingleTableSynthesizer.

Arguments:

• endpoint - Base URL of the synthesis API.
• model_version - Version identifier for model persistence.
• config - Advanced client configuration.
• storage_config - Artifact storage credentials/configuration.
• **parameters - Model parameters (categorical_cols, epochs, etc.).

Examples:

```python
synth = RemoteTabDiff(
    endpoint="http://localhost:8000",
    categorical_cols=["city", "product"],
    epochs=1000,
)
synth.fit(df)
synthetic = synth.transform(n=1000)
```

RemoteSMOTE

class RemoteSMOTE(_RemoteSingleTableSynthesizer)

Remote client for SMOTE-based synthesis.

Mirrors the interface of the local SMOTE class but delegates all computation to a remote REST API. Useful for oversampling minority classes in imbalanced datasets.

Inherits fit, transform, fit_transform, evaluate, and summary from :class:_RemoteSingleTableSynthesizer.

Arguments:

• endpoint - Base URL of the synthesis API.
• model_version - Version identifier for model persistence.
• config - Advanced client configuration.
• storage_config - Artifact storage credentials/configuration.
• **parameters - Model parameters (categorical_cols, k, noise_scale, etc.).

Examples:

```python
synth = RemoteSMOTE(
    endpoint="http://localhost:8000",
    categorical_cols=["class"],
    k=5,
)
synth.fit(df)
synthetic = synth.transform(n=1000)
```

RemoteTabularGAN

class RemoteTabularGAN(_RemoteSingleTableSynthesizer)

Remote client for TabularGAN-based synthesis.

Mirrors the interface of the local TabularGAN class but delegates all computation to a remote REST API. Uses CTABGAN architecture with mode-specific normalization for mixed continuous/categorical columns.

Inherits fit, transform, fit_transform, evaluate, and summary from :class:_RemoteSingleTableSynthesizer.

Arguments:

• endpoint - Base URL of the synthesis API.
• model_version - Version identifier for model persistence.
• config - Advanced client configuration.
• storage_config - Artifact storage credentials/configuration.
• **parameters - Model parameters (categorical_cols, epochs, etc.).

Examples:

```python
synth = RemoteTabularGAN(
    endpoint="http://localhost:8000",
    categorical_cols=["city", "product"],
    epochs=300,
)
synth.fit(df)
synthetic = synth.transform(n=1000)
```

PrivacyEvaluator

class PrivacyEvaluator()

Remote client for privacy attack evaluation.

Provides methods to evaluate privacy risks in synthetic data using membership inference attacks, sensitive attribute reconstruction, and linkage attack risk analysis.

Arguments:

• endpoint str, optional - Base URL of the synthesis API.
• config Optional[ClientConfig] - Advanced client configuration.

Attributes:

• client SynthesisClient - Underlying HTTP client.

Examples:

Basic privacy evaluation:

```python
from synthetic_data_sdk import PrivacyEvaluator
import pandas as pd

evaluator = PrivacyEvaluator(endpoint="http://localhost:8000")

# Load datasets
train_real = pd.read_csv("data/train.csv")
test_real = pd.read_csv("data/test.csv")
synthetic = pd.read_csv("data/synthetic.csv")

# Evaluate privacy
results = evaluator.evaluate(
    train_real_data=train_real,
    test_real_data=test_real,
    synthetic_data=synthetic,
    sensitive_columns=["ssn", "salary", "diagnosis"],
)

print(f"Overall Risk: {results['overall_risk']}")
print(f"Successful Attacks: {results['summary']['successful_attacks']}")
```

Custom configuration:

```python
results = evaluator.evaluate(
    train_real_data=train_real,
    test_real_data=test_real,
    synthetic_data=synthetic,
    sensitive_columns=["income", "health_status"],
    k_values=[2, 5, 10, 20],
    config={"shadow_models": 10, "attack_model": "xgboost", "random_state": 42},
)
```

Access individual attack results:

```python
for attack in results["attacks"]:
    print(f"Attack: {attack['attack_type']}")
    print(f"Risk Level: {attack['risk_level']}")
    print(f"Metrics: {attack['metrics']}")
```

__init__

def __init__(endpoint: str | None = None, config: ClientConfig | None = None)

Initialize privacy evaluator client.

Arguments:

• endpoint - API endpoint URL (e.g., ‘http://api.example.com:8000’). Not required if config is provided.
• config - Advanced client configuration (timeout, retries, etc.). If provided, endpoint can be omitted.

evaluate

def evaluate(train_real_data: pd.DataFrame | str,
             test_real_data: pd.DataFrame | str,
             synthetic_data: pd.DataFrame | str,
             sensitive_columns: list[str] | None = None,
             k_values: list[int] | None = None,
             config: dict[str, Any] | None = None) -> dict[str, Any]

Evaluate privacy risks in synthetic data.

Executes membership inference attacks, sensitive attribute reconstruction, and linkage attack risk analysis to assess privacy preservation quality.

Arguments:

• train_real_data - Real training data (DataFrame or path/URI to CSV). This is the data used to train the synthesizer.
• test_real_data - Real test/holdout data (DataFrame or path/URI to CSV). This data was NOT used to train the synthesizer.
• synthetic_data - Synthetic data (DataFrame or path/URI to CSV).
• sensitive_columns - List of column names considered sensitive. If None, all columns are considered.
• k_values - List of k values for k-anonymity analysis. Defaults to [2, 3, 5, 10].
• config - Advanced configuration options:
  • shadow_models (int): Number of shadow models for MIA (default: 5)
  • attack_model (str): ML model for MIA (‘catboost’, ‘xgboost’, ‘rf’)
  • sarp_target_model (str): ML model for SARP (‘xgboost’, ‘catboost’)
  • optuna_trials (int): Number of Optuna optimization trials
  • random_state (int): Random seed for reproducibility

Returns:

• dict - Privacy evaluation results containing:
  • request_id (str): Request identifier
  • status (str): ‘success’ or ’error’
  • overall_risk (str): Overall risk level (’low’, ‘medium’, ‘high’, ‘critical’)
  • attacks (List[dict]): Results for each attack type
  • summary (dict): High-level summary with:
  • total_attacks: Number of attacks executed
  • successful_attacks: Number of successful attacks
  • risk_distribution: Count by risk level
  • recommendations: List of recommended actions
  • metadata (dict): Execution details (time, dataset sizes, etc.)

Raises:

• SynthesisAPIError - If evaluation fails.
• ValidationError - If data schemas don’t match or inputs are invalid.
• ConnectionError - If API is unreachable.

Notes:

Attack Types:

1. Membership Inference Attack (MIA):

• Determines if a record was in training data
• Reports: precision, recall, AUC-ROC
• High success rate indicates privacy risk

2. Sensitive Attribute Reconstruction (SARP):

• Attempts to predict sensitive attributes
• Reports: accuracy, F1 score per sensitive column
• High accuracy indicates information leakage

3. Linkage Attack Risk:

• Analyzes k-anonymity of synthetic data
• Reports: violation percentage for each k value
• High violations indicate re-identification risk

Examples:

DataFrame inputs:

```python
evaluator = PrivacyEvaluator(endpoint="http://localhost:8000")

results = evaluator.evaluate(
    train_real_data=train_df,
    test_real_data=test_df,
    synthetic_data=synth_df,
    sensitive_columns=["ssn", "salary"],
)

print(f"Overall Risk: {results['overall_risk']}")
print(f"Attacks: {len(results['attacks'])}")
```

Path/URI inputs:

```python
results = evaluator.evaluate(
    train_real_data="s3://data/train.csv",
    test_real_data="s3://data/test.csv",
    synthetic_data="s3://data/synthetic.csv",
    sensitive_columns=["income", "diagnosis"],
)
```

Custom configuration:

```python
results = evaluator.evaluate(
    train_real_data=train_df,
    test_real_data=test_df,
    synthetic_data=synth_df,
    sensitive_columns=["health_status"],
    k_values=[2, 5, 10, 20],
    config={
        "shadow_models": 10,
        "attack_model": "xgboost",
        "sarp_target_model": "catboost",
        "optuna_trials": 50,
        "random_state": 42,
    },
)
```

Accessing results:

```python
# Overall assessment
print(f"Risk: {results['overall_risk']}")
print(f"Recommendations: {results['summary']['recommendations']}")

# Individual attacks
for attack in results["attacks"]:
    if attack["attack_type"] == "membership_inference":
        print(f"MIA AUC: {attack['metrics']['auc_roc']:.3f}")
        print(f"MIA Risk: {attack['risk_level']}")

# Linkage risk
for attack in results["attacks"]:
    if "linkage" in attack["attack_type"]:
        violations = attack["metrics"]["k_anonymity_violations"]
        for k, pct in violations.items():
            print(f"k={k}: {pct:.1f}% at risk")
```

CertificationClient

class CertificationClient()

Client for certifying synthetic data quality via remote API.

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

Score Components:

• Fidelity (40%): Statistical similarity to real data
• Privacy (30%): Protection against attacks and memorization
• Utility (20%): Usefulness for downstream tasks
• Completeness (10%): Coverage and diversity

Grade Scale:

• A+ (97-100): Production-ready, exceptional quality
• A (93-96): Production-ready, excellent quality
• A- (90-92): Production-ready, very good quality
• B+ (87-89): Production-ready with minor concerns
• B (83-86): Production-ready, acceptable quality
• B- (80-82): Conditional production use
• C+ (75-79): Development/testing only
• C (70-74): Significant improvements needed
• F (<60): Failure - do not use

Examples:

```python
from synthetic_data_sdk import CertificationClient
import pandas as pd

# Initialize client
cert = CertificationClient(endpoint="http://localhost:8000")

# Certify synthetic data (basic)
real = pd.read_csv("real.csv")
synthetic = pd.read_csv("synthetic.csv")

result = cert.certify(
    real_data=real,
    synthetic_data=synthetic,
    categorical_cols=["city", "gender"],
    target_col="income",
    task_type="regression",
)

print(f"Grade: {result['grade']}")
print(f"Score: {result['overall_score']:.1f}/100")
print(f"Risk: {result['risk_level']}")
print(f"Summary: {result['summary']}")

# Certify with privacy attacks
train_real = pd.read_csv("train_real.csv")
test_real = pd.read_csv("test_real.csv")

result = cert.certify(
    real_data=real,
    synthetic_data=synthetic,
    categorical_cols=["city", "gender"],
    target_col="income",
    task_type="regression",
    include_privacy_attacks=True,
    train_real_data=train_real,
    test_real_data=test_real,
    feature_cols=["age", "income", "education"],
    sensitive_col="medical_condition",
    quasi_identifiers=["zipcode", "age", "gender"],
)

print(f"Grade: {result['grade']}")
print("Recommendations:")
for rec in result["recommendations"]:
    print(f"  - {rec}")
```

__init__

def __init__(endpoint: str = "http://localhost:8000",
             api_key: str | None = None,
             config: ClientConfig | None = None)

Initialize certification client.

Arguments:

• endpoint - Base URL of the synthesis API server (ignored if config is provided)
• api_key - Optional API key for authentication (ignored if config is provided)
• config - Optional ClientConfig object. If not provided, will create one from endpoint and api_key

certify

def certify(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,
            include_privacy_attacks: bool = False,
            train_real_data: pd.DataFrame | str | None = None,
            test_real_data: pd.DataFrame | str | None = None,
            feature_cols: list[str] | None = None,
            sensitive_col: str | None = None,
            quasi_identifiers: list[str] | None = None,
            fidelity_weight: float = 0.40,
            privacy_weight: float = 0.30,
            utility_weight: float = 0.20,
            completeness_weight: float = 0.10) -> dict[str, Any]

Certify synthetic data quality with comprehensive scoring.

Arguments:

• real_data - Real dataset (DataFrame or CSV path)
• synthetic_data - Synthetic dataset (DataFrame or CSV path)
• categorical_cols - List of categorical column names
• target_col - Target column for utility evaluation (TSTR/TRTR)
• task_type - Task type: ‘classification’ or ‘regression’
• include_privacy_attacks - Run privacy attack evaluation (MIA, SARP, Linkage)
• train_real_data - Training split of real data (required if include_privacy_attacks=True)
• test_real_data - Test split of real data (required if include_privacy_attacks=True)
• feature_cols - Feature columns for MIA (privacy attacks)
• sensitive_col - Sensitive column for SARP (privacy attacks)
• quasi_identifiers - Quasi-identifier columns for linkage analysis
• fidelity_weight - Weight for fidelity component (default 40%)
• privacy_weight - Weight for privacy component (default 30%)
• utility_weight - Weight for utility component (default 20%)
• completeness_weight - Weight for completeness component (default 10%)

Returns:

Dict with certification results:

• overall_score: 0-100 certification score
• grade: Letter grade (A+ to F)
• risk_level: ’low’, ‘medium’, ‘high’, or ‘critical’
• breakdown: Detailed score components
• recommendations: List of actionable recommendations
• summary: Natural language summary
• metadata: Certification metadata

Raises:

• SynthesisAPIError - If certification fails

Example:

cert = CertificationClient(endpoint=“http://localhost:8000”)

result = cert.certify( real_data=“data/real.csv”, synthetic_data=“data/synthetic.csv”, categorical_cols=[“city”], target_col=“income”, task_type=“regression”, )

• print(f"Grade - {result[‘grade’]} ({result[‘overall_score’]:.1f}/100)")
• print(f"Risk - {result[‘risk_level’]}")

CausalEvaluator

class CausalEvaluator()

Remote client for causal fidelity evaluation.

Provides methods to evaluate whether synthetic data preserves causal relationships, decision boundaries, and fairness properties from the original real data.

Arguments:

• endpoint str, optional - Base URL of the synthesis API.
• config Optional[ClientConfig] - Advanced client configuration.

Attributes:

• client SynthesisClient - Underlying HTTP client.

Examples:

Treatment effect evaluation:

```python
from synthetic_data_sdk import CausalEvaluator
import pandas as pd

evaluator = CausalEvaluator(endpoint="http://localhost:8000")

# Load datasets
real = pd.read_csv("data/real.csv")
synthetic = pd.read_csv("data/synthetic.csv")

# Evaluate treatment effect stability
results = evaluator.evaluate(
    real_data=real,
    synthetic_data=synthetic,
    treatment_col="received_treatment",
    outcome_col="recovery_time",
    covariates=["age", "severity"],
)

print(f"Overall Preserved: {results['overall_preserved']}")
print(f"Preservation Rate: {results['summary']['preservation_rate']:.1f}%")
```

Decision consistency evaluation:

```python
results = evaluator.evaluate(
    real_data=real,
    synthetic_data=synthetic,
    target_col="purchased",
    feature_cols=["age", "income", "score"],
    task_type="classification",
)

print(
    "Decision Agreement: "
    f"{results['evaluations'][0]['metrics']['decision_agreement']:.2%}"
)
```

Comprehensive evaluation:

```python
results = evaluator.evaluate(
    real_data=real,
    synthetic_data=synthetic,
    treatment_col="treatment",
    outcome_col="outcome",
    target_col="target",
    feature_cols=["age", "income"],
    task_type="classification",
    sensitive_attr="gender",
)

for evaluation in results["evaluations"]:
    print(f"{evaluation['evaluation_type']}: {evaluation['preserved']}")
```

__init__

def __init__(endpoint: str | None = None, config: ClientConfig | None = None)

Initialize causal evaluator client.

Arguments:

• endpoint - API endpoint URL (e.g., ‘http://api.example.com:8000’). Not required if config is provided.
• config - Advanced client configuration (timeout, retries, etc.). If provided, endpoint can be omitted.

evaluate

def evaluate(real_data: pd.DataFrame | str,
             synthetic_data: pd.DataFrame | str,
             treatment_col: str | None = None,
             outcome_col: str | None = None,
             covariates: list[str] | None = None,
             target_col: str | None = None,
             feature_cols: list[str] | None = None,
             task_type: str | None = None,
             sensitive_attr: str | None = None,
             config: dict[str, Any] | None = None) -> dict[str, Any]

Evaluate causal fidelity in synthetic data.

Executes treatment effect stability, decision consistency, and/or fairness shift analyses based on the parameters provided.

Arguments:

• real_data - Real/original data (DataFrame or path/URI to CSV).
• synthetic_data - Synthetic data (DataFrame or path/URI to CSV).
• treatment_col - Column name for treatment indicator (binary 0/1). Required for treatment effect analysis.
• outcome_col - Column name for outcome/response variable. Required for treatment effect analysis.
• covariates - List of covariate columns for treatment effect adjustment. Optional for treatment effect analysis.
• target_col - Target/label column name. Required for decision consistency and fairness analysis.
• feature_cols - List of feature column names for modeling. Required for decision consistency analysis.
• task_type - Machine learning task type (‘classification’ or ‘regression’). Required for decision consistency analysis.
• sensitive_attr - Sensitive attribute column (e.g., ‘gender’, ‘race’). Required for fairness shift analysis.
• config - Advanced configuration options:
  • ate_threshold (float): Threshold for treatment effect preservation
  • fairness_threshold (float): Threshold for fairness shift
  • test_size (float): Train/test split ratio
  • random_state (int): Random seed for reproducibility

Returns:

• dict - Causal evaluation results containing:
  • request_id (str): Request identifier
  • status (str): ‘success’ or ’error’
  • overall_preserved (bool): Whether all evaluations passed
  • evaluations (List[dict]): Results for each evaluation type
  • summary (dict): High-level summary with:
  • total_evaluations: Number of evaluations executed
  • preserved_evaluations: Number that passed
  • preservation_rate: Percentage preserved
  • recommendations: List of recommended actions
  • metadata (dict): Execution details (time, dataset sizes, config)

Raises:

• SynthesisAPIError - If evaluation fails.
• ValidationError - If data schemas don’t match or inputs are invalid.
• ConnectionError - If API is unreachable.

Notes:

Evaluation Types:

1. Treatment Effect Stability:

• Compares Average Treatment Effect (ATE) between real and synthetic
• Required: treatment_col, outcome_col
• Optional: covariates for adjustment
• Reports: ate_preserved, ate_relative_error

2. Decision Consistency:

• Compares decision boundaries of models trained on real vs synthetic
• Required: target_col, feature_cols, task_type
• Reports: decision_agreement, consistency_score

3. Fairness Shift:

• Measures changes in demographic parity
• Required: sensitive_attr, target_col
• Reports: fairness_preserved, fairness_shift

At least one evaluation type must be specified by providing the required parameters for that evaluation.

Examples:

Treatment effect only:

        ```python
        evaluator = CausalEvaluator(endpoint="http://localhost:8000")

        results = evaluator.evaluate(
            real_data=real_df,
            synthetic_data=synth_df,
            treatment_col="treatment",
            outcome_col="outcome",
            covariates=["age", "income"],
        )

        te_result = results["evaluations"][0]
        print(f"ATE Preserved: {te_result['preserved']}")
        print(f"ATE Real: {te_result['metrics']['ate_real']:.3f}")
        print(f"ATE Synth: {te_result['metrics']['ate_synth']:.3f}")
        ```

Decision consistency only:

        ```python
        results = evaluator.evaluate(
            real_data="s3://data/real.csv",
            synthetic_data="s3://data/synthetic.csv",
            target_col="purchased",
            feature_cols=["age", "income", "score"],
            task_type="classification",
        )

        dc_result = results["evaluations"][0]
        print(f"Decision Agreement: {dc_result['metrics']['decision_agreement']:.2%}")
        ```

Fairness shift only:

        ```python
        results = evaluator.evaluate(
            real_data=real_df,
            synthetic_data=synth_df,
            sensitive_attr="gender",
            target_col="hired",
        )

        fs_result = results["evaluations"][0]
        print(f"Fairness Preserved: {fs_result['preserved']}")
        ```

Comprehensive evaluation (all three):

        ```python
        results = evaluator.evaluate(
            real_data=real_df,
            synthetic_data=synth_df,
            treatment_col="treatment",
            outcome_col="outcome",
            covariates=["age", "income"],
            target_col="target",
            feature_cols=["age", "income", "score"],
            task_type="classification",
            sensitive_attr="gender",
            config={"ate_threshold": 0.15, "fairness_threshold": 0.1, "random_state": 42},
        )

        print(f"Total Evaluations: {results['summary']['total_evaluations']}")
        print(f"Preservation Rate: {results['summary']['preservation_rate']:.1f}%")

        for evaluation in results["evaluations"]:
            print(f"

{evaluation[’evaluation_type’]}:") print(f" Preserved: {evaluation[‘preserved’]}") print(f" {evaluation[‘interpretation’]}") ```

Path/URI inputs:

        ```python
        results = evaluator.evaluate(
            real_data="gs://bucket/real.parquet",
            synthetic_data="gs://bucket/synthetic.parquet",
            treatment_col="treatment",
            outcome_col="outcome",
        )
        ```

config

Configuration for the Synthetic Data SDK

Manages client-side settings for API communication, including endpoint URLs, timeouts, retry policies, and authentication.

Supported Data URI Formats

Cloud data can be passed to any SDK method that accepts a str path. The server resolves URIs using pty-ai-artifact-storage-lib. Credentials are embedded directly in the URI, there is no separate storage_config field.

AWS S3

s3://bucket/path/to/file.csv # IAM / instance role s3://ACCESS_KEY:SECRET_KEY@REGION/bucket/prefix/ # explicit credentials s3://bucket/path?region=us-east-1&connect_timeout=5&read_timeout=600

Google Cloud Storage

gs://bucket/path/to/file.csv # Application Default Creds gs://project@/bucket/prefix/?credentials=/path/to/sa.json

Azure Blob Storage

azure://container/blob.csv # DefaultAzureCredential Connection string and account URL are server-side settings only

MinIO (S3-compatible)

minio://ACCESS_KEY:SECRET_KEY@HOST:PORT/bucket/prefix/ http://bucket.HOST:PORT/prefix # virtual-hosted style

Local filesystem (SDK reads client-side and sends inline)

• file:///abs/path/to/file.csv
• /abs/path/to/file.csv
• ./relative/path.csv The SDK detects these, reads the file locally, and sends data as inline base64. The server never receives a local path.

Multi-table (dict of URIs or local paths)

Pass a dict[str, str] mapping table names to any of the URI formats above when using multi-table synthesizers. All tables must use the same input kind: either all local paths/file:// URIs (SDK reads and sends inline) or all cloud URIs (passed to the server). Mixing the two raises ValueError.

Timeout query parameters (all cloud backends)

Examples:

```python
from synthetic_data_sdk import ClientConfig, RemoteVineCopula

# Custom configuration
config = ClientConfig(endpoint="http://api.example.com:8000", timeout=60, max_retries=3)

synth = RemoteVineCopula(config=config)

# Pass S3 URI with embedded credentials
synth.fit("s3://AKID:SECRET@us-east-1/my-bucket/train.csv")

# Pass GCS URI (uses Application Default Credentials)
synth.fit("gs://my-bucket/data/train.csv")

# Multi-table with MinIO
from synthetic_data_sdk import RemoteMultiTableVineCopula
mt = RemoteMultiTableVineCopula(
    endpoint="http://api.example.com:8000",
    relationships=[("customers", "id", "orders", "customer_id")],
)
mt.fit(
    {
        "customers": "minio://key:secret@minio.example.com:9000/bucket/customers.csv",
        "orders": "minio://key:secret@minio.example.com:9000/bucket/orders.csv",
    }
)
```

ClientConfig

@dataclass
class ClientConfig()

Configuration for SDK clients.

Attributes:

• endpoint str - Base URL of the synthesis API (e.g., ‘http://localhost:8000’).
• timeout int - Request timeout in seconds. Default: 300 (5 minutes).
• max_retries int - Maximum number of retry attempts for failed requests. Default: 3.
• verify_ssl bool - Whether to verify SSL certificates. Default: True.
• api_key Optional[str] - API key for authentication (if required). Default: None.
• headers dict - Additional HTTP headers to include in all requests.

Examples:

Production configuration:

```python
config = ClientConfig(
    endpoint="https://api.example.com",
    timeout=120,
    max_retries=5,
    verify_ssl=True,
    api_key="your-api-key-here",
)
```

Development configuration:

```python
config = ClientConfig(
    endpoint="http://localhost:8000",
    timeout=60,
    verify_ssl=False,  # For self-signed certs
)
```

Custom headers:

```python
config = ClientConfig(
    endpoint="http://api.example.com:8000",
    headers={"X-Organization-ID": "org-123", "X-Environment": "staging"},
)
```

__post_init__

def __post_init__()

Validate and normalize configuration.

from_env

@classmethod
def from_env(cls) -> "ClientConfig"

Create configuration from environment variables.

Reads:

• SYNTHESIS_ENDPOINT: API endpoint URL (may include path prefix)
• SYNTHESIS_API_KEY: API key for authentication
• SYNTHESIS_TIMEOUT: Request timeout (seconds)
• SYNTHESIS_VERIFY_SSL: Whether to verify SSL (true/false)

Returns:

• ClientConfig - Configuration instance.

Examples:

```python
import os
os.environ["SYNTHESIS_ENDPOINT"] = "http://api.example.com:8000"
os.environ["SYNTHESIS_API_KEY"] = "sk-..."
config = ClientConfig.from_env()
print(config.endpoint)
http://api.example.com:8000
```

constants

Constants for Synthetic Data SDK.

This module provides standardized constants for field names used in API requests, ensuring consistency and type safety across the SDK.

DataFieldNames

class DataFieldNames()

Standard field names for data parameters in API requests.

All data fields map to DataInput objects on the server side, a single field that holds exactly one of: inline (base64 CSV), uri (cloud/file URI), inline_tables (multi-table base64 dict), or uri_tables (multi-table URI dict).

Examples:

```python
# Using constants for clarity
payload = {DataFieldNames.TRAINING: {"inline": base64_data}}

# Cloud URI
payload = {DataFieldNames.TRAINING: {"uri": "s3://bucket/train.csv"}}
```

ModelNames

class ModelNames()

Standard model names supported by the API.

Examples:

```python
client = RemoteVineCopula(endpoint="http://localhost:8000")
assert client.model_name == ModelNames.VINE
```

ActionNames

class ActionNames()

Standard action names for synthesis operations.

Examples:

```python
payload = {"action": ActionNames.FIT_TRANSFORM}
```

exceptions

Exceptions for the Synthetic Data SDK

Custom exception hierarchy for distinguishing between different types of API errors, enabling granular error handling in client applications.

Exception Hierarchy: SynthesisAPIError (base) ├── ConnectionError (network failures) ├── ValidationError (4xx client errors) └── ServerError (5xx server errors)

Examples:

```python
from synthetic_data_sdk import RemoteVineCopula, ValidationError, ServerError
try:
    synth = RemoteVineCopula(endpoint="http://localhost:8000")
    synth.fit(invalid_data)
except ValidationError as e:
    print(f"Invalid request: {e}")
    print(f"Fix your data and retry")
except ServerError as e:
    print(f"Server error: {e}")
    print(f"Contact support with request_id: {e.request_id}")
except ConnectionError as e:
    print(f"Network error: {e}")
    print(f"Check server availability")
```

SynthesisAPIError

class SynthesisAPIError(Exception)

Base exception for all Synthesis API errors.

Attributes:

• message str - Human-readable error description.
• status_code Optional[int] - HTTP status code if available.
• request_id Optional[str] - Request ID for tracking/debugging.
• response_body Optional[dict] - Full API response for detailed inspection.

Examples:

```python
try:
    synth.fit(data)
except SynthesisAPIError as e:
    logger.error(
        f"API error: {e.message}",
        extra={"request_id": e.request_id, "status_code": e.status_code},
    )
```

__init__

def __init__(message: str,
             status_code: int | None = None,
             request_id: str | None = None,
             response_body: dict | None = None)

Initialize API error.

Arguments:

• message - Human-readable error description.
• status_code - HTTP status code (e.g., 400, 500).
• request_id - Unique request identifier from API response.
• response_body - Full JSON response from API for debugging.

__str__

def __str__() -> str

Format error message with optional metadata.

ConnectionError

class ConnectionError(SynthesisAPIError)

Network or connection-related errors.

Raised when:

• Server is unreachable
• Network timeout
• DNS resolution failure
• SSL/TLS errors

Examples:

```python
try:
    synth = RemoteVineCopula(endpoint="http://nonexistent:8000")
    synth.fit(df)
except ConnectionError:
    print("Server unreachable - check endpoint URL and network")
```

ValidationError

class ValidationError(SynthesisAPIError)

Request validation errors (HTTP 4xx).

Raised when:

• Missing required fields
• Invalid parameter values
• Malformed request body
• Unknown model name

Examples:

```python
try:
    synth = RemoteVineCopula(endpoint="http://localhost:8000")
    synth.transform(n=-10)  # Invalid n_samples
except ValidationError as e:
    print(f"Invalid request: {e}")
    # Fix the issue and retry
```

ServerError

class ServerError(SynthesisAPIError)

Server-side errors (HTTP 5xx).

Raised when:

• Internal server error
• Service temporarily unavailable
• Synthesis operation failed

Examples:

```python
try:
    synth = RemoteVineCopula(endpoint="http://localhost:8000")
    synth.fit(df)
except ServerError as e:
    print(f"Server error - contact support")
    print(f"Request ID: {e.request_id}")
    # Implement retry logic with exponential backoff
```

TierRestrictionError

class TierRestrictionError(SynthesisAPIError)

Feature not available in the server’s active tier (HTTP 403).

Raised when the server returns 403 because the requested feature requires a higher product tier than the one currently deployed.

Attributes:

• feature - Gated feature name (e.g. "tabdiff").
• component - Component category (e.g. "models").
• current_tier - Tier running on the server.
• required_tier - Lowest tier that unlocks the feature.

Examples:

```python
try:
    synth = RemoteTabDiff(endpoint="http://localhost:8000")
    synth.fit(df)
except TierRestrictionError as e:
    print(f"Upgrade required: current={e.current_tier}, need={e.required_tier}")
```

3.6 - Uninstalling Synthetic Data

1. Open a command prompt.

2. Navigate to the cloned repository location.

3. Navigate to the synthetic-data directory.

   cd synthetic-data
   

4. Run the following command to remove the containers and images.

   docker compose down --rmi all
   

4 - Anonymization

Anonymization is a powerful feature that helps organizations protect sensitive data by anonymizing it while maintaining its utility for analysis and development. By leveraging AI, Anonymization enables organizations to transform sensitive data into anonymized data that preserves its analytical value while ensuring privacy and compliance.

4.1 - Anonymization Architecture

Protegrity Anonymization allows processing of the datasets through generalization, to ensure the risk of re-identification is within tolerable thresholds. The anonymization process will have an impact on data utility, but Protegrity Anonymization optimizes this fundamental privacy-utility trade-off to ensure maximum data quality within the privacy goals.

Protegrity Anonymization leverages Kubernetes for data anonymization at scale and it provides instructions and support for deployment and usage on AWS EKS and Microsoft Azure AKS.

An overview of the communication is shown in the following figure.

Architecture

Protegrity Anonymization uses several pods on Kubernetes. The Protegrity Anonymization Web Server processes requests and stores the data securely in an internal Database Server. The Protegrity Anonymization request is received by the Nginx-Ingress component. Ingress forwards the request to the Anon-App. The Anon-App processes the request and submits the tasks to the cluster. The scheduler schedules tasks on the workers. The Anon-app stores the metadata about the job in the Anon-DB container. Next, the workers read, write, and process the data that is stored in the Anon-Storage, the request stream, or the Cloud storage. The Anon-Storage uses S3 bucket for storing data. The communication between the scheduler and the workers is handled by the scheduler. The workers run on random ports.

The user accesses Protegrity Anonymization using HTTPS over port 443. The user requests are directed to an Ingress Controller, and the controller in turn communicates with the required pods using the following ports:

• 8090: Ingress controller and the Protegrity Anonymization API Web Service
• 8786: Ingress controller
• 8100: Ingress controller and S3 bucket

Protegrity Anonymization leverages Kubernetes for data anonymization at scale and it provides instructions and support for deployment and usage on AWS EKS and Microsoft Azure AKS.

Components

Protegrity Anonymization is composed of the following main components:

• Protegrity Anonymization REST Server: This core component exposes a REST interface through which clients can interact with the Protegrity Anonymization service. It uses an in-memory task queue and stores anonymized datasets and respective metadata on persistent storage. Protegrity Anonymization tasks are submitted to a queue and are handled in first-in first out fashion.

Note: Only one anonymization task is executed at a time in Protegrity Anonymization.

• REST Client: The client connects to the Protegrity Anonymization REST Server using an API tool, such as Postman, to create, send, and receive the Protegrity Anonymization request. It also provides a Swagger interface detailing the APIs available. The Swagger interface can also be used as a REST client for raising API requests.
• Python SDK: It is the Python programmatic interface used to communicate with the REST server.
• Anon-Storage*: It is used to read data from and write data to the storage. It uses the S3 bucket framework to perform file operations.
• Anon-DB: It is a PostgreSQL database that is used to store metadata related to Protegrity Anonymization jobs.

4.2 - Prerequisites for Anonymization

Ensure that the following prerequisites are met before running these examples for Anonymization:

• Docker CLI, Docker Compose, and Python are installed. For more information, refer to AI Developer Edition, Pre-requisites Guide.
• For shell samples: Bash version greater than or equal to 5.1.8 and curl version greater than or equal to 7.76.1.
• For notebook samples: JupyterLab version greater than or equal to 4.5.6.

4.3 - Setting up Anonymization

Use the containers to set up the Anonymization feature required for identifying sensitive data.

1. Open a command prompt.

2. Navigate to the cloned repository location for protegrity-ai-developer-edition.

3. Run the following command to download and start the containers. The dependent containers are large in size. Based on the network connection, the containers might take time to download and deploy.

   cd anonymization
   docker compose up -d
   

   Based on your configuration use the docker-compose up -d command.

   Note: By default images are obtained from ghcr.io. To obtain images from public.ecr.aws, navigate to the anonymization directory and copy the .env.example file to .env. Open the .env file and uncomment the REGISTRY=public.ecr.aws/protegrity-ai-developer-edition line in the file. Save the file and run the docker compose up -d command to download and start the containers.

4. Verify that the containers started successfully.

   docker compose logs
   

5. Set up the Jupyter notebook for working with the notebooks provided from the cloned repository location for protegrity-ai-developer-edition.

   pip install -r shared/requirements.txt
   

6. Install the Anonymization SDK package.

   pip install protegrity-anonymization-sdk
   

4.4 - Running the Anonymization samples

The example scripts under the anonymization/ folder demonstrate the usage of Anonymization APIs. For more information about the Anonymization APIs, refer to the section Anonymization APIs.

Note: A dedicated anonymization/docker-compose.yml is provided to start the Anonymization services.

1. Open a command prompt.

2. Navigate to the directory where AI Developer Edition is cloned.

3. Run the following command to start Jupyter Lab.

   jupyter lab
   

4. Copy the URL displayed and navigate to the site from a web browser. Ensure that localhost is replaced with the IP address of the system where the AI Developer Edition is set up.

5. In the left pane of the Jupyter Lab, navigate to anonymization/samples/python/sample-app-anonymization.

6. Open the anonymization.ipynb file.

7. Click the Play icon and follow the prompts in the Jupyter Lab.

4.5 - Using the Anonymization APIs

client

Anonymization SDK Client.

Provides synchronous (AnonymizationClient) and asynchronous (AsyncAnonymizationClient) Python clients for the Anonymization anonymization API.

Public models, enums, and exceptions are re-exported here for backward compatibility so that from anonymization_sdk.client import X continues to work.

AnonymizationClient

class AnonymizationClient()

Synchronous client for the Anonymization anonymization API.

Arguments:

• base_url - Base URL of the Anonymization API (default: http://localhost:8000)
• timeout - Request timeout in seconds (default: 30)
• headers - Additional headers to include in requests

__init__

def __init__(base_url: str = DEFAULT_BASE_URL,
             timeout: float = DEFAULT_TIMEOUT,
             headers: dict[str, str] | None = None,
             mlops_config: dict[str, Any] | None = None)

Initialize the Anonymization client.

Arguments:

• base_url - Base URL of the Anonymization API
• timeout - Request timeout in seconds
• headers - Additional HTTP headers to include in requests
• mlops_config - Default MLOps tracking configuration applied to every anonymize, auto_anonymize, apply_anon, and calculate_risk call. Can be overridden per-call by passing mlops_config explicitly.

close

def close() -> None

Close the HTTP client.

is_healthy

def is_healthy() -> bool

Check if the API is healthy and responding.

Returns:

True if the API is reachable and healthy, False otherwise.

get_health

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

Get detailed health information from the API.

Returns:

Dictionary with health status, version, and component states.

Raises:

• APIError - If the API returns an error status.

detect_qi

def detect_qi(data: DataInputType,
              *,
              mode: DetectionMode | str = DetectionMode.AUTO,
              sampling_method: SamplingMethod | str = SamplingMethod.FAST,
              cumulative_importance_threshold: float = 0.8,
              max_quasi_identifiers: int = 10,
              uniqueness_threshold: float = 0.95,
              known_identifiers: list[str] | None = None,
              known_sensitive: list[str] | None = None,
              ignore_columns: list[str] | None = None) -> DetectionResult

Detect quasi-identifiers in a dataset.

Arguments:

• data - Inline records (List[Dict]), local file path / file:// URI, or cloud URI (s3://, gs://, azure://, etc.). Local paths are read and encoded automatically.
• mode - Detection algorithm (“auto”, “ml”, “heuristic”).
• sampling_method - Sampling strategy (“fast”, “full”, “adaptive”).
• cumulative_importance_threshold - Stop adding QIs at this cumulative importance threshold (0.0–1.0, default 0.8).
• max_quasi_identifiers - Maximum QIs to return (default 10).
• uniqueness_threshold - Columns above this uniqueness ratio are flagged as direct identifiers (0.0–1.0, default 0.95).
• known_identifiers - Columns you know are direct identifiers.
• known_sensitive - Columns you know are sensitive.
• ignore_columns - Columns to skip during detection.

Returns:

DetectionResult with quasi_identifiers, direct_identifiers, sensitive_attributes, attributes, and optional model_metrics.

Raises:

• APIError - If the API returns an error.
• ValidationError - If the request is invalid.

generate_config

def generate_config(data: DataInputType,
                    *,
                    privacy_model: PrivacyModel
                    | str = PrivacyModel.K_ANONYMITY,
                    k: int = 5,
                    l: int | None = None,
                    t: float | None = None,
                    mode: DetectionMode | str = DetectionMode.AUTO,
                    **kwargs) -> AutoConfigResult

Generate anonymization configuration automatically.

Arguments:

• data - Inline records (List[Dict]), local file path, or cloud URI.
• privacy_model - Privacy model (“k-anonymity”, “l-diversity”, “t-closeness”).
• k - K value (default 5).
• l - L value for l-diversity.
• t - T threshold for t-closeness.
• mode - Detection algorithm (“auto”, “ml”, “heuristic”).
• **kwargs - max_suppression, diversity_type, distance_metric, sampling_method.

Returns:

AutoConfigResult with detection results and a ready-to-use anonymize_request configuration dict.

calculate_risk

def calculate_risk(data: DataInputType,
                   quasi_identifiers: list[str] | None = None,
                   *,
                   risk_threshold: float = 0.2,
                   suppress_value: str = "*",
                   include_prosecutor: bool = True,
                   include_journalist: bool = True,
                   include_marketer: bool = True,
                   mlops_config: dict[str, Any] | None = None) -> RiskResult

Calculate re-identification risk metrics.

Arguments:

• data - Inline records (List[Dict]), local file path, or cloud URI.
• quasi_identifiers - QI column names to consider for risk.
• risk_threshold - Records above this threshold are “at risk” (default 0.2).
• suppress_value - Value marking suppressed records (default “*”).
• include_prosecutor - Calculate prosecutor risk (default True).
• include_journalist - Calculate journalist risk (default True).
• include_marketer - Calculate marketer risk (default True).
• mlops_config - MLOps config override.

Returns:

RiskResult with prosecutor, journalist, marketer risk models and k_anonymity, highest_risk_level, equivalence class statistics.

anonymize

def anonymize(data: DataInputType,
              *,
              privacy_model: PrivacyModel | str = PrivacyModel.K_ANONYMITY,
              k: int = 5,
              l: int | None = None,
              t: float | None = None,
              attributes: list[dict[str, Any]] | None = None,
              max_suppression: float = 0.0,
              output_uri: str | None = None,
              output_format: str = "csv",
              mlops_config: dict[str, Any] | None = None,
              **kwargs) -> AnonymizeResult

Anonymize data synchronously using the specified privacy model.

Arguments:

• data - Inline records (List[Dict]), local file path / file:// URI, or cloud URI (s3://, gs://, azure://, etc.). Local paths are read and encoded automatically.
• privacy_model - Privacy model (“k-anonymity”, “l-diversity”, “t-closeness”).
• k - K value for k-anonymity (default 5).
• l - L value for l-diversity.
• t - T threshold for t-closeness (0.0–1.0).
• attributes - Attribute configurations - list of dicts with name, type (“quasi_identifier”, “sensitive”, “identifier”, “insensitive”), and optional hierarchy.
• max_suppression - Maximum fraction of records to suppress (0.0–1.0).
• output_uri - Cloud URI to write results to instead of returning inline (e.g. "s3://bucket/output.csv"). When set, result_path is populated in the response instead of data.
• output_format - Format for cloud output (“csv”, “parquet”, “json”).
• mlops_config - MLOps tracking configuration.
• **kwargs - diversity_type, distance_metric, use_lattice_search, etc.

Returns:

AnonymizeResult with data (inline), or result_path (cloud output), row_count, suppressed_count, and metrics.

submit_job

def submit_job(data: DataInputType,
               *,
               privacy_model: PrivacyModel | str = PrivacyModel.K_ANONYMITY,
               k: int = 5,
               l: int | None = None,
               t: float | None = None,
               attributes: list[dict[str, Any]] | None = None,
               max_suppression: float = 0.0,
               **kwargs) -> JobResponse

Submit an anonymization job for asynchronous processing.

Arguments:

• data - Inline records (List[Dict]), local file path, or cloud URI.
• privacy_model - Privacy model (“k-anonymity”, “l-diversity”, “t-closeness”).
• k - K value for k-anonymity (default 5).
• l - L value for l-diversity.
• t - T threshold for t-closeness.
• attributes - Attribute configurations.
• max_suppression - Maximum suppression rate (0.0–1.0).
• **kwargs - Additional parameters (diversity_type, distance_metric).

Returns:

JobResponse with job_id, status, message, and created_at timestamp.

get_job_status

def get_job_status(job_id: str) -> JobStatusResponse

Get the status of an anonymization job.

Poll this method to track progress of jobs submitted via submit_job(). The response includes progress percentage, status, timestamps, and any error messages if the job failed.

Arguments:

• job_id - Unique job identifier returned by submit_job()

Returns:

JobStatusResponse with:

• job_id: Job identifier
• status: Current status (pending, running, completed, failed, cancelled)
• progress: Progress percentage (0-100)
• message: Status message
• created_at: Job creation timestamp
• updated_at: Last update timestamp
• completed_at: Completion timestamp (if completed)
• result_path: Path to result file (if completed)
• error: Error message (if failed)

Raises:

• APIError - If job not found or API call fails

cancel_job

def cancel_job(job_id: str) -> None

Cancel a pending or running anonymization job.

Cancels a job that was submitted via submit_job(). Only jobs with status PENDING or RUNNING can be cancelled. Completed, failed, or already cancelled jobs cannot be cancelled.

Arguments:

• job_id - Unique job identifier returned by submit_job()

Raises:

• APIError - If job not found or cannot be cancelled

apply_anon

def apply_anon(job_id: str,
               data: DataInputType,
               *,
               mlops_config: dict[str, Any] | None = None) -> "ApplyResult"

Apply a saved anonymization solution to new data.

Re-uses the generalization levels computed during a prior anonymize() call identified by job_id. The lattice is not recomputed.

Arguments:

• job_id - Solution identifier returned in AnonymizeResult.job_id.
• data - Inline records (List[Dict]), local file path, or cloud URI.
• mlops_config - Optional per-request MLOps tracking configuration.

Returns:

ApplyResult with anonymized data, row/suppressed counts, source_job_id, and privacy_model.

list_models

def list_models(*,
                model_type: str | None = None,
                all_metrics: bool = False) -> dict[str, Any]

List tracked anonymization models in Production.

Arguments:

• model_type - Optional filter by privacy model type (e.g. “k-anonymity”).
• all_metrics - If True, return all metrics instead of only the promotion metric.

Returns:

Raw response dict with ‘models’ list and ‘count’.

list_jobs

def list_jobs(*,
              status: JobStatus | str | None = None,
              limit: int = 100,
              offset: int = 0) -> "JobListResult"

List / browse all jobs with optional status filter and pagination.

Returns newest jobs first.

Arguments:

• status - Optional filter (e.g. JobStatus.COMPLETED or “failed”)
• limit - Page size (1-1000, default 100)
• offset - Page offset (default 0)

Returns:

JobListResult with jobs list, total count, limit, and offset.

Raises:

• APIError - If the API call fails.

get_job_history

def get_job_history(job_id: str) -> list["JobHistoryEntry"]

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

Each create/update call on the server appends an entry with the status, step, progress, and timestamp at that point.

Arguments:

• job_id - Unique job identifier.

Returns:

List of JobHistoryEntry ordered by sequence.

Raises:

• APIError - If job not found or API call fails.

wait_for_job

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

Poll a job until it reaches a terminal state and return its status.

Arguments:

• job_id - Unique job identifier returned by submit_job().
• poll_interval - Seconds between status polls (default 2s).
• timeout - Maximum seconds to wait (default 600s / 10 min).
• callback - Optional callable (JobStatusResponse) -> None invoked after each poll.

Returns:

JobStatusResponse at the terminal state. The anonymization result (if completed) is available in status.context["result"].

Raises:

• APIError - If the job ends in a failed state.
• TimeoutError - If the job does not complete within timeout.

auto_anonymize

def auto_anonymize(data: DataInputType,
                   *,
                   privacy_model: PrivacyModel
                   | str = PrivacyModel.K_ANONYMITY,
                   k: int = 5,
                   l: int | None = None,
                   t: float | None = None,
                   mode: DetectionMode | str = DetectionMode.AUTO,
                   mlops_config: dict[str, Any] | None = None,
                   **kwargs) -> AutoAnonymizeResult

Automatically detect QIs and anonymize in one step.

Arguments:

• data - Inline records (List[Dict]), local file path, or cloud URI.
• privacy_model - Privacy model (“k-anonymity”, “l-diversity”, “t-closeness”).
• k - K value (default 5).
• l - L value for l-diversity.
• t - T threshold for t-closeness.
• mode - Detection algorithm (“auto”, “ml”, “heuristic”).
• mlops_config - MLOps tracking configuration.
• **kwargs - max_suppression, sampling_method, use_lattice_search, etc.

Returns:

AutoAnonymizeResult with detection results and anonymized data.

validate

def validate(
        data: DataInputType,
        quasi_identifiers: list[str] | None = None,
        *,
        privacy_model: PrivacyModel | str = PrivacyModel.K_ANONYMITY,
        k: int = 5,
        l: int | None = None,
        t: float | None = None,
        sensitive_attributes: list[str] | None = None) -> ValidationResult

Validate that data meets privacy requirements.

Arguments:

• data - Inline records (List[Dict]), local file path, or cloud URI.
• quasi_identifiers - QI column names to check.
• privacy_model - Privacy model to validate against.
• k - Required k for k-anonymity (default 5).
• l - Required l for l-diversity.
• t - Required t for t-closeness.
• sensitive_attributes - Sensitive columns (required for l-diversity/t-closeness).

Returns:

ValidationResult with is_valid, model_type, violations, statistics.

measure

def measure(original_data: DataInputType,
            anonymized_data: DataInputType,
            quasi_identifiers: list[str] | None = None) -> MetricsResult

Measure anonymization quality metrics.

Arguments:

• original_data - Original dataset - inline records, local path, or cloud URI.
• anonymized_data - Anonymized dataset - inline records, local path, or cloud URI.
• quasi_identifiers - QI column names that were generalized.

Returns:

MetricsResult with information_loss and detailed metrics.

create_pattern

def create_pattern(name: str,
                   classification: str,
                   column_patterns: list[str],
                   *,
                   priority: int = 50,
                   value_patterns: list[str] | None = None,
                   min_match_ratio: float = 0.8,
                   description: str | None = None) -> Pattern

Create a custom detection pattern.

Patterns are used during QI detection to automatically classify columns based on their names and values. Custom patterns take precedence over built-in patterns.

Arguments:

• name - Unique name for the pattern (e.g., ‘customer_id’)
• classification - Classification type - one of:
  • “DI”: Direct Identifier (e.g., SSN, email)
  • “QI”: Quasi-Identifier (e.g., age, zipcode)
  • “SI”: Sensitive Identifier (e.g., salary, diagnosis)
  • “NSI”: Non-Sensitive Identifier (safe to publish)
• column_patterns - List of column name patterns to match. Case-insensitive. Use ‘’ as wildcard (e.g., [’_id’, ‘user*’])
• priority - Priority level (1-1000, lower = checked first). Default: 50
• value_patterns - Optional list of regex patterns for value validation
• min_match_ratio - Minimum ratio of values that must match (0-1). Default: 0.8
• description - Optional description of what this pattern detects

Returns:

Pattern object with assigned ID and metadata

Raises:

• APIError - If creation fails (e.g., duplicate name)
• ValidationError - If parameters are invalid

list_patterns

def list_patterns(classification: str | None = None) -> PatternListResult

List all custom detection patterns.

Arguments:

• classification - Optional filter by classification (DI, QI, SI, NSI)

Returns:

PatternListResult containing list of patterns and total count

get_pattern

def get_pattern(pattern_id: str) -> Pattern

Get a specific pattern by ID.

Arguments:

• pattern_id - The pattern ID to retrieve

Returns:

Pattern object

Raises:

• APIError - If pattern not found (404)

update_pattern

def update_pattern(pattern_id: str,
                   *,
                   name: str | None = None,
                   classification: str | None = None,
                   column_patterns: list[str] | None = None,
                   priority: int | None = None,
                   value_patterns: list[str] | None = None,
                   min_match_ratio: float | None = None,
                   description: str | None = None) -> Pattern

Update an existing pattern.

Only provided fields will be updated; others remain unchanged.

Arguments:

• pattern_id - The pattern ID to update
• name - New name for the pattern
• classification - New classification (DI, QI, SI, NSI)
• column_patterns - New column name patterns
• priority - New priority (1-1000)
• value_patterns - New value regex patterns
• min_match_ratio - New minimum match ratio (0-1)
• description - New description

Returns:

Updated Pattern object

Raises:

• APIError - If pattern not found or update fails
• ValidationError - If parameters are invalid

delete_pattern

def delete_pattern(pattern_id: str) -> dict[str, Any]

Delete a pattern by ID.

Arguments:

• pattern_id - The pattern ID to delete

Returns:

Dictionary with confirmation message

Raises:

• APIError - If pattern not found (404)

delete_all_patterns

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

Delete all custom patterns.

WARNING: This removes all customer-defined patterns. Built-in patterns from the YAML config are not affected.

Returns:

Dictionary with count of deleted patterns

reload_patterns

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

Reload patterns from storage file.

Use this to sync after manual file edits.

Returns:

Dictionary with count of reloaded patterns

dp_compute

def dp_compute(data: DataInputType,
               *,
               mechanism: DPMechanismType | str = DPMechanismType.MEAN,
               column: str | None = None,
               columns: list[str] | None = None,
               group_by: str | None = None,
               epsilon: float = 1.0,
               delta: float = 0.0,
               noise_type: DPNoiseType | str = DPNoiseType.LAPLACE,
               bounds: tuple | None = None,
               bins: int | None = None,
               histogram_range: tuple | None = None,
               session_id: str | None = None,
               predicate: str | None = None,
               candidates: list | None = None,
               utility_scores: list[float] | None = None,
               sensitivity: float | None = None,
               epsilon_map: dict[str, float] | None = None,
               min_group_size: int | None = None) -> DPComputeResult

Compute a differentially private statistic on a data column.

Arguments:

• data - Inline records (List[Dict]), local file path, or cloud URI.
• mechanism - DP mechanism (“mean”, “sum”, “variance”, “histogram”, “count”, “exponential”).
• column - Column name for single-column queries.
• columns - Column names for multi-column queries.
• group_by - Categorical column to group by.
• epsilon - Privacy parameter epsilon (>0).
• delta - Privacy parameter delta (>=0, <1).
• noise_type - “laplace” or “gaussian”.
• bounds - (lower, upper) clipping bounds. Required for mean/sum/variance.
• bins - Number of histogram bins (histogram only).
• histogram_range - (min, max) range for histogram bins.
• session_id - Budget session ID for cumulative tracking.
• predicate - Filter expression (e.g., “> 50”, “<= 100”).
• candidates - Candidate outputs (exponential mechanism only).
• utility_scores - Utility scores for candidates (exponential only).
• sensitivity - Utility function sensitivity (exponential only).
• epsilon_map - Per-column or per-group epsilon overrides.
• min_group_size - Minimum rows per group (default 5).

Returns:

DPComputeResult with private_value (single) or results dict (multi/group).

dp_stream_update

def dp_stream_update(session_id: str | None = None,
                     data: DataInputType | None = None,
                     *,
                     column: str | None = None,
                     columns: list[str] | None = None,
                     group_by: str | None = None,
                     mechanism: DPStreamMechanismType | str | None = None,
                     epsilon: float | None = None,
                     delta: float | None = None,
                     noise_type: DPNoiseType | str | None = None,
                     bounds: tuple | None = None,
                     get_result: bool = False,
                     window_size: int | None = None,
                     epsilon_map: dict[str, float] | None = None,
                     min_group_size: int | None = None,
                     budget_session_id: str | None = None) -> DPStreamResult

Feed data into a streaming DP session.

On the first call for a session_id, provide mechanism, epsilon, and bounds. Subsequent calls only need session_id, data, and column.

Arguments:

• session_id - Unique session identifier.
• data - Batch of records. Mutually exclusive with data_path.
• data_path - Cloud/local URI for data batch.
• column - Column name for single-column streaming.
• columns - Column names for multi-column streaming.
• group_by - Categorical column to group by.
• mechanism - Streaming mechanism. Required on first call.
• epsilon - Privacy epsilon. Required on first call.
• delta - Privacy delta.
• noise_type - Noise mechanism.
• bounds - Clipping bounds. Required on first call (except for count).
• get_result - If True, also return the current private result.
• window_size - Window size for sliding/tumbling window mechanisms.
• epsilon_map - Per-column or per-group epsilon overrides.
• min_group_size - Minimum rows per group (default 5).
• budget_session_id - Link to a budget session for automatic deduction.

Returns:

DPStreamResult with session status and optional results.

dp_stream_delete

def dp_stream_delete(session_id: str) -> None

Delete a streaming DP session.

Arguments:

• session_id - Session to delete.

dp_stream_list_sessions

def dp_stream_list_sessions() -> list

List all active streaming DP sessions.

Returns:

List of dicts with session_id, mechanism, column, batches_processed, total_count.

dp_budget_create

def dp_budget_create(session_id: str,
                     epsilon_budget: float,
                     delta_budget: float = 0.0,
                     composition: str = "basic") -> DPBudgetStatus

Create a privacy budget session.

Arguments:

• session_id - Unique session identifier.
• epsilon_budget - Total epsilon budget.
• delta_budget - Total delta budget.
• composition - Composition mode (“basic” or “rdp”). RDP requires delta_budget > 0 and yields tighter privacy accounting.

Returns:

DPBudgetStatus with initial budget state.

dp_budget_status

def dp_budget_status(session_id: str) -> DPBudgetStatus

Get privacy budget status for a session.

Arguments:

• session_id - Session to query.

Returns:

DPBudgetStatus with current spend and remaining budget.

dp_budget_delete

def dp_budget_delete(session_id: str) -> None

Delete a privacy budget session.

Arguments:

• session_id - Session to delete.

dp_advise_composition

def dp_advise_composition(epsilon_budget: float,
                          num_queries: int,
                          delta_budget: float = 0.0,
                          delta_per_query: float = 0.0) -> dict

Get composition advice for planned queries.

Returns optimal per-query epsilon under basic and RDP composition with a recommendation.

Arguments:

• epsilon_budget - Total epsilon budget available.
• num_queries - Number of planned queries.
• delta_budget - Total delta budget (required for RDP comparison).
• delta_per_query - Delta per query for Gaussian noise. 0 = Laplace.

Returns:

Dict with basic/rdp analysis, recommendation, and savings_pct.

audit_list

def audit_list(*,
               operation: str | None = None,
               status: str | None = None,
               limit: int = 50,
               offset: int = 0) -> list[AuditEntry]

List audit log entries.

Arguments:

• operation - Filter by operation (dp_compute, anonymize_sync, …).
• status - Filter by outcome (‘success’ or ’error’).
• limit - Max entries to return (1–500).
• offset - Pagination offset.

Returns:

List of AuditEntry objects.

audit_get

def audit_get(entry_id: str) -> AuditEntry

Get a single audit entry.

Arguments:

• entry_id - Audit entry ID.

Returns:

AuditEntry with full details.

Raises:

• APIError - If entry not found (404).

AsyncAnonymizationClient

class AsyncAnonymizationClient()

Asynchronous client for the Anonymization anonymization API.

Same interface as AnonymizationClient but with async/await support.

__init__

def __init__(base_url: str = DEFAULT_BASE_URL,
             timeout: float = DEFAULT_TIMEOUT,
             headers: dict[str, str] | None = None,
             mlops_config: dict[str, Any] | None = None)

Initialize the async Anonymization client.

Arguments:

• base_url - Base URL of the Anonymization API
• timeout - Request timeout in seconds
• headers - Additional HTTP headers to include in requests
• mlops_config - Default MLOps tracking configuration applied to every anonymize, auto_anonymize, apply_anon, and calculate_risk call. Can be overridden per-call.

close

async def close() -> None

Close the HTTP client.

is_healthy

async def is_healthy() -> bool

Check if the API is healthy and responding.

get_health

async def get_health() -> dict[str, Any]

Get detailed health information.

detect_qi

async def detect_qi(
        data: DataInputType,
        *,
        mode: DetectionMode | str = DetectionMode.AUTO,
        sampling_method: SamplingMethod | str = SamplingMethod.FAST,
        cumulative_importance_threshold: float = 0.8,
        max_quasi_identifiers: int = 10,
        uniqueness_threshold: float = 0.95,
        known_identifiers: list[str] | None = None,
        known_sensitive: list[str] | None = None,
        ignore_columns: list[str] | None = None) -> DetectionResult

Detect quasi-identifiers (async version).

Refer to synchronous detect_qi() for full documentation.

generate_config

async def generate_config(data: DataInputType,
                          *,
                          privacy_model: PrivacyModel
                          | str = PrivacyModel.K_ANONYMITY,
                          k: int = 5,
                          l: int | None = None,
                          t: float | None = None,
                          mode: DetectionMode | str = DetectionMode.AUTO,
                          **kwargs) -> AutoConfigResult

Generate anonymization configuration automatically (async version).

calculate_risk

async def calculate_risk(
        data: DataInputType,
        quasi_identifiers: list[str] | None = None,
        *,
        risk_threshold: float = 0.2,
        suppress_value: str = "*",
        include_prosecutor: bool = True,
        include_journalist: bool = True,
        include_marketer: bool = True,
        mlops_config: dict[str, Any] | None = None) -> RiskResult

Calculate re-identification risk metrics (async version).

anonymize

async def anonymize(data: DataInputType,
                    *,
                    privacy_model: PrivacyModel
                    | str = PrivacyModel.K_ANONYMITY,
                    k: int = 5,
                    l: int | None = None,
                    t: float | None = None,
                    attributes: list[dict[str, Any]] | None = None,
                    max_suppression: float = 0.0,
                    output_uri: str | None = None,
                    output_format: str = "csv",
                    mlops_config: dict[str, Any] | None = None,
                    **kwargs) -> AnonymizeResult

Anonymize data (async version). Refer to synchronous anonymize() for full documentation.

submit_job

async def submit_job(data: DataInputType,
                     *,
                     privacy_model: PrivacyModel
                     | str = PrivacyModel.K_ANONYMITY,
                     k: int = 5,
                     l: int | None = None,
                     t: float | None = None,
                     attributes: list[dict[str, Any]] | None = None,
                     max_suppression: float = 0.0,
                     **kwargs) -> JobResponse

Submit anonymization job (async version).

Refer to synchronous submit_job() for full documentation.

get_job_status

async def get_job_status(job_id: str) -> JobStatusResponse

Get job status (async version).

Refer to synchronous get_job_status() for full documentation.

cancel_job

async def cancel_job(job_id: str) -> None

Cancel job (async version). Refer to synchronous cancel_job() for full documentation.

apply_anon

async def apply_anon(
        job_id: str,
        data: DataInputType,
        *,
        mlops_config: dict[str, Any] | None = None) -> "ApplyResult"

Apply saved anonymization (async). Refer to synchronous apply_anon() for full docs.

list_models

async def list_models(*,
                      model_type: str | None = None,
                      all_metrics: bool = False) -> dict[str, Any]

List tracked anonymization models (async).

Refer to synchronous list_models() for full docs.

list_jobs

async def list_jobs(*,
                    status: JobStatus | str | None = None,
                    limit: int = 100,
                    offset: int = 0) -> "JobListResult"