ETH.id Python SDK

Zero-Knowledge Document Verification SDK for Python.

Installation

pip install ethid

Quick Start

from ethid import EthIdClient, LLMProvider

# Initialize client
client = EthIdClient(
    provider=LLMProvider.OPENAI,
    api_key="sk-your-key"
)

# Verify a document
result = client.verify(
    document_path="passport.pdf",
    claim="over 18 years old"
)

print(f"Answer: {result.answer}")
print(f"Confidence: {result.confidence}%")
print(f"Reasoning: {result.reasoning}")

Features

• Zero-Knowledge Verification: Documents never leave your machine
• Privacy-First: Only minimal, claim-relevant data is processed
• Multiple LLM Providers: OpenAI, Claude, Ollama
• Cryptographic Attestations: Tamper-evident proof bundles
• Audit Trail: Complete verification history
• Type-Safe: Full type hints and dataclasses

Usage

Basic Verification

from ethid import EthIdClient

client = EthIdClient()

# Age verification
result = client.verify(
    document_path="id.pdf",
    claim="maior de 18 anos"
)

if result.answer:
    print("Person is over 18")

With Attestation

# Generate cryptographic proof
result = client.verify(
    document_path="id.pdf",
    claim="over 21 years old",
    attest=True
)

# Get attestation bundle
bundle = client.get_attestation(result.session_id)

# Verify integrity
if bundle.verify_integrity():
    print("Attestation is valid")

Offline Mode

# Complete privacy with local LLM
client = EthIdClient(
    provider=LLMProvider.OLLAMA,
    offline=True
)

result = client.verify(
    document_path="document.pdf",
    claim="document is signed"
)

Audit Log

# List all verifications
entries = client.list_audit_log(limit=10)

for entry in entries:
    print(f"{entry.timestamp}: {entry.claim} -> {entry.answer}")

# Get specific entry
entry = client.get_audit_entry(session_id="...")

Privacy Guarantees

What is NEVER Sent

For age verification:

• ❌ Birth date
• ❌ Full name
• ❌ Address
• ✅ Only: "Age calculation result: true"

For CPF verification:

• ❌ Full CPF (123.456.789-00)
• ✅ Only: Masked (123..-00)

API Reference

EthIdClient

class EthIdClient:
    def __init__(
        self,
        cli_path: Optional[str] = None,
        provider: Optional[LLMProvider] = None,
        api_key: Optional[str] = None,
        offline: bool = False,
        debug: bool = False,
    )

Methods

verify()

def verify(
    self,
    document_path: str,
    claim: str,
    provider: Optional[LLMProvider] = None,
    attest: bool = False,
    zk_only: bool = False,
) -> VerificationResult

get_attestation()

def get_attestation(
    self,
    session_id: str,
) -> AttestationBundle

list_audit_log()

def list_audit_log(
    self,
    limit: Optional[int] = None,
    filter_claim: Optional[str] = None,
) -> List[AuditEntry]

configure()

def configure(
    self,
    provider: Optional[LLMProvider] = None,
    api_key: Optional[str] = None,
)

Types

VerificationResult

@dataclass
class VerificationResult:
    session_id: str
    answer: bool
    confidence: float
    reasoning: str
    proof_type: ProofType
    claim: str
    privacy_metadata: PrivacyMetadata
    timestamp: datetime

AttestationBundle

@dataclass
class AttestationBundle:
    session_id: str
    document_hash: str
    claim: str
    result: VerificationResult
    proof_type: ProofType
    bundle_hash: str
    created_at: datetime
    
    def verify_integrity(self) -> bool

Examples

Age Verification

result = client.verify(
    document_path="passport.pdf",
    claim="over 18 years old"
)

print(f"Over 18: {result.answer}")

CPF Verification

result = client.verify(
    document_path="brazilian_id.pdf",
    claim="CPF bate com 123.456.789-00"
)

# Only masked CPF is sent: 123.***.***-00

Income Verification

result = client.verify(
    document_path="income_proof.pdf",
    claim="renda acima de 5000"
)

# Only amount field is sent, no name/CPF

Multiple Providers

# OpenAI
client_openai = EthIdClient(provider=LLMProvider.OPENAI)

# Claude
client_claude = EthIdClient(provider=LLMProvider.CLAUDE)

# Ollama (offline)
client_ollama = EthIdClient(
    provider=LLMProvider.OLLAMA,
    offline=True
)

Error Handling

from ethid import (
    DocumentParsingError,
    ClaimParsingError,
    VerificationError,
)

try:
    result = client.verify(
        document_path="document.pdf",
        claim="over 18 years old"
    )
except DocumentParsingError as e:
    print(f"Failed to parse document: {e}")
except ClaimParsingError as e:
    print(f"Failed to parse claim: {e}")
except VerificationError as e:
    print(f"Verification failed: {e}")

Requirements

• Python 3.8+
• ETH.id CLI installed (cargo install --path .)

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black ethid/

# Type check
mypy ethid/

License

MIT

Links

• Documentation
• GitHub
• Issues