SamilG2 commited on
Commit
8ccac0b
Β·
1 Parent(s): 1607935

feat: sync deterministic coach module + COACH_MODEL dispatcher from develop

Browse files
config.py CHANGED
@@ -22,6 +22,13 @@ TROCR_BATCH_SIZE = int(os.getenv("TROCR_BATCH_SIZE", "8"))
22
  # Se desactiva automΓ‘ticamente si hay GPU CUDA disponible.
23
  TROCR_QUANTIZE = os.getenv("TROCR_QUANTIZE", "auto").lower() # "auto" | "true" | "false"
24
 
 
 
 
 
 
 
 
25
  # ─── App ─────────────────────────────────────────────────────────────────────
26
  MAX_UPLOAD_MB = 10
27
  ALLOWED_EXTENSIONS = {"jpg", "jpeg", "png"}
 
22
  # Se desactiva automΓ‘ticamente si hay GPU CUDA disponible.
23
  TROCR_QUANTIZE = os.getenv("TROCR_QUANTIZE", "auto").lower() # "auto" | "true" | "false"
24
 
25
+ # ─── Modelo de comentarios (entrenador) ──────────────────────────────────────
26
+ # Selecciona quΓ© modelo genera la retroalimentaciΓ³n estratΓ©gica por jugada:
27
+ # "deterministic" β†’ Experimento A: modelo determinΓ­stico propio (modules.deterministic)
28
+ # "qwen" β†’ Experimento B: LLM Qwen2.5 (modules.llm)
29
+ # Ambos son intercambiables; se conserva Qwen para la comparaciΓ³n (DO-002).
30
+ COACH_MODEL = os.getenv("COACH_MODEL", "deterministic").lower()
31
+
32
  # ─── App ─────────────────────────────────────────────────────────────────────
33
  MAX_UPLOAD_MB = 10
34
  ALLOWED_EXTENSIONS = {"jpg", "jpeg", "png"}
