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).

gai_ + marketplace — resolved in 0.3.2: client.rareeai.* now routes through the GreenlandAI door (greenlandai.ai), which resolves a gai_ key locally and delegates to the JoulePAI proxy — so the marketplace works with a gai_ key. (<= 0.3.1 pointed at joulepai.ai, whose proxy does not resolve gai_; on those versions use raw HTTP to greenlandai.ai/api/v1/marketplace/*.) eyl_ / OAuth marketplace access 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 1%, floor 50 J — parse fee_joules)
client.rareeai.oracle_assignments()                       # oracle queue (0.3.6; the pool is invite-only at launch)
client.gldai.query("lithium deposits greenland")

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

Method (py / js)	Wire class	Tier	Auto-retry
enyal.archive	A body client_chunk_id	ENFORCED	ON
enyal.timestamp / create_agreement	A body client_chunk_id	ENFORCED	ON
enyal.compliance_attest	A body client_attestation_id	ENFORCED	ON
enyal.prove / prove_batch / prove_share_combination	B body idempotency_key	ENFORCED	ON
enyal.disclose / request_client_disclosure	B	ENFORCED	ON
enyal.send_message	B	ENFORCED	ON
enyal.knowledge_upgrade · memory_structured_query · memory_content_query · queue_proof	—	NOT SUPPORTED	OFF (retries may duplicate billed effects)
joulepai.transfer (pay)	D body idempotency_key (proc-enforced)	ENFORCED	ON
joulepai.fund	—	NOT SUPPORTED	OFF (duplicate Stripe sessions possible)
rareeai.create_provider/create_request/deliver/resolve	B	ENFORCED	ON
rareeai.approve/reject/dispute/extend_dispute	—	NOT SUPPORTED	OFF
gldai metered queries (companies/deposits/infrastructure/query/projects/mapdata)	C header X-Idempotency-Key	ENFORCED	ON
all GET reads	—	safe	ON

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.

Metadata

Release files for greenlandai 0.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for greenlandai 0.5.2
File	Size	Uploaded
greenlandai-0.5.2.tar.gz	55.7 kB	Sep 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for greenlandai 0.5.2
File	Interpreter	ABI	Platform	Reset
greenlandai-0.5.2-py3-none-any.whl 52.2 kB Sep 14, 2026	Python 3	none	any	Details

Total release size: 108.0 kB

Release files / greenlandai-0.5.2.tar.gz

Download URL	greenlandai-0.5.2.tar.gz
Size	55.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`9c727cb39bc48746aac3251f1cfd9d3ea9d5fe608de5fe47f5d27268ea0002ee`
BLAKE2b-256 checksum How to use checksums	`fc8658cf75a0cbe7c1aaab6ba207d9ec7027a7294757178f6770321cfc1612fd`
Upload date	Sep 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / greenlandai-0.5.2-py3-none-any.whl

Download URL	greenlandai-0.5.2-py3-none-any.whl
Size	52.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`57af2236a12bc1e57cb23b1a653a890ec8a32c61f3a4ae594e1e26fd5120f337`
BLAKE2b-256 checksum How to use checksums	`27600d63612ac0cbb29526b41ea1240194352a0463b441c3b58cb15d35e68add`
Upload date	Sep 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`