Neural Gambit – Guia de Instalação Local

Este documento descreve como executar o sistema Neural Gambit localmente para fins de desenvolvimento e testes.

O sistema é composto por:

• Backend em FastAPI
• Frontend em Next.js
• Banco de dados PostgreSQL
• Engine de xadrez Stockfish
• Docker e Docker Compose

---

Pré-requisitos

• Docker
• Docker Compose
• Node.js (versão LTS)
• Python 3.10 ou superior
• PostgreSQL (opcional, caso não utilize Docker)
• Stockfish

---

Configuração do Backend

Crie um arquivo .env no diretório do backend com as seguintes variáveis:

MODEL_PROVIDER="mistralai"
MODEL_NAME="mistral-large-latest"
GENAI_API_KEY="SUA_CHAVE_DE_API"
CHESS_ENGINE_PATH="/usr/games/stockfish"
DB_USER="admin"
DB_PASSWORD="admin"
DB_HOST="localhost"
DB_PORT="5432"
DB_NAME="chess_app_db"
SENDER_EMAIL="seu_email@gmail.com"
EMAIL_PASSWORD="senha_de_aplicativo"
JWT_SECRET="SEGREDO_JWT"
JWT_ALGORITHM="HS256"
FRONTEND_URL="http://localhost:3000"
ACTIVATION_LINK="http://localhost:3000/api/fetchmain/"

---

Execução do Backend

Sem Docker:

cd backend
uv run fastapi dev --port 8000 --host 0.0.0.0 backend/src/main.py --reload

Com Docker:

make docker-build
make docker-run

---

Execução com Docker Compose com o banco de dados

make docker-up
make docker-down
make docker-compose-build

---

Configuração do Frontend

BACKEND_URL="http://localhost:8000"

---

Instalação:

    npm install
    npm run dev

Frontend disponível em http://localhost:3000

---

Testes

make test

---

Segurança

• Não versionar arquivos .env
• Usar chaves diferentes em produção
• Proteger a chave da API de IA

Demo Video

Screencast.From.2025-12-21.08-24-11.mp4