Skip to content

Python SDK

Official Python client for the Climate-Lama API. Engine-agnostic — the SDK only talks HTTP to the backbone.

Install

pip install climate-lama

The package name on PyPI is climate-lama; the import path is climate_lama_client.

Quickstart

from climate_lama_client import ClimateLama

client = ClimateLama(base_url="https://api.example.com")
client.auth.login(email="you@example.com", password="...", org_slug="default")

hz = client.hazards.list()
ex = client.exposures.upload("portfolio.csv", name="My portfolio")

# exposure_id is optional — when omitted, the backbone uses the caller-org's
# most recent exposure dataset.
result = client.compute.impact(
    hazard_id=hz[0]["id"],
    exposure_id=ex["id"],
).wait(timeout_s=300, poll_interval_s=2)
print(result["ead"], result["aai"])

job.wait() polls GET /v1/jobs/{id} every poll_interval_s (default 2s). When the job completes, it auto-fetches GET /v1/results/{result_id} and returns the result summary. Raises JobError on failure and TimeoutError after timeout_s (default 300s).

Authentication

Compute endpoints require Role.ANALYST or above. Either log in via client.auth.login(...) (sets the bearer token on the client for subsequent calls), or pass a token at construction:

client = ClimateLama(base_url=..., token="<jwt-or-api-key>")

API keys (prefix clk_) and JWTs are both accepted as bearer tokens.

Cost-benefit

Cost-benefit runs against an existing impact result, not raw inputs. Capture the impact job's result_id first:

impact_job = client.compute.impact(hazard_id=..., exposure_id=...)
impact_job.wait()
result_id = impact_job.payload["result_id"]

cb = client.compute.cost_benefit(
    impact_result_id=result_id,
    measure_ids=[...],
    discount_rate=0.014,
    time_horizon_years=10,
    value_growth_rate=0.013,
).wait()

Field-name translation

The SDK uses friendlier hazard_id / exposure_id parameter names but translates them to the backbone's wire-level hazard_dataset_id / exposure_dataset_id before sending. Cost-benefit's wire shape is mostly 1:1 with the SDK because there's no shorter friendly name for impact_result_id.

Errors

The backbone returns ADR-028 error envelopes (code, severity, message, details). The SDK decodes them into typed Python exceptions, one per registered code:

from climate_lama_client.errors import (
    HazardIntensityUnitMismatchError,
    NotFoundError,
    ClimateLamaError,
)

try:
    client.compute.impact(hazard_id="hz-1", exposure_id="ex-1").wait()
except HazardIntensityUnitMismatchError as exc:
    # Catch a specific code…
    print(exc.message, exc.details)
except ClimateLamaError as exc:
    # …or fall back to the base class for anything you didn't enumerate.
    print("API error", exc.code, exc.message)

The error class registry is generated from the backbone's src/climate_lama/core/errors.py by sdk/python/scripts/regenerate_errors.py, so the SDK never drifts from the backbone's published codes. Codes the SDK doesn't recognize fall back to the base ClimateLamaError class instead of crashing — which is what makes it safe to add new codes to the backbone without breaking older SDK versions.

Async support

This release is sync-only. Async support (tracked in #276) will land in a future release as climate_lama_client.aio.

Versioning

The SDK is shipped from the sdk/python/ subdirectory of the climate-lama repo. Tagging a release as sdk-vX.Y.Z publishes to Test PyPI automatically; production PyPI publishes are gated behind a manual approval step.

Source

sdk/python/ on GitHub.