rukh · lab

// curso · 13 módulos · ≈ 74 h

Dos fases, un artefacto.

Cada módulo cierra con algo que funciona y se mide con la misma tabla: legalidad, exactitud, puzles y Elo frente a Stockfish. Las lecciones se publican hito a hito; el módulo 0 ya está disponible.

01 / Fase 1// siete módulos · cinco semanas · ≈ 44 h

Un modelo de lenguaje de ajedrez desde cero

  1. M03 hvigente0/1

    Taller: repo, entorno, datos y tablero

    Los tres repos, uv con CUDA 12.8, el recorte de datos de Lichess lanzado en segundo plano, Stockfish verificado, MLflow local y un tablero que solo acepta jugadas legales.

    Al terminar funciona

    • uv sync --extra cu128 deja un entorno con torch y CUDA listos y rukh info lo demuestra.
    • El recorte de datos (dos meses de Lichess, filtros documentados) está descargado con su manifiesto.
    • La demo muestra un tablero que solo acepta jugadas legales, sin modelo todavía.
    1. 00Taller: repo, entorno, datos y tablero180 min
  2. M16 hvigente0/1

    Del PGN al tensor: datos y tokenización

    Qué es un token y por qué la elección importa: tres tokenizaciones de la misma partida comparadas con el mismo modelo, dataloaders con empaquetado por bloques y un tokenizador que corre en el navegador.

    Al terminar funciona

    • Un dataloader sirve lotes de las tres tokenizaciones (UCI fijo, SAN por carácter, BPE) con máscara causal.
    • Comparativa medida de tokens por partida y cobertura de vocabulario.
    • El tokenizador UCI existe en Python y en TypeScript con un fixture de paridad.
    1. 01Del PGN al tensor: datos y tokenización360 min
  3. M28 hvigente0/1

    El decoder: un GPT que juega

    Embeddings, atención con máscara causal, bloques pre-norm y la receta de entrenamiento, escritos a mano y entrenados en la RTX 5090. Termina con el modelo exportado a ONNX y jugable en la web.

    Al terminar funciona

    • rukh-small propone jugada legal sin máscara en el 99,4 % de las posiciones (listón de GOAL.md: ≥ 99 %) y alcanza 1007 de Elo estimado (IC 95 % 920-1101), por debajo del listón de 1200, que se documenta y no se mueve.
    • Juegas contra él en la demo, con WebGPU o WASM, sin backend.
    • Un mapa de atención y una repetición del entrenamiento checkpoint a checkpoint en la lección.
    1. 01El decoder: un GPT que juega al ajedrez480 min
  4. M36 hvigente0/1

    El encoder: entender la posición

    Un encoder bidireccional entrenado con masked move modeling (75,2 % de acierto en las jugadas tapadas), cabezas de valor y de detección de errores sobre 438 093 posiciones etiquetadas, y la lección de por qué un 96,78 % de exactitud sobre una clase del 3,7 % no significa nada.

    Al terminar funciona

    • Valor de la posición y alerta de error en vivo en la demo.
    • Cumplido: el detector de errores supera a la heurística de material en 9,0 puntos de F1 (0,179 frente a 0,089), por encima de los cinco que pide GOAL.md.
    • No cumplido: la correlación entre el valor del encoder y los centipeones de Stockfish se queda en 0,42 de Spearman frente al 0,80 que pide GOAL.md. Diagnóstico publicado: 4 000 pasos de afinado, 9,8 % de cobertura de etiquetas y una escala tanh(cp/400) que comprime justo donde hay más densidad.
    • Medido: afinar solo los dos últimos bloques y la norma final (0,1180 de error de valor) gana a afinar el modelo entero (0,1354) y al tronco congelado (0,1429), con una tirada por modo.
    • Medido: la curva por número de etiquetas se aplana en el 25 % (109 523 filas), así que las tres cuartas partes de las evaluaciones de Stockfish no compran nada medible; la única diferencia que supera el ruido entre tiradas es la exactitud de errores con el 10 %.
    1. 01El encoder: entender la posición360 min
  5. M47 hprevisto

    Fine-tuning e instrucción

    SFT con partidas de maestros, condicionamiento por Elo como instrucción, LoRA escrito a mano y con peft, y QLoRA de Qwen3 sobre PGN para una comparación honesta con un LLM general.

    Al terminar funciona

    • Selector "juega como 1500 / 2000 / 2400" en la demo, con Elo medido por condición y monótono.
    • Adaptadores LoRA de estilo intercambiables en caliente.
    • Tabla comparativa con Qwen3 afinado con QLoRA sobre el mismo recorte.

    Lecciones en cuanto se cierre el hito.

  6. M58 hprevisto

    Alineamiento con recompensas verificables

    El modelo como política: reward model con Bradley-Terry, DPO con pares on-policy, GRPO con recompensas que un motor puede verificar y una galería de reward hacking observado.

    Al terminar funciona

    • Modelos DPO y GRPO medibles: al menos +50 Elo con intervalo de confianza sobre su base.
    • Reward model con al menos un 75 % de acierto en pares no vistos.
    • Funciones de recompensa con tests y una galería de trampas que aprendió el modelo.

    Lecciones en cuanto se cierre el hito.

  7. M66 hprevisto

    Evaluar, exportar, publicar

    Métricas de dominio frente a proxies, intervalos de confianza del Elo, cuantización con paridad, model cards generadas desde MLflow y la demo final con selector de etapa.

    Al terminar funciona

    • Una tabla única y reproducible con todas las etapas y los baselines públicos.
    • Model cards en inglés para cada modelo de la colección Rukh.
    • Demo final con selector de etapa, arena modelo contra modelo y puzles en vivo.
    • report · Informe de resultados
    • bot · Bot de Lichess (opcional)
    • post · Post 4 (vídeo)

    Lecciones en cuanto se cierre el hito.

