SCT Python SDK

Python client library for the SCT (Secure Compact Tokenization) API. Pseudonymize, de-pseudonymize, detect PII, compress bulky output, and optimize LLM tokens with a single import — sync (SCTClient) or async (AsyncSCTClient).

Installation

pip install sct-client

Quick Start

from sct_client import SCTClient

with SCTClient(api_key="sct_YOUR_API_KEY") as sct:
    # Pseudonymize a JSON record
    result = sct.pseudonymize(
        '{"name": "Max Mustermann", "email": "max@example.com"}',
        format="json",
        auto_detect_pii=True,
    )
    print(result.pseudonymized_data)
    print(f"Processed {result.record_count} records in {result.duration_ms}ms")

Pseudonymize and De-pseudonymize

from sct_client import SCTClient

sct = SCTClient(api_key="sct_YOUR_API_KEY")

# Pseudonymize with specific fields
result = sct.pseudonymize(
    '{"name": "Erika Musterfrau", "age": 42, "email": "erika@example.com"}',
    format="json",
    encryption_method="aes-256-gcm",
    fields=["name", "email"],
)

# Reverse the pseudonymization
original = sct.de_pseudonymize(
    result.pseudonymized_data,
    encryption_key="YOUR_ENCRYPTION_KEY",
    format="json",
)
print(original.original_data)

sct.close()

PII Detection

with SCTClient(api_key="sct_YOUR_API_KEY") as sct:
    result = sct.detect_pii(
        "Bitte kontaktieren Sie Max Mustermann unter max@example.com oder 0171-1234567."
    )
    for entity in result.entities:
        print(f"  {entity['entity_type']}: {entity['value']}")

Token Optimization

Reduce LLM token usage while preserving meaning:

import os

with SCTClient(api_key=os.environ["SCT_API_KEY"]) as sct:
    result = sct.optimize_tokens(
        "This is a long document that could be compressed for LLM processing...",
        model="gpt-4o",
        aggressive_fillers=True,  # opt-in extra filler-word removal
    )
    print(f"Tokens: {result.original_tokens} -> {result.optimized_tokens}")
    print(f"Reduction: {result.reduction_pct:.1%}")

    # Just count tokens without optimizing
    count = sct.count_tokens("How many tokens is this?", model="claude-3")
    print(f"Token count: {count.token_count}")

Output Compression

Compress bulky tool/observation output (test runners, linters, diffs, grep, …) before it hits an LLM. The engine picks a structured parser, a noise-strip filter, or the prose optimizer, and is guaranteed never to cost more tokens than the raw input. compress_output() is an alias of compress().

import os

with SCTClient(api_key=os.environ["SCT_API_KEY"]) as sct:
    result = sct.compress(
        raw_pytest_output,
        format="pytest",      # omit to let the engine sniff the format
        model="gpt-4o",
        verbosity="compact",  # compact | verbose | ultra
    )
    print(result.compressed)
    print(f"Saved {result.tokens_saved} tokens ({result.savings_pct}%)")
    print(f"tier={result.tier} format_used={result.format_used}")

Async

AsyncSCTClient mirrors the full sync surface (built on httpx.AsyncClient) for LangChain ainvoke/abatch and other async paths:

import os

from sct_client import AsyncSCTClient

async with AsyncSCTClient(api_key=os.environ["SCT_API_KEY"]) as sct:
    ps = await sct.pseudonymize('{"name": "Max"}', auto_detect_pii=True)
    comp = await sct.compress(bulky_text, format="jest")
    original = await sct.de_pseudonymize(ps.pseudonymized_data, ps.encryption_key)

End-to-End Encrypted Streaming

For large datasets, use streaming sessions with client-side encryption:

with SCTClient(api_key="sct_YOUR_API_KEY") as sct:
    # Single-request E2E processing
    result = sct.stream_e2e(
        kek="YOUR_KEK",
        envelope={
            "wrapped_dek": "...",
            "ciphertext": "...",
            "nonce": "...",
        },
        mode="pseudonymize",
        throughput_tier="real_time",
    )

    # Multi-chunk session
    session = sct.create_session(kek="YOUR_KEK", mode="pseudonymize")

    sct.send_chunk(session.session_id, index=0, envelope={...})
    sct.send_chunk(session.session_id, index=1, envelope={...}, is_last=True)

    audit = sct.get_session_audit(session.session_id)
    sct.close_session(session.session_id)

Error Handling

The SDK raises typed exceptions for every error category:

from sct_client import SCTClient
from sct_client.exceptions import (
    SCTAuthenticationError,
    SCTRateLimitError,
    SCTValidationError,
)

with SCTClient(api_key="sct_YOUR_API_KEY") as sct:
    try:
        result = sct.pseudonymize("")
    except SCTValidationError as exc:
        print(f"Invalid request: {exc} — details: {exc.details}")
    except SCTAuthenticationError:
        print("Check your API key")
    except SCTRateLimitError as exc:
        print(f"Slow down — retry after {exc.retry_after}s")

Configuration

Encryption Methods

License

MIT