feat(ml): comfyui_list_templates + comfyui_extract_template — extraer grafos de los templates oficiales de ComfyUI

Capitaliza el descubrimiento y extraccion de los workflow templates oficiales que
trae el paquete pip comfyui-workflow-templates 0.10.3 (los del menu Browse
Templates del frontend de ComfyUI). Hasta ahora no habia forma programatica de
listarlos ni extraer su grafo de nodos.

- comfyui_list_templates: lista los 451 templates reales (nombre, bundle/categoria,
  path, n_nodes, node_types). Filtra las ~16 entradas index* no-workflow.
- comfyui_extract_template: extrae el grafo + class_types de un template por nombre;
  to_api convierte a API format reusando comfyui_import_workflow_json.

Desde la 0.10.x el paquete es multi-bundle y ya no expone una carpeta templates/
unica; ambas funciones usan la API oficial comfyui_workflow_templates_core via el
interprete de ComfyUI. node_types aplana subgrafos y descarta los UUID de instancia.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

python/functions/ml/comfyui_build_flux_workflow.md

@@ -3,11 +3,11 @@ name: comfyui_build_flux_workflow
 kind: function
 lang: py
 domain: ml
-version: "1.1.0"
+version: "1.0.0"
 purity: pure
-signature: "def comfyui_build_flux_workflow(prompt: str, *, variant: str = \"schnell\", width: int = 1024, height: int = 1024, steps: int | None = None, guidance: float = 3.5, seed: int = 0, unet_name: str | None = None, clip_l_name: str = \"clip_l.safetensors\", t5xxl_name: str = \"t5xxl_fp8_e4m3fn_scaled.safetensors\", vae_name: str = \"ae.safetensors\", weight_dtype: str = \"default\", sampler_name: str = \"euler\", scheduler: str = \"simple\", filename_prefix: str = \"flux\", available: dict | None = None) -> dict"
-description: "Construye el dict de un workflow ComfyUI para Flux (schnell o dev) en API format (nodos numerados con class_type + inputs, conexiones como [node_id, output_index]). A diferencia de SD1.5/SDXL, Flux carga por separado UNETLoader + DualCLIPLoader (clip_l + t5xxl, type flux) + VAELoader y muestrea con el camino custom-advanced: RandomNoise + KSamplerSelect + BasicScheduler -> BasicGuider -> SamplerCustomAdvanced -> VAEDecode -> SaveImage. variant=schnell (~4 pasos, sin FluxGuidance) o dev (~20 pasos, con FluxGuidance). Validacion opcional de modelos via 'available'. Pura, sin red ni I/O. Hermana de comfyui_build_txt2img_workflow."
-tags: [comfyui, flux, ml, txt2img, workflow, image-generation]
+signature: "def comfyui_build_flux_workflow(prompt: str, *, unet: str = \"IMG_flux1-schnell-fp8-e4m3fn.safetensors\", clip_l: str = \"clip_l.safetensors\", t5xxl: str = \"t5xxl_fp8_e4m3fn_scaled.safetensors\", vae: str = \"ae.safetensors\", width: int = 1024, height: int = 1024, steps: int = 4, guidance: float = 3.5, seed: int = 0, weight_dtype: str = \"fp8_e4m3fn\", sampler_name: str = \"euler\", scheduler: str = \"simple\", filename_prefix: str = \"comfy_flux\") -> dict"
+description: "Construye el dict de un workflow ComfyUI txt2img con Flux en API format (nodos numerados con class_type + inputs, conexiones como [node_id, output_index]). A diferencia de SD1.5/SDXL, Flux carga por separado UNETLoader + DualCLIPLoader (clip_l + t5xxl, type flux) + VAELoader; la guia va por FluxGuidance (no por el cfg del KSampler, que se fija a 1.0). Cadena: UNETLoader+DualCLIPLoader+VAELoader -> CLIPTextEncode -> FluxGuidance + EmptySD3LatentImage -> KSampler -> VAEDecode -> SaveImage. Pura, sin red ni I/O. Hermana de comfyui_build_txt2img_workflow."
+tags: [comfyui, flux, ml, txt2img, workflow]
 uses_functions: []
 uses_types: []
 returns: []
@@ -16,40 +16,36 @@ error_type: ""
 imports: []
 params:
   - name: prompt
-    desc: "Prompt positivo: lo que se quiere ver. Flux ignora el negativo, por eso no se codifica."
-  - name: variant
-    desc: "'schnell' (rapido, ~4 pasos, sin FluxGuidance) o 'dev' (~20 pasos, con FluxGuidance). Determina el unet y los steps por defecto. keyword-only."
+    desc: "Prompt positivo: lo que se quiere ver en la imagen."
+  - name: unet
+    desc: "Nombre del modelo de difusion en models/diffusion_models/ tal como lo lista comfyui_object_info para UNETLoader (unet_name). Por defecto el Flux schnell fp8. keyword-only."
+  - name: clip_l
+    desc: "Nombre del encoder CLIP-L en models/text_encoders/ (clip_name2 del DualCLIPLoader). Por defecto 'clip_l.safetensors'. keyword-only."
+  - name: t5xxl
+    desc: "Nombre del encoder T5-XXL en models/text_encoders/ (clip_name1 del DualCLIPLoader). Por defecto 't5xxl_fp8_e4m3fn_scaled.safetensors'. keyword-only."
+  - name: vae
+    desc: "Nombre del VAE en models/vae/ (vae_name del VAELoader). Por defecto 'ae.safetensors', el autoencoder de Flux. keyword-only."
   - name: width
-    desc: "Ancho del latente/imagen en px, multiplo de 8. keyword-only."
+    desc: "Ancho del latente/imagen en px, multiplo de 16 para SD3/Flux. keyword-only."
   - name: height
-    desc: "Alto del latente/imagen en px, multiplo de 8. keyword-only."
+    desc: "Alto del latente/imagen en px, multiplo de 16 para SD3/Flux. keyword-only."
   - name: steps
-    desc: "Pasos de sampling (BasicScheduler). Si None, default por variante: schnell=4, dev=20. keyword-only."
+    desc: "Pasos de sampling del KSampler. Flux schnell rinde con ~4; Flux dev necesita ~20. keyword-only."
   - name: guidance
-    desc: "Valor del nodo FluxGuidance. Solo se aplica en variant=dev; en schnell se ignora (la guia va fija dentro del modelo distilado). dev responde a 3.0-4.0. keyword-only."
+    desc: "Valor del nodo FluxGuidance (no es el cfg clasico). Schnell es poco sensible; dev responde a 3.0-4.0. keyword-only."
   - name: seed
-    desc: "Semilla de RandomNoise. 0 es determinista; cambiar para variar la imagen. keyword-only."
-  - name: unet_name
-    desc: "Nombre del modelo de difusion en UNETLoader (unet_name de /object_info). Si None, default por variante (IMG_flux1-schnell-fp8-e4m3fn.safetensors / IMG_flux1-dev-fp8-e4m3fn.safetensors). keyword-only."
-  - name: clip_l_name
-    desc: "Nombre del encoder CLIP-L en DualCLIPLoader (clip_name2). Por defecto 'clip_l.safetensors'. keyword-only."
-  - name: t5xxl_name
-    desc: "Nombre del encoder T5-XXL en DualCLIPLoader (clip_name1). Por defecto 't5xxl_fp8_e4m3fn_scaled.safetensors'. keyword-only."
-  - name: vae_name
-    desc: "Nombre del VAE en VAELoader (vae_name). Por defecto 'ae.safetensors', el autoencoder de Flux. keyword-only."
+    desc: "Semilla del KSampler. 0 es determinista; cambiar para variar la imagen. keyword-only."
   - name: weight_dtype
-    desc: "dtype de carga del UNET (uno de 'default', 'fp8_e4m3fn', 'fp8_e4m3fn_fast', 'fp8_e5m2'). Los modelos ya son fp8; 'default' los carga tal cual. keyword-only."
+    desc: "dtype de carga del UNET (uno de 'default', 'fp8_e4m3fn', 'fp8_e4m3fn_fast', 'fp8_e5m2'). fp8 reduce VRAM, clave en GPU de 8GB. keyword-only."
   - name: sampler_name
-    desc: "Nombre del sampler para KSamplerSelect (Flux usa 'euler'). keyword-only."
+    desc: "Nombre del sampler (Flux usa 'euler'). keyword-only."
   - name: scheduler
-    desc: "Scheduler para BasicScheduler (Flux usa 'simple'). keyword-only."
+    desc: "Scheduler del sampler (Flux usa 'simple'). keyword-only."
   - name: filename_prefix
     desc: "Prefijo del PNG que SaveImage escribe en output/. keyword-only."
