Metadata-Version: 2.4
Name: trustflow
Version: 1.0.0
Summary: TrustFlow Python SDK — Governance-as-a-Service for AI agent transactions
Author-email: TrustFlow <hello@trust-flow.dev>
License: MIT
Project-URL: Homepage, https://trust-flow.dev
Project-URL: Documentation, https://trust-flow.dev/quickstart.html
Project-URL: API Reference, https://api.trust-flow.dev/docs
Project-URL: Repository, https://github.com/jaimemelconlopez-hub/trustflow-saas
Project-URL: Issues, https://github.com/jaimemelconlopez-hub/trustflow-saas/issues
Project-URL: Changelog, https://trust-flow.dev/changelog.html
Keywords: ai,agents,governance,risk,compliance,psd2,fintech
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-httpx; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# TrustFlow Python SDK

**Governance-as-a-Service for AI Agent Transactions**

Evaluate transaction risk, enforce compliance, and trace decisions — in one API call.

[![PyPI](https://img.shields.io/pypi/v/trustflow)](https://pypi.org/project/trustflow/)
[![Python](https://img.shields.io/pypi/pyversions/trustflow)](https://pypi.org/project/trustflow/)

## Install

```bash
pip install trustflow
```

## Quick Start

```python
from trustflow import TrustFlowClient

client = TrustFlowClient(api_key="tf_live_a1b2c3...")

# Evaluate a transaction
result = client.evaluate(
    amount=349.99,
    category="electronics",
    merchant_id="amazon_bot",
    user_id="user_456",
)

print(result.decision)    # "APPROVED"
print(result.risk_score)  # 32.5
print(result.risk_level)  # "MEDIUM"
print(result.trace_id)    # "tf-a8f3c9b12e04"
print(result.factors)     # 7 risk factors with scores and explanations
```

## Features

- **Automatic retry** with exponential backoff
- **Typed responses** — full IDE autocompletion
- **Agent Identity** — sign requests with Ed25519/JWS/HMAC for verified agent transactions
- **Idempotency** — pass `idempotency_key` to prevent duplicate evaluations
- **Sandbox mode** — use `tf_test_` keys for deterministic testing

## Agent Identity Verification

For verified agent transactions (Visa Trusted Agent Protocol, Google AP2, x402):

```python
from trustflow import TrustFlowClient, generate_ed25519_keypair, sign_ed25519

client = TrustFlowClient(api_key="tf_live_...")

# One-time: generate a keypair and register the public key with TrustFlow
priv_b64, pub_b64 = generate_ed25519_keypair()
# POST /v1/identity/issuers with pub_b64 to register your issuer

# Per-transaction: sign the canonical payload
identity = sign_ed25519(
    private_key_b64=priv_b64,
    agent_id="my-shopping-agent-v2",
    issuer="my-company.example.com",
    amount=349.99,
    currency="USD",
    merchant_id="amazon_bot",
    user_id="user_456",
)

result = client.evaluate(
    amount=349.99,
    category="electronics",
    merchant_id="amazon_bot",
    user_id="user_456",
    agent_identity=identity,
)

# Verified agents get lower risk scores
print(result.agent_identity)  # {"status": "verified", "scheme": "ed25519", ...}
```

## Configuration

```python
# Custom base URL
client = TrustFlowClient(
    api_key="tf_live_...",
    base_url="https://your-instance.example.com",
    timeout=10.0,
    max_retries=3,
)
```

## API Reference

Full documentation: [api.trust-flow.dev/docs](https://api.trust-flow.dev/docs)

## Get Your API Key

```bash
curl -X POST https://api.trust-flow.dev/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "Your Name", "email": "you@company.com"}'
```

Free tier: 100 evaluations/hour, 1,000/day. No credit card required.

## License

MIT
