Metadata-Version: 2.5
Name: privra-ai
Version: 0.2.0
Summary: Python SDK for the Privra AI security proxy
Project-URL: Homepage, https://github.com/privra/privra-ai-python
Project-URL: Repository, https://github.com/privra/privra-ai-python
Author: Privra AI
License: Proprietary
Keywords: ai,llm,pii,prompt-injection,proxy,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.25
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
python -m pip install privra-ai
```

## Quick Start

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

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

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

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

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

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

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

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

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

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

## Config and Logs

```python
config = client.get_config()

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

logs = client.get_logs(limit=100)
```

## Advisor Streaming

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

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