Seja bem-vindo à competição Codenames da DCC Week 2026! O desafio consiste em desenvolver dois agentes de IA (o codemaster e o guesser) que competirão entre si em partidas de Codenames valendo prêmios para os três primeiros colocados. Esta competição é individual e uma adaptação do desafio da IEEE CoG 2026.

Como funciona o jogo Codenames

O Codenames é um jogo de dedução e associação de palavras. No tabuleiro há 25 palavras distribuídas. As equipes (Vermelha e Azul) possuem dois papéis cada:

  • Codemaster: Sabe exatamente a qual equipe cada palavra do tabuleiro pertence (além de cartas neutras e o Assassino). A função dele é dar uma dica de apenas uma palavra acompanhada de um número, conectando duas ou mais palavras do seu time (ex: animal, 2).
  • Guesser: Baseando-se apenas nessa dica, deve deduzir e selecionar quais são as palavras corretas no tabuleiro.

A equipe ganha se descobrir todas as suas palavras primeiro. Se o Guesser selecionar uma carta do time adversário ou uma carta neutra, o turno passa. Se selecionar a carta do Assassino, a equipe perde imediatamente.

Sobre a Competição Original

A competição original desenvolve um benchmark para testar agentes (frequentemente baseados em LLMs como GPT-4, Llama, etc.) no jogo “Codenames”. A estrutura original é dividida em duas tracks:

  • Single Team: Avalia uma única equipe tentando adivinhar todas as suas palavras no menor número de turnos possível.
  • Two Teams: Duas equipes (Vermelha e Azul) competem simultaneamente para descobrir suas palavras primeiro, com base no win-rate.

Para mais detalhes: Como utilizamos o framework oficial, a documentação completa da competição original, regras detalhadas e exemplos de código estão no repositório oficial: Codenames_GPT no GitHub.

Formato da Competição (Exclusivo DCC Week)

Diferente do evento original, no DCC Week teremos apenas a modalidade Two Teams. Os agentes se enfrentarão seguindo as regras originais de disputa direta (Equipe Vermelha vs. Equipe Azul). O torneio será dividido em duas etapas principais:

  • Primeira Fase (Round Robin): Ocorrerá em formato de todos contra todos. O desempenho de cada equipe será medido pelo seu pela quantidade de vitórias (win-rate). Em caso de empate, o tempo total que o agente levou para finalizar todas as partidas determina o melhor. As 4 melhores equipes avançam para a próxima fase.
  • Segunda Fase (Mata-mata): Um torneio de eliminação simples entre o Top 4. Os confrontos serão definidos por chaveamento. As partidas desta fase serão decididas em formato melhor de três.

Regras

Você deve desenvolver e submeter dois agentes funcionais em um único arquivo .py, imitando os arquivos de exemplo do repositório.

Seus agentes (Codemaster e Guesser) devem respeitar estritamente o formato de dicas do Codenames:

  • Formato obrigatório: Uma única palavra em inglês + um número indicando a quantidade de cartas associadas (ex: pebble, 2). O número “0” pode ser usado para palpites ilimitados.
  • Infrações (Desclassificação): Dicas que indiquem posição no tabuleiro (ex: “Quatro-Dois”), palavras compostas irregulares, erros propositais de ortografia ou derivações diretas das palavras visíveis.

Métodos obrigatórios para o Codemaster:

  • __init__(self)
  • set_game_state(words_on_board: List[str], key_grid: List[str]) -> None
  • get_clue() -> Tuple[str, int]

Métodos obrigatórios para o Guesser:

  • __init__(self)
  • set_board(words: List[str]) -> None
  • set_clue(clue: str, num_guesses: int) -> None
  • keep_guessing() -> bool
  • get_answer() -> str

(Dica: Ambas as classes podem usar super().get_move_history() para acessar o histórico de ações da partida).

Regras de Desenvolvimento:

  • Não modifique os arquivos base do framework original.
  • Uso de IA: Permitido o uso de LLMs (GPT-4, Gemini, Llama, etc.) via API ou modelos locais, além de abordagens clássicas (word embeddings).
  • Custos: O uso de APIs pagas é de total responsabilidade da equipe (vocês devem fornecer e gerenciar suas próprias chaves e créditos).
  • A competição é individual, ou seja, as equipes devem ser compostas por apenas um aluno.

Instalação Básica e Teste

Recomenda-se o uso do Anaconda para rodar o framework original:

  • conda create --name codenames python=3.9
  • conda activate codenames
  • pip install -U colorama openai
  • git clone https://github.com/stepmat/Codenames_GPT.git
  • cd Codenames_GPT

Para testar seus agentes localmente no terminal:

  • python run_game.py seu_arquivo.SeuCodemasterRed seu_arquivo.SeuGuesserRed seu_arquivo.SeuCodemasterBlue seu_arquivo.SeuGuesserBlue --seed 3442

Datas Importantes

  • As inscrições vão até o dia 06/08;
  • O resultado final será divulgado durante o evento no dia 07/08.

Premiação

Os três primeiros colocados receberão uma premiação. Os detalhes serão divulgados posteriormente.

Submissão

Você deverá anexar no formulário de inscrição um arquivo .zip contendo:

  • O arquivo .py com as classes do seu Codemaster e Guesser.
  • Um arquivo README especificando bibliotecas extras necessárias, instruções claras de execução e links para download de modelos locais (se houver).

Para participar, o candidato deve ser um aluno inscrito no evento DCC Week 2026.

Realizar Inscrição