Metadata-Version: 2.4
Name: truthvouch
Version: 0.1.0
Summary: TruthVouch Governance SDK — embed AI governance into your agent frameworks
Project-URL: Homepage, https://truthvouch.ai
Project-URL: Documentation, https://docs.truthvouch.ai/sdk
Project-URL: Repository, https://github.com/truthvouch/sdk
Author-email: TruthVouch <sdk@truthvouch.ai>
License: Proprietary
Keywords: agent,ai,governance,hallucination,llm,safety
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.25
Provides-Extra: crewai
Requires-Dist: crewai>=0.40; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Description-Content-Type: text/markdown

# TruthVouch Governance SDK

Embed AI governance into your agent frameworks with a single pip install.

## Installation

```bash
pip install truthvouch
```

For framework integrations:

```bash
pip install "truthvouch[langgraph]"   # LangGraph / LangChain
pip install "truthvouch[crewai]"      # CrewAI
```

## Quickstart

```python
import truthvouch

# Synchronous usage
client = truthvouch.TruthVouchClient(api_key="vt_live_...")

result = client.evaluate_input("My SSN is 123-45-6789", model="gpt-4o")
if result.blocked:
    print("Blocked:", result.block_reasons)
elif result.flagged:
    print("Flagged:", result.flag_reasons)

llm_response = call_your_llm(prompt)
output_result = client.evaluate_output(llm_response, model="gpt-4o")

client.shutdown()
```

### Context manager

```python
with truthvouch.TruthVouchClient(api_key="vt_live_...") as client:
    result = client.evaluate_input("Hello!", model="gpt-4o")
```

### Async usage

```python
async with truthvouch.AsyncTruthVouchClient(api_key="vt_live_...") as client:
    result = await client.evaluate_input("Hello!", model="gpt-4o")
    output_result = await client.evaluate_output(llm_response, model="gpt-4o")
```

## Framework Adapters

### LangGraph / LangChain

```python
from truthvouch.adapters.langgraph import TruthVouchCallbackHandler

handler = TruthVouchCallbackHandler(client, model="gpt-4o")
result = chain.invoke(inputs, config={"callbacks": [handler]})
```

### CrewAI

```python
from truthvouch.adapters.crewai import TruthVouchMiddleware
from langchain_openai import ChatOpenAI
from crewai import Agent

middleware = TruthVouchMiddleware(client)
llm = middleware.wrap_llm(ChatOpenAI(model="gpt-4o"))
agent = Agent(llm=llm, role="Analyst", goal="...", backstory="...")
```

## EvaluationResult

```python
result.blocked         # bool — True if any guard returned BLOCK
result.flagged         # bool — True if any guard returned FLAG (no block)
result.block_reasons   # list[str] — human-readable block messages
result.flag_reasons    # list[str] — human-readable flag messages
result.guard_results   # list[GuardResult] — per-guard details
result.total_duration_ms  # float — total evaluation time in ms
```

## Built-in Guards

| Guard | Type | Description |
|---|---|---|
| `pii_regex` | Local | Regex PII detection (SSN, CC, email, phone, passport, address) |
| `banned_phrases` | Local | Case-insensitive banned phrase matching |
| `injection` | Local | 2-layer prompt injection heuristic detector |
| `cost` | Local | Token estimation + budget enforcement |
| `truth` | Remote | Truth nugget verification (requires truth_scan_enabled) |
| `pii_remote` | Remote | Full Presidio PII scan (requires pii_remote_enabled) |

## Degraded Mode

If the SDK cannot reach the TruthVouch API at startup, it operates in
**degraded mode**: local guards still run, remote guards are skipped, and
telemetry is disabled. Your application will not be blocked by infrastructure
issues.
