kaironull

Python SDK for the KairoNull Umbra Trust Protocol — capture AI decision events to a hash-chained, RFC3161-anchored evidence ledger, and verify records independently.

Install

pip install kaironull

Quickstart

from kaironull import KairoNull

client = KairoNull(api_key="utp_live_...")  # get a key at kaironull.com/get-access

result = client.record(
    pipeline_id="credit-decisioning",
    entry_type="flag",            # "pass" | "flag" | "block" | "escalate"
    stage_slug="risk-review",
    summary="Application flagged for manual review: DTI ratio 0.61 exceeds threshold",
    trust_score=0.42,
    model_version="risk-model-v3.2",
)

print(result.entry_hash)   # sha256 hex — share this with an auditor
print(result.chain_height) # position in your org's evidence chain

Verify a record (no API key needed)

from kaironull import KairoNull

client = KairoNull()  # public methods don't require a key
verified = client.verify("95be8bb5253668bb898da34631cc3c9e...")

if verified.found:
    print(verified.record["summary"])
    print("Anchored:", verified.anchor.anchored)

Anyone can verify a hash — auditors don't need credentials, an account, or access to your systems. This is also what powers the public widget at kaironull.com/#verify.

Check chain health

status = client.chain_status()
print(status.chain_height, status.healthy)

Same data backing kaironull.com/status.

Export an evidence bundle

bundle = client.export_report(from_="2026-06-01T00:00:00Z", to="2026-07-01T00:00:00Z")
# bundle["entries"], bundle["anchor"] — hand this to an auditor or regulator

Revoke your key

client.revoke_key(key_id="...")  # the key used to auth this call is what's revoked

Error handling

from kaironull import AuthenticationError, ValidationError, APIError

try:
    client.record(...)
except ValidationError as e:
    # bad input — fix the call
    ...
except AuthenticationError as e:
    # missing/invalid/revoked key
    ...
except APIError as e:
    # anything else — e.status_code has the HTTP status
    ...

Context manager

with KairoNull(api_key="...") as client:
    client.record(...)
# session closed automatically

Links

• Full API reference / quickstart
• Get an API key
• Docs

Status

This SDK covers the full public API surface: record, verify, chain_status, export_report, revoke_key. It is a thin wrapper — every method maps directly to one REST call, so behaviour matches the quickstart examples exactly.