♟ Chess Coach

El coach de ajedrez más potente que existe. Analiza tus partidas de Chess.com con Stockfish en local y recibe coaching personalizado de una IA que conoce tu juego real.

¿Qué hace?

• Descarga tus partidas de Chess.com automáticamente
• Analiza cada posición con Stockfish (solo tus jugadas, nunca las del rival)
• Clasifica tus errores: tácticos, estratégicos, posicionales, de conversión, de defensa
• Detecta patrones transversales entre múltiples partidas (puntos ciegos, debilidades recurrentes)
• Coach IA que conoce tus datos reales y te da consejos específicos, no genéricos
• Plan de mejora personalizado y progresivo

Requisitos previos

1. Python 3.10 o superior — Descargar Python
2. Stockfish — Motor de ajedrez open source
3. API key de Anthropic — Para el coach IA (opcional, el análisis funciona sin ella)
4. Cuenta en Chess.com — El usuario cuyas partidas quieres analizar

Instalación paso a paso

1. Clonar el repositorio

git clone https://github.com/tu-usuario/chess-coach.git
cd chess-coach

2. Instalar dependencias de Python

pip install -r requirements.txt

3. Descargar Stockfish

Ve a stockfishchess.org/download y descarga la versión para tu sistema operativo.

Windows:

• Descarga el archivo ZIP para Windows
• Extrae el ejecutable (ej: stockfish-windows-x86-64-avx2.exe)
• Crea la carpeta data/stockfish/ dentro del proyecto
• Copia el ejecutable ahí

Mac:

brew install stockfish

Luego edita config.py y cambia STOCKFISH_PATH a la ruta donde se instaló (normalmente /usr/local/bin/stockfish o /opt/homebrew/bin/stockfish).

Linux:

sudo apt install stockfish

Edita config.py y cambia STOCKFISH_PATH a /usr/games/stockfish o la ruta correspondiente.

4. Configurar la API key de Anthropic (para el Coach IA)

El coach IA necesita una API key de Anthropic. Sin ella, el análisis con Stockfish funciona pero no tendrás el coach conversacional.

Opción A: Variable de entorno (recomendado)

Windows:

set ANTHROPIC_API_KEY=sk-ant-tu-clave-aqui

Mac/Linux:

export ANTHROPIC_API_KEY=sk-ant-tu-clave-aqui

Opción B: Editar config.py

Abre config.py y cambia:

ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY", "")

por:

ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY", "sk-ant-tu-clave-aqui")

⚠️ NUNCA subas tu API key a GitHub. Si la pones en config.py, asegúrate de no commitear ese cambio.

5. Verificar que Stockfish funciona

python -m engine.stockfish

Deberías ver algo como:

Posición inicial:
  Evaluación rápida: +0.46
  Mejor jugada: e4
Stockfish funciona correctamente.

6. Lanzar la aplicación

streamlit run app.py

Se abrirá en tu navegador en http://localhost:8501.

Cómo usar

1. Configurar el análisis

En la pantalla de Inicio:

• Escribe tu usuario de Chess.com
• Selecciona el periodo (último día, semana, mes...)
• Elige el control de tiempo mínimo (3 minutos descarta bullet)
• Selecciona el límite de partidas (50-100 recomendado para empezar)
• Pulsa Analizar partidas

2. Esperar el análisis

Stockfish analizará cada partida posición a posición. Con 50 partidas tarda unos 50 minutos. Puedes ver el progreso en tiempo real.

El análisis es incremental: si lo paras y lo relanzas, continúa desde donde se quedó.

3. Explorar los resultados

• 📊 Dashboard — Vista general: elo, win rate, distribución de errores
• ♟ Aperturas — Rendimiento por apertura con blancas y negras
• ❌ Errores — Todos tus errores con tablero, clasificación y enlace a la partida
• 🔍 Patrones — Debilidades recurrentes detectadas automáticamente
• 🏁 Finales — Rendimiento por tipo de final
• 🎓 Coach — Chat con IA que conoce tus datos reales
• 📈 Plan de mejora — Plan personalizado generado por el coach

4. Usar el Coach

Puedes usar las acciones rápidas (Diagnóstico, Plan de mejora, Análisis de aperturas, Análisis de finales) o hacerle preguntas libres.

