veracity-connect 0.2.1

Send an AI workflow's run evidence to Veracity for verification.

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/*