Anonymization SDK

Python client library for the Protegrity Anonymization server

Requirements

Running Anonymization Server: This SDK requires a running Anonymization server.

Installation

# Using pip
pip install -e .

# Using uv, by adding dependency
uv sync

Quick Start

from anonymization_sdk import AnonymizationClient

with AnonymizationClient(base_url="http://localhost:8000") as client:
    result = client.auto_anonymize(
        data=[
            {"patient_id": "P001", "age": 25, "zipcode": "12345", "disease": "flu"},
            {"patient_id": "P002", "age": 30, "zipcode": "23456", "disease": "cold"},
        ],
        k=2,
    )
    print(f"Anonymized {result.anonymization.row_count} records")

Features

• Simple API: Easy-to-use Python client for the Anonymization server
• Privacy Models: k-anonymity, l-diversity, t-closeness, differential privacy
• Auto-Detection: Automatic QI/DI/SA detection
• Solution Reuse: apply_anon() re-applies a saved solution to new data batches without recomputing
• Lattice Search: Opt-in optimal generalization level search (use_lattice_search=True)
• Risk Metrics: Calculate re-identification risk

Detection

• detect_qi() — Auto-detect quasi-identifiers
• generate_config() — Auto-generate anonymization config

Anonymization

• anonymize() — Synchronous anonymization (supports use_lattice_search, mlops_config)
• apply_anon() — Apply a saved solution to new data without recomputing
• submit_job() — Submit async anonymization job
• get_job_status() — Check job status
• cancel_job() — Cancel running job
• auto_anonymize() — One-step detection + anonymization

Risk & Validation

• calculate_risk() — Calculate re-identification risk (supports mlops_config)
• validate() — Validate privacy guarantees
• measure() — Measure anonymization quality

Differential Privacy

• dp_compute() — Compute DP-protected aggregate (mean, sum, variance, histogram)
• dp_stream_update() — feed a batch into a streaming session (creates on first call)
• dp_stream_delete() — close and delete a streaming session
• dp_stream_list_sessions() — list active streaming sessions
• dp_budget_create() / dp_budget_status() / dp_budget_delete()
• dp_advise_composition() — advise on epsilon/delta budget for a composition plan

Privacy Models

Model	Protection Level	Use Case	Key Feature
k-anonymity	Basic	Hide in groups of k	Each record indistinguishable from k-1 others
l-diversity	Enhanced	Diverse sensitive values	Prevents homogeneity attacks
t-closeness	Advanced	Distribution matching	Prevents skewness attacks
Differential Privacy	Mathematical	Aggregate queries, streaming	Provable ε-privacy guarantees via calibrated noise

Example Use Cases

• Healthcare: Anonymize patient records for research (HIPAA compliance)
• Finance: Share transaction data for analysis (PCI DSS compliance)
• Marketing: Publish customer analytics datasets (GDPR compliance)
• Research: Share study data with collaborators (IRB approval)

Lattice Search

By default the server applies level 1 of every configured hierarchy. Pass use_lattice_search=True to find the shallowest generalization level combination that satisfies k-anonymity — yielding lower information loss:

result = client.anonymize(
    data=data,
    k=10,
    max_suppression=0.05,
    attributes=[...],
    use_lattice_search=True,
    lattice_strategy="basic",  # basic | with_importance | with_deviation | full
)

The generalization_levels field in the result shows the actual levels chosen per QI.

Solution Reuse (apply_anon)

Re-apply the exact same solution to new data batches without recomputing hierarchies:

# Step 1: anonymize training batch → solution stored server-side
anon = client.anonymize(data=training_data, k=5, ...)
job_id = anon.job_id

# Step 2: apply to any new batch instantly
apply_result = client.apply_anon(job_id=job_id, data=new_batch)
print(f"Applied: {apply_result.row_count} rows | Suppressed: {apply_result.suppressed_count}")

client = AnonymizationClient(
    base_url="http://localhost:8000",
    mlops_config={
        "postgres_dsn": "postgresql://mlopsuser:mlopspsw@localhost:5432/mlopsdb",
        "experiment_prefix": "my-project",
        "model_name": "patient-records",
        "auto_promote": True,
        "promotion_metric": "combined_loss",
        "promotion_direction": "lower_better",
    },
)
result = client.anonymize(data=data, k=5, ...)
models = client.list_models()

Configuration

Use ClientConfig to configure the SDK, or load settings from environment variables with ClientConfig.from_env().

from anonymization_sdk import AnonymizationClient
from anonymization_sdk.config import ClientConfig

# Explicit configuration
config = ClientConfig(
    base_url="https://api.example.com/pty/anonymization/v3",
    username="admin",
    password="secret",
    verify_ssl=True,
)

# Or load from environment variables
config = ClientConfig.from_env()

client = AnonymizationClient(config=config)

The key environment variables are ANON_API_URL, ANON_USERNAME, and ANON_PASSWORD. See ClientConfig.from_env() docstring for the full list.

Supported Storage DSN Formats

data and output_uri accept a local path/file:// URI (read and sent as inline base64 by the SDK) or a cloud URI, forwarded to the server and resolved by pty-ai-artifact-storage-lib:

Scheme	Backend
file://, /abs/path, ./rel/path	Local filesystem (SDK reads & inlines)
s3:// (aliases s3a://, s3n://)	AWS S3
minio://	MinIO / S3-compatible
gs:// (alias gcs://)	Google Cloud Storage
abfs://, abfss:// (legacy azure://, az://)	Azure Blob Storage

Credentials are embedded in the URI (s3://key:secret@region/bucket/...); see anonymization_sdk.config module docstring for full examples.

Documentation

API reference is available via docstrings in src/anonymization_sdk/. Refer to Online Documentation

Support

• Issues: Report bugs and request features via issue tracker
• Email: info@protegrity.com

License

MIT License