Metadata-Version: 2.4
Name: veratum
Version: 2.4.0
Summary: Litigation-grade evidence infrastructure for EU AI Act compliance
Home-page: https://github.com/veratum/sdk-python
Author: Ali Ashkir
Author-email: Ali Ashkir <ali@veratum.ai>
License: MIT
Project-URL: Homepage, https://veratum.ai
Project-URL: Documentation, https://docs.veratum.ai
Project-URL: Repository, https://github.com/veratum/sdk-python
Project-URL: Bug Tracker, https://github.com/veratum/sdk-python/issues
Keywords: audit,AI,accountability,transparency,compliance,evidence,blockchain,xrpl
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
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 :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: opentimestamps-client>=0.7.0
Provides-Extra: zk
Requires-Dist: ezkl>=15.0.0; extra == "zk"
Provides-Extra: litellm
Requires-Dist: litellm>=1.0; extra == "litellm"
Provides-Extra: portkey
Requires-Dist: portkey-ai>=1.0; extra == "portkey"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: ezkl>=15.0.0; extra == "all"
Requires-Dist: litellm>=1.0; extra == "all"
Requires-Dist: portkey-ai>=1.0; extra == "all"
Requires-Dist: mcp>=1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# Veratum SDK for Python

Production-grade SDK for AI auditability and accountability, with full compliance to Article 12 of the EU AI Act and ISO 24970 standards.

## Overview

The Veratum SDK provides seamless integration with AI model providers (starting with Anthropic) to capture, audit, and verify all interactions. Each interaction generates a cryptographically-signed receipt with full chain integrity, enabling transparent and accountable AI systems.

**Key Features:**
- Transparent prompt/response capture
- Automatic receipt generation with chain integrity
- Article 12 & ISO 24970 compliance fields
- Secure hash chain linking
- Blockchain-ready architecture
- Zero-friction client wrapping

## Installation

```bash
pip install veratum-sdk
```

## Quick Start

### Basic Usage with Anthropic

```python
from veratum import VeratumSDK
import anthropic

# Initialize Veratum SDK
sdk = VeratumSDK(
    endpoint="https://api.veratum.ai/v1",
    api_key="vsk_your_api_key_here",
    vertical="hiring"
)

# Create Anthropic client
client = anthropic.Anthropic(api_key="sk_your_key_here")

# Wrap the client - all calls are now audited
wrapped_client = sdk.wrap(client)

# Use as normal - receipts generated automatically
response = wrapped_client.messages.create(
    model="claude-3-opus-20250219",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "What are the key responsibilities of a product manager?"
        }
    ]
)

print(response.content[0].text)

# Cleanup
sdk.close()
```

### Context Manager Usage

```python
from veratum import VeratumSDK
import anthropic

with VeratumSDK(
    endpoint="https://api.veratum.ai/v1",
    api_key="vsk_...",
    vertical="hiring"
) as sdk:
    client = anthropic.Anthropic(api_key="sk_...")
    wrapped_client = sdk.wrap(client)

    response = wrapped_client.messages.create(
        model="claude-3-opus-20250219",
        messages=[{"role": "user", "content": "Hello"}]
    )
```

## How It Works

### 1. Transparent Interception

The SDK monkey-patches the client's `messages.create()` method to intercept all API calls without requiring code changes:

```python
# The wrapper is transparent - code works identically
response = wrapped_client.messages.create(...)  # Receipt generated automatically
```

### 2. Receipt Generation

For each interaction, the SDK generates a receipt containing:

**Core Fields:**
- `schema_version`: Receipt schema version
- `entry_hash`: SHA256 hash of canonical receipt JSON
- `prev_hash`: Link to previous receipt (chain integrity)
- `sequence_no`: Monotonically increasing sequence number
- `timestamp`: UTC ISO 8601 timestamp

**Interaction Data:**
- `prompt_hash`: SHA256 of input prompt
- `response_hash`: SHA256 of model response
- `model`: Model identifier used
- `provider`: Provider name (e.g., "anthropic")
- `tokens_in`: Input tokens consumed
- `tokens_out`: Output tokens generated

**Article 12 & ISO 24970 Compliance:**
- `decision_type`: Classification of decision
- `vertical`: Industry vertical (hiring, lending, content_moderation, etc.)
- `ai_score`: Model confidence/prediction score
- `ai_threshold`: Decision threshold
- `recruiter_action`: Action taken by human reviewer
- `human_review_state`: Status of human review
- `reviewer_id`: ID of human reviewer
- `override_reason`: Reason for any manual override

**Blockchain Integration:**
- `xrpl_tx_hash`: XRPL transaction hash (populated by backend)
- `signature`: Digital signature (populated by backend)

