Skip to content
TruthVouch Docs

PydanticAI Integration

Add hallucination detection, content verification, and execution tracing to any PydanticAI agent using the TruthVouch Trust API.

Installation

Terminal window
pip install pydantic-ai-truthvouch

Requires Python 3.9+ and pydantic-ai >= 1.0.0.

Quick Start

Instrumentor (OpenTelemetry tracing)

import os
os.environ["TRUTHVOUCH_API_KEY"] = "your-api-key"


from pydantic_ai import Agent
from truthvouch_pydanticai import setup_instrumentor


# One-line global setup
setup_instrumentor()


agent = Agent("openai:gpt-4o", instrument=True)
result = agent.run_sync("What is the capital of France?")
print(result.data)

Output Validator

import os
os.environ["TRUTHVOUCH_API_KEY"] = "your-api-key"


from pydantic_ai import Agent
from truthvouch_pydanticai import TruthVouchOutputValidator, EnforcementMode


validator = TruthVouchOutputValidator(
    threshold=0.85,
    enforcement=EnforcementMode.RETRY,
)


agent = Agent("openai:gpt-4o", output_type=str)


@agent.output_validator
async def check_trust(ctx, output):
    return await validator(ctx, output)


result = await agent.run("Tell me about the Eiffel Tower.")
print(validator.last_result.trust_score)

Components

TrustApiClient

Low-level async/sync client for the Trust API verify and traces endpoints:

from truthvouch_pydanticai import TrustApiClient


client = TrustApiClient(
    api_key="your-api-key",           # or set TRUTHVOUCH_API_KEY env var
    base_url="http://localhost:5000/api/v1/trust",   # default (verify)
    traces_url="http://localhost:5004/api/v1/trust", # default (traces)
)


result = client.verify_sync("Paris is the capital of France.", mode="standard")
print(result.trust_score)  # 0.97

TruthVouchInstrumentor

Registers as an OpenTelemetry SpanExporter that receives completed PydanticAI agent spans and forwards them to TruthVouch for observability and audit logging:

from truthvouch_pydanticai import TruthVouchInstrumentor


instrumentor = TruthVouchInstrumentor(
    api_key="your-api-key",
    include_content=False,  # strip prompt/completion text for privacy
)


instrumentor.instrument()          # instrument all agents globally
instrumentor.instrument_agent(a)   # or a single agent

TruthVouchOutputValidator

Callable class that verifies agent outputs and enforces configurable trust thresholds. Compatible with PydanticAI’s @agent.output_validator decorator:

from truthvouch_pydanticai import TruthVouchOutputValidator, EnforcementMode


validator = TruthVouchOutputValidator(
    threshold=0.8,
    enforcement=EnforcementMode.RETRY,  # or LOG, BLOCK
)


@agent.output_validator
async def check_trust(ctx, output):
    return await validator(ctx, output)

Configuration

ParameterEnvironment VariableDefault
api_keyTRUTHVOUCH_API_KEY(required)
base_url—http://localhost:5000/api/v1/trust
traces_url—http://localhost:5004/api/v1/trust
threshold—0.8
mode—spot_check
enforcement—LOG
include_content—True

Enforcement Modes

ModeBehaviour
RETRYRaises ModelRetry — the LLM regenerates with feedback on failed claims.
LOGLogs a warning and returns output unchanged (monitoring without blocking).
BLOCKRaises TrustThresholdError with trust_score, threshold, and full result.

Streaming Support

When ctx.partial_output is True (streaming partial result), verification is skipped and the output is returned immediately. Only the final complete output is verified.

Fail-Open Behaviour

If TruthVouch is unreachable (network error, timeout, 5xx), the validator logs a warning and returns the output unchanged. The integration never becomes a single point of failure.

License

Apache-2.0

Next Steps