Python SDK surface

The Python distribution is GAOS's Game-as-a-Benchmark integration surface for research harnesses. It provides a zero-runtime-dependency hosted client, provider-neutral evaluation helpers, and portable replay utilities. It targets Python 3.10 or newer.

Capability boundary

Python is the research and hosted-integration surface. It can:

• create and control sessions on a protocol-compatible host;
• run duck-typed policies for one episode or a batch;
• parse, validate, and serialize canonical gaos.replay JSONL; and
• use synchronous or asynchronous hosted clients.

Python does not include the TypeScript mechanism engine, a local TickReducer runtime, replay re-simulation, model-provider drivers, or agent CLI launchers. Build the game and its authoritative reducer with the TypeScript SDK, then use Python when a research harness needs to control the hosted game or inspect portable evidence.

Install

Install the v1.0 Python package directly from the tagged repository:

python -m pip install "git+https://github.com/yugao-gaos/GAOS-SDK.git@v1.0.1#subdirectory=python"

The distribution name is gaos-sdk and the import name is gaos_sdk.

Async applications can use AsyncSessionClient, which runs the same validated, bounded requests in worker threads without blocking the event loop.

Hosted client

Use SessionClient for any host that implements /v1/sessions. Its observations and commands remain opaque:

from gaos_sdk import SessionClient

client = SessionClient("https://host.example")
created = client.create_session({"game": "creator/cards"})
print(created["tick"])

The client speaks the gaos.ticks v1 envelope on /v1/sessions. Commands carry the session cursor, participant, and a deterministic submission ID: reuse it for an exact retry and create a new one for each logical control step. attach_session() resumes an attachable session at its durable head, and finalize_session() requests the same immutable finalization used by ordinary and evaluated play. Python also constructs and independently verifies the portable RFC-018 attachment-receipt chain. AsyncSessionClient exposes the same operations.

run_agent_episode and evaluate_agent_episodes accept any duck-typed environment with Gymnasium-compatible reset() and step() methods. They do not provide a product environment, choose a model provider, or define what a benchmark score means. Product repositories own their typed clients and environment adapters.

Exchange portable replay evidence

from gaos_sdk import (
    parse_replay_jsonl,
    serialize_replay_jsonl,
    validate_replay_artifact,
)

with open("run.gaos-replay.jsonl", encoding="utf-8") as source:
    artifact = parse_replay_jsonl(source.read())

errors = validate_replay_artifact(artifact)
if errors:
    raise ValueError(errors)

canonical_jsonl = serialize_replay_jsonl(artifact)

Validation checks the replay envelope, schema, sequence, digests, and canonical transport representation. It does not execute the game. Full rechecking requires the pinned historical reducer and authored content. Use the TypeScript gaos verify adapter contract or provide a Python recheck_replay(artifact) adapter whose result includes semantic command/timeout binding facts for signed evidence. See portable replay and verification.

For lower-level envelope operations, see the complete Python README on GitHub.