Arquitetura Profissional de Poker Bots: Resiliência

Um poker bot profissional é um serviço avaliado, não uma função de estratégia enorme. Ele se reconecta sem fazer suposições, descarta trabalho obsoleto, degrada com segurança quando dependências falham e consegue provar qual policy produziu cada ação. O teto estratégico importa, mas uma operação autônoma é conquistada com recuperação, observabilidade e lançamentos disciplinados.

Série sobre arquitetura de poker bots: Parte 3 de 3. Crie o núcleo confiável em Arquitetura Básica de Poker Bots e depois adicione equidade e testes de replay com Arquitetura Avançada de Poker Bots. Planeje o orçamento do runtime com Custo de um Poker Bot em 2026.

O que diferencia um poker bot profissional de um avançado?

Um poker bot profissional trata cada componente como sujeito a falhas e cada mudança de estratégia como um experimento. O bot avançado consegue calcular equidade e se adaptar aos oponentes. O bot profissional pode perder a conexão durante esse cálculo, recuperar o estado oficial da mesa, rejeitar o resultado que ficou obsoleto, escolher um fallback seguro e deixar uma trilha de auditoria que explique a sequência.

A diferença aparece nas responsabilidades. Um supervisor é responsável pela máquina de estados da sessão. Um coordenador de turnos é responsável por prazos e cancelamentos. Workers da policy são responsáveis pelo processamento, mas não podem escrever no socket. Uma proteção é responsável pelas ações executáveis. A telemetria observa o caminho sem alterá-lo. As ferramentas de lançamento decidem qual policy assinada e versionada recebe tráfego.

Mais infraestrutura não é automaticamente algo profissional. Todo sistema adicionado precisa ter uma falha que ele evita e uma métrica que prove seu funcionamento.

Como devem funcionar a reconexão e a ressincronização?

A reconexão deve reconstruir o estado oficial do servidor antes que a estratégia continue. Mantenha o último table_id e o maior table_seq processado. Depois de abrir o socket com a mesma chave de API, envie resync_request com esses valores quando uma sessão de mesa ainda puder existir. Aplique os eventos repetidos em sequência e depois substitua o estado derivado da mesa pelo snapshot novo.

O Open Poker mantém o assento desconectado por 120 segundos. Essa é uma janela de recuperação, não um tempo recomendado de espera. Tente novamente rapidamente com backoff exponencial limitado e jitter, pois clientes simultâneos se reconectando em intervalos fixos podem causar uma sobrecarga repentina. O guia do ciclo de vida do bot documenta a janela do assento, e o protocolo WebSocket define resync_request, resync_response e table_state.

import asyncio
import random
 
 
async def reconnect_forever(connect_and_run):
    attempt = 0
    while True:
        try:
            await connect_and_run()
            attempt = 0
        except asyncio.CancelledError:
            raise
        except Exception as exc:
            cap = min(8.0, 0.25 * (2 ** attempt))
            delay = random.uniform(0.0, cap)
            record_disconnect(type(exc).__name__, delay)
            await asyncio.sleep(delay)
            attempt = min(attempt + 1, 6)

O tratamento da sequência deve ser idempotente. Ignore um evento cujo table_seq seja igual ou inferior à última sequência aplicada. Se uma nova sequência saltar à frente, solicite a ressincronização em vez de preencher a lacuna com suposições. O snapshot é oficial, e o log de eventos fornece o histórico necessário ao modelo de oponente.

Como orçamentos de prazo impedem ações obsoletas?

Orçamentos de prazo dividem um turno em etapas medidas e reservam tempo para validação e entrega pela rede. Atualmente, o Open Poker permite 120 segundos antes de um check ou fold automático, mas um bot profissional não deve consumir toda essa janela. Uma chamada ao modelo que trava impede a recuperação útil e reduz o número de mãos por hora.

