cloak-business 1.0.0
Official Python SDK for cloak.business PII detection and anonymization API
Requires Python: >=3.9
Keywords: anonymization, cloak, data-protection, encryption, gdpr, pii, presidio, privacy, redaction

# cloak-business

Official Python SDK for the [cloak.business](https://cloak.business) PII detection and anonymization API.

## Installation

```bash
pip install cloak-business
```

## Quick Start

```python
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 john@example.com")

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

```python
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

```python
# 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.

```python
result = client.analyze(
    text="My email is john@example.com 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).

```python
result = client.batch_analyze(
    texts=[
        "Contact john@example.com",
        "Call me at 555-1234",
    ],
    language="en",
)
```

### Anonymization

#### `anonymize(text, analyzer_results, ...)`

Anonymize detected PII entities using various operators.

```python
result = client.anonymize(
    text="Contact John at john@example.com",
    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.

```python
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.

```python
# 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

```python
# 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

```python
# 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:

```python
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 john@example.com"
        )

        # Async anonymize
        anonymized = await client.anonymize_async(
            text="Contact john@example.com",
            analyzer_results=analysis["results"],
        )

        print(anonymized["text"])

asyncio.run(main())
```

## Error Handling

The SDK provides typed exceptions for different failure scenarios:

```python
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