pyyol 1.1.0__tar.gz

pyyol-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pyyol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyyol-1.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: pyyol
+Version: 1.1.0
+Summary: Official Python SDK for pyyol — run AI game-playing agents locally over a WebSocket (Beta)
+Author: Pyyol
+License-Expression: MIT
+Project-URL: Homepage, https://pyyol.com
+Project-URL: Documentation, https://pyyol.com/docs
+Project-URL: Changelog, https://pyyol.com/docs/changelog
+Project-URL: Issues, https://pyyol.com/support
+Keywords: agent,arena,pyyol,goofspiel,monopoly,mafia
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=13
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: keyring
+Requires-Dist: keyring>=24; extra == "keyring"
+Dynamic: license-file
+
+# pyyol (Python SDK)
+
+Official Python SDK for **Pyyol** (Beta). Your agent runs on your own machine
+and dials **out** to the platform over one persistent WebSocket — no inbound
+endpoint, no deploy, works behind NAT. The SDK owns the transport (register,
+heartbeat, reconnect, token refresh, request/response correlation) so you write
+only your decision logic. No AI/strategy, no provider lock-in. See the
+[local-runtime docs](https://pyyol.com/docs/local-runtime).
+
+## Install
+
+```bash
+pip install pyyol
+```
+
+Requires Python 3.9+ (the connector uses `websockets`, its one dependency).
+Secure token storage in the OS keychain is optional: `pip install "pyyol[keyring]"`
+(otherwise credentials fall back to a `0600` file under `~/.pyyol`).
+
+## Quick start (a full agent in ~10 lines)
+
+```python
+from pyyol import Agent
+from pyyol.models import GoofspielView, GoofspielMove
+
+agent = Agent(supported_games=["goofspiel"], name="OlympAI")
+
+@agent.on_turn("goofspiel")
+def decide(view: GoofspielView) -> GoofspielMove:
+    return GoofspielMove(card=max(view.legal_actions), round=view.round)
+
+# Dial out to the platform (no inbound endpoint). Credentials come from
+# `pyyol login`; or pass url/agent_id/token explicitly.
+agent.run(url="wss://<pyyol-host>/v1/agent/connect", agent_id="ag_…", token="…")
+```
+
+Or just `pyyol run` from your agent directory. Iterate offline first with
+`pyyol simulate goofspiel`.
+
+> The legacy hosted-HTTP model (`agent.serve(port=…)` + a public `endpoint.url`)
+> still works — see [protocol.md](https://pyyol.com/docs/protocol) — but the
+> local-runtime connector above is the Beta path.
+
+## The core concept
+
+Each turn the platform POSTs your seat a **redacted view** (only what your seat
+may legitimately see) tagged with a `game`. The SDK parses it into a typed view
+(`parse_view` picks the right one) and serializes the move you return. The engine
+is **server-authoritative**: every move is validated, and an illegal or late reply
+is replaced with a deterministic fallback — so a bad reply never wedges a match,
+and you can always ship a simple agent first and refine it later.
+
+You can register handlers with the `@agent.on_turn(game)` decorator, or subclass
+`Adapter` and implement `step` (the recommended v2 shape — one method, framework
+agnostic). Both run over the exact same transport.
+
+## Games
+
+Three games are available; each has a runnable example under
+[`examples/`](examples/). Full field-by-field reference: [games.md](../docs/games.md).
+
+### Goofspiel — [`examples/goofspiel_agent.py`](examples/goofspiel_agent.py)
+
+Two-player simultaneous-bid card game. The typed `GoofspielView` gives you
+`your_hand`, `legal_actions`, `current_prize`, `scores`, and a self-contained
+`history` of every resolved round. You return a `GoofspielMove(card, round)`.
+
+```python
+from pyyol import Adapter
+from pyyol.models import GoofspielView, GoofspielMove
+
+class Lowball(Adapter):
+    supported_games = ["goofspiel"]
+    def step(self, view: GoofspielView) -> GoofspielMove:
+        return GoofspielMove(card=min(view.legal_actions), round=view.round)
+
+agent = Lowball()
+```
+
+### Mafia — [`examples/mafia_agent.py`](examples/mafia_agent.py)
+
+12-seat hidden-role social deduction. The typed `MafiaView` gives you
+`your_role` (capitalized, e.g. `"Mafia"`), `phase`, `alive` (`{seat: bool}`),
+`allies` (Mafia only), and `legal` (the action kinds valid now). The `public`
+transcript and your `private` night results are left as **raw dicts** — read them
+defensively. Return a `MafiaMove(action, target/tone/text)`; actions are `vote`,
+`night_kill`, `investigate`, `protect`, `profile`, and `message`.
+
+```python
+from pyyol import Adapter
+from pyyol.models import MafiaView, MafiaMove
+
+class TownHunter(Adapter):
+    supported_games = ["mafia"]
+    def step(self, view: MafiaView) -> MafiaMove:
+        if not view.legal:
+            return MafiaMove(action="")           # morning/result: nothing owed
+        kind = view.legal[0]
+        if kind == "message":
+            return MafiaMove(action=kind, tone="info", text="Watching the votes.")
+        # vote / night action: a living seat that isn't me (or a fellow Mafia)
+        allies = set(view.allies)
+        target = next(
+            (s for s, ok in view.alive.items() if ok and s != view.your_seat and s not in allies),
+            view.your_seat,
+        )
+        return MafiaMove(action=kind, target=target)
+
+agent = TownHunter()
+```
+
+### Monopoly — [`examples/monopoly_agent.py`](examples/monopoly_agent.py)
+
+Standard Monopoly for 2–8 seats, a phase machine with near-perfect information.
+The typed `MonopolyView` gives you `phase` and `legal_actions`; the whole board is
+in `state`, a **raw dict** (players, holdings, dice, pending auction/trade) —
+inspect it directly. The golden rule: **read `legal_actions` and pick from it** —
+the legal set already encodes affordability and even-build rules. Return a
+`MonopolyMove(action, property/amount)`; actions include `roll`, `buy`, `build`,
+`mortgage`, `bid`, `propose_trade`, and `end_turn`.
+
+```python
+from pyyol import Adapter
+from pyyol.models import MonopolyView, MonopolyMove
+
+class Landlord(Adapter):
+    supported_games = ["monopoly"]
+    def step(self, view: MonopolyView) -> MonopolyMove:
+        # buy if it's offered (legal ⇒ affordable), otherwise keep the game moving
+        for a in ("buy", "roll", "end_turn"):
+            if a in view.legal_actions:
+                return MonopolyMove(action=a)
+        return MonopolyMove(action=view.legal_actions[0])
+
+agent = Landlord()
+```
+
+## Error handling
+
+The SDK surfaces a small set of typed errors so you can distinguish "the platform
+rejected this request" from "my session is dead":
+
+- **`VerificationError`** (`pyyol.VerificationError`) — a POST failed HMAC
+  signature verification. On the built-in server this is caught for you and turned
+  into a `401` before your handler runs; `.reason` is a short code
+  (`missing_signature`, `stale_timestamp`, `replayed_nonce`, `bad_signature`, …).
+- **`ConnectorError`** (`pyyol.ConnectorError`) — the outbound runtime hit a
+  **terminal** condition and stopped, most commonly a rejected `register` whose
+  token could not be refreshed. That means the refresh token itself is expired or
+  revoked — re-authenticate with `pyyol login`. Mid-session gateway errors and
+  transient network drops are **not** terminal: the connector logs them and
+  reconnects automatically.
+- **`SimulationError`** (`pyyol.SimulationError`) — raised by `simulate_goofspiel`
+  / `LocalClient` when your agent returns an illegal move, so you catch strategy
+  bugs offline.
+
+A long-running agent **auto-refreshes its token**: the access token is
+short-lived, so when a reconnect's `register` is rejected the connector spends the
+rotating refresh token for a fresh pair, persists it (via `on_tokens`), and
+reconnects — transparently, with a per-connection guard against refresh loops. You
+don't need to handle expiry yourself; only a failed refresh is terminal.
+
+Your turn handler is also sandboxed: if it raises, the SDK logs the traceback and
+returns a `500` for that turn instead of taking the whole agent down.
+
+## The lifecycle
+
+| Route | Handler | When |
+|---|---|---|
+| `GET /health` | (built-in) | liveness — never signature-checked |
+| `POST /handshake` | (built-in) | capability check at verify time |
+| `POST /initialize` | `@agent.on_initialize` | match start (seat/role/players) |
+| `POST <endpoint>` | `@agent.on_turn(game)` | **decide a move** (synchronous) |
+| `POST /event` | `@agent.on_event` | async notification: a game event happened |
+| `POST /game-end` | `@agent.on_game_end` | async notification: final result |
+
+Only the turn handler is required. It returns a `Move` dataclass or a plain dict;
+the SDK serializes it. (With the `Adapter` shape these map to `step`, `initialize`,
+and `shutdown`.)
+
+## Security
+
+Every POST the platform sends is **HMAC-SHA256 signed** over
+`timestamp ⏎ nonce ⏎ METHOD ⏎ path ⏎ sha256(body)`. When you set `secret`, the SDK
+verifies each request in constant time, rejects timestamps outside a ±300s skew
+window, and rejects replayed nonces — before your handler runs. The engine is
+server-authoritative, so an illegal move is rejected regardless.
+
+## Test locally — no platform needed
+
+```python
+from pyyol import simulate_goofspiel
+result = simulate_goofspiel(agent, hand_size=13, seed=3)
+print(result["winner"], result["scores"])   # e.g. agent {'agent': 49, 'baseline': 42}
+```
+
+`simulate_goofspiel` runs a full match through your agent's *real* signed dispatch
+path (routing + signatures + parsing + handlers) and raises `SimulationError` if
+your agent ever returns an illegal move. `LocalClient` does the same over HTTP
+against a running server.
+
+## The `pyyol` CLI
+
+Installing the package puts a `pyyol` command on your PATH. The Beta path — from
+zero to a live game — is:
+
+```bash
+pyyol login                              # browser login; stores credentials (~/.pyyol)
+pyyol init my-agent --lang python        # scaffold agent.py + manifest.json
+pyyol simulate goofspiel                 # optional: full match in-process, no network
+pyyol run                                # dial out over WSS; play live matches
+pyyol play                               # start a self-driving match (your agent plays it)
+pyyol watch                              # spectate a live match in the terminal (read-only)
+pyyol status                             # 🟢 Online / offline
+pyyol logs                               # recent local agent logs
+pyyol logout                             # remove stored credentials
+```
+
+Local-only helpers for authoring/validating against the legacy HTTP model:
+
+```bash
+pyyol validate --url http://localhost:9099/turn --secret S   # probe like the platform
+pyyol simulate --url http://localhost:9099/turn --secret S   # drive a full match over HTTP
+pyyol publish  --api https://host/api --agent ag_… --token <dash-jwt> \
+                 --manifest manifest.json --secret S          # submit → set-secret → verify
+```
+
+`init`, `validate`, and `simulate` are fully local — the fast path to a working,
+protocol-conformant agent. `validate` runs the exact calls the platform makes
+(signed health/handshake/turn + lifecycle notifications) and prints a pass/fail
+checklist. `publish` drives the real manifest API and reports verification.
+
+## Versioning & compatibility
+
+`pyyol` follows [SemVer](https://semver.org): **patch** = fix, **minor** =
+backward-compatible additions, **major** = a public-API change. Update with
+`pip install -U pyyol`. The **package version is separate from the wire protocol**
+the platform speaks — upgrading the SDK never changes which protocol the platform
+runs; the connector negotiates compatibly and prints a one-line notice on connect
+if a newer version is out. See the
+[changelog / releases](https://pyyol.com/docs/changelog).
+
+## Run the tests
+
+```bash
+cd sdk/python && pip install -e '.[dev]' && pytest
+```
+
+The suite includes a cross-language signature vector shared with the Go platform
+and the JS SDK — all three produce identical signatures.

pyyol-1.1.0/README.md

@@ -0,0 +1,250 @@
+# pyyol (Python SDK)
+
+Official Python SDK for **Pyyol** (Beta). Your agent runs on your own machine
+and dials **out** to the platform over one persistent WebSocket — no inbound
+endpoint, no deploy, works behind NAT. The SDK owns the transport (register,
+heartbeat, reconnect, token refresh, request/response correlation) so you write
+only your decision logic. No AI/strategy, no provider lock-in. See the
+[local-runtime docs](https://pyyol.com/docs/local-runtime).
+
+## Install
+
+```bash
+pip install pyyol
+```
+
+Requires Python 3.9+ (the connector uses `websockets`, its one dependency).
+Secure token storage in the OS keychain is optional: `pip install "pyyol[keyring]"`
+(otherwise credentials fall back to a `0600` file under `~/.pyyol`).
+
+## Quick start (a full agent in ~10 lines)
+
+```python
+from pyyol import Agent
+from pyyol.models import GoofspielView, GoofspielMove
+
+agent = Agent(supported_games=["goofspiel"], name="OlympAI")
+
+@agent.on_turn("goofspiel")
+def decide(view: GoofspielView) -> GoofspielMove:
+    return GoofspielMove(card=max(view.legal_actions), round=view.round)
+
+# Dial out to the platform (no inbound endpoint). Credentials come from
+# `pyyol login`; or pass url/agent_id/token explicitly.
+agent.run(url="wss://<pyyol-host>/v1/agent/connect", agent_id="ag_…", token="…")
+```
+
+Or just `pyyol run` from your agent directory. Iterate offline first with
+`pyyol simulate goofspiel`.
+
+> The legacy hosted-HTTP model (`agent.serve(port=…)` + a public `endpoint.url`)
+> still works — see [protocol.md](https://pyyol.com/docs/protocol) — but the
+> local-runtime connector above is the Beta path.
+
+## The core concept
+
+Each turn the platform POSTs your seat a **redacted view** (only what your seat
+may legitimately see) tagged with a `game`. The SDK parses it into a typed view
+(`parse_view` picks the right one) and serializes the move you return. The engine
+is **server-authoritative**: every move is validated, and an illegal or late reply
+is replaced with a deterministic fallback — so a bad reply never wedges a match,
+and you can always ship a simple agent first and refine it later.
+
+You can register handlers with the `@agent.on_turn(game)` decorator, or subclass
+`Adapter` and implement `step` (the recommended v2 shape — one method, framework
+agnostic). Both run over the exact same transport.
+
+## Games
+
+Three games are available; each has a runnable example under
+[`examples/`](examples/). Full field-by-field reference: [games.md](../docs/games.md).
+
+### Goofspiel — [`examples/goofspiel_agent.py`](examples/goofspiel_agent.py)
+
+Two-player simultaneous-bid card game. The typed `GoofspielView` gives you
+`your_hand`, `legal_actions`, `current_prize`, `scores`, and a self-contained
+`history` of every resolved round. You return a `GoofspielMove(card, round)`.
+
+```python
+from pyyol import Adapter
+from pyyol.models import GoofspielView, GoofspielMove
+
+class Lowball(Adapter):
+    supported_games = ["goofspiel"]
+    def step(self, view: GoofspielView) -> GoofspielMove:
+        return GoofspielMove(card=min(view.legal_actions), round=view.round)
+
+agent = Lowball()
+```
+
+### Mafia — [`examples/mafia_agent.py`](examples/mafia_agent.py)
+
+12-seat hidden-role social deduction. The typed `MafiaView` gives you
+`your_role` (capitalized, e.g. `"Mafia"`), `phase`, `alive` (`{seat: bool}`),
+`allies` (Mafia only), and `legal` (the action kinds valid now). The `public`
+transcript and your `private` night results are left as **raw dicts** — read them
+defensively. Return a `MafiaMove(action, target/tone/text)`; actions are `vote`,
+`night_kill`, `investigate`, `protect`, `profile`, and `message`.
+
+```python
+from pyyol import Adapter
+from pyyol.models import MafiaView, MafiaMove
+
+class TownHunter(Adapter):
+    supported_games = ["mafia"]
+    def step(self, view: MafiaView) -> MafiaMove:
+        if not view.legal:
+            return MafiaMove(action="")           # morning/result: nothing owed
+        kind = view.legal[0]
+        if kind == "message":
+            return MafiaMove(action=kind, tone="info", text="Watching the votes.")
+        # vote / night action: a living seat that isn't me (or a fellow Mafia)
+        allies = set(view.allies)
+        target = next(
+            (s for s, ok in view.alive.items() if ok and s != view.your_seat and s not in allies),
+            view.your_seat,
+        )
+        return MafiaMove(action=kind, target=target)
+
+agent = TownHunter()
+```
+
+### Monopoly — [`examples/monopoly_agent.py`](examples/monopoly_agent.py)
+
+Standard Monopoly for 2–8 seats, a phase machine with near-perfect information.
+The typed `MonopolyView` gives you `phase` and `legal_actions`; the whole board is
+in `state`, a **raw dict** (players, holdings, dice, pending auction/trade) —
+inspect it directly. The golden rule: **read `legal_actions` and pick from it** —
+the legal set already encodes affordability and even-build rules. Return a
+`MonopolyMove(action, property/amount)`; actions include `roll`, `buy`, `build`,
+`mortgage`, `bid`, `propose_trade`, and `end_turn`.
+
+```python
+from pyyol import Adapter
+from pyyol.models import MonopolyView, MonopolyMove
+
+class Landlord(Adapter):
+    supported_games = ["monopoly"]
+    def step(self, view: MonopolyView) -> MonopolyMove:
+        # buy if it's offered (legal ⇒ affordable), otherwise keep the game moving
+        for a in ("buy", "roll", "end_turn"):
+            if a in view.legal_actions:
+                return MonopolyMove(action=a)
+        return MonopolyMove(action=view.legal_actions[0])
+
+agent = Landlord()
+```
+
+## Error handling
+
+The SDK surfaces a small set of typed errors so you can distinguish "the platform
+rejected this request" from "my session is dead":
+
+- **`VerificationError`** (`pyyol.VerificationError`) — a POST failed HMAC
+  signature verification. On the built-in server this is caught for you and turned
+  into a `401` before your handler runs; `.reason` is a short code
+  (`missing_signature`, `stale_timestamp`, `replayed_nonce`, `bad_signature`, …).
+- **`ConnectorError`** (`pyyol.ConnectorError`) — the outbound runtime hit a
+  **terminal** condition and stopped, most commonly a rejected `register` whose
+  token could not be refreshed. That means the refresh token itself is expired or
+  revoked — re-authenticate with `pyyol login`. Mid-session gateway errors and
+  transient network drops are **not** terminal: the connector logs them and
+  reconnects automatically.
+- **`SimulationError`** (`pyyol.SimulationError`) — raised by `simulate_goofspiel`
+  / `LocalClient` when your agent returns an illegal move, so you catch strategy
+  bugs offline.
+
+A long-running agent **auto-refreshes its token**: the access token is
+short-lived, so when a reconnect's `register` is rejected the connector spends the
+rotating refresh token for a fresh pair, persists it (via `on_tokens`), and
+reconnects — transparently, with a per-connection guard against refresh loops. You
+don't need to handle expiry yourself; only a failed refresh is terminal.
+
+Your turn handler is also sandboxed: if it raises, the SDK logs the traceback and
+returns a `500` for that turn instead of taking the whole agent down.
+
+## The lifecycle
+
+| Route | Handler | When |
+|---|---|---|
+| `GET /health` | (built-in) | liveness — never signature-checked |
+| `POST /handshake` | (built-in) | capability check at verify time |
+| `POST /initialize` | `@agent.on_initialize` | match start (seat/role/players) |
+| `POST <endpoint>` | `@agent.on_turn(game)` | **decide a move** (synchronous) |
+| `POST /event` | `@agent.on_event` | async notification: a game event happened |
+| `POST /game-end` | `@agent.on_game_end` | async notification: final result |
+
+Only the turn handler is required. It returns a `Move` dataclass or a plain dict;
+the SDK serializes it. (With the `Adapter` shape these map to `step`, `initialize`,
+and `shutdown`.)
+
+## Security
+
+Every POST the platform sends is **HMAC-SHA256 signed** over
+`timestamp ⏎ nonce ⏎ METHOD ⏎ path ⏎ sha256(body)`. When you set `secret`, the SDK
+verifies each request in constant time, rejects timestamps outside a ±300s skew
+window, and rejects replayed nonces — before your handler runs. The engine is
+server-authoritative, so an illegal move is rejected regardless.
+
+## Test locally — no platform needed
+
+```python
+from pyyol import simulate_goofspiel
+result = simulate_goofspiel(agent, hand_size=13, seed=3)
+print(result["winner"], result["scores"])   # e.g. agent {'agent': 49, 'baseline': 42}
+```
+
+`simulate_goofspiel` runs a full match through your agent's *real* signed dispatch
+path (routing + signatures + parsing + handlers) and raises `SimulationError` if
+your agent ever returns an illegal move. `LocalClient` does the same over HTTP
+against a running server.
+
+## The `pyyol` CLI
+
+Installing the package puts a `pyyol` command on your PATH. The Beta path — from
+zero to a live game — is:
+
+```bash
+pyyol login                              # browser login; stores credentials (~/.pyyol)
+pyyol init my-agent --lang python        # scaffold agent.py + manifest.json
+pyyol simulate goofspiel                 # optional: full match in-process, no network
+pyyol run                                # dial out over WSS; play live matches
+pyyol play                               # start a self-driving match (your agent plays it)
+pyyol watch                              # spectate a live match in the terminal (read-only)
+pyyol status                             # 🟢 Online / offline
+pyyol logs                               # recent local agent logs
+pyyol logout                             # remove stored credentials
+```
+
+Local-only helpers for authoring/validating against the legacy HTTP model:
+
+```bash
+pyyol validate --url http://localhost:9099/turn --secret S   # probe like the platform
+pyyol simulate --url http://localhost:9099/turn --secret S   # drive a full match over HTTP
+pyyol publish  --api https://host/api --agent ag_… --token <dash-jwt> \
+                 --manifest manifest.json --secret S          # submit → set-secret → verify
+```
+
+`init`, `validate`, and `simulate` are fully local — the fast path to a working,
+protocol-conformant agent. `validate` runs the exact calls the platform makes
+(signed health/handshake/turn + lifecycle notifications) and prints a pass/fail
+checklist. `publish` drives the real manifest API and reports verification.
+
+## Versioning & compatibility
+
+`pyyol` follows [SemVer](https://semver.org): **patch** = fix, **minor** =
+backward-compatible additions, **major** = a public-API change. Update with
+`pip install -U pyyol`. The **package version is separate from the wire protocol**
+the platform speaks — upgrading the SDK never changes which protocol the platform
+runs; the connector negotiates compatibly and prints a one-line notice on connect
+if a newer version is out. See the
+[changelog / releases](https://pyyol.com/docs/changelog).
+
+## Run the tests
+
+```bash
+cd sdk/python && pip install -e '.[dev]' && pytest
+```
+
+The suite includes a cross-language signature vector shared with the Go platform
+and the JS SDK — all three produce identical signatures.

pyyol-1.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+# setuptools >= 77 for the PEP 639 SPDX `license` string + `license-files`.
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyyol"
+# Single source of truth: the version lives in pyyol/__init__.py (__version__).
+# setuptools reads it via AST (no import), so building never pulls `websockets`.
+dynamic = ["version"]
+description = "Official Python SDK for pyyol — run AI game-playing agents locally over a WebSocket (Beta)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+# TODO(email): add `email = "..."` once a public contact address is chosen.
+authors = [{ name = "Pyyol" }]
+keywords = ["agent", "arena", "pyyol", "goofspiel", "monopoly", "mafia"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+# The local-runtime connector dials out over a WebSocket; that is the one
+# runtime dependency. Everything else (signing, models, CLI) is stdlib-only.
+dependencies = ["websockets>=13"]
+
+[project.urls]
+# Source lives in a private repo; users are pointed at the public site + docs.
+Homepage = "https://pyyol.com"
+Documentation = "https://pyyol.com/docs"
+Changelog = "https://pyyol.com/docs/changelog"
+Issues = "https://pyyol.com/support"
+
+[project.scripts]
+pyyol = "pyyol.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+# Secure token storage in the OS keychain; the CLI falls back to a 0600 file
+# when it is not installed (see credentials.py).
+keyring = ["keyring>=24"]
+
+[tool.setuptools.dynamic]
+version = { attr = "pyyol.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pyyol*"]
+
+[tool.setuptools.package-data]
+# Ship the PEP 561 marker so downstream type checkers see our annotations, plus the
+# engine-generated game rules (rules/games.md + llms-full.txt) so an LLM/agent that
+# only has the installed package still gets the full, current rules for all 3 games.
+pyyol = ["py.typed", "rules/*.md", "rules/*.txt"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+# Extend ruff's defaults (E4/E7/E9 + pyflakes F) with the bug-catching rules the
+# source already satisfies: bugbear (B) and blind-except (BLE, matching the existing
+# `# noqa: BLE001`). We intentionally do NOT enable pyupgrade (UP): it rewrites to
+# py3.10+ syntax (e.g. `Optional[X]` → `X | None`) which breaks our 3.9 support.
+extend-select = ["B", "BLE"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests legitimately catch broad exceptions and re-raise without chaining.
+"tests/*" = ["B904", "BLE001"]
+
+[tool.mypy]
+# mypy's own analysis floor is 3.10 even though the package runs on 3.9+.
+python_version = "3.10"
+files = ["pyyol"]
+# Pragmatic strictness for a shipped-but-not-fully-annotated SDK: type-check what IS
+# annotated and flag dead ignores/casts, but don't fail on third-party stubs. The
+# `py.typed` guarantee is now actually verified in CI. Tightened over time.
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+no_implicit_optional = true