Skip to main content

veracity-connect-python

veracity-connect sends an AI workflow's run evidence to Veracity for verification.

This is the standalone Python SDK package for Veracity Connect.

Install

After the package is published to PyPI:

pip install veracity-connect

For optional integrations:

pip install "veracity-connect[langchain]"
pip install "veracity-connect[otel]"

If you need the current unreleased main branch:

pip install "veracity-connect @ git+https://github.com/nardosstem/veracity-connect-python.git@main"

Quick Start

This is a reference example for a common SQL-backed workflow. The SDK is not limited to this shape: create a VeracityRun, attach the evidence your workflow used, record the tool calls your workflow executed, set the artifact your workflow produced, and send the run to Veracity.

from veracity_connect import NativeArtifactBuilder, VeracityClient, VeracityRun, query_ref

client = VeracityClient(
    base_url="https://app.veracity.example",
    pairing_token="vrc_...",
)

run = VeracityRun(
    agent_name="acme-finance-agent",
    framework="langgraph",
    source_snapshot_attestation="attested",
)
run.attach_source("financials.csv", alias="financials")
run.record_sql(
    "SELECT SUM(revenue) AS total_revenue FROM financials",
    output={"columns": ["total_revenue"], "rows": [[240000]]},
    alias="revenue_totals",
)
artifact = (
    NativeArtifactBuilder()
    .text("Total revenue was ")
    .ref(query_ref("revenue_totals", 0, "total_revenue"), "$240,000")
    .text(".")
    .build(source_aliases=run.source_aliases())
)
run.set_artifact(native=artifact)
receipt = client.send(run, prompt="Summarize revenue.")

You can also load connection settings from the environment:

export VERACITY_BASE_URL="https://app.veracity.example"
export VERACITY_PAIRING_TOKEN="vrc_..."
from veracity_connect import VeracityClient

client = VeracityClient.from_env()

What To Record

attach_source(...) accepts source files or inline content. CSV sources are sent as text; Excel, SQLite, and DuckDB files are sent as encoded file content.

record_sql(...) records SQL tool calls and their outputs for replay/verification. If your workflow is already instrumented, the optional OpenTelemetry and LangChain integrations can collect supported tool calls for you. record_tool_call(...) is generic and can carry non-SQL tool calls too; the connector preserves them in the envelope for provenance/native-hint context even when Veracity's replay path is currently SQL-authoritative.

set_artifact(...) records the final output Veracity should check, either as rendered text, an Excel workbook, or both.

source_snapshot_attestation="attested" is a top-level run property. Use it only when the submitted source snapshot is the exact source Veracity controlled or can honestly attest as the workflow's release-relevant input. Otherwise leave it as the default unattested.

Optional integrations:

  • veracity_connect.langchain.VeracityCallbackHandler preserves LangChain/LangGraph tool calls in the envelope and upgrades SQL query calls into replayable record_sql(...) entries when possible.
  • veracity_connect.otel.VeracitySpanProcessor does the same for OpenTelemetry execute_tool spans, while still treating backend replay as the authority on what becomes verified proof.

Native Citation Hints

When your workflow can expose its own evidence refs, emit them from the connector/workflow layer rather than teaching the agent to write Veracity-specific strings itself.

  • raw source reads: source.<source_alias>[row].<column>
  • derived outputs: rows.<output_alias>[row].<column>

The helper API keeps those refs stable:

from veracity_connect import NativeArtifactBuilder, output_ref, source_ref

builder = NativeArtifactBuilder()
builder.text("Q3 source revenue was ")
builder.ref(source_ref("financials", 0, "revenue"), "$120,000")
builder.text("; rounded output was ")
builder.ref(output_ref("python_postprocess", 0, "rounded_total"), "$120,000")
artifact = builder.build(source_aliases=run.source_aliases())
run.set_artifact(native=artifact)

These hints are additive only. Veracity still replays authoritative tool calls and treats imported native hints as evidence, not trust by themselves.

For less manual wiring:

builder = run.artifact_builder()
builder.text("Q3 revenue was ")
builder.ref(source_ref("financials", 0, "revenue"), "$120,000")
run.set_native_artifact(builder, artifact_kind="prose_report")

Python Computed Outputs

When a derived value comes from a replayable Python step rather than SQL, use record_python_script(...) instead of hand-building the python_script tool payload:

run.record_python_script(
    script=\"\"\"
import json, sqlite3, sys
conn = sqlite3.connect(sys.argv[1])
value = conn.execute("SELECT SUM(revenue) FROM income WHERE quarter = 'Q3'").fetchone()[0]
print(json.dumps({"columns": ["total_revenue"], "rows": [{"total_revenue": value}]}))
\"\"\",
    output={"columns": ["total_revenue"], "rows": [{"total_revenue": 115000}]},
    alias="computed_metrics",
)

Forward-Compatible Flags

If the backend adds new top-level ingest flags before the SDK gets a dedicated setter, you can pass them explicitly with set_envelope_fields(...):

run.set_envelope_fields(example_future_flag="value")

Example-Agent Pattern

Keep the agent logic framework-native and inject Veracity-specific aliases/citations in the wrapper that packages the run:

def invoke_agent(inputs) -> dict:
    return agent.invoke(inputs)


def build_veracity_run(agent_result: dict) -> VeracityRun:
    run = VeracityRun(agent_name="acme-finance-agent", framework="langgraph")
    run.attach_source("financials.csv", alias="financials")
    run.record_sql(agent_result["sql"], output=agent_result["rows"], alias="revenue_totals")
    run.set_artifact(native=build_native_artifact(run, agent_result))
    return run

For a fuller mixed SQL + non-SQL example, see examples/mixed_tool_workflow.py.

Envelope Contract

The SDK sends an Agent-Run Evidence Envelope to POST /workspace/api/agent-runs/ingest with the pairing token in the X-Veracity-Pairing-Token header. The token is never serialized into the JSON payload.

payload = run.to_dict()
payload_json = run.to_json()
restored = VeracityRun.from_dict(payload)

Supported source types are csv, excel, sqlite, and duckdb. JSON sources are rejected until backend replay support exists.

Development

python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
python -m pytest
python -m build
python -m twine check dist/*

Metadata

Release files for veracity-connect 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for veracity-connect 0.2.1
File Size Uploaded Provenance Actions
veracity_connect-0.2.1.tar.gz 23.6 kB Without provenance Details for veracity_connect-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for veracity-connect 0.2.1
File Interpreter ABI Platform Actions
veracity_connect-0.2.1-py3-none-any.whl Python 3 none any Details for veracity_connect-0.2.1-py3-none-any.whl

Total release size: 43.0 kB

Release files / veracity_connect-0.2.1.tar.gz

Download URL veracity_connect-0.2.1.tar.gz
Size 23.6 kB
Tags Source
SHA-256 checksum
How to use checksums
3538ee20119f08a20e44d4058b54d231ce335529f9d70e46f824db0e3520439e
BLAKE2b-256 checksum
How to use checksums
284ef4a0c7919b9efd9fde80db9a7ac2f2108011c523ff3e48f4412ea608cd60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.5

Release files / veracity_connect-0.2.1-py3-none-any.whl

Download URL veracity_connect-0.2.1-py3-none-any.whl
Size 19.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ecb39a5ac89fb70ae5ce5f7203ba0196c4822f4ae8e0ccd41e664996ca8b02f6
BLAKE2b-256 checksum
How to use checksums
ca7a8937b535f4cdfbf001be7aa77e09b50bd6a6986d6d12f5d529a81184ab1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.5

Security for veracity-connect 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page