AI Developer Edition

• 1: Introduction
• 1.1: What is Protegrity AI Developer Edition?
• 1.2: Key Features and Benefits
• 1.3: Overview of the components
• 1.4: Personas
• 1.5: Release Highlights
• 2: Use Cases
• 3: Setting up AI Developer Edition
• 3.1: Prerequisites
• 3.2: Obtaining access to the AI Developer Edition API Service
• 3.3: Obtaining the packages
• 3.4: Verifying the repository structure
• 3.5: Setting up the features
• 3.5.1: Setting up Data Discovery
• 3.5.2: Setting up Semantic Guardrails
• 3.5.3: Setting up Synthetic Data
• 3.5.4: Setting up Anonymization
• 3.5.5: Setting up Data Protection Features
• 3.5.5.1: Building the Python Module
• 3.5.5.2: Building the Java Libraries
• 4: Updating configurations for the sample application
• 5: Protegrity AI Developer Edition Features
• 5.1: Data Discovery
• 5.1.1: Data Discovery Architecture
• 5.1.2: What's New
• 5.1.3: Running the Data Discovery samples
• 5.1.4: Using the Data Discovery APIs
• 5.1.5: Uninstalling Data Discovery
• 5.2: Semantic Guardrails
• 5.2.1: Semantic Guardrails Architecture
• 5.2.2: Running the Semantic Guardrails samples
• 5.2.3: Using the Semantic Guardrails APIs
• 5.2.4: Uninstalling Semantic Guardrails
• 5.3: Synthetic Data
• 5.3.1: Synthetic Data Architecture
• 5.3.2: Running the Synthetic Data samples
• 5.3.3: Using the Synthetic Data APIs
• 5.3.4: Uninstalling Synthetic Data
• 5.4: Anonymization
• 5.4.1: Anonymization Architecture
• 5.4.2: Running the Anonymization samples
• 5.4.3: Using the Anonymization APIs
• 5.4.4: Uninstalling Anonymization
• 5.5: Data Protection
• 5.5.1: Running the Data Protection samples
• 5.5.2: Using the Application Protector Python APIs
• 5.5.3: Using the Application Protector Java APIs
• 5.5.4: Uninstalling Data Protection
• 6: Promoting to AI Team Edition
• 6.1: Preparing for AI Team Edition
• 6.2: Updating Data Discovery
• 6.3: Updating Semantic Guardrails
• 6.4: Updating Python Modules
• 6.5: Updating Java Libraries
• 7: Using AI Developer Edition with Vibe Coding IDEs like Cursor, Claude
• 8: Next Steps with Protegrity AI Developer Edition
• 9: Additional Information
• 9.1: Policy Definition
• 9.2: Supported Classification Entities

1 - Introduction

Protegrity AI Developer Edition is a lightweight, containerized sandbox. It helps developers, data scientists, and architects quickly explore and integrate prototype data protection and discovery workflows. It does not require setting up a complex infrastructure and managing its operational overhead.

It is a self-contained, Docker-based environment designed to enable hands-on experimentation without needing full-scale infrastructure. With modular architecture, built-in sample data, and a developer-first experience, AI Developer Edition is ideal for evaluating Protegrity’s capabilities in a fast, flexible, and frictionless way.

1.1 - What is Protegrity AI Developer Edition?

Protegrity AI Developer Edition is designed to help a developer move quickly from idea to implementation, using familiar tools, sample apps, and open APIs.

It provides a streamlined environment to:

• Discover and redact sensitive data using APIs and sample apps.
• Discover and protect or unprotect sensitive data using APIs and sample apps.
• Experience tokenization using the Protegrity Data Protection Jupyter notebook.
• Perform message and conversation level risk scoring.
• Scan Personally Identifiable Information (PII) for GenAI flows.
• Provide a streamlined environment to test real-world use cases with sample datasets and guided walkthroughs.
• Generate synthetic data.

AI Developer Edition runs entirely on Docker, making it easy to spin up, tear down, and iterate quickly. It helps build a proof of concept, validate integration points, and get familiar with Protegrity’s core concepts. This edition provides the tools to set up the product fast and independently.

Note: This product is not meant for production use, but it is the perfect launchpad for innovation.

1.2 - Key Features and Benefits

AI Developer Edition is purpose-built for fast, frictionless exploration of Protegrity’s core capabilities.

