Jogo de Damas com Pydantic e LLMs

Este projeto demonstra como usar a biblioteca Pydantic junto com modelos de linguagem (LLMs) para criar um jogo de damas onde dois modelos LLM jogam entre si.

Características

• Validação de dados com Pydantic: Estruturas de dados fortemente tipadas e validadas
• Integração com modelos LLM: Uso de modelos Ollama locais para jogar damas
• Geração de relatórios: Relatórios detalhados em Markdown de cada partida
• Arquitetura modular: Código organizado em módulos independentes

Requisitos

• Python 3.9 ou superior
• Ollama instalado e configurado
• Modelos Ollama disponíveis (como llama3.1 e mistral)

Instalação

1. Clone o repositório:

2. Instale as dependências:

pip install -r requirements.txt

Uso

Executando pela Linha de Comando (Original)

Execute o script principal para iniciar um jogo diretamente no console:

python main.py

Opções de linha de comando (main.py)

python main.py --modelo-brancas=llama3.1 --modelo-pretas=mistral --max-jogadas=20

• --modelo-brancas: Nome do modelo Ollama para jogar com peças brancas (padrão: llama3.1)
• --modelo-pretas: Nome do modelo Ollama para jogar com peças pretas (padrão: mistral)
• --max-jogadas: Número máximo de jogadas (padrão: 10)

O relatório final será salvo em um arquivo .md.

Executando a Interface Web (Flask)

Para visualizar o jogo em uma interface web:

1. Certifique-se de ter instalado as dependências, incluindo o Flask:

   pip install -r requirements.txt

2. Execute a aplicação Flask:

   python app.py

3. Abra seu navegador e acesse: http://127.0.0.1:5001 (ou o endereço/porta exibido no console).

4. Na interface web:

   • Você pode alterar os nomes dos modelos Ollama e o número máximo de jogadas.
   • Clique em "Iniciar Novo Jogo" para começar.
   • Clique em "Próxima Jogada IA" para avançar o jogo turno a turno.
   • O tabuleiro, o status, o histórico e o raciocínio da IA serão atualizados.

O relatório final também será salvo em um arquivo .md quando o jogo terminar (seja por vitória, empate ou limite de jogadas) na pasta onde app.py foi executado.

Usando a API Diretamente (sem Interface Gráfica)

Se a aplicação Flask (app.py) estiver rodando, você pode interagir com o jogo usando ferramentas como curl ou scripts Python.

1. Iniciar um Novo Jogo:

• Endpoint: /api/start_game
• Método: POST
• Corpo (JSON): (Opcional) Especifique os modelos e o máximo de jogadas.

  {
    "modelo_brancas": "seu_modelo_branco",
    "modelo_pretas": "seu_modelo_preto",
    "max_jogadas": 100
  }

• Exemplo com curl:

  curl -X POST -H "Content-Type: application/json" \
       -d '{"modelo_brancas": "llama3.1", "modelo_pretas": "mistral", "max_jogadas": 60}' \
       http://127.0.0.1:5001/api/start_game

• Resposta: Estado inicial do jogo em formato JSON.

2. Obter o Estado Atual do Jogo:

• Endpoint: /api/game_state
• Método: GET
• Exemplo com curl:

  curl http://127.0.0.1:5001/api/game_state

• Resposta: Estado atual do jogo em formato JSON (inclui tabuleiro, turno, status, etc.).

3. Executar a Próxima Jogada:

• Endpoint: /api/next_move
• Método: POST
• Exemplo com curl:

  curl -X POST http://127.0.0.1:5001/api/next_move

• Resposta: Estado do jogo após a jogada, incluindo o raciocínio bruto da IA (raciocinio_ultima_jogada).

Exemplo de Fluxo com curl:

# Inicia o jogo
curl -X POST -H "Content-Type: application/json" -d '{}' http://127.0.0.1:5001/api/start_game

# Faz a primeira jogada (Brancas)
curl -X POST http://127.0.0.1:5001/api/next_move

# Faz a segunda jogada (Pretas)
curl -X POST http://127.0.0.1:5001/api/next_move

# Verifica o estado atual
curl http://127.0.0.1:5001/api/game_state

# Continua chamando /api/next_move até o jogo terminar...

Estrutura do Projeto

• app.py: Aplicação web Flask para interface visual.
• main.py: Ponto de entrada para execução via linha de comando.
• engine.py: Motor principal do jogo que coordena as interações.
• models.py: Definições de modelos Pydantic (Peca, TabuleiroDeXadrez, Jogada).
• game.py: Funções relacionadas à lógica do jogo de damas (ex: criar tabuleiro inicial).
• llm_player.py: Classe JogadorLLM para interação com modelos LLM.
• reporting.py: Funções para geração e salvamento de relatórios.
• templates/: Contém o arquivo HTML para a interface web.
  • index.html
• static/: Contém os arquivos CSS e JavaScript para a interface web.
  • style.css
  • script.js
• requirements.txt: Lista de dependências Python.
• README.md: Este arquivo.

Exemplo de Relatório

Após cada jogo, um relatório detalhado é gerado em formato Markdown. Este relatório inclui:

• Resumo da partida
• Estatísticas de jogadas e capturas
• Histórico completo de movimentos
• Respostas originais das LLMs
• Visualização do tabuleiro após cada jogada
• Dados estruturados Pydantic de cada movimento

Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou enviar pull requests.

Licença

Este projeto está licenciado sob a licença MIT.