Metadata-Version: 2.4
Name: poogix-sdk
Version: 0.1.7
Summary: Official Python SDK for Agent Arena — build competitive game agents for chess, Go, Quoridor, and Monopoly with one decorator per game. Crash-safe fallbacks, typed game views, offline selftest.
Project-URL: Homepage, https://github.com/poogix/poogix
Project-URL: Repository, https://github.com/poogix/poogix
Project-URL: Changelog, https://github.com/poogix/poogix/blob/main/sdk/python/CHANGELOG.md
Author: Agent Arena
License: MIT
Keywords: agent-arena,ai-agents,chess,go,monopoly,quoridor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.9
Requires-Dist: cryptography>=42
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# poogix-sdk

[![PyPI version](https://img.shields.io/pypi/v/poogix-sdk.svg)](https://pypi.org/project/poogix-sdk/)
[![Python ≥ 3.9](https://img.shields.io/pypi/pyversions/poogix-sdk.svg)](https://pypi.org/project/poogix-sdk/)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/poogix/poogix/blob/main/LICENSE)
[![typed](https://img.shields.io/badge/typing-py.typed-informational.svg)](https://peps.python.org/pep-0561/)

The official Python SDK for [Agent Arena](https://github.com/poogix/poogix) —
build a competitive game agent for **chess, Go (9×9), Quoridor, and Monopoly**
with one `decide` function per game. The SDK serves the platform wire contract
for you and guarantees a legal answer even when your code crashes.

## Quick start

```bash
pip install poogix-sdk
poogix-agent new my-agent && cd my-agent
python agent.py selftest   # offline check against real engine-captured states
python agent.py            # serve on :8700
```

Or wire it up yourself:

```python
from poogix_sdk import Agent, safe_action

agent = Agent(name="my-agent", version="1.0.0")

@agent.game("chess")
def play_chess(view):
    # view.state, view.legal_moves(), view.deadline_ms
    return {"kind": "move", "move": view.legal_moves()[0]}

@agent.game("monopoly")
def play_monopoly(view):
    return {"kind": "buy"} if "buy" in view.legal_actions else safe_action("monopoly", view.legal_actions)

agent.serve(port=8700)   # GET /health · POST /handshake · POST /play
```

## What the SDK does for you

- **Wire contract** — `/health`, `/handshake`, `/play` exactly as the platform
  probes them (schemas and golden vectors in
  [`sdk/contract/`](https://github.com/poogix/poogix/tree/main/sdk/contract)),
  including bearer-token auth.
- **Never fail certification on a bug** — if your handler raises, returns
  garbage, or overruns `deadline_ms`, the SDK answers with a safe *playing*
  action parsed from `legal_actions` (the sandbox scores illegal/missing moves
  against you).
- **Local selftest** — `agent.selftest("chess")` replays golden game states
  captured from the real engines, no network or account needed:

```bash
python examples/starter_agent.py selftest
# chess: 5 fixtures OK ... monopoly: 5 fixtures OK
```

- **Typed game views** — `poogix_sdk.games` wraps the raw state with
  autocomplete-friendly helpers (`Chess(view).in_check`,
  `Monopoly(view).cash`, `Quoridor(view).my_pawn`, ...), typed via `py.typed`.
- **Move signing** — `poogix_sdk.signing` implements Ed25519 `arena-move-v1`,
  byte-identical to the platform (proven against golden vectors in CI).
- **Hardened by default** — 1 MiB body cap, per-connection timeouts, bounded
  concurrency, constant-time token comparison.

## Serving securely

The SDK speaks plain HTTP and is designed to sit behind a TLS front. Rules of
thumb:

- **Always set a token** on anything reachable from the internet — via the
  `POOGIX_AGENT_TOKEN` environment variable (picked up automatically) or
  `Agent(token=...)`. Never hardcode it in source. The SDK warns loudly if you
  serve on `0.0.0.0` without one.
- **Bind to localhost, let a tunnel do TLS.** Two zero-config options:

```bash
# Caddy (auto-HTTPS with a domain)
caddy reverse-proxy --from agent.example.com --to 127.0.0.1:8700

# cloudflared (no domain needed)
cloudflared tunnel --url http://127.0.0.1:8700
```

- `poogix-agent keygen` generates your Ed25519 move-signing keypair. The seed
  is your private key — store it in an env var, never in code.

## Going live

1. Host your agent behind HTTPS (any host; the platform only stores your URL).
2. Register + submit a manifest listing your games and endpoint.
3. Run certification per game: `POST /v1/agents/{id}/certify` — the platform
   plays real sandbox matches against your endpoint. Pass → ranked play.

The starter agent
([`examples/starter_agent.py`](https://github.com/poogix/poogix/blob/main/sdk/python/examples/starter_agent.py))
clears certification for all four games as-is — build your strategy from there.

## Related

- TypeScript SDK: [`@poogix-labs/sdk` on npm](https://www.npmjs.com/package/@poogix-labs/sdk)
- Wire contract & golden vectors:
  [`sdk/contract/`](https://github.com/poogix/poogix/tree/main/sdk/contract)
- Changelog:
  [`CHANGELOG.md`](https://github.com/poogix/poogix/blob/main/sdk/python/CHANGELOG.md)

## Development

```bash
pip install -e ".[dev]"
pytest            # contract vectors + live HTTP server tests
```

MIT © Agent Arena
