Veriproof.Sdk.Annotations

Veriproof.Sdk.Annotations provides typed Activity extension methods that add VeriProof governance attributes to any OTel span, along with the enums, model records, and event-name constants used across the entire .NET SDK.

Compatibility: .NET 10+, System.Diagnostics.Activity (no OpenTelemetry SDK dependency required at call sites)

Installation


dotnet add package Veriproof.Sdk.Annotations

Quick example


using System.Diagnostics;
using Veriproof.Sdk.Annotations;
using Veriproof.Sdk.Annotations.Models;
 
var tracer = new ActivitySource("my-ai-app");
 
using var session = tracer.StartActivity("ai.session");
session?
    .SetSessionIntent(SessionIntent.transaction)
    .SetTransactionId("loan-app:LA-2026-1042")
    .SetDataSensitivity(DataSensitivity.Confidential);
 
using var step = tracer.StartActivity("ai.step.assess");
step?
    .SetStepType(StepType.llm_call)
    .SetAiSystem("openai")
    .SetAiModel("gpt-4.1")
    .SetTokenUsage(inputTokens: 312, outputTokens: 148)
    .SetGroundingStatus(GroundingStatus.grounded)
    .SetRiskLevel(RiskLevel.Low)
    .SetStepOutcome(StepOutcome.success);

Session-level attributes


Activity SetSessionIntent(SessionIntent intent)
Activity SetDecisionType(DecisionType type)
Activity SetSessionOutcome(SessionOutcome outcome)
Activity SetTransactionType(string transactionType)
Activity SetTransactionId(string transactionId)
Activity SetDataSensitivity(DataSensitivity sensitivity)
Activity SetDataFormat(DataFormat format)

Per-step governance


Activity SetStepOutcome(StepOutcome outcome)
Activity SetStepType(StepType stepType)
Activity SetGuardrailAction(GuardrailAction action)
Activity SetHumanOversight(HumanOversightType oversight)
Activity SetContentSafetyFlags(ContentSafetyFlag flags)   // [Flags] — combine with |
Activity SetGroundingStatus(GroundingStatus status)
Activity SetAgentRole(AgentRole role)
Activity SetRiskLevel(RiskLevel level)
Activity AddRiskFactor(RiskFactor factor)
Activity AddRiskFactors(IEnumerable<RiskFactor> factors)

Composite convenience helpers (set multiple related attributes at once):


Activity SetGovernanceClean()
    // → outcome=success, guardrail=passed, safety=clean, oversight=not_applicable
 
Activity SetLlmGovernance(StepOutcome outcome, GroundingStatus grounding, ContentSafetyFlag safety)
Activity SetDecisionGovernance(StepOutcome outcome, HumanOversightType oversight, ContentSafetyFlag safety)
Activity SetAgentGovernance(AgentRole role, StepOutcome outcome)

AI / GenAI attributes


Activity SetAiSystem(string system)        // gen_ai.system
Activity SetAiModel(string model)          // gen_ai.request.model
Activity SetTokenUsage(int inputTokens, int outputTokens)
Activity SetConversationId(string conversationId)
Activity SetProviderName(string providerName)

Decision events


// Records governance attributes AND adds a veriproof.decision span event
Activity SetGovernanceDecision(DecisionContext decision)
 
// Add any named governance event to the span
Activity AddGovernanceEvent(string eventName, GovernanceEventData data)

DecisionContext factory methods:


DecisionContext.Simple("Should we approve?", "APPROVE", reasoning: "Score above threshold")
 
DecisionContext.WithOptions(
    question: "Risk classification",
    options: ["LOW", "MEDIUM", "HIGH"],
    chosen: "MEDIUM",
    reasoning: "DTI 0.34, marginal",
    confidence: 0.82)
 
DecisionContext.WithSources(
    question: "Regulatory check",
    chosen: "PASS",
    sources: ["sanctions-list", "pep-database"])