Truco: Cada sección (Aperturas, Errores, Patrones, Finales) tiene un botón "Enviar al Coach" al final que le da los datos exactos de esa sección para que los analice.

Estructura del proyecto

chess-coach/
├── app.py                      # Punto de entrada de Streamlit
├── config.py                   # Configuración (editar con tus datos)
├── requirements.txt            # Dependencias Python
├── data/
│   ├── chess_coach.db          # Base de datos (se crea automáticamente)
│   └── stockfish/              # Binario de Stockfish
├── database/
│   ├── db.py                   # Conexión SQLite
│   ├── models.py               # Esquema de tablas
│   └── queries.py              # Consultas encapsuladas
├── chess_com/
│   ├── client.py               # Descarga de partidas de Chess.com
│   └── parser.py               # Parseo de PGN
├── engine/
│   ├── stockfish.py            # Wrapper de Stockfish
│   ├── analyzer.py             # Análisis posición a posición
│   ├── classifier.py           # Clasificación de errores
│   └── patterns.py             # Detección de patrones
├── coach/
│   ├── claude_client.py        # Cliente API de Anthropic
│   ├── context_builder.py      # Constructor de contexto RAG
│   ├── plan_generator.py       # Generador de planes
│   └── prompts.py              # Prompts del coach
└── ui/
    ├── components/             # Componentes reutilizables
    │   ├── board.py            # Tablero SVG
    │   ├── charts.py           # Gráficos Plotly
    │   ├── game_link.py        # Enlaces a Chess.com
    │   ├── progress_bar.py     # Barra de progreso
    │   └── summary.py          # Resúmenes para el coach
    └── pages/                  # Páginas de la app
        ├── home.py             # Inicio y configuración
        ├── dashboard.py        # Dashboard principal
        ├── openings.py         # Análisis de aperturas
        ├── errors.py           # Análisis de errores
        ├── patterns.py         # Patrones detectados
        ├── endgames.py         # Análisis de finales
        ├── coach_chat.py       # Coach conversacional
        └── improvement.py      # Plan de mejora

Características técnicas

• Análisis de dos pasadas: Pasada rápida (profundidad 10) para todas las posiciones, pasada profunda (profundidad 18) solo para momentos críticos
• Solo errores del usuario: El sistema nunca confunde errores del rival con los tuyos
• Sistema RAG: El coach recibe solo los datos relevantes a tu pregunta, minimizando tokens y coste
• Análisis incremental: Si paras y relanzas, continúa desde donde se quedó
• Detección de mates: Dar mate nunca se clasifica como error
• 14 detectores de patrones: Errores por fase, debilidades en aperturas, puntos ciegos tácticos, presión de tiempo, problemas de conversión, finales, asimetría por color, tilt, autopilot, y más

Coste del Coach IA

Con Claude Sonnet 4 ($3/M tokens input, $15/M tokens output):

• Pregunta normal: ~$0.007 (menos de 1 céntimo)
• Diagnóstico completo: ~$0.03 (3 céntimos)
• Con 5€ de créditos: ~700 preguntas o ~160 diagnósticos

Cambiar de usuario

La app analiza un usuario a la vez. Para analizar otro usuario:

1. Borra la base de datos: elimina data/chess_coach.db
2. Relanza la app y escribe el nuevo usuario
3. Lanza el análisis

Solución de problemas

"Stockfish no encontrado"

• Verifica que el ejecutable está en data/stockfish/
• Verifica el nombre del archivo en config.py → STOCKFISH_PATH

"API key no configurada"

• Configura la variable de entorno o edita config.py

"Credit balance too low"

• Compra créditos en console.anthropic.com

El análisis es muy lento

• Reduce el número de partidas (50 es un buen inicio)
• Puedes bajar STOCKFISH_DEPTH_DEEP a 14 en config.py (menos preciso pero más rápido)
• Aumenta STOCKFISH_THREADS si tu PC tiene más núcleos

"NotImplementedError" al analizar

• Problema de Python 3.13 + Windows. El fix ya está incluido en engine/stockfish.py

Licencia

MIT

Créditos

• Stockfish — Motor de ajedrez open source
• python-chess — Librería de ajedrez para Python
• Chess.com API — API pública de Chess.com
• Anthropic Claude — IA para el coach conversacional
• Streamlit — Framework para la interfaz web