♟️ Chess Trainer

Sistema completo de entrenamiento de ajedrez con backend FastAPI y frontend React + Vite.

🎉 Nuevo en v3.0.0

Mejoras de UX, responsividad y sistema de disponibilidad:

🎨 UI simplificada y responsiva (tablero adaptable, casillas de 75px, sin scrollbars innecesarios)
🖱️ Interacción unificada (click + drag & drop mejorados, resaltados consistentes)
✅ Sistema de disponibilidad de motores (verificación automática de binarios y configuración)
📊 Herramientas de análisis (página de comparación mejorada con detección de motores no disponibles)
🐳 Soporte Docker (motores incluidos, configuración lista para producción)
🔍 Filtrado inteligente (solo muestra motores realmente disponibles)

👉 Ver cambios completos | Docker Setup | Fuentes de Motores

🎉 Nuevo en v2.0.0

Refactorización completa con arquitectura de protocolos:

✨ ~500 líneas de código duplicado eliminadas
🏗️ Sistema de protocolos (UCI, REST, LocalLLM, APILLM)
🎨 Patrones Bridge + Composition aplicados
📦 100% retrocompatible con configuraciones existentes
📚 Documentación completa de la nueva arquitectura
🎨 Frontend React con UI retro y moderno

👉 Ver cambios completos | Documentación técnica | Ejemplos de uso

🚀 Características

Backend

Arquitectura Modular: Soporta motores tradicionales (Stockfish), neuronales (LCZero) y generativos (GPT-4)
API REST: Interfaz unificada para todos los motores
Extensible: Añade nuevos motores sin modificar el código base
Asíncrono: Máxima performance con async/await
Validación Inteligente: Schema para motores tradicionales, Prompt parsing para LLMs
Configuración YAML: Gestión centralizada de motores

Frontend

UI Retro: Interfaz inspirada en terminales de los 80s
React 19: Framework moderno con las últimas características
Vite: Build tool rápido y eficiente
Chess.js: Motor de ajedrez en JavaScript
React Chessboard: Componente visual del tablero

📋 Requisitos Previos

Python 3.9+
Conda: El proyecto usa el entorno conda chess (opcional)
Node.js: Instalado en el sistema
npm: Para gestionar dependencias del frontend
Stockfish: Para motores UCI locales (opcional)

🛠 Instalación

Configuración Inicial

Clonar repositorio:

git clone <repo-url>
cd chessTrainer

Crear entorno virtual (Python):

python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate
pip install -r requirements.txt

Instalar dependencias del frontend:

cd frontend
npm install
cd ..

🚀 Inicio Rápido

Backend

# Activar entorno virtual
source venv/bin/activate  # En Windows: venv\Scripts\activate

# Iniciar servidor
python main.py

El servidor estará disponible en http://localhost:8000

Frontend

Opción 1: Scripts Automáticos (Recomendado)

# Iniciar servidor frontend
bash start_frontend.sh

# Detener servidor
bash stop_frontend.sh

Opción 2: Manual

cd frontend
npm run dev

El frontend estará disponible en http://localhost:5173

🎮 Uso Rápido

API Backend

1. Listar Motores Disponibles

curl http://localhost:8000/engines

2. Obtener Mejor Movimiento

curl -X POST http://localhost:8000/move \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "stockfish-local",
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
    "depth": 20
  }'

3. Comparar Todos los Motores

curl -X POST http://localhost:8000/compare \
  -H "Content-Type: application/json" \
  -d '{
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
    "depth": 15
  }'

Frontend

Abre http://localhost:5173 en tu navegador
Selecciona los motores para jugar
¡Juega!

⚙️ Configuración

La configuración de motores está dividida en dos archivos:

config/engines_local.yaml: Motores locales (no requieren tokens de API)
config/engines_external.yaml: Motores externos (requieren tokens de API)

Motores Locales (`engines_local.yaml`)

engines:
  # Motor tradicional UCI local
  stockfish-local:
    engine_type: traditional_uci
    type: uci
    command: "stockfish"
    default_depth: 15

Motores Externos (`engines_external.yaml`)

engines:
  # Motor generativo (LLM) - Usa variables de entorno para API keys
  gpt-4o-mini:
    engine_type: generative
    provider: openai
    model: "gpt-4o-mini"
    # api_key se lee automáticamente desde variable de entorno OPENAI_API_KEY

Nota: El sistema carga ambos archivos automáticamente. Los motores están organizados por tipo (tradicionales, neuronales, generativos) dentro de cada archivo.

Configuración de API Keys

Las API keys se configuran mediante variables de entorno para mayor seguridad:

Copia el archivo de ejemplo:
```
cp .env.example .env
```
Edita .env y añade tus API keys:
```
OPENAI_API_KEY=sk-tu-api-key-aqui
```
El sistema busca las API keys en este orden:
- {PROVIDER}_API_KEY (ej: OPENAI_API_KEY)
- {ENGINE_NAME}_API_KEY (ej: GPT_4O_MINI_API_KEY)
- API_KEY (genérico)

Modelos GPT gratuitos disponibles:

gpt-4o-mini - Velocidad promedio
gpt-3.5-turbo-0125
gpt-3.5-turbo-1106
gpt-3.5-turbo - Versión estándar
gpt-3.5-turbo-16k - Contexto extendido
net-gpt-3.5-turbo - Con búsqueda en red (menos estable)