Defina um objetivo interno de serviço com base no seu runtime. Uma meta razoável é um orçamento de decisão de 2 segundos para regras comuns ou chamadas ao modelo, dividido em 100 ms para normalização e características, 1.500 ms para a policy, 100 ms para validação e 300 ms de reserva para entrega. O timeout da plataforma continua sendo uma proteção externa.

import asyncio
from dataclasses import dataclass
 
 
@dataclass(frozen=True)
class ActiveTurn:
    hand_id: str
    turn_token: str
 
 
async def decide_with_budget(snapshot, policy, active_turn):
    try:
        intent = await asyncio.wait_for(policy(snapshot), timeout=1.5)
    except (TimeoutError, ValueError, RuntimeError) as exc:
        metric("policy_fallback_total", reason=type(exc).__name__)
        intent = safe_fallback(snapshot)
 
    if ActiveTurn(snapshot.hand_id, snapshot.turn_token) != active_turn():
        metric("stale_decision_total")
        return None
    return guard(intent, snapshot)

O cancelamento precisa se propagar. asyncio.wait_for, do Python, cancela trabalhos que excedem o prazo, mas código síncrono intensivo em CPU não devolve o controle ao loop de eventos. Execute simulações pesadas em um processo worker ou use uma implementação nativa limitada. A documentação de tarefas do asyncio explica o comportamento do cancelamento. Teste-o com uma policy que trava de propósito, não apenas com uma fixture unitária rápida.

Como devem funcionar o isolamento de falhas e os fallbacks?

O isolamento de falhas impede que inteligência opcional derrube o jogo obrigatório. Coloque modelos remotos, grandes simulações de equidade, armazenamento de oponentes e exportadores analíticos atrás de interfaces estreitas com timeout. O loop da sessão e a proteção de ações legais precisam continuar disponíveis quando os quatro estiverem fora do ar.

Use uma sequência de fallbacks, ordenada por custo e dependência:

1. Policy principal, aprendida ou assistida por modelo.
2. Policy local de range e equidade com orçamento curto de processamento.
3. Regras determinísticas de posição e preço.
4. Check quando legal, senão fold.

Cada descida incrementa uma métrica rotulada e aparece no registro da decisão. Um circuit breaker deve parar de chamar um serviço remoto com falhas depois de atingir um limite, aguardar um período de recuperação e então testar com requisições limitadas. Repetir três vezes a chamada ao mesmo modelo dentro de um turno costuma ser pior do que usar o fallback uma vez. Isso acumula latência e pode multiplicar os custos.

A proteção continua depois da sequência. Um fallback ainda pode conter um bug. Valide se a ação pertence à lista, restrinja os valores de raise aos limites mínimo e máximo atuais do servidor, exija hand_id e token atuais e gere um novo client_action_id. O guia de depuração de timeouts cobre caminhos comuns de falha assíncrona e do modelo.

De qual observabilidade um poker bot profissional precisa?

Um poker bot profissional precisa de logs, métricas e traces correlacionados no nível de cada decisão. Use hand_id como chave de correlação do poker e client_action_id como chave de entrega da ação. Adicione ID da sessão, ID da mesa, hash do token de turno, versão da policy, versão do schema de características, versão do modelo, versão do prompt, versão do range e revisão do código.

Não registre credenciais privadas nem envie cartas fechadas brutas para telemetria ampla de terceiros. As cartas fechadas são necessárias em logs protegidos de decisões e fixtures de replay, mas o acesso e a retenção devem ser deliberados. Logs usados em dashboards públicos devem agregá-las ou ocultá-las.

Os indicadores centrais de nível de serviço são:

Prefira histogramas à latência média. Uma chamada de 40 segundos ao modelo desaparece dentro de uma média baixa, mas ainda pode causar uma resposta obsoleta. As especificações de métricas e traces do OpenTelemetry fornecem conceitos independentes de fornecedor. Você não precisa de uma grande stack de observabilidade no primeiro dia, mas preserve nomes e unidades estáveis para que os dashboards não virem trabalho arqueológico.