modules/deterministic/__init__.py ADDED
@@ -0,0 +1,12 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Modelo DeterminΓ­stico de RetroalimentaciΓ³n EstratΓ©gica (Experimento A β€” TA-003).
2
+
3
+ SubmΓ³dulos:
4
+ features.py β€” matemΓ‘tica (regresiΓ³n, media, racha, cambio de rΓ©gimen, fase)
5
+ estado.py β€” estado recursivo (cadena de Markov)
6
+ reglas.py β€” motor de inferencia (features β†’ patrΓ³n)
7
+ plantillas.py β€” generaciΓ³n de texto (patrΓ³n β†’ {corto, expandido})
8
+ model.py β€” entry point: comentar(move, clasificacion, history)
9
+ """
10
+ from .model import comentar
11
+
12
+ __all__ = ["comentar"]
modules/deterministic/estado.py ADDED
@@ -0,0 +1,72 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Estado estratΓ©gico recursivo del modelo determinΓ­stico (Experimento A β€” TA-003).
2
+
3
+ Formaliza la idea de CADENA DE MARKOV: el estado en la jugada N se obtiene
4
+ aplicando una funciΓ³n de transiciΓ³n al estado anterior y a la jugada actual,
5
+
6
+ estado_N = actualizar(estado_{N-1}, jugada_N)
7
+
8
+ donde el estado resume toda la historia relevante (es un *estadΓ­stico
9
+ suficiente*: contiene la serie y los features derivados de ella). Como la
10
+ transiciΓ³n es determinΓ­stica y sin azar, el mismo historial produce SIEMPRE el
11
+ mismo estado β†’ replicabilidad por construcciΓ³n (RN-004).
12
+
13
+ CategorΓ­a acadΓ©mica: autΓ³mata de estado finito / proceso markoviano determinΓ­stico.
14
+ """
15
+ from __future__ import annotations
16
+ from dataclasses import dataclass, replace
17
+
18
+ from . import features
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class EstadoEstrategico:
23
+ """EstadΓ­stico suficiente de la partida hasta la jugada actual (un jugador).
24
+
25
+ `frozen=True` lo vuelve inmutable: cada transiciΓ³n devuelve un estado nuevo,
26
+ nunca muta el anterior. Esto refuerza la pureza y la replicabilidad.
27
+ """
28
+ n_jugadas: int = 0
29
+ serie_cp: tuple = () # diferencia_cp del jugador, en orden cronolΓ³gico
30
+ errores: int = 0
31
+ imprecisiones: int = 0
32
+ # Features derivados (se recalculan en cada transiciΓ³n).
33
+ media_propia: float = 0.0
34
+ pendiente: float = 0.0
35
+ racha: int = 0
36
+ cambio: float = 0.0
37
+ fase: str = "apertura"
38
+ ultima_clasificacion: str = ""
39
+
40
+
41
+ def actualizar(estado: EstadoEstrategico, dif_cp: int,
42
+ clasificacion: str, numero: int) -> EstadoEstrategico:
43
+ """FunciΓ³n de transiciΓ³n de la cadena de Markov: estado_{N-1} β†’ estado_N."""
44
+ serie = estado.serie_cp + (dif_cp,)
45
+ serie_lista = list(serie)
46
+ media_propia = features.media(serie_lista)
47
+ return replace(
48
+ estado,
49
+ n_jugadas=estado.n_jugadas + 1,
50
+ serie_cp=serie,
51
+ errores=estado.errores + (1 if clasificacion == "Error" else 0),
52
+ imprecisiones=estado.imprecisiones + (1 if clasificacion == "ImprecisiΓ³n" else 0),
53
+ media_propia=media_propia,
54
+ pendiente=features.pendiente(serie_lista[-features.VENTANA:]),
55
+ racha=features.racha_bajo_media(serie_lista, media_propia),
56
+ cambio=features.cambio_regimen(serie_lista),
57
+ fase=features.fase(numero),
58
+ ultima_clasificacion=clasificacion,
59
+ )
60
+
61
+
62
+ def construir(jugadas: list[tuple]) -> EstadoEstrategico:
63
+ """Reduce (fold) la funciΓ³n de transiciΓ³n sobre la secuencia de jugadas.
64
+
65
+ `jugadas`: lista de tuplas (diferencia_cp, clasificacion, numero) en orden
66
+ cronolΓ³gico, correspondientes a un mismo jugador. Aplicar `actualizar`
67
+ repetidamente ES la cadena de Markov desplegada sobre la partida.
68
+ """
69
+ estado = EstadoEstrategico()
70
+ for dif_cp, clasificacion, numero in jugadas:
71
+ estado = actualizar(estado, dif_cp, clasificacion, numero)
72
+ return estado
modules/deterministic/features.py ADDED
@@ -0,0 +1,81 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Capa matemΓ‘tica del modelo determinΓ­stico (Experimento A β€” TA-003).
2
+
3
+ Funciones puras sobre la serie temporal de `diferencia_cp` de UN jugador. Cada
4
+ `diferencia_cp` es, desde el punto de vista del jugador que moviΓ³, cuΓ‘ntos
5
+ centipeones ganΓ³ (positivo) o cediΓ³ (negativo) en esa jugada. Analizar la
6
+ SECUENCIA de estos valores β€”y no el valor puntualβ€” es lo que distingue al
7
+ modelo de una traducción directa cp→texto.
8
+
9
+ CategorΓ­a acadΓ©mica: estadΓ­stica descriptiva + anΓ‘lisis de series temporales.
10
+ """
11
+ from __future__ import annotations
12
+
13
+ # NΒΊ de jugadas propias que forman la "ventana reciente" para tendencia/rΓ©gimen.
14
+ VENTANA = 4
15
+
16
+
17
+ def media(serie: list[float]) -> float:
18
+ """Media aritmΓ©tica de la serie (0.0 si estΓ‘ vacΓ­a)."""
19
+ return sum(serie) / len(serie) if serie else 0.0
20
+
21
+
22
+ def pendiente(serie: list[float]) -> float:
23
+ """Pendiente de la regresiΓ³n lineal por mΓ­nimos cuadrados sobre la serie.
24
+
25
+ Mide la tendencia: negativa y de magnitud apreciable β‡’ el jugador viene
26
+ perdiendo terreno de forma progresiva (deterioro sostenido); positiva β‡’
27
+ viene recuperΓ‘ndose. Es la derivada promedio de la trayectoria, no una
28
+ comparaciΓ³n puntual de dos valores.
29
+ """
30
+ n = len(serie)
31
+ if n < 2:
32
+ return 0.0
33
+ mx = (n - 1) / 2 # media de los Γ­ndices 0..n-1
34
+ my = media(serie)
35
+ num = sum((x - mx) * (y - my) for x, y in enumerate(serie))
36
+ den = sum((x - mx) ** 2 for x in range(n))
37
+ return num / den if den else 0.0
38
+
39
+
40
+ def racha_bajo_media(serie: list[float], referencia: float) -> int:
41
+ """Jugadas consecutivas (contando desde la ΓΊltima) por debajo de la referencia.
42
+
43
+ La referencia es la media del PROPIO jugador, no un umbral externo fijo: el
44
+ modelo detecta cuando alguien empeora respecto a su propio nivel en esta
45
+ partida, sea cual sea ese nivel.
46
+ """
47
+ cont = 0
48
+ for v in reversed(serie):
49
+ if v < referencia:
50
+ cont += 1
51
+ else:
52
+ break
53
+ return cont
54
+
55
+
56
+ def cambio_regimen(serie: list[float], ventana: int = VENTANA) -> float:
57
+ """Diferencia entre el promedio de la ventana reciente y la inmediatamente previa.
58
+
59
+ << 0 β‡’ caΓ­da brusca (venΓ­a mejor y cayΓ³ de golpe). >> 0 β‡’ salto de mejora.
60
+ Es una detecciΓ³n de cambio de rΓ©gimen comparando dos ventanas contiguas; se
61
+ necesita historial suficiente (2Β·ventana), si no devuelve 0.0.
62
+ """
63
+ if len(serie) < ventana * 2:
64
+ return 0.0
65
+ reciente = serie[-ventana:]
66
+ previa = serie[-2 * ventana:-ventana]
67
+ return media(reciente) - media(previa)
68
+
69
+
70
+ def fase(numero_jugada: int) -> str:
71
+ """Fase de la partida derivada del nΓΊmero de jugada.
72
+
73
+ Se deriva del nΓΊmero porque en este punto del pipeline no tenemos el material
74
+ del tablero. HeurΓ­stica estΓ‘ndar: apertura ≀10, medio juego 11–30, final >30.
75
+ La fase MODULA la interpretaciΓ³n: el mismo error pesa mΓ‘s en un final.
76
+ """
77
+ if numero_jugada <= 10:
78
+ return "apertura"
79
+ if numero_jugada <= 30:
80
+ return "medio juego"
81
+ return "final"
modules/deterministic/model.py ADDED
@@ -0,0 +1,54 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Modelo DeterminΓ­stico de RetroalimentaciΓ³n EstratΓ©gica β€” Experimento A (TA-003).
2
+
3
+ Contraparte del LLM (Experimento B, en modules/llm). Expone la MISMA firma
4
+ `comentar(move, clasificacion, history)` para ser intercambiable con Qwen en
5
+ routes/comment.py y comparable en el experimento (DO-002).
6
+
7
+ Pipeline:
8
+ historial ─► serie del jugador ─► estado recursivo (Markov)
9
+ ─► patrΓ³n (reglas sobre features) ─► comentario (plantillas)
10
+
11
+ Es funciΓ³n PURA del historial: mismo input β‡’ mismo output, sin estado global ni
12
+ azar (RN-004).
13
+ """
14
+ from modules.analysis.classifier import classify
15
+ from . import estado as estado_mod
16
+ from . import reglas, plantillas, tablero
17
+
18
+
19
+ def _serie_del_jugador(move: dict, clasificacion: str, history: list) -> list[tuple]:
20
+ """Jugadas del MISMO color que la actual, en orden, incluyendo la actual.
21
+
22
+ La tendencia estratΓ©gica se mide sobre las jugadas del propio jugador, no
23
+ sobre los plies del rival intercalados.
24
+ """
25
+ color = move["color"]
26
+ jugadas = [
27
+ (h.get("diferencia_cp", 0), classify(h.get("diferencia_cp", 0)), h.get("number", 0))
28
+ for h in history if h.get("color") == color
29
+ ]
30
+ jugadas.append((move.get("diferencia_cp", 0), clasificacion, move.get("number", 0)))
31
+ return jugadas
32
+
33
+
34
+ def comentar(move: dict, clasificacion: str, history: list | None = None) -> dict:
35
+ """Genera {corto, expandido} para una jugada analizando la secuencia hasta ella.
36
+
37
+ Args:
38
+ move: dict de Stockfish (number, color, diferencia_cp, ...).
39
+ clasificacion: categorΓ­a de la jugada actual (classify del diferencia_cp).
40
+ history: jugadas ANTERIORES de la partida (ambos colores); se filtra el
41
+ color propio internamente.
42
+
43
+ Returns:
44
+ {"corto": str, "expandido": str | None}
45
+ """
46
+ history = history or []
47
+ jugadas = _serie_del_jugador(move, clasificacion, history)
48
+ estado = estado_mod.construir(jugadas)
49
+ # ReconstrucciΓ³n del tablero a partir de la secuencia SAN completa (ambos
50
+ # colores), para aportar el contexto posicional al patrΓ³n.
51
+ sans = [h.get("move") for h in history] + [move.get("move")]
52
+ feats = tablero.features_tablero(sans, move["color"], move.get("number", 0))
53
+ patron = reglas.detectar_patron(estado, clasificacion, feats)
54
+ return plantillas.generar(patron, estado)
modules/deterministic/plantillas.py ADDED
@@ -0,0 +1,117 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """GeneraciΓ³n de lenguaje natural por plantillas (Experimento A β€” TA-003).
2
+
3
+ Cada patrΓ³n detectado mapea a un par de comentarios deterministas en espaΓ±ol
4
+ (neutro, tuteo) con tono de entrenador y SIN recomendar jugadas (la mejor jugada
5
+ la muestra Stockfish por separado en la UI). Dos niveles:
6
+ - corto: 1–2 lΓ­neas, siempre visible junto al avatar.
7
+ - expandido: contexto de las jugadas previas que llevaron a este momento.
8
+
9
+ CategorΓ­a acadΓ©mica: NLG basada en plantillas (template-based generation).
10
+ """
11
+
12
+ _PLANTILLAS = {
13
+ "caida_brusca": {
14
+ "corto": "VenΓ­as llevando bien la partida y aquΓ­ rompes el ritmo; cuidado con regalar lo que construiste.",
15
+ "expandido": "Tus ΓΊltimas jugadas venΓ­an siendo sΓ³lidas, pero esta marca una caΓ­da brusca respecto a ese nivel. No es un problema de toda la partida sino un descuido puntual: frena, respira y retoma el plan que te venΓ­a funcionando.",
16
+ },
17
+ "deterioro_sostenido": {
18
+ "corto": "Llevas {racha} jugadas cediendo terreno de forma sostenida; esta agrava el patrΓ³n.",
19
+ "expandido": "No es un error aislado: tu evaluaciΓ³n viene bajando jugada tras jugada (ya acumulas {imprecisiones} imprecisiones y {errores} errores en la partida). La tendencia es de deterioro progresivo, asΓ­ que conviene cortar la inercia y reordenar la posiciΓ³n antes de que el desgaste se vuelva decisivo.",
20
+ },
21
+ "rey_sin_enrocar": {
22
+ "corto": "Tu rey lleva varias jugadas sin enrocar y quedΓ³ expuesto en el centro.",
23
+ "expandido": "Vienes demorando el enroque y tu rey sigue en el centro, donde es vulnerable. Antes de seguir con otros planes, ponlo a salvo: la seguridad del rey es una prioridad de la apertura, y este error lo confirma.",
24
+ },
25
+ "sin_desarrollo": {
26
+ "corto": "Tus piezas siguen dormidas; llevas jugadas sin sacarlas al juego.",
27
+ "expandido": "Las jugadas previas descuidaron el desarrollo: tus caballos y alfiles siguen en casa. Sin piezas activas cuesta crear amenazas o defenderte; prioriza sacar las menores en vez de mover lo mismo dos veces.",
28
+ },
29
+ "cede_centro": {
30
+ "corto": "Vienes cediendo el control del centro jugada tras jugada.",
31
+ "expandido": "A lo largo de las ΓΊltimas jugadas fuiste perdiendo presencia en el centro (d4/e4/d5/e5). Quien domina el centro dicta el juego; recupera esas casillas con peones o piezas antes de que tu rival se asiente ahΓ­.",
32
+ },
33
+ "avance_enroque": {
34
+ "corto": "EstΓ‘s empujando los peones que protegen a tu rey y debilitas su refugio.",
35
+ "expandido": "Adelantar los peones delante del rey enrocado abre lΓ­neas hacia tu propia posiciΓ³n. Salvo que sea un ataque muy concreto, conviene no tocar ese escudo de peones: cada avance deja huecos que el rival puede aprovechar.",
36
+ },
37
+ "dama_temprano": {
38
+ "corto": "Sacaste la dama demasiado pronto; el rival gana tiempo atacΓ‘ndola.",
39
+ "expandido": "Mover la dama temprano la expone: tu rival desarrolla sus piezas con tempo, atacΓ‘ndola y ganando ritmo. Mejor desarrolla primero caballos y alfiles, y reserva la dama para cuando la posiciΓ³n lo pida.",
40
+ },
41
+ "pieza_repetida": {
42
+ "corto": "Moviste la misma pieza otra vez en lugar de desarrollar nuevas.",
43
+ "expandido": "En la apertura cada tiempo cuenta. Volver a mover una pieza ya desarrollada, mientras otras siguen en casa, te hace perder ritmo de desarrollo. Saca una pieza nueva al juego en vez de reacomodar la misma.",
44
+ },
45
+ "caballo_borde": {
46
+ "corto": "Llevaste el caballo al borde, donde controla muy pocas casillas.",
47
+ "expandido": "Un caballo en la columna del borde (a/h) domina menos casillas que en el centro y suele quedar mal colocado. Salvo que vaya a una buena casilla concreta, conviene dirigir los caballos hacia el centro del tablero.",
48
+ },
49
+ "error_en_final": {
50
+ "corto": "En el final cada imprecisiΓ³n pesa el doble, y aquΓ­ estΓ‘s soltando ventaja.",
51
+ "expandido": "EstΓ‘s en la fase final, donde los mΓ‘rgenes de error son mΓ­nimos y cada concesiΓ³n cuesta caro. Una imprecisiΓ³n que en el medio juego serΓ­a recuperable, en el final puede definir el resultado: juega con mΓ‘s cuidado y calcula hasta el final.",
52
+ },
53
+ "hallazgo": {
54
+ "corto": "Gran recurso tΓ‘ctico: encontraste algo por encima de tu lΓ­nea habitual.",
55
+ "expandido": "Esta jugada destaca sobre el resto de tu partida: detectaste un recurso tΓ‘ctico que mejora claramente tu posiciΓ³n. Buen ojo; ese tipo de hallazgos son los que inclinan partidas parejas.",
56
+ },
57
+ "recuperacion": {
58
+ "corto": "Buena reacciΓ³n: estΓ‘s recuperando el control despuΓ©s de un tramo flojo.",
59
+ "expandido": "DespuΓ©s de unas jugadas por debajo de tu nivel, retomas el rumbo y tu evaluaciΓ³n vuelve a mejorar. MantΓ©n esta concentraciΓ³n: salir de un mal tramo sin hundirte es una seΓ±al de solidez.",
60
+ },
61
+ "solidez": {
62
+ "corto": "Jugada sΓ³lida, mantienes el plan sin sobresaltos.",
63
+ "expandido": "Vienes sosteniendo un nivel parejo, sin concesiones importantes. No hay mucho que corregir aquΓ­: sigue con la misma claridad de plan y sin apurarte.",
64
+ },
65
+ # Fallback por tipo de jugada (cuando no hay un patrΓ³n fuerte): evita el
66
+ # comentario genΓ©rico idΓ©ntico mencionando quΓ© clase de jugada fue.
67
+ "leve_captura": {
68
+ "corto": "Esta captura no termina de favorecerte; cambiaste sin mejorar tu posiciΓ³n.",
69
+ "expandido": "Cambiar piezas no es malo en sΓ­, pero aquΓ­ la captura entrega algo de ventaja sin una compensaciΓ³n clara. Antes de cambiar, fΓ­jate si el cambio te conviene o si ayuda mΓ‘s al rival.",
70
+ },
71
+ "leve_peon": {
72
+ "corto": "Este avance de peΓ³n no aporta mucho y cede algo de precisiΓ³n.",
73
+ "expandido": "Los avances de peΓ³n son permanentes: no se vuelven atrΓ‘s y dejan casillas dΓ©biles. Este no mejora tu posiciΓ³n; en general conviene priorizar desarrollo y seguridad antes de mover peones sin un plan concreto.",
74
+ },
75
+ "leve_pieza": {
76
+ "corto": "Mueves la pieza, pero la jugada cede algo de precisiΓ³n; quizΓ‘ habΓ­a algo mejor.",
77
+ "expandido": "La jugada no es grave, pero tu pieza queda algo menos activa de lo posible. Busca casillas donde tus piezas presionen el centro o las debilidades del rival, no solo una casilla cΓ³moda.",
78
+ },
79
+ "leve_enroque": {
80
+ "corto": "El enroque no era el momento mΓ‘s preciso, aunque la posiciΓ³n sigue jugable.",
81
+ "expandido": "Enrocar casi siempre es bueno, pero el timing importa: aquΓ­ habΓ­a algo un poco mΓ‘s exacto primero. De todos modos poner el rey a salvo rara vez es un error serio.",
82
+ },
83
+ "leve_otro": {
84
+ "corto": "Esta jugada cede algo de precisiΓ³n, pero la partida sigue equilibrada.",
85
+ "expandido": "Es una pequeΓ±a concesiΓ³n dentro de una partida que venΓ­as manejando bien. No es para alarmarse: registra el detalle y vuelve a tu plan en la prΓ³xima jugada.",
86
+ },
87
+ "desviacion_leve": {
88
+ "corto": "Esta jugada cede algo de precisiΓ³n, pero la partida sigue equilibrada.",
89
+ "expandido": "Es una pequeΓ±a concesiΓ³n dentro de una partida que venΓ­as manejando bien. No es para alarmarse: registra el detalle y vuelve a tu plan en la prΓ³xima jugada.",
90
+ },
91
+ "neutro": {
92
+ "corto": "Mantienes el equilibrio de la posiciΓ³n.",
93
+ "expandido": "La partida sigue su curso sin cambios estratΓ©gicos relevantes en este momento. Sigue atento a la evoluciΓ³n de la posiciΓ³n.",
94
+ },
95
+ }
96
+
97
+ _FALLBACK = {"corto": "Jugada registrada.", "expandido": None}
98
+
99
+
100
+ def generar(patron: str, estado) -> dict:
101
+ """Rellena la plantilla del patrΓ³n con los valores del estado acumulado.
102
+
103
+ Devuelve {corto, expandido}. La interpolaciΓ³n usa solo enteros del estado
104
+ (racha, errores…), asΓ­ que el texto es totalmente determinista.
105
+ """
106
+ plantilla = _PLANTILLAS.get(patron, _FALLBACK)
107
+ ctx = {
108
+ "racha": estado.racha,
109
+ "errores": estado.errores,
110
+ "imprecisiones": estado.imprecisiones,
111
+ "fase": estado.fase,
112
+ }
113
+ expandido = plantilla["expandido"]
114
+ return {
115
+ "corto": plantilla["corto"].format(**ctx),
116
+ "expandido": expandido.format(**ctx) if expandido else None,
117
+ }
modules/deterministic/reglas.py ADDED
@@ -0,0 +1,101 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Motor de inferencia: del estado/features al patrΓ³n estratΓ©gico dominante.
2
+
3
+ REGLA DE ORO del experimento: las condiciones operan sobre FEATURES derivados de
4
+ la secuencia (pendiente, racha, cambio de rΓ©gimen, fase), NUNCA sobre el valor
5
+ puntual de `diferencia_cp`. Por eso el comentario emerge del anΓ‘lisis de la
6
+ trayectoria y no es una traducción directa cp→texto.
7
+
8
+ CategorΓ­a acadΓ©mica: sistema basado en reglas (inferencia simbΓ³lica).
9
+ """
10
+ from .estado import EstadoEstrategico
11
+
12
+ # Umbrales sobre FEATURES (no sobre cp crudo de la jugada actual).
13
+ UMBRAL_PENDIENTE = -8.0 # cp/jugada: pendiente que indica caΓ­da sostenida
14
+ UMBRAL_RACHA = 2 # jugadas seguidas por debajo de la media propia
15
+ UMBRAL_CAMBIO = 35.0 # cp: salto entre ventanas que indica cambio de rΓ©gimen
16
+
17
+ _MALAS = {"ImprecisiΓ³n", "Error"}
18
+
19
+
20
+ def _patron_posicional(t: dict) -> str | None:
21
+ """PatrΓ³n ajedrecΓ­stico a partir de los features del tablero (python-chess).
22
+
23
+ Explica el PORQUÉ posicional de un error mirando lo que vienen mostrando las
24
+ jugadas previas. Reglas de mΓ‘s a menos especΓ­ficas; la primera que matchea
25
+ gana. Devuelve None si no hay un problema posicional claro.
26
+ """
27
+ if t.get("avance_enroque"):
28
+ return "avance_enroque"
29
+ if not t["enrocado"] and t["rey_centro"] and t["numero"] >= 8:
30
+ return "rey_sin_enrocar"
31
+ if t["desarrollo"] <= 1 and t["numero"] >= 6:
32
+ return "sin_desarrollo"
33
+ if t.get("pieza_repetida") and t["numero"] <= 12:
34
+ return "pieza_repetida"
35
+ if t.get("dama_fuera") and t["numero"] <= 7:
36
+ return "dama_temprano"
37
+ if t.get("caballo_borde"):
38
+ return "caballo_borde"
39
+ if t["control_centro"] <= 1 and t["numero"] >= 5:
40
+ return "cede_centro"
41
+ return None
42
+
43
+
44
+ def _fallback_por_jugada(t: dict | None) -> str:
45
+ """Fallback cuando no hay patrΓ³n claro: varΓ­a segΓΊn el tipo de jugada (SAN).
46
+
47
+ Evita el comentario genΓ©rico idΓ©ntico: aunque no se detecte un patrΓ³n fuerte,
48
+ el texto menciona quΓ© clase de jugada fue (captura, peΓ³n, pieza...).
49
+ """
50
+ if not t:
51
+ return "desviacion_leve"
52
+ return "leve_" + t.get("tipo_jugada", "otro")
53
+
54
+
55
+ def detectar_patron(estado: EstadoEstrategico, clasificacion: str,
56
+ tablero: dict | None = None) -> str:
57
+ """Devuelve la clave del patrΓ³n dominante.
58
+
59
+ Las reglas estΓ‘n ordenadas de mΓ‘s a menos especΓ­ficas: la primera que se
60
+ cumple gana. AsΓ­ un mismo conjunto de features produce siempre el mismo
61
+ patrΓ³n (determinismo). `tablero` aporta el contexto posicional (python-chess);
62
+ si es None, se decide solo con los features de cp.
63
+ """
64
+ mala = clasificacion in _MALAS
65
+
66
+ # 1. CaΓ­da brusca: el rΓ©gimen reciente cae con fuerza (suele ser un error
67
+ # tΓ‘ctico puntual; narrativa fuerte y especΓ­fica).
68
+ if mala and estado.cambio <= -UMBRAL_CAMBIO:
69
+ return "caida_brusca"
70
+
71
+ # 2. ExplicaciΓ³n posicional del error (apertura/medio juego, con tablero).
72
+ # Tiene prioridad sobre la tendencia de cp porque dice el PORQUÉ ajedrecístico
73
+ # (rey expuesto, sin desarrollo, centro cedido), no solo que "viene cayendo".
74
+ if mala and tablero and estado.fase != "final":
75
+ posicional = _patron_posicional(tablero)
76
+ if posicional:
77
+ return posicional
78
+
79
+ # 3. Deterioro sostenido: racha bajo la media propia + pendiente negativa.
80
+ if mala and estado.racha >= UMBRAL_RACHA and estado.pendiente <= UMBRAL_PENDIENTE:
81
+ return "deterioro_sostenido"
82
+
83
+ # 4. Error en el final: la fase amplifica el costo del descuido.
84
+ if mala and estado.fase == "final":
85
+ return "error_en_final"
86
+
87
+ # 5. Hallazgo tΓ‘ctico.
88
+ if clasificacion == "Brillante":
89
+ return "hallazgo"
90
+
91
+ # 6. RecuperaciΓ³n: salto de mejora de rΓ©gimen tras un tramo flojo.
92
+ if not mala and estado.cambio >= UMBRAL_CAMBIO:
93
+ return "recuperacion"
94
+
95
+ # 7. Solidez: sin racha sostenida bajo la media propia, juego parejo.
96
+ if not mala and estado.racha < UMBRAL_RACHA:
97
+ return "solidez"
98
+
99
+ # 8. Sin patrΓ³n fuerte: fallback que varΓ­a segΓΊn el tipo de jugada (mala) /
100
+ # neutro (buena sin patrΓ³n marcado).
101
+ return _fallback_por_jugada(tablero) if mala else "neutro"
modules/deterministic/tablero.py ADDED
@@ -0,0 +1,163 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Capa de anΓ‘lisis del TABLERO para el modelo determinΓ­stico (TA-003).
2
+
3
+ Reconstruye las posiciones de la partida con python-chess a partir de la
4
+ secuencia de jugadas (SAN) y extrae features ajedrecΓ­sticos: desarrollo,
5
+ seguridad del rey y control del centro. Esto le da al modelo conocimiento de la
6
+ POSICIΓ“N β€”no solo de la evaluaciΓ³n numΓ©rica de Stockfishβ€”, para que la
7
+ retroalimentaciΓ³n explique el porquΓ© posicional de la secuencia.
8
+
9
+ Importante: python-chess solo LEE el tablero (no evalΓΊa); la evaluaciΓ³n es de
10
+ Stockfish. Todo es determinista: misma secuencia de jugadas β†’ mismos features.
11
+
12
+ CategorΓ­a acadΓ©mica: extracciΓ³n de features de dominio (conocimiento ajedrecΓ­stico).
13
+ """
14
+ from __future__ import annotations
15
+ import chess
16
+
17
+ # Casillas iniciales de las piezas menores (caballos y alfiles) por color.
18
+ _HOME_MINOR = {
19
+ chess.WHITE: {chess.B1, chess.G1, chess.C1, chess.F1},
20
+ chess.BLACK: {chess.B8, chess.G8, chess.C8, chess.F8},
21
+ }
22
+ _CENTRO = (chess.D4, chess.E4, chess.D5, chess.E5)
23
+
24
+
25
+ def _reconstruir(sans: list[str]) -> chess.Board | None:
26
+ """Replaya la secuencia SAN desde la posiciΓ³n inicial; None si algo es ilegal."""
27
+ board = chess.Board()
28
+ for san in sans:
29
+ if not san:
30
+ return None
31
+ try:
32
+ board.push_san(san)
33
+ except (ValueError, AssertionError):
34
+ return None
35
+ return board
36
+
37
+
38
+ def _desarrollo(board: chess.Board, color: bool) -> int:
39
+ """Cantidad de piezas menores propias (caballos/alfiles) fuera de su casa."""
40
+ home = _HOME_MINOR[color]
41
+ n = 0
42
+ for tipo in (chess.KNIGHT, chess.BISHOP):
43
+ for sq in board.pieces(tipo, color):
44
+ if sq not in home:
45
+ n += 1
46
+ return n
47
+
48
+
49
+ def _rey_en_centro(board: chess.Board, color: bool) -> bool:
50
+ """True si el rey propio sigue en las columnas centrales (d/e)."""
51
+ rey = board.king(color)
52
+ if rey is None:
53
+ return False
54
+ return chess.square_file(rey) in (3, 4) # columna d=3, e=4
55
+
56
+
57
+ def _control_centro(board: chess.Board, color: bool) -> int:
58
+ """Casillas centrales (d4/e4/d5/e5) ocupadas o atacadas por el color."""
59
+ score = 0
60
+ for sq in _CENTRO:
61
+ pieza = board.piece_at(sq)
62
+ if pieza and pieza.color == color:
63
+ score += 1
64
+ if board.is_attacked_by(color, sq):
65
+ score += 1
66
+ return score
67
+
68
+
69
+ def _destino_file(san: str) -> int | None:
70
+ """Columna (0-7) de la casilla de destino de una jugada SAN, o None."""
71
+ s = san.split("=")[0].rstrip("+#")
72
+ if len(s) >= 2 and s[-2] in "abcdefgh" and s[-1] in "12345678":
73
+ return ord(s[-2]) - ord("a")
74
+ return None
75
+
76
+
77
+ def _dama_fuera(board: chess.Board, color: bool) -> bool:
78
+ """True si la dama propia ya saliΓ³ de su casilla inicial (d1/d8)."""
79
+ home = chess.D1 if color == chess.WHITE else chess.D8
80
+ return any(sq != home for sq in board.pieces(chess.QUEEN, color))
81
+
82
+
83
+ def _caballo_en_borde(san: str) -> bool:
84
+ """True si la jugada actual lleva un caballo a la columna del borde (a/h)."""
85
+ if not san.startswith("N"):
86
+ return False
87
+ df = _destino_file(san)
88
+ return df in (0, 7)
89
+
90
+
91
+ def _avance_peon_rey(board: chess.Board, color: bool, san: str) -> bool:
92
+ """True si la jugada empuja un peΓ³n delante del propio rey ya enrocado.
93
+
94
+ Debilita el refugio del rey. Solo aplica si el rey ya saliΓ³ del centro
95
+ (enrocΓ³); empujar peones centrales en la apertura es normal y no se marca.
96
+ """
97
+ if not san or san[0] not in "abcdefgh": # las jugadas de peΓ³n empiezan con columna
98
+ return False
99
+ df = _destino_file(san)
100
+ rey = board.king(color)
101
+ if df is None or rey is None:
102
+ return False
103
+ kf = chess.square_file(rey)
104
+ fuera_del_centro = kf not in (3, 4) # rey ya enrocado a un flanco
105
+ return fuera_del_centro and abs(df - kf) <= 1
106
+
107
+
108
+ def _pieza_repetida(board: chess.Board, color: bool) -> bool:
109
+ """True si la jugada actual vuelve a mover una pieza (no peΓ³n) ya movida antes.
110
+
111
+ Detecta pΓ©rdida de tiempo: re-mover una pieza en vez de desarrollar nuevas.
112
+ """
113
+ if not board.move_stack:
114
+ return False
115
+ actual = board.move_stack[-1]
116
+ pieza = board.piece_at(actual.to_square)
117
+ if pieza is None or pieza.piece_type == chess.PAWN:
118
+ return False
119
+ inicio = 0 if color == chess.WHITE else 1
120
+ previos = board.move_stack[inicio:-1:2] # jugadas anteriores del mismo color
121
+ return any(m.to_square == actual.from_square for m in previos)
122
+
123
+
124
+ def _tipo_jugada(san: str) -> str:
125
+ """Clasifica la jugada por su forma SAN (para el comentario de fallback)."""
126
+ if not san:
127
+ return "otro"
128
+ if san.startswith("O-O"):
129
+ return "enroque"
130
+ if "x" in san:
131
+ return "captura"
132
+ if san[0] in "NBRQK":
133
+ return "pieza"
134
+ if san[0] in "abcdefgh":
135
+ return "peon"
136
+ return "otro"
137
+
138
+
139
+ def features_tablero(sans: list[str], color_str: str, numero: int) -> dict | None:
140
+ """Features posicionales del jugador `color_str` tras su ΓΊltima jugada.
141
+
142
+ `sans`: secuencia COMPLETA de jugadas (ambos colores) en orden, incluyendo la
143
+ actual como ΓΊltima. Devuelve None si la secuencia no se puede reconstruir
144
+ (SAN invΓ‘lido), para que el modelo caiga limpiamente a los patrones de cp.
145
+ """
146
+ board = _reconstruir(sans)
147
+ if board is None:
148
+ return None
149
+ color = chess.WHITE if color_str == "white" else chess.BLACK
150
+ sans_jugador = sans[0::2] if color == chess.WHITE else sans[1::2]
151
+ san_actual = sans[-1] if sans else ""
152
+ return {
153
+ "desarrollo": _desarrollo(board, color),
154
+ "enrocado": any(s.startswith("O-O") for s in sans_jugador),
155
+ "rey_centro": _rey_en_centro(board, color),
156
+ "control_centro": _control_centro(board, color),
157
+ "dama_fuera": _dama_fuera(board, color),
158
+ "caballo_borde": _caballo_en_borde(san_actual),
159
+ "avance_enroque": _avance_peon_rey(board, color, san_actual),
160
+ "pieza_repetida": _pieza_repetida(board, color),
161
+ "tipo_jugada": _tipo_jugada(san_actual),
162
+ "numero": numero,
163
+ }
modules/llm/prompt_builder.py CHANGED
@@ -1,20 +1,45 @@
 
 
 
 
 
