Metadata-Version: 2.1
Name: greenlandai
Version: 0.3.4
Summary: Unified SDK for the GreenlandAI ecosystem (ENYAL, JoulePAI, RAREEAI, GreenlandAI)
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Requires-Dist: cryptography>=41
Provides-Extra: bip39
Requires-Dist: mnemonic>=0.21; extra == "bip39"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: mnemonic>=0.21; extra == "dev"
Requires-Dist: kyber-py==1.2.0; extra == "dev"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
Provides-Extra: pq
Requires-Dist: kyber-py==1.2.0; extra == "pq"

# 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
```bash
pip install greenlandai            # core
pip install "greenlandai[bip39]"   # + mnemonic recovery primitives
pip install "greenlandai[otel]"    # + OpenTelemetry metrics (opt-in; OFF by default)
```

## Auth
```python
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)
```python
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)

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