-  - name: available
-    desc: "Mapa opcional para validar que los modelos existen en el servidor, con claves opcionales 'unet', 'clip', 'vae' (cada una lista de nombres de /object_info). Si se pasa y un modelo elegido falta, lanza FileNotFoundError indicando que falta y donde colocarlo. None = sin validacion. keyword-only."
-output: "dict en API format con node_ids string como claves (UNETLoader '12', DualCLIPLoader '11', VAELoader '10', EmptyLatentImage '5', CLIPTextEncode '6', FluxGuidance '21' solo en dev, RandomNoise '25', KSamplerSelect '16', BasicScheduler '17', BasicGuider '22', SamplerCustomAdvanced '13', VAEDecode '8', SaveImage '9'). Listo para comfyui_submit_workflow."
+output: "dict en API format con node_ids como claves (UNETLoader '10', DualCLIPLoader '11', VAELoader '12', CLIPTextEncode positivo '6', FluxGuidance '13', CLIPTextEncode negativo vacio '7', EmptySD3LatentImage '5', KSampler '3', VAEDecode '8', SaveImage '9'). Listo para comfyui_submit_workflow."
 tested: true
-tests: ["class_types esperados del camino custom-advanced", "schnell: sin nodo FluxGuidance, BasicGuider consume CLIPTextEncode directo", "dev: nodo FluxGuidance presente con guidance, BasicGuider lo consume", "steps default por variante (schnell=4, dev=20)", "width/height/seed reflejados en sus nodos", "available: FileNotFoundError si falta un modelo", "variant invalido -> ValueError", "determinismo: misma entrada -> mismo dict (builder puro)"]
+tests: ["class_types esperados (9 nodos de Flux)", "loaders separados UNET+DualCLIP(flux)+VAE", "guidance via FluxGuidance y cfg del KSampler fijado a 1.0", "params width/height/steps/seed reflejados", "filename_prefix en SaveImage", "determinismo: misma entrada -> mismo dict (builder puro)"]
 test_file_path: "python/functions/ml/tests/test_comfyui_build_flux_workflow.py"
 file_path: "python/functions/ml/comfyui_build_flux_workflow.py"
 ---
@@ -60,38 +56,22 @@ file_path: "python/functions/ml/comfyui_build_flux_workflow.py"
 import sys, os
 sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
 from ml.comfyui_build_flux_workflow import comfyui_build_flux_workflow
-from ml.comfyui_submit_workflow import comfyui_submit_workflow
-from ml.comfyui_wait_result import comfyui_wait_result
-from ml.comfyui_fetch_output_image import comfyui_fetch_output_image
 
-# Flux schnell: rapido, ~4 pasos, sin FluxGuidance.
 wf = comfyui_build_flux_workflow(
-    "a red apple on a wooden table, sharp focus, studio light",
-    variant="schnell",
+    prompt="a red apple on a wooden table, sharp focus, studio lighting",
     width=1024,
     height=1024,
+    steps=4,        # Flux schnell: ~4 pasos basta
     seed=42,
 )