The following features make it ideal for prototyping and integration:

Platform Capabilities

AI Developer Edition provides a comprehensive set of platform capabilities that simplify how developers integrate data protection into their workflows. From containerized deployment to cross-language SDK support, each component is designed for rapid setup, minimal configuration, and seamless iteration.

• Modular, Containerized Architecture: AI Developer Edition runs on Docker, making it easy to test, isolate, and iterate.
• Lightweight: No orchestration overhead. Just deploy the container and use the sample application.
• Python Module: An open-source Python module providing APIs to protect, unprotect, and reprotect sensitive data in Python-based applications. It is available through PyPI for easy installation.
• Java Library: An open-source Java library providing APIs to protect, unprotect, and reprotect sensitive data in Java-based applications. It is distributed using Maven Central for easy integration.
• AI Developer Edition API Service: A service hosted by Protegrity that allows developers to interact with Protegrity’s protection and discovery services through intuitive endpoints. It supports protection and unprotection of sensitive data, enabling rapid prototyping and testing of data protection scenarios without needing full-scale infrastructure. Registration is required for this service. The credentials can be obtained for free.
• Sample Apps and Data: Jumpstart evaluation with ready-to-run sample apps that demonstrate real-world use cases. These use cases include finding sensitive data in unstructured text, finding and redacting, finding and protecting or unprotecting sensitive data, multi-turn conversations, and agent coordination patterns. Adjust behavior through shared/config.json.
• Cross-platform: Works on Linux, macOS, and Windows.

Core Data Protection Services

Protegrity AI Developer Edition offers features that help build AI services. These features range from identifying and protecting sensitive information to generating safe synthetic alternatives.

• Data Discovery: Identifies and classifies sensitive data using built-in and custom classifiers with confidence scoring. Discovers and redacts sensitive data in datasets for use in training GenAI models or sharing with third parties.
• Semantic Guardrails: A security guardrail engine for AI systems. Evaluates risks in GenAI systems such as chatbots, workflows, and agents through advanced semantic analytics and intent classification to detect potentially malicious messages. Provides message and conversation level risk scoring and PII scanning to prevent context poisoning and enforce governance in multi-agent systems.
• Synthetic Data: Analyzes a data set and generates data that mimics the properties of real data, such as data types, ranges, correlations, and distributions, without containing any actual personal information. Enables safe model training and end-to-end agent workflow testing.
• Anonymization: Replaces sensitive data with anonymized values to protect privacy while maintaining the utility of the data for analysis and model training.

Secure Data and AI Pipelines

AI Developer Edition enables end-to-end privacy across the AI lifecycle from data ingestion and model training to inference and output delivery. This ensures that sensitive information is protected at every stage of the pipeline.

• Privacy in conversational AI: Sensitive chatbot inputs are protected before they reach generative AI models.
• Prompt sanitization for LLMs: Automated PII masking reduces risk during large language model prompt engineering and inference.
• Experimentation with Jupyter notebooks: Data scientists can prototype directly in Jupyter notebooks for agile experimentation.
• Output redaction and leakage prevention: Detect and protect sensitive data in model outputs before returning them to end users.
• Privacy-enhanced AI training: Sensitive fields in training datasets are de-identified to support compliant and secure AI development.

Note: This product is continuously improving. The features and capabilities mentioned here are either already available or will be available shortly.

1.3 - Overview of the components

A high-level architecture of AI Developer Edition is provided in the following image.

This release of AI Developer Edition includes sample applications. It showcases the capabilities of Data Discovery, Semantic Guardrails, Synthetic Data, and Anonymization. The applications demonstrate protection and unprotection using simple Python modules or Java libraries. The Data Discovery component is used for identifying sensitive data. After identification, the Python module or Java library redacts, masks, or protects the sensitive information. Protection is done using the AI Developer Edition API Service.

1.4 - Personas

AI Developer Edition targets developers building AI-powered systems in regulated industries. These industries include financial services, healthcare, and public sectors who need to protect sensitive data across AI workflows. The primary persona is the Agentic AI Developer (Agent Builder).

Primary Persona: Agentic AI Developer (Agent Builder)

Agent builders create systems that go beyond chat/RAG. They plan, call tools, take actions, and coordinate with other agents. As agentic AI expands unstructured data use and introduces new pipelines, data protection complexity rises significantly.

