> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetrident.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Python SDK API Reference (vouch-sdk)
> Complete API reference for vouch-sdk: vouch_sdk.init(), firewall_headers(), redact_text(), redact_value(), and configuration options.
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()`
```python theme={null}
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 public key. Falls back to `TRIDENT_PROJECT_PUBLIC_KEY`, then `VOUCH_PROJECT_PUBLIC_KEY`. **Required** — provide it here or via the environment variable.
Project secret key. Falls back to `TRIDENT_PROJECT_SECRET_KEY`, then `VOUCH_PROJECT_SECRET_KEY`. **Required** — provide it here or via the environment variable.
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`.
Override the Trident host. Useful for on-premise deployments. Falls back to `TRIDENT_ENDPOINT`, then `VOUCH_ENDPOINT`.
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.
OTel resource `service.name`. Defaults to `agent_id`, then `"vouch-app"`.
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.
Pass a set of traceloop `Instruments` enum values to restrict which libraries are instrumented. When `None` (the default) all supported integrations are activated.
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.
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
```python theme={null}
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()`
```python theme={null}
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 public key. Falls back to `TRIDENT_PROJECT_PUBLIC_KEY` / `VOUCH_PROJECT_PUBLIC_KEY`. Required when `include_project_credentials=True` (the default).
Project secret key. Falls back to `TRIDENT_PROJECT_SECRET_KEY` / `VOUCH_PROJECT_SECRET_KEY`. Required when `include_project_credentials=True`.
Agent identifier to attach to the scan. Falls back to `TRIDENT_AGENT_ID` / `VOUCH_AGENT_ID`.
Specific policy ID to enforce for this scan. When omitted the firewall applies the project's default policy.
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.
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
```python theme={null}
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()`
```python theme={null}
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_]` 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
The value to scan. Strings are scrubbed and returned as new strings. Non-string values (including `None`) pass through unchanged without error.
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
```python theme={null}
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()`
```python theme={null}
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
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.
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
```python theme={null}
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. |