Metadata-Version: 2.4
Name: veracity-connect
Version: 0.2.0
Summary: Send an AI workflow's run evidence to Veracity for verification.
Author: Veracity
License-Expression: MIT
Project-URL: Homepage, https://github.com/nardosstem/veracity-connect-python
Project-URL: Repository, https://github.com/nardosstem/veracity-connect-python
Project-URL: Issues, https://github.com/nardosstem/veracity-connect-python/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: langchain
Requires-Dist: langchain-core; extra == "langchain"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk; extra == "otel"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# 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:

```bash
pip install veracity-connect
```

For optional integrations:

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

If you need the current unreleased `main` branch:

```bash
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.

```python
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",
)
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:

```bash
export VERACITY_BASE_URL="https://app.veracity.example"
export VERACITY_PAIRING_TOKEN="vrc_..."
```

```python
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.

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:

```python
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.

## Example-Agent Pattern

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

```python
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`](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.

```python
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

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