Value Proposition: Protegrity AI Developer Edition is the fastest way for agent builders to make LLM-powered systems safe for real data. This is achieved by embedding masking, tokenization, and semantic guardrails directly into agent workflows.

Without Protegrity, an agent builder must build: PII detection models or regex, masking/tokenization logic, audit/compliance layer, and governance rules. AI Developer Edition provides out-of-box APIs, a developer sandbox, and pre-built PII entity detection; accelerating dev-to-production and reducing attack surface, compliance risk, and security approval cycles.

Supporting Personas

The following personas have been considered when developing AI Developer Edition.

1.5 - Release Highlights

General

The following updates are included in AI Developer Edition 1.2.0.

• Added badges to the README for improved visibility and quick access to key resources.
• Restructured directory for better organization of samples and source code. The files for each feature are now available in the feature directory.

Data Discovery

Data Discovery provides the functionality to explore and analyze datasets for sensitive information. For more information about Data Discovery, refer to the feature section.

• Upgraded to Data Discovery version 2.0.
• Added direct-API example scripts for text classification, tabular (CSV) classification, and redaction, both Python and bash variants.
• Introduced an isolated data-discovery/docker-compose.yml for starting only the Data Discovery service.
• Updated API endpoints to the v2 paths: v2/classify/text, v2/classify/csv, and v2/transform/label.

Semantic Guardrails

Semantic Guardrails provides functionality to enforce policies and guidelines within AI interactions. For more information about Semantic Guardrails, refer to the feature section.

• Expanded domain model coverage to three verticals: customer service, financial, and healthcare.
• Extended the pii processor to user messages, in addition to AI messages, enabling PII detection on both sides of a conversation.
• Improved privacy in API responses: PII explanation output now returns character spans instead of the actual detected PII values.
• Changed the OpenAPI documentation endpoint from /swagger to /doc.
• Added a Jupyter notebook sample for seamless evaluation and execution.
• Included richer examples in the sample files for easier understanding.

Synthetic Data

Synthetic Data provides functionality to generate artificial datasets that mimic real data while preserving privacy. For more information about Synthetic Data, refer to the feature section.

• Expanded generative model support. In addition to GANs, Tabular Variational Autoencoders (TVAE) and diffusion-based models are now explicitly supported.
• Added the typeHint parameter to the generate request payload, allowing explicit selection of the model type. For example, "model_type": "tabdiff" for diffusion-based generation.
• When typeHint is not specified, the system automatically determines the most appropriate model during training.
• Refactored the synthetic data generation code for improved performance and maintainability.
• Updated the Jupyter notebook samples for quick evaluation and execution.

Anonymization

Anonymization provides functionality to remove or obscure personally identifiable information (PII) from datasets. For more information about Anonymization, refer to the feature section.

• Added new feature for the AI Developer Edition: Anonymization.
• Included sample code and documentation for using the Anonymization feature effectively.

Data Protection API Wrappers

Data Protection API Wrappers provide functionality to interact with the Data Protection APIs for tokenization, masking, and other privacy-preserving operations. For more information about Data Protection API Wrappers, refer to the feature section.

• Protegrity Data Protection Jupyter notebook to quickly test tokenization.
• Provided support and sample implementations for both Python and Java.
• Ensured Java samples are fully compatible across Linux, macOS, and Windows.
• Delivered Java source code for customization and compilation flexibility.

2 - Use Cases

AI Developer Edition supports privacy-first development across agentic AI workflows and traditional data protection scenarios. The use cases below are organized into two categories:

• Agentic AI Use Cases: For developers building autonomous agent systems. Covers data protection across prompts, memory, tool interactions, logs, and multi-agent communication.
• Data Protection and Security Use Cases: For any developer working with sensitive data. Covers discovery, redaction, tokenization, synthetic data, and anonymization.

Agentic AI Use Cases

As AI systems become more autonomous, protecting sensitive data across every stage of the agent lifecycle is critical. The following use cases illustrate how AI Developer Edition helps secure prompts, memory, tool interactions, logs, and multi-agent communication.

Risks Addressed per Agent Layer

Each layer of the agent stack introduces distinct data exposure risks. The following table summarizes the key risks and how AI Developer Edition mitigates them.

