privedge (Python SDK)

Privacy on the edge. Python client for the Privedge compliance proxy — a drop-in-style AI inference gateway that detects PII/secrets in your prompts and either anonymizes them before forwarding to a cloud LLM, routes inference to a Cloudflare edge model instead (no external call at all), or passes clean prompts through untouched.

Functional parity with @privedge/sdk (TypeScript). See the root README for how the proxy itself works.

Install

pip install privedge

Requires Python 3.9+. The only runtime dependency is httpx (see Dependencies).

Quickstart — sync

from privedge import Privedge

client = Privedge(api_key="pvdg_live_...", worker_url="https://edge.privedge.io")

resp = client.chat.completions.create(
    model="gpt-5.4-nano",
    messages=[{"role": "user", "content": "Summarize this patient record..."}],
)

print(resp.choices[0].message["content"])
print(resp.routed_to)     # "edge" | "cloud"
print(resp.anonymized)    # True if PII was redacted before the cloud call
print(resp.pii_matches)   # number of PII tokens detected
print(resp.ner_ran)       # whether semantic (NER) detection ran — see below

Or as a context manager, to close the HTTP session automatically:

with Privedge(api_key="pvdg_live_...", worker_url="https://edge.privedge.io") as client:
    resp = client.chat.completions.create(
        model="gpt-5.4-nano",
        messages=[{"role": "user", "content": "..."}],
    )

Quickstart — async

import asyncio
from privedge import AsyncPrivedge

async def main():
    async with AsyncPrivedge(api_key="pvdg_live_...", worker_url="https://edge.privedge.io") as client:
        resp = await client.chat.completions.create(
            model="gpt-5.4-nano",
            messages=[{"role": "user", "content": "..."}],
        )
        print(resp.choices[0].message["content"])

asyncio.run(main())

Other endpoints

# Dry-run PII/secret detection, no LLM call
detect = client.detect(messages=[{"role": "user", "content": "My DNI is 12345678Z"}])
print(detect.pii_types, detect.pii_count, detect.has_secret, detect.ner_ran)

# API key metadata
info = client.keys.info()
print(info.provider, info.provider_mode, info.cloud_model)

ner_ran — read this before you rely on empty PII results

Every response — ChatCompletionResponse and DetectResponse — carries a boolean ner_ran field.

The semantic detection layer (Named Entity Recognition — catches person names, organizations, and street addresses that regex cannot) is gated behind the Pro/Enterprise tier. On the Free tier it never runs, so ner_entities (or pii_types restricted to NER-only categories) is always empty — not because your prompt is clean, but because names, organizations and addresses were never looked for.

resp = client.chat.completions.create(model="gpt-5.4-nano", messages=[...])

if not resp.ner_ran:
    # resp.ner_entities == [] here tells you NOTHING about whether the
    # prompt contains a person's name, a hospital name, or a street address.
    # Only regex-coverable PII (SSN, DNI, email, credit cards, phone, etc.)
    # was checked.
    ...

Always check ner_ran before treating an empty ner_entities (or the absence of NER-only types in pii_types) as "this prompt has no PII." Treat it as "no PII of the types actually checked."

Response fields

ChatCompletionResponse

DetectResponse (from client.detect(...))

KeyInfo (from client.keys.info())

Exceptions

All errors raised by the SDK derive from PrivedgeError, which carries .message, .status_code, and .body (the parsed JSON error payload, if any).

from privedge import Privedge, PrivedgeNERUnavailableError, PrivedgeRateLimitError

with Privedge(api_key="...", worker_url="...") as client:
    try:
        resp = client.chat.completions.create(model="gpt-5.4-nano", messages=[...])
    except PrivedgeNERUnavailableError:
        # Nothing leaked — detection failed closed. Retry shortly.
        ...
    except PrivedgeRateLimitError as e:
        print(f"retry after reset={e.reset}, remaining={e.remaining}")

Detection scope by tier

On Free, client.detect(...) and chat.completions.create(...) only ever check the deterministic regex layer. If your prompts might contain names of patients, clients, or organizations and that matters for your compliance posture, you need a Pro/Enterprise key — ner_ran=False on Free is not a bug, it's the tier boundary made visible instead of silently assumed.

Model resolution

model is optional on chat.completions.create(...):

# model omitted — the worker falls back to the cloud_model configured on
# the API key (see client.keys.info().cloud_model)
resp = client.chat.completions.create(
    messages=[{"role": "user", "content": "..."}],
)

# model passed — always wins over the key's configured default
resp = client.chat.completions.create(
    model="gpt-5.4-nano",
    messages=[{"role": "user", "content": "..."}],
)

Passing model always takes precedence over the key's configured cloud_model. This keeps the SDK a drop-in OpenAI replacement, and on a self-hosted deployment — where there's no dashboard to configure a key's default model — it's the only way to choose one at all.

When model is omitted, the SDK does not send the field (never as model: null); the worker only honors a request-supplied model when it's present as a string.

No streaming

The Privedge worker has no streaming code path — stream is not accepted by this SDK. Every request is a single buffered request/response.

Timeouts

client = Privedge(api_key="...", worker_url="...", timeout=30.0)  # seconds, default 60.0

Applies to connect/read/write/pool via httpx's timeout model. A PrivedgeAPIError is raised on timeout.

Dependencies

Total runtime dependency footprint: one package (httpx).

Development

cd packages/sdk-python
pip install -e ".[dev]"
pytest

Tests mock all HTTP calls via respx — no network access required, no live worker needed.