Evaluar: los labs de cierre

La última lección del módulo y de la fase 1: los siete labs con sus comandos y sus salidas, los cuatro scripts de labs/m6 enteros, una lista de comprobación que sirve para cualquier modelo y el balance de la fase.

Labs

Siete laboratorios, en el orden en que se hicieron, y ninguno entrena nada. Los dos primeros miden el instrumento y reconstruyen la tabla; el tercero responde a la pregunta que M2 dejó abierta; los demás ponen la tabla donde la gente la va a leer: en cada card, en la colección y en la demo.

Lab 1 · El suelo del instrumento, medido cuatro veces

// Viene delección 2 · La escalera calibrada: el rival por nodos y la identidad de unos pesos

La hipótesis de partida: la escalera no repite porque el rival juega por tiempo. Se mide el mismo modelo con la misma semilla, dos veces por tiempo y dos con un presupuesto de nodos, y se mira cuánto se separan las dos tiradas de cada régimen. elo_nodes: 200000 es lo que 0,1 s compra en esta máquina: el mismo rival en fuerza, otro en comportamiento (lección 2).

uv run rukh eval --model checkpoints/medium-v4/best.pt --config configs/eval/ladder-time.yaml --stage ladder-time-a --no-cache
uv run rukh eval --model checkpoints/medium-v4/best.pt --config configs/eval/ladder-time.yaml --stage ladder-time-b --no-cache
uv run rukh eval --model checkpoints/medium-v4/best.pt --config configs/eval/ladder-nodes.yaml --stage ladder-nodes-a --no-cache
uv run rukh eval --model checkpoints/medium-v4/best.pt --config configs/eval/ladder-nodes.yaml --stage ladder-nodes-b --no-cache
uv run python labs/m6/ladder_floor_export.py --decision time

Las cuatro tiradas, con 160 partidas cada una y quince minutos de máquina parada entre ellas:

Sin GPU, o sin la hora y media de máquina, la ruta corta trae las cuatro evaluaciones del hito y regenera solo la figura. ladder_check.py, en cambio, juega motor contra motor y no necesita GPU, solo unos 35 minutos de CPU:

git checkout p6 -- artifacts/eval/ladder-time-a artifacts/eval/ladder-time-b artifacts/eval/ladder-nodes-a artifacts/eval/ladder-nodes-b
uv run python labs/m6/ladder_floor_export.py --decision time

Deja el mismo artifacts/web/ladder-floor.json que la ruta larga, con las cifras de la tabla de arriba.

Cero Elo de separación por tiempo y 17 por nodos, las dos muy por debajo del semiancho del intervalo (±55). El presupuesto de nodos hace determinista la búsqueda, no al rival, porque UCI_LimitStrength aleatoriza a propósito; y con la máquina tranquila el reloj ya repite al nivel del ruido de muestreo. El rival sigue por tiempo, con una condición en el runbook (nada más en la máquina mientras corre una escalera), y elo_nodes se queda para quien mida en una máquina compartida y para el lab 3, donde el propio jugador carga la CPU. La lectura completa está en la lección 8.

Falta la calibración, motor contra motor, de los ocho peldaños por reloj: cada peldaño juega 40 partidas contra el ancla uci-1320 con colores alternados y una apertura aleatoria por pareja, y el script imprime el Elo que explica el marcador al lado de la etiqueta del peldaño.

uv run python labs/m6/ladder_check.py --games 40

anchor uci-1320 (1320) · 40 games per rung · 0.1 s per move
rung        label   score  measured         IC 95 %   delta
skill-0      1381   0.588      1381    1276-1488         +0
skill-1      1467   0.762      1523    1418-1669        +56
uci-1500     1500   0.725      1488    1381-1621        -12
skill-2      1589   0.762      1523    1418-1658        -66
skill-3      1678   0.938      1790    1658-2520       +112
uci-1800     1800   0.900      1702    1561-1956        -98
uci-2000     2000   0.950      1832    1679-2520       -168
2126 s
control: uci-1500 should read about +180 over the anchor; if it does not, stop here.

El control pasa: uci-1500 sale a +168 sobre el ancla, donde los autores de Stockfish lo ponen a +180. Las siete etiquetas caen dentro del intervalo de su medición, así que la escalera se sostiene. Los intervalos de los tres peldaños altos son enormes (hasta 2520) porque el ancla pierde casi todo contra ellos: 40 partidas contra un rival que gana el 95 % solo dicen que está lejos. Es la limitación de calibrar con un solo ancla, y el motivo de que la escalera use ocho peldaños y no dos.

Lab 2 · La tabla entera con un comando

// Viene delección 3 · El baseline público: el nanoGPT de Karvonen en nuestra escalera y lección 4 · La tabla cada noche: doce etapas, un comando, una fecha

La tabla única exige todas las etapas, la misma suite y el mismo día. rukh eval nightly recorre el catálogo de rukh pull, trae lo que falte, fusiona cada adaptador LoRA sobre su base, mide lo que no está en caché y reescribe artifacts/web/results.json y docs/benchmarks.md. Primero el plan, que no mide nada:

uv run rukh eval nightly --dry-run