1
  SYSTEM = (
2
- "Eres un entrenador de ajedrez personal que habla en primera persona. "
3
- "Escribe DOS oraciones cortas en espaΓ±ol: "
4
- "primero explica quΓ© pasΓ³ con la jugada, "
5
- "luego di 'Yo te recomendarΓ­a {mejor jugada} porque...' con una razΓ³n breve y concreta. "
6
- "MΓ‘ximo 30 palabras en total. Sin mencionar Stockfish. Solo ajedrez."
 
 
7
  )
8
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9
 
10
- def build(move: dict, clasificacion: str) -> str:
11
  color_str = "Blancas" if move["color"] == "white" else "Negras"
12
- antes = move["eval_antes_cp"] / 100
13
- despues = move["eval_despues_cp"] / 100
14
- mejor = move.get("mejor_jugada") or "no disponible"
15
  return (
16
- f"Jugada {move['number']} ({color_str}): {move['move']}. "
17
- f"ClasificaciΓ³n: {clasificacion}. "
18
- f"EvaluaciΓ³n antes: {antes:+.1f}, despuΓ©s: {despues:+.1f}. "
19
- f"Mejor jugada: {mejor}."
20
  )
 
1
+ from modules.analysis.classifier import classify
2
+
3
+ # El entrenador SOLO comenta el patrΓ³n estratΓ©gico. La mejor jugada y la
4
+ # evaluaciΓ³n numΓ©rica las muestra Stockfish por separado en la UI, asΓ­ que el
5
+ # modelo NO debe mencionarlas (de hecho no se las pasamos en el prompt).
6
  SYSTEM = (
7
+ "Eres un entrenador de ajedrez. Comenta la jugada en UNA sola oraciΓ³n "
8
+ "corta y directa en espaΓ±ol, explicando la idea o el patrΓ³n estratΓ©gico "
9
+ "(por ejemplo: control del centro, seguridad del rey, piezas pasivas, "
10
+ "iniciativa). "
11
+ "Reglas estrictas: NO menciones nΓΊmeros ni evaluaciones; NO recomiendes "
12
+ "ninguna jugada alternativa; NO uses muletillas como 'teniendo en cuenta "
13
+ "las jugadas anteriores'. Ve directo al punto."
14
  )