Data Protection and Security Use Cases

These use cases apply to any development workflow involving sensitive data, whether or not agents are involved. They cover core Protegrity capabilities such as data discovery, redaction, tokenization, anonymization, and synthetic data generation.

3 - Setting up AI Developer Edition

Complete the prerequisites, register for access to AI Developer Edition API Service, set up, verify, and run the required files for using Protegrity AI Developer Edition.

3.1 - Prerequisites

General requirements

The system requirements for the AI Developer Edition are provided here.

Hardware requirements

For the local docker deployment mode, a machine with the following specifications enables the user to experiment with the main features:

• RAM: 16 GB
• CPU: 8 core
• GPU: 4 GB VRAM, for Synthetic Data only
• Hard Disk: 50GB available

Software requirements

• Linux
• Windows
• macOS

3.2 - Obtaining access to the AI Developer Edition API Service

The tokenization and encryption features are processed by the AI Developer Edition API Service. Free registration is required to access this service.

Note: Registration is only required for running the APIs to protect, unprotect, and reprotect data. The find and redact that uses Data Discovery, Semantic Guardrails, and Synthetic Data features can be used without registration. Skip this section if find and protect that uses the tokenization and encryption feature is not required.

Registering for access

Sign up for access to the AI Developer Edition API Service. This is required for obtaining access to use the APIs.

1. Open a web browser.
2. Navigate to https://www.protegrity.com/developers/dev-edition-api.
3. Specify the following details:
   • First Name
   • Last Name
   • Work Email
   • Job Title
   • Company Name
   • Country
4. Click the Terms & Conditions link and read the terms and conditions.
5. Select the check box to accept the terms and conditions.
6. Click Get Started.

The request is analyzed. After the request is approved, a password and API key to access the AI Developer Edition API Service are sent to the Work Email specified. If the account already exists, then the details are re-sent to the email address. The email takes a minute or two to arrive. If the email does not arrive in the specified email’s inbox, check the spam or junk folder first, before retrying.

Before running requests, verify that the AI Developer Edition Service is running. The service availability can be monitored on the status page, refer to AI Developer Edition System Status.

Note: Use the online notebook with the credentials to test tokenization, refer to Protegrity Data Protection Jupyter notebook.

Specifying the authentication information

Set the credentials from your registration email as environment variables to access the AI Developer Edition API Service.

Note: It is recommended to add the details to the environment variables to avoid specifying the information every time the environment is initialized.

1. Open a command prompt.
2. Initialize a Python virtual environment.
3. Add the email address of the user.

• Linux
• Windows PowerShell
• macOS

export DEV_EDITION_EMAIL='<Email_used_for_registration>'

$env:DEV_EDITION_EMAIL = '<Email_used_for_registration>' 

export DEV_EDITION_EMAIL='<Email_used_for_registration>'

4. Specify the password provided in the registration email.

• Linux
• Windows PowerShell
• macOS

export DEV_EDITION_PASSWORD='<Password_provided_in_email>'

$env:DEV_EDITION_PASSWORD = '<Password_provided_in_email>' 

export DEV_EDITION_PASSWORD='<Password_provided_in_email>'

5. Specify the API key for accessing the AI Developer Edition API Service.

• Linux
• Windows PowerShell
• macOS

export DEV_EDITION_API_KEY='<API_key_provided_in_email>'

$env:DEV_EDITION_API_KEY = '<API_key_provided_in_email>'  

export DEV_EDITION_API_KEY='<API_key_provided_in_email>'

6. Verify that the variables are set.

• Linux
• Windows PowerShell
• macOS

test -n "$DEV_EDITION_EMAIL" && echo "EMAIL $DEV_EDITION_EMAIL set" || echo "EMAIL missing"
test -n "$DEV_EDITION_PASSWORD" && echo "PASSWORD $DEV_EDITION_PASSWORD set" || echo "PASSWORD missing"
test -n "$DEV_EDITION_API_KEY" && echo "API KEY $DEV_EDITION_API_KEY set" || echo "API KEY missing"

if ($env:DEV_EDITION_EMAIL) { Write-Output "EMAIL $env:DEV_EDITION_EMAIL set"} else { Write-Output "EMAIL missing"} 
if ($env:DEV_EDITION_PASSWORD) { Write-Output "PASSWORD $env:DEV_EDITION_PASSWORD set" } else { Write-Output "PASSWORD missing" } 
if ($env:DEV_EDITION_API_KEY) { Write-Output "API KEY $env:DEV_EDITION_API_KEY set" } else { Write-Output "API KEY missing" } 

