feat(ml): núcleo subsistema comfyui-skill + ask_llm_vision

Grupo nuevo comfyui-skill: recetas versionadas de generación ComfyUI que
compilan a un workflow cambiando solo el subject.

- comfyui_build_skill_workflow (pura): receta -> workflow API format,
  despacha base (txt2img/flux/sdxl_refiner), sustituye {subject}+triggers,
  encadena loras e inject blocks (facedetailer, hires_fix). SkillWorkflowError tipada.
- comfyui_inject_hires_fix (pura): inyecta 2ª pasada UltimateSDUpscale sobre dict.
- comfyui_save/load/list_skill (impuras): CRUD de la librería en disco con
  versionado por snapshots, round-trip idéntico, filtro NSFW.
- ask_llm_vision (core, claude-direct): pregunta multimodal imagen+texto via
  API directa Anthropic, para puntuar generaciones.
- Página madre docs/capabilities/comfyui-skill.md con schema canónico de recipe.json.

Tests offline: 11 verdes (6 builder + 5 inject_hires_fix). Sin GPU.
This commit is contained in:
agent
2026-06-24 14:35:46 +02:00
parent e8a66f0dad
commit 70d541fca9
15 changed files with 1666 additions and 0 deletions
+72
View File
@@ -0,0 +1,72 @@
---
name: comfyui_save_skill
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: impure
signature: "def comfyui_save_skill(recipe: dict, *, library_dir: str = None) -> dict"
description: "Persiste una receta de skill ComfyUI (schema comfyui-skill) en la libreria de disco: valida el schema minimo y escribe <library_dir>/<slug>/recipe.json + un snapshot inmutable versions/vN.json (N incremental) + bitacora growth_log.jsonl + regenera INDEX.md. No muta la receta (round-trip identico con comfyui_load_skill). library_dir default ~/ComfyUI/skills_library. Devuelve dict {ok, slug, path, version_file, n_versions, error}; nunca lanza."
error_type: error_go_core
tags: [comfyui, comfyui-skill, ml, skill, library, persistence]
uses_functions: []
uses_types: []
params:
- name: recipe
desc: "Dict de la receta (schema comfyui-skill). Requiere al menos slug, base_workflow y version (strings no vacios). No se muta."
- name: library_dir
desc: "Raiz de la libreria en disco. Default ~/ComfyUI/skills_library. keyword-only."
output: "dict {ok, slug, path, recipe_path, version_file, n_versions, error}. En error de validacion o escritura ok=False y error describe la causa."
file_path: python/functions/ml/comfyui_save_skill.py
---
# comfyui_save_skill
Escribe una receta de skill en la libreria de disco con versionado por snapshots. Parte del CRUD
del grupo `comfyui-skill` ([`comfyui_load_skill`](comfyui_load_skill.md),
[`comfyui_list_skills`](comfyui_list_skills.md)).
## Ejemplo
```python
import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from ml.comfyui_save_skill import comfyui_save_skill
recipe = {
"schema_version": 1, "slug": "portrait_cinematic_sdxl", "version": "1.0.0",
"title": "Retrato cinematográfico SDXL", "base_workflow": "txt2img",
"checkpoint": "juggernaut_xl_v11.safetensors",
"params": {"steps": 30, "cfg": 5.5, "sampler_name": "dpmpp_2m", "scheduler": "karras"},
"prompt_scaffold": {"positive": "cinematic portrait of {subject}", "negative": "blurry",
"trigger_words": []},
"provenance": {"source": "manual", "nsfw": False},
}
res = comfyui_save_skill(recipe, library_dir="/tmp/skills_demo")
# {'ok': True, 'slug': 'portrait_cinematic_sdxl', 'n_versions': 1,
# 'version_file': '/tmp/skills_demo/portrait_cinematic_sdxl/versions/v1.json', ...}
```
O directo: `./fn run comfyui_save_skill` (guarda una skill demo en /tmp/skills_demo).
## Cuando usarla
- Cuando crees o actualices una receta de skill y quieras persistirla con versionado. Cada save
escribe un snapshot nuevo `versions/vN.json` además de actualizar `recipe.json`, así que el
historial queda intacto.
- Tras ajustar params/loras/blocks de una skill que iterabas: guárdala para reproducirla luego
con `comfyui_load_skill` + `comfyui_build_skill_workflow`.
## Gotchas
- **No muta la receta**: lo escrito en `recipe.json` es idéntico al dict de entrada (garantiza el
round-trip con `comfyui_load_skill`). No rellena defaults ni reordena.
- **Validación mínima**: exige `slug`, `base_workflow` y `version` (strings no vacíos); el `slug`
no puede contener separadores de ruta ni empezar por `.`. No valida la semántica completa del
workflow (eso lo hace `comfyui_build_skill_workflow` al compilar).
- **`n_versions` cuenta los snapshots existentes + 1**: guardar la misma skill dos veces crea
`v1.json` y `v2.json`; `recipe.json` siempre apunta a la última.
- **No lanza excepción**: errores (validación, permisos de escritura) salen como `{ok: False, error: ...}`.
- **Escribe bajo `~/ComfyUI/skills_library` por defecto** (carpeta de metadata, no toca el venv
ni los modelos). Para tests/uso aislado pasa un `library_dir` propio.