feat(ml): mixer de capacidades comfyui (compose + generate_mixed_oneshot + inject controlnet/ipadapter)

Mezclador del grupo comfyui-skill que promueve a una sola llamada la secuencia
base -> compose -> submit -> wait -> fetch -> judge (issue 0087):

- comfyui_compose_capabilities_py_ml (PURA): aplica en orden las capacidades
  activadas (loras, controlnet, ipadapter, facedetailer, hires) sobre un
  workflow base, sin mutar la entrada.
- comfyui_generate_mixed_oneshot_py_pipelines: one-shot que resuelve el base
  (skill/txt2img/dict), compone, encola, espera, descarga el PNG y lo puntua
  con el panel comfyui-judge.
- comfyui_inject_controlnet_py_ml, comfyui_inject_ipadapter_py_ml: inyectores
  encadenables que consume el compose.
- Tests (24 passed) + pagina madre docs/capabilities/comfyui-skill.md.

Prueba real en GPU: txt2img dreamshaper_8 + 2 LoRAs (3d_render_redmond +
detail_tweaker) + FaceDetailer -> imagen 512x512 en ~24s, juez verdict 'good'
(score 4.69, votos aesthetic+clip good; voto llm degradado por rate-limit 429).

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

python/functions/ml/comfyui_inject_ipadapter.md