15
 
16
+ # Clasificaciones que cuentan como "mala jugada" para detectar tendencia.
17
+ _MALAS = {"ImprecisiΓ³n", "Error"}
18
+ _BUENAS = {"Brillante", "Excelente", "Buena"}
19
+
20
+
21
+ def _tendencia(history: list, max_n: int = 4) -> str:
22
+ """Resume la tendencia reciente en lenguaje natural (sin tokens de jugadas).
23
+
24
+ En vez de pasar el historial crudo (que el modelo copiaba textual), le
25
+ damos una seΓ±al de alto nivel: si viene fallando o jugando bien. AsΓ­ el
26
+ comentario considera la tendencia sin filtrar nombres de jugadas.
27
+ """
28
+ recientes = [classify(h.get("diferencia_cp", 0)) for h in history[-max_n:]]
29
+ if not recientes:
30
+ return "Tendencia: es de las primeras jugadas, aΓΊn no hay patrΓ³n."
31
+ malas = sum(1 for c in recientes if c in _MALAS)
32
+ if malas >= 2:
33
+ return "Tendencia: el jugador viene cometiendo varias imprecisiones seguidas."
34
+ if malas == 0 and all(c in _BUENAS for c in recientes):
35
+ return "Tendencia: el jugador venΓ­a jugando con precisiΓ³n."
36
+ return "Tendencia: el juego venΓ­a equilibrado, sin un patrΓ³n marcado."
37
+
38
 