Content capture (opt-in)

Content capture must be enabled in VeriproofExporterOptions.EnableContentCapture = true. Only enable this if your data handling policies permit sending prompt/completion content to VeriProof, where it is AES-256-GCM encrypted at rest.


// OTel GenAI JSON format
Activity SetUserPrompt(string text)
Activity SetAssistantResponse(string text, string? finishReason = "stop")
Activity SetSystemInstructions(string content)
Activity SetInputMessages(IReadOnlyList<GenAiMessage> messages)
Activity SetOutputMessages(IReadOnlyList<GenAiMessage> messages)
 
// OpenInference flattened format (dual-format — use alongside OTel versions)
Activity SetLlmInputMessages(IReadOnlyList<GenAiMessage> messages)
Activity SetLlmOutputMessages(IReadOnlyList<GenAiMessage> messages)
 
// Tool calls
Activity SetToolCallArguments(string toolCallId, string name, string? argsJson)
Activity SetToolCallResult(string toolCallId, string result)
 
// RAG documents
Activity SetRetrievedDocuments(IReadOnlyList<OiDocument> documents, int maxContentBytes = 4096)

Privacy & compliance attributes


Activity SetVeriproofRedactionPolicy(string policy)
Activity SetVeriproofDataSubject(Guid dataSubjectId)
Activity SetVeriproofComplianceStandard(string standard)  // "gdpr" | "ccpa" | "hipaa"

Enums reference

Enum	Values
`SessionIntent`	`inquiry` `application` `transaction` `dispute` `review` `onboarding` `verification` `support` `advisory` `reporting` `monitoring`
`SessionOutcome`	`unknown` `success` `failure` `escalated` `cancelled` `partial`
`StepType`	`unknown` `llm_call` `tool_call` `retrieval` `decision` `user_interaction` `validation` `output` `error` `agent_delegation`
`StepOutcome`	`success` `failed` `skipped` `blocked` `timeout` `rate_limited` `refused` `fallback_used` `cached` `human_override` `partial`
`GuardrailAction`	`none` `passed` `warned` `modified` `blocked` `escalated` `retry_requested`
`ContentSafetyFlag`	`clean`(0) `pii_detected`(1) `toxicity_detected`(2) `hallucination_suspected`(4) `off_topic`(8) `prompt_injection_detected`(16) `jailbreak_attempted`(32) `bias_detected`(64) `confidential_leak`(128) `copyright_concern`(256)
`GroundingStatus`	`not_applicable` `grounded` `partially_grounded` `ungrounded` `grounding_failed`
`HumanOversightType`	`none` `approval_required` `approval_granted` `approval_denied` `review_completed` `override_applied` `escalated`
`AgentRole`	`primary` `orchestrator` `specialist` `validator` `reviewer` `router` `summarizer` `safety_checker` `tool_executor`
`DecisionType`	`none` `approval` `denial` `conditional_approval` `referral` `escalation` `deferral` `recommendation` `classification` `calculation`
`RiskLevel` / `RiskSeverity`	`Low` `Medium` `High` `Critical`

`RiskFactor` factory methods


RiskFactor.PiiDetected(int stepNumber, string fieldName)
RiskFactor.LowConfidence(double confidence, double threshold = 0.75)
RiskFactor.DurationAnomaly(int stepNumber, long durationMs, long expectedMs)
RiskFactor.PolicyViolation(string policyName, string detail)
 
// Manual:
new RiskFactor(
    Category: "credit-risk",
    Description: "DTI above preferred threshold",
    Severity: RiskSeverity.Medium,
    StepNumber: 2)

Next steps

Veriproof.Sdk.Core reference — OTel setup, VeriproofExporterOptions, transport config
Semantic Kernel instrumentation — automatic function/prompt span capture
AutoGen instrumentation — agent run and message span capture
Governance Session Builder example (.NET) — full worked example