Skip to main content

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 root ergon), 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 example client.buckets.buckets or client.iam.companies.
  • Pages — list(...) returns a Page with .items and .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) exposes workflows/{id}/*, and client.buckets.buckets.access(bucket_id).grants exposes 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.7.0

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

Source distribution (sdist)

Source distribution for ergon-platform-sdk 0.7.0
File Size Uploaded Provenance Actions
ergon_platform_sdk-0.7.0.tar.gz 221.4 kB Without provenance Details for ergon_platform_sdk-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ergon-platform-sdk 0.7.0
File Interpreter ABI Platform Actions
ergon_platform_sdk-0.7.0-py3-none-any.whl Python 3 none any Details for ergon_platform_sdk-0.7.0-py3-none-any.whl

Total release size: 529.1 kB

Release files / ergon_platform_sdk-0.7.0.tar.gz

Download URL ergon_platform_sdk-0.7.0.tar.gz
Size 221.4 kB
Tags Source
SHA-256 checksum
How to use checksums
495b7354662c10e0542bb4f1bb949c52156eecb0d6a99604b70249bfdb736ab4
BLAKE2b-256 checksum
How to use checksums
23071cbc2444c9e4f9658b6d3be3a9701a89d06e96405040f5e81a3b511bae31
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.7.0-py3-none-any.whl

Download URL ergon_platform_sdk-0.7.0-py3-none-any.whl
Size 307.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2d1968e8ab4d8869600a7f372d65f7f4fdba091182fe7abfa1efe51c52b43aa7
BLAKE2b-256 checksum
How to use checksums
c6c99e1259f2552d4cc8fde0d67670e07bd2f7d7b351373f4cd58635bc04b10a
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.7.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page