Privra AI Python SDK

Python client for calling the Privra AI security proxy.

Privra AI lets applications send LLM requests through a centralized security proxy for policy checks, PII handling, rate-limit context, audit logs, and provider routing. The SDK uses only your Privra AI proxy API key. Provider keys for OpenAI, Anthropic, and Gemini stay on the Privra AI server.

Install

python -m pip install privra-ai

Quick Start

from privra_ai import PrivraAIClient

client = PrivraAIClient(
    base_url="https://your-privra-proxy.example.com",
    api_key="your-privra-api-key",
)

response = client.responses(
    model="gpt-4o-mini",
    input="Summarize this safely.",
)

print(response["proxy"]["decision"])
print(client.output_text(response))

Environment Variables

The SDK can read connection settings from environment variables:

export PRIVRA_AI_BASE_URL=https://your-privra-proxy.example.com
export PRIVRA_AI_API_KEY=your-privra-api-key

from privra_ai import PrivraAIClient

client = PrivraAIClient.from_env()

Use PRIVRA_AI_BASE_URL, PRIVRA_AI_API_KEY, and the privra_ai import path for new integrations.

Provider Selection

Privra AI supports openai, anthropic, and gemini.

client.responses(
    provider="anthropic",
    model="claude-sonnet-4-6",
    input="Review this text safely.",
)

client.responses(
    provider="gemini",
    model="gemini-2.0-flash",
    input="Review this text safely.",
)

If provider is omitted, Privra AI infers it from the model name where possible. Models starting with claude route to Anthropic, models starting with gemini route to Gemini, and everything else defaults to OpenAI.

Request Metadata

The SDK accepts OpenAI-style request fields plus Privra AI metadata fields:

response = client.responses(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are concise."},
        {"role": "user", "content": "Summarize this safely."},
    ],
    temperature=0.2,
    max_tokens=300,
    context={
        "tenant_id": "tenant-1",
        "app_id": "support-bot",
        "user_id": "user-123",
        "conversation_id": "conversation-456",
        "classification_tags": ["internal"],
        "metadata": {"source": "helpdesk"},
    },
)

Metadata fields are used by Privra AI for policy context, rate-limit context, and audit logs. Provider API keys stay on the proxy server. Metadata is not sent directly to the model provider unless the proxy explicitly allows that field.

Policy Blocks

Policy blocks raise PrivraAIPolicyBlockedError by default:

from privra_ai import PrivraAIClient, PrivraAIPolicyBlockedError

client = PrivraAIClient.from_env()

try:
    client.responses(model="gpt-4o-mini", input="sensitive content")
except PrivraAIPolicyBlockedError as exc:
    print(exc.request_id)
    print(exc.violations)

To receive the raw 403 JSON body instead:

client = PrivraAIClient(
    base_url="https://your-privra-proxy.example.com",
    api_key="your-privra-api-key",
    raise_on_policy_block=False,
)

Response Streaming

Streaming is exposed as a separate iterator. The proxy currently supports response streaming only for OpenAI:

for event in client.responses_stream(
    provider="openai",
    model="gpt-4o-mini",
    input="Stream this safely.",
):
    print(event)

Use responses_stream(...) for streaming responses.

Async Usage

Async applications can use AsyncPrivraAIClient:

from privra_ai import AsyncPrivraAIClient

async with AsyncPrivraAIClient.from_env() as client:
    response = await client.responses(
        provider="openai",
        model="gpt-4o-mini",
        input="Summarize this safely.",
    )
    print(client.output_text(response))

Async streaming uses async for:

async for event in client.responses_stream(
    provider="openai",
    model="gpt-4o-mini",
    input="Stream this safely.",
):
    print(event)

Config and Logs

config = client.get_config()

updated = client.update_config({
    "pii": {
        "action": "mask",
        "unmask_output": True,
    }
})

logs = client.get_logs(limit=100)

Advisor Streaming

for event in client.advisor_chat_stream("Why was the last request blocked?"):
    if "text" in event:
        print(event["text"], end="")

Retries

By default, the SDK does not retry requests. To retry transient gateway failures (502, 503, 504) and transport errors:

client = PrivraAIClient(
    base_url="https://your-privra-proxy.example.com",
    api_key="your-privra-api-key",
    max_retries=2,
)

Policy blocks, authentication errors, rate limits, and non-retryable HTTP errors are not retried.

Requirements

Privra AI Python SDK requires Python 3.9 or newer.