cloak-business 1.0.0

Official Python SDK for cloak.business PII detection and anonymization API

cloak-business

Official Python SDK for the cloak.business PII detection and anonymization API.

Installation

pip install cloak-business

Quick Start

from cloak_business import CloakClient

client = CloakClient(api_key="cb_your_api_key_here")

# Analyze text for PII
analysis = client.analyze(text="Contact John Doe at [e-mail]")

print(analysis["results"])
# [
#   {"entity_type": "PERSON", "start": 8, "end": 16, "score": 0.85},
#   {"entity_type": "EMAIL_ADDRESS", "start": 20, "end": 36, "score": 1.0}
# ]

Features

• Full async support with _async method variants
• Automatic retry with exponential backoff on network/server errors
• Rate limit handling with retry-after support
• Request timeout configuration
• Type hints for IDE support

API Reference

Configuration

client = CloakClient(
    api_key="cb_your_api_key_here",  # Required: Your API key
    base_url="https://cloak.business/api",  # Optional: API base URL
    timeout=30.0,  # Optional: Request timeout in seconds (default: 30.0)
    retries=3,  # Optional: Retry count on 5xx/network errors (default: 3)
)

Context Manager Support

# Sync usage
with CloakClient(api_key="cb_...") as client:
    result = client.analyze(text="...")

# Async usage
async with CloakClient(api_key="cb_...") as client:
    result = await client.analyze_async(text="...")

Text Analysis

analyze(text, ...)

Detect PII entities in text.

result = client.analyze(
    text="My email is [e-mail] and my SSN is 123-45-6789",
    language="en",  # Optional: ISO 639-1 language code
    entities=["EMAIL_ADDRESS", "US_SSN"],  # Optional: Filter entity types
    score_threshold=0.5,  # Optional: Minimum confidence (0.0-1.0)
)

batch_analyze(texts, ...)

Analyze multiple texts in a single request (max 50 texts).

result = client.batch_analyze(
    texts=[
        "Contact [e-mail]",
        "Call me at 555-1234",
    ],
    language="en",
)

Anonymization

anonymize(text, analyzer_results, ...)

Anonymize detected PII entities using various operators.

result = client.anonymize(
    text="Contact John at [e-mail]",
    analyzer_results=analysis["results"],
    operators={
        "PERSON": {"type": "replace", "new_value": "[NAME]"},
        "EMAIL_ADDRESS": {"type": "hash", "hash_type": "sha256"},
        "DEFAULT": {"type": "redact"},  # Fallback for other types
    },
)

Available Operators:

Operator	Description	Options
replace	Replace with custom text	new_value
redact	Remove completely	-
hash	One-way hash	hash_type: 'sha256' or 'sha512'
mask	Partial masking	masking_char, chars_to_mask, from_end
encrypt	Reversible encryption	key (16/24/32 chars)
keep	Leave unchanged	-

deanonymize(text, anonymizer_results, deanonymizers)

Decrypt encrypted PII entities.

decrypted = client.deanonymize(
    text=encrypted["text"],
    anonymizer_results=encrypted["items"],
    deanonymizers={
        "PERSON": {"type": "decrypt", "key": "my-32-character-secret-key!!"},
        "EMAIL_ADDRESS": {"type": "decrypt", "key": "my-32-character-secret-key!!"},
    },
)

Image Processing

process_image(file, mode, ...)

Detect or redact PII in images.

# Analyze mode - returns detected entities
analysis = client.process_image(
    file="./document.png",  # File path, bytes, or Path object
    mode="analyze",
    language="en",
)

# Redact mode - returns image bytes
redacted_bytes = client.process_image(
    file=image_bytes,
    mode="redact",
    fill_color="black",  # 'black', 'white', 'red', 'green', 'blue', 'gray'
)

Account Management

# Get token balance
balance = client.get_token_balance()
print(f"Tokens: {balance['balance']}")

# List encryption sessions
sessions = client.get_sessions()

# Delete a session
client.delete_session("session-id")

Utility Methods

# Get API limits
limits = client.get_limits()

# Get available presets
presets = client.get_presets()

# Get all entity types
entities = client.get_entities()

# Health check
health = client.health()

Async Support

All methods have async variants with _async suffix:

import asyncio
from cloak_business import CloakClient

async def main():
    async with CloakClient(api_key="cb_...") as client:
        # Async analyze
        analysis = await client.analyze_async(
            text="Contact [e-mail]"
        )

        # Async anonymize
        anonymized = await client.anonymize_async(
            text="Contact [e-mail]",
            analyzer_results=analysis["results"],
        )

        print(anonymized["text"])

asyncio.run(main())

Error Handling

The SDK provides typed exceptions for different failure scenarios:

from cloak_business import (
    CloakClient,
    AuthenticationError,
    RateLimitError,
    InsufficientTokensError,
    ValidationError,
)

try:
    client.analyze(text="test")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except InsufficientTokensError:
    print("Not enough tokens")
except ValidationError as e:
    print(f"Invalid request: {e.details}")

Requirements

• Python 3.9 or higher
• httpx >= 0.25.0

License

MIT