Metadata-Version: 2.4
Name: veritera
Version: 0.2.1
Summary: Forge Verify SDK — Verify AI agent decisions with cryptographic attestation
Author-email: Veritera AI <engineering@veritera.ai>
License: MIT
Project-URL: Homepage, https://veritera.ai
Project-URL: Documentation, https://veritera.ai/docs
Project-URL: Repository, https://github.com/VeriteraAI/veritera-website
Keywords: veritera,forge,forge-verify,ai,verification,agent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: cryptography>=41.0.0

# forge-verify

Forge Verify SDK for Python. Verify AI agent decisions with cryptographic attestation.

## Install

```bash
pip install forge-verify
```

## Quick Start

```python
from forge_verify import ForgeVerify

forge = ForgeVerify(api_key="vt_live_...")

result = await forge.verify_decision(
    agent_id="agent-1",
    action="payment.create",
    params={"amount": 100, "currency": "USD"},
    policy="finance-controls",
)

if result.verified:
    # Action approved
    pass
else:
    print("Blocked:", result.reason)
```

### Synchronous Usage

```python
from forge_verify import ForgeVerify

forge = ForgeVerify(api_key="vt_live_...")
result = forge.verify_sync("send_email", params={"to": "user@example.com"}, policy="email-controls")
```

`verify_sync()` works in plain scripts, running asyncio event loops, FastAPI contexts, and Jupyter notebooks.

## API

### `ForgeVerify(api_key, **options)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | `str` | *required* | API key (`vt_live_...`, `vt_sandbox_...`) |
| `base_url` | `str` | `https://veritera.ai` | API base URL |
| `timeout` | `float` | `10.0` | Request timeout (seconds) |
| `max_retries` | `int` | `2` | Retries on 5xx errors |
| `fail_closed` | `bool` | `True` | Return denied instead of raising on errors |
| `debug` | `bool` | `False` | Enable debug logging |

Aliases: `Forge`, `Veritera` (backward compatibility)

### Methods

- `verify_decision(agent_id, action, ...)` — Verify an agent action against policy
- `get_proof(proof_id)` — Retrieve a verification proof
- `verify_proof_locally(attestation, payload, public_key)` — Verify attestation offline (Ed25519)
- `create_delegation(agent_id, allowed_actions, ...)` — Create a scoped agent delegation
- `get_usage(period=None)` — Get billing usage stats
- `health()` — Check API health

### Error Handling

```python
from forge_verify import ForgeError, RateLimitError

try:
    result = await forge.verify_decision(...)
except RateLimitError as e:
    # Wait e.retry_after_ms before retrying
    pass
except ForgeError as e:
    print(e.code, e.status, str(e))
```

### Fail-Closed (Default)

When `fail_closed=True` (default), network/server errors return a denied result instead of raising. The agent is blocked, not crashed.

### Circuit Breaker

After 5 consecutive failures, the SDK opens a circuit breaker for 30 seconds. After 30s, one request is allowed through (half-open). On success, the circuit closes.

### Idempotency

Pass `idempotency_key` to `verify_decision()` to prevent duplicate processing:

```python
result = await forge.verify_decision(
    agent_id="agent-1",
    action="payment.create",
    idempotency_key="unique-request-id",
)
```

## Migrating from veritera

```bash
pip uninstall veritera
pip install forge-verify
```

Update imports:
```python
# Before
from veritera import Veritera
# After (Veritera still works as alias)
from forge_verify import ForgeVerify
```

## Requirements

- Python >= 3.9
- Dependencies: `httpx`, `cryptography`

## Links

- [Docs](https://veritera.ai/docs)
- [API Reference](https://veritera.ai/docs/api)