test -n "$DEV_EDITION_EMAIL" && echo "EMAIL $DEV_EDITION_EMAIL set" || echo "EMAIL missing"
test -n "$DEV_EDITION_PASSWORD" && echo "PASSWORD $DEV_EDITION_PASSWORD set" || echo "PASSWORD missing"
test -n "$DEV_EDITION_API_KEY" && echo "API KEY $DEV_EDITION_API_KEY set" || echo "API KEY missing"

AI Developer Edition API Service usage guidelines

To ensure fair use of the API service, a rate limit is enforced on API requests to the AI Developer Edition API Service.

These limits are:

• Request rate: 50 per second
• Burst: up to 100
• Quota: 10,000 requests per user per day
• Maximum payload size: 1MB

3.3 - Obtaining the packages

The following packages are available for download:

• protegrity-ai-developer-edition: Contains Docker Compose files, sample applications, and configuration templates.
• protegrity-ai-developer-python: Contains the source files for customizing and using the Python module.
• protegrity-ai-developer-java: Contains the source files for customizing and using the Java library.

Cloning the repositories

Sync the repositories to download the packages onto your local system. You can use the git clone command to clone the repositories.

• Fresh setup
• Upgrade

Setting up feature containers

After downloading the common packages, set up the containers for the features you want to use. Refer to the setup instructions in each feature section:

• Data Discovery
• Semantic Guardrails
• Synthetic Data
• Anonymization
• Data Protection

Setting up Jupyter notebook

Set up the Jupyter notebook for working with the notebooks provided from the cloned repository location for protegrity-ai-developer-edition. Ensure that the Python virtual environment is activated before running this command.

pip install -r shared/requirements.txt

3.4 - Verifying the repository structure

protegrity-ai-developer-edition repository

This repository contains the files for obtaining and running the sample application.

• CHANGELOG.md: Tracks version updates and changes.
• CODE_OF_CONDUCT.md: Details the policies of equality followed at Protegrity.
• CONTRIBUTING.md: The guidelines for contributing to the project.
• LICENSE: The license file with the terms and conditions for using the application.
• README.md: The readme file specifying the steps to set up the product.
• .gitignore: The files and directories to ignore in version control.
• anonymization: The directory with the sample application and scripts for Anonymization.
• binder: The files for running the binder.
• community-solutions: The solutions and projects provided by the community for showcasing and using AI Developer Edition.
• data-discovery: The directory with the sample application and scripts for Data Discovery.
• data-protection: The directory with the sample application and scripts for protecting, unprotecting, and reprotecting data.
• semantic-guardrail: The directory with the sample scripts for Semantic Guardrails.
• synthetic-data: The directory with the sample scripts for Synthetic Data.
• samples: The directory with the sample application and scripts for testing the features.
  • python: The directory with the sample scripts for testing the features using Python.
• shared: The directory with the configuration for AI Developer Edition features.
• solutions: The directory with end-to-end solutions by Protegrity that combine multiple features.

protegrity-ai-developer-python repository

This repository contains the source files for customizing and building the Python module.

• LICENSE: The license file with the terms and conditions for using the application.
• README.md: The readme file for working with the Python file.
• pyproject.toml: The configuration file for the script.
• pytest.ini: The configuration file for the Pytest framework.
• requirements.txt: The file lists the Python package dependencies required by the module.
• setup.cfg: The additional settings for packaging and tools.
• conda-recipe: The configuration files for building and distributing the module as a Conda package.
• src: The core implementation of the Python module.
• tests: The unit and integration tests to ensure that the Python module works as expected.
• .gitignore: The files and directories to ignore in version control.
• .pylintrc: The linting rules for code quality are defined here.
• CHANGELOG.md: The file tracks version updates and changes.
• CONTRIBUTIONS.md: The guidelines for contributing to the project.

protegrity-ai-developer-java repository

This repository contains the source files for customizing and building the Java library.

