veratum 2.1.0__tar.gz

veratum-2.1.0/INTEGRATION_EXAMPLE.md

@@ -0,0 +1,236 @@
+# Veratum SDK Integration Examples
+
+## Basic Integration 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_anthropic_key")
+
+# 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": "Evaluate this candidate profile..."
+        }
+    ]
+)
+
+# Response is returned transparently
+print(response.content[0].text)
+
+# Cleanup
+sdk.close()
+```
+
+## Context Manager Pattern (Recommended)
+
+```python
+from veratum import VeratumSDK
+import anthropic
+
+with VeratumSDK(
+    endpoint="https://api.veratum.ai/v1",
+    api_key="vsk_your_api_key_here",
+    vertical="hiring"
+) as sdk:
+    client = anthropic.Anthropic(api_key="sk_your_key")
+    wrapped_client = sdk.wrap(client)
+
+    response = wrapped_client.messages.create(
+        model="claude-3-opus-20250219",
+        messages=[{"role": "user", "content": "Hello"}]
+    )
+
+# SDK automatically cleaned up
+```
+
+## Multiple Clients
+
+```python
+from veratum import VeratumSDK
+import anthropic
+
+sdk = VeratumSDK(
+    endpoint="https://api.veratum.ai/v1",
+    api_key="vsk_your_api_key_here",
+    vertical="hiring"
+)
+
+# Wrap multiple clients with same SDK
+client1 = anthropic.Anthropic(api_key="sk_key1")
+client2 = anthropic.Anthropic(api_key="sk_key2")
+
+wrapped1 = sdk.wrap(client1)
+wrapped2 = sdk.wrap(client2)
+
+# All calls from both clients are audited
+response1 = wrapped1.messages.create(
+    model="claude-3-opus-20250219",
+    messages=[{"role": "user", "content": "Request 1"}]
+)
+
+response2 = wrapped2.messages.create(
+    model="claude-3-opus-20250219",
+    messages=[{"role": "user", "content": "Request 2"}]
+)
+```
+
+## Checking Chain State
+
+```python
+from veratum import VeratumSDK
+import anthropic
+
+sdk = VeratumSDK(
+    endpoint="https://api.veratum.ai/v1",
+    api_key="vsk_your_api_key_here"
+)
+
+client = anthropic.Anthropic(api_key="sk_...")
+wrapped = sdk.wrap(client)
+
+# Make some calls
+for i in range(3):
+    wrapped.messages.create(
+        model="claude-3-opus-20250219",
+        messages=[{"role": "user", "content": f"Message {i}"}]
+    )
+
+# Check chain integrity
+state = sdk.get_chain_state()
+print(f"Sequence number: {state['sequence_no']}")  # 3
+print(f"Previous hash: {state['prev_hash']}")      # Last entry_hash
+```
+
+## Error Handling
+
+```python
+from veratum import VeratumSDK
+import anthropic
+
+sdk = VeratumSDK(
+    endpoint="https://api.veratum.ai/v1",
+    api_key="vsk_your_api_key_here"
+)
+
+client = anthropic.Anthropic(api_key="sk_...")
+wrapped = sdk.wrap(client)
+
+try:
+    response = wrapped.messages.create(
+        model="claude-3-opus-20250219",
+        messages=[{"role": "user", "content": "Test"}]
+    )
+    print("Response received and receipt uploaded")
+except Exception as e:
+    # API call error - receipt may or may not have been created
+    print(f"Error: {e}")
+finally:
+    sdk.close()
+```
+
+## Environment Variables
+
+```bash
+# Set environment variables
+export VERATUM_ENDPOINT="https://api.veratum.ai/v1"
+export VERATUM_API_KEY="vsk_your_api_key"
+export VERATUM_VERTICAL="hiring"
+```
+
+```python
+import os
+from veratum import VeratumSDK
+import anthropic
+
+# Load from environment
+sdk = VeratumSDK(
+    endpoint=os.getenv("VERATUM_ENDPOINT"),
+    api_key=os.getenv("VERATUM_API_KEY"),
+    vertical=os.getenv("VERATUM_VERTICAL", "hiring")
+)
+
+client = anthropic.Anthropic()
+wrapped = sdk.wrap(client)
+```
+
+## Receipt Upload Details
+
+When you call the wrapped client:
+
+1. **Prompt Captured**: The input message is hashed (SHA256)
+2. **API Called**: Original API call proceeds normally
+3. **Response Captured**: Response text is hashed (SHA256)
+4. **Receipt Generated**: Includes all Article 12 & ISO 24970 fields
+5. **Chain Integrity**: Links to previous receipt via hash chain
+6. **Upload**: Receipt posted to Veratum endpoint
+7. **Return**: Original response returned transparently
+
+All of this happens automatically without modifying your code!
+
+## Vertical Classifications
+
+Choose the appropriate vertical for your use case:
+
+```python
+# Hiring/recruitment decisions
+sdk = VeratumSDK(..., vertical="hiring")
+
+# Lending/credit decisions
+sdk = VeratumSDK(..., vertical="lending")
+
+# Content moderation
+sdk = VeratumSDK(..., vertical="content_moderation")
+
+# Advertising/ad delivery
+sdk = VeratumSDK(..., vertical="ad_delivery")
+
+# Healthcare
+sdk = VeratumSDK(..., vertical="healthcare")
+
+# General purpose
+sdk = VeratumSDK(..., vertical="general")
+```
+
+## Zero-Code Integration
+
+The beauty of the Veratum SDK is that it requires zero changes to existing code:
+
+```python
+# Before: Regular Anthropic client
+client = anthropic.Anthropic(api_key="sk_...")
+response = client.messages.create(
+    model="claude-3-opus-20250219",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+# After: Just add 3 lines
+from veratum import VeratumSDK
+
+sdk = VeratumSDK(endpoint="...", api_key="...")
+client = anthropic.Anthropic(api_key="sk_...")
+client = sdk.wrap(client)  # ← Add this one line!
+
+response = client.messages.create(
+    model="claude-3-opus-20250219",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+# Everything else stays the same!
+```

veratum-2.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include INTEGRATION_EXAMPLE.md
+recursive-include veratum *.py
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *$py.class

veratum-2.1.0/PKG-INFO

@@ -0,0 +1,380 @@
+Metadata-Version: 2.4
+Name: veratum
+Version: 2.1.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
+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