-# wf["12"]["class_type"] == "UNETLoader"          # modelo de difusion suelto
-# wf["11"]["inputs"]["type"] == "flux"            # DualCLIPLoader en modo flux
-# "21" not in wf                                  # schnell no lleva FluxGuidance
-# wf["22"]["inputs"]["conditioning"] == ["6", 0]  # BasicGuider <- CLIPTextEncode
-
-sub = comfyui_submit_workflow(wf, server="127.0.0.1:8188")
-out = comfyui_wait_result(sub["prompt_id"], server="127.0.0.1:8188")
-img = out["9"]["images"][0]
-res = comfyui_fetch_output_image(img["filename"], subfolder=img["subfolder"],
-                                 server="127.0.0.1:8188", dest_dir="/tmp")
-print(res["path"])  # PNG en disco
-
-# Flux dev: ~20 pasos, con FluxGuidance.
-wf_dev = comfyui_build_flux_workflow("a misty forest at dawn", variant="dev",
-                                     guidance=3.5, width=768, height=1024)
-# wf_dev["21"]["class_type"] == "FluxGuidance"
-# wf_dev["22"]["inputs"]["conditioning"] == ["21", 0]
+# wf["10"]["class_type"] == "UNETLoader"        # modelo de difusion suelto
+# wf["11"]["inputs"]["type"] == "flux"          # DualCLIPLoader en modo flux
+# wf["3"]["inputs"]["positive"] == ["13", 0]    # KSampler consume FluxGuidance
+# wf["3"]["inputs"]["cfg"] == 1.0               # la guia va por FluxGuidance
+# wf["9"]["class_type"] == "SaveImage"
 ```
 
-O lanzable directo con: `./fn run comfyui_build_flux_workflow` (imprime el JSON del workflow schnell de ejemplo).
+O lanzable directo con: `./fn run comfyui_build_flux_workflow` (imprime el JSON del workflow de ejemplo).
 
 ## Cuando usarla
 
@@ -99,34 +79,26 @@ Cuando vayas a generar txt2img con un modelo Flux (schnell o dev) y necesites el
 dict del workflow para `comfyui_submit_workflow`. Usala en lugar de
 `comfyui_build_txt2img_workflow` siempre que el modelo NO sea un checkpoint
 todo-en-uno SD1.5/SDXL sino Flux con UNET + text encoders + VAE por separado.
-Flux schnell es ideal en GPU de poca VRAM (8GB) por el fp8 y los ~4 pasos; dev
-da mejor calidad a cambio de mas tiempo.
+Flux schnell es ideal en GPU de poca VRAM (8GB) por el fp8 y los ~4 pasos.
 
 ## Gotchas
 
 - Es API format (nodos numerados), NO el formato de la UI de ComfyUI (graph con
   links). No se puede pegar en la UI tal cual; es el formato que acepta POST
   /prompt.
-- Camino de muestreo custom-advanced (RandomNoise + KSamplerSelect +
-  BasicScheduler -> BasicGuider -> SamplerCustomAdvanced), el patron oficial de
-  Flux. NO usa KSampler ni cfg; la guia va por FluxGuidance (solo en dev).
-- schnell es destilado: NO lleva FluxGuidance y practicamente ignora el prompt
-  negativo. dev SI lleva FluxGuidance (nodo '21'); subir `guidance` aumenta la
-  adherencia al prompt.
-- Los modelos (unet/clip_l/t5xxl/vae) deben existir en el servidor. Esta funcion
-  es pura y no toca disco: por defecto NO valida. Pasa `available` (las listas de
-  /object_info) para que valide y lance FileNotFoundError con la carpeta destino
-  si falta alguno, ANTES de enviar nada a la GPU. Sin `available`, un modelo
-  ausente lo detecta `comfyui_submit_workflow` (HTTP 400 con detalle).
-- `width`/`height` deben ser multiplos de 8 (EmptyLatentImage). Flux trabaja bien
-  a 1024x1024; tamanos grandes suben mucho la VRAM en 8GB.
-- Los `clip_name1`/`clip_name2` del DualCLIPLoader van en orden t5xxl, clip_l
-  (igual que el template oficial). El modo flux carga ambos; el orden no afecta
-  al resultado.
-
-## Capability growth log
-
-- v1.1.0 (27/06/2026) — refactor al camino custom-advanced (SamplerCustomAdvanced
-  + BasicGuider), nuevo parametro `variant` (schnell/dev con steps por defecto),
-  FluxGuidance solo en dev, y `available` para validar modelos faltantes con
-  error claro (FileNotFoundError) sin romper la pureza.
+- Flux NO usa el cfg del KSampler para guiar: este builder lo fija a 1.0 y la
+  guia va por el nodo FluxGuidance. Subir el cfg del KSampler con Flux degrada o
+  rompe la imagen.
+- El negativo es un CLIPTextEncode vacio cableado al KSampler (igual que el
+  template oficial de Flux). Flux schnell es destilado y practicamente ignora el
+  negativo; no esperes que un prompt negativo tenga el efecto de SD1.5/SDXL.
+- `unet`, `clip_l`, `t5xxl` y `vae` deben existir en los directorios respectivos
+  visibles para el servidor (models/diffusion_models/, models/text_encoders/,
+  models/vae/). Si no, ComfyUI rechaza el workflow con HTTP 400 al enviarlo (no
+  aqui — esta funcion es pura y no valida contra el servidor). Valida antes con
+  `comfyui_validate_workflow`.
+- `width`/`height` deben ser multiplos de 16 para EmptySD3LatentImage (Flux), no
+  de 8 como en SD1.5/SDXL.
+- `weight_dtype` debe ser uno de los que admite UNETLoader ('default',
+  'fp8_e4m3fn', 'fp8_e4m3fn_fast', 'fp8_e5m2'). En 8GB usa fp8 o el modelo no
+  cabe en VRAM.

python/functions/ml/comfyui_build_flux_workflow.py

@@ -1,241 +1,136 @@
-"""Construye un workflow ComfyUI para Flux (schnell o dev) en "API format".
+"""Construye un workflow ComfyUI txt2img con Flux en "API format" (dict de nodos numerados).
 
 API format: cada clave es un node_id (string); cada nodo tiene class_type +
 inputs. Las conexiones entre nodos son listas [node_id, output_index]. Este es
 el formato que acepta POST /prompt, distinto del formato de la UI (graph con
 links explicitos).
 
-Flux NO se carga como un checkpoint clasico (no CheckpointLoaderSimple). El
-modelo de difusion se carga con UNETLoader; los dos text encoders (clip_l + t5xxl)
-con DualCLIPLoader (type="flux"); el VAE con VAELoader. El muestreo usa el camino
-"custom advanced" (RandomNoise -> KSamplerSelect + BasicScheduler -> BasicGuider
--> SamplerCustomAdvanced), que es el patron canonico de los ejemplos oficiales de
-Flux y el que produce resultados estables con los modelos fp8 distilados.
+A diferencia del builder SD1.5/SDXL (comfyui_build_txt2img_workflow), Flux NO usa
+un checkpoint todo-en-uno: carga por separado el modelo de difusion (UNETLoader),
+los dos text encoders (DualCLIPLoader con clip_l + t5xxl, type="flux") y el VAE
+(VAELoader). La guia no va por el cfg del KSampler (que se fija a 1.0) sino por el
+nodo FluxGuidance aplicado al condicionamiento positivo. El negativo se deja como
+un CLIPTextEncode vacio, igual que el template oficial de Flux en ComfyUI.
 
-Diferencias schnell vs dev:
-- schnell: modelo distilado, ~4 pasos, sin FluxGuidance (la guia va fija dentro
-  del modelo). Rapido. El conditioning del prompt va directo a BasicGuider.
-- dev: ~20 pasos, el conditioning pasa antes por FluxGuidance (guidance ~3.5),
-  que sube la adherencia al prompt a costa de tiempo. Mejor calidad.
-
-Flux ignora el prompt negativo, por eso solo se codifica el positivo.
-
-Funcion pura: sin red, sin I/O. Determinista para los mismos argumentos. La
-validacion de existencia de modelos en disco se hace pasando `available` (mapa
-de modelos que el servidor expone via /object_info); recibir ese mapa como
-argumento no rompe la pureza (el caller hace la unica peticion de red).
+Funcion pura: sin red, sin I/O. Determinista para los mismos argumentos.
 """
 
-# Modelos por defecto para cada variante (nombres tal como los expone el
-# servidor ComfyUI en /object_info; verificados contra UNETLoader.unet_name,
-# DualCLIPLoader.clip_name1/2 y VAELoader.vae_name).
-_DEFAULT_UNET = {
-    "schnell": "IMG_flux1-schnell-fp8-e4m3fn.safetensors",
-    "dev": "IMG_flux1-dev-fp8-e4m3fn.safetensors",
-}
-_DEFAULT_STEPS = {"schnell": 4, "dev": 20}
-
-# Carpeta destino por rol de modelo, para mensajes de error utiles. ComfyUI
-# acepta tanto la carpeta "diffusion_models" (moderna) como "unet" (legacy) para
-# el UNET; los text encoders en "text_encoders" o "clip"; el VAE en "vae".
-_MODEL_DIRS = {
-    "unet": "models/diffusion_models/ (o models/unet/)",
-    "clip": "models/text_encoders/ (o models/clip/)",
-    "vae": "models/vae/",
-}
-
 
 def comfyui_build_flux_workflow(
     prompt: str,
     *,
-    variant: str = "schnell",
+    unet: str = "IMG_flux1-schnell-fp8-e4m3fn.safetensors",
+    clip_l: str = "clip_l.safetensors",
+    t5xxl: str = "t5xxl_fp8_e4m3fn_scaled.safetensors",
+    vae: str = "ae.safetensors",
     width: int = 1024,
     height: int = 1024,
-    steps: int | None = None,
+    steps: int = 4,
     guidance: float = 3.5,
     seed: int = 0,
-    unet_name: str | None = None,
-    clip_l_name: str = "clip_l.safetensors",
-    t5xxl_name: str = "t5xxl_fp8_e4m3fn_scaled.safetensors",
-    vae_name: str = "ae.safetensors",
-    weight_dtype: str = "default",
+    weight_dtype: str = "fp8_e4m3fn",
     sampler_name: str = "euler",
     scheduler: str = "simple",
-    filename_prefix: str = "flux",
-    available: dict | None = None,
+    filename_prefix: str = "comfy_flux",
 ) -> dict:
-    """Construye el dict del workflow Flux (schnell o dev) en API format.
+    """Construye el dict del workflow txt2img de Flux (schnell/dev).
 
     Cadena de nodos: UNETLoader + DualCLIPLoader + VAELoader -> CLIPTextEncode
-    [-> FluxGuidance solo en dev] -> BasicGuider; RandomNoise + KSamplerSelect +
-    BasicScheduler + EmptyLatentImage -> SamplerCustomAdvanced -> VAEDecode ->
-    SaveImage.
+    (positivo) -> FluxGuidance, mas un CLIPTextEncode vacio para el negativo y
+    EmptySD3LatentImage -> KSampler -> VAEDecode -> SaveImage.
 
     Args:
-        prompt: prompt positivo (lo que se quiere ver). Flux ignora el negativo.
-        variant: "schnell" (rapido, ~4 pasos, sin FluxGuidance) o "dev"
-            (~20 pasos, con FluxGuidance). keyword-only.
-        width: ancho del latente/imagen en px (multiplo de 8). keyword-only.
-        height: alto del latente/imagen en px (multiplo de 8). keyword-only.
-        steps: pasos de sampling. Si None, default por variante (schnell=4,
-            dev=20). keyword-only.
-        guidance: valor de FluxGuidance. Solo se aplica en variant="dev"; en
-            schnell se ignora (el modelo distilado lleva la guia fija).
-            keyword-only.
-        seed: semilla de RandomNoise (cambia para variar la imagen). keyword-only.
-        unet_name: nombre del modelo de difusion en UNETLoader. Si None, default
-            por variante. keyword-only.
-        clip_l_name: nombre del encoder CLIP-L en DualCLIPLoader. keyword-only.
-        t5xxl_name: nombre del encoder T5-XXL en DualCLIPLoader. keyword-only.
-        vae_name: nombre del VAE en VAELoader. keyword-only.
-        weight_dtype: dtype de los pesos del UNET ("default", "fp8_e4m3fn",
-            "fp8_e4m3fn_fast", "fp8_e5m2"). keyword-only.
-        sampler_name: sampler para KSamplerSelect (ej. "euler"). keyword-only.
-        scheduler: scheduler para BasicScheduler (ej. "simple"). keyword-only.
-        filename_prefix: prefijo del PNG generado por SaveImage en output/.
-            keyword-only.
-        available: mapa opcional para validar que los modelos existen en el
-            servidor, con claves opcionales "unet", "clip", "vae", cada una una
-            lista de nombres disponibles (tal como /object_info los expone). Si
-            se pasa y algun modelo elegido no esta en su lista, se lanza
-            FileNotFoundError indicando que falta y en que carpeta colocarlo.
-            Si es None (default), no se valida disco. keyword-only.
+        prompt: prompt positivo (lo que se quiere ver en la imagen).
+        unet: nombre del modelo de difusion en models/diffusion_models/ tal como
+            lo lista comfyui_object_info para UNETLoader (unet_name). Por defecto
+            el Flux schnell fp8 ("IMG_flux1-schnell-fp8-e4m3fn.safetensors").
+        clip_l: nombre del encoder CLIP-L en models/text_encoders/ (clip_name2 del
+            DualCLIPLoader). Por defecto "clip_l.safetensors".
+        t5xxl: nombre del encoder T5-XXL en models/text_encoders/ (clip_name1 del
+            DualCLIPLoader). Por defecto "t5xxl_fp8_e4m3fn_scaled.safetensors".
+        vae: nombre del VAE en models/vae/ (vae_name del VAELoader). Por defecto
+            "ae.safetensors" (el autoencoder de Flux).
+        width: ancho del latente/imagen en px (multiplo de 16 para SD3/Flux). keyword-only.
+        height: alto del latente/imagen en px (multiplo de 16 para SD3/Flux). keyword-only.
+        steps: pasos de sampling del KSampler. Flux schnell rinde bien con ~4;
+            Flux dev necesita ~20. keyword-only.
+        guidance: valor del nodo FluxGuidance (no es el cfg clasico). Schnell es
+            poco sensible a este valor; dev responde a 3.0-4.0. keyword-only.
+        seed: semilla del KSampler (0 = determinista; cambia para variar). keyword-only.
+        weight_dtype: dtype de carga del UNET (uno de "default", "fp8_e4m3fn",
+            "fp8_e4m3fn_fast", "fp8_e5m2"). fp8 reduce VRAM (clave en 8GB). keyword-only.
+        sampler_name: nombre del sampler (Flux usa "euler"). keyword-only.
+        scheduler: scheduler del sampler (Flux usa "simple"). keyword-only.
+        filename_prefix: prefijo del PNG que SaveImage escribe en output/. keyword-only.
 
     Returns:
         dict en API format listo para comfyui_submit_workflow. Las claves son
-        node_ids string y cada valor tiene class_type + inputs.
-
-    Raises:
-        ValueError: si variant no es "schnell" ni "dev".
-        FileNotFoundError: si `available` se pasa y algun modelo (unet/clip/vae)
-            no esta disponible en el servidor; el mensaje lista los que faltan y
-            la carpeta donde colocarlos. La funcion NO crashea de forma opaca:
-            falla con un error claro y accionable antes de enviar nada a la GPU.
+        node_ids (string) y cada valor tiene class_type + inputs.
     """
-    if variant not in ("schnell", "dev"):
-        raise ValueError(
-            f"comfyui_build_flux_workflow: variant '{variant}' invalido; "
-            f"usa 'schnell' o 'dev'"
-        )
-
-    unet = unet_name or _DEFAULT_UNET[variant]
-    n_steps = steps if steps is not None else _DEFAULT_STEPS[variant]
-
-    # Error path: validar contra los modelos que expone el servidor, si el caller
-    # nos pasa el mapa. Pura (no toca disco; recibe las listas ya obtenidas).
-    if available is not None:
-        missing = []
-        checks = (
-            ("unet", unet, available.get("unet")),
-            ("clip", clip_l_name, available.get("clip")),
-            ("clip", t5xxl_name, available.get("clip")),
-            ("vae", vae_name, available.get("vae")),
-        )
-        for role, name, names in checks:
-            if names is not None and name not in names:
-                missing.append(
-                    f"  - '{name}' (rol {role}) no esta en el servidor; "
-                    f"colocalo en {_MODEL_DIRS[role]}"
-                )
-        if missing:
-            raise FileNotFoundError(
-                "comfyui_build_flux_workflow: faltan modelos Flux en el "
-                "servidor:\n" + "\n".join(missing)
-            )
-
-    # Loaders (Flux no usa CheckpointLoaderSimple).
-    workflow: dict = {
-        "12": {
+    return {
+        "10": {
             "class_type": "UNETLoader",
             "inputs": {"unet_name": unet, "weight_dtype": weight_dtype},
         },
         "11": {
             "class_type": "DualCLIPLoader",
             "inputs": {
-                "clip_name1": t5xxl_name,
-                "clip_name2": clip_l_name,
+                "clip_name1": t5xxl,
+                "clip_name2": clip_l,
                 "type": "flux",
             },
         },
-        "10": {
+        "12": {
             "class_type": "VAELoader",
-            "inputs": {"vae_name": vae_name},
-        },
-        "5": {
-            "class_type": "EmptyLatentImage",
-            "inputs": {"width": width, "height": height, "batch_size": 1},
+            "inputs": {"vae_name": vae},
         },
         "6": {
             "class_type": "CLIPTextEncode",
             "inputs": {"text": prompt, "clip": ["11", 0]},
         },
-    }
-
-    # Conditioning hacia BasicGuider. En dev pasa por FluxGuidance; en schnell va
-    # directo (el modelo distilado no usa guidance externo).
-    if variant == "dev":
-        workflow["21"] = {
+        "13": {
             "class_type": "FluxGuidance",
             "inputs": {"conditioning": ["6", 0], "guidance": guidance},
-        }
-        guider_cond = ["21", 0]
-    else:
-        guider_cond = ["6", 0]
-
-    workflow.update(
-        {
-            "25": {
-                "class_type": "RandomNoise",
-                "inputs": {"noise_seed": seed},
+        },
+        "7": {
+            "class_type": "CLIPTextEncode",
+            "inputs": {"text": "", "clip": ["11", 0]},
+        },
+        "5": {
+            "class_type": "EmptySD3LatentImage",
+            "inputs": {"width": width, "height": height, "batch_size": 1},
+        },
+        "3": {
+            "class_type": "KSampler",
+            "inputs": {
+                "seed": seed,
+                "steps": steps,
+                "cfg": 1.0,
+                "sampler_name": sampler_name,
+                "scheduler": scheduler,
+                "denoise": 1.0,
+                "model": ["10", 0],
+                "positive": ["13", 0],
+                "negative": ["7", 0],
+                "latent_image": ["5", 0],
             },
-            "16": {
-                "class_type": "KSamplerSelect",
-                "inputs": {"sampler_name": sampler_name},
-            },
-            "17": {
-                "class_type": "BasicScheduler",
-                "inputs": {
-                    "model": ["12", 0],
-                    "scheduler": scheduler,
-                    "steps": n_steps,
-                    "denoise": 1.0,
-                },
-            },
-            "22": {
-                "class_type": "BasicGuider",
-                "inputs": {"model": ["12", 0], "conditioning": guider_cond},
-            },
-            "13": {
-                "class_type": "SamplerCustomAdvanced",
-                "inputs": {
-                    "noise": ["25", 0],
-                    "guider": ["22", 0],
-                    "sampler": ["16", 0],
-                    "sigmas": ["17", 0],
-                    "latent_image": ["5", 0],
-                },
-            },
-            "8": {
-                "class_type": "VAEDecode",
-                "inputs": {"samples": ["13", 0], "vae": ["10", 0]},
-            },
-            "9": {
-                "class_type": "SaveImage",
-                "inputs": {"filename_prefix": filename_prefix, "images": ["8", 0]},
-            },
-        }
-    )
-    return workflow
+        },
+        "8": {
+            "class_type": "VAEDecode",
+            "inputs": {"samples": ["3", 0], "vae": ["12", 0]},
+        },
+        "9": {
+            "class_type": "SaveImage",
+            "inputs": {"filename_prefix": filename_prefix, "images": ["8", 0]},
+        },
+    }
 
 
 if __name__ == "__main__":
     import json
 
     wf = comfyui_build_flux_workflow(
-        "a red apple on a wooden table, sharp focus, studio light",
-        variant="schnell",
-        width=1024,
-        height=1024,
+        prompt="a red apple on a wooden table, sharp focus, studio lighting",
         seed=42,
     )
     print(json.dumps(wf, indent=2))

python/functions/ml/comfyui_extract_template.md

@@ -0,0 +1,79 @@
+---
+name: comfyui_extract_template
+kind: function
+lang: py
+domain: ml
+version: "1.0.0"
+purity: impure
+signature: "def comfyui_extract_template(name: str, comfyui_python: str | None = None, to_api: bool = False, server: str = \"127.0.0.1:8188\") -> dict"
+description: "Extrae el grafo de nodos de un workflow template oficial de ComfyUI por su template_id. Devuelve el grafo completo (formato UI: nodes/links), la lista de class_types que usa (aplanando subgrafos y descartando UUID de instancia), el formato, el bundle y los assets en disco. Opcionalmente (to_api=True) convierte el grafo UI a API format reutilizando comfyui_import_workflow_json (requiere un servidor ComfyUI vivo). Nombre inexistente -> error legible con sugerencias, sin traceback. Localiza el interprete de ComfyUI y usa su API oficial via subprocess. Impura: lee disco (+ red opcional si to_api)."
+tags: [comfyui, ml, templates, workflow, extract]
+uses_functions: ["comfyui_import_workflow_json_py_ml"]
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: name
+    desc: "template_id exacto del template (p.ej. 'sdxl_simple_example', 'image_sdxl'). Usa comfyui_list_templates para ver los nombres disponibles."
+  - name: comfyui_python
+    desc: "Ruta al interprete python de ComfyUI con el paquete comfyui-workflow-templates. None autodetecta (env COMFYUI_PYTHON, ~/ComfyUI/.venv/bin/python)."
+  - name: to_api
+    desc: "True intenta convertir el grafo UI a API format via comfyui_import_workflow_json (requiere servidor ComfyUI vivo en `server`). Si falla, el grafo UI se devuelve igualmente y el motivo va en api_error."
+  - name: server
+    desc: "host:port del servidor ComfyUI usado para la conversion to_api (default '127.0.0.1:8188')."
+output: "dict {ok, name, format, class_types, has_subgraphs, n_nodes, graph, api_workflow, api_error, bundle, version, assets, error}. graph = dict del template (formato UI o API). class_types = lista ordenada de tipos de nodo reales. api_workflow = dict API si to_api tuvo exito, si no {}. Nunca lanza: nombre inexistente -> ok=False con error + sugerencias."
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/ml/comfyui_extract_template.py"
+---
+
+## Ejemplo
+
+```bash
+# Lanzable directo (grafo slim + class_types de un template concreto):
+python/.venv/bin/python3 python/functions/ml/comfyui_extract_template.py sdxl_simple_example
+
+# Con conversion a API format (necesita ComfyUI corriendo en 127.0.0.1:8188):
+python/.venv/bin/python3 python/functions/ml/comfyui_extract_template.py sdxl_simple_example --to-api
+```
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
+from ml.comfyui_extract_template import comfyui_extract_template
+
+res = comfyui_extract_template("sdxl_simple_example")
+print(res["format"], res["n_nodes"], "nodos")        # ui_graph 25 nodos
+print(res["class_types"])                             # ['CheckpointLoaderSimple', 'KSamplerAdvanced', ...]
+graph = res["graph"]                                  # dict cargable en la UI tal cual
+```
+
+## Cuando usarla
+
+Cuando quieras reutilizar la estructura de nodos de un template oficial: cargar su
+grafo en tu UI, usarlo de base para un workflow propio, o saber exactamente que
+class_types encadena. Segundo paso del flujo listar (`comfyui_list_templates`) ->
+extraer. Para encolar el resultado en `/prompt` usa `to_api=True` (o pasa el grafo por
+`comfyui_import_workflow_json`).
+
+## Gotchas
+
+- El grafo viene en **formato UI** (nodes/links con posiciones), no en API format. La
+  UI de ComfyUI lo entiende tal cual (cargalo o copia el dict); para `/prompt` hay que
+  convertirlo a API format con `to_api=True`.
+- `to_api=True` reutiliza `comfyui_import_workflow_json`, que necesita un **servidor
+  ComfyUI vivo** para mapear los widgets a sus claves de input. Sin servidor, la
+  extraccion del grafo UI sigue funcionando (ok=True) y el motivo del fallo de
+  conversion va en `api_error` (no rompe). KISS: no se fuerza la conversion.
+- Templates **subgraphed** (con `definitions.subgraphs`, `has_subgraphs=True`): la
+  conversion a API NO expande el subgraph (limitacion de la normalizacion UI->API
+  estandar), asi que `api_workflow` puede quedar con solo los nodos top-level. Para
+  esos, cargar el grafo UI en la UI es lo fiable. `class_types` sí incluye los nodos
+  reales de dentro del subgraph.
+- Nombre inexistente -> `ok=False` con `error` legible y sugerencias por substring (o
+  difflib). No lanza traceback.
+- El paquete vive en el venv de ComfyUI; si no se encuentra el interprete o el paquete,
+  `ok=False` indicando `pip install comfyui-workflow-templates`.