stage                           measure  status     seconds  checkpoint
tiny-greedy                     decoder  planned        0.0  checkpoints/tiny/best.pt
small-v3-greedy                 decoder  planned        0.0  checkpoints/small-v3/best.pt
medium-v4-greedy                decoder  planned        0.0  checkpoints/medium-v4/best.pt
encoder-v4                      encoder  planned        0.0  checkpoints/encoder-heads-v4/step-4000.pt
medium-elo                      decoder  planned        0.0  checkpoints/medium-elo/step-3800.pt
medium-masters                  decoder  planned        0.0  checkpoints/medium-masters/step-3800.pt
lora-e4                         decoder  planned        0.0  checkpoints/lora-e4
lora-d4                         decoder  planned        0.0  checkpoints/lora-d4
qwen3-pgn-qlora                 qwen     planned        0.0  checkpoints/qwen3-pgn-qlora
medium-v4-dpo-onpolicy-greedy   decoder  planned        0.0  checkpoints/medium-v4-dpo-onpolicy/dpo.pt
medium-v4-grpo-greedy           decoder  planned        0.0  checkpoints/medium-v4-grpo/grpo.pt
karvonen-8l                     karvonen planned        0.0  checkpoints/karvonen-8l/lichess_8layers_ckpt_no_optimizer.pt

Doce etapas: las nueve del proyecto que juegan, el encoder y los dos baselines, el Qwen3 general que afinó M4 y el nanoGPT de Karvonen de la lección 3, el único que no es del curso.

uv run rukh eval nightly

stage                           measure  status     seconds
tiny-greedy                     decoder  measured     698.1
small-v3-greedy                 decoder  measured     825.3
medium-v4-greedy                decoder  measured     866.4
encoder-v4                      encoder  measured       7.1
medium-elo                      decoder  measured     864.8
medium-masters                  decoder  measured     872.7
lora-e4                         decoder  measured     849.5
lora-d4                         decoder  measured     913.6
qwen3-pgn-qlora                 qwen     measured    2506.2
medium-v4-dpo-onpolicy-greedy   decoder  measured     858.4
medium-v4-grpo-greedy           decoder  measured     843.4
karvonen-8l                     karvonen failed         0.1  (ValueError: … holds no model_state to hash)
seconds:    10106

Dos horas y cuarenta y ocho minutos: unos catorce minutos por etapa de decoder, siete segundos el encoder (no juega), cuarenta y dos Qwen, y un fallo: el checkpoint de Karvonen guarda sus tensores bajo model y no bajo model_state, y el hash de pesos de la lección 2 no lo sabía. Con el hash arreglado, rukh eval nightly --only karvonen-8l lo midió en quince minutos.

Esa salida es la del hito, no la que vas a ver tú. El weights_sha que tecleaste en la lección 2 es el arreglado, que ya lee payload.get("model"), así que en tu tirada karvonen-8l sale measured a la primera y el --only no hace falta; cuenta con unos quince minutos más en el total. Las dos filas que no están en el catálogo (small v1 y el DPO fuera de política) se volvieron a medir a mano el mismo día para que ninguna fila de decoder tuviera otra fecha: 1355 (1297-1420) y 1586 (1530-1651). Las dos filas del encoder que llevaban el nombre de su carpeta de ejecución se retiran con rukh eval drop, y la tabla que queda es la de la lección 8.

Lab 3 · Lo que cuesta el int8, en Elo

// Viene delección 6 · int8 y el jugador ONNX: un grafo exportado en la escalera

M2 midió la paridad y dejó la pregunta abierta: un int8 que elige otra jugada una vez de cada veinte, ¿cuánto peor juega? OnnxDecoder pone el grafo dentro del mismo DecoderPlayer que usa el checkpoint, así que las tres precisiones pasan por la misma máscara, el mismo muestreo y el mismo rescate. ONNX Runtime juega en CPU, y por eso el rival va por nodos: por tiempo, un jugador más lento cambiaría también al motor.

El lab lee una exportación de medium-v4 que ninguna lección anterior hizo (M2 exportó tiny y small, y rukh pull baja los pesos, no los ONNX). Primero se exporta, con el mismo comando de M2; --check-parity escribe el parity.json que el script lee, con la paridad de cada precisión sobre 1 000 posiciones de validación:

uv run rukh export --ckpt checkpoints/medium-v4/best.pt --out artifacts/onnx/medium-v4 --fp16 --int8 --check-parity
uv run python labs/m6/parity_cost.py --onnx artifacts/onnx/medium-v4 --config configs/eval/ladder-nodes.yaml

La exportación deja model.onnx, model-fp16.onnx, model-int8.onnx y parity.json en artifacts/onnx/medium-v4/. Sin GPU, o sin 41 minutos de máquina, trae las tres medidas del hito y la figura que salió de ellas en vez de jugarlas:

git checkout p6 -- artifacts/eval/parity-cost artifacts/web/parity-cost.json

artifacts/eval/parity-cost/ tiene un JSON por precisión, con el EloResult entero, y artifacts/web/parity-cost.json es el resumen que dibuja la figura de la lección 8.

medium-v4 · 20 games per rung · 8 rungs · 200000 nodes

fp32   parity  1.000  elo 1472 (1415-1527)  160 games  816 s
fp16   parity  0.999  elo 1535 (1484-1600)  160 games  837 s
int8   parity  0.951  elo 1524 (1467-1576)  160 games  813 s

El 4,9 % de jugadas distintas del int8 cuesta menos de lo que la escalera puede ver con 160 partidas: su intervalo y el del fp16 casi se superponen. El fp32, la misma red que el checkpoint, sale 60 puntos por debajo del fp16 sin ningún mecanismo que lo explique: el suelo del instrumento otra vez. Ver una diferencia tan pequeña pediría un enfrentamiento directo de miles de partidas, que es el segundo ejercicio de este lab.

Lab 4 · Las cards y la colección, regeneradas desde la tabla

