veratum 2.1.0

Litigation-grade evidence infrastructure for EU AI Act compliance

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

pip install veratum-sdk

Quick Start

Basic Usage with Anthropic

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

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:

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

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.

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.

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:

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

Then initialize with minimal config:

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:

# 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

# 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: [e-mail]
• GitHub: https://github.com/veratum/sdk-python

License

MIT License - See LICENSE file for details