Case study案例研究

Counterplay · 过招

A real-time GTO trainer for iOS — built entirely on Pokerai API. Zero cached strategy, one thin client, 10 of the 12 endpoints. This is the same API you get.一款 iOS 实时 GTO 陪练——完全构建在 Pokerai API 上。零缓存策略,一个薄客户端,用了 12 个端点里的 10 个。用的就是你能拿到的这套 API。

What it does它做什么

Every hand, Hero takes a random seat at a 6-max 100bb table against five pure-GTO opponents. Counterplay records each of Hero's decisions, calls Pokerai API for the GTO frequencies at that exact spot, and grades the chosen action by its GTO frequency (a low-frequency action = a bigger deviation). An optional LLM coach then explains the spot and summarizes leaks across hands. When one hand ends, the next begins.每一手,Hero 在 6-max 100bb 桌随机座位,对阵五个纯 GTO 对手。过招记录 Hero 的每个决策,对该局面向 Pokerai API 取 GTO 频率,再按「所选动作的 GTO 频率」给决策评级(低频动作=更大偏移)。可选的 LLM 教练随后讲解局面并跨手总结漏洞。一手打完,自动开下一手。

Architecture架构

The engine (PokerKit) runs the table; the backend tracks game state and asks Pokerai API for strategy at each decision — directly, with no cache. The entire strategy layer is one file, app/gto/client.py, 270 lines.引擎(PokerKit)驱动牌桌;后端跟踪牌局状态,在每个决策点直连 Pokerai API 取策略——零缓存。整个策略层就一个文件 app/gto/client.py,270 行。

Which endpoint powers which part每个端点驱动哪一块

Traced from the real client (method → endpoint → where it's used):取自真实客户端(方法 → 端点 → 用途):

Endpoint	Client method客户端方法	Used for用途
/v1/gto/preflop	preflop()	Villain preflop actions + grading Hero's preflop decision对手翻前动作 + Hero 翻前决策评级
/v1/gto/preflop/range	preflop_range()	The 13×13 range grid shown in review复盘里的 13×13 范围网格
/v1/gto/flop/tree	flop_tree()	Postflop decision tree for the flop spot翻牌局面的翻后决策树
/v1/gto/flop/node	flop_node()	Strategy at the current flop node (+ grading)当前翻牌节点策略(+评级)
/v1/gto/flop/projected-range	projected_range()	Update ranges along the flop action line沿翻牌行动线更新范围
/v1/gto/range	range_convert()	Assemble solver_results for an action line为行动线组装 solver_results
/v1/gto/turn/projected-range	turn_projected_range()	Flop → turn range handoff翻牌 → 转牌范围交接
/v1/gto/solver	solver_schedule()	Submit a turn/river spot for real-time solving提交转/河牌局面实时求解
/v1/gto/solver/tree	solver_tree()	Decision tree of the solved turn/river spot已解转/河牌局面的决策树
/v1/gto/solver/node	solver_node()	Strategy at a turn/river node (+ grading)转/河牌节点策略(+评级)

The one unused endpoint is /v1/gto/preflop/versions — Counterplay is fixed to 6-max 100bb, so it never enumerates depths.唯一没用到的是 /v1/gto/preflop/versions——过招固定 6-max 100bb,无需枚举深度。

The whole strategy layer整个策略层

One Bearer key, thin typed methods, one shared retry/timeout wrapper. Verbatim from app/gto/client.py:一把 Bearer Key、薄类型方法、一个共享的重试/超时封装。摘自 app/gto/client.py 原文:

class GtoClient:
    def __init__(self, settings):
        self._headers = {"Authorization": f"Bearer {settings.gto_api_key}"}

    async def preflop(self, hole_cards, hero_pos, preflop_actions):
        body = {"hole_cards": hole_cards,
                "positions": {"hero": hero_pos},
                "preflop_actions": preflop_actions}
        return _strategy_from(await self._post("/v1/gto/preflop", body))

    async def flop_node(self, node_token, hole_cards=None):
        body = {"node": node_token}
        if hole_cards: body["hole_cards"] = hole_cards
        return _strategy_from(await self._post("/v1/gto/flop/node", body))
    # … + solver_schedule / solver_tree / solver_node, all one-liners over _post()

The decision loop决策循环

1. Preflop: feed the table's actions to /v1/gto/preflop; grade Hero's choice by its returned frequency.翻前:把桌上动作喂给 /v1/gto/preflop;按返回频率给 Hero 的选择评级。
2. Flop: get the presolved tree (/flop/tree), walk to the current node (/flop/node), grade again.翻牌:取预解树(/flop/tree),走到当前节点(/flop/node),再评级。
3. Turn/river: hand off the range (/turn/projected-range), submit to the real-time solver (/solver), poll, then read the node (/solver/node).转/河牌:交接范围(/turn/projected-range),提交实时求解(/solver),轮询,再读节点(/solver/node)。
4. Grade & explain: deviation = how far Hero's action sits from GTO frequency; an LLM coach turns that into plain-language feedback.评级+讲解:偏移=Hero 动作离 GTO 频率有多远;LLM 教练把它转成人话反馈。