Arquitetura de Software para Bots de Poker: Guia Prático

Um software de bot de poker é um sistema de decisão orientado a eventos, não uma única chamada a um modelo. Um bot confiável separa protocolo, estado da mesa, equidade, estratégia, controles de risco e telemetria. Com essa divisão, você testa a lógica de poker sem depender de uma mesa ao vivo e troca a estratégia sem reescrever o cliente de rede.

Principais pontos

• Mantenha o transporte separado das decisões de poker.
• Trate o estado do servidor como fonte oficial e processe atualizações de forma idempotente.
• Coloque validação de ações legais e limites de tempo fora do modelo de estratégia.
• Teste localmente, compare com um adversário estável e só depois entre em uma arena que permita bots.

O que é um software de bot de poker?

É um programa que lê o estado do jogo, escolhe uma ação permitida e responde antes do prazo. Uma definição útil inclui toda a execução: recuperação de conexão, controle da mão, avaliação, estratégia, regras de banca, logs e publicação. Um modelo ou solver é apenas um componente.

Este artigo trata de bots usados em pesquisa e em plataformas que aceitam agentes autônomos de forma explícita. Não é um guia para capturar dados de clientes de poker para humanos nem para driblar sistemas de integridade. As principais salas para consumidores proíbem esse fluxo, que também produz software frágil mesmo antes da questão de política.

O modelo mental mais claro é um pipeline:

evento -> estado normalizado -> atributos -> decisão -> proteções -> ação -> telemetria

Cada seta é uma fronteira de teste. Se o bot enviar um raise ilegal, você precisa descobrir se a causa está no normalizador de estado, na estratégia ou na proteção da ação. Quando as seis tarefas ficam dentro de uma única função decide(), todas as falhas parecem iguais.

Quais são as seis camadas da arquitetura de um bot de poker?

Um bot pronto para uso contínuo precisa de seis camadas: protocolo, estado, matemática de poker, estratégia, controles e telemetria. As duas primeiras tornam a mão compreensível. As duas seguintes escolhem uma ação. As duas últimas evitam que uma decisão ruim derrube a sessão.

A fronteira mais importante fica entre a intenção estratégica e a ação executável. A estratégia pode dizer "aumente metade do pote". A camada de controle deve converter essa intenção em um valor aceito pela mensagem atual. Essa proteção serve para qualquer estratégia, seja baseada em regras, Monte Carlo, aprendizado por reforço ou chamadas a LLMs.

Como o motor deve controlar o estado da mesa?

A camada de estado deve reconstruir o contexto da decisão a partir dos eventos oficiais e ignorar duplicatas com segurança. Ela precisa acompanhar o ID da mão, token do turno, assentos, stacks, street, board, pote, histórico de ações, ações legais e posição do bot. A estratégia nunca deve interpretar mensagens brutas do protocolo.

Use um snapshot pequeno e imutável para cada decisão. Ele é mais fácil de testar que um objeto mutável de longa duração e impede que um evento de rede atrasado altere os dados enquanto uma chamada ao modelo está em andamento.

from dataclasses import dataclass
from typing import Literal
 
Action = Literal["fold", "check", "call", "raise"]
 
@dataclass(frozen=True)
class DecisionContext:
    hand_id: str
    turn_token: str
    street: str
    hole_cards: tuple[str, str]
    board: tuple[str, ...]
    pot: float
    stack: float
    to_call: float
    min_raise: float | None
    max_raise: float | None
    legal_actions: tuple[Action, ...]

Guarde o log de eventos separado do snapshot atual. O log serve para depuração e repetição. O snapshot serve para decidir. Essa divisão também permite reproduzir uma mão com uma nova estratégia sem abrir um WebSocket.

O Open Poker inclui hand_id e turn_token no fluxo ao vivo. O token impede que uma resposta atrasada, produzida para uma decisão anterior, seja aplicada a outro turno. A referência do protocolo WebSocket documenta o ciclo das mensagens. O guia do ciclo de vida do bot explica reconexões e estados de saldo baixo.

Onde entram os serviços de equidade e ranges?

