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.

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.4.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.4.0
File Size Uploaded Provenance Actions
ergon_platform_sdk-0.4.0.tar.gz 213.8 kB Without provenance Details for ergon_platform_sdk-0.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 515.9 kB

Release files / ergon_platform_sdk-0.4.0.tar.gz

Download URL ergon_platform_sdk-0.4.0.tar.gz
Size 213.8 kB
Tags Source
SHA-256 checksum
How to use checksums
a78ab56465898adfebaebb6ae2c2c796f20f8107296122ab24b854da684976d3
BLAKE2b-256 checksum
How to use checksums
63797f127f43a371cb67a82f9ca308f199d32733ceb0d1e01525a4ff94457d3f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.4.0-py3-none-any.whl

Download URL ergon_platform_sdk-0.4.0-py3-none-any.whl
Size 302.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5da148931cad9c4ba7e58fc09facbbef96455eb888ddab061f2d52a00edc8f0c
BLAKE2b-256 checksum
How to use checksums
f7e99aace8066aa33977d8980798fb10c4f30160c9bd692712f0e5eb3c9c76e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.4.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