39
+ def build(move: dict, clasificacion: str, history: list | None = None) -> str:
40
  color_str = "Blancas" if move["color"] == "white" else "Negras"
 
 
 
41
  return (
42
+ f"{_tendencia(history or [])}\n"
43
+ f"Jugada actual ({color_str}): {move['move']}, clasificada como {clasificacion}. "
44
+ f"Explica en una oraciΓ³n el mΓ©rito o el problema estratΓ©gico de esta jugada."
 
45
  )
routes/comment.py CHANGED
@@ -1,57 +1,98 @@
1
  """Endpoint /api/comment β€” genera clasificaciΓ³n y comentario por jugada.
2
 
3
- Estrategia tipo chess.com:
4
- - Excelente / Buena β†’ comentario BREVE determinista (no se llama al LLM).
5
- - Brillante / ImprecisiΓ³n / Error β†’ comentario DETALLADO con LLM
6
- (con fallback determinista si el LLM falla validaciΓ³n).
 
 
 
 
7
  """
8
  from flask import Blueprint, request, jsonify
9
  from modules.analysis.classifier import classify
 
10
  from modules.llm.prompt_builder import build
11
  from modules.llm.qwen import generate
12
  from modules.llm.guardrails import validate, brief
 
13
 
14
  comment_bp = Blueprint('comment', __name__)