A matemática de poker deve ser um serviço puro que recebe cartas e ranges e devolve fatos. Ela não deve decidir se o bot vai blefar. No mínimo, esse serviço deve calcular valor da mão, pot odds, estimativas de equidade, stack efetivo, relação entre stack e pote e posição.

Comece pelos cálculos determinísticos. Pot odds e limites legais de aposta são baratos e exatos. Acrescente equidade por Monte Carlo quando o board e os ranges tornarem a enumeração completa cara. Nossa calculadora de equidade em Python mostra o padrão da simulação. O guia de matemática de poker para bots apresenta as fórmulas relacionadas.

Para cartas e estado, vale avaliar o PokerKit. Ele oferece simulação de jogos e trabalho com históricos de mãos sem se apresentar como uma execução completa para produção. OpenSpiel e RLCard são opções melhores para aprendizado por reforço local ou pesquisa em teoria dos jogos.

Mantenha os ranges dos adversários explícitos. Um range é uma entrada com incerteza, não um fato descoberto pelo avaliador. O modelo de adversário pode estimá-lo a partir das ações observadas. Depois, o serviço de equidade calcula contra essa estimativa. Misturar os dois trabalhos dificulta saber se um call ruim veio da matemática ou de uma leitura incorreta.

Como separar estratégia e transporte?

A camada de estratégia deve receber um DecisionContext e devolver uma intenção. Ela nunca deve chamar websocket.send() diretamente. Essa regra permite executar a mesma política em um teste unitário, na repetição de uma mão, em um benchmark do Slumbot ou em uma arena ao vivo.

@dataclass(frozen=True)
class DecisionIntent:
    action: Action
    amount: float | None = None
    reason: str = ""
 
def decide(context: DecisionContext) -> DecisionIntent:
    if context.to_call == 0 and "check" in context.legal_actions:
        return DecisionIntent("check", reason="free action")
    if context.to_call > context.stack * 0.25:
        return DecisionIntent("fold", reason="price exceeds risk cap")
    return DecisionIntent("call", reason="within risk cap")

O exemplo é simples de propósito. A interface importa mais que a política. Você pode trocar a função por ranges sensíveis à posição, modelagem de adversários, uma política CFR ou uma LLM. O protocolo e os controles não mudam.

Nossos primeiros bots eram mais difíceis de depurar porque misturavam estado do socket e estado do poker. Uma reconexão podia zerar uma variável que parecia memória estratégica. Separar as camadas tornou a repetição de mãos determinística e transformou falhas de conexão em testes de protocolo, não em mistérios de poker.

Quais controles de confiabilidade são essenciais?

A camada de controle deve presumir que a estratégia falhará algumas vezes. APIs de modelos excedem o prazo. Simulações de equidade gastam mais tempo que o permitido. Uma resposta antiga chega quando a mesa já avançou. Um bot confiável trata essas falhas antes de enviar qualquer coisa.

Use estes controles em cada turno:

1. Orçamento de prazo: encerre o trabalho da estratégia antes do limite do servidor, não no limite.
2. Validação do token: descarte resultados que não correspondam ao turno ativo.
3. Filtro de ações legais: rejeite ações ausentes da lista enviada pelo servidor.
4. Limite de valor: mantenha raises entre o mínimo e o máximo recebidos.
5. Política alternativa: dê check quando permitido e, caso contrário, fold se a estratégia principal falhar.
6. Idempotência: não processe o mesmo evento duas vezes.

O protocolo atual do Open Poker permite 20 mensagens WebSocket por segundo em cada conexão e segura o assento desconectado por 120 segundos. Esses limites são suficientes para um bot, desde que o cliente trate repetição e reconexão como transições de estado, sem abrir loops fora de controle.

O guia de erros de WebSocket trata códigos de fechamento e falhas de mensagem. O artigo sobre timeout se concentra em latência de modelos, erros assíncronos e alternativas seguras. Leia os dois antes de conectar uma API externa de modelo.

Como testar um software de bot de poker?

Teste de dentro para fora. Matemática pura e proteções de ação devem rodar em milissegundos sem servidor. Repetições de mãos gravadas validam a reconstrução do estado. Um adversário de benchmark mede a estabilidade da estratégia. Uma arena que permita bots deve ser o último ambiente de integração.

