veriproof-sdk

Python 3.9+OpenTelemetry

Who can use this

Available to

DeveloperAdministrator

Not available to

Governance EngineerCompliance OfficerBusiness OwnerAuditor

SDK installation, configuration, and reference documentation is for Developers and Administrators. Governance Engineers, Compliance Officers, Business Owners, and Auditors work with the output of SDK instrumentation in the portal — they do not install or configure the SDK. Start with the Training Academy track for your role instead.

The core Python SDK for VeriProof. Handles OpenTelemetry configuration, session-level governance tracing, batch export with Merkle verification, and circuit-breaker transport resilience.

Install:


pip install veriproof-sdk

Quick start


import os
from veriproof_sdk import VeriproofClientOptions, configure_veriproof
 
# Call once at application startup
configure_veriproof(
    VeriproofClientOptions(
        api_key=os.environ["VERIPROOF_API_KEY"],
        application_id="my-ai-app",
    ),
    service_name="my-ai-app",
    set_global=True,   # Registers as the global TracerProvider
)
# All OTel spans created after this call are exported to VeriProof

`configure_veriproof`

Sets up a TracerProvider with a VeriproofSpanExporter and optionally registers it as the global OTel provider.


def configure_veriproof(
    options: VeriproofClientOptions,
    service_name: str,
    set_global: bool = False,
    existing_provider: TracerProvider | None = None,
) -> tuple[TracerProvider, VeriproofSpanExporter]:

Parameter	Type	Description
`options`	`VeriproofClientOptions`	SDK configuration (see below)
`service_name`	`str`	OTel service name attribute on all spans
`set_global`	`bool`	If `True`, calls `opentelemetry.trace.set_tracer_provider()`
`existing_provider`	`TracerProvider \| None`	Attach to an existing provider instead of creating one

Returns (TracerProvider, VeriproofSpanExporter).

`VeriproofClientOptions`


VeriproofClientOptions(
    # ── Required (or via environment variables) ─────────────────
    api_key: str | None = None,
        # Sent as the X-API-Key header. Falls back to VERIPROOF_API_KEY env var.
    application_id: str | None = None,
        # Logical name registered in the portal. Falls back to VERIPROOF_APPLICATION_ID.
 
    # ── Network ─────────────────────────────────────────────────
    endpoint: str = "https://api.veriproof.app",
        # Ingest API base URL. Override for Enterprise Federated deployments.
        # Falls back to VERIPROOF_ENDPOINT env var.
    http_timeout_seconds: float = 30.0,
    allow_insecure_endpoint: bool = False,
        # Must be True to allow http:// endpoints (disabled by default).
    headers: Mapping[str, str] = {},
        # Extra headers merged into every outbound request.
    api_key_provider: Callable[[], str] | None = None,
        # Called at request time to retrieve the API key. Use for dynamic rotation.
 
    # ── Circuit breaker ─────────────────────────────────────────
    circuit_breaker_failure_threshold: int = 3,
        # Consecutive failures to open the circuit.
    circuit_breaker_reset_timeout_seconds: float = 30.0,
        # Seconds the circuit stays open before entering half-open.
 
    # ── Buffer ──────────────────────────────────────────────────
    buffer_capacity: int = 500,
        # Max payloads buffered while the circuit is open. Oldest dropped when full.
 
    # ── Content capture ─────────────────────────────────────────
    enable_content_capture: bool = False,
        # Capture gen_ai.* message fields and retrieval documents in exported spans.
        # Keep False (default) for GDPR compliance and data minimization.
    content_capture_size_threshold_bytes: int = 65_536,
        # Max byte length of a single content field before truncation.
    max_document_content_bytes: int = 4_096,
        # Max byte length of a captured retrieval document.
    redacted_attributes: tuple[str, ...] = (),
        # OTel attribute keys to redact. Supports prefix.* glob.
        # Example: ("gen_ai.input_messages",)
 
    # ── Defaults ────────────────────────────────────────────────
    default_transaction_type: str | None = None,
        # Applied to sessions that do not call .with_transaction_type().
)

Standard options object:


opts = VeriproofClientOptions(
    api_key="vp_cust_acme.akv7f4a2b3c9x.3xQr9pLm8N2vT4wK",
    application_id="my-app",
)

There is no separate sandbox-specific Python client helper. The shared sandbox in the Customer Portal is a read-only viewing mode, not a separate SDK credential type.

`VeriproofSession`

Fluent session builder. Wraps a logical AI transaction with governance context.


import os
from veriproof_sdk import (
    VeriproofClient, VeriproofClientOptions, VeriproofSession,
    StartSessionOptions, SessionIntent,
)
 
client = VeriproofClient(
    VeriproofClientOptions(
        api_key=os.environ["VERIPROOF_API_KEY"],
        application_id="my-app",
    )
)
 
session = VeriproofSession(
    client,
    "my-session",
    StartSessionOptions(session_id="session-001", transaction_type="credit_review"),
)
 
async with session:
    session.set_session_intent(SessionIntent.APPLICATION)
    # ... add steps, chat turns, decision ...

Methods