02 / Fase 2// seis módulos · cuatro semanas · ≈ 30 h

IA agéntica: el entrenador

  1. A16 hprevisto

    Embeddings y RAG: posiciones y libros

    Embeddings de posiciones con el encoder propio, un índice vectorial de millones de posiciones y RAG sobre libros de ajedrez de dominio público, evaluado con RAGAS.

    Al terminar funciona

    • "En posiciones parecidas, los maestros jugaron…" con recuperación por embedding.
    • Comentarios con citas literales de Capablanca y Lasker, con métricas RAGAS documentadas.
    • dataset · Índice de posiciones

    Lecciones en cuanto se cierre el hito.

  2. A27 hprevisto

    Agente con herramientas (LangGraph)

    Un agente entrenador que analiza una partida llamando al motor, al modelo, al libro de aperturas y al buscador, con trazas completas en LangSmith.

    Al terminar funciona

    • El agente comenta una partida completa decidiendo qué herramienta usar en cada jugada.
    • Cada ejecución deja una traza inspeccionable en LangSmith.

    Lecciones en cuanto se cierre el hito.

  3. A34 hprevisto

    Evaluación y observabilidad

    Suite de evaluación del entrenador con preguntas doradas, jueces automáticos y regresión por commit en LangSmith.

    Al terminar funciona

    • Suite de evaluación en LangSmith en verde.
    • Cada commit del agente se compara con el anterior sobre el mismo conjunto dorado.
    • report · Suite de evaluación

    Lecciones en cuanto se cierre el hito.

  4. A45 hprevisto

    Multiagente

    Tres roles que cooperan y se corrigen: jugador, entrenador y redactor del informe, orquestados como un grafo.

    Al terminar funciona

    • Jugador, entrenador y redactor producen un informe de partida coherente entre los tres.
    • report · Informe de partida

    Lecciones en cuanto se cierre el hito.

  5. A53 hprevisto

    MCP

    Las herramientas de ajedrez (motor, modelo, libro, índice) expuestas como un servidor MCP que cualquier cliente puede usar.

    Al terminar funciona

    • Servidor MCP con las herramientas de ajedrez, usable desde un cliente externo.

    Lecciones en cuanto se cierre el hito.

  6. A65 hprevisto

    Capstone

    El entrenador: backend opcional, comentarios en vivo mientras juegas y un informe final de la partida, publicado como cierre del curso.

    Al terminar funciona

    • Web del entrenador: juegas, te comenta en vivo y recibes un informe al final.
    • Post de cierre con la historia completa del proyecto.

    Lecciones en cuanto se cierre el hito.