Python SDK API Reference (vouch-sdk)

The vouch-sdk package exports four public functions: init(), firewall_headers(), redact_text(), and redact_value(). This page documents every parameter, return value, and supported environment variable for each one.

`vouch_sdk.init()`

def init(
    project_pk: str | None = None,
    project_sk: str | None = None,
    agent_id: str | None = None,
    endpoint: str | None = None,
    *,
    agent_url: str | None = None,
    app_name: str | None = None,
    disable_batch: bool = False,
    instruments: set | None = None,
    redact_pii: bool | dict = True,
    **traceloop_kwargs,
) -> None

Initialises Trident tracing for the current Python process. Call this once, before you create any LLM client, at the top of your application entry point. init() lazy-imports the OpenLLMetry / traceloop instrumentation layer, patches all supported LLM clients already in scope, and begins shipping OTel spans to your Trident project. When redact_pii is enabled (the default), it installs a span processor that scrubs PII from span attributes before the OTLP export request leaves your process.

Parameters

project_pk

str

Project public key. Falls back to TRIDENT_PROJECT_PUBLIC_KEY, then VOUCH_PROJECT_PUBLIC_KEY. Required — provide it here or via the environment variable.

project_sk

str

Project secret key. Falls back to TRIDENT_PROJECT_SECRET_KEY, then VOUCH_PROJECT_SECRET_KEY. Required — provide it here or via the environment variable.

agent_id

str

A logical identifier for this agent (e.g. "prod-rag-bot"). Appears in the Trident dashboard’s connection panel and scopes all spans to a named agent. Falls back to TRIDENT_AGENT_ID / VOUCH_AGENT_ID.

endpoint

str

default:"https://app.tryvouch.ai"

Override the Trident host. Useful for on-premise deployments. Falls back to TRIDENT_ENDPOINT, then VOUCH_ENDPOINT.

agent_url

str

Public HTTP endpoint where this agent receives prompts (e.g. "https://api.example.com/api/chat"). When set, the SDK fires a background POST to Trident’s agent registration endpoint so the Red Team page can auto-target your agent without you typing a URL. Falls back to VOUCH_AGENT_URL. Failure is silent — it never interrupts tracing setup.

app_name

str

OTel resource service.name. Defaults to agent_id, then "vouch-app".

disable_batch

bool

default:"False"

Emit each span immediately via SimpleSpanProcessor instead of batching with BatchSpanProcessor. Useful for short-lived scripts or notebooks where the process exits before the batch flushes.

instruments

set

Pass a set of traceloop Instruments enum values to restrict which libraries are instrumented. When None (the default) all supported integrations are activated.

redact_pii

bool | dict

default:"True"

Controls edge PII redaction. True uses the built-in rule set (emails, AWS keys, JWTs, API keys, SSNs, credit card numbers, IBANs, IPs, phone numbers). Pass {"rules": [...]} to supply a custom list of PiiRule named tuples. False disables redaction entirely.Redaction runs in-process before any data leaves — raw PII never travels over the wire to Trident.

**traceloop_kwargs

Any

Extra keyword arguments forwarded verbatim to Traceloop.init(). Use these for advanced OpenLLMetry configuration not directly exposed by the Trident wrapper.

Return value

None. Tracing is started synchronously. Agent registration (when agent_url is set) runs on a daemon thread in the background.

Raises

ValueError if both project_pk and project_sk are unresolvable from the arguments and environment.

Example

import vouch_sdk

vouch_sdk.init(
    project_pk="pk-lf-...",
    project_sk="sk-lf-...",
    agent_id="prod-rag-bot",
    endpoint="https://app.tryvouch.ai",  # optional
    agent_url="https://api.example.com/api/chat",
    disable_batch=False,
    redact_pii=True,
)

`vouch_sdk.firewall_headers()`

def firewall_headers(
    project_pk: str | None = None,
    project_sk: str | None = None,
    agent_id: str | None = None,
    *,
    policy_id: str | None = None,
    upstream_trace_id: str | None = None,
    include_project_credentials: bool = True,
) -> dict[str, str]

