Metadata-Version: 2.5
Name: supertag
Version: 0.1.0
Summary: Extensible Python SDK for SuperTag Workers, Harnesses, and Gateway connectivity
Project-URL: Homepage, https://github.com/bfloat-inc/supertag
Project-URL: Documentation, https://github.com/bfloat-inc/supertag/tree/main/docs
Project-URL: Repository, https://github.com/bfloat-inc/supertag
Project-URL: Issues, https://github.com/bfloat-inc/supertag/issues
Author: SuperTag maintainers
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,codex,gateway,harness,supertag,workers
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: websockets<17,>=13
Provides-Extra: codex
Requires-Dist: openai-codex<0.145,>=0.144.4; extra == 'codex'
Provides-Extra: dev
Requires-Dist: openai-codex<0.145,>=0.144.4; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
Description-Content-Type: text/markdown

# 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:

```sh
python -m pip install 'supertag[codex]'
```

The distribution and import namespace both use the product name:

```python
from supertag import CodexHarness, CodexWorker, RemoteWorkerHost
```

When developing this repository, install the local package instead:

```sh
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.

```sh
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.
