Metadata-Version: 2.4
Name: veracity-connect
Version: 0.1.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 you
want verified, set the artifact your workflow produced, and send the run to Veracity.

```python
from veracity_connect import VeracityClient, VeracityRun

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")
run.record_sql("SELECT SUM(revenue) AS total_revenue FROM financials", output=[{"total_revenue": 240000}])
run.set_artifact(rendered="Total revenue was $240,000.")
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.

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

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