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)

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):

# 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.