Returns a dictionary of HTTP headers you attach to requests sent to the Trident firewall service. Use this when you call the firewall’s HTTP API directly — for example when you’ve deployed the firewall as a sidecar and want to associate the scan with your project, agent, and active OTel trace.

Parameters

project_pk

str

Project public key. Falls back to TRIDENT_PROJECT_PUBLIC_KEY / VOUCH_PROJECT_PUBLIC_KEY. Required when include_project_credentials=True (the default).

project_sk

str

Project secret key. Falls back to TRIDENT_PROJECT_SECRET_KEY / VOUCH_PROJECT_SECRET_KEY. Required when include_project_credentials=True.

agent_id

str

Agent identifier to attach to the scan. Falls back to TRIDENT_AGENT_ID / VOUCH_AGENT_ID.

policy_id

str

Specific policy ID to enforce for this scan. When omitted the firewall applies the project’s default policy.

upstream_trace_id

str

OTel trace ID from the upstream request. The firewall attaches its own span to this trace so the scan appears in the same trace tree as your agent’s LLM calls.

include_project_credentials

bool

default:"True"

When True, the returned dict includes x-vouch-langfuse-public-key and x-vouch-langfuse-secret-key headers so the firewall can attribute telemetry to your project. Set False if you use a different authentication mechanism.

Return value

dict[str, str] — a flat dictionary of HTTP header name → value pairs. Pass it directly to your HTTP client’s headers parameter. The dictionary may contain any of the following headers:

Header	Set when
`x-vouch-agent`	`agent_id` is resolved
`x-vouch-policy`	`policy_id` is provided
`x-vouch-trace-id`	`upstream_trace_id` is provided
`x-vouch-langfuse-public-key`	`include_project_credentials=True`
`x-vouch-langfuse-secret-key`	`include_project_credentials=True`

Raises

ValueError if include_project_credentials=True and neither project_pk/project_sk arguments nor the corresponding environment variables are set.

Example

import httpx
import vouch_sdk

# Build the header dict.
headers = vouch_sdk.firewall_headers(
    agent_id="prod-rag-bot",
    upstream_trace_id=current_trace_id,
)

# Attach the headers to your firewall HTTP call.
response = httpx.post(
    "https://firewall.example.com/scan",
    headers=headers,
    json={"prompt": user_message},
)
verdict = response.json()

if not verdict.get("is_valid"):
    return "I'm unable to help with that."

`vouch_sdk.redact_text()`

def redact_text(text: Any, rules: list[PiiRule] | None = None) -> Any

Scans a string for PII and returns a copy with every detected pattern replaced by a [REDACTED_<TYPE>] token. Non-string values are returned unchanged. Uses the default rule set when rules is omitted. Call this function directly when you want to scrub your own payloads — for example before logging a user message, writing to a database, or passing content to a third-party service — rather than relying solely on the automatic span-level redaction.

Parameters

text

Any

required

The value to scan. Strings are scrubbed and returned as new strings. Non-string values (including None) pass through unchanged without error.

rules

list[PiiRule] | None

Custom list of PiiRule named tuples to apply instead of the built-in defaults. When None (the default), DEFAULT_PII_RULES is used. Import PiiRule and DEFAULT_PII_RULES from vouch_sdk to build your own rule set.

Return value

Any — a new string with all matched PII replaced, or the original value unchanged if it is not a string or contains no matches.

PII patterns detected by default

Token	Pattern
`[REDACTED_EMAIL]`	Email addresses
`[REDACTED_AWS_KEY]`	AWS access key IDs (`AKIA…`, `ASIA…`, `AIDA…`, `AROA…`)
`[REDACTED_JWT]`	JSON Web Tokens (`eyJ…`)
`[REDACTED_API_KEY]`	API keys matching `sk-…` or `sk-ant-…`
`[REDACTED_SSN]`	US Social Security Numbers (`XXX-XX-XXXX`)
`[REDACTED_CREDIT_CARD]`	Credit card numbers (Luhn-validated)
`[REDACTED_IBAN]`	International Bank Account Numbers
`[REDACTED_IP]`	IPv4 addresses
`[REDACTED_PHONE]`	Phone numbers

