Python SDK reference

The Python package is named griot. Source lives at sdk/griot-py in the SDK feature branches; there is no published PyPI release for this new public interface. The stable sync entry point is Griot(base_url, *, api_key, workspace_id, ...). AsyncGriot uses an async transport and supports async with.

Resource groups

Group	Available convenience methods	Notes
workspace	get, subscription, capabilities; members.list/get/invite/remove; roles.list/assign/remove	Server roles and grants still apply.
catalog	list/create/delete	create follows the server's upsert contract.
domain	list/get/create	create can include an explicit catalog.
compute_definitions	list/get/create/update/validate/resource_classes	Server validation is authoritative.
authored.notebooks, authored.reports	list/get/create; reports also publish	Publishing is a separate write.
buckets	list/create; files.list/upload/upload_folder	Keeps original bytes; existing path refuses overwrite.
tables	list/get/create_from_file	List/get accept catalog and domain scope; creation requires a human steward session and structured source in a bucket.
query	execute(sql)	Returns the server's response envelope.

client.api (and PlatformClient) exposes generated operation methods beyond this facade. client.operations() and client.check_skew() expose the local manifest and server mismatch. client.dataset("griot://domain/table") preserves the domain; the legacy sample route accepts only a bare slug and refuses a qualified reference rather than discarding context.

Credentials and safety

Explicit api_key= wins over GRIOT_API_KEY; an injected GRIOT_JWT or GRIOT_JWT_FILE is the fallback. A gpat_ PAT needs workspace_id because it carries no tenant claim. A session JWT's workspace claim must match the supplied context. The REST transport refuses gak_ agent keys; use those at the MCP edge. Do not log credential.value, commit a token, or present an agent key as a human steward session.

AsyncGriot also exposes async bucket file listing, byte/folder uploads, table list/get/create-from-file, and query execution. It does not expose the sync client's path-based single-file upload convenience; read the file and use upload_bytes, or use upload_folder. See Automate a workspace with Python for code-backed examples.

Error model and version boundary

Transport, auth, not-found, governance refusal, and server errors are typed in griot._core.errors. The generated manifest can drift from a running K01; check skew and use a matching server revision for newly added catalog operations. These interfaces are implemented in feature branches, not yet a package-registry release.