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

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.5.1
File Size Uploaded Provenance Actions
ergon_platform_sdk-0.5.1.tar.gz 218.2 kB Without provenance Details for ergon_platform_sdk-0.5.1.tar.gz

Built distribution (wheel)

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

Total release size: 523.3 kB

Release files / ergon_platform_sdk-0.5.1.tar.gz

Download URL ergon_platform_sdk-0.5.1.tar.gz
Size 218.2 kB
Tags Source
SHA-256 checksum
How to use checksums
b6867b0c8e1184a7a82e14c363a99c6c3cdd80d10398b3962a66d30eefe43ec0
BLAKE2b-256 checksum
How to use checksums
e2bc374419040fb1cd86d3a307cbe443b4b86fe1125b48299564c519243a8f13
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.5.1-py3-none-any.whl

Download URL ergon_platform_sdk-0.5.1-py3-none-any.whl
Size 305.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
df08629884863fe7b4dce6ed08659ad15b6cb6196905f90f700b2e45efe7897b
BLAKE2b-256 checksum
How to use checksums
0ea5c567867503c0faa8c38fa653f91ce0ae675c9cac65c39a24e901bf72bafd
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.5.1

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