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.VeracityCallbackHandlerpreserves LangChain/LangGraph tool calls in the envelope and upgrades SQL query calls into replayablerecord_sql(...)entries when possible.veracity_connect.otel.VeracitySpanProcessordoes the same for OpenTelemetryexecute_toolspans, 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.