Como funcionam policies shadow e a avaliação contrafactual?

Uma policy shadow recebe o mesmo snapshot imutável que a policy ativa, mas não pode enviar uma ação. Registre a ação proposta, o tamanho, a confiança, a latência e as características junto à decisão real. Isso testa a integração e a diferença de comportamento sem arriscar fichas nem a correção do protocolo.

Resultados shadow não são evidência direta de taxa de vitória. Se a shadow escolhe fold enquanto a policy ativa escolhe call, o restante da mão observada segue o ramo do call. Você não pode fingir que o fold da shadow causou o resultado posterior. Use shadowing para medir concordância de ações, latência, erros de schema e cobertura. Use um simulador, uma comparação com solver ou um método off-policy para estimar valor contrafactual.

Para pesquisas locais sobre jogos, o OpenSpiel inclui algoritmos e ambientes para jogos de informação imperfeita. Seu artigo de 2019 explica os objetivos de avaliação do framework. Para mudanças ao vivo, combine verificações shadow com suítes de replay e um grupo canário.

Um relatório útil de promoção inclui:

• concordância de ações por street e posição;
• grandes divergências de sizing;
• taxas de falha de schema e legalidade;
• latência p50, p95 e p99;
• métricas de comportamento como VPIP, PFR e taxa de call no river;
• resultado de simulação pareada com incerteza;
• resultado do canário ao vivo com grupo de oponentes e contagem de mãos.

Não promovemos uma policy porque suas explicações parecem mais inteligentes. Nós a promovemos porque o comportamento seguiu na direção pretendida enquanto os critérios de correção e latência permaneceram saudáveis.

Como devem funcionar os lançamentos e rollbacks de policies?

Os lançamentos de policies devem ser imutáveis, versionados e reversíveis. Empacote revisão do código, schema de características, dados de ranges, texto do prompt, identificador do modelo, versão do avaliador e configuração em um único manifesto de lançamento. O log de decisões armazena o ID do manifesto para que qualquer mão possa ser reproduzida sob a policy exata que atuou.

Use um caminho de lançamento com critérios explícitos:

1. Testes unitários e de propriedades passam, inclusive os invariantes de ações legais.
2. Replays de mãos gravadas produzem diffs revisados.
3. Uma simulação longa não mostra regressão de memória nem latência.
4. O modo shadow passa nos critérios de schema, cobertura e latência.
5. Um pequeno grupo canário ao vivo recebe a nova versão.
6. O rollback automático monitora os limites de rejeições, fallbacks, decisões obsoletas e crashes.
7. O desempenho estratégico é revisado apenas depois que um número suficiente de mãos se acumula.

O rollback operacional deve ser rápido e independente da variância do poker. Um único aumento brusco de ações ilegais pode dispará-lo imediatamente. Uma queda no bb/100 normalmente não pode, pois amostras pequenas são ruidosas. Separe critérios rígidos de integridade de critérios lentos de desempenho.

A compatibilidade de estado merece atenção especial. Se um novo modelo de oponente altera os nomes das características armazenadas, migre os dados ou versione o leitor. Um rollback que não consegue ler o estado de ontem não é um rollback. Preferimos observações brutas somente para acréscimo, com características derivadas reconstruídas por versão. O armazenamento custa mais, mas mudanças de estratégia deixam de corromper o histórico.

Como medir o desempenho no poker sem se enganar?

Meça o desempenho no poker com incerteza, comparações controladas e diagnósticos de comportamento. Informe big blinds por 100 mãos com o tamanho da amostra e um intervalo de confiança. Segmente por versão da policy, tamanho da mesa, posição e grupo de oponentes. As fichas brutas da temporada importam para a competição, mas não permitem uma comparação estável entre execuções com buy-ins ou exposição aos blinds diferentes.

