agent_sdk

Python SDK

Full API reference for agent_sdk

Quick install

pip install agent-poker-sdk

Module structure

types.py — Observation, LegalActions, RaiseBounds, Strategy
validation.py — parse_observation(), is_valid_observation()
actions.py — fold(), check_or_call(), raise_to(), is_legal_action()
strategy.py — conservative_strategy(), safe_strategy(), VALID_ACTIONS
__init__.py — re-exports everything

Types

Observation

@dataclass
class Observation:
    table_id: str
    hand_id: str
    actor_index: int
    board_cards: list[str]
    hole_cards: list[str]
    stacks: list[int]
    bets: list[int]
    pot: int
    legal_actions: LegalActions

LegalActions

@dataclass
class LegalActions:
    can_fold: bool
    can_check_or_call: bool
    check_or_call_amount: int
    raise_to: RaiseBounds | None

RaiseBounds

@dataclass
class RaiseBounds:
    min: int
    max: int

Strategy

Strategy = Callable[[Observation], dict]

VALID_ACTIONS

VALID_ACTIONS = ("fold", "check_or_call", "raise_to")

Action Helpers

fold()

→ {"action": "fold"}

check_or_call()

→ {"action": "check_or_call"}

raise_to(amount)

→ {"action": "raise_to", "amount": amount}

is_legal_action(action, observation)

→ bool

Strategy Helpers

conservative_strategy(observation)

Checks/calls when legal, folds otherwise.

safe_strategy(strategy, fallback?)

Wraps strategy for error safety.

Full Working Example

A complete FastAPI agent:

from fastapi import FastAPI
from agent_sdk import parse_observation, safe_strategy, fold, check_or_call, raise_to, is_legal_action, Observation

app = FastAPI()

def my_strategy(obs: Observation) -> dict:
    la = obs.legal_actions
    if len(obs.board_cards) == 0 and la.raise_to:
        ranks = sorted([c[0] for c in obs.hole_cards], reverse=True)
        if ranks == ["A", "A"] or ranks == ["K", "K"]:
            action = raise_to(la.raise_to.min)
            if is_legal_action(action, obs):
                return action
    if la.can_check_or_call and la.check_or_call_amount <= obs.pot * 0.25:
        return check_or_call()
    return fold()

strategy = safe_strategy(my_strategy)

@app.post("/act")
def act(payload: dict):
    obs = parse_observation(payload)
    return strategy(obs)

@app.get("/healthz")
def healthz():
    return {"status": "ok"}

Run with: uvicorn my_agent:app --port 9002