// Viene delección 5 · El Hub y las cards: el catálogo, la vuelta y la afirmación pública

Cuando la tabla cambia, todas las cards quedan desactualizadas, y republicar 460 MB de pesos para cambiar un párrafo es la herramienta equivocada. rukh publish cards prepara cada repositorio como su propio publicador, en seco, y sube solo el README.md, que ahora lleva una sección «In the course» con la lección, la fila, la demo y el rukh pull de cada modelo.

uv run rukh publish cards --dry-run

chorcat/rukh-tiny                  staged    artifacts/publish/chorcat/rukh-tiny/README.md
chorcat/rukh-small                 staged    artifacts/publish/chorcat/rukh-small/README.md
chorcat/rukh-medium                staged    artifacts/publish/chorcat/rukh-medium/README.md
…
chorcat/rukh-tokenizer             staged    data/publish/rukh-tokenizer/README.md

La primera vez que se lanzó, rukh-tiny falló por la guarda del hash de fichero: es el caso que resolvió el hash de pesos (lecciones 2 y 5).

Los dos comandos de abajo publican en chorcat, y no hay opción para cambiarlo: el catálogo fija el owner (lección 5). Con tu cuenta, quédate en el --dry-run de arriba y sube la card que quieras a un repositorio tuyo con uv run hf upload <tu-usuario>/<repo> <ruta-de-la-card> README.md.

uv run rukh publish cards
uv run rukh publish collection

La colección se monta desde el mismo catálogo, así que lo que se descarga, lo que se lee y lo que está en la tabla son la misma lista de veintiún repositorios. Lanzarla dos veces no cambia nada.

Lab 5 · La arena: dos etapas, en tu navegador

// Viene delección 7 · La demo final: arena, puzles y tu propio modelo desde el disco

M5 enseñó que para medir una diferencia se mide la diferencia, y la demo lo hace ahora en el navegador con la aritmética de rukh eval match (lección 7). Al lado del marcador imprime cuántas partidas harían falta para separar una diferencia de ese tamaño del cero, para que nadie lea diez partidas como un veredicto.

Lab 6 · Los puzles, en vivo, contra la fila de la tabla

// Viene delección 7 · La demo final: arena, puzles y tu propio modelo desde el disco

Los 150 puzles de la demo salen del mismo split de test que la suite, se preguntan con el prefijo real de la partida y los Elo, y se cuentan con el mismo criterio: la línea entera.

Lab 7 · El post del cierre

// Viene delección 8 · Evaluar: lo que salió

El cierre de la fase es un texto: el guion del vídeo, con las tres cifras que importan y ninguna que no esté en docs/benchmarks.md o en el registro de decisiones. Se escribe después de la tabla, nunca antes.

Los cuatro scripts de labs/m6

Los siete labs se apoyan en cuatro scripts: dos miden el instrumento, uno responde la pregunta de M2 y uno exporta los puzles de la demo. Van enteros porque producen las cifras de la lección 8. Sus docstrings conservan la numeración de labs de antes de reordenarlos («Lab 2 of M6» es el lab 3 de esta página, «Lab 5 of M6» el 6); la buena es la de aquí.

ladder_check.py: calibrar la escalera contra sí misma

"""Measure the ladder against itself: every rung plays the anchor, engine against engine.

Lab 1 of M6, and the method of D-070 turned into a script. The four ``Skill Level`` rungs of the
Elo ladder were once labelled 800/950/1100/1250 by assumption and measured 1381/1467/1589/1678;
the labels of a ladder are hypotheses until the rungs have played each other. This plays each
rung against ``uci-1320`` (the anchor, the floor of ``UCI_Elo``) with colours alternated and a
seeded random opening per pair, and prints the rating that explains the score, with its
interval, next to the label the ladder carries.

It takes the same limit the harness takes -- a clock or a node budget -- so the ladder can be
calibrated for the regime it is going to be used in:

    uv run python labs/m6/ladder_check.py --games 40                 # 0.1 s per move, as P2-P5
    uv run python labs/m6/ladder_check.py --games 40 --nodes 200000  # the node budget of M6

The control is built in: ``uci-1500`` against ``uci-1320`` should come out near +180. If it
does not, the procedure is biased and no other row of the table means anything.
"""

↗labs/m6/ladder_check.pylíneas 1-18 · p6

La última frase lleva el control dentro: uci-1500 contra uci-1320 tiene que salir cerca de +180, lo que los autores de Stockfish dicen de esos dos ajustes. Si no sale, el procedimiento está sesgado y ninguna otra fila significa nada. El patrón vale para cualquier medición: mete una medida cuyo valor ya conoces y mírala antes que las que no conoces.

from __future__ import annotations

import argparse
import math
import sys
import time

import chess
import numpy as np

from rukh.eval.elo import DEFAULT_RUNGS, EloRung
from rukh.eval.match import opening_book
from rukh.infer.game import StockfishOpponent

if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

ANCHOR = DEFAULT_RUNGS[0]
MAX_PLIES = 300

↗labs/m6/ladder_check.pylíneas 20-38 · p6

sys.stdout.reconfigure(encoding="utf-8") es por Windows: la consola no es UTF-8, la salida lleva un ·, y sin esa línea una UnicodeEncodeError mataría treinta y cinco minutos de tirada al imprimir el resultado. ANCHOR = DEFAULT_RUNGS[0] toma el ancla del propio harness, así que si la escalera cambiara de peldaño más bajo el script calibraría contra el nuevo.