• LICENSE: The license file with the terms and conditions for using the application.
• README.md: The readme file for working with the Java library.
• pom.xml: The Maven Project Object Model file for building the Java project.
• .gitignore: The files and directories to ignore in version control.
• mvnw and mvnw.cmd: The Maven Wrapper scripts for Linux, Mac, and Windows.
• protegrity-ai-developer-edition: The additional modules or extensions for the Developer Edition.
• integration-tests: The integration tests for validating the Java library functionality.
• application-protector-java: The Java library implementation for the Application Protector service. It includes source code and configuration files.
• .mvn/wrapper: The Maven Wrapper configuration files.

3.5 - Setting up the features

Install the features that you require to use and test the product.

3.5.1 - Setting up Data Discovery

Prerequisites

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 Setting Up AI Developer Edition.
• 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.

Installation

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

• Fresh setup
• Upgrade

3.5.2 - Setting up Semantic Guardrails

Prerequisites

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 Setting Up AI Developer Edition.
• 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.

Installation

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

• Fresh setup
• Upgrade

docker compose logs

3.5.3 - Setting up Synthetic Data

Prerequisites

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 Setting Up AI Developer Edition.
• 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.

Installation

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

• Fresh setup
• Upgrade

3.5.4 - Setting up Anonymization

Prerequisites

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 Setting Up AI Developer Edition.
• 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.

Installation

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
   

3.5.5 - Setting up Data Protection Features

Prerequisites

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

• Python, pip, Java, and Maven are installed. For more information, refer to Setting Up AI Developer Edition.
• Credentials to access AI Developer Edition API Service are obtained by registering for free. For more information, refer to Obtaining access to the AI Developer Edition API Service.
• Required modules and libraries are installed. For more information, refer to Installing the Python module and Installing the Java library.
• For shell samples: Bash version greater than or equal to 5.1.8 and curl version greater than or equal to 7.76.1.
• Verify that the AI Developer Edition Service is running. The service availability can be monitored on the status page, refer to AI Developer Edition System Status.

Note: The Java samples provided in this section are for Linux or macOS. For Windows, use <filename>.bat.

Installation

Steps to install the required modules and libraries for the Data Protection feature are provided below.

Installing the protegrity-ai-developer-python module

The module has built-in functions to find, redact, mask, and protect data.

• Fresh setup
• Upgrade

Installing the protegrity-ai-developer-java library

When you run the Java samples for the first time, Maven automatically pulls the protegrity-ai-developer-java library from Maven Central as a dependency. This ensures that all required classes and resources are available without manual download.

3.5.5.1 - Building the Python Module

The protegrity-ai-developer-python repository is part of the Protegrity AI Developer Edition suite. This repository provides the Python module for integrating Protegrity’s Data Discovery and Protection APIs into GenAI and traditional applications. Customize, compile, and use the module as per your requirement.

Note: This module should only be built and used if the source and default behavior are to be changed. Ensure that the Protegrity AI Developer Edition is set up before installing this module.
For setup instructions, refer to installation steps.

Prerequisites

• Git is installed for cloning the repository.
• Python v3.11 and above is installed for compiling the module.
• For installing packages: pip
• Python Virtual Environment is set up for installing the module and its dependencies.
• Uninstall the protegrity_developer_python module from the Python virtual environment if it is already installed.

  pip uninstall protegrity_developer_python
  

Build the protegrity-ai-developer-python module

1. Clone the repository.

   git clone https://github.com/Protegrity-AI-Developer-Edition/protegrity-ai-developer-python.git
   

2. Navigate to the protegrity-ai-developer-python directory in the cloned location.

3. Optional: Update the files in the Python source directory as required.

4. Activate the Python virtual environment.

5. Install the dependencies.

   pip install -r requirements.txt
   

6. Build and install the Python module by running the following command from the root directory of the repository.

   pip install .
   

   The installation completes and the success message is displayed.

3.5.5.2 - Building the Java Libraries

The protegrity-ai-developer-java repository is part of the Protegrity AI Developer Edition suite. This repository provides the Java library for integrating Protegrity’s Data Discovery and Protection APIs into GenAI and traditional applications. Customize, compile, and use the Java library as per your requirement.

Note: This module should only be built and used if the source and default behavior are to be changed. Ensure that the Protegrity AI Developer Edition is set up before installing the Java library.
For setup instructions, refer to installation steps.

Prerequisites

