egutierrez
fb67ec17a6
Documenta el diseño completo: proveedores (DiceBear, RoboHash, Multiavatar), arquitectura pure/impure, integracion CLI y pipeline. Todas las tareas completadas. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
118 lines
4.6 KiB
Markdown
118 lines
4.6 KiB
Markdown
# Issue 0042: Auto-avatar con proveedores gratuitos
|
|
|
|
## Objetivo
|
|
|
|
Cuando se crea un agente/robot, asignarle automaticamente un avatar unico generado por un proveedor gratuito de imagenes, usando el agent ID como seed. Asi cada bot tiene una imagen distintiva en lugar de la letra por defecto de Matrix.
|
|
|
|
## Contexto
|
|
|
|
- El issue 0004 implemento la funcionalidad manual de avatar (`agentctl avatar <id> <path>`)
|
|
- Actualmente los bots se crean con la letra inicial como avatar (default de Matrix)
|
|
- Existen proveedores gratuitos que generan imagenes unicas a partir de un texto seed
|
|
- La generacion de URLs es pura (solo string formatting), la descarga es impura (HTTP)
|
|
|
|
## Arquitectura
|
|
|
|
Respeta **pure core / impure shell**:
|
|
|
|
```
|
|
pkg/avatar/provider.go — PURO: tipos, URL builders (Provider, Options, URL())
|
|
shell/avatar/fetch.go — IMPURO: HTTP download a temp file (Fetch, Download, FetchToDir)
|
|
cmd/agentctl/autoavatar.go — CLI: agentctl auto-avatar <id> [--provider] [--style]
|
|
dev-scripts/agent/avatar.sh — wrapper bash (ya existente, sin cambios)
|
|
```
|
|
|
|
### Archivos afectados
|
|
|
|
| Archivo | Accion | Pure/Impure |
|
|
|---------|--------|-------------|
|
|
| `pkg/avatar/provider.go` | `NEW` | Pure |
|
|
| `pkg/avatar/provider_test.go` | `NEW` | Pure |
|
|
| `shell/avatar/fetch.go` | `NEW` | Impure |
|
|
| `shell/avatar/fetch_test.go` | `NEW` | Impure |
|
|
| `shell/matrix/profile.go` | Refactorizar: separar UploadMedia de SetAvatarURL | Impure |
|
|
| `cmd/agentctl/autoavatar.go` | `NEW` | CLI |
|
|
| `cmd/agentctl/avatar.go` | Añadir upload-media y set-avatar-url | CLI |
|
|
| `cmd/agentctl/main.go` | Registrar nuevos subcomandos | CLI |
|
|
| `dev-scripts/agent/create-full.sh` | Integrar auto-avatar en pipeline | Script |
|
|
|
|
## Tareas
|
|
|
|
### Fase 1: Refactorizar profile.go
|
|
|
|
- [x] 1.1 Separar `SetAvatar` en `UploadMedia` + `SetAvatarURL` + `SetAvatar` (convenience)
|
|
- [x] 1.2 Añadir subcomandos `upload-media` y `set-avatar-url` en agentctl
|
|
|
|
### Fase 2: Proveedores de imagenes (pkg/avatar)
|
|
|
|
- [x] 2.1 Crear `pkg/avatar/provider.go` con tipos: Provider, Options, DiceBearStyle, RoboHashSet
|
|
- [x] 2.2 Implementar `URL()` — funcion pura que genera URL del proveedor dado seed y opciones
|
|
- [x] 2.3 Proveedores soportados: DiceBear, RoboHash, Multiavatar
|
|
- [x] 2.4 Tests unitarios
|
|
|
|
### Fase 3: Fetcher (shell/avatar)
|
|
|
|
- [x] 3.1 Crear `shell/avatar/fetch.go` con `Fetch()`, `Download()`, `FetchToDir()`
|
|
- [x] 3.2 Protecciones: timeout 30s, max 10MB, content-type → extension
|
|
- [x] 3.3 Tests con httptest (sin internet)
|
|
|
|
### Fase 4: Integracion CLI
|
|
|
|
- [x] 4.1 Crear `agentctl auto-avatar <id>` con flags --provider, --style, --set, --size, --dry-run
|
|
- [x] 4.2 Integrar auto-avatar en `create-full.sh` (paso opcional post-registro)
|
|
|
|
### Fase 5: Documentacion
|
|
|
|
- [x] 5.1 Crear issue
|
|
- [x] 5.2 Actualizar `create_agent.md` para mencionar auto-avatar
|
|
|
|
## Proveedores soportados
|
|
|
|
| Proveedor | URL base | Parametros | Formato |
|
|
|-----------|----------|------------|---------|
|
|
| **DiceBear** | `api.dicebear.com/9.x/{style}/png` | seed, size | PNG |
|
|
| **RoboHash** | `robohash.org/{seed}.png` | set (robots/monsters/heads/cats/humans), size | PNG |
|
|
| **Multiavatar** | `api.multiavatar.com/{seed}.png` | — | PNG |
|
|
|
|
Todos son gratuitos, no requieren API key, y generan imagenes deterministas (mismo seed = misma imagen).
|
|
|
|
## Ejemplo de uso
|
|
|
|
```bash
|
|
# Auto-avatar con DiceBear (default)
|
|
agentctl auto-avatar assistant-bot
|
|
# fetch assistant-bot https://api.dicebear.com/9.x/bottts/png?seed=assistant-bot&size=256
|
|
# ok assistant-bot avatar → mxc://matrix-af2f3d.organic-machine.com/abc123
|
|
|
|
# Auto-avatar con RoboHash robots
|
|
agentctl auto-avatar monitor-bot --provider robohash
|
|
|
|
# Auto-avatar con DiceBear pixel-art
|
|
agentctl auto-avatar creative-bot --provider dicebear --style pixel-art
|
|
|
|
# Solo ver la URL sin descargar
|
|
agentctl auto-avatar test-bot --dry-run
|
|
# url test-bot https://api.dicebear.com/9.x/bottts/png?seed=test-bot&size=256
|
|
```
|
|
|
|
## Decisiones de diseno
|
|
|
|
1. **Seed = agent ID**: el ID es unico por agente, asi que cada bot obtiene una imagen distinta y reproducible.
|
|
2. **DiceBear como default**: tiene la mayor variedad de estilos y la API mas estable.
|
|
3. **No guardar URL en config**: el avatar se sube a Matrix una vez. No necesita persistencia local.
|
|
4. **Funciones separadas**: UploadMedia y SetAvatarURL son independientes para poder reusar imagenes ya subidas.
|
|
|
|
## Prerequisitos
|
|
|
|
- Issue 0004 (avatar manual) — completado
|
|
|
|
## Riesgos
|
|
|
|
| Riesgo | Mitigacion |
|
|
|--------|------------|
|
|
| Proveedor caido | --dry-run muestra URL; retry manual con otro --provider |
|
|
| Imagen muy grande | Limite de 10MB en el fetcher |
|
|
| Proveedor cambia API | URLs versionadas (DiceBear v9.x); facil cambiar en pkg/avatar |
|
|
|
|
## Estado: COMPLETADO
|