fn_registry/docs/capabilities/comfyui-judge.md

# comfyui-judge — panel multi-juez de calidad de imagen

El "modelo adversario" del pipeline ComfyUI: el sistema que distingue **producto bueno de
malo** de forma objetiva. Tres jueces independientes puntúan/critican una imagen y un
agregador vota por mayoría. Es el **gate objetivo** que consumen los tests, los contratos
DoD y el bucle de mejora de skills (grupo `comfyui-skill`): un skill no está "hecho" hasta
que la imagen que produce pasa el panel (`verdict == 'good'`).

## Funciones del grupo

| ID | Firma corta | Qué hace |
|---|---|---|
| `comfyui_score_aesthetic_py_ml` | `score_aesthetic(image_path) -> {ok, score_0_10}` | Calidad estética LAION-V2 (head MLP sobre CLIP ViT-L/14). Subproceso al venv ComfyUI. Barato, determinista, sin API. |
| `comfyui_score_clip_alignment_py_ml` | `score_clip_alignment(image_path, prompt) -> {ok, score_0_1}` | Fidelidad prompt↔imagen (similitud coseno CLIP). Subproceso al venv ComfyUI. |
| `comfyui_critique_image_llm_py_ml` | `critique_image_llm(image_path, prompt) -> {ok, verdict, score_0_10, reasons}` | Crítica de un LLM-vision (artefactos, anatomía, watermarks). Compone `ask_llm_vision` (claude-direct). Cuesta API. |
| `comfyui_judge_image_py_ml` | `judge_image(image_path, prompt) -> {ok, verdict, score, votes, reasons}` | **Agregadora.** Llama a los 3, vota good/bad por mayoría, agrega razones. Degrada si un juez cae. |

Los tres jueces son ortogonales a propósito: el estético mide *belleza*, el de fidelidad mide
*que sea lo pedido*, y el crítico LLM ve *defectos finos* que un score global no penaliza. Un
único score se engaña fácil; tres votos independientes, no.

## Ejemplo canónico (end-to-end)

```python
import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from ml.comfyui_judge_image import comfyui_judge_image

img = os.path.expanduser("~/ComfyUI/output/comfy_sdxl_00001_.png")
prompt = "a majestic lion standing on rocks at sunset, photorealistic"

res = comfyui_judge_image(img, prompt)
print(res["verdict"], round(res["score"], 2), res["votes"])
# good 7.1 {'aesthetic': 'good', 'clip': 'good', 'llm': 'good'}

if res["verdict"] != "good":
    for r in res["reasons"]:
        print("  -", r)   # feedback accionable para mejorar el skill
```

Jueces sueltos (cuando solo quieres una dimensión):

```bash
# estético (sin API, rápido)
python/.venv/bin/python3 python/functions/ml/comfyui_score_aesthetic.py ~/ComfyUI/output/comfy_sdxl_00001_.png
# fidelidad
python/.venv/bin/python3 python/functions/ml/comfyui_score_clip_alignment.py ~/ComfyUI/output/comfy_sdxl_00001_.png "a lion at sunset"
```

## Cómo se enchufa a tests / DoD como gate objetivo

- **e2e_check de un skill ComfyUI**: declarar en el `app.md` (o en el contrato del skill) un
  check que genere la imagen y exija `comfyui_judge_image(img, prompt)["verdict"] == "good"`.
  Es la cláusula golden: producto = imagen que el panel aprueba, no "el workflow no petó".
- **Bucle de mejora** (grupo `comfyui-skill`): tras generar, juzgar; si `verdict == 'bad'`,
  las `reasons` del juez crítico indican qué corregir (más steps, otro sampler, fix de prompt)
  y se re-genera. Convergencia = el panel aprueba.
- **Selección de la mejor de N**: ejecutar el panel sobre cada candidata y rankear por `score`
  (o filtrar por `verdict == 'good'`).

Umbrales por defecto (ajustables): estético `>= 6.0` → good; fidelidad `>= 0.24` → good; el
crítico da su propio verdict. Veredicto final = **mayoría** de los votos vivos; empate → `bad`.

## Fronteras (qué NO cubre)

- **No genera imágenes.** Eso es el grupo `comfyui` (build_*_workflow + submit + wait + fetch).
  Este grupo solo *juzga* una imagen ya producida.
- **No es un detector forense de IA** ni un clasificador NSFW/seguridad: juzga *calidad de
  producto*, no procedencia ni políticas de contenido.
- **No corre en el venv del registry.** Los jueces estético/fidelidad necesitan torch +
  open_clip, que viven en `~/ComfyUI/.venv`; se invocan por subproceso. El crítico necesita la
  API Anthropic (claude-direct).
- **No persiste resultados.** Devuelve dicts en memoria; persistir veredictos (operations.db,
  e2e_runs) es responsabilidad del consumidor.

## Prerequisitos

- venv de ComfyUI con torch + open_clip 3.x: `~/ComfyUI/.venv/bin/python3`.
- Modelo estético LAION en `/mnt/2tb/comfyui_models/aesthetic/sac+logos+ava1-l14-linearMSE.pth`.
- CLIP ViT-L-14-quickgelu (pretrained openai) cacheado (se descarga la 1ª vez, ~900 MB).
- Token OAuth de Claude (claude-direct) para el juez crítico — lo resuelve `ask_llm_vision`.

## Notas

- **QuickGELU** es obligatorio en CLIP (`ViT-L-14-quickgelu`/`openai`): sin él los embeddings
  se degradan en silencio y tanto el score estético como el ranking de fidelidad se desvirtúan.
- El panel **degrada con gracia**: si un juez cae (p.ej. el LLM en HTTP 429), vota con los
  demás y lo anota; solo falla si caen los tres.