Python SDK

The staged ivorleaf Python SDK compatibility candidate v0.2.0.dev0 wraps the supplied/acquisition contract on the existing Validation Intelligence POST/GET API. Python 3.10–3.14 is supported. Its only direct runtime dependency is HTTPX.

Pilot installation

This candidate is not published or distributed. Its distribution must be coordinated with the v1 cutover. After that release is approved, install the matching wheel supplied by the Ivorleaf team:

python -m pip install ./ivorleaf-0.2.0.dev0-py3-none-any.whl

Or run python -m pip install . from the supplied SDK checkout. No public repository destination is established here. Package-index publication is a separate release action.

First validation

Set IVORLEAF_API_KEY securely in your environment or secret manager. An explicit Ivorleaf(api_key="...") overrides the environment; never commit the key.

from ivorleaf import Ivorleaf

with Ivorleaf() as client:
    result = client.validation.create(
        information="H2O is the chemical formula for water.",
        evidence=[{"text": "The chemical formula for water is H2O."}],
    )
    print(result.validation_id, result.determination)
    print(result.relationships)

Expected: supported with a supports relationship. result.to_dict() preserves the canonical public response, including information units, evidence, reason, signals and provenance. No confidence score is added.

Explicit acquisition

with Ivorleaf() as client:
    result = client.validation.create(
        information="SQL Server supports the WHERE clause for filtering rows returned by a query.",
        evidence=[{"acquire": {
            "title": "WHERE (Transact-SQL) — Microsoft Learn",
            "url": "https://learn.microsoft.com/en-us/sql/t-sql/queries/where-transact-sql",
        }}],
    )

Nonblank evidence text is evaluated unchanged; optional source metadata is provenance only. Explicit acquire invokes Source Inspection. Do not combine these forms. Failure fails closed without caller-text substitution. New acquired provenance is accepted; historical stored responses remain unchanged. The SDK never fetches evidence URLs locally. Coordinate this compatibility update with the v1 cutover before distributing it.

Automatic 202 → GET handling

create() sends Prefer: respond-async by default. HTTP 200 returns the completed result; HTTP 202 triggers GET polling of the same validation ID to a terminal state. Retry-After is respected with a minimum/fallback one-second interval. No automatic POST or semantic retries occur.

The default SDK wait budget is 120 seconds, configurable with Ivorleaf(wait_timeout=120). It includes the initial POST and subsequent polling. It is distinct from the server's 20s sync / 60s provider / 90s hard budgets. Network inactivity timeouts and deadline checks apply; this is not hard real-time cancellation.

Retrieve, wait and recovery

from ivorleaf.errors import IvorleafWaitTimeout, IvorleafUnknownOutcomeError

with Ivorleaf() as client:
    state = client.validation.retrieve("YOUR_VALIDATION_ID")  # one GET
    result = client.validation.wait("YOUR_VALIDATION_ID")     # GET until terminal

retrieve() returns completed, in_progress or failed typed states. create() and wait() raise ValidationExecutionError on terminal failure, with validation_id and public code/message. An SDK wait timeout preserves validation_id: the server may still be running, so retrieve or wait later.

For create, supply a durable idempotency_key="workflow-event-123" or let the SDK generate one, exposed as result.idempotency_key. Unknown POST outcome raises IvorleafUnknownOutcomeError carrying the effective idempotency_key. Explicit recovery must preserve the same key and payload. Never blindly create again with a new key. Store a caller-chosen key before sending if crash recovery is required.

Typed HTTP errors cover 401, 403, 404, 409, 422, 429 and 500/502/503/504; see errors and idempotency. All SDK exceptions inherit ivorleaf.errors.IvorleafError.

JSON file input

with Ivorleaf() as client:
    result = client.validation.create_from_file("validation-request.json")

One regular UTF-8 .json file maps to one exact ValidationRequest. Arrays, unknown request fields, invalid evidence forms, Markdown and remote file references are rejected. Explicit acquire is sent to the API; the file parser does not retrieve evidence. The filename does not enter idempotency. Use the canonical JSON examples.