agents_and_robots/dev/issues/completed/0042-auto-avatar-providers.md

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

• 1.1 Separar SetAvatar en UploadMedia + SetAvatarURL + SetAvatar (convenience)
• 1.2 Añadir subcomandos upload-media y set-avatar-url en agentctl

Fase 2: Proveedores de imagenes (pkg/avatar)

• 2.1 Crear pkg/avatar/provider.go con tipos: Provider, Options, DiceBearStyle, RoboHashSet
• 2.2 Implementar URL() — funcion pura que genera URL del proveedor dado seed y opciones
• 2.3 Proveedores soportados: DiceBear, RoboHash, Multiavatar
• 2.4 Tests unitarios

Fase 3: Fetcher (shell/avatar)

• 3.1 Crear shell/avatar/fetch.go con Fetch(), Download(), FetchToDir()
• 3.2 Protecciones: timeout 30s, max 10MB, content-type → extension
• 3.3 Tests con httptest (sin internet)

Fase 4: Integracion CLI

• 4.1 Crear agentctl auto-avatar <id> con flags --provider, --style, --set, --size, --dry-run
• 4.2 Integrar auto-avatar en create-full.sh (paso opcional post-registro)

Fase 5: Documentacion

• 5.1 Crear issue
• 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

# 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