# ComfyUI Styles — presets y catálogo de estilo

Tag: `comfyui-styles` (+ `gamedev-2d` para los dos presets gamedev). Sub-grupo de
[`comfyui`](comfyui.md) que añade una **capa de estilo reutilizable** sobre los builders de
workflow: en vez de repetir a mano los mismos modificadores de cámara/iluminación/render en cada
prompt, el estilo se trata como un dato curado y reusable.

Dos vertientes complementarias:

- **Catálogo WAS** (`comfyui-styles`): ~190 estilos curados en el formato exacto del selector WAS de
  ComfyUI (*Prompt Styles Selector* / *Prompt Multiple Styles Selector*), generación de estilos
  nuevos por LLM, y fusión segura sobre el `styles.json` del usuario.
- **Style presets gamedev** (`gamedev-2d`): recetas que empaquetan como datos puros el *look* de un
  juego entero (prefijo/sufijo de prompt, checkpoint, LoRA, negative, tamaño, post-proceso) y se
  traducen a los kwargs que consume un builder de sujeto del grupo [`gamedev-2d`](gamedev-2d.md).

Filtro MCP: `mcp__registry__fn_search query="" tag="comfyui-styles"` (catálogo WAS) y
`mcp__registry__fn_search query="style preset" tag="gamedev-2d"` (presets gamedev).

## Funciones del grupo

### Catálogo WAS — dominio `ml` (tag `comfyui-styles`)

| ID | Firma corta | Qué hace |
|---|---|---|
| [comfyui_curated_styles_catalog_py_ml](../../python/functions/ml/comfyui_curated_styles_catalog.md) | `curated_styles_catalog(category=None) -> dict` | Catálogo curado (~190 estilos) en el formato exacto `{nombre: {prompt, negative_prompt}}` que consume el selector WAS. Cada `prompt` son modificadores de estilo potentes (cámara, lente, iluminación, render engine, medio artístico, paleta, mood), no descripciones de escena. Filtra por `category`. **Pura**. |
| [comfyui_generate_styles_llm_py_ml](../../python/functions/ml/comfyui_generate_styles_llm.md) | `generate_styles_llm(category, n=8, prefix='', avoid=None, model='claude-haiku-4-5-20251001') -> dict` | Genera N estilos de una categoría temática usando `ask_llm` (grupo claude-direct, API directa, arranque 0), en el mismo formato `{nombre: {prompt, negative_prompt}}`. `avoid` evita duplicar nombres ya existentes. **Impura** (LLM). |
| [comfyui_append_styles_py_ml](../../python/functions/ml/comfyui_append_styles.md) | `append_styles(new_styles, styles_path=DEFAULT_STYLES_PATH, overwrite=False, backup=True, dry_run=False) -> dict` | Fusiona (merge + dedup por nombre) un dict de estilos sobre el `styles.json` del selector WAS de forma SEGURA y NO destructiva: preserva todos los existentes (ganan salvo `overwrite=True`), hace backup con timestamp antes de escribir. `dry_run=True` previsualiza sin tocar disco. **Impura** (I/O disco). |

### Style presets gamedev — dominio `ml` (tag `gamedev-2d`)

| ID | Firma corta | Qué hace |
|---|---|---|
| [comfyui_get_gamedev_style_preset_py_ml](../../python/functions/ml/comfyui_get_gamedev_style_preset.md) | `get_gamedev_style_preset(name=None) -> dict` | Devuelve la receta de un *style preset* gamedev curado (`gameboy`, `ghibli`, `pixel-art-retro`) o el catálogo de nombres si `name=None`. Un preset empaqueta como DATOS puros el look de un juego entero: `subject_prefix`/`suffix`, `style`, `negative`, checkpoint recomendado, LoRA + strength, `size`, `transparent`, post-proceso. **Pura**. |
| [comfyui_apply_style_preset_py_ml](../../python/functions/ml/comfyui_apply_style_preset.md) | `apply_style_preset(preset, subject, *, style=None, negative=None) -> dict` | Traduce un *style preset* gamedev (de `get_gamedev_style_preset`) + un `subject` del usuario a lo que necesita un builder de sujeto del grupo gamedev-2d: el subject combinado con el prefijo/sufijo del estilo y los kwargs comunes (`style`, `checkpoint`, `lora`, `lora_strength`, `negative`, resolución) listos para `**spread`. `style`/`negative` permiten override puntual. **Pura**. |

## Ejemplo canónico — generar un estilo, fusionarlo y aplicarlo

Dos flujos típicos: (1) ampliar el catálogo del selector WAS, y (2) usar un preset gamedev para
generar un asset con look consistente.

### A) Ampliar el catálogo WAS con estilos nuevos por LLM

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

# 1. Pedir 6 estilos de una categoría. Devuelve el dict {nombre: {prompt, negative_prompt}}
#    directo (best-effort: {} si el LLM falla).
nuevos = comfyui_generate_styles_llm("film noir cinematic", n=6, prefix="noir-")

# 2. Previsualizar la fusión (no escribe), luego aplicar con backup.
if nuevos:
    print(comfyui_append_styles(nuevos, dry_run=True)["total_after"])   # nº tras fusionar, sin tocar disco
    res = comfyui_append_styles(nuevos)                                  # backup + merge + dedup + escritura
    print(res["total_before"], "->", res["total_after"], "añadidos:", len(res["added"]))
```

### B) Aplicar un style preset gamedev a un sujeto

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

preset = comfyui_get_gamedev_style_preset("gameboy")     # receta pura del look Game Boy
ap = comfyui_apply_style_preset(preset, "a wizard casting a spell")
# ap = {subject, builder_kwargs, size, transparent, post, ...} listo para un builder gamedev-2d:
wf = comfyui_build_enemy_creature_workflow(
    ap["subject"], size=ap["size"], transparent=ap["transparent"], **ap["builder_kwargs"]
)
```

El catálogo curado completo se consulta sin red (devuelve el dict plano directo):

```python
from ml.comfyui_curated_styles_catalog import comfyui_curated_styles_catalog
print(comfyui_curated_styles_catalog("__categories__"))  # {'categories': {...}, 'total': 190}
todos = comfyui_curated_styles_catalog()                  # dict {nombre: {prompt, negative_prompt}}
print(len(todos), list(todos)[:5])
```

## Fronteras

- **No genera imágenes**: este sub-grupo produce y gestiona DATOS de estilo (dicts de prompt /
  negative, presets). Generar el asset es trabajo de los builders del grupo [`comfyui`](comfyui.md)
  y [`gamedev-2d`](gamedev-2d.md), o de los pipelines oneshot (p.ej.
  `comfyui_generate_styled_asset_oneshot_py_pipelines`, que compone un preset + un builder + submit).
- **El catálogo WAS asume el custom node WAS instalado**: `append_styles` escribe sobre el
  `styles.json` que lee el selector WAS en la UI. Sin ese node, el catálogo sigue siendo usable como
  dict de modificadores, pero el selector no aparecerá en el grafo.
- **Los dos presets gamedev (`get`/`apply`) llevan tag `gamedev-2d`**, no `comfyui-styles`: son la
  vía de estilo para los builders de assets de juego, no para el selector WAS genérico. Se listan
  aquí por afinidad de capacidad (estilo reutilizable).
- **Formato exacto**: el dict de estilos es `{nombre: {prompt, negative_prompt}}`. Los prompts son
  modificadores (cámara/lente/luz/render/medio/paleta/mood), no descripciones de escena — la escena
  la pone el `subject` del usuario.