Chess Coach FastAPI

Este proyecto es una aplicación de coaching de ajedrez que utiliza FastAPI para exponer una API que analiza partidas en tiempo real desde Lichess y proporciona asistencia mediante un avanzado sistema de inteligencia artificial.

Características

• Modo Asistente: Chat interactivo con un coach de ajedrez basado en un LLM, enriquecido con análisis táctico.
• Sistema RAG (Retrieval-Augmented Generation): Las respuestas se enriquecen con ejemplos tácticos relevantes extraídos de una base de datos vectorial local.
• Análisis con Stockfish: Integración con el potente motor de ajedrez Stockfish para un análisis profundo de las posiciones.
• Modo Comentarista: Comentarios automáticos en tiempo real via WebSocket.
• Análisis en tiempo real: Conexión directa con partidas de Lichess.
• Extensión de navegador: Interfaz integrada en Lichess.org.
• Arquitectura escalable: Pool de conexiones y juegos 'thread-safe'.

Arquitectura

La arquitectura está diseñada para ser modular, separando la lógica de la aplicación principal de los componentes de IA.

/
├── chess_coach/              # Aplicación principal FastAPI
│   ├── app/
│   ├── config/
│   ├── core/
│   └── ...
├── moduloProcesador/         # Módulo de Inteligencia Artificial
│   ├── fileProcessing/       # Scripts para procesar y vectorizar datos
│   │   ├── cleanFile.py
│   │   ├── process_chess_rag.py
│   │   └── chess_rag_local/  # Vector store (generado)
│   ├── FinalQuery/           # Lógica del agente LLM y RAG
│   │   ├── ConsultorFinal.py
│   │   └── RAGMgr.py
│   └── ...
├── stockfish/                # Motor de ajedrez Stockfish
│   └── stockfish-windows-x86-64-avx2.exe
├── extension/                # Extensión de Chrome
└── ...

Requisitos

• Python 3.10 o superior
• Google Chrome (para la extensión)
• Cuenta de Lichess con API token

Instalación

1. Clona el repositorio:

   git clone <repo-url>
   cd ChessCoach

2. Crea entorno virtual:

   python -m venv venv
   # Windows:
   venv\Scripts\activate
   # Linux/Mac:
   source venv/bin/activate

3. Instala dependencias:

   pip install -r requirements.txt

4. Configura el motor Stockfish:

   • Descarga una versión compatible de Stockfish.
   • Descomprime el archivo y coloca la carpeta stockfish (que contiene el ejecutable) directamente en la raíz del proyecto.

5. Genera la Base de Datos Vectorial (RAG):

   Para que el sistema RAG funcione, necesitas procesar el archivo de texto con ejemplos tácticos y crear el almacén de vectores local. Ejecuta el siguiente comando desde la raíz del proyecto:

   python -m moduloProcesador.fileProcessing.process_chess_rag

   Esto creará la carpeta moduloProcesador/fileProcessing/chess_rag_local con los datos vectorizados. Este paso solo es necesario hacerlo una vez.

6. Configura variables de entorno:

   Crea un archivo .env en la raíz del proyecto:

   LICHESS_API_KEY=lip_xxxxxxxxxxxxxxxxx
   DEEPSEEK_API_KEY=tu_deepseek_api_key

   El API key de Lichess debe tener permisos de 'game' (Board API).

7. Instala la extensión de Chrome:

   • Abre Chrome → Extensiones → Modo desarrollador ON
   • "Cargar extensión sin empaquetar" → Selecciona carpeta extension/

Ejecución

1. Inicia el servidor FastAPI:

   uvicorn chess_coach.app.Main:app --reload

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

2. Abre una partida en Lichess:

   • Ve a https://lichess.org
   • Inicia o observa una partida
   • La extensión aparecerá automáticamente en el lado derecho

Uso

Modo Asistente (Chat Interactivo)

• Haz clic en "Asistente" en la extensión
• Escribe preguntas sobre la partida actual
• Recibe consejos personalizados del coach, ahora enriquecidos con ejemplos tácticos gracias al sistema RAG.
• Soporte para mensajes multilínea (Ctrl+Enter para nueva línea)

Modo Comentarista (Automático)

• Haz clic en "Comentarista" en la extensión
• Recibe comentarios automáticos en tiempo real
• Los comentarios aparecen cuando se realizan movimientos

Componentes de Inteligencia Artificial

Esta sección detalla el núcleo de IA del proyecto, que se encuentra principalmente en el moduloProcesador.

1. Motor de Análisis: Stockfish

• Función: Proporciona un análisis de ajedrez crudo y objetivo. Se utiliza para evaluar la fuerza de las jugadas, identificar errores tácticos y calcular las mejores líneas.
• Integración: El sistema invoca al ejecutable de Stockfish ubicado en la carpeta /stockfish para analizar posiciones específicas de la partida actual cuando el usuario lo solicita.

2. Generación Aumentada por Recuperación (RAG)

Este sistema permite que el coach de IA proporcione respuestas más ricas y contextualizadas, basadas en un conocimiento externo.

• Fuente de Conocimiento: Un archivo de texto (tactica-ajedrez.txt) que contiene cientos de ejemplos de tácticas de ajedrez con sus respectivas posiciones (en formato FEN) y descripciones.
• Proceso de Indexación:
  1. El script cleanFile.py limpia y estandariza los datos del archivo de texto.
  2. process_chess_rag.py utiliza modelos de embeddings de HuggingFace (sentence-transformers) para convertir cada ejemplo táctico en un vector numérico.
  3. Estos vectores se almacenan en una base de datos vectorial local (ChromaDB) en la carpeta chess_rag_local.
• Proceso de Recuperación:
  1. Cuando el usuario hace una pregunta, el sistema la convierte en un vector.
  2. Se realiza una búsqueda de similitud en la base de datos ChromaDB para encontrar los ejemplos tácticos más relevantes para la pregunta.
  3. Los ejemplos recuperados se inyectan en el prompt final que se envía al LLM.

3. Agente LLM con Herramientas (ConsultorFinal)

Es el cerebro orquestador que decide cómo responder al usuario.

• Flujo de Trabajo:
  1. Recibe la consulta del usuario y el estado actual de la partida (últimos movimientos, FEN).
  2. Consulta al RAG: Utiliza el sistema RAG (RAGMgr.py) para buscar ejemplos tácticos relevantes.
  3. Construcción del Prompt: El ArmadorPromptFinal.py construye un prompt detallado que incluye:
     • El rol del LLM (un coach de ajedrez).
     • El estado de la partida.
     • La pregunta del usuario.
     • El contexto recuperado por el sistema RAG.
  4. Generación de Respuesta: El prompt final se envía a un modelo de lenguaje grande (LLM) que genera la respuesta en lenguaje natural que se muestra al usuario.
• Herramientas (Tools): El agente está diseñado para poder usar "herramientas", como funciones para obtener el estado del tablero o consultar a Stockfish, lo que le permite recopilar información de forma autónoma para dar una mejor respuesta.