💡

Quick overview

SDK Instrumentation

SDK Instrumentation explains how to configure the VeriProof SDK beyond the Quick Start defaults — enabling enrichments, tuning performance, and integrating with your existing observability stack.

Enrichment configuration: Enrichments are optional modules that add signal to your policy and evidence payloads. Enable them in the VeriProofClient constructor.

Available enrichments: pii-scan, topic-classification, sentiment, content-capture, language-detection, toxicity-score.

Performance tuning:

mode: 'async' — fire-and-forget. Decisions are governed after the response is returned to the user (~0 ms overhead).
mode: 'sync' (default) — policy verdict returned inline (~25–75 ms overhead depending on enrichments).
batchSize — async mode only; controls how many decisions are grouped per API call (default: 50).

Sampling: Set sampleRate: 0.1 to govern only 10% of decisions (useful for very high-throughput systems during initial roll-out).

SDK Instrumentation

Instrumentation is the process of embedding VeriProof session and policy annotations into your AI application’s code. The SDK records each AI decision as a structured session with typed fields such as intent, risk level, decision outcome, guardrail events, and human oversight. This guide explains what to instrument, why each field matters, and how to verify coverage.

Core Concepts

Sessions and Steps

Every interaction with an AI model that VeriProof governs is recorded as a session. A session can contain one or more steps — individual instrumented operations like an LLM call, a tool use, a guardrail evaluation, or a multi-agent delegation.

The minimum viable session is a single step with a decision outcome. Full policy coverage requires annotating the session with the fields described below.

The Policy Annotation Model

VeriProof policy fields are additive. Start with the minimum set, then add richer annotations as your operating model matures. The five policy input dimensions tracked by the Coverage tab are:

Dimension	What to annotate	Framework relevance
Intent	The classified purpose of this AI interaction	EU AI Act Article 9 risk classification; ISO 42001 A.6.2
Grounding	Whether the model output is grounded in retrieved facts	EU AI Act Article 13 transparency; NIST AI RMF Measure
Human oversight	Whether a human reviewed or could review this decision	EU AI Act Article 14; ISO 42001 Annex A.10.3
Content safety	Whether content safety was evaluated	SOC 2 CC7; HIPAA Technical Safeguards
Outcome	The eventual business result of the AI decision	ISO 42001 A.9.2 performance monitoring

Minimum Required Annotations

At minimum, every session should record:

Application ID — set in SDK configuration
Decision — a descriptive label or structured DecisionContext passed to set_decision() / setDecision()
Risk level — your assessment of the risk level: LOW, MEDIUM, HIGH, or CRITICAL

Without these three fields, the session is recorded but contributes limited policy evidence.

Python


import os
from veriproof_sdk import (
    VeriproofClient, VeriproofClientOptions, VeriproofSession,
    SessionOutcome, RiskLevel,
)
 
client = VeriproofClient(
    VeriproofClientOptions(
        api_key=os.environ["VERIPROOF_API_KEY"],
        application_id="loan-assistant",
    )
)
 
with VeriproofSession(client, "loan-session") as session:
    # ... your AI logic ...
    session.set_decision("approve")        # free-form label or DecisionContext
    session.set_risk_level(RiskLevel.LOW)
    session.set_outcome(SessionOutcome.SUCCESS)

TypeScript


import { VeriproofClient, VeriproofSdkOptions, RiskLevel, SessionOutcome } from '@veriproof/sdk-core';
 
// client is created once at app startup
const client = new VeriproofClient(
  VeriproofSdkOptions.createDevelopment({
    apiKey: process.env.VERIPROOF_API_KEY!,
    applicationId: 'loan-assistant',
  }),
);
 
const session = client.startSession('loan-session');
// ... your AI logic ...
session.setDecision('approve');            // free-form label or DecisionContext
session.setRiskLevel(RiskLevel.Low);
await session.complete(SessionOutcome.Success);

.NET


// Set governance attributes on the current Activity span
Activity.Current?
    .SetDecisionType(DecisionType.Approval)
    .SetRiskLevel(RiskLevel.Low)
    .SetSessionOutcome(SessionOutcome.success);

Adding Intent Classification

The intent label categorizes why this AI interaction is happening. Use labels from the Vocabulary Browser for consistent classification:

Python


session.set_session_intent(SessionIntent.REVIEW)

TypeScript


session.setSessionIntent(SessionIntent.Review);

.NET


Activity.Current?.SetSessionIntent(SessionIntent.review);

Annotating Human Oversight

For regulated decisions where a human reviewed the AI output, record the review as a session step using StepTags.review() with the appropriate HumanOversightType:

Python


from veriproof_sdk import HumanOversightType, StepTags
 
session.add_step(
    "human_review",
    "Reviewer approved the AI recommendation.",
    StepTags.review().with_human_oversight(HumanOversightType.APPROVAL_GRANTED),
)

TypeScript


import { HumanOversightType, StepTags } from '@veriproof/sdk-core';
 
session.addStep(
  'human_review',
  'Reviewer approved the AI recommendation.',
  StepTags.review().withHumanOversight(HumanOversightType.ApprovalGranted),
);

.NET


// Record the review step on its own Activity span
using var reviewStep = tracer.StartActivity("ai.step.review");
reviewStep?
    .SetStepType(StepType.review)
    .SetHumanOversight(HumanOversightType.ApprovalGranted);

Recording Business Outcomes

Outcomes connect the AI decision to its eventual real-world result. Set the session outcome and, when a quality assessment is available, attach an outcome rating:

Python


from veriproof_sdk import SessionOutcome, OutcomeRating
 
# Set the outcome during the session
session.set_outcome(SessionOutcome.SUCCESS)
 
# Optionally add a quality rating once the result is known
session.set_outcome_rating(
    OutcomeRating.GOOD,
    note="Loan repaid on schedule within first quarter.",
)

TypeScript


import { SessionOutcome, OutcomeRating } from '@veriproof/sdk-core';
 
// Set the outcome during the session
session.setOutcome(SessionOutcome.Success);
 
// Optionally add a quality rating
session.setOutcomeRating(OutcomeRating.Good, {
  note: 'Loan repaid on schedule within first quarter.',
});

.NET


// Set on the session Activity span
Activity.Current?
    .SetSessionOutcome(SessionOutcome.success);

Verifying Coverage

After deploying instrumented code, verify coverage in the portal:

Navigate to Applications → [your application] → Coverage.
Review the coverage tier for each of the five policy input dimensions.
Any dimension showing below Adequate (< 60%) warrants improvement before production usage under a regulated framework.

The Coverage tab shows which specific annotation types are missing and links to the relevant instrumentation section in this guide.

Build a custom SDK adapter for a framework not covered by the built-in adapters.

Adapter Authoring

Comparison of instrumentation capabilities across Python, TypeScript, and .NET SDKs.

SDK Feature Matrix

Monitor annotation coverage for each policy input dimension in the portal.

Application Coverage

Debug missing sessions, annotation errors, and export failures.

SDK Troubleshooting