Python SDK

Use veriproof-sdk for application-owned actions. Add the Enforce adapter for each framework your application uses.

Govern one action

In the customer portal, open Tools and SDKs. Select your language and adapters, then follow the installation instructions shown there.

VeriProof SDKs are distributed through customer-gated GitLab packages, not public registries. See SDK access for workstation and CI guidance.

VeriProof packages used here: veriproof-sdk, veriproof-sdk-adapter-agent-framework.

Store the application SDK key as VERIPROOF_API_KEY, then create one client:

import asyncio
 
from veriproof_sdk import GovernedActionContext, Veriproof
 
 
async def pay_claim(context: GovernedActionContext) -> dict:
    # Your business logic. It runs only when policy allows the action.
    return {"paymentId": "PAY-1", "claimId": context.input["claim_id"]}
 
 
async def main() -> None:
    claim = {"claim_id": "CLM-4417", "amount": 1250}
 
    vp = Veriproof.from_env()
    try:
        result = await vp.govern(
            "claims.pay",
            claim,
            pay_claim,
            facts={"claim_amount": claim["amount"]},
        )
    finally:
        await vp.shutdown()
 
    if result.completed:
        print(result.value)
    else:
        print(result.status.value, result.reason_code, result.message)
 
 
asyncio.run(main())

govern is async, so call it from async code. shutdown() sends any evidence the SDK kept during an outage, then closes the client. It raises if some evidence couldn’t be delivered. async with Veriproof.from_env() as vp: also closes the client, but doesn’t send kept evidence.

Each govern() call records its own session. The SDK creates a new session ID for every call unless you pass session_id=, and a session ID you pass must not be reused. To connect the steps of one conversation, pass the same session_context=SessionContext(external_reference="...") on each call. Each step stays a separate session, and the portal shows the shared reference on each one.

The core SDK checks the input before it calls pay_claim. It checks output before release through the typed result.value boundary.

Only completed, completed_with_warning, and transformed carry a released value. When policy stops the action the status is blocked, which the portal shows as Stopped by policy. A stopped input never calls the protected action, and a stopped output never reaches the caller. Never release a value from a blocked result. Use result.status, result.message, result.reason_code, and result.evidence_reference to handle results without a value.

result carries no top-level decision ID. Read it from result.decision.decision_id, which is set when a rule decided the outcome, and read the session from result.session_id. See Rate a session result for every status.

Handle a stop

Pass the governed action context into child work. Call context.throw_if_stopped() immediately before each protected side effect.

A live Stop directive applies only to its matching run or application. The SDK signals the action before it acknowledges the directive. It does not terminate the Python process. Reconcile the side effect when the result reports uncertain completion.

Add industry values

Generated values add the canonical policy field and evidence attribute with one .fact() call. Use facts for application-specific rule data.

from veriproof_sdk.verticals.insurance import PolicyLifecycleStatus
 
industry = PolicyLifecycleStatus.in_force.fact()

The active field contract checks required fields, types, and allowed values before protected work begins.

Derive facts once

When every call carries the same kind of facts, register a fact extractor on the client instead of building facts at each call site. It receives the action name, input, session and invocation IDs, the adapter name, the tool name when an adapter governs a tool call, and any run_metadata you pass:

from veriproof_sdk import FactExtractionContext, Veriproof
 
 
def facts_from_call(context: FactExtractionContext):
    if context.tool_name == "send_payment":
        return {"payment_amount": context.input["amount"]}
    return None
 
 
vp = Veriproof.from_env(fact_extractor=facts_from_call)

Facts you pass to govern(facts=...) win over extracted facts with the same name. Extracted facts go through the same sanitization and field-contract checks as facts you pass yourself, and they’re saved in review checkpoints. A resumed review uses those saved facts without calling the extractor again.

If the extractor raises or returns something other than a JSON object, the call ends with failed and reason code fact_extraction_failed. The action doesn’t run. run_metadata only reaches the extractor; the SDK never sends it to VeriProof.

Add human review

When a rule sends an action for review, pass review=GovernReviewOptions(...) so VeriProof can build the reviewer’s request. Before your first review, check that:

• an active review profile exists in the portal, and you pass its key as GovernReviewOptions(profile=...);
• human review is turned on for your organization in Settings > Human review and escalation;
• an Administrator has granted the application key Human review access on the application’s Config > Keys tab; and
• the application has a public HTTPS callback URL registered. VeriProof doesn’t deliver outcomes to private or local addresses.

from veriproof_sdk import GovernReviewOptions
 
# Inside main(), in place of the earlier govern call:
result = await vp.govern(
    "claims.pay",
    claim,
    pay_claim,
    facts={"claim_amount": claim["amount"]},
    review=GovernReviewOptions(
        profile="claims-review",
        proposed_action_summary="Review the proposed claim payment.",
    ),
)

A missing profile fails with review_profile_not_found. A key without human review access fails with permission_denied. Neither runs the action.

Continue after human review

Save every review_required checkpoint in a protected workflow store. Verify signed callback bytes before parsing the response. A worker can then call the review runtime with the saved checkpoint and a rebuilt protected callback.

The runtime checks each callback against the signing keys VeriProof publishes at your endpoint. If your host can’t reach VeriProof, pass webhook_keys=PinnedWebhookKeySet(key_set_json) to reviews(). To check review event webhooks, use verify_webhook with the key set, your whsec_ subscription secret, or both.

Core Human Review uses a 12-field bounded brief and a response and resume-mode matrix. route_to_revision starts application-owned revision work and never runs the superseded payload. Private-note content remains in VeriProof and is excluded from the callback.

The hosted Server Ingest path is the default. Set the Edge endpoint option when your tenant has a licensed Edge Gateway.

See Core Human Review for the lifecycle contract and the runnable Python receiver guide for callback hosting.

Framework adapters

Add the Enforce adapter for each framework your application uses. Checks names the operation the adapter controls. Put the core SDK’s governed action around anything under Not covered.

See the package catalog and Python release notes.