Ergon Platform SDK (Python)
Typed Python client for the Ergon Platform public HTTP API. Async and sync, with automatic API-key authentication, retries, pagination, and typed errors.
- Distribution:
ergon-platform-sdk - Import root:
ergon_platform
This is the client SDK (for consuming the platform API). It is unrelated to
ergon-framework-python(import rootergon), which is for building services.
Install
pip install ergon-platform-sdk
# or, in this workspace:
uv sync
Quick start
Synchronous
from ergon_platform import ErgonClient
# Machine-to-machine: the API key's company is baked into the issued token,
# so you never pass company_id.
client = ErgonClient(
client_id="ek_...",
client_secret="eks_...",
base_url="http://localhost", # gateway origin
)
# IAM — `companies` is a uniform collection
company = client.iam.companies.create(name="Acme")
for key in client.iam.api_keys.iter(company_id=company.id):
print(key.name)
# Workflows — the service node *is* the workflow resource (list/create are
# company-scoped); drill into one workflow's subtree via the scope accessor.
page = client.workflows.list(limit=50) # company_id is inferred from the JWT
for wf in page.items:
print(wf.id, wf.name)
scope = client.workflows.workflow(page.items[0].id)
scope.create_item(title="New ticket") # POST workflows/{id}/items
client.workflows.items.claim(item_id="...") # id-addressed action
Asynchronous
import asyncio
from ergon_platform import AsyncErgonClient
async def main() -> None:
async with AsyncErgonClient(client_id="ek_...", client_secret="eks_...") as client:
# `iter` transparently follows pagination across pages
async for bucket in client.buckets.buckets.iter():
print(bucket.id, bucket.name)
asyncio.run(main())
Errors
from ergon_platform import NotFoundError, PermissionDeniedError
try:
client.iam.companies.get("does-not-exist")
except NotFoundError as exc:
print(exc.status_code, exc.detail, exc.request_id)
Examples
Runnable, commented walkthroughs live in
examples/:
quickstart.py— minimal client setup and a few reads.practical_usage.py— end-to-end tour: workflows (folder → workflow → phase → item), Vault credentials, Compute governed HTTP invocation, pagination, typed errors, and the async client.
Authentication
| Mode | Constructor args | Notes |
|---|---|---|
| API key (M2M) | client_id, client_secret |
Primary. Token exchanged + refreshed automatically. Tenant is implicit. |
| Bearer token | token= |
Pre-obtained JWT (e.g. a user access token). Pass company_id= if the token isn't pinned to a company. |
Worker identity (Pull only phases)
Pass consumer_id= to send X-Ergon-Consumer-Id on every request. Pull only
workflow phases use it to fence item claims: items pulled or claimed under one
consumer id carry an expiry and cannot be released, routed or extended by another
consumer (409 claim_mismatch). Use one value per worker process, e.g.
f"{hostname}:{pid}"; allowed characters are [A-Za-z0-9._:@-], up to 128.
client = ErgonClient(client_id="ek_...", client_secret="eks_...", consumer_id="billing-worker:1")
pulled = client.workflows.phases.pull_items(phase_id, max=10)
for item in pulled.items:
client.workflows.items.complete(item.id)
Services
Twelve services hang off the client:
client.iam, client.workflows, client.channels, client.agents,
client.worksheets, client.buckets, client.event_streams,
client.conversations, client.automations, client.apps,
client.compute, client.vault.
Conventions
The facade follows the same shape across every service, so once you learn one you know them all:
- Collections — a uniform REST resource exposes
list/iter/get/create/update/delete. For exampleclient.buckets.bucketsorclient.iam.companies. - Pages —
list(...)returns aPagewith.itemsand.total;iter(...)is a generator (or async generator) that transparently walks every page for you. - Scopes — resources nested under a parent id are reached through an
accessor that returns a sub-client, e.g.
client.workflows.workflow(workflow_id)exposesworkflows/{id}/*, andclient.buckets.buckets.access(bucket_id).grantsexposes the per-bucket grant subtree. - Actions — non-CRUD endpoints are plain methods named after the verb,
e.g.
client.workflows.items.claim(item_id=...)or.route(item_id=..., target_phase_id=...). - Typing — responses are parsed into generated Pydantic models when the schema is unambiguous; otherwise a permissive model is used that preserves every field the server returns (so new fields never break you).
- Escape hatch — the full, fully-typed generated client and every schema
for every endpoint live under
ergon_platform._generated.<service>if you need an operation the facade doesn't surface ergonomically.
Both ErgonClient and AsyncErgonClient expose the identical surface; the
async variant returns awaitables / async iterators.
Coverage
The facade wires every public operation of all twelve services (see the
generated matrix at docs/coverage.md). Only each
service's /health liveness probe is intentionally left out. A CI guard
(scripts/coverage.py --check) fails the build if the platform grows a new
endpoint that isn't wired, so the SDK can't silently drift behind the API.
Development
uv run python scripts/export_openapi.py # refresh specs from a running platform
uv run python scripts/generate.py # regenerate the _generated client layer
uv run python scripts/coverage.py # regenerate docs/coverage.md
uv run python scripts/coverage.py --check # CI guard: fail on unwired endpoints
uv run --package ergon-platform-sdk pytest # unit tests
ERGON_INTEGRATION=1 uv run --package ergon-platform-sdk pytest -m integration
Metadata
Release files for ergon-platform-sdk 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ergon_platform_sdk-0.8.0.tar.gz | 220.8 kB | Without provenance | Details for ergon_platform_sdk-0.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ergon_platform_sdk-0.8.0-py3-none-any.whl | Python 3 | none | any | Details for ergon_platform_sdk-0.8.0-py3-none-any.whl |
Total release size: 526.7 kB
Release files / ergon_platform_sdk-0.8.0.tar.gz
| Download URL | ergon_platform_sdk-0.8.0.tar.gz |
|---|---|
| Size | 220.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
612d294a4aafe7724b0da8fa494e92a0277a394841dad7cd3641995fdbacd119
|
|
BLAKE2b-256 checksum How to use checksums |
b24fd2dc3735e1e541f601accdde5ca1165a5811c539a5bbcfc8a0243c1bd341
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / ergon_platform_sdk-0.8.0-py3-none-any.whl
| Download URL | ergon_platform_sdk-0.8.0-py3-none-any.whl |
|---|---|
| Size | 305.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69dc66d22a355495fe499cd018af4a52d632a9940cb988c11ba7b3a3a8bb38fe
|
|
BLAKE2b-256 checksum How to use checksums |
904569bc649c3b6192bc338ef17f767a083b475c60b7346446efbc0892c21696
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for ergon-platform-sdk 0.8.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.