SuperTag Python SDK

Build Python Workers and connect them to a persistent SuperTag Gateway. The SDK implements the same language-neutral Worker boundary as the TypeScript SDK:

• Worker and Worker Host descriptors
• protocol v7 negotiation
• outbound, reconnecting WebSocket transport
• heartbeats, concurrent jobs, and cancellation
• ordered Task Attempt events
• reusable conformance checks
• a Codex Harness powered by the official openai-codex SDK

Install the published SDK with Codex support:

python -m pip install 'supertag[codex]'

The distribution and import namespace both use the product name:

from supertag import CodexHarness, CodexWorker, RemoteWorkerHost

When developing this repository, install the local package instead:

python -m pip install -e './sdks/python[codex]'

The Codex Worker uses an existing Codex sign-in. It runs against a local workspace with a read-only sandbox, streams the answer, and saves an opaque Codex thread checkpoint so the next Task in the Session can resume the conversation.

export SUPERTAG_WORKER_PAIRING_TOKEN='pairing-token-from-the-gateway'
supertag-codex-worker \
  --gateway https://gateway.example.com \
  --workspace /path/to/repository

The pairing token stays in the environment instead of the command line. The Worker connects outward, so the local host does not need a public inbound port.

To build another Worker, implement describe() and execute(), place it in a LocalWorkerHost, and pass that host to RemoteWorkerHost. Run run_worker_conformance() before connecting it to a Gateway.

The JSON Schemas in the repository's spec/ directory are the source of truth for every language implementation.