Skip to main content

Python Client

The official tszclient_py package provides a small typed wrapper for Safe Zone detection and chat-completions gateway calls. Use it when a Python service needs consistent timeouts, authentication headers, response parsing, and error handling without maintaining raw HTTP code at every call site.

Installation​

Install the client from the Safe Zone source repository:

pip install "tszclient-py @ git+https://source.example/thyris/repository@main"

The client uses requests. Pin the Safe Zone source revision in production so deployments do not change when the default branch changes.

Create a Client​

from tszclient_py import TSZClient, TSZConfig

client = TSZClient(TSZConfig(
    base_url="http://localhost:8080",
    api_key="token_detect",
    timeout=10.0,
))

base_url points to the Safe Zone gateway. api_key is optional when authentication is disabled. When it is provided, the client sends a bearer token and the legacy admin-key header for compatibility. Use a token limited to the operation the application performs.

Detect and Redact Text​

result = client.detect_text(
    "Send the report to user@example.com",
    rid="checkout-8f3c",
    guardrails=["TOXIC_LANGUAGE"],
)

if result.blocked:
    raise ValueError(result.message or "Safe Zone blocked the request")

safe_text = result.redacted_text or ""
print(safe_text)

This call scans the text, applies the named guardrails, and returns typed detection results. The rid connects the application request to Safe Zone audit data. If blocked is true, stop the downstream operation. Otherwise, use redacted_text rather than the original input.

Inspect Detection Details​

for detection in result.detections:
    print(
        detection.type,
        detection.placeholder,
        detection.confidence_score,
    )

Detection details are useful for audit and metrics. Avoid writing detection.value to ordinary application logs because it contains the sensitive value that Safe Zone found.

Call the LLM Gateway​

from tszclient_py import ChatCompletionRequest

response = client.chat_completions(
    ChatCompletionRequest(
        model="your-approved-model",
        messages=[
            {"role": "user", "content": "Summarize this customer request"},
        ],
    ),
    headers={
        "X-TSZ-RID": "support-42",
        "X-TSZ-Guardrails": "TOXIC_LANGUAGE",
    },
)

content = response["choices"][0]["message"]["content"]

The gateway scans user input before it reaches the upstream model and checks the model output before returning it in non-streaming mode. Gateway headers select the request ID and guardrail set for this call.

Error Handling​

from tszclient_py import APIError

try:
    result = client.detect_text("Text to scan", rid="request-123")
except APIError as exc:
    print(f"Safe Zone returned HTTP {exc.status_code}")
except RuntimeError as exc:
    print(f"Safe Zone request failed: {exc}")

APIError represents a non-success HTTP response. Network failures and invalid JSON responses are raised as RuntimeError. Decide whether to fail closed or fail open before production; sensitive workflows should normally fail closed.

Production Guidance​

  • Reuse a configured requests.Session for connection pooling in long-running services.
  • Set a timeout shorter than the caller's total request deadline.
  • Use a stable, non-sensitive request ID for correlation.
  • Never log raw sensitive input or detection values.
  • Handle blocked separately from transport errors.
  • Use detect:read for detection-only clients and gateway:use for gateway clients.

See Authentication and Access Control for token permissions and Policy Management for configuring the guardrails referenced by client calls.