Python SDK

The official Python client for the AIality Reality Gateway: resolve exact, immutable Reality, inspect its Freshness and Authority basis, and create Reality Locks over the exact state a decision was based on. Available to pilot customers today; not yet published to PyPI.

Status

Official Python SDK 0.1.0 — available to pilot customers. PyPI publication pending. The public method names and model shapes below are the intended long-term shape, exercised against the real Gateway contract — but this is a 0.x release, so expect additive field growth as the Gateway contract itself matures. Distribution is handled as part of pilot onboarding; see Request a pilot.

Quickstart

The real client API — first Reality result in a few lines, no SQL, no internal ids:

from aiality import AIality

client = AIality(api_key="gwk_...")  # from your AIality account

# Discover what's available — no internal ids needed anywhere below.
for entity in client.list_entities():
    print(entity.entity, entity.display_name)

# Resolve Anthropic's current retention Reality.
reality = client.resolve_reality(
    entity="anthropic",
    topic="data-retention",
    scope={"product": "claude_api", "organization_retention_mode": "STANDARD"},
)
print(reality.value)
print(reality.freshness.status)      # "FRESH" | "STALE" | "UNKNOWN"
print(reality.fact_state_version_id)

# Inspect the exact, immutable state this resolution points at.
state = client.get_state(reality.fact_state_version_id)
assert state.value == reality.value  # same id -> byte-identical, forever

Exact state vs. Freshness

Two deliberately separate calls, mirroring the server's own contract exactly: get_state(fsv_id) returns the immutable ExactRealityState — it never changes for a given id. get_freshness(fsv_id) returns a live verdict, evaluated at read time, never cached as immutable — see Freshness.

Authority

authority = client.get_authority(fsv_id)
print(authority.status)  # "BOUND" | "UNBOUND"

UNBOUND means exactly what it says — no reviewed Authority binding governs this state's source. The SDK never converts this into a confidence score; there is no numeric authority score anywhere in it, because the server has none either.

Reality Lock

lock = client.create_reality_lock(
    [fsv_id],
    idempotency_key="my-decision-2026-09-15-001",  # your own dedupe key
    purpose="approve-vendor-onboarding",
)

assessment = client.assess_reality_lock(lock.id)
for item in assessment.basis:
    print(item.fact_state_version_id, item.freshness_now.status, item.is_current_head)

A durable, auditable record of the exact Reality basis a decision used — not a claim that Reality is frozen. Re-calling with the same idempotency_key and basis returns the same lock, safely; reusing that key with a different basis raises a conflict error.

Configuration

base_url defaults to wherever the production Gateway happens to live today — a provider-generated hostname, not a stable custom domain, and not guaranteed as a long-term contract. If your integration cares about URL stability, pass base_url explicitly rather than relying on the implicit default; this is also how you point the SDK at a staging environment or a local instance under test.

What this SDK does not do

• It does not compute Freshness, Authority, or Change Classification itself — every value is exactly what the Gateway returned, never re-derived client-side.
• It is synchronous-only today; an async variant is a planned follow-up, not a redesign.
• It does not retry write operations (e.g. create_reality_lock) automatically — retry safely yourself using the same idempotency_key.
• It does not offer OpenAI Reality resolution as a working example, because OpenAI's public resolution is not yet published — see Overview.

Next

See Resolve Reality for the full REST contract this SDK wraps, or Request a pilot to get access.