Tutorial de PokerKit para bots de pôquer: avalie mãos de verdade

PokerKit é a evolução mais rápida depois que você conecta seu primeiro bot ao Open Poker. O exemplo inicial de 47 linhas comprova que o loop WebSocket funciona; PokerKit acrescenta avaliação de mãos, análise do board e recursos de simulação. Use a biblioteca para tomar decisões e mantenha o protocolo WebSocket do Open Poker para competir.

Parte de: O guia completo para construir um bot de IA para poker em 2026 - a referência do curso sobre ferramentas, lógica de decisão, equidade, testes e onde competir.

Principais conclusões

• PokerKit é uma biblioteca de pôquer escrita inteiramente em Python com avaliação de mãos, simulações e suporte para Texas Hold'em.
• Use PokerKit dentro de sua função de decisão, não como um substituto para o cliente WebSocket Open Poker.
• Comece convertendo as strings das cartas do Open Poker no formato compacto do PokerKit e, em seguida, compare os objetos StandardHighHand.

O que PokerKit deve fazer dentro do seu bot

PokerKit deve responder a uma pergunta: “Qual é a força da minha mão neste momento?” O servidor do Open Poker envia o estado do jogo por WebSocket, enquanto PokerKit avalia as cartas localmente. A documentação do PokerKit registra 1.016.740,7 avaliações padrão de high hand por segundo em um único núcleo Intel i7-1255U com Python 3.11.5 (documentação do PokerKit).

Esse desempenho é suficiente para decisões comuns no Open Poker, pois a plataforma oferece 45 segundos antes que uma ação expire (documentação de ações do Open Poker). A primeira melhoria não exige uma rede neural. Basta parar de tratar ace-high e flush como casos equivalentes de “dar call se estiver barato”.

As responsabilidades se dividem assim:

Se você ainda está escrevendo seu primeiro loop de eventos, comece com Construa um Bot de Pôquer em Python. Volte aqui assim que o bot puder sentar-se à mesa sem expirar.

Como você instala PokerKit para um bot

Instale PokerKit com pip install pokerkit. O README PokerKit atual diz que a biblioteca requer Python 3.11 ou superior e é Python puro, portanto, ela se ajusta ao mesmo modelo de implantação de um bot Open Poker normal (PokerKit GitHub).

python -m venv .venv
. .venv/bin/activate
pip install websockets pokerkit

Mantenha websockets para a conexão com o Open Poker. PokerKit não faz login, não entra no lobby e não envia ações. Ele ajuda a analisar as cartas depois que o servidor envia uma mensagem your_turn.

O protocolo do Open Poker representa as cartas como Ah, Kd e 7c. PokerKit aceita as mesmas strings compactas de valor e naipe. Portanto, você pode transformar uma lista do Open Poker em uma string do PokerKit com uma simples junção:

def compact(cards):
    return "".join(cards)
 
assert compact(["Ah", "Kd"]) == "AhKd"

A documentação do PokerKit observa que processar strings repetidamente custa caro em loops críticos. Para o primeiro bot, isso não será um problema. Quando você passar a executar milhares de simulações de Monte Carlo por decisão, faça o parsing uma vez ou use cache de forma mais agressiva.

Como você avalia uma mão de Texas Hold'em

Use StandardHighHand.from_game(hole, board) para Texas Hold'em No-Limit comum. Open Poker é NLHE 6-max com blinds 10/20 e buy-ins de 1.000 a 5.000 fichas (documentao da temporada), então a avaliação padrão de mão alta é o padrão correto.

from pokerkit import StandardHighHand
 
 
def made_hand(hole_cards, board_cards):
    """Return the best standard high hand from hole cards plus board."""
    hole = "".join(hole_cards)
    board = "".join(board_cards)
    return StandardHighHand.from_game(hole, board)
 
 
hero = made_hand(["As", "Ah"], ["Ad", "7c", "2d", "9h", "Ks"])
villain = made_hand(["Kc", "Kh"], ["Ad", "7c", "2d", "9h", "Ks"])
 
if hero > villain:
    print("hero wins")

Essa comparação é o ponto central. Os objetos de mão do PokerKit aceitam operadores comuns de comparação, permitindo classificar resultados sem escrever regras manuais como “um par vence ace-high”.

Não refine demais essa lógica no início. No flop, duas cartas ainda estão por vir, portanto a maioria das decisões não depende apenas da força da mão feita. Use essa força nos casos óbvios e depois acrescente estimativas de equidade para draws e calls marginais. É aí que o PokerKit se torna especialmente útil.

Como você conecta PokerKit em your_turn

Execute PokerKit dentro do branch your_turn, depois de armazenar em cache suas últimas cartas fechadas. A mensagem WebSocket your_turn inclui valid_actions, pot, community_cards, min_raise, max_raise e um novo turn_token (documentos WebSocket).

from pokerkit import StandardHighHand
 
 
def current_hand_label(hole_cards, board_cards):
    if len(board_cards) < 3:
        return "preflop"
    hand = StandardHighHand.from_game("".join(hole_cards), "".join(board_cards))
    return str(hand)
 
 
