chore: avance acumulado de sesiones previas (reorg dev/issues + ajustes)

Reorganizacion de dev/issues en subcarpetas (completed/, cpp/, gamedev/, kanban/, trading/, imagegen/, matrix/) y cambios acumulados en cmd/fn/pyrunner, .claude/commands y settings. Trabajo de otro LLM/sesion, commiteado a peticion del usuario para desbloquear el working tree. Excluido logs/ardour_mcp_server.log (ruido).
2026-06-30 14:43:51 +02:00
parent 5501507588
commit a3f75d61ec
125 changed files with 421 additions and 203 deletions
@@ -0,0 +1,101 @@
+---
+id: "0083"
+title: "imagegen — notebook 02 validacion cruzada diffusers vs sdcpp_python"
+status: pendiente
+type: feature
+domain:
+  - imagegen
+scope: multi-app
+priority: alta
+depends: []
+blocks: []
+related: []
+created: 2026-05-13
+updated: 2026-05-17
+tags: [ausente-ready]
+---
+
+## Objetivo
+
+Notebook `02_cross_validation.ipynb` que ejecuta los mismos `GenerationConfig` con
+los dos backends operativos (diffusers GPU + sdcpp_python CPU) sobre SD Turbo,
+genera grid lado-a-lado con `image_compare_side_by_side_py_ml` y decide
+cuales configs portan bien entre backends y cuales requieren ajuste.
+
+## Contexto
+
+- Backend diffusers GPU operativo (Ola 3.A) — 192ms/imagen warm, VRAM 3097MB.
+- Backend sdcpp_python CPU operativo (Ola 3.B) — 27s/imagen 512x512 4 steps.
+- Funcion `image_compare_side_by_side_py_ml` lista (Ola 3.D) con grid + diff
+  perceptual + pHash + pixel MSE.
+- Documento `Stack de generacion de imagenes` (raiz proyecto imagegen) dice:
+  "Bit-exact entre backends es imposible. Aceptamos diff perceptual."
+
+## Arquitectura
+
+Archivos NUEVOS:
+- `projects/imagegen/analysis/spike_diffusers_vs_sdcpp/notebooks/02_cross_validation.ipynb`
+- `~/vaults/imagegen_models/configs/cross_validated/*.json` — configs que pasan
+- `~/vaults/imagegen_models/outputs/cross/*.png` — grids A | diff | B
+
+NO se crean funciones nuevas — todo se compone de funciones existentes del registry.
+
+## Tareas
+
+1. Plan del notebook (declarar al usuario antes de escribirlo)
+   1.1. Titulo, objetivo, criterio PASS (pHash distance < umbral X, pixel_mse < Y)
+   1.2. Lista de celdas y output esperado por celda
+
+2. Notebook
+   2.1. Celda hardware check + GPU info (reuse).
+   2.2. Definir 4 configs base (seeds 42, 123, 7, 999), SD Turbo, 1-step euler_a, 512x512.
+   2.3. Loop config: generar A=diffusers, B=sdcpp_python.
+   2.4. `image_compare_side_by_side(A, B, label_a="diffusers", label_b="sdcpp")` por par.
+   2.5. Tabla resumen: pHash distance, pixel MSE, duration_a, duration_b.
+   2.6. Veredicto por config: PASS si pHash<=N (a calibrar), FAIL si no.
+   2.7. Guardar grids comparativos a vault.
+
+3. Ejecutar el notebook desde la sesion claude
+   3.1. Lanzar Jupyter si no esta arriba.
+   3.2. Ejecutar celdas 1..N via `jupyter_exec_py_notebook cell`.
+   3.3. Reportar veredicto por config.
+
+4. Conclusion
+   4.1. Si todos los configs PASS → contrato `GenerationConfig` es portable.
+   4.2. Si alguno FAIL → documentar campo problematico (sampler, cfg_scale, ...)
+        y abrir proposal de ajuste.
+
+## Ejemplo de uso
+
+Output esperado al final:
+
+```
+seed=42   pHash_dist=12  pixel_mse=812.4  diffusers=189ms  sdcpp=26200ms  PASS
+seed=123  pHash_dist=14  pixel_mse=901.0  diffusers=192ms  sdcpp=27100ms  PASS
+seed=7    pHash_dist=11  pixel_mse=750.8  diffusers=187ms  sdcpp=26800ms  PASS
+seed=999  pHash_dist=18  pixel_mse=1102.3 diffusers=194ms  sdcpp=27500ms  PASS
+VEREDICTO GLOBAL: PASS (contrato portable)
+```
+
+## Decisiones
+
+- **Umbrales pHash y MSE** se calibran en este notebook — no hay valor previo.
+  Empezar con pHash<=20 (bastante permisivo), pixel_mse<=2000.
+- **`imagehash` puede no estar instalado** en el venv — `pip install imagehash`
+  como primera celda si falta.
+- **Solo SD Turbo en este notebook** — modelos mayores (SDXL Turbo, FLUX) iran en
+  notebooks separados cuando se descarguen.
+
+## Prerequisitos
+
+- Backends 3.A + 3.B operativos (hechos).
+- SD Turbo en vault (hecho).
+- Jupyter del analysis levantado (script `run-jupyter-lab.sh`).
+
+## Riesgos
+
+- sdcpp_python tarda ~27s por imagen en CPU → 4 imagenes x 2 backends = ~2 min
+  de espera real, aceptable.
+- pHash de imagehash requiere instalar el paquete — documentar en cell 0.
+- Si el sampler de sd.cpp difiere demasiado del de diffusers (ej. trailing
+  timesteps de SD Turbo), la diff sera grande aunque la implementacion sea OK.
@@ -0,0 +1,142 @@
+---
+id: "0084"
+title: "imagegen_studio — app Go binario producto (Fase 3 plan stack)"
+status: pendiente
+type: feature
+domain:
+  - imagegen
+scope: app-scoped
+priority: media
+depends: []
+blocks: []
+related: []
+created: 2026-05-13
+updated: 2026-05-17
+tags: []
+---
+
+## Objetivo
+
+App Go autocontenida `imagegen_studio` que orquesta `sd-cli` para generar imagenes
+sin Python en runtime. Encarna la Fase 3 del documento del stack: binario
+distribuible, `GenerationConfig` Go nativo, subprocess streaming con progreso.
+
+## Contexto
+
+- Toda la capa Go del contrato esta lista: tipos `GenerationConfig_go_ml`,
+  `ModelRef_go_ml`, `LoraRef_go_ml`, `ImageGenResult_go_ml`, interface
+  `ImageGenerator_go_ml`.
+- Funciones Go ya construidas: `sdcli_resolve_binary_go_ml`, `sdcli_generate_go_ml`,
+  `subprocess_stream_go_core`, `genconfig_to_sdcli_args_go_ml`,
+  `genconfig_json_marshal_go_ml`, `sdcli_parse_progress_go_ml`, `get_gpu_info_go_infra`.
+- Plan del documento: producto Go con subprocess gestionando `sd-cli`,
+  binario embebido via `go:embed` o descarga al primer arranque.
+
+## Arquitectura
+
+Path: `projects/imagegen/apps/imagegen_studio/`
+
+```
+imagegen_studio/
+  main.go               # CLI args / TUI entry / HTTP API
+  studio.go             # ImageGenerator wrapper sobre sdcli_generate
+  app.md                # frontmatter del registry
+  CMakeLists.txt        # NO (es Go, usa go.mod)
+  go.mod
+  README.md
+  embed/                # opcional: sd binary embebido
+```
+
+**Pure core / impure shell:**
+- `pkg/`: validacion `GenerationConfig`, serializacion JSON, formato outputs (paths derivados).
+- `shell/` o `studio.go`: invocacion `SdcliGenerate`, IO disco, manejo subproceso.
+
+Tres modos de uso:
+
+1. **CLI**: `imagegen_studio generate --prompt "..." --seed 42 --out out.png`
+2. **HTTP API**: `imagegen_studio serve --port 8088` → POST /generate {GenerationConfig JSON}
+3. **TUI (opcional, Bubble Tea)**: forma interactiva, preview, queue
+
+Empezar por CLI; HTTP API y TUI iterativos.
+
+## Tareas
+
+1. Scaffolding
+   1.1. `fn run init_go_app --project imagegen imagegen_studio` (si existe pipeline)
+        o crear estructura manual.
+   1.2. `app.md` con `framework: cli`, `tags: [ml, imagegen, service?]`,
+        `uses_functions:` lista de las 7 funciones Go citadas.
+   1.3. `go.mod` con dependencias minimas (registry imports + cobra opcional).
+
+2. CLI minima (Fase A)
+   2.1. Subcomando `generate`: flags --prompt/--negative/--seed/--steps/--cfg/--sampler/
+        --width/--height/--model/--out
+   2.2. Construir `GenerationConfig`, llamar `SdcliResolveBinary("")`, `SdcliGenerate(...)`.
+   2.3. Stream progreso a stderr (callback `SdcliProgressCallback`).
+   2.4. Salida final: imprime path de la imagen + duration_ms + JSON meta.
+
+3. JSON I/O (Fase B)
+   3.1. Subcomando `generate-from-json --config path/cfg.json --out out.png`.
+   3.2. Permite pegar configs validados de la fase 2 (notebook cross-validation).
+
+4. HTTP server (Fase C, feature flag)
+   4.1. `imagegen_studio serve --port 8088`.
+   4.2. POST `/generate` body = GenerationConfig JSON → respuesta multipart PNG + meta.
+   4.3. GET `/health` → 200 + version + GpuInfo.
+   4.4. Feature flag `imagegen-studio-server` para esconder cuando no compila/no testeado.
+
+5. e2e_checks
+   5.1. Anadir bloque `e2e_checks` en `app.md`:
+        - `build`: go build con CGO_ENABLED=0
+        - `cli_help`: ./imagegen_studio --help, contiene "generate"
+        - `smoke`: si `sd` binario en $PATH + SD Turbo en vault, generar 1 imagen
+          a /tmp/, verificar PNG valido. Si no: SKIP (warning).
+
+6. Tests
+   6.1. Tests unitarios sobre helpers puros (path derivation, JSON marshaling).
+   6.2. Test integracion en e2e_checks (smoke).
+
+## Ejemplo de uso
+
+```bash
+# CLI directo
+imagegen_studio generate \
+  --model /home/lucas/vaults/imagegen_models/diffusers/sd-turbo/sd_turbo.safetensors \
+  --prompt "a red apple on a wooden table" \
+  --seed 42 --steps 1 --cfg-scale 0.0 --sampler euler_a \
+  --width 512 --height 512 \
+  --out /tmp/apple.png
+
+# Desde config JSON validado en spike notebook 02
+imagegen_studio generate-from-json \
+  --config ~/vaults/imagegen_models/configs/spike01_seed42_*.json \
+  --out /tmp/seed42.png
+
+# HTTP API (feature flag activado)
+imagegen_studio serve --port 8088 &
+curl -X POST -H "Content-Type: application/json" \
+  -d @config.json http://localhost:8088/generate -o out.png
+```
+
+## Decisiones
+
+- **Subprocess via SdcliGenerate** — no cgo ni bindings. Mas robusto, mas lento al
+  arrancar (~200ms cold start), pero overhead irrelevante frente a 1-30s generacion.
+- **NO `go:embed` del binario `sd` en Fase A** — el binario depende de la GPU del
+  usuario (CUDA/CPU/Vulkan). Documentar requisito: tener `sd` en $PATH (issue 0082).
+- **Feature flag para HTTP API** — Fase A es CLI, no romper master con server a medias.
+
+## Prerequisitos
+
+- Issue 0082 (binario `sd` compilado en $PATH) — sin esto el smoke falla pero la
+  app compila. Se puede arrancar el scaffolding antes.
+- Funciones Go de Ola 3.C (hechas).
+
+## Riesgos
+
+- `sd-cli` no soporta SD Turbo cleanly con 1-step euler_a → puede requerir 4-step
+  como minimo. Validar en issue 0082.
+- Distribucion sin binario `sd` empotrado obliga al usuario a instalarlo. Aceptable
+  para Fase A; reevaluar `go:embed` con build-per-backend en Fase C+.
+- Si Fase 0 (spike) del documento revela calidad insuficiente: replantear stack y
+  pausar este issue.