def elo_of(score: float) -> float:
    """The rating difference that explains a score, clipped away from 0 and 1."""
    p = min(max(score, 1e-3), 1 - 1e-3)
    return 400.0 * math.log10(p / (1.0 - p))


def play(white: StockfishOpponent, black: StockfishOpponent, opening: list[str]) -> float:
    """One game from ``opening``; the score from White's point of view."""
    board = chess.Board()
    for uci in opening:
        board.push_uci(uci)
    while not board.is_game_over(claim_draw=True) and board.ply() < MAX_PLIES:
        mover = white if board.turn == chess.WHITE else black
        board.push(mover.choose(board))
    if board.is_game_over(claim_draw=True):
        result = board.result(claim_draw=True)
        return {"1-0": 1.0, "0-1": 0.0}.get(result, 0.5)
    return 0.5  # out of plies: a draw, the same adjudication the harness would not accept but fair

↗labs/m6/ladder_check.pylíneas 41-58 · p6

elo_of es la misma fórmula con el mismo recorte que la arena de la lección 7 y el harness. Tres implementaciones de la misma cuenta, en un script, un módulo del paquete y un fichero de TypeScript que no se pueden importar entre sí; las mantiene iguales que el recorte, 1e-3, tiene el mismo valor en las tres.

Una partida que se queda sin plies cuenta aquí como tablas, «una adjudicación que el harness no aceptaría pero es justa». El harness adjudica por material, porque una partida cortada con ventaja decisiva no son tablas; aquí los dos jugadores son el mismo motor a fuerzas parecidas, y el sesgo se reparte por igual.