15
 
16
- # Solo estas clasificaciones disparan el LLM.
17
- NEEDS_LLM = {"Brillante", "ImprecisiΓ³n", "Error"}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
18
 
19
 
20
  @comment_bp.route('/comment', methods=['POST'])
21
  def comment():
22
  """
23
  Body JSON:
24
- { "moves": [...] } β€” array de moves devuelto por /api/analyze
 
 
25
 
26
  Respuesta:
27
- { "comments": [{ "number", "color", "clasificacion", "comentario" }, ...] }
 
28
  """
29
- data = request.get_json(silent=True) or {}
30
- moves = data.get('moves')
 
31
  if not moves or not isinstance(moves, list):
32
  return jsonify({'error': "Se esperaba {'moves': [...]}"}), 400
33
 
34
- n_llm = sum(1 for m in moves if classify(m.get('diferencia_cp', 0)) in NEEDS_LLM)
35
- print(f"[comment] {len(moves)} jugadas, {n_llm} requieren LLM", flush=True)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
36
 
37
  comments = []
38
- for move in moves:
39
  clasificacion = classify(move.get('diferencia_cp', 0))
40
-
41
- if clasificacion in NEEDS_LLM:
42
- try:
43
- text = generate(build(move, clasificacion))
44
- text = validate(text, move, clasificacion)
45
- except Exception:
46
- text = validate("", move, clasificacion)
47
- else:
48
- text = brief(move, clasificacion)
49
-
50
- comments.append({
51
- 'number': move.get('number'),
52
- 'color': move.get('color'),
53
- 'clasificacion': clasificacion,
54
- 'comentario': text,
55
- })
56
 