Method	Description
`set_session_intent(intent: SessionIntent)`	Set the session-level intent (use `SessionIntent` enum values)
`with_transaction_type(type: str)`	Classify the transaction type
`add_step(name, data, tags=None)`	Add a discrete step; `data` is `str`, `bytes`, or `AddStepData`
`add_chat_turn(user_message, assistant_response, model=None)`	Log an LLM prompt/response pair
`set_decision(context)`	Attach a structured decision record (`str` or `DecisionContext`)
`set_outcome(outcome: SessionOutcome)`	Record the session outcome
`set_risk_level(level: RiskLevel)`	Set the aggregate risk level
`with_metadata(key, value)`	Attach a key-value attribute to the most recent step
`with_session_metadata(metadata: SessionMetadata)`	Attach structured session metadata
`with_tags(*tags: str)`	Add free-form string tags to the session
`complete()`	Submit the session trace synchronously (also available as `complete_async()`)

`DecisionContext`


# Options decision (recommended for compliance evidence)
# Positional args: question, options, chosen, reasoning (optional), confidence (optional)
ctx = DecisionContext.with_options(
    "Loan approval",
    ["approve", "deny", "manual_review"],
    "approve",
    "Credit score 718 exceeds minimum 680 threshold.",
    0.91,
)
 
# Simple decision
ctx = DecisionContext.simple(
    "Credit risk assessment",
    "approve",
    "All eligibility criteria satisfied.",
)

`StepTags`

Pre-defined tag sets that classify step types for compliance dashboards:

Tag method	Purpose
`StepTags.retrieval()`	Data retrieval (RAG, database lookup, API call)
`StepTags.llm_call(model)`	LLM generation step
`StepTags.tool_call(tool_name)`	Tool or function call
`StepTags.agent_delegation()`	Agent routing or sub-agent delegation
`StepTags.user_interaction()`	Human-in-the-loop interaction
`StepTags.decision()`	Decision point step
`StepTags.planning()`	Agentic task decomposition or planning

Enums

Enum	Values
`RiskLevel`	`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`
`SessionOutcome`	`SUCCESS`, `FAILURE`, `ESCALATED`, `CANCELLED`, `PARTIAL`, `ERROR`, `CONDITIONAL_APPROVAL`, `UNKNOWN`
`SessionIntent`	`APPLICATION`, `TRANSACTION`, `REVIEW`, `INQUIRY`, `VERIFICATION`, `ONBOARDING`, `SUPPORT`, `ADVISORY`, `REPORTING`, `MONITORING`

Industry vertical enums

Industry-specific enum types live in per-vertical submodules. Import the module for the vertical you are instrumenting:


from veriproof_sdk.verticals import banking_financial_services as bfs
 
span.set_attribute(bfs.PaymentStatusISO20022.__otel_attribute__, bfs.PaymentStatusISO20022.ACTC.value)

Every class exposes __otel_attribute__, __opa_policy_path__, __rego_input_key__, and __permitted_values__ as class attributes. Because these are StrEnum subclasses, members compare and serialise directly as strings — .value is only needed when you want the bare string explicitly. The full list of vertical module names mirrors the catalog filenames in the industry enum reference.

Merkle utilities

The SDK exposes the same Merkle functions used internally for transport verification:


from veriproof_sdk import compute_merkle_root_hex, generate_proof, verify_proof
 
leaves = [
    '{"step": "retrieve", "score": 735}',
    '{"step": "evaluate", "passed": True}',
    '{"decision": "approve", "confidence": 0.91}',
]
 
root  = compute_merkle_root_hex(leaves)           # SHA-256 root
proof = generate_proof(leaves, index=2)           # Merkle proof path for leaf[2]
 
assert verify_proof(proof, leaf=leaves[2], root=root)

These utilities are useful for independently verifying the integrity of exported compliance records against the root stored in your Solana CMT.

`VeriproofSpanExporter`

Low-level span exporter — used if you need to attach VeriProof to an existing OTel provider without calling configure_veriproof.


from veriproof_sdk import VeriproofSpanExporter, VeriproofClientOptions
from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
exporter = VeriproofSpanExporter(
    VeriproofClientOptions(api_key="vp_cust_...", application_id="my-app")
)
existing_provider.add_span_processor(BatchSpanProcessor(exporter))

Transport reliability

The exporter uses a per-endpoint circuit breaker. If the ingest API returns 3 consecutive errors or connection failures:

The circuit opens — spans are buffered locally instead of exported.
After 30 seconds (configurable), the circuit enters half-open and retries one request.
On success, the circuit closes and buffered spans are flushed.

The in-memory buffer holds up to 500 payloads (configurable via buffer_capacity). When the buffer is full, oldest payloads are dropped. For critical workloads requiring zero payload loss, use the Enterprise Federated deployment with a local relay.

FAQ

Can I use the SDK alongside my existing OTel setup?

Yes. Use existing_provider to attach VeriProof as an additional exporter. Your existing traces continue flowing to their current backends.

Does the SDK work in async and sync code?

Yes. VeriproofSession supports both async with session: and with session: usage patterns.

How do I test that spans are being exported?

Set the OTEL_LOG_LEVEL=debug environment variable, or configure standard Python logging for the veriproof_sdk logger:


import logging
logging.getLogger("veriproof_sdk").setLevel(logging.DEBUG)

Each batch sent to the ingest API will appear in the debug log with its Merkle root and span count.

Next steps

SDK Annotations (Python) — @trace_operation decorator reference
Framework Adapters — LangGraph — auto-instrumentation for LangGraph
Examples — Python — runnable code for all supported frameworks