def measure(
    rung: EloRung, games: int, seed: int, move_time: float, nodes: int | None
) -> tuple[float, float, float, float]:
    """Score of ``rung`` against the anchor, its Elo over the anchor and a bootstrap interval."""
    book = opening_book(games // 2, plies=6, seed=seed)
    scores: list[float] = []
    with (
        StockfishOpponent(
            elo=rung.uci_elo or 1320, skill=rung.skill, move_time=move_time, nodes=nodes
        ) as candidate,
        StockfishOpponent(elo=ANCHOR.uci_elo or 1320, move_time=move_time, nodes=nodes) as anchor,
    ):
        for opening in book:
            scores.append(play(candidate, anchor, opening))  # rung as White
            scores.append(1.0 - play(anchor, candidate, opening))  # rung as Black
    draws = np.asarray(scores)
    rng = np.random.default_rng(seed)
    boots = [
        elo_of(float(rng.choice(draws, size=len(draws), replace=True).mean())) for _ in range(500)
    ]
    lo, hi = np.percentile(boots, [2.5, 97.5])
    return float(draws.mean()), elo_of(float(draws.mean())), float(lo), float(hi)

↗labs/m6/ladder_check.pylíneas 61-82 · p6

opening_book(games // 2, ...) y dos partidas por apertura, una con cada color: el emparejamiento espejado de la arena y de rukh eval match, que con aperturas aleatorias es la única forma de que la ventaja de las blancas no se cuele en la calibración. 1.0 - play(anchor, candidate, opening) invierte el resultado en vez de inventar otra convención, y evita el error de signo más probable del fichero.

El with abre dos procesos de Stockfish a la vez y los cierra pase lo que pase. Dos motores compitiendo por la CPU es el escenario en que el rival por reloj no repite, y por eso el script acepta --nodes. El bootstrap reutiliza la semilla de las aperturas: son dos usos independientes y ahorra un parámetro.

def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    parser.add_argument("--games", type=int, default=40, help="Games per rung (even).")
    parser.add_argument("--seed", type=int, default=7)
    parser.add_argument("--move-time", type=float, default=0.1)
    parser.add_argument("--nodes", type=int, default=None, help="Node budget instead of the clock.")
    args = parser.parse_args()
    if args.games % 2:
        raise SystemExit("--games must be even: every opening is played with both colours")
    regime = f"{args.nodes} nodes" if args.nodes else f"{args.move_time:g} s per move"
    print(f"anchor {ANCHOR.name} ({ANCHOR.elo}) · {args.games} games per rung · {regime}\n")
    print(f"{'rung':<10}{'label':>7}{'score':>8}{'measured':>10}{'IC 95 %':>16}{'delta':>8}")
    started = time.perf_counter()
    for rung in DEFAULT_RUNGS[1:]:
        score, over, lo, hi = measure(rung, args.games, args.seed, args.move_time, args.nodes)
        measured = ANCHOR.elo + over
        print(
            f"{rung.name:<10}{rung.elo:>7}{score:>8.3f}{measured:>10.0f}"
            f"{ANCHOR.elo + lo:>8.0f}-{ANCHOR.elo + hi:<7.0f}{measured - rung.elo:>+8.0f}"
        )
    print(f"\n{time.perf_counter() - started:.0f} s")
    print("control: uci-1500 should read about +180 over the anchor; if it does not, stop here.")


if __name__ == "__main__":
    main()

↗labs/m6/ladder_check.pylíneas 85-110 · p6

Un número impar de partidas se rechaza antes de jugar, con el motivo en el mensaje («cada apertura se juega con los dos colores»). La cabecera imprime el régimen (0.1 s per move o 200000 nodes), porque una calibración sin él acabará comparada con otra de otro régimen. Y la última línea repite el control, donde queda el cursor. La salida de la tirada está en el lab 1.

ladder_floor_export.py: las cuatro tiradas, en una figura

"""The floor of the ladder, as a figure: four runs of the same model, two on a clock, two on nodes.

D-107 found that the same configuration with the same seed gave 1498 and 1558, because the
opponent plays on a clock and a clock is not the same twice. M6 measured it on purpose: the same
checkpoint, the same rungs, games and seed, twice with ``elo_move_time`` and twice with
``elo_nodes``. This collects the four ``results.json`` and writes the course figure's
``artifacts/web/ladder-floor.json``, with the spread between the two runs of each regime and the
regime that was chosen (D-135):

    uv run python labs/m6/ladder_floor_export.py --decision nodes
"""

↗labs/m6/ladder_floor_export.pylíneas 1-11 · p6

from __future__ import annotations

import argparse
import json
from datetime import UTC, datetime

from rukh.paths import resolve

RUNS = {
    "time-a": ("ladder-time-a", "time"),
    "time-b": ("ladder-time-b", "time"),
    "nodes-a": ("ladder-nodes-a", "nodes"),
    "nodes-b": ("ladder-nodes-b", "nodes"),
}

↗labs/m6/ladder_floor_export.pylíneas 13-26 · p6

El diccionario RUNS es el contrato con los cuatro nombres de etapa que el lab 1 escribió con --stage. Es un acoplamiento por cadena, y la protección es que un fichero que falta se imprime y se salta.

def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    parser.add_argument("--decision", choices=["time", "nodes"], required=True)
    parser.add_argument("--out", default="artifacts/web/ladder-floor.json")
    args = parser.parse_args()

    runs: list[dict[str, object]] = []
    model = None
    games = None
    for name, (stage, limit) in RUNS.items():
        path = resolve(f"artifacts/eval/{stage}/results.json")
        if not path.is_file():
            print(f"{name}: {path} missing, skipped")
            continue
        result = json.loads(path.read_text(encoding="utf-8"))
        elo = result["elo"]
        model = model or result.get("checkpoint")
        games = games or elo.get("games")
        runs.append(
            {
                "name": name,
                "limit": limit,
                "elo": round(elo["elo"]),
                "lo": None if elo.get("ci_low") is None else round(elo["ci_low"]),
                "hi": None if elo.get("ci_high") is None else round(elo["ci_high"]),
                "date": result.get("date"),
            }
        )
        print(f"{name:<8} {limit:<6} {runs[-1]['elo']} ({runs[-1]['lo']}-{runs[-1]['hi']})")

↗labs/m6/ladder_floor_export.pylíneas 29-57 · p6

model y games se toman de la primera tirada que se encuentre, sin comprobarlos contra las demás. Si alguien mezclara resultados de dos modelos, la figura diría el nombre del primero; lo que lo impide es el procedimiento (las cuatro tiradas salen de una sesión), no el código. Y un resultado separado no tiene intervalo, así que round(None) explotaría sin el ternario.

    spread = {}
    for limit in ("time", "nodes"):
        pair = [r["elo"] for r in runs if r["limit"] == limit]
        if len(pair) == 2:
            spread[limit] = abs(int(pair[0]) - int(pair[1]))
            print(f"spread {limit}: {spread[limit]} Elo")

    out = resolve(args.out)
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_text(
        json.dumps(
            {
                "meta": {
                    "generated": datetime.now(UTC).isoformat(timespec="seconds"),
                    "model": model,
                    "games": games,
                },
                "runs": runs,
                "spread": spread,
                "decision": args.decision,
            },
            indent=2,
        )
        + "\n",
        encoding="utf-8",
    )
    print(f"wrote {out}")


if __name__ == "__main__":
    main()

↗labs/m6/ladder_floor_export.pylíneas 59-89 · p6

spread solo se calcula con dos tiradas del mismo régimen: con una, un cero publicaría «repite perfectamente» sobre una medición que no se hizo. El campo decision es lo que la figura imprime al lado de los cuatro números, porque además de la medición hay que publicar qué se decidió con ella: time, el rival se queda por reloj. El ejemplo del docstring escribe --decision nodes y cita otra decisión del registro: son dos erratas del tag p6, y el comando que se ejecutó es el del lab 1.

parity_cost.py: lo que cuesta cada precisión, jugando

"""What the export costs in Elo: fp32, fp16 and int8 of the same model on the same ladder.

Lab 2 of M6. M2 measured **parity** -- in how many positions each export picks the checkpoint's
move (fp16 99.9 %, int8 95.1 % for ``medium-v4``) -- and left the question that matters open: a
model that plays another move once in twenty games is another player, so how much weaker is it?
Parity cannot answer that; only playing can. This puts each ONNX file on the very ladder every
published Elo was measured on, through the same ``DecoderPlayer`` (same masking, sampling and
rescue), with the same rungs, games and seed, and writes one interval per precision next to the
parity that was already known:

    uv run python labs/m6/parity_cost.py --onnx artifacts/onnx/medium-v4 \
        --config configs/eval/greedy.yaml

ONNX Runtime plays on the CPU here, so the opponent's limit should be a node budget (the config's
``elo_nodes``): on a clock, a slower player would make the engine's side of the game different,
and the comparison would be between two Stockfishes, not between three exports.

Writes ``artifacts/eval/parity-cost/<name>.json`` (one ``EloResult`` per precision) and
``artifacts/web/parity-cost.json`` for the course figure.
"""

↗labs/m6/parity_cost.pylíneas 1-20 · p6

El segundo párrafo del docstring deja escrita la razón del rival por nodos: con ONNX Runtime en CPU y el rival por reloj, un jugador más lento haría jugar distinto al motor, y la comparación sería entre dos Stockfish y no entre tres exportaciones. Es la única medición del proyecto donde los nodos eran la opción correcta, y por eso el lab usa ladder-nodes.yaml y no el greedy.yaml del ejemplo.

Un aviso sobre el primer párrafo: las cifras son buenas, la atribución no. M2 midió la paridad de small (99,80 % en fp16, 95,40 % en int8); las de medium-v4 (99,9 % y 95,1 %) las mide la exportación del lab 3, con el --check-parity que escribe el parity.json que el script lee.

from __future__ import annotations

import argparse
import json
import sys
import time
from datetime import UTC, datetime

from rukh.config import load_yaml
from rukh.eval.elo import estimate, play_rungs
from rukh.eval.suite import EvalConfig
from rukh.infer import DecoderPlayer
from rukh.infer.onnx_player import OnnxDecoder
from rukh.paths import resolve
from rukh.tokenize.uci_vocab import UciTokenizer

PRECISIONS = {"fp32": "model.onnx", "fp16": "model-fp16.onnx", "int8": "model-int8.onnx"}

↗labs/m6/parity_cost.pylíneas 22-38 · p6

PRECISIONS mapea el nombre a los tres ficheros que escribe rukh export --fp16 --int8; es un diccionario porque la salida se ordena por él y --only fp16 int8 valida contra sus claves.

def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    parser.add_argument("--onnx", default="artifacts/onnx/medium-v4", help="Folder of the export.")
    parser.add_argument("--config", default="configs/eval/greedy.yaml")
    parser.add_argument("--games", type=int, default=None, help="Games per rung (config's).")
    parser.add_argument("--only", nargs="*", default=list(PRECISIONS), choices=list(PRECISIONS))
    parser.add_argument("--out", default="artifacts/eval/parity-cost")
    parser.add_argument("--web", default="artifacts/web/parity-cost.json")
    args = parser.parse_args()

    cfg = load_yaml(resolve(args.config), EvalConfig)
    games = args.games or cfg.elo_games
    folder = resolve(args.onnx)
    parity = json.loads((folder / "parity.json").read_text(encoding="utf-8"))
    out = resolve(args.out)
    out.mkdir(parents=True, exist_ok=True)
    tok = UciTokenizer()
    regime = f"{cfg.elo_nodes} nodes" if cfg.elo_nodes else f"{cfg.elo_move_time} s"
    print(f"{folder.name} · {games} games per rung · {len(cfg.elo_rungs)} rungs · {regime}\n")

↗labs/m6/parity_cost.pylíneas 41-59 · p6

parity.json se lee de la exportación de M2, no se recalcula: este lab pone la paridad al lado del Elo, que es el gesto que la lección quiere enseñar. games = args.games or cfg.elo_games permite recortar para una prueba, y el régimen va en la cabecera, como en el script anterior.

    variants: list[dict[str, object]] = []
    for name in args.only:
        path = folder / PRECISIONS[name]
        if not path.is_file():
            print(f"{name:<6} missing ({path.name}), skipped", file=sys.stderr)
            continue
        agreement = parity["precisions"].get(name, {}).get("agreement")
        started = time.perf_counter()
        player = DecoderPlayer(OnnxDecoder(path), tok, cfg.sampling())  # type: ignore[arg-type]
        records = play_rungs(
            None,
            tok,
            cfg.elo_rungs,
            games,
            cfg.sampling(),
            move_time=cfg.elo_move_time,
            max_plies=cfg.elo_max_plies,
            header_elo=cfg.header_elo,
            player=player,
            nodes=cfg.elo_nodes,
        )
        result = estimate(records, samples=cfg.bootstrap, seed=cfg.seed)
        elapsed = time.perf_counter() - started
        (out / f"{name}.json").write_text(
            json.dumps(
                {
                    "precision": name,
                    "file": path.as_posix(),
                    "parity": agreement,
                    "games": games,
                    "regime": regime,
                    "seed": cfg.seed,
                    "seconds": round(elapsed),
                    "elo": result.model_dump(mode="json"),
                },
                indent=2,
            )
            + "\n",
            encoding="utf-8",
        )
        variants.append(
            {
                "name": name,
                "parity": agreement,
                "elo": round(result.elo),
                "lo": None if result.ci_low is None else round(result.ci_low),
                "hi": None if result.ci_high is None else round(result.ci_high),
                "games": result.games,
            }
        )
        low = "?" if result.ci_low is None else f"{result.ci_low:.0f}"
        high = "?" if result.ci_high is None else f"{result.ci_high:.0f}"
        print(
            f"{name:<6} parity {agreement if agreement is None else f'{agreement:.3f}':>6}  "
            f"elo {result.elo:.0f} ({low}-{high})  {result.games} games  {elapsed:.0f} s"
        )

↗labs/m6/parity_cost.pylíneas 61-116 · p6

El bucle no reimplementa nada: el grafo entra por el jugador de la lección 6 (DecoderPlayer(OnnxDecoder(path), ...)), la escalera es la de la lección 2 y el estimate es el de M2. Poco código para responder una pregunta abierta desde hacía cuatro módulos, porque todas las piezas existían.

Un fichero que falta se salta con un aviso en stderr, así que quien solo exportó fp16 e int8 obtiene dos filas. Y los JSON por precisión se escriben dentro del bucle: cada uno cuesta catorce minutos de motor, y perderlos porque falle el tercero sería el error que el nightly evita con su except.

    web = resolve(args.web)
    web.parent.mkdir(parents=True, exist_ok=True)
    web.write_text(
        json.dumps(
            {
                "meta": {
                    "generated": datetime.now(UTC).isoformat(timespec="seconds"),
                    "games": games,
                    "regime": regime,
                },
                "model": folder.name,
                "variants": variants,
            },
            indent=2,
        )
        + "\n",
        encoding="utf-8",
    )
    print(f"\nwrote {web}")


if __name__ == "__main__":
    main()

↗labs/m6/parity_cost.pylíneas 118-140 · p6

El JSON de la figura lleva además un meta con la fecha, las partidas y el régimen: la figura no puede dibujar tres barras sin decir con qué presupuesto se jugaron. La salida está en el lab 3.

puzzles_export.py: los 150 puzles de la demo

"""Export a small, seeded set of test puzzles for the demo's live puzzle mode.

Lab 5 of M6. The demo cannot read a parquet and should not download 22 MB to show fifty puzzles,
so this writes `artifacts/web/puzzles.json`: 50 puzzles per difficulty band drawn from the
`test` split of `chorcat/rukh-puzzles-split` with the same loader the harness uses
(`rukh.eval.puzzles.load_puzzles`), so what the browser attempts is exactly what the table
measured -- the real game prefix, the players' own ratings in the header, and the whole line as
the criterion (D-053). The file is copied into `rukh-web/public/puzzles.json` by hand (it is
versioned there: the demo must not depend on this repository being around).

    uv run python labs/m6/puzzles_export.py            # 50 per band, seed 6
    uv run python labs/m6/puzzles_export.py --per-band 20 --seed 1
"""

↗labs/m6/puzzles_export.pylíneas 1-13 · p6

Dos frases del docstring son decisiones. La demo no puede leer un parquet ni debería descargar 22 MB para enseñar cincuenta puzles, así que se exporta un JSON de 150. Y el fichero se copia a mano a rukh-web/public/puzzles.json y se versiona allí: dos repositorios que se despliegan por separado no comparten artefactos generados.

from __future__ import annotations

import argparse
import json
import sys
from datetime import UTC, datetime

from rukh.eval.puzzles import load_puzzles
from rukh.paths import resolve

if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

SCHEMA = "rukh-puzzles/1"

↗labs/m6/puzzles_export.pylíneas 15-28 · p6

def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    parser.add_argument("--puzzles", default="data/puzzles/puzzles.parquet")
    parser.add_argument("--per-band", type=int, default=50)
    parser.add_argument("--seed", type=int, default=6)
    parser.add_argument("--split", default="test")
    parser.add_argument("--out", default="artifacts/web/puzzles.json")
    args = parser.parse_args()

    items = load_puzzles(resolve(args.puzzles), args.per_band, seed=args.seed, split=args.split)
    without_prefix = sum(1 for item in items if not item.prefix)
    if without_prefix:
        raise SystemExit(
            f"{without_prefix} puzzles carry no game prefix; the demo prompts with the real game "
            "(D-053), so the parquet must be the `with_games` one"
        )

↗labs/m6/puzzles_export.pylíneas 31-46 · p6

load_puzzles es el cargador del harness con los mismos argumentos (split, semilla, número por tramo), así que los 150 puzles son una muestra del mismo conjunto que mide la tabla.

La guarda que sigue es la decisión central: si algún puzle llega sin prefijo de partida, el script se niega a escribir. Un puzle sin prefijo se preguntaría «a ciegas» (lección 3) y la tasa sería un suelo. Negarse es más útil que avisar, porque el fichero acaba en otro repositorio donde nadie leería el aviso.

    bands: dict[str, list[dict[str, object]]] = {}
    for item in items:
        bands.setdefault(item.band, []).append(
            {
                "id": item.puzzle_id,
                "fen": item.fen,
                "moves": item.moves,
                "rating": item.rating,
                "prefix": item.prefix,
                "whiteElo": item.white_elo,
                "blackElo": item.black_elo,
            }
        )
    payload = {
        "schema": SCHEMA,
        "source": f"chorcat/rukh-puzzles-split · split {args.split}",
        "seed": args.seed,
        "perBand": args.per_band,
        "generated": datetime.now(UTC).isoformat(timespec="seconds"),
        "bands": bands,
    }
    out = resolve(args.out)
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_text(json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n", "utf-8")
    print(f"{out} · {sum(len(v) for v in bands.values())} puzzles · {out.stat().st_size:,} bytes")
    for band, rows in sorted(bands.items()):
        ratings = [row["rating"] for row in rows]
        print(f"  {band:<10} {len(rows):>3} puzzles · rating {min(ratings)}-{max(ratings)}")


if __name__ == "__main__":
    main()

↗labs/m6/puzzles_export.pylíneas 47-78 · p6

El payload lleva los campos que src/lib/puzzles.ts comprueba en la lección 7: los dos lados de la frontera se escribieron con el mismo contrato delante. separators=(",", ":") quita espacios a un fichero que se sirve en cada visita, y ensure_ascii=False deja los caracteres tal cual. Las dos últimas líneas imprimen el tamaño y el rango de dificultad de cada tramo, para ver un tramo raro antes de copiar el fichero.

La lista de comprobación, sin ajedrez

Todo lo anterior es de este proyecto. Esto es el mismo cierre escrito sin una palabra de ajedrez, para cuando midas y publiques otra cosa. Nueve puntos, y cada uno tapa un error que este módulo estuvo a punto de cometer.

Antes de medir:

1. Mide el instrumento contra sí mismo. El mismo modelo contra el mismo modelo tiene que dar empate; la misma suite repetida tiene que repetir dentro de su ruido. Lo que se mueva ahí es suelo.
2. Escribe el suelo antes de ver el resultado. Si dos tiradas idénticas se separan 60 puntos, una mejora de 40 no existe por mucho que salga.

Al medir:

3. Una suite para todas las filas: misma configuración, mismo muestreo, mismo corte.
4. Registra el fichero exacto y el muestreo: el checkpoint, la precisión, la temperatura y la semilla. Sin eso el número no se puede volver a sacar.
5. Publica y compara intervalos. Dos que se solapan son una pregunta que aún no has pagado.

Antes de publicar:

6. Mide lo que vas a servir. Lo que corre en producción está cuantizado, convertido o recompilado; mide ese fichero, no el que entrenaste.
7. Genera la ficha desde la tabla. Una escrita a mano envejece en silencio.
8. Escribe qué no puedes afirmar: el proxy que usaste, contra qué se midió y en qué se parece a lo que le importa a quien lo lea.
9. Deja el comando que lo reproduce todo. Si el lector no puede sacar tu intervalo, has publicado una cifra, no un resultado.

Lo que deja el módulo

Si te quedas con tres ideas, que sean estas.

Mide el instrumento antes de fiarte de él. Cuatro escaleras del mismo modelo, una calibración y una tabla vieja frente a una nueva dijeron lo mismo: con la máquina parada el reloj repite al nivel del ruido de muestreo, los nodos no compran nada, y lo que se mueve es lo que el intervalo permite. Sin esa medición, los +72 de dpo-onpolicy en un día habrían parecido una noticia.

Una tabla es de un día. Trece filas de decoder con la misma fecha, un comando que las regenera y cada card diciendo sobre qué fichero y con qué muestreo se midió cada número. La fila que no cumple eso se retira o se vuelve a medir.

Lo que no se puede decir es parte del resultado. Un Elo contra Stockfish limitado no es un Elo de Lichess, una paridad no es una fuerza, un baseline medido con otro harness no es un baseline, y quien te lea reproduce el intervalo, no el número.

El balance de la fase 1

Cuando empezaste no había aprendiz: había un club por montar, con su tablero, su árbitro y su cuaderno de bitácora. Luego le enseñaste a escribir una jugada y le ordenaste la biblioteca. Leyó millones de partidas y aprendió a adivinar la siguiente, de oído. Aprendió a mirar una posición entera y decir quién iba mejor. Recibió clases particulares y, con unas notas adhesivas de 1,6 MB, cambió de repertorio sin cambiar de fuerza. Tuvo un entrenador que le enseñó a preferir, y tú aprendiste a vigilar que no jugara para agradar al juez. En este módulo salió a competir: un rating medido con las mismas reglas para todos, una ficha que dice sobre qué fichero se midió cada número y una mesa en la que cualquiera puede sentarse a jugarle.

Ahora juega con un número al lado que dice cuánto vale, y sabes cuánto fiarte de ese número. Ese recorrido (infraestructura, datos, preentrenamiento, comprensión, ajuste fino, alineamiento, evaluación y despliegue) es el de cualquier modelo de lenguaje, hecho entero con uno pequeño, en una sola GPU, dejando en cada paso un artefacto que se puede descargar y una cifra que se puede contradecir.

Los tres criterios de aceptación del módulo se cumplieron. La tabla única y reproducible con todas las etapas y los baselines públicos: trece filas de decoder medidas el mismo día (once con un comando y dos a mano), dos baselines (Karvonen y el Qwen3 afinado en M4) y el suelo del instrumento publicado con ella. Las model cards en inglés para cada modelo de la colección: veintiuna, regeneradas desde la tabla, cada una con su lección, su fila, su demo y su rukh pull. Y la demo final con selector de etapa, arena y puzles en vivo, comprobada en Chrome con WebGPU.

Y estos no se cumplieron, de este módulo y de los anteriores:

• La paridad del 99,9 % que pedía la especificación de M2 no se alcanzó en small ni con fp16 (99,80 %), y el int8 se quedó en 95,40 %; medium-v4, medido en el lab 3, sí la toca en fp16 (0,999) y deja el int8 en 95,1 %. M6 midió qué cuesta no alcanzarla: con 160 partidas, menos de lo que la escalera puede ver.
• El 75 % de acierto del reward model de M5 tampoco: 72,91 % y 74,21 % en dos ejecuciones idénticas, y con 1,3 puntos entre ejecuciones iguales perseguirlo con semillas habría sido pescar.
• Maia-2 como segundo baseline condicionado por Elo quedó en el backlog: fija torch 2.8 frente al 2.11 del proyecto y descarga sus pesos de Google Drive. Cabe como proceso hijo en su propio entorno, y el diseño está escrito.
• El bot de Lichess del plan original, que era opcional y necesita una cuenta de bot.
• La arena solo enfrenta etapas publicadas: puedes cargar tu .onnx, jugar contra él y resolver los puzles, pero no enfrentarlo a un modelo del curso.

En la fase 2 el aprendiz se convierte en entrenador. El modelo pasa a ser una herramienta que algo más usa: el encoder de M3 como índice para buscar posiciones y pasajes de libros (A1), un agente que analiza tus partidas llamando al motor y al modelo (A2), y la disciplina de este módulo aplicada a algo cuya salida es texto (A3). De una fase a la otra se lleva la costumbre de medir el instrumento antes de fiarse de él, y de escribir lo que no se puede afirmar al lado de lo que sí.

La cheatsheet del módulo, con su pregunta y su respuesta corta, está justo debajo.