• Git is installed for cloning the repository.
• Java 11 or later is installed for compiling the library.
• Maven 3.6 or later is installed or use the included Maven wrapper.

Build and test the protegrity-ai-developer-java library

1. Clone the repository.

   git clone https://github.com/Protegrity-AI-Developer-Edition/protegrity-ai-developer-java.git
   

2. Navigate to the protegrity-ai-developer-java directory in the cloned location.

3. Optional: Update the files in the Java source directory as required.

4. Build the project using Maven wrapper. It is recommended to use this method.

   ./mvnw clean install
   

   OR Build the project using system Maven.

   mvn clean install
   

   The build completes and the success message is displayed. This creates:

   • application-protector-java/target/ApplicationProtectorJava-1.1.0.jar (fat JAR with dependencies)
   • protegrity-ai-developer-edition/target/ProtegrityDeveloperJava-1.1.0.jar (fat JAR with dependencies)
   • Maven artifacts in your local repository (.m2/repository)

4 - Updating configurations for the sample application

The steps mentioned in this section are optional. The sample application can run to detect and redact the data with the default configuration.

Sample application customization for Python and Java

From the feature directory, use the appropriate file type for your platform:

Specifying the source file

The source file contains the data that must be processed. This file can have a paragraph of text or a table with values. Protegrity AI Developer Edition can process various files. However, for security reasons, certain characters are not processed and rejected. To enable or disable these security settings, refer to Input Sanitization. This version of the release only supports files containing plain text.

To specify the source file:

• Python
• Java

Specifying the output file

The output file location specifies where the processed output file must be stored.

To specify the output file:

• Python
• Java

Specifying the configuration settings

Use the config.json configuration file to specify the data that must be redacted or masked. The character that must be used for masking can also be specified.

Before you begin:

Identify the sensitive fields that are present in the source file.

• Python
• Java

Updating the configuration file

The configuration file controls how the sample application processes sensitive data. Update the config.json file to customize the masking character, define entity mappings, and select the data protection method.

• Python
• Java

Specifying the classification score threshold settings

The classification score threshold sets the minimum confidence level needed for the system to treat detected data as valid. It helps filter out uncertain matches so only high-confidence results are flagged. Adjust this threshold during setup. It is a value, such as 0.6 for 60%. Lowering it makes the system more sensitive, while raising it reduces false positives.

To set the value:

• Python
• Java

Specifying the logging parameters

The log messages are sent to the terminal. To capture logging data, transfer and save the output of the commands to a log file.

To set the logging level:

• Python
• Java

Python module and Java library configuration

The following parameters are configurable for AI Developer Edition.

5 - Protegrity AI Developer Edition Features

The following features are available with Protegrity AI Developer Edition:

• Data Discovery: Identify sensitive data across your organization using AI-powered scanning and classification.
• Semantic Guardrails: Implement AI-driven policies to protect sensitive data while allowing for flexible access controls.
• Synthetic Data: Create realistic synthetic data for testing and development without exposing real sensitive information.
• Anonymization: Use AI techniques to anonymize or mask sensitive data while preserving its utility for analysis and development.
• Data Protection: Implement encryption and tokenization to secure sensitive data.

In AI Developer Edition, a sample file is used by the sample application, which is processed by the Data Discovery container. The containers detect sensitive data. A Python module then redacts, masks, or protects and unprotects the data. The processed file is saved to a configured location. For more information about the sample application, refer to Sample applications.

Use the steps provided to run the application end-to-end. If required, run the APIs and functions provided for performing specific tasks. For more information about the APIs, refer to the respective Feature APIs.

The sample applications are grouped below based on whether they require a free account registration.

No registration required

The following sample applications can be run by deploying the respective containers without any registration:

• Running Data Discovery
• Running Semantic Guardrails
• Generating synthetic data
• Anonymizing data

Free registration required

Data Protection sample applications require a free account registration. The following sample applications can be run by deploying the respective containers after registering for a free account:

• Data Protection

Sample Applications

Protegrity AI Developer Edition provides Python and Java applications that showcase the features of Protegrity products.

sample-app-find

The sample-app-find is a Python or Java application that processes and identifies sensitive data.

It can be customized to do the following functions:

• Specify a file name and output location for the source data. Only raw file formats are supported for Data Discovery. Multipart formats are not supported; only binary files are accepted.

sample-app-find-and-redact