57
  return jsonify({'comments': comments})
 
1
  """Endpoint /api/comment β€” genera clasificaciΓ³n y comentario por jugada.
2
 
3
+ Dos modelos INTERCAMBIABLES generan el comentario de las jugadas interesantes
4
+ (Brillante/ImprecisiΓ³n/Error), segΓΊn config.COACH_MODEL:
5
+ - "deterministic" β†’ Experimento A: modelo determinΓ­stico propio (modules.deterministic)
6
+ - "qwen" β†’ Experimento B: LLM Qwen2.5 (modules.llm)
7
+ Las jugadas rutinarias (Excelente/Buena) usan plantilla breve determinista.
8
+
9
+ Ambos modelos consideran el HISTORIAL reciente (no la jugada en aislado) y
10
+ devuelven {corto, expandido} para que la salida sea homogΓ©nea y comparable.
11
  """
12
  from flask import Blueprint, request, jsonify
13
  from modules.analysis.classifier import classify
14
+ from modules.deterministic import comentar as comentar_deterministico
15
  from modules.llm.prompt_builder import build
16
  from modules.llm.qwen import generate
17
  from modules.llm.guardrails import validate, brief
18
+ from config import COACH_MODEL
19
 
20
  comment_bp = Blueprint('comment', __name__)
21
 
22
+ # Solo estas clasificaciones disparan un modelo de comentarios.
23
+ NEEDS_MODEL = {"Brillante", "ImprecisiΓ³n", "Error"}
24
+
25
+
26
+ def _comentar_qwen(move: dict, clasificacion: str, history: list) -> dict:
27
+ """Experimento B: envuelve el LLM Qwen en el contrato {corto, expandido}."""
28
+ try:
29
+ text = generate(build(move, clasificacion, history))
30
+ text = validate(text, move, clasificacion)
31
+ except Exception:
32
+ text = validate("", move, clasificacion)
33
+ return {"corto": text, "expandido": None}
34
+
35
+
36
+ def _comentar(move: dict, clasificacion: str, history: list) -> dict:
37
+ """Genera {corto, expandido} para UNA jugada segΓΊn el modelo configurado."""
38
+ if clasificacion in NEEDS_MODEL:
39
+ if COACH_MODEL == "qwen":
40
+ return _comentar_qwen(move, clasificacion, history)
41
+ return comentar_deterministico(move, clasificacion, history)
42
+ return {"corto": brief(move, clasificacion), "expandido": None}
43
+
44
+
45
+ def _payload(move: dict, clasificacion: str, res: dict) -> dict:
46
+ """Arma el objeto de respuesta de una jugada."""
47
+ return {
48
+ 'number': move.get('number'),
49
+ 'color': move.get('color'),
50
+ 'clasificacion': clasificacion,
51
+ 'comentario': res['corto'],
52
+ 'comentario_expandido': res['expandido'],
53
+ }
54
 
55
 
56
  @comment_bp.route('/comment', methods=['POST'])
57
  def comment():
58
  """
59
  Body JSON:
60
+ { "moves": [...] } β†’ comenta TODAS las jugadas (batch).
61
+ { "moves": [...], "target": N } β†’ comenta SOLO la jugada N (1-based),
62
+ usando las anteriores como historial.
63
 
64
  Respuesta:
65
+ { "comments": [{ number, color, clasificacion, comentario,
66
+ comentario_expandido }, ...] }
67
  """
68
+ data = request.get_json(silent=True) or {}
69
+ moves = data.get('moves')
70
+ target = data.get('target')
71
  if not moves or not isinstance(moves, list):
72
  return jsonify({'error': "Se esperaba {'moves': [...]}"}), 400
73
 
74
+ # ── Modo target: una sola jugada con su historial ───────────────────────
75
+ if target is not None:
76
+ try:
77
+ idx = int(target)
78
+ except (TypeError, ValueError):
79
+ return jsonify({'error': 'target debe ser entero'}), 400
80
+ if not (1 <= idx <= len(moves)):
81
+ return jsonify({'error': 'target fuera de rango'}), 400
82
+ move = moves[idx - 1]
83
+ history = moves[:idx - 1]
84
+ clasificacion = classify(move.get('diferencia_cp', 0))
85
+ res = _comentar(move, clasificacion, history)
86
+ return jsonify({'comments': [_payload(move, clasificacion, res)]})
87
+
88
+ # ── Modo batch: todas las jugadas, cada una con su historial ────────────
89
+ n_modelo = sum(1 for m in moves if classify(m.get('diferencia_cp', 0)) in NEEDS_MODEL)
90
+ print(f"[comment] {len(moves)} jugadas, {n_modelo} usan modelo '{COACH_MODEL}'", flush=True)
91
 
92
  comments = []
93
+ for i, move in enumerate(moves):
94
  clasificacion = classify(move.get('diferencia_cp', 0))
95
+ res = _comentar(move, clasificacion, moves[:i])
96
+ comments.append(_payload(move, clasificacion, res))
 
 
 
 
 
 
 
 
 
 
 
 
 
 
97
 
98
  return jsonify({'comments': comments})