Example

import vouch_sdk

raw = "Contact jane.doe@example.com or call +1 415-555-0123 for support."
clean = vouch_sdk.redact_text(raw)
# "Contact [REDACTED_EMAIL] or call [REDACTED_PHONE] for support."

print(clean)

`vouch_sdk.redact_value()`

def redact_value(value: Any, rules: list[PiiRule] | None = None) -> Any

Recursively scrubs PII from an arbitrary Python value. Handles strings, lists, tuples, and dicts by descending into the structure and applying redact_text() to every string it finds. Non-string scalars (int, float, bool, None) are returned unchanged. Use this when you need to sanitise structured objects — API response bodies, JSON payloads, span attribute dicts — before sending them anywhere.

Parameters

value

Any

required

The value to scrub. May be a str, list, tuple, dict, or any scalar. The function does not mutate the input — it returns a new value.

rules

list[PiiRule] | None

Custom list of PiiRule named tuples to apply instead of the built-in defaults. When None (the default), DEFAULT_PII_RULES is used.

Return value

Any — a copy of the input with all string values scrubbed. The type and structure are preserved:

str → str
list → list (same length, string elements scrubbed)
tuple → tuple
dict → dict (keys preserved, string values scrubbed)
All other types → returned unchanged

Example

import vouch_sdk

payload = {
    "user": "alice@example.com",
    "card": "4111 1111 1111 1111",
    "messages": [
        {"role": "user", "content": "My SSN is 123-45-6789"},
        {"role": "assistant", "content": "Got it."},
    ],
    "request_count": 42,
}

clean = vouch_sdk.redact_value(payload)
# {
#   "user": "[REDACTED_EMAIL]",
#   "card": "[REDACTED_CREDIT_CARD]",
#   "messages": [
#     {"role": "user", "content": "My SSN is [REDACTED_SSN]"},
#     {"role": "assistant", "content": "Got it."},
#   ],
#   "request_count": 42,
# }

redact_value() is the right choice when you’re handling structured data like API responses or log records. Use redact_text() when you have a single string to sanitise.

Environment variables

The SDK reads the following environment variables. Explicitly passed arguments always take precedence.

Variable	Used by	Description
`TRIDENT_PROJECT_PUBLIC_KEY`	`init`, `firewall_headers`	Project public key. Preferred name.
`TRIDENT_PROJECT_SECRET_KEY`	`init`, `firewall_headers`	Project secret key. Preferred name.
`VOUCH_PROJECT_PUBLIC_KEY`	`init`, `firewall_headers`	Back-compat alias.
`VOUCH_PROJECT_SECRET_KEY`	`init`, `firewall_headers`	Back-compat alias.
`TRIDENT_AGENT_ID`	`init`, `firewall_headers`	Logical agent identifier.
`VOUCH_AGENT_ID`	`init`, `firewall_headers`	Back-compat alias.
`TRIDENT_ENDPOINT`	`init`	Override the Trident host.
`VOUCH_ENDPOINT`	`init`	Back-compat alias.
`VOUCH_AGENT_URL`	`init`	Public agent endpoint for Red Team registration.

​vouch_sdk.init()

​Parameters

​Return value

​Raises

​Example

​vouch_sdk.firewall_headers()

​Parameters

​Return value

​Raises

​Example

​vouch_sdk.redact_text()

​Parameters

​Return value

​PII patterns detected by default

​Example

​vouch_sdk.redact_value()

​Parameters

​Return value

​Example

​Environment variables

`vouch_sdk.init()`

Parameters

Return value

Raises

Example

`vouch_sdk.firewall_headers()`

Parameters

Return value

Raises

Example

`vouch_sdk.redact_text()`

Parameters

Return value

PII patterns detected by default

Example

`vouch_sdk.redact_value()`

Parameters

Return value

Example

Environment variables