The sample-app-find-and-redact is a Python or Java application that processes the identified data and redacts or masks the information.

It can be customized to do the following functions:

• Specify the items that must be identified.
• Specify the operation to be performed on the data, which is redact or mask.
• Specify a file name and output location for the source data. Only raw file formats are supported for Data Discovery. Multipart formats are not supported; only binary files are accepted.
• Specify a file name and output location for the transformed data.

sample-guardrail-python

The sample-guardrail-python is a Python application that submits a request to Semantic Guardrails for analysis.

It can be customized to do the following functions:

• Specify the data that must be processed.
• Specify the operation that must be performed, that is, semantic processor for messages and pii processor for AI.

sample-app-find-and-protect

The sample-app-find-and-protect is a Python or Java application that processes the identified data and protects the information. Calls are made to the AI Developer Edition API Service for performing tokenization.

It can be customized to do the following functions:

• Specify the items that must be identified.
• Specify a file name and output location for the source data. Only raw file formats are supported for Data Discovery. Multipart formats are not supported; only binary files are accepted.
• Specify a file name and output location for the transformed data.

sample-app-find-and-unprotect

The sample-app-find-and-unprotect is a Python or Java application that unprotects the information protected by the sample-app-find-and-protect module. Calls are made to the AI Developer Edition API Service for performing detokenization.

It can be customized to do the following functions:

• Specify a file name and output location for the source data. Only data protected by the sample-app-find-and-protect module can be unprotected.
• Specify a file name and output location for the transformed data.

sample-app-protection

The sample-app-protection is a Python or Java application that protects and unprotects data. Calls are made to the AI Developer Edition API Service for performing tokenization. The Data Discovery and Semantic Guardrails containers are not required to be running for the sample-app-protection module to work.

It can be customized to do the following functions:

• Specify the items that must be protected, data element name, and user.
• Specify the operation that must be performed, protect and unprotect.

sample-classification-<type>-text

The sample-classification-<type>-text is a Python, Java, or Jupyter application that classifies the text data. Calls are made to the Data Discovery API Service for performing classification.

It can be customized to do the following functions:

• Specify the data that must be classified.
• Specify the type of classification, which is either pii or semantic.

sample-classification-<type>-tabular

The sample-classification-<type>-tabular is a Python, Java, or Jupyter application that classifies the tabular data. Calls are made to the Data Discovery API Service for performing classification.

It can be customized to do the following functions:

• Specify the data that must be classified.
• Specify the type of classification, which is either pii or semantic.

sample-redaction-<type>

The sample-redaction-<type> is a Python, Java, or Jupyter application that redacts the data. Calls are made to the Data Discovery API Service for performing classification and redaction.

It can be customized to do the following functions:

• Specify the data that must be redacted.
• Specify the type of redaction, which is either pii or semantic.

5.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.

For the steps to set up and configure Data Discovery for AI Developer Edition, refer to the Setting up Data Discovery.

5.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 provides real-time classification of sensitive data in text inputs. 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. Designed for unstructured text such as chatbot conversations, call transcripts, and GenAI outputs.

Architecture

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

5.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.

5.1.3 - 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 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.

5.1.4 - 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.

5.1.5 - 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
   

5.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.

For the steps to set up and configure Semantic Guardrails for AI Developer Edition, refer to the Installation and Setup Guide.

5.2.1 - Semantic Guardrails Architecture

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.

5.2.2 - 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 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.

5.2.3 - 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.

5.2.4 - 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
   

5.3 - Synthetic Data

Synthetic Data generates datasets that mimic the statistical properties of real data without containing actual personal information. By leveraging AI, Synthetic Data enables organizations to generate high-quality synthetic data that maintains the statistical properties of the original data while ensuring privacy and compliance.

For the steps to set up and configure Synthetic Data for AI Developer Edition, refer to the Installation and Setup Guide.

5.3.1 - Synthetic Data Architecture

Synthetic Data 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.

5.3.2 - 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 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.

5.3.3 - 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 using :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 using 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}")
```

5.3.4 - 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
   

5.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.

For the steps to set up and configure Anonymization for AI Developer Edition, refer to the Installation and Setup Guide.

5.4.1 - Anonymization Architecture

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.

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.

5.4.2 - 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 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.

5.4.3 - 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 using 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 using 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