def choose_action(msg, hole_cards):
    actions = {a["action"]: a for a in msg["valid_actions"]}
    board = msg.get("community_cards", [])
 
    # Preflop still needs ranges, not a made-hand evaluator.
    if len(board) == 0:
        if "raise" in actions and is_premium_preflop(hole_cards):
            return "raise", actions["raise"]["min"]
        if "check" in actions:
            return "check", None
        return "fold", None
 
    hand = StandardHighHand.from_game("".join(hole_cards), "".join(board))
    label = hand.entry.label.name
 
    if label in {"STRAIGHT_FLUSH", "FOUR_OF_A_KIND", "FULL_HOUSE", "FLUSH"}:
        if "raise" in actions:
            return "raise", actions["raise"]["min"]
        if "call" in actions:
            return "call", None
 
    if "check" in actions:
        return "check", None
    return "fold", None

Isso é intencionalmente conservador. Ele desiste demais, mas não doará stacks com o par mais baixo. Uma vez executado, combine-o com estratégia de apostas de bot de pôquer para que mãos fortes aumentem para um tamanho útil em vez de sempre clicar no mínimo.

Quando adicionar equidade em vez de rótulos

Adicione equidade quando uma categoria simples esconder diferenças importantes. Um flush draw e um par feito podem ser lucrativos em situações distintas, mas um bot orientado apenas pelo nome da mão interpretará mal pelo menos uma delas. Com PokerKit, você pode simular as cartas desconhecidas do turn e do river em vez de adivinhar.

O caminho mais simples é:

1. Construa um baralho de 52 cartas.
2. Remova cartas de herói e cartas visíveis do board.
3. Amostras de cartas fechadas do oponente e cartas faltantes da mesa.
4. Compare as mãos finais de PokerKit.
5. Repita 1.000 a 10.000 vezes.

Isso lhe dá uma probabilidade estimada de vitória. Em seguida, compare com as probabilidades do pote:

def pot_odds(pot, call_amount):
    return call_amount / (pot + call_amount)
 
 
def should_call(pot, call_amount, equity):
    return equity > pot_odds(pot, call_amount)

Open Poker já envia o valor do pote e do call em valid_actions, então você não precisa reconstruir a rodada de apostas. Para a implementação completa de equidade, leia Calculadora de equidade de pôquer com Monte Carlo em Python.

Para que você não deve usar PokerKit

Não use PokerKit como substituto de testes ao vivo. A biblioteca consegue dizer se uma mão vence outra, mas não se os oponentes foldam demais para apostas no river, defendem o big blind com mãos demais ou entregam o stack depois de um blefe fracassado. Open Poker existe porque simulações isoladas não revelam esses padrões.

Também não simule toda a mesa do Open Poker localmente sem uma razão específica. O servidor é a fonte de verdade. O bot deve reagir a your_turn, enviar ações válidas com o turn_token atual e usar client_action_id para deduplicação. Reconstruir todo o estado da mesa tende a adicionar bugs antes de trazer qualquer vantagem.

Uma boa primeira forma de produção é:

WebSocket message
  -> parse visible state
  -> PokerKit evaluates cards
  -> policy chooses action
  -> send action with turn_token
  -> log result for later review

Essa estrutura basta para superar a maioria dos bots iniciantes. Depois, você pode adicionar ranges por posição, modelagem de oponentes e gestão de stack, um recurso por vez.

O que você deve registrar após adicionar PokerKit

Registre a categoria da mão, a street, a ação e o resultado final. Open Poker expõe o fluxo público pelo WebSocket e as estatísticas da temporada pelo painel e pela API, mas somente o seu log de decisões explica por que o bot agiu. Sem esse registro, até um avaliador melhor continuará parecendo uma caixa preta.

Comece com uma linha JSON por decisão:

def log_decision(msg, hole_cards, action, amount, hand_label):
    row = {
        "hand_id": msg.get("hand_id"),
        "street": "river" if len(msg.get("community_cards", [])) == 5 else "postflop",
        "hole": hole_cards,
        "board": msg.get("community_cards", []),
        "pot": msg["pot"],
        "hand": hand_label,
        "action": action,
        "amount": amount,
    }
    print(json.dumps(row))

Depois de 200 a 500 mãos, agrupe os logs por hand e action. Assim você verá se o bot está foldando pares com frequência demais diante de apostas pequenas ou dando raise com flushes, mas apenas call com full houses.

Esse processo também evita mudar cinco coisas ao mesmo tempo. Adicione PokerKit, execute uma amostra, compare o resultado com o bot antigo e altere apenas um ramo da política. O avaliador deve facilitar a depuração do bot, não dificultá-la.

Perguntas frequentes

PokerKit é melhor do que escrever meu próprio avaliador

Sim para quase todos os bots Open Poker. PokerKit fornece avaliação de mãos de Hold'em testadas, oferece suporte a operadores de comparação e relata 99% de cobertura de código em seu README. Seu tempo é melhor gasto em estratégia, registro e política pós-flop.

O PokerKit pode se conectar diretamente ao Open Poker

Não. Open Poker usa WebSocket e JSON para as partidas ao vivo. PokerKit é uma biblioteca Python local para avaliar mãos e simular cartas. Use os dois: WebSocket para a arena e PokerKit para as decisões.

Devo usar PokerKit ou OpenSpiel

Use PokerKit se estiver construindo um bot ativo. Use o OpenSpiel se estiver pesquisando algoritmos em muitos jogos. OpenSpiel é uma excelente infraestrutura de pesquisa, mas PokerKit é mais simples quando a tarefa é “avaliar essas cartas Hold'em agora mesmo”.

O PokerKit torna um bot lucrativo por si só

Não. Um avaliador de mãos evita erros óbvios, mas o lucro depende da seleção de ranges, do sizing, da modelagem de oponentes e da gestão de bankroll. Adicione PokerKit primeiro e depois leia ranges de posição para bots de pôquer.