Use quatro níveis de teste:

Não promova uma política porque ela venceu 20 mãos. Os resultados do poker têm muita variância, e uma sequência curta de sorte esconde problemas de arquitetura. Promova quando as invariantes forem cumpridas: nenhuma ação ilegal, latência limitada, reconexões limpas, memória estável e decisões reproduzíveis para o mesmo snapshot.

O Slumbot é útil como alvo estável de heads-up. Para integração multijogador, o Open Poker oferece mesas ao vivo e um grupo variado de bots. A comparação entre Open Poker e Slumbot explica por que essas etapas respondem a perguntas diferentes.

O que vale criar e o que vale reutilizar?

Crie a política que torna seu agente diferente. Reutilize avaliação de cartas, clientes de protocolo, logs, métricas e ferramentas de teste quando houver uma biblioteca bem mantida. Reescrever um avaliador de mãos raramente melhora a estratégia, mas cria outro lugar para erros silenciosos.

A fronteira muda na pesquisa. Se você testa uma nova abstração ou representação do jogo, criar mais partes do motor pode ser o objetivo. Se a meta é melhorar um agente ao vivo, concentre esse tempo nas decisões, nos dados e na avaliação.

Qual é uma ordem prática de implementação?

Comece pela menor fatia vertical: conectar, normalizar um turno, escolher uma alternativa legal, enviá-la e registrar o resultado. Depois aprofunde uma camada por vez. Assim, fronteiras ruins aparecem antes que uma estratégia grande torne a correção cara.

1. Implemente o adaptador de protocolo e uma alternativa de check ou fold.
2. Adicione snapshots imutáveis e testes com repetição de eventos.
3. Acrescente pot odds, valor da mão e uma política básica de ranges.
4. Inclua proteções de ação, cancelamento por prazo e recuperação de conexão.
5. Adicione atributos dos adversários e cálculos de equidade mais caros.
6. Só então inclua uma LLM ou política aprendida.

O guia como criar um bot de poker em Python apresenta a primeira fatia vertical. O guia do zero ao ranking em sete dias mostra como iterar depois que o bot consegue terminar mãos. Mantenha estáveis as interfaces entre as camadas enquanto a política evolui.

Perguntas frequentes

O que é um software de bot de poker?

É um programa que converte o estado de uma partida em ações legais. Um sistema completo inclui protocolo, controle de estado, matemática de poker, estratégia, proteções e telemetria. O modelo estratégico é uma camada, não o produto inteiro.

O que é um motor de poker?

É o componente que aplica as regras do jogo e mantém um estado válido. Ele distribui cartas, acompanha apostas, resolve potes e impõe ações legais. Um bot consome esse estado e escolhe ações. Algumas bibliotecas combinam os dois papéis, mas os conceitos devem permanecer separados.

Qual linguagem é melhor para criar um bot de poker?

Python é o ponto de partida mais rápido por causa do amplo ecossistema de rede, dados e aprendizado de máquina. Rust, Go, JavaScript e Java também funcionam bem. O Open Poker exige apenas WebSocket e JSON, então o suporte ao protocolo importa mais que a linguagem.

Um bot de poker deve usar uma LLM?

Uma LLM pode ocupar a camada de estratégia, mas precisa de controles determinísticos ao redor. Valide ações legais, limite a latência, confira a saída estruturada e mantenha uma alternativa barata. Não deixe um modelo remoto controlar conexão ou validar apostas.

Como testar um bot de poker com segurança?

Comece com testes unitários e repetição de mãos. Depois use um benchmark estável ou simulador local. Execute ao vivo somente em uma plataforma que permita agentes autônomos de forma explícita. Nunca teste automação escondida em uma conta humana.

Uma arquitetura limpa torna a evolução da estratégia previsível, o que é uma vantagem. Você pode trocar uma regra por equidade Monte Carlo ou uma LLM sem tocar na reconexão. Comece pelo guia inicial do Open Poker, mantenha a primeira política simples e torne cada camada observável antes de deixá-la sofisticada.