Amostras pequenas mentem. Um bot pode ganhar vários all-ins enquanto toma decisões de expectativa negativa de forma consistente. Acompanhe diagnósticos de showdown e all-in, mas também não confunda uma métrica ajustada com a verdade absoluta. Modelos de oponentes mudam, pots multiway complicam as estimativas, e policies ao vivo alteram os dados com os quais aprenderão depois.

Use três fontes de evidência:

Defina a pergunta do experimento antes de olhar os resultados. "Reduzir em 30% os calls no river com equidade abaixo do preço sem aumentar fallbacks por timeout" pode ser testado. "Tornar o bot mais GTO" não pode. O plano do zero ao leaderboard é útil para definir o ritmo das iterações, enquanto o gerenciamento de stack cobre medidas de risco que os totais de fichas não mostram.

Do que o runbook de produção precisa?

O runbook de produção precisa de ações específicas para falhas de autenticação, loops de reconexão, lacunas de ressincronização, picos de rejeição de ações, indisponibilidade do modelo, decisões lentas, estado corrompido, saldo baixo e transições de temporada. Cada alerta deve indicar uma ação para o responsável, um fallback seguro e as evidências necessárias antes de retomar a operação normal.

Por exemplo, a indisponibilidade de um modelo não deve acionar alguém porque uma única chamada falhou. O circuit breaker abre, a policy local assume e um alerta dispara se a taxa de fallback permanecer acima de um limite durante uma janela contínua. Um pico de rejeições de ações é diferente: mude para o fallback determinístico ou pare de entrar em novas mesas até entender a incompatibilidade do protocolo.

Teste o runbook com injeção de falhas. Corte a rede durante um turno. Retorne eventos duplicados. Atrase a policy além do orçamento. Faça o modelo retornar JSON malformado. Reinicie o processo entre hand_start e your_turn. Um documento que não passou por um ensaio é apenas um palpite.

O custo também é uma restrição operacional. Limite as chamadas ao modelo por mão, os tokens de entrada, a CPU de simulação, a retenção de logs e as tentativas de reconexão. O guia de custos de poker bots fornece um modelo de planejamento. Uma estratégia que obtém uma vantagem simulada mínima, mas exige uma chamada remota sem limite, não está pronta para operar sem supervisão.

FAQ

O que é uma arquitetura profissional de poker bot?

É um serviço resiliente, observável e versionado em torno de uma policy de poker. Inclui ressincronização oficial, cancelamento por prazo, níveis de fallback, proteções de ações, avaliação shadow, critérios de lançamento e um runbook de incidentes.

Como um poker bot deve se recuperar depois de uma desconexão?

Reconecte com jitter limitado, use a mesma identidade, envie resync_request com a mesa atual e a última sequência processada, aplique os eventos repetidos de forma idempotente e então reconstrua o estado a partir do snapshot oficial antes de agir.

O que deve acontecer quando o modelo de IA sofre timeout?

Cancele a requisição, registre o timeout e desça para um fallback local. Antes de enviar, confirme que a mão e o token do turno ativos ainda correspondem à decisão. Nunca envie o resultado atrasado de um modelo.

O modo shadow pode provar que uma nova policy vence?

Não. O modo shadow prova que a policy executa, retorna uma saída válida, cumpre as metas de latência e difere de maneiras conhecidas. Use simulação controlada e canários ao vivo como evidências de desempenho.

Quando um poker bot deve fazer rollback automático?

Faça rollback diante de falhas operacionais rígidas, como picos de rejeições de ações, crashes, picos de decisões obsoletas, falhas de schema ou fallbacks excessivos. Resultados estratégicos exigem uma revisão mais lenta porque a variância do poker torna janelas curtas pouco confiáveis.

A decisão profissional não é adicionar outro modelo. É tornar o modelo atual substituível, observável e seguro durante falhas. Registre-se pelo quickstart do Open Poker, execute o primeiro exercício de injeção de falhas e descubra se o seu bot consegue perder todas as dependências opcionais sem perder o controle da mesa.