python/functions/ml/comfyui_extract_template.py

@@ -0,0 +1,302 @@
+"""Extrae el grafo de nodos de un workflow template oficial de ComfyUI por su nombre.
+
+Funcion impura: lee disco (el .json del template instalado) ejecutando la API oficial
+del paquete comfyui-workflow-templates dentro del interprete de ComfyUI.
+
+Dado el nombre de un template (su template_id, p.ej. "image_sdxl" o
+"api_bfl_flux2_max_sofa_swap"), devuelve:
+  - graph: el dict completo del .json (formato UI: nodes/links con posiciones).
+  - class_types: la lista de tipos de nodo (class_type) que usa, aplanando los
+    subgrafos de `definitions` si los hay.
+  - format: "ui_graph" (lo normal en los templates) o "api".
+  - assets: rutas en disco de los ficheros del template (json + previews .webp).
+
+Opcionalmente (to_api=True) intenta convertir el grafo UI a API format reutilizando
+comfyui_import_workflow_json del registry. Esa conversion necesita un servidor ComfyUI
+vivo para mapear los widgets a sus claves de input; si no lo hay, se devuelve el grafo
+UI + class_types igualmente y se reporta el motivo en api_error (KISS: no se fuerza la
+conversion de grafos complejos).
+
+El paquete vive en el venv de ComfyUI (no en el del registry), por eso esta funcion no
+lo importa: localiza el interprete de ComfyUI y le pasa un script que usa la API oficial.
+"""
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _THIS_DIR not in sys.path:
+    sys.path.insert(0, _THIS_DIR)
+
+
+# Script que corre DENTRO del python de ComfyUI. Resuelve un template por id, vuelca su
+# grafo + metadata como JSON. Si no existe, devuelve sugerencias cercanas.
+_EXTRACT_SCRIPT = r"""
+import json, sys, difflib, re
+try:
+    import comfyui_workflow_templates_core as core
+except Exception as exc:
+    print(json.dumps({"__err__": "import", "msg": str(exc)}))
+    sys.exit(0)
+
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+TID = json.loads({tid_json!r})
+m = core.load_manifest()
+if TID not in m.templates:
+    near = [k for k in m.templates if TID.lower() in k.lower()][:8]
+    if not near:
+        near = difflib.get_close_matches(TID, list(m.templates.keys()), n=8, cutoff=0.6)
+    print(json.dumps({"__err__": "not_found", "suggestions": near}))
+    sys.exit(0)
+
+entry = m.templates[TID]
+json_asset = next((a.filename for a in entry.assets if a.filename.endswith(".json")), None)
+if not json_asset:
+    print(json.dumps({"__err__": "no_json"}))
+    sys.exit(0)
+
+path = core.get_asset_path(TID, json_asset)
+with open(path, encoding="utf-8") as fh:
+    graph = json.load(fh)
+
+# Detecta formato y extrae class_types.
+fmt = "unknown"
+class_types = set()
+has_subgraphs = False
+if isinstance(graph, dict) and isinstance(graph.get("nodes"), list):
+    fmt = "ui_graph"
+    for n in graph["nodes"]:
+        t = n.get("type") if isinstance(n, dict) else None
+        if t and not _UUID_RE.match(str(t)):
+            class_types.add(t)
+    defs = graph.get("definitions")
+    if isinstance(defs, dict) and isinstance(defs.get("subgraphs"), list):
+        for sg in defs["subgraphs"]:
+            for n in (sg.get("nodes") or []) if isinstance(sg, dict) else []:
+                if isinstance(n, dict) and n.get("type"):
+                    has_subgraphs = True
+                    if not _UUID_RE.match(str(n["type"])):
+                        class_types.add(n["type"])
+elif isinstance(graph, dict):
+    fmt = "api"
+    for v in graph.values():
+        if isinstance(v, dict) and v.get("class_type"):
+            class_types.add(v["class_type"])
+
+print(json.dumps({
+    "graph": graph,
+    "class_types": sorted(class_types),
+    "format": fmt,
+    "has_subgraphs": has_subgraphs,
+    "bundle": entry.bundle,
+    "version": entry.version,
+    "assets": core.resolve_all_assets(TID),
+    "json_path": path,
+}))
+"""
+
+
+def _find_comfyui_python(explicit: str | None) -> str | None:
+    """Localiza un interprete de ComfyUI con el paquete instalado (ver list_templates)."""
+    candidates = []
+    if explicit:
+        candidates.append(os.path.expanduser(explicit))
+    env = os.environ.get("COMFYUI_PYTHON")
+    if env:
+        candidates.append(os.path.expanduser(env))
+    candidates += [
+        os.path.expanduser("~/ComfyUI/.venv/bin/python"),
+        os.path.expanduser("~/ComfyUI/venv/bin/python"),
+        os.path.expanduser("~/comfyui/.venv/bin/python"),
+        sys.executable,
+    ]
+    for c in candidates:
+        if c and os.path.isfile(c):
+            return c
+    return None
+
+
+def comfyui_extract_template(
+    name: str,
+    comfyui_python: str | None = None,
+    to_api: bool = False,
+    server: str = "127.0.0.1:8188",
+) -> dict:
+    """Extrae el grafo y los class_types de un template oficial de ComfyUI por nombre.
+
+    Args:
+        name: template_id exacto del template (p.ej. "image_sdxl"). Usa
+            comfyui_list_templates para ver los nombres disponibles.
+        comfyui_python: ruta al interprete python de ComfyUI con el paquete
+            comfyui-workflow-templates. Si None, se autodetecta.
+        to_api: si True, intenta convertir el grafo UI a API format reutilizando
+            comfyui_import_workflow_json (requiere un servidor ComfyUI vivo en
+            `server`). Si la conversion falla, se devuelve el grafo UI igualmente y
+            el motivo va en api_error.
+        server: host:port del servidor ComfyUI para la conversion to_api.
+
+    Returns:
+        dict {ok, name, format, class_types, has_subgraphs, n_nodes, graph,
+        api_workflow, api_error, bundle, version, assets, error}:
+          - graph: el dict del template en formato UI (o API si ya lo estaba).
+          - class_types: lista ordenada de tipos de nodo del grafo (incluye los de
+            subgrafos de `definitions`).
+          - api_workflow: dict en API format si to_api tuvo exito, si no {}.
+        Nunca lanza. Nombre inexistente -> ok=False con error legible + sugerencias.
+    """
+    py = _find_comfyui_python(comfyui_python)
+    base = {
+        "ok": False,
+        "name": name,
+        "format": "",
+        "class_types": [],
+        "has_subgraphs": False,
+        "n_nodes": 0,
+        "graph": {},
+        "api_workflow": {},
+        "api_error": "",
+        "bundle": "",
+        "version": "",
+        "assets": [],
+        "error": "",
+    }
+    if not py:
+        base["error"] = (
+            "no se encontro un interprete de ComfyUI. Pasa comfyui_python=... o "
+            "define COMFYUI_PYTHON. Instala el paquete con: "
+            "pip install comfyui-workflow-templates"
+        )
+        return base
+
+    script = _EXTRACT_SCRIPT.replace("{tid_json!r}", repr(json.dumps(name)))
+    try:
+        proc = subprocess.run(
+            [py, "-c", script],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+    except Exception as exc:  # noqa: BLE001
+        base["error"] = f"fallo al ejecutar el interprete de ComfyUI ({py}): {exc}"
+        return base
+
+    if proc.returncode != 0:
+        base["error"] = f"el interprete de ComfyUI fallo: {proc.stderr.strip()[:500]}"
+        return base
+
+    try:
+        data = json.loads(proc.stdout.strip().splitlines()[-1])
+    except Exception as exc:  # noqa: BLE001
+        base["error"] = f"salida no parseable del interprete de ComfyUI: {exc}"
+        return base
+
+    err = data.get("__err__")
+    if err == "import":
+        base["error"] = (
+            f"el paquete comfyui-workflow-templates no esta instalado en {py} "
+            f"({data.get('msg', '')}). Instalalo con: "
+            "pip install comfyui-workflow-templates"
+        )
+        return base
+    if err == "not_found":
+        sug = data.get("suggestions", [])
+        hint = f" ¿Quizas: {', '.join(sug)}?" if sug else ""
+        base["error"] = f"template '{name}' no existe en el paquete.{hint}"
+        return base
+    if err == "no_json":
+        base["error"] = f"el template '{name}' no tiene asset .json."
+        return base
+
+    graph = data.get("graph", {})
+    fmt = data.get("format", "")
+    nodes = graph.get("nodes") if isinstance(graph, dict) else None
+    n_nodes = len(nodes) if isinstance(nodes, list) else (
+        len(graph) if fmt == "api" and isinstance(graph, dict) else 0
+    )
+
+    out = {
+        "ok": True,
+        "name": name,
+        "format": fmt,
+        "class_types": data.get("class_types", []),
+        "has_subgraphs": data.get("has_subgraphs", False),
+        "n_nodes": n_nodes,
+        "graph": graph,
+        "api_workflow": {},
+        "api_error": "",
+        "bundle": data.get("bundle", ""),
+        "version": data.get("version", ""),
+        "assets": data.get("assets", []),
+        "error": "",
+    }
+
+    if to_api:
+        if fmt == "api":
+            out["api_workflow"] = graph
+        else:
+            out["api_workflow"], out["api_error"] = _convert_to_api(graph, server)
+
+    return out
+
+
+def _convert_to_api(graph: dict, server: str) -> tuple[dict, str]:
+    """Convierte un grafo UI a API format via comfyui_import_workflow_json del registry.
+
+    Requiere un servidor ComfyUI vivo para mapear widgets. Devuelve (workflow, "")
+    si tuvo exito o ({}, motivo) si fallo. No lanza.
+    """
+    try:
+        from comfyui_import_workflow_json import comfyui_import_workflow_json
+    except Exception as exc:  # noqa: BLE001
+        return {}, f"no se pudo importar comfyui_import_workflow_json: {exc}"
+
+    tmp = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w", suffix=".json", delete=False, encoding="utf-8"
+        ) as fh:
+            json.dump(graph, fh)
+            tmp = fh.name
+        res = comfyui_import_workflow_json(tmp, server=server)
+        if res.get("ok"):
+            return res.get("workflow", {}), ""
+        return {}, (
+            res.get("error", "conversion fallida")
+            + f" (requiere un servidor ComfyUI vivo en {server})"
+        )
+    except Exception as exc:  # noqa: BLE001
+        return {}, f"conversion to_api fallida: {exc}"
+    finally:
+        if tmp and os.path.exists(tmp):
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+
+
+if __name__ == "__main__":
+    import argparse
+
+    ap = argparse.ArgumentParser(description="Extrae el grafo de un template ComfyUI")
+    ap.add_argument("name", help="template_id (ver comfyui_list_templates)")
+    ap.add_argument("--comfyui-python", default=None)
+    ap.add_argument("--to-api", action="store_true")
+    ap.add_argument("--server", default="127.0.0.1:8188")
+    ap.add_argument("--full", action="store_true", help="incluye el grafo entero")
+    args = ap.parse_args()
+
+    res = comfyui_extract_template(
+        args.name,
+        args.comfyui_python,
+        to_api=args.to_api,
+        server=args.server,
+    )
+    if args.full or not res["ok"]:
+        print(json.dumps(res, indent=2, ensure_ascii=False))
+    else:
+        slim = {k: v for k, v in res.items() if k != "graph"}
+        slim["graph_keys"] = list(res["graph"].keys()) if isinstance(res["graph"], dict) else []
+        print(json.dumps(slim, indent=2, ensure_ascii=False))

