---
name: comfyui_build_upscale_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_upscale_workflow(image: str, *, model_name: str = \"4x-UltraSharp.pth\", method: str = \"model\") -> dict"
description: "Construye el dict de un workflow ComfyUI de upscale en API format. method='model' usa UpscaleModelLoader + ImageUpscaleWithModel (ESRGAN, alta calidad); method='latent' usa ImageScaleBy (reescalado de pixel x2 sin modelo). Pura, sin red ni I/O."
tags: [comfyui, ml, upscale, esrgan, stable-diffusion, workflow]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: image
    desc: "Nombre del archivo de imagen dentro de la carpeta input/ del servidor ComfyUI; lo carga el nodo LoadImage."
  - name: model_name
    desc: "Nombre del modelo de upscale en models/upscale_models/ (ej. '4x-UltraSharp.pth'). Solo se usa con method='model'. keyword-only."
  - name: method
    desc: "'model' (ESRGAN via UpscaleModelLoader + ImageUpscaleWithModel) o 'latent' (reescalado de pixel x2 con ImageScaleBy, sin modelo). keyword-only."
output: "dict en API format. Con method='model': LoadImage '10' + UpscaleModelLoader '12' + ImageUpscaleWithModel '13' + SaveImage '9'. Con method='latent': LoadImage '10' + ImageScaleBy '13' + SaveImage '9'. Listo para comfyui_submit_workflow."
tested: true
tests: ["method='model' usa UpscaleModelLoader+ImageUpscaleWithModel", "method='latent' usa ImageScaleBy sin modelo", "determinismo: misma entrada -> mismo dict (builder puro)"]
test_file_path: "python/functions/ml/tests/test_comfyui_build_upscale_workflow.py"
file_path: "python/functions/ml/comfyui_build_upscale_workflow.py"
---

## Ejemplo

```python
import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from ml.comfyui_build_upscale_workflow import comfyui_build_upscale_workflow

# Upscale con modelo ESRGAN (necesita el .pth en models/upscale_models/)
wf = comfyui_build_upscale_workflow("render.png", model_name="4x-UltraSharp.pth")
# wf["12"]["class_type"] == "UpscaleModelLoader"
# wf["13"]["inputs"]["upscale_model"] == ["12", 0]

# Upscale rapido sin modelo (reescalado de pixel x2)
wf_latent = comfyui_build_upscale_workflow("render.png", method="latent")
# wf_latent["13"]["class_type"] == "ImageScaleBy"
```

Lánzalo con el python del venv (import de arriba o heredoc). Nota: `./fn run` directo no aplica porque la firma usa `*` (keyword-only), no soportado por el generador de runner de `fn run`.

## Cuando usarla

Cuando quieras ampliar una imagen ya generada. Usa `method="model"` (ESRGAN) para
mejor calidad si tienes un upscaler en `models/upscale_models/` (ej. 4x-UltraSharp);
usa `method="latent"` para un reescalado rapido sin descargar nada. Pega la salida
de un txt2img/img2img como `image` en el input/ del servidor.

## Gotchas

- `method="latent"` NO es un upscale en espacio latente real (eso requiere un
  checkpoint+VAE para encode/decode, que esta firma no recibe). Usa `ImageScaleBy`
  = reescalado de pixel con lanczos x2. Es honesto: barato y sin modelo, pero no
  recupera detalle como un ESRGAN. Para latent-upscale real construye un workflow
  con checkpoint + VAEEncode + LatentUpscale + VAEDecode.
- Con `method="model"`, `model_name` debe existir en `models/upscale_models/`. Si
  no, ComfyUI rechaza el workflow al enviarlo (HTTP 400). Valida antes con
  `comfyui_validate_workflow`.
- `image` debe existir en la carpeta `input/` del servidor.
- Es pura: no valida contra el servidor.
