greenlandai (Python)

Unified SDK for the GreenlandAI ecosystem — ENYAL, JoulePAI, RAREEAI, GreenlandAI. Supersedes but does not replace enyal-sdk v2.1.x (permanent coexistence — the standalone enterprise track stays published and maintained; see design §5).

Install

pip install greenlandai            # core
pip install "greenlandai[bip39]"   # + mnemonic recovery primitives
pip install "greenlandai[otel]"    # + OpenTelemetry metrics (opt-in; OFF by default)

Auth

from greenlandai import Client
client = Client(api_key="eyl_...")          # eyl_ (ENYAL / cross-product) API key
client = Client(api_key="gai_...")          # gai_ (GreenlandAI agent key) — for the gldai intelligence family
client = Client(oauth_token=jwt)             # web sessions: ENYAL-issued OAuth JWT
# Any api_key → X-API-Key; an oauth_token (JWT) → Authorization: Bearer. Pass exactly one.
# Passing an API key via oauth_token (or a JWT via api_key) raises immediately — no silent mis-route.
# 401s surface to you (no auto-refresh); hook: Client(..., on_auth_expired=cb)
# Key rotation = generate a new key server-side and rebuild the Client (no dual-validation window).

Known limitation (gai_ + marketplace): a gai_ key authenticates the GreenlandAI intelligence family (client.gldai.*). The marketplace (client.rareeai.*) is served via joulepai.ai, whose proxy does not yet resolve gai_ keys — for marketplace with a gai_ key, call greenlandai.ai/api/v1/marketplace/* over raw HTTP until the server side lands. eyl_ / OAuth marketplace access via the SDK is unaffected.

Hello world (one per submodule)

client.enyal.archive("agent-1", "decision_record", "k1", {"decision": "x"})
client.joulepai.transfer("@bob", 1000, note="thanks")     # auto idempotency key
client.rareeai.create_request(resource_type="gpu")        # marketplace (flat 0.5%, route-fixed)
client.gldai.query("lithium deposits greenland")

Idempotency promise matrix (auto-retry behavior — design §6, post-G1 2026-06-10)

Every billed call auto-generates a UUID4 key (stable across retries) unless you pass idempotency_key / idempotencyKey yourself.

Observability (OFF by default)

Client(logger=my_logger, on_retry=..., on_terminal_failure=..., metrics=otel_metrics()) — DEBUG logs redact Authorization + X-API-Key structurally.

Migration from enyal-sdk 2.1.0: see MIGRATION.md. Changelog: CHANGELOG.md.