grundnorm 0.1.0

Official SDK for the Grundnorm grounded source-of-law truth layer — resolve a legal norm by open identifier (ELI/ECLI) + date and verify its cryptographic seal locally.

grundnorm (Python SDK)

Resolve a legal norm by its open identifier (ELI/ECLI) and a date, and get back its canonical, sealed meaning as an independently verifiable signed object. The SDK recomputes the content hash and verifies every Ed25519 signature locally — you never have to trust the server.

• Deterministic, zero-LLM read path. Honest not_found instead of a guess.
• Point-in-time: [validFrom, validUntil).
• Python 3.9+. One dependency: cryptography.

Install

pip install grundnorm

Use

from grundnorm import GrundnormClient

# Defaults to the public GDPR demonstrator. For a pilot:
#   GrundnormClient(endpoint="https://.../api/grundnorm/resolve", api_key="nlk_...")
client = GrundnormClient()

r = client.resolve(
    id="http://data.europa.eu/eli/reg/2016/679/art_5",
    jurisdiction="EU",
    at="2026-07-07",   # omit for "today"
)

if r.status == "found":
    print(r.norm["atoms"])          # subject / modality / action / condition / exception / scope + evidence
    print(r.verification["ok"])     # True only if hash recomputes AND all signatures verify

resolve() verifies the seal by default. Skip with verify=False, or verify a stored envelope later:

from grundnorm import verify
v = verify(norm)  # {"ok", "hash_ok", "recomputed_hash", "signatures", "quorum"}

How verification works (no trust required)

1. sha256(canonicalize(norm["canonical"]["content"])) must equal norm["seal"]["contentHash"], where canonicalize = JSON with object keys sorted recursively, no whitespace, hashed as UTF-8.
2. Each seal.signatures[].signatureHex is an Ed25519 signature by that signer's publicKeyHex over the UTF-8 bytes of the seal.contentHash hex string.

Errors

• Nothing sealed for (id, date) → returns NotFound (a normal outcome).
• Bad key, bad input, or server error → raises GrundnormError (.status, .code).

Demonstrator note: the demo corpus (GDPR sample) is signed by demo keys, not institutions, and its accuracy is not yet jurist-graded. See the project's DEMO-TRUTHFULNESS.md.