---
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: true
tests:
  - "_find_comfyui_python: interprete existente se devuelve tal cual"
  - "_find_comfyui_python: ruta inexistente cae al fallback (sys.executable)"
  - "sin el paquete instalado -> ok=False con error que menciona comfyui-workflow-templates"
  - "el dict de retorno conserva todas sus claves aun en fallo"
  - "golden (skip si no hay ComfyUI con el paquete): catalogo no vacio, cada template con name+bundle"
  - "golden (skip si no hay ComfyUI con el paquete): bundle inexistente filtra a lista vacia con ok=True"
test_file_path: "python/functions/ml/tests/test_comfyui_list_templates.py"
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.