python/functions/ml/comfyui_list_templates.md

@@ -0,0 +1,82 @@
+---
+name: comfyui_list_templates
+kind: function
+lang: py
+domain: ml
+version: "1.0.0"
+purity: impure
+signature: "def comfyui_list_templates(comfyui_python: str | None = None, bundle: str | None = None, name_filter: str | None = None, with_nodes: bool = True, workflows_only: bool = True, limit: int = 0) -> dict"
+description: "Lista los workflow templates oficiales del paquete pip comfyui-workflow-templates (los del menu 'Browse Templates' del frontend de ComfyUI). Devuelve nombre, bundle/categoria, path en disco, n_nodes y node_types (class_types reales, aplanando subgrafos y descartando los UUID de instancia). Localiza el interprete de ComfyUI y usa su API oficial via subprocess (el paquete vive en el venv de ComfyUI, no en el del registry). Impura: lee disco. Filtra entradas no-workflow (index*/localizacion) por defecto."
+tags: [comfyui, ml, templates, workflow, discovery]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: comfyui_python
+    desc: "Ruta al interprete python de ComfyUI con el paquete comfyui-workflow-templates instalado. None autodetecta (env COMFYUI_PYTHON, ~/ComfyUI/.venv/bin/python, ~/ComfyUI/venv/bin/python)."
+  - name: bundle
+    desc: "Filtra por bundle exacto: 'media-api', 'media-image', 'media-video' o 'media-other'. None = todos."
+  - name: name_filter
+    desc: "Subcadena (case-insensitive) que debe contener el nombre del template. None = sin filtro."
+  - name: with_nodes
+    desc: "True (default) incluye node_types en cada registro; False los omite (registros mas ligeros)."
+  - name: workflows_only
+    desc: "True (default) excluye entradas que no son grafos de workflow (ficheros index*/localizacion del paquete)."
+  - name: limit
+    desc: "Si > 0, trunca a los primeros N templates tras filtrar y ordenar por nombre."
+output: "dict {ok: bool, count: int, package_version: str, templates: list, error: str}. Cada template: {name, category, bundle, version, path, n_nodes, node_types, is_workflow}. Nunca lanza: paquete ausente o interprete no hallado -> ok=False con error legible que indica como instalar (pip install comfyui-workflow-templates)."
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/ml/comfyui_list_templates.py"
+---
+
+## Ejemplo
+
+```bash
+# Lanzable directo (muestra version del paquete + 15 primeros con sus node_types):
+./fn run comfyui_list_templates
+
+# Filtrado por bundle de imagen, sin abrir node_types, primeros 20:
+python/.venv/bin/python3 python/functions/ml/comfyui_list_templates.py \
+    --bundle media-image --no-nodes --limit 20
+```
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
+from ml.comfyui_list_templates import comfyui_list_templates
+
+res = comfyui_list_templates(name_filter="sdxl")
+print(res["count"], "templates SDXL")          # p.ej. 4
+for t in res["templates"]:
+    print(t["name"], t["n_nodes"], t["node_types"][:3])
+```
+
+## Cuando usarla
+
+Para descubrir que workflow templates oficiales trae ComfyUI sin abrir la UI:
+explorar el catalogo, filtrar por bundle/nombre, o saber que `node_types` usa cada
+template antes de extraerlo con `comfyui_extract_template`. Primer paso del flujo
+listar -> extraer -> (cargar en UI / convertir a API).
+
+## Gotchas
+
+- El paquete `comfyui-workflow-templates` vive en el venv de ComfyUI, NO en el del
+  registry. La funcion no lo importa: localiza el python de ComfyUI y corre su API
+  oficial en un subprocess. Si no encuentra ese interprete (o el paquete no esta
+  instalado) devuelve `ok=False` con un error que dice como instalarlo. No lanza.
+- Desde la 0.10.x el paquete es multi-bundle y ya NO expone una carpeta `templates/`
+  unica (la API antigua `get_templates_path()` lanza a proposito). Por eso se usa
+  `comfyui_workflow_templates_core` (`load_manifest`/`get_asset_path`).
+- `node_types` aplana los subgrafos de `definitions` y descarta los `type` que son
+  UUID (instancias de subgraph), para mostrar class_types reales (KSampler, CLIPLoader,
+  …) en vez de identificadores opacos. `n_nodes` cuenta solo los nodos top-level.
+- `workflows_only=True` (default) excluye ~16 entradas `index*` que son metadata de
+  localizacion del frontend, no grafos. Pasa `workflows_only=False` (o `--all` en CLI)
+  para verlas.
+- Impura: abre cada `.json` en disco (≈451 ficheros pequeños, ~0.2s). No toca red ni
+  arranca GPU.

python/functions/ml/comfyui_list_templates.py

@@ -0,0 +1,284 @@
+"""Lista los workflow templates oficiales que trae el paquete comfyui-workflow-templates.
+
+Funcion impura: lee disco (los .json de los templates instalados) ejecutando la
+API oficial del paquete dentro del interprete de ComfyUI.
+
+ComfyUI 0.26+ distribuye los templates oficiales (los del menu "Browse Templates"
+del frontend) en el paquete pip `comfyui-workflow-templates`, que desde la 0.10.x es
+un meta-paquete multi-bundle: ya NO expone una carpeta `templates/` unica, sino una
+API en `comfyui_workflow_templates_core` (`load_manifest`, `iter_templates`,
+`get_asset_path`). Cada template es un grafo de nodos en formato UI (nodes/links con
+posiciones), agrupado en uno de cuatro bundles: media-api, media-image, media-video,
+media-other.
+
+Como el paquete vive en el venv de ComfyUI (no en el del registry), esta funcion no
+lo importa directamente: localiza el interprete de ComfyUI y le pasa un script que usa
+la API oficial y vuelca el catalogo como JSON. Asi es robusta ante cambios de la
+estructura interna del paquete.
+"""
+import json
+import os
+import subprocess
+import sys
+
+
+# Script que corre DENTRO del python de ComfyUI. Usa la API oficial del paquete y
+# vuelca el catalogo (metadata + node_types por template) como una linea JSON.
+_DUMP_SCRIPT = r"""
+import json, sys, re
+try:
+    import comfyui_workflow_templates_core as core
+except Exception as exc:
+    print(json.dumps({"__err__": "import", "msg": str(exc)}))
+    sys.exit(0)
+
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+def _collect_types(graph):
+    # Recoge class_types reales: aplana los subgrafos de definitions y descarta los
+    # type que son UUID (instancias de subgraph, cuyo contenido real ya se incluye).
+    types = set()
+    if isinstance(graph, dict) and isinstance(graph.get("nodes"), list):
+        for n in graph["nodes"]:
+            if isinstance(n, dict) and n.get("type") and not _UUID_RE.match(str(n["type"])):
+                types.add(n["type"])
+        defs = graph.get("definitions")
+        if isinstance(defs, dict) and isinstance(defs.get("subgraphs"), list):
+            for sg in defs["subgraphs"]:
+                for n in (sg.get("nodes") or []) if isinstance(sg, dict) else []:
+                    if isinstance(n, dict) and n.get("type") and not _UUID_RE.match(str(n["type"])):
+                        types.add(n["type"])
+        return len(graph["nodes"]), sorted(types)
+    if isinstance(graph, dict):  # API format
+        for v in graph.values():
+            if isinstance(v, dict) and v.get("class_type"):
+                types.add(v["class_type"])
+        if types:
+            return len(graph), sorted(types)
+    return 0, []
+
+WITH_NODES = {with_nodes}
+m = core.load_manifest()
+try:
+    import importlib.metadata as _md
+    pkg_version = _md.version("comfyui-workflow-templates")
+except Exception:
+    pkg_version = ""
+
+out = []
+for tid, entry in m.templates.items():
+    json_asset = next(
+        (a.filename for a in entry.assets if a.filename.endswith(".json")), None
+    )
+    path = core.get_asset_path(tid, json_asset) if json_asset else ""
+    rec = {
+        "name": tid,
+        "bundle": entry.bundle,
+        "category": entry.bundle,
+        "version": entry.version,
+        "path": path,
+        "n_nodes": 0,
+        "node_types": [],
+    }
+    rec["is_workflow"] = False
+    if path:
+        try:
+            with open(path, encoding="utf-8") as fh:
+                graph = json.load(fh)
+            n_nodes, node_types = _collect_types(graph)
+            is_api = isinstance(graph, dict) and any(
+                isinstance(v, dict) and v.get("class_type") for v in graph.values()
+            )
+            rec["is_workflow"] = bool(
+                (isinstance(graph, dict) and isinstance(graph.get("nodes"), list) and graph["nodes"])
+                or is_api
+            )
+            rec["n_nodes"] = n_nodes
+            if WITH_NODES:
+                rec["node_types"] = node_types
+        except Exception:
+            pass
+    out.append(rec)
+
+print(json.dumps({"package_version": pkg_version, "templates": out}))
+"""
+
+
+def _find_comfyui_python(explicit: str | None) -> str | None:
+    """Devuelve la ruta a un interprete de ComfyUI que tenga el paquete instalado.
+
+    Orden de busqueda: argumento explicito -> env COMFYUI_PYTHON -> candidatos
+    habituales (~/ComfyUI/.venv, ~/ComfyUI/venv) -> el python actual. Devuelve None
+    si ninguno existe en disco.
+    """
+    candidates = []
+    if explicit:
+        candidates.append(os.path.expanduser(explicit))
+    env = os.environ.get("COMFYUI_PYTHON")
+    if env:
+        candidates.append(os.path.expanduser(env))
+    candidates += [
+        os.path.expanduser("~/ComfyUI/.venv/bin/python"),
+        os.path.expanduser("~/ComfyUI/venv/bin/python"),
+        os.path.expanduser("~/comfyui/.venv/bin/python"),
+        sys.executable,
+    ]
+    for c in candidates:
+        if c and os.path.isfile(c):
+            return c
+    return None
+
+
+def comfyui_list_templates(
+    comfyui_python: str | None = None,
+    bundle: str | None = None,
+    name_filter: str | None = None,
+    with_nodes: bool = True,
+    workflows_only: bool = True,
+    limit: int = 0,
+) -> dict:
+    """Lista los templates oficiales de ComfyUI con su grafo de nodos.
+
+    Args:
+        comfyui_python: ruta al interprete python de ComfyUI que tiene instalado
+            el paquete comfyui-workflow-templates. Si None, se autodetecta (env
+            COMFYUI_PYTHON o ~/ComfyUI/.venv/bin/python).
+        bundle: si se da, filtra por bundle exacto ("media-api", "media-image",
+            "media-video", "media-other").
+        name_filter: si se da, filtra a templates cuyo nombre contenga esta
+            subcadena (case-insensitive).
+        with_nodes: si True (default) incluye node_types en cada registro. Si
+            False los omite (registros mas ligeros).
+        workflows_only: si True (default) excluye entradas que no son grafos de
+            workflow (ficheros index*/localizacion del paquete).
+        limit: si > 0, trunca la lista a los primeros N tras filtrar.
+
+    Returns:
+        dict {ok, count, package_version, templates, error}:
+          - templates: lista de {name, category, bundle, version, path, n_nodes,
+            node_types} ordenada por name.
+          - count: numero de templates devueltos (tras filtros y limit).
+        Nunca lanza: cualquier fallo (paquete ausente, interprete no hallado)
+        devuelve ok=False con un error legible.
+    """
+    py = _find_comfyui_python(comfyui_python)
+    if not py:
+        return {
+            "ok": False,
+            "count": 0,
+            "package_version": "",
+            "templates": [],
+            "error": (
+                "no se encontro un interprete de ComfyUI. Pasa comfyui_python=... "
+                "o define COMFYUI_PYTHON. El paquete se instala con: "
+                "pip install comfyui-workflow-templates"
+            ),
+        }
+
+    script = _DUMP_SCRIPT.replace("{with_nodes}", "True" if with_nodes else "False")
+    try:
+        proc = subprocess.run(
+            [py, "-c", script],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+    except Exception as exc:  # noqa: BLE001
+        return {
+            "ok": False,
+            "count": 0,
+            "package_version": "",
+            "templates": [],
+            "error": f"fallo al ejecutar el interprete de ComfyUI ({py}): {exc}",
+        }
+
+    if proc.returncode != 0:
+        return {
+            "ok": False,
+            "count": 0,
+            "package_version": "",
+            "templates": [],
+            "error": f"el interprete de ComfyUI fallo: {proc.stderr.strip()[:500]}",
+        }
+
+    try:
+        data = json.loads(proc.stdout.strip().splitlines()[-1])
+    except Exception as exc:  # noqa: BLE001
+        return {
+            "ok": False,
+            "count": 0,
+            "package_version": "",
+            "templates": [],
+            "error": f"salida no parseable del interprete de ComfyUI: {exc}",
+        }
+
+    if data.get("__err__") == "import":
+        return {
+            "ok": False,
+            "count": 0,
+            "package_version": "",
+            "templates": [],
+            "error": (
+                "el paquete comfyui-workflow-templates no esta instalado en "
+                f"{py} ({data.get('msg', '')}). Instalalo con: "
+                "pip install comfyui-workflow-templates"
+            ),
+        }
+
+    templates = data.get("templates", [])
+    if workflows_only:
+        templates = [t for t in templates if t.get("is_workflow")]
+    if bundle:
+        templates = [t for t in templates if t.get("bundle") == bundle]
+    if name_filter:
+        nf = name_filter.lower()
+        templates = [t for t in templates if nf in t.get("name", "").lower()]
+    templates.sort(key=lambda t: t.get("name", ""))
+    if limit and limit > 0:
+        templates = templates[:limit]
+
+    return {
+        "ok": True,
+        "count": len(templates),
+        "package_version": data.get("package_version", ""),
+        "templates": templates,
+        "error": "",
+    }
+
+
+if __name__ == "__main__":
+    import argparse
+
+    ap = argparse.ArgumentParser(description="Lista templates oficiales de ComfyUI")
+    ap.add_argument("--comfyui-python", default=None)
+    ap.add_argument("--bundle", default=None)
+    ap.add_argument("--name-filter", default=None)
+    ap.add_argument("--no-nodes", action="store_true", help="omite node_types")
+    ap.add_argument("--all", action="store_true", help="incluye entradas no-workflow (index*)")
+    ap.add_argument("--limit", type=int, default=0)
+    ap.add_argument("--full", action="store_true", help="dump completo (todos los node_types)")
+    args = ap.parse_args()
+
+    res = comfyui_list_templates(
+        args.comfyui_python,
+        bundle=args.bundle,
+        name_filter=args.name_filter,
+        with_nodes=not args.no_nodes,
+        workflows_only=not args.all,
+        limit=args.limit,
+    )
+    if args.full or not res["ok"]:
+        print(json.dumps(res, indent=2, ensure_ascii=False))
+    else:
+        print(
+            json.dumps(
+                {
+                    "ok": res["ok"],
+                    "count": res["count"],
+                    "package_version": res["package_version"],
+                    "sample": res["templates"][:15],
+                },
+                indent=2,
+                ensure_ascii=False,
+            )
+        )

python/functions/ml/tests/test_comfyui_build_flux_workflow.py

@@ -3,8 +3,6 @@
 import os
 import sys
 
-import pytest
-
 sys.path.insert(0, os.path.dirname(__file__))
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", ".."))
 
@@ -12,54 +10,35 @@ from ml.comfyui_build_flux_workflow import comfyui_build_flux_workflow
 from _comfyui_wf_assert import assert_api_format, class_types, node_by_ct
 
 
-_BASE_CTS = {
-    "UNETLoader",
-    "DualCLIPLoader",
-    "VAELoader",
-    "EmptyLatentImage",
-    "CLIPTextEncode",
-    "RandomNoise",
-    "KSamplerSelect",
-    "BasicScheduler",
-    "BasicGuider",
-    "SamplerCustomAdvanced",
-    "VAEDecode",
-    "SaveImage",
-}
-
-
-def test_schnell_class_types_sin_fluxguidance():
-    wf = comfyui_build_flux_workflow("POS", variant="schnell")
+def test_estructura_y_class_types():
+    wf = comfyui_build_flux_workflow("POS")
     assert_api_format(wf)
-    # schnell usa el camino custom-advanced y NO incluye FluxGuidance.
-    assert class_types(wf) == _BASE_CTS
-    # BasicGuider consume el CLIPTextEncode positivo directo.
-    assert node_by_ct(wf, "BasicGuider")["inputs"]["conditioning"] == ["6", 0]
-
-
-def test_dev_class_types_con_fluxguidance():
-    wf = comfyui_build_flux_workflow("POS", variant="dev", guidance=2.5)
-    assert_api_format(wf)
-    assert class_types(wf) == _BASE_CTS | {"FluxGuidance"}
-    fg = node_by_ct(wf, "FluxGuidance")["inputs"]
-    assert fg["guidance"] == 2.5
-    assert fg["conditioning"] == ["6", 0]  # FluxGuidance aplica sobre el positivo
-    # BasicGuider consume la salida de FluxGuidance, no el CLIPTextEncode directo.
-    assert node_by_ct(wf, "BasicGuider")["inputs"]["conditioning"] == ["21", 0]
+    assert class_types(wf) == {
+        "UNETLoader",
+        "DualCLIPLoader",
+        "VAELoader",
+        "CLIPTextEncode",
+        "FluxGuidance",
+        "EmptySD3LatentImage",
+        "KSampler",
+        "VAEDecode",
+        "SaveImage",
+    }
 
 
 def test_loaders_separados_de_flux():
     # Flux carga UNET + dos text encoders + VAE por separado (no checkpoint unico).
     wf = comfyui_build_flux_workflow(
         "POS",
-        variant="schnell",
-        clip_l_name="clip_l.safetensors",
-        t5xxl_name="t5xxl_fp8_e4m3fn_scaled.safetensors",
-        vae_name="ae.safetensors",
+        unet="IMG_flux1-schnell-fp8-e4m3fn.safetensors",
+        clip_l="clip_l.safetensors",
+        t5xxl="t5xxl_fp8_e4m3fn_scaled.safetensors",
+        vae="ae.safetensors",
+        weight_dtype="fp8_e4m3fn",
     )
     unet = node_by_ct(wf, "UNETLoader")["inputs"]
     assert unet["unet_name"] == "IMG_flux1-schnell-fp8-e4m3fn.safetensors"
-    assert unet["weight_dtype"] == "default"
+    assert unet["weight_dtype"] == "fp8_e4m3fn"
     dual = node_by_ct(wf, "DualCLIPLoader")["inputs"]
     assert dual["type"] == "flux"
     assert dual["clip_name1"] == "t5xxl_fp8_e4m3fn_scaled.safetensors"
@@ -67,36 +46,25 @@ def test_loaders_separados_de_flux():
     assert node_by_ct(wf, "VAELoader")["inputs"]["vae_name"] == "ae.safetensors"
 
 
-def test_unet_default_por_variante():
-    schnell = comfyui_build_flux_workflow("POS", variant="schnell")
-    dev = comfyui_build_flux_workflow("POS", variant="dev")
-    assert (
-        node_by_ct(schnell, "UNETLoader")["inputs"]["unet_name"]
-        == "IMG_flux1-schnell-fp8-e4m3fn.safetensors"
-    )
-    assert (
-        node_by_ct(dev, "UNETLoader")["inputs"]["unet_name"]
-        == "IMG_flux1-dev-fp8-e4m3fn.safetensors"
-    )
-
-
-def test_steps_default_por_variante():
-    schnell = comfyui_build_flux_workflow("POS", variant="schnell")
-    dev = comfyui_build_flux_workflow("POS", variant="dev")
-    assert node_by_ct(schnell, "BasicScheduler")["inputs"]["steps"] == 4
-    assert node_by_ct(dev, "BasicScheduler")["inputs"]["steps"] == 20
-    # steps explicito gana al default.
-    custom = comfyui_build_flux_workflow("POS", variant="schnell", steps=6)
-    assert node_by_ct(custom, "BasicScheduler")["inputs"]["steps"] == 6
+def test_guidance_y_cfg_de_flux():
+    # La guia va por FluxGuidance; el cfg del KSampler se fija a 1.0 (schnell).
+    wf = comfyui_build_flux_workflow("POS", guidance=2.5)
+    assert node_by_ct(wf, "FluxGuidance")["inputs"]["guidance"] == 2.5
+    ks = node_by_ct(wf, "KSampler")["inputs"]
+    assert ks["cfg"] == 1.0
+    # KSampler positive consume la salida de FluxGuidance, no la del CLIPTextEncode directo.
+    assert ks["positive"] == ["13", 0]
 
 
 def test_params_se_reflejan_en_los_nodos():
-    wf = comfyui_build_flux_workflow(
-        "POS", variant="schnell", width=768, height=512, seed=123
-    )
-    assert node_by_ct(wf, "RandomNoise")["inputs"]["noise_seed"] == 123
-    lat = node_by_ct(wf, "EmptyLatentImage")["inputs"]
+    wf = comfyui_build_flux_workflow("POS", width=768, height=512, steps=8, seed=123)
+    ks = node_by_ct(wf, "KSampler")["inputs"]
+    assert ks["seed"] == 123
+    assert ks["steps"] == 8
+    lat = node_by_ct(wf, "EmptySD3LatentImage")["inputs"]
     assert lat["width"] == 768 and lat["height"] == 512
+    pos = node_by_ct(wf, "FluxGuidance")["inputs"]["conditioning"]
+    assert pos == ["6", 0]  # FluxGuidance aplica sobre el CLIPTextEncode positivo
 
 
 def test_filename_prefix_en_saveimage():
@@ -104,36 +72,8 @@ def test_filename_prefix_en_saveimage():
     assert node_by_ct(wf, "SaveImage")["inputs"]["filename_prefix"] == "demo_flux"
 
 
-def test_variant_invalido_lanza_valueerror():
-    with pytest.raises(ValueError):
-        comfyui_build_flux_workflow("POS", variant="turbo")
-
-
-def test_available_valida_modelos_faltantes():
-    # Si se pasa 'available' y un modelo elegido no esta, lanza FileNotFoundError
-    # con el nombre que falta (error path: no crashea opaco).
-    available = {
-        "unet": ["otro_modelo.safetensors"],  # el schnell por defecto NO esta
-        "clip": ["clip_l.safetensors", "t5xxl_fp8_e4m3fn_scaled.safetensors"],
-        "vae": ["ae.safetensors"],
-    }
-    with pytest.raises(FileNotFoundError) as exc:
-        comfyui_build_flux_workflow("POS", variant="schnell", available=available)
-    assert "IMG_flux1-schnell-fp8-e4m3fn.safetensors" in str(exc.value)
-
-
-def test_available_ok_no_lanza():
-    available = {
-        "unet": ["IMG_flux1-schnell-fp8-e4m3fn.safetensors"],
-        "clip": ["clip_l.safetensors", "t5xxl_fp8_e4m3fn_scaled.safetensors"],
-        "vae": ["ae.safetensors"],
-    }
-    wf = comfyui_build_flux_workflow("POS", variant="schnell", available=available)
-    assert_api_format(wf)
-
-
 def test_determinista():
     # Builder puro: misma entrada -> mismo dict (sin red, seed fijo, sin estado).
-    a = comfyui_build_flux_workflow("POS", variant="dev", seed=123)
-    b = comfyui_build_flux_workflow("POS", variant="dev", seed=123)
+    a = comfyui_build_flux_workflow("POS", seed=123)
+    b = comfyui_build_flux_workflow("POS", seed=123)
     assert a == b