### 3. Chain Integrity

Receipts form a cryptographic hash chain:

- **Genesis Receipt**: `prev_hash = "0"*64`, `sequence_no = 0`
- **Each Receipt**: `prev_hash` points to previous receipt's `entry_hash`
- **Verification**: Each receipt can be verified to ensure:
  - Correct entry_hash computation
  - Proper linkage to previous receipt
  - No tampering or reordering

### 4. Automatic Upload

Each receipt is immediately uploaded to the Veratum endpoint for:
- Secure storage
- Blockchain recording (via XRPL)
- Chain verification
- Compliance auditing

## Architecture

### Core Classes

#### `VeratumSDK`
Main SDK class for initialization and client wrapping.

```python
sdk = VeratumSDK(
    endpoint="https://api.veratum.ai/v1",  # Veratum endpoint
    api_key="vsk_...",                      # Your API key
    vertical="hiring",                      # Industry classification
    timeout=30.0                            # Request timeout
)

# Wrap any compatible client
wrapped = sdk.wrap(client)

# Get current chain state
state = sdk.get_chain_state()
# {"sequence_no": 5, "prev_hash": "abc123..."}

# Reset chain (dev/testing only)
sdk.reset_chain()

# Cleanup resources
sdk.close()
```

#### `Receipt`
Generates audit receipts with full compliance.

```python
from veratum import Receipt, HashChain

chain = HashChain()
receipt_gen = Receipt(chain)

receipt = receipt_gen.generate(
    prompt="What is the capital of France?",
    response="The capital of France is Paris.",
    model="claude-3-opus-20250219",
    provider="anthropic",
    tokens_in=12,
    tokens_out=8,
    decision_type="informational",
    vertical="hiring",
    ai_score=0.95,
    ai_threshold=0.8
)
```

#### `HashChain`
Manages cryptographic chain integrity.

```python
from veratum import HashChain

chain = HashChain()

# Compute entry hash (excludes entry_hash, xrpl_tx_hash, signature)
entry_hash = chain.compute_entry_hash(receipt_dict)

# Advance chain
chain.advance_chain(receipt_dict)

# Get state
state = chain.get_chain_state()
# {"sequence_no": 1, "prev_hash": "abc123..."}
```

## Configuration

### Environment Variables

You can configure via environment variables:

```bash
export VERATUM_ENDPOINT="https://api.veratum.ai/v1"
export VERATUM_API_KEY="vsk_..."
export VERATUM_VERTICAL="hiring"
```

Then initialize with minimal config:

```python
from veratum import VeratumSDK
import os

sdk = VeratumSDK(
    endpoint=os.getenv("VERATUM_ENDPOINT"),
    api_key=os.getenv("VERATUM_API_KEY"),
    vertical=os.getenv("VERATUM_VERTICAL", "hiring")
)
```

### Vertical Classifications

Supported industry verticals:
- `hiring`: Recruitment and hiring decisions
- `lending`: Loan and credit decisions
- `content_moderation`: Content review and moderation
- `ad_delivery`: Advertisement targeting
- `healthcare`: Medical decision support
- `general`: General-purpose applications

## Compliance

### Article 12 - EU AI Act

The SDK automatically captures and documents:
- Training data used
- Testing and validation results
- Performance metrics
- Human oversight procedures
- Decision documentation

### ISO 24970 - AI Auditability

Receipts include:
- Complete audit trail with timestamps
- Cryptographic integrity verification
- Immutable record linkage
- Provider identification
- Model identification
- Decision reasoning information

## Error Handling

The SDK is designed to be resilient:

```python
# Receipt failures don't break the application
try:
    response = wrapped_client.messages.create(...)
except Exception as e:
    # Application continues even if receipt upload fails
    print(f"API call succeeded, but receipt upload may have failed: {e}")
```

## Performance Considerations

- **Transparent**: No latency added to API calls
- **Asynchronous Upload**: Receipts uploaded in background
- **Timeout Handling**: 30-second default timeout for receipt uploads
- **Error Recovery**: Failed uploads logged but don't block responses

## Testing

```bash
# Install dev dependencies
pip install veratum-sdk[dev]

# Run tests
pytest

# Check types
mypy veratum/

# Format code
black veratum/

# Lint
ruff check veratum/
```

## Security

- All communication uses HTTPS with Bearer token authentication
- Prompts and responses are hashed (SHA256), not stored
- Signatures use cryptographic signing (provided by backend)
- Chain integrity prevents tampering
- No sensitive data in logs

## Support

For issues, questions, or feedback:
- Documentation: https://docs.veratum.ai
- Email: team@veratum.ai
- GitHub: https://github.com/veratum/sdk-python

## License

MIT License - See LICENSE file for details
