143 lines
5.3 KiB
Markdown
143 lines
5.3 KiB
Markdown
---
|
|
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.
|