Python SDK

Das offizielle Python-SDK kavra-siegel-client bietet einen asynchronen Client für alle Siegel-Operationen.

Installation

pip install "kavra-siegel-client @ git+https://github.com/mscharfetter/kavra-shared.git@v0.1.0-siegel#subdirectory=py-siegel"

Abhängigkeiten

Das SDK benötigt httpx und pydantic (v2). Beide werden automatisch installiert.

Quickstart

import asyncio
from kavra_siegel import SiegelClient, StampTier

async def main():
    client = SiegelClient(
        base_url="https://siegel.kavra.cloud",
        service_token="sk_your_token_here",
    )

    # 1. Hash stempeln
    token = await client.stamp_hash(
        sha256_hex="a1b2c3d4" * 8,  # 64-char hex
        tier=StampTier.BASIC,
        metadata={"source": "my-app", "document": "contract-42"},
    )
    print(f"Token-ID:      {token.token_id}")
    print(f"Qualifiziert:  {token.is_qualified}")
    print(f"Verify-URL:    {token.verify_url}")

    # 2. Content stempeln (bytes werden client-seitig gehasht)
    content = b"Vertragsentwurf v3 - finale Version"
    token2 = await client.stamp_content(
        content=content,
        tier=StampTier.PLUS,
    )
    print(f"Content-Hash:  {token2.content_sha256}")

    # 3. Stempel verifizieren (kein Auth nötig)
    result = await client.verify_token(token.token_id)
    print(f"Gültig:        {result.valid}")
    print(f"TSP-Provider:  {result.tsp_provider}")

    # 4. Health-Check
    health = await client.health()
    print(f"Status:        {health.status}")
    print(f"Qualifiziert:  {health.is_qualified}")

asyncio.run(main())

Tiers

Tier	Beschreibung	Content-Upload
basic	Nur Hash wird gestempelt	Nein
plus	Hash + Verify-URL	Nein
sealed	Vollständiger Inhalt serverseitig gespeichert	Ja (Base64)

Fehlerbehandlung

from kavra_siegel import (
    SiegelAuthError,
    SiegelValidationError,
    SiegelUnavailableError,
)

try:
    token = await client.stamp_hash("invalid")
except SiegelAuthError:
    print("Token ungültig oder fehlend")
except SiegelValidationError as e:
    print(f"Validierungsfehler: {e}")
except SiegelUnavailableError:
    print("Service nicht erreichbar")

Exported API

Symbol	Typ	Beschreibung
SiegelClient	Class	Async HTTP-Client
StampTier	Enum	BASIC, PLUS, SEALED
StampToken	Model	Antwort von /stamp
VerificationResult	Model	Antwort von /verify
HealthResponse	Model	Antwort von /health
SiegelError	Exception	Basis-Exception
SiegelAuthError	Exception	401 Unauthorized
SiegelValidationError	Exception	422 Validation Error
SiegelUnavailableError	Exception	Timeout / 5xx

Mock-TSP

Aktuell liefert der Service is_qualified=False. Qualifizierte Stempel folgen nach TSP-Vertragsabschluss (geplant Q4 2026). Das SDK loggt eine Warnung, wenn ein Stempel nicht qualifiziert ist.