🏗 Arquitectura

Estructura del Proyecto

chessTrainer/
├── engines/              # Módulo de motores (backend)
│   ├── base.py          # Clase base y enums
│   ├── validators.py    # Validadores (Schema y Prompt)
│   ├── traditional.py   # Motores tradicionales
│   ├── neuronal.py      # Motores neuronales
│   ├── generative.py   # Motores generativos (LLM)
│   └── factory.py       # Factory y Registry
├── frontend/            # Aplicación React
│   ├── src/
│   │   ├── App.jsx
│   │   ├── GamePage.jsx
│   │   └── ...
│   ├── package.json
│   └── vite.config.js
├── config/
│   ├── engines_local.yaml     # Motores locales (sin API keys)
│   └── engines_external.yaml  # Motores externos (con API keys)
├── docs/                # Documentación
├── engine_manager.py    # Gestor de motores
├── main.py             # API FastAPI
├── start_frontend.sh   # Script de inicio frontend
├── stop_frontend.sh    # Script de detención frontend
└── requirements.txt    # Dependencias Python

🌐 API Endpoints

Información

GET / - Servir frontend o redirigir a desarrollo
GET /api - Información general de la API
GET /health - Estado de salud
GET /engines - Lista de motores disponibles
GET /engines/info - Información detallada de motores
GET /engines/matrix - Matriz de clasificación

Operaciones

POST /move - Obtener mejor movimiento de un motor
POST /compare - Comparar sugerencias de todos los motores
POST /reload - Recargar configuración sin reiniciar

🎯 Tipos de Motores

1. Motores Tradicionales

Algoritmos deterministas (minimax, alfa-beta)
Ejemplos: Stockfish, Komodo, Houdini

2. Motores Neuronales

Redes neuronales + búsqueda MCTS
Ejemplos: Leela Chess Zero, AlphaZero

3. Motores Generativos

Basados en LLMs
Pueden explicar decisiones
Ejemplos: GPT-4, Claude

📚 Documentación

👉 Índice completo de documentación - Navegación organizada por categorías

Documentación Detallada

ARQUITECTURA.md - Arquitectura completa del sistema
REFACTORIZACION_PROTOCOLOS.md - Sistema de protocolos
patrones_diseño.md - Patrones de diseño utilizados

🔧 Desarrollo

Backend

# Tests
pytest

# Linting
flake8 engines/ engine_manager.py main.py

# Formato
black engines/ engine_manager.py main.py

Frontend

cd frontend

# Desarrollo
npm run dev

# Build producción
npm run build

# Preview build
npm run preview

# Linting
npm run lint

🐛 Solución de Problemas

Backend

Los motores LLM requieren API keys válidas
LCZero puede requerir configuración adicional de GPU
Algunos motores externos tienen rate limits

Frontend

Verificar que el puerto 5173 está libre: lsof -i :5173
Si hay problemas, usar bash stop_frontend.sh y luego bash start_frontend.sh
Reinstalar dependencias: cd frontend && rm -rf node_modules && npm install

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

Fork el proyecto
Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add some AmazingFeature')
Push a la rama (git push origin feature/AmazingFeature)
Abre un Pull Request

📝 Roadmap

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver archivo LICENSE para más detalles.

👥 Autores

Chess Trainer Team

🙏 Agradecimientos

Stockfish - Motor de ajedrez open source
Leela Chess Zero - Motor neuronal open source
python-chess - Librería de ajedrez
FastAPI - Framework web moderno
React - Biblioteca de JavaScript
Vite - Build tool moderno

Versión: 3.0.0
Última actualización: 1/12/2025

Para más información, consulta la documentación completa.

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
config		config
docs		docs
engines-bin		engines-bin
engines		engines
frontend		frontend
scripts		scripts
weights		weights
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile.engines		Dockerfile.engines
LICENSE		LICENSE
README.md		README.md
config.py		config.py
docker-compose.engines.yml		docker-compose.engines.yml
docker-compose.yml		docker-compose.yml
download_weights.sh		download_weights.sh
engine_manager.py		engine_manager.py
main.py		main.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

♟️ Chess Trainer

🎉 Nuevo en v3.0.0

🎉 Nuevo en v2.0.0

🚀 Características

Backend

Frontend

📋 Requisitos Previos

🛠 Instalación

Configuración Inicial

🚀 Inicio Rápido

Backend

Frontend

Opción 1: Scripts Automáticos (Recomendado)

Opción 2: Manual

🎮 Uso Rápido

API Backend

1. Listar Motores Disponibles

2. Obtener Mejor Movimiento

3. Comparar Todos los Motores

Frontend

⚙️ Configuración

Motores Locales (engines_local.yaml)

Motores Externos (engines_external.yaml)

Configuración de API Keys

🏗 Arquitectura

Estructura del Proyecto

🌐 API Endpoints

Información

Operaciones

🎯 Tipos de Motores

1. Motores Tradicionales

2. Motores Neuronales

3. Motores Generativos

📚 Documentación

Documentación Detallada

🔧 Desarrollo

Backend

Frontend

🐛 Solución de Problemas

Backend

Frontend

🤝 Contribuir

📝 Roadmap

📄 Licencia

👥 Autores

🙏 Agradecimientos

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Motores Locales (`engines_local.yaml`)

Motores Externos (`engines_external.yaml`)

Packages