---
name: comfyui_score_clip_alignment
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: impure
signature: "def comfyui_score_clip_alignment(image_path: str, prompt: str, *, server: str = '127.0.0.1:8188', venv_python: str = '~/ComfyUI/.venv/bin/python3', device: str = 'auto', timeout: float = 180.0) -> dict"
description: "Fidelidad prompt<->imagen via CLIP (0-1): similitud coseno entre el embedding de la imagen y el del texto con CLIP ViT-L/14. Juez de fidelidad del panel comfyui-judge. Impura: delega a un subproceso contra el python del venv de ComfyUI (torch + open_clip); calculo local, no via el server (el param server queda reservado)."
tags: [comfyui-judge, ml, clip, alignment, fidelity, scoring]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: error_go_core
imports: []
params:
  - name: image_path
    desc: "Ruta a la imagen en disco local."
  - name: prompt
    desc: "Texto contra el que medir la alineacion (idealmente en ingles, como CLIP)."
  - name: server
    desc: "host:port del server ComfyUI. RESERVADO para un backend futuro basado en nodos CLIPVisionEncode/CLIPTextEncode; hoy el calculo es local via open_clip. keyword-only."
  - name: venv_python
    desc: "Python del venv de ComfyUI con torch + open_clip; se expande '~'. keyword-only."
  - name: device
    desc: "'auto' (cuda si hay, si no cpu), 'cuda' o 'cpu'. keyword-only."
  - name: timeout
    desc: "Timeout del subproceso en segundos. keyword-only."
output: "dict {ok, score_0_1, error}. En exito ok=True y score_0_1 es la similitud coseno clamp a [0,1] (mayor = mas fiel al prompt; tipico 0.28-0.35 buen match, 0.10-0.18 distinto). En error ok=False, score_0_1=0.0 y error describe la causa. Nunca lanza excepcion."
tested: true
tests: ["error: imagen inexistente", "error: prompt vacio", "error: python del venv ComfyUI ausente", "nunca lanza excepcion + determinismo del error"]
test_file_path: "python/functions/ml/tests/test_comfyui_score_clip_alignment.py"
file_path: "python/functions/ml/comfyui_score_clip_alignment.py"
---

## Ejemplo

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

img = os.path.expanduser("~/ComfyUI/output/comfy_sdxl_00001_.png")
print(comfyui_score_clip_alignment(img, "a lion standing on rocks at sunset"))
# {'ok': True, 'score_0_1': 0.2818, 'error': ''}   (match)
print(comfyui_score_clip_alignment(img, "a red apple on a table"))
# {'ok': True, 'score_0_1': 0.1187, 'error': ''}   (mismatch -> mas bajo)
```

CLI directa:

```bash
python/.venv/bin/python3 python/functions/ml/comfyui_score_clip_alignment.py ~/ComfyUI/output/comfy_sdxl_00001_.png "a lion standing on rocks at sunset"
```

## Cuando usarla

- Cuando necesites comprobar que una imagen REALMENTE muestra lo que el prompt pedia
  (fidelidad), no solo que es bonita. Complementa a `comfyui_score_aesthetic`.
- Para elegir entre varias generaciones del mismo prompt la que mejor lo representa.
- Como uno de los tres jueces de `comfyui_judge_image`.

## Gotchas

- **No corre en el venv del registry.** Igual que el scorer estetico, la inferencia va por
  subproceso contra `~/ComfyUI/.venv/bin/python3` (torch + open_clip).
- **QuickGELU obligatorio** (`ViT-L-14-quickgelu` pretrained `openai`). Sin quick_gelu los
  embeddings se degradan y el ranking de prompts se invierte de forma silenciosa.
- **El score es similitud coseno, no una probabilidad.** Rangos tipicos: ~0.28-0.35 buen
  match, ~0.10-0.18 contenido distinto. Usa un umbral (~0.24) o compara RELATIVAMENTE; no
  esperes valores cercanos a 1.0 ni para un match perfecto.
- **Prompts en ingles.** CLIP openai esta entrenado en ingles; prompts en otros idiomas dan
  scores mas bajos y menos fiables.
- **`server` no se usa hoy.** El calculo es local; el parametro queda como contrato para un
  backend server futuro.
