chipzen-bot 0.2.0__tar.gz

chipzen_bot-0.2.0/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+dist/
+build/
+
+# JavaScript / TypeScript
+node_modules/
+*.log
+.npm
+.pnpm-store/
+coverage/
+.next/
+.nuxt/
+.turbo/
+
+# Rust
+target/
+Cargo.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Local env
+.env
+.env.local
+.env.*.local
+.envrc
+
+# Credentials and secrets — defense in depth, the platform's threat
+# model assumes uploaded bot images carry no per-user secrets but a
+# leaked dotfile in a contributor's working tree is still bad.
+*.key
+*.pem
+*.cert
+*.crt
+secrets.*
+credentials.*
+.aws/credentials
+
+# Build artifacts
+*.tar.gz
+*.zip
+*.whl
+
+# CLA signatures storage
+.cla-signatures.json

chipzen_bot-0.2.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to the `chipzen-bot` Python SDK will be documented
+in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — Initial public release
+
+First release of `chipzen-bot` to PyPI. The package was previously
+developed inside the Chipzen platform repo and is now extracted to
+[chipzen-ai/chipzen-sdk](https://github.com/chipzen-ai/chipzen-sdk)
+as the canonical home.
+
+### Scope
+
+The published SDK is intentionally narrow:
+
+1. A **protocol adapter** (`chipzen.Bot` base class plus the WebSocket
+   client) so your bot doesn't hand-roll the wire protocol.
+2. A **`chipzen-sdk validate`** CLI that runs the same pre-upload
+   checks the platform performs (size, imports, sandbox-blocked
+   modules, `decide()` timeout sniff).
+3. (Forthcoming, in a follow-up release) An **IP-protected Dockerfile
+   recipe** — Cython multi-stage build that ships compiled `.so`
+   artifacts only, not your `.py` source.
+
+Local match simulation, hand evaluation, opponent pools, and
+bot-vs-bot strength testing are explicitly out of scope; the platform
+runs that evaluation post-upload. See the
+[README](README.md#what-the-sdk-is-for-and-what-it-isnt).
+
+### CLI surface
+
+Two commands. Both have detailed `--help` output.
+
+- `chipzen-sdk init <name>` — scaffold a new bot project from a
+  starter template.
+- `chipzen-sdk validate <path>` — pre-upload go/no-go.
+
+### Public API
+
+- **`chipzen.Bot`** — abstract base class (alias for
+  `chipzen.bot.ChipzenBot`). Override `decide(state) -> action`.
+  Optional lifecycle hooks: `on_match_start`, `on_round_start`,
+  `on_hand_start`, `on_phase_change`, `on_turn_result`,
+  `on_round_result`, `on_hand_result`, `on_match_end`.
+- **`chipzen.GameState`** — dataclass built from the server's
+  `turn_request` payload. Fields documented in the
+  [DEV-MANUAL §2.3](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/DEV-MANUAL.md#23-gamestate).
+- **`chipzen.Action`** — factory: `Action.fold()`, `Action.check()`,
+  `Action.call()`, `Action.raise_to(amount)`, `Action.all_in()`.
+  `Action.to_wire()` produces the two-layer `turn_action` params
+  schema.
+- **`chipzen.Card`** — `(rank, suit)` frozen dataclass.
+  `Card.from_str("Ah")` parses wire format; `str(card)` renders it.
+- **`chipzen.client.run_bot(...)`** — async runner that drives the
+  full WebSocket lifecycle (handshake, envelope sequence check,
+  ping/pong, `action_rejected` retry, reconnect, clean exit on
+  `match_end`).
+
+### Built-in example bots
+
+Importable as canonical `Bot` subclass examples (not as competitive
+opponents — there is no local match runner):
+
+- `chipzen.examples.call_bot.CallBot` — always calls.
+- `chipzen.examples.random_bot.RandomBot` — picks a uniform random
+  valid action.
+- `chipzen.examples.tight_aggressive.TightAggressiveBot` — simplified
+  TAG strategy.
+
+### Two-layer wire protocol
+
+The client speaks the Chipzen two-layer protocol (Layer 1 Transport +
+Layer 2 Poker) defined in
+[`docs/protocol/TRANSPORT-PROTOCOL.md`](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/protocol/TRANSPORT-PROTOCOL.md)
+and
+[`docs/protocol/POKER-GAME-STATE-PROTOCOL.md`](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/protocol/POKER-GAME-STATE-PROTOCOL.md).
+
+Highlights for clients written in other languages or for anyone
+debugging at the wire level:
+
+- The `run_bot` handshake sends `authenticate` first, waits for the
+  server `hello`, then sends the client `hello` with
+  `supported_versions=["1.0"]`.
+- Heartbeat: client replies to `ping` with `pong`.
+- `action_rejected`: SDK falls back to `check` (or `fold` if check is
+  not legal) using the original `request_id`.
+- `reconnected` messages with embedded `pending_request` are
+  dispatched as if they were fresh `turn_requests`.
+
+### License
+
+Apache-2.0 (changed from MIT in earlier internal builds — aligns with
+the chipzen-sdk repo's root LICENSE).

chipzen_bot-0.2.0/IP-PROTECTION.md

@@ -0,0 +1,115 @@
+# IP protection — what shipping a Cython-compiled bot does and doesn't do
+
+The Python starter at
+[`starters/python/`](starters/python/) ships a multi-stage Dockerfile
+that compiles `bot.py` to a Cython `.so` module in a builder stage,
+then copies only that compiled binary into the runtime image.
+
+This is the **alpha-tier IP-protection recipe**. Anything stronger is
+on the future-hardening list (see the bottom of this file).
+
+## What this protects against
+
+- **Casual source disclosure.** Anyone who somehow obtains read access
+  to your image (e.g., a misconfigured backup, a leaked tarball) can
+  no longer `cat bot.py` to see your strategy. The `.py` source is
+  discarded in the builder stage and never enters the runtime image.
+- **Direct copy-paste forks.** A compromised image can't be
+  re-uploaded as-is by a different account because the published
+  contents are obfuscated enough that the next reviewer would ask
+  questions. Not a hard guarantee, but a friction layer.
+- **Trivial introspection from inside a running container.** Even if
+  an attacker gains code execution inside your bot's container during
+  a match, they can't read your strategy directly — they'd be reading
+  C-extension memory, not Python source.
+
+## What this does NOT protect against
+
+- **Determined reverse engineering.** Cython compiles Python to C and
+  then to a `.so`. Decompilation is harder than reading Python source
+  but absolutely possible with disassemblers (Ghidra, Hex-Rays). A
+  motivated attacker with infinite time can recover your algorithm.
+  Treat this as "raises the cost", not "makes it impossible".
+- **The Chipzen platform owner.** The platform stores your uploaded
+  image in its own infrastructure. The platform owner can technically
+  inspect what you uploaded. This SDK assumes you trust the platform
+  with your image; if you don't, this Dockerfile won't help you.
+- **Side-channel leakage from observed gameplay.** Opponents who play
+  against your bot at the table will infer aspects of your strategy
+  from its actions, regardless of how the source was packaged. Bet
+  sizing, timing, action distributions, and showdown information are
+  all visible to opponents and the platform.
+- **The `requirements.txt` you ship.** Your dependency list is shipped
+  in the runtime image as plain text. If you depend on a unique
+  combination of solver / model libraries, the requirements.txt is a
+  meaningful tell. Strip it from the runtime image (after `pip install`
+  succeeds in the builder stage) if this matters to you.
+
+## Why this is sufficient for alpha
+
+The Chipzen platform's posture (see
+[`../../SECURITY.md`](../../SECURITY.md#bot-runtime--what-the-platform-enforces-on-uploaded-bots)
+for the full version):
+
+- Uploaded bot images go directly to platform-controlled storage,
+  encrypted at rest.
+- No public access to bot images.
+- Bot containers run with strict network egress controls — your
+  competitors can't pull your image while a match is running.
+
+Combined, the practical threat model for an alpha bot author is
+"casual access via an unexpected leak" rather than "well-resourced
+adversary with disassembler". Cython compilation handles the former.
+
+## How the recipe works (step by step)
+
+```
+Stage 1 (builder):
+  - python:3.12-slim @ <pinned digest>
+  - pip install cython==3.0.* setuptools
+  - COPY bot.py
+  - cythonize -i bot.py        # produces bot.cpython-312-<arch>-linux-gnu.so
+  - rm bot.py                  # remove the source so stage 2 cannot copy it
+
+Stage 2 (runtime):
+  - python:3.12-slim @ <same pinned digest>
+  - PYTHONUNBUFFERED=1, no .pyc emission, no pip cache
+  - pip install -r requirements.txt
+  - strip /usr/local/lib/python3.12/**/__pycache__ and **/tests
+  - COPY --from=builder /build/*.so /bot/
+  - non-root user (uid 10001)
+  - ENTRYPOINT ["python", "-c", "from bot import main; main()"]
+```
+
+The `from bot import main` form works because Python's standard
+import system finds `bot.cpython-312-<arch>-linux-gnu.so` and loads
+it as the module named `bot`. The `main()` callable inside the
+compiled module is whatever you defined in your `bot.py` before
+compilation.
+
+## Build-time / runtime Python ABI compatibility
+
+Cython output is ABI-specific. The builder and runtime stages must
+use the **same Python version + platform**. This Dockerfile pins
+both stages to identical `python:3.12-slim` digests so the ABI line
+up. If you change one, change both.
+
+If you want to ship for multiple Python versions or architectures
+(e.g., arm64 for Apple Silicon devs running locally), use Docker
+Buildx with `--platform=linux/amd64,linux/arm64` and a Dockerfile
+template that parameterizes the digest per platform.
+
+## Future hardening (not in alpha)
+
+The implementation plan calls these out as follow-ups, not blockers:
+
+- **Nuitka** instead of Cython for stronger optimization + harder
+  reverse engineering. Larger binaries, longer build times.
+- **PyArmor** obfuscation as a layer on top of Cython for
+  resistance against the easy decompilation paths.
+- **Encrypted-at-rest module loading** — the bot decrypts itself at
+  runtime using a per-match key the platform injects at launch. Adds
+  startup latency and requires platform-side coordination.
+- **ELF binary stripping** of the Cython output (`strip --strip-all`
+  on the `.so`) to remove debug symbols and harden against quick
+  symbol-table inspection. Easy to add when the platform supports it.

chipzen_bot-0.2.0/Makefile

@@ -0,0 +1,55 @@
+.PHONY: install dev lint format test build clean
+
+## Install the SDK in the current environment
+install:
+	pip install .
+
+## Install with development dependencies
+dev:
+	pip install -e ".[dev]"
+
+## Run linter (ruff check)
+lint:
+	ruff check src/ tests/
+
+## Auto-format code
+format:
+	ruff format src/ tests/
+
+## Run the test suite
+test:
+	pytest tests/ -v
+
+## Run tests with coverage
+coverage:
+	pytest tests/ -v --cov=chipzen --cov-report=term-missing
+
+## Build distribution packages
+build:
+	python -m build
+
+## Remove build artifacts
+clean:
+	rm -rf dist/ build/ *.egg-info src/*.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+
+## Validate that the scaffolded bot template passes checks
+validate-template:
+	@tmpdir=$$(mktemp -d) && \
+	chipzen-sdk init test_bot --dir "$$tmpdir" && \
+	chipzen-sdk validate "$$tmpdir/test_bot" && \
+	rm -rf "$$tmpdir"
+
+## Show help
+help:
+	@echo "Available targets:"
+	@echo "  install           Install the SDK"
+	@echo "  dev               Install with dev dependencies"
+	@echo "  lint              Run ruff linter"
+	@echo "  format            Auto-format code"
+	@echo "  test              Run test suite"
+	@echo "  coverage          Run tests with coverage"
+	@echo "  build             Build distribution packages"
+	@echo "  clean             Remove build artifacts"
+	@echo "  validate-template Validate the scaffolded bot template"

chipzen_bot-0.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: chipzen-bot
+Version: 0.2.0
+Summary: Build, test, and deploy poker bots for the Chipzen AI competition platform
+Project-URL: Homepage, https://chipzen.ai
+Project-URL: Documentation, https://chipzen.ai/docs/sdk
+Project-URL: Repository, https://github.com/chipzen-ai/chipzen-sdk
+Project-URL: Issues, https://github.com/chipzen-ai/chipzen-sdk/issues
+Project-URL: Changelog, https://github.com/chipzen-ai/chipzen-sdk/blob/main/packages/python/CHANGELOG.md
+Author-email: "Chipzen, Inc." <support@chipzen.ai>
+License-Expression: Apache-2.0
+Keywords: ai,bot,chipzen,competition,poker,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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 :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# chipzen-bot
+
+> [!WARNING]
+> **Alpha software.** This SDK is in active development; the public
+> API may change between minor versions before 1.0. Pin to a specific
+> version in production. Report issues at
+> [chipzen-ai/chipzen-sdk/issues](https://github.com/chipzen-ai/chipzen-sdk/issues).
+
+The Python adapter for the [Chipzen](https://chipzen.ai) AI poker
+competition platform. Wraps the WebSocket protocol so your bot only
+has to implement `decide(state) -> action`, and ships a `validate`
+CLI that confirms your bot will be accepted by the upload pipeline.
+
+## Install
+
+```bash
+pip install chipzen-bot
+```
+
+Python 3.10+ is supported. The runtime dependency is a single package
+(`websockets`); your bot can pull in whatever else it needs (numpy,
+torch, etc.) on top.
+
+## Minimal bot
+
+```python
+from chipzen import Bot, Action, GameState
+
+class MyBot(Bot):
+    def decide(self, state: GameState) -> Action:
+        if "check" in state.valid_actions:
+            return Action.check()
+        return Action.fold()
+
+if __name__ == "__main__":
+    MyBot().run()
+```
+
+The SDK handles the Layer-1 transport handshake, Layer-2 game-state
+parsing, ping/pong, request-id echoing, `action_rejected` retries,
+and reconnect. Subclass `Bot`, override `decide()`, return an
+`Action`. That's the entire surface for a working bot.
+
+Lifecycle hooks (`on_match_start`, `on_round_start`, `on_phase_change`,
+`on_turn_result`, `on_round_result`, `on_match_end`) are optional —
+override them if you need to maintain per-match or per-hand state
+between turns.
+
+## CLI
+
+The `chipzen-sdk` CLI is installed alongside the Python package:
+
+| Command | Purpose |
+|---|---|
+| `chipzen-sdk init <name>` | Scaffold a new bot project from a starter template. |
+| `chipzen-sdk validate <path>` | Run the same checks the upload pipeline runs (size, imports, sandbox-blocked modules, decide() timeout sniff). The supported go/no-go before docker packaging. |
+
+Run `chipzen-sdk <command> --help` for the full option list per command.
+
+## What the SDK is for (and what it isn't)
+
+The SDK does three things and nothing else:
+
+1. **Protocol adapter** — your bot doesn't hand-roll WebSockets.
+2. **`chipzen-sdk validate`** — pre-upload conformance check.
+3. **(Forthcoming) IP-protected Dockerfile recipe** — Cython
+   multi-stage build that produces an image containing only compiled
+   `.so` files, not your `.py` source.
+
+It does **not** include a local match simulator, hand evaluator, or
+opponent pool. Bot strength testing happens after upload; the platform
+runs comprehensive bot-vs-bot evaluation as part of the submission
+pipeline. If you want fast local iteration, write your own profiling
+harness that calls your `Bot.decide()` directly with recorded
+`GameState` objects.
+
+## Reference
+
+Full developer documentation lives in the [chipzen-sdk
+repo](https://github.com/chipzen-ai/chipzen-sdk):
+
+- [DEV-MANUAL](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/DEV-MANUAL.md)
+  — SDK reference, lifecycle hooks, performance budgets, container
+  contract, troubleshooting.
+- [QUICKSTART](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/QUICKSTART.md)
+  — write a bot, validate it, package it (~10 minutes).
+- [Protocol spec](https://github.com/chipzen-ai/chipzen-sdk/tree/main/docs/protocol)
+  — Layer 1 (Transport) + Layer 2 (Poker game state). Authoritative.
+- [Bot runtime security model](https://github.com/chipzen-ai/chipzen-sdk/blob/main/SECURITY.md)
+  — what the platform enforces on uploaded bots (sandbox, network
+  egress, resource limits).
+
+Per-package quickstart: [QUICKSTART.md](QUICKSTART.md).
+
+## License
+
+Apache-2.0. See the [LICENSE](https://github.com/chipzen-ai/chipzen-sdk/blob/main/LICENSE)
+file in the repo.

chipzen_bot-0.2.0/QUICKSTART.md

@@ -0,0 +1,75 @@
+# chipzen-bot quickstart
+
+The Python-specific path. For the broader story (Docker, upload, debugging on the platform) see the [top-level QUICKSTART](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/QUICKSTART.md).
+
+## 1. Install
+
+```bash
+pip install chipzen-bot
+```
+
+Python 3.10+. One runtime dependency (`websockets`).
+
+## 2. Scaffold a bot project
+
+```bash
+chipzen-sdk init my_bot
+cd my_bot
+```
+
+You'll get a small project with `main.py`, `requirements.txt`, and a Dockerfile.
+
+## 3. Implement your strategy
+
+Open `main.py`. The default scaffold gives you a `MyBot(Bot)` subclass
+with a no-op `decide()`. Replace it with your strategy:
+
+```python
+from chipzen import Bot, Action, GameState
+
+class MyBot(Bot):
+    def decide(self, state: GameState) -> Action:
+        # Your strategy. The SDK has already handed you a fully-parsed
+        # GameState (hole cards, board, pot, valid_actions, etc.) and
+        # is waiting on a single Action in return.
+        if "check" in state.valid_actions:
+            return Action.check()
+        return Action.fold()
+```
+
+The full `GameState` and `Action` surfaces are documented in the
+[DEV-MANUAL §2.3 / §2.4](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/DEV-MANUAL.md#23-gamestate).
+
+## 4. Validate before packaging
+
+```bash
+chipzen-sdk validate .
+```
+
+Runs the same checks the upload pipeline runs: artifact size, syntax,
+imports against the platform's sandbox-blocked module list, presence
+of a `Bot` subclass with a `decide()` method, a `decide()` timeout
+sniff, and a smoke instantiation. Exits non-zero on any failure.
+
+This is the **supported go/no-go** before you build a container image.
+A clean validate means "the upload pipeline will accept this on
+protocol grounds" — not "your bot is good".
+
+## 5. Package and upload
+
+The Docker build + upload steps are the same across all SDK languages.
+See the [top-level QUICKSTART](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/QUICKSTART.md)
+from step 5 onwards.
+
+## Where to go next
+
+- **Lifecycle hooks** (`on_match_start`, `on_round_start`,
+  `on_phase_change`, `on_turn_result`, `on_round_result`,
+  `on_match_end`) for per-match / per-hand state tracking — see
+  [DEV-MANUAL §2.2](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/DEV-MANUAL.md#22-bot-lifecycle-hooks).
+- **Performance budgets** (per-tier decision timeouts, queue drain
+  pitfalls) — see
+  [DEV-MANUAL §6](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/DEV-MANUAL.md#6-performance).
+- **Bot runtime security model** (sandbox, network egress, resource
+  limits) — see
+  [SECURITY.md](https://github.com/chipzen-ai/chipzen-sdk/blob/main/SECURITY.md#bot-runtime--what-the-platform-enforces-on-uploaded-bots).

chipzen_bot-0.2.0/README.md

@@ -0,0 +1,98 @@
+# chipzen-bot
+
+> [!WARNING]
+> **Alpha software.** This SDK is in active development; the public
+> API may change between minor versions before 1.0. Pin to a specific
+> version in production. Report issues at
+> [chipzen-ai/chipzen-sdk/issues](https://github.com/chipzen-ai/chipzen-sdk/issues).
+
+The Python adapter for the [Chipzen](https://chipzen.ai) AI poker
+competition platform. Wraps the WebSocket protocol so your bot only
+has to implement `decide(state) -> action`, and ships a `validate`
+CLI that confirms your bot will be accepted by the upload pipeline.
+
+## Install
+
+```bash
+pip install chipzen-bot
+```
+
+Python 3.10+ is supported. The runtime dependency is a single package
+(`websockets`); your bot can pull in whatever else it needs (numpy,
+torch, etc.) on top.
+
+## Minimal bot
+
+```python
+from chipzen import Bot, Action, GameState
+
+class MyBot(Bot):
+    def decide(self, state: GameState) -> Action:
+        if "check" in state.valid_actions:
+            return Action.check()
+        return Action.fold()
+
+if __name__ == "__main__":
+    MyBot().run()
+```
+
+The SDK handles the Layer-1 transport handshake, Layer-2 game-state
+parsing, ping/pong, request-id echoing, `action_rejected` retries,
+and reconnect. Subclass `Bot`, override `decide()`, return an
+`Action`. That's the entire surface for a working bot.
+
+Lifecycle hooks (`on_match_start`, `on_round_start`, `on_phase_change`,
+`on_turn_result`, `on_round_result`, `on_match_end`) are optional —
+override them if you need to maintain per-match or per-hand state
+between turns.
+
+## CLI
+
+The `chipzen-sdk` CLI is installed alongside the Python package:
+
+| Command | Purpose |
+|---|---|
+| `chipzen-sdk init <name>` | Scaffold a new bot project from a starter template. |
+| `chipzen-sdk validate <path>` | Run the same checks the upload pipeline runs (size, imports, sandbox-blocked modules, decide() timeout sniff). The supported go/no-go before docker packaging. |
+
+Run `chipzen-sdk <command> --help` for the full option list per command.
+
+## What the SDK is for (and what it isn't)
+
+The SDK does three things and nothing else:
+
+1. **Protocol adapter** — your bot doesn't hand-roll WebSockets.
+2. **`chipzen-sdk validate`** — pre-upload conformance check.
+3. **(Forthcoming) IP-protected Dockerfile recipe** — Cython
+   multi-stage build that produces an image containing only compiled
+   `.so` files, not your `.py` source.
+
+It does **not** include a local match simulator, hand evaluator, or
+opponent pool. Bot strength testing happens after upload; the platform
+runs comprehensive bot-vs-bot evaluation as part of the submission
+pipeline. If you want fast local iteration, write your own profiling
+harness that calls your `Bot.decide()` directly with recorded
+`GameState` objects.
+
+## Reference
+
+Full developer documentation lives in the [chipzen-sdk
+repo](https://github.com/chipzen-ai/chipzen-sdk):
+
+- [DEV-MANUAL](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/DEV-MANUAL.md)
+  — SDK reference, lifecycle hooks, performance budgets, container
+  contract, troubleshooting.
+- [QUICKSTART](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/QUICKSTART.md)
+  — write a bot, validate it, package it (~10 minutes).
+- [Protocol spec](https://github.com/chipzen-ai/chipzen-sdk/tree/main/docs/protocol)
+  — Layer 1 (Transport) + Layer 2 (Poker game state). Authoritative.
+- [Bot runtime security model](https://github.com/chipzen-ai/chipzen-sdk/blob/main/SECURITY.md)
+  — what the platform enforces on uploaded bots (sandbox, network
+  egress, resource limits).
+
+Per-package quickstart: [QUICKSTART.md](QUICKSTART.md).
+
+## License
+
+Apache-2.0. See the [LICENSE](https://github.com/chipzen-ai/chipzen-sdk/blob/main/LICENSE)
+file in the repo.