Metadata-Version: 2.4
Name: veritera
Version: 0.3.0
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/forge-python
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 SDK for Python

[![PyPI](https://img.shields.io/pypi/v/veritera)](https://pypi.org/project/veritera/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

Verify every AI agent action before execution. Cryptographic attestation. Sub-millisecond latency. Zero data access.

## Install

```bash
pip install veritera
```

## Complete Flow: Zero to Verified in 60 Seconds

```python
from veritera import Forge

forge = Forge(api_key="vt_live_...")  # Get your key at veritera.ai

# 1. Create a policy (do this once)
policy = forge.create_policy_sync(
    name="finance-controls",
    description="Block high-value transactions and dangerous operations",
    rules=[
        {"type": "action_whitelist", "params": {"allowed": ["payment.read", "payment.create", "balance.check"]}},
        {"type": "amount_limit", "params": {"max": 10000, "currency": "USD"}},
        {"type": "action_blacklist", "params": {"blocked": ["database.drop", "admin.override"]}},
    ],
)
print(f"Policy created: {policy.name} (ID: {policy.id})")

# 2. Verify an action
result = forge.verify_sync(
    action="payment.create",
    agent_id="finance-bot",
    params={"amount": 500, "currency": "USD", "recipient": "vendor@acme.com"},
    policy="finance-controls",
)

if result.verified:
    print(f"Approved — proof: {result.proof_id}")
    # Safe to execute the action
else:
    print(f"Blocked — reason: {result.reason}")
    # Do NOT execute

# 3. List your policies
for p in forge.list_policies_sync():
    print(f"  {p.name} (v{p.version}) — {len(p.rules)} rules")

# 4. Test a policy without executing
test = forge.test_policy_sync(
    policy_id=policy.id,
    action="database.drop",
    params={"table": "users"},
)
print(f"Test: {test.verdict}")  # "denied"
```

That's it. No GUI needed. No dashboard required. Everything from code.

## Async Usage

```python
import asyncio
from veritera import Forge

async def main():
    async with Forge(api_key="vt_live_...") as forge:
        policy = await forge.create_policy(
            name="email-controls",
            rules=[{"type": "rate_limit", "params": {"max_per_hour": 50}}],
        )

        result = await forge.verify_decision(
            agent_id="support-bot",
            action="send_email",
            params={"to": "customer@example.com", "subject": "Your refund"},
            policy="email-controls",
        )
        print("Approved" if result.verified else f"Blocked: {result.reason}")

asyncio.run(main())
```

## Generate Policies from Natural Language

Don't want to write JSON rules? Describe what you want in plain English:

```python
result = forge.generate_policy_sync(
    "Only allow my agent to read files, send emails (max 50 per hour), "
    "and check balances. Block all deletions and admin operations.",
    save=True,  # save it immediately
)
print(f"Created: {result['name']}")
print(f"Rules: {result['rules']}")
```

## Use with Framework Integrations

The policy you create here works with all Forge framework packages:

```python
# Create the policy once
forge.create_policy_sync("finance-controls", rules=[...])

# Then use it in any framework:
# OpenAI Agents SDK:  forge_protect(tools, policy="finance-controls")
# LangGraph:          ForgeVerifyMiddleware(policy="finance-controls")
# CrewAI:             ForgeVerifyTool(policy="finance-controls")
# LlamaIndex:         ForgeVerifyToolSpec(policy="finance-controls")
```

| Package | Install |
|---------|---------|
| [forge-openai](https://github.com/VeriteraAI/forge-openai) | `pip install forge-openai` |
| [langchain-forge](https://github.com/VeriteraAI/forge-langchain) | `pip install langchain-forge` |
| [crewai-forge](https://github.com/VeriteraAI/forge-crewai) | `pip install crewai-forge` |
| [llama-index-tools-forge](https://github.com/VeriteraAI/forge-llamaindex) | `pip install llama-index-tools-forge` |

## API Reference

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

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | `str` | *required* | Your API key (`vt_live_...` or `vt_test_...`) |
| `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 |

### Verification

| Method | Description |
|--------|-------------|
| `verify_decision(agent_id, action, params, policy)` | Verify an action (async) |
| `verify_sync(action, agent_id, params, policy)` | Verify an action (sync) |
| `get_proof(proof_id)` | Retrieve a verification proof |
| `verify_proof_locally(attestation, payload, public_key)` | Verify Ed25519 attestation offline |

### Policies

| Method | Description |
|--------|-------------|
| `create_policy(name, rules, description)` | Create a new policy (async) |
| `create_policy_sync(name, rules, description)` | Create a new policy (sync) |
| `list_policies()` / `list_policies_sync()` | List all active policies |
| `get_policy(policy_id)` / `get_policy_sync(policy_id)` | Get a policy by ID |
| `update_policy(policy_id, name, rules, description)` / `update_policy_sync(...)` | Update a policy |
| `delete_policy(policy_id)` / `delete_policy_sync(policy_id)` | Deactivate a policy |
| `test_policy(policy_id, action, params)` / `test_policy_sync(...)` | Test a policy without persisting |
| `generate_policy(prompt, save)` / `generate_policy_sync(...)` | Generate policy from natural language |
| `get_policy_templates()` | Get all available policy templates |

### Policy Rule Types

| Type | Description | Params |
|------|-------------|--------|
| `action_whitelist` | Only allow specific actions | `{"allowed": ["action1", "action2"]}` |
| `action_blacklist` | Block specific actions | `{"blocked": ["action1", "action2"]}` |
| `amount_limit` | Cap transaction amounts | `{"max": 10000, "currency": "USD"}` |
| `rate_limit` | Limit action frequency | `{"max_per_hour": 50}` |
| `time_window` | Restrict to business hours | `{"start": "09:00", "end": "17:00", "timezone": "US/Eastern"}` |
| `require_confirmation` | Flag for human approval | `{"actions": ["payment.create"]}` |
| `recipient_constraint` | Control who agent can contact | `{"allowed_domains": ["@company.com"]}` |
| `resource_access` | Restrict file/resource access | `{"denied_resources": [".env*", "*.key"]}` |
| `custom` | Custom constraint logic | `{...}` |

### Delegations

| Method | Description |
|--------|-------------|
| `create_delegation(agent_id, allowed_actions, constraints, expires_in)` | Create a scoped delegation |

### Account

| Method | Description |
|--------|-------------|
| `get_usage(period)` | Get billing usage statistics |
| `health()` | Check API health |

## Error Handling

```python
from veritera import ForgeError, RateLimitError

try:
    result = await forge.verify_decision(...)
except RateLimitError as e:
    print(f"Rate limited — retry in {e.retry_after_ms}ms")
except ForgeError as e:
    print(f"Error: {e.code} ({e.status}): {e}")
```

### Fail-Closed (Default)

When `fail_closed=True`, network/server errors return a denied result instead of raising. Your agent is blocked, not crashed. This is the safe default.

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

## Requirements

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

## Get Your API Key

1. Go to [veritera.ai](https://veritera.ai)
2. Sign up (free tier: 250 verifications)
3. Copy your API key from the dashboard
4. Set it: `export VERITERA_API_KEY=vt_live_...`

## License

MIT — Forge by [Veritera AI](https://veritera.ai)