@@ -0,0 +1,91 @@
+---
+name: comfyui_inject_ipadapter
+kind: function
+lang: py
+domain: ml
+version: "1.0.0"
+purity: pure
+signature: "def comfyui_inject_ipadapter(workflow: dict, ref_image: str, *, mode: str = \"style\", weight: float = 0.8, preset: str | None = None, weight_type: str | None = None, start_at: float = 0.0, end_at: float = 1.0, weight_faceidv2: float = 1.0, lora_strength: float = 0.6, combine_embeds: str = \"concat\", embeds_scaling: str = \"V only\", provider: str = \"CPU\", model_node: str | None = None) -> dict"
+description: "Inyecta una rama IPAdapter (LoadImage + UnifiedLoader + IPAdapter, modo style o faceid) en un workflow ComfyUI ya construido (API format), repuntando el KSampler.model al MODEL condicionado por una imagen de referencia. La fuente del MODEL es la que hoy alimenta el KSampler (tras las LoRAs, no el checkpoint crudo). Version ENCADENABLE-sobre-dict del builder comfyui_build_ipadapter_workflow; reutiliza sus defaults de preset/weight_type. Pensada para componerse con inject_lora/inject_controlnet/inject_hires_fix. Pura: no muta el dict de entrada."
+tags: [comfyui, comfyui-skill, ml, ipadapter, faceid, stable-diffusion, workflow]
+uses_functions: [comfyui_build_ipadapter_workflow_py_ml]
+uses_types: []
+returns: []
+returns_optional: false
+error_type: ""
+imports: []
+params:
+  - name: workflow
+    desc: "dict en API format (ej. salida de comfyui_build_txt2img_workflow, posiblemente con LoRAs). No se muta; se devuelve una copia."
+  - name: ref_image
+    desc: "Nombre del archivo de imagen de referencia en input/ del servidor. En faceid debe contener una cara nitida; en style es la imagen de estilo. No puede estar vacio (raise ValueError)."
+  - name: mode
+    desc: "'style' (transfiere estilo/composicion) o 'faceid' (rostro consistente via insightface + FaceID). keyword-only."
+  - name: weight
+    desc: "Peso de la influencia IPAdapter (0..1+). 0.8 buen punto de partida. keyword-only."
+  - name: preset
+    desc: "Preset del UnifiedLoader. None = default del modo ('STANDARD (medium strength)' style, 'FACEID PLUS V2' faceid). keyword-only."
+  - name: weight_type
+    desc: "Tipo de ponderacion del nodo IPAdapter/FaceID. None = default del modo ('standard' style, 'linear' faceid). keyword-only."
+  - name: start_at
+    desc: "Fraccion del sampling donde empieza a aplicar IPAdapter (0..1). keyword-only."
+  - name: end_at
+    desc: "Fraccion del sampling donde deja de aplicar (0..1). keyword-only."
+  - name: weight_faceidv2
+    desc: "Peso del embedding FaceID v2 (solo mode='faceid'). keyword-only."
+  - name: lora_strength
+    desc: "Fuerza de la LoRA FaceID que carga el UnifiedLoaderFaceID (solo faceid). keyword-only."
+  - name: combine_embeds
+    desc: "Como combinar embeddings si hay varias caras ('concat'|'add'|...). Solo faceid. keyword-only."
+  - name: embeds_scaling
+    desc: "Escalado de embeddings ('V only'|'K+V'|...). Solo faceid. keyword-only."
+  - name: provider
+    desc: "Backend de insightface ('CPU'|'CUDA'|...). CPU por defecto para no competir por VRAM. Solo faceid. keyword-only."
+  - name: model_node
+    desc: "node_id cuya salida MODEL (slot 0) alimentara la rama IPAdapter. None = detecta la fuente del KSampler.model (CheckpointLoader como fallback). keyword-only."
+output: "copia del workflow con LoadImage + (UnifiedLoader|UnifiedLoaderFaceID) + (IPAdapter|IPAdapterFaceID) insertados y el KSampler.model repuntado a la salida MODEL de la rama IPAdapter. node_ids = max id numerico + 1/2/3."
+tested: true
+tests: ["mode style inyecta IPAdapterUnifiedLoader + IPAdapter y repunta KSampler.model", "mode faceid inyecta IPAdapterUnifiedLoaderFaceID + IPAdapterFaceID", "la rama toma el MODEL actual del KSampler (tras loras, no el checkpoint)", "respeta weight/preset/weight_type", "no muta el dict de entrada (pureza)", "mode invalido lanza ValueError", "ref_image vacio lanza ValueError", "api format valido"]
+test_file_path: "python/functions/ml/tests/test_comfyui_inject_ipadapter.py"
+file_path: "python/functions/ml/comfyui_inject_ipadapter.py"
+---
+
+## Ejemplo
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
+from ml.comfyui_build_txt2img_workflow import comfyui_build_txt2img_workflow
+from ml.comfyui_inject_multi_lora import comfyui_inject_multi_lora
+from ml.comfyui_inject_ipadapter import comfyui_inject_ipadapter
+
+base = comfyui_build_txt2img_workflow("dreamshaper_8.safetensors", "portrait of a knight")
+wf = comfyui_inject_multi_lora(base, [{"name": "detail_tweaker_sd15.safetensors", "strength_model": 0.5}])
+wf = comfyui_inject_ipadapter(wf, "hero_face.png", mode="faceid", weight=0.9)
+# KSampler.model viene de IPAdapterFaceID(model=ultimo LoraLoader, image=hero_face)
+```
+
+## Cuando usarla
+
+Cuando quieras condicionar un workflow txt2img ya construido con una **imagen de
+referencia** (estilo en `style`, rostro consistente en `faceid`) encadenando
+sobre el mismo dict que las LoRAs, sin reconstruir el grafo. Es la pieza
+IPAdapter del mixer `comfyui_compose_capabilities`. Para un workflow IPAdapter
+aislado desde cero usa `comfyui_build_ipadapter_workflow`.
+
+## Gotchas
+
+- Pura: no muta el `workflow` de entrada y NO valida que los modelos IPAdapter
+  esten instalados. La imagen de referencia debe estar subida al `input/` del
+  servidor ANTES de submit.
+- **ref_image obligatorio** y **mode in {style, faceid}**: ambos validados con
+  `ValueError`. Es el error path tipico al activar la capacidad sin referencia.
+- **Compatibilidad de checkpoint**: usa modelos IPAdapter SD1.5 con checkpoints
+  SD1.5 (dreamshaper_8) y SDXL con SDXL. Mezclar familias da un error de shape en
+  ejecucion.
+- `faceid` carga insightface (provider CPU por defecto) + un FaceID .bin + su
+  LoRA: es la rama mas pesada. En 8GB lowvram funciona pero apilarla con
+  ControlNet + hires + facedetailer a la vez puede dar OOM — baja resolucion o
+  desactiva capacidades.
+- Se aplica DESPUES de las LoRAs (toma el MODEL actual del KSampler), que es el
+  orden correcto del mixer.