tests/test_deterministic.py ADDED
@@ -0,0 +1,191 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Tests del modelo determinΓ­stico (TA-003).
2
+
3
+ Demuestran el requisito cientΓ­fico RN-004: mismo input β†’ mismo output, y que
4
+ cada patrΓ³n estratΓ©gico se dispara con la secuencia esperada.
5
+
6
+ Corre con pytest (`pytest backend/tests/`) o directo (`python test_deterministic.py`).
7
+ """
8
+ import copy
9
+ import os
10
+ import sys
11
+
12
+ # Permite importar `modules.*` corriendo desde cualquier carpeta.
13
+ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
14
+
15
+ from modules.deterministic import comentar
16
+ from modules.deterministic.estado import construir
17
+ from modules.deterministic.reglas import detectar_patron
18
+ from modules.deterministic import tablero
19
+ from modules.analysis.classifier import classify
20
+
21
+
22
+ def _move(color: str, number: int, dif: int) -> dict:
23
+ """Construye un dict de jugada con la forma que devuelve Stockfish."""
24
+ return {
25
+ "color": color, "number": number, "diferencia_cp": dif,
26
+ "move": "Xx", "eval_antes_cp": 0, "eval_despues_cp": 0,
27
+ "mejor_jugada": "Yy", "mejor_eval_cp": 0,
28
+ }
29
+
30
+
31
+ def _jugadas(difs, numero_base=1):
32
+ """Lista de (dif, clasificacion, numero) a partir de una lista de diferencia_cp."""
33
+ return [(d, classify(d), numero_base + i) for i, d in enumerate(difs)]
34
+
35
+
36
+ # ─── Replicabilidad (RN-004) ─────────────────────────────────────────────────
37
+
38
+ def test_replicabilidad_mismo_input_mismo_output():
39
+ history = [_move("white", i + 1, d) for i, d in enumerate([-5, -20, -40, -60])]
40
+ move = _move("white", 5, -90)
41
+ salidas = [comentar(move, "Error", history) for _ in range(100)]
42
+ assert all(s == salidas[0] for s in salidas), "El modelo NO es determinΓ­stico"
43
+
44
+
45
+ def test_no_muta_la_entrada():
46
+ history = [_move("white", 1, -10)]
47
+ move = _move("white", 2, -90)
48
+ h_copia, m_copia = copy.deepcopy(history), copy.deepcopy(move)
49
+ comentar(move, "Error", history)
50
+ assert history == h_copia and move == m_copia, "comentar() mutΓ³ sus argumentos"
51
+
52
+
53
+ # ─── Estructura de salida ────────────────────────────────────────────────────
54
+
55
+ def test_estructura_salida():
56
+ out = comentar(_move("black", 3, -90), "Error", [])
57
+ assert set(out) == {"corto", "expandido"}
58
+ assert isinstance(out["corto"], str) and len(out["corto"]) > 0
59
+
60
+
61
+ # ─── DetecciΓ³n de patrones (sobre features, no sobre cp puntual) ─────────────
62
+
63
+ def test_deterioro_sostenido():
64
+ # Serie que empeora progresivamente: pendiente negativa + racha bajo la media.
65
+ estado = construir(_jugadas([-5, -20, -50, -80]))
66
+ assert detectar_patron(estado, "Error") == "deterioro_sostenido"
67
+
68
+
69
+ def test_caida_brusca():
70
+ # 4 jugadas buenas y luego 4 malas β†’ cambio de rΓ©gimen fuerte.
71
+ estado = construir(_jugadas([-5, -3, -8, -2, -50, -60, -70, -90]))
72
+ assert detectar_patron(estado, "Error") == "caida_brusca"
73
+
74
+
75
+ def test_error_en_final():
76
+ # Jugada mala aislada pero en fase final (nΓΊmero > 30).
77
+ estado = construir([(-50, "ImprecisiΓ³n", 35)])
78
+ assert detectar_patron(estado, "ImprecisiΓ³n") == "error_en_final"
79
+
80
+
81
+ def test_hallazgo():
82
+ estado = construir([(200, "Brillante", 10)])
83
+ assert detectar_patron(estado, "Brillante") == "hallazgo"
84
+
85
+
86
+ def test_solidez():
87
+ estado = construir(_jugadas([-2, -3, -1, -4]))
88
+ assert detectar_patron(estado, "Buena") == "solidez"
89
+
90
+
91
+ def test_misma_jugada_distinto_historial_distinto_comentario():
92
+ """El nΓΊcleo del aporte: mismo cp actual, comentario distinto segΓΊn la secuencia."""
93
+ move = _move("white", 9, -80)
94
+ hist_deterioro = [_move("white", i + 1, d) for i, d in enumerate([-5, -20, -50])]
95
+ hist_estable = [_move("white", i + 1, d) for i, d in enumerate([-2, -3, -1])]
96
+ c1 = comentar(move, "Error", hist_deterioro)
97
+ c2 = comentar(move, "Error", hist_estable)
98
+ assert c1["corto"] != c2["corto"], "El historial no influye en el comentario"
99
+
100
+
101
+ # ─── Capa de tablero (python-chess) ──────────────────────────────────────────
102
+
103
+ def test_tablero_estructura():
104
+ sans = ["e4", "c5", "Nf3", "d6", "d4", "cxd4", "Nxd4", "Nf6"]
105
+ f = tablero.features_tablero(sans, "white", 4)
106
+ assert f is not None
107
+ assert {"desarrollo", "enrocado", "rey_centro", "control_centro", "numero"} <= set(f)
108
+ assert isinstance(f["desarrollo"], int)
109
+
110
+
111
+ def test_tablero_san_invalido_devuelve_none():
112
+ assert tablero.features_tablero(["e4", "zz99"], "black", 1) is None
113
+
114
+
115
+ def test_tablero_enroque_detectado():
116
+ sans = ["e4", "e5", "Nf3", "Nc6", "Bc4", "Bc5", "O-O"] # enrocan las blancas
117
+ f = tablero.features_tablero(sans, "white", 4)
118
+ assert f["enrocado"] is True
119
+ assert f["rey_centro"] is False
120
+
121
+
122
+ def test_tablero_rey_en_centro():
123
+ sans = ["e4", "e5", "Bc4", "Bc5", "Qe2", "Qe7"] # nadie enroca
124
+ f = tablero.features_tablero(sans, "white", 3)
125
+ assert f["enrocado"] is False
126
+ assert f["rey_centro"] is True
127
+
128
+
129
+ def test_patron_posicional_rey_sin_enrocar():
130
+ estado = construir([(-50, "ImprecisiΓ³n", 8)])
131
+ feats = {"desarrollo": 3, "enrocado": False, "rey_centro": True,
132
+ "control_centro": 2, "numero": 8}
133
+ assert detectar_patron(estado, "ImprecisiΓ³n", feats) == "rey_sin_enrocar"
134
+
135
+
136
+ def test_patron_posicional_sin_desarrollo():
137
+ estado = construir([(-50, "Error", 7)])
138
+ feats = {"desarrollo": 0, "enrocado": True, "rey_centro": False,
139
+ "control_centro": 3, "numero": 7}
140
+ assert detectar_patron(estado, "Error", feats) == "sin_desarrollo"
141
+
142
+
143
+ def test_patron_avance_enroque():
144
+ # Negro enroca corto y luego empuja g5 delante de su propio rey.
145
+ sans = ["e4", "e5", "Nf3", "Nc6", "Bc4", "Bc5", "d3", "Nf6", "Nc3", "O-O", "h3", "h6", "a3", "g5"]
146
+ f = tablero.features_tablero(sans, "black", 7)
147
+ assert f is not None
148
+ assert f["avance_enroque"] is True
149
+
150
+
151
+ def test_patron_caballo_borde():
152
+ f = tablero.features_tablero(["e4", "Nh6"], "black", 1)
153
+ assert f["caballo_borde"] is True
154
+
155
+
156
+ def test_patron_dama_temprano():
157
+ f = tablero.features_tablero(["e4", "e5", "Qh5"], "white", 2)
158
+ assert f["dama_fuera"] is True
159
+
160
+
161
+ def test_fallback_varia_por_tipo_de_jugada():
162
+ # Una mala sin patrΓ³n fuerte debe dar comentarios DISTINTOS segΓΊn el SAN.
163
+ base = lambda san: {
164
+ "color": "white", "number": 12, "move": san, "diferencia_cp": -50,
165
+ "mejor_jugada": "Xx",
166
+ }
167
+ captura = comentar(base("Rxe5"), "ImprecisiΓ³n", [])
168
+ peon = comentar(base("a3"), "ImprecisiΓ³n", [])
169
+ assert captura["corto"] != peon["corto"]
170
+
171
+
172
+ def test_patron_cp_sin_tablero_sigue_andando():
173
+ # Sin features de tablero, debe caer a los patrones de cp (compatibilidad).
174
+ estado = construir(_jugadas([-5, -20, -50, -80]))
175
+ assert detectar_patron(estado, "Error") == "deterioro_sostenido"
176
+
177
+
178
+ # ─── Runner sin pytest ───────────────────────────────────────────────────────
179
+
180
+ if __name__ == "__main__":
181
+ funcs = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
182
+ fallos = 0
183
+ for f in funcs:
184
+ try:
185
+ f()
186
+ print(f" OK {f.__name__}")
187
+ except AssertionError as e:
188
+ fallos += 1
189
+ print(f" FAIL {f.__name__}: {e}")
190
+ print(f"\n{len(funcs) - fallos}/{len(funcs)} tests pasaron.")
191
+ sys.exit(1 if fallos else 0)