MapacheDescribe

Bot para Mastodon que genera propuestas de texto alternativo (ALT) para imágenes cuando se le menciona.

El objetivo es facilitar la accesibilidad cuando alguien publica una imagen sin descripción.
El bot analiza la imagen y devuelve una sugerencia de ALT, que la persona puede revisar y adaptar.

Todo el procesamiento se realiza localmente, sin APIs externas ni servicios de pago.
Las imágenes no se envían a ningún servicio externo: el análisis ocurre completamente en el servidor donde corre el bot.

---

Cómo funciona

El bot escucha menciones en Mastodon.

Cuando detecta una imagen sin ALT:

1. descarga la imagen
2. genera una descripción automática con Florence
3. traduce el resultado al español con NLLB
4. responde al toot con un ALT sugerido

Uso típico:

1. Publicas una imagen sin ALT
2. Mencionas al bot en ese toot o en una respuesta
3. El bot analiza la imagen
4. El bot responde con una propuesta de ALT

Si la imagen ya tiene ALT, el bot lo indica y no genera uno nuevo.
Si un toot contiene varias imágenes, el bot puede procesar hasta 4.

---

Arquitectura

El bot separa el listener del procesado de imágenes para evitar bloquear el stream de Mastodon.

Mastodon Stream
       │
       ▼
Listener (encola menciones)
       │
       ▼
Queue
       │
       ▼
Worker(s) → procesan imágenes

Esto permite que el bot siga escuchando menciones mientras los modelos están trabajando.

---

Modelos utilizados

Modelo	Uso
microsoft/Florence-2-base	descripción de imagen
facebook/nllb-200-distilled-600M	traducción al español

Ambos modelos se descargan automáticamente la primera vez que se ejecuta el bot.

---

Requisitos del servidor

• Python 3.10+
• 4–8 GB de RAM
• CPU moderna
• GPU opcional (acelera el procesado pero no es necesaria)

Tiempo aproximado por imagen en CPU: 8–20 segundos, dependiendo del tamaño de la imagen y del servidor.

---

Crear la cuenta del bot

Crea una cuenta nueva en tu instancia Mastodon y ve a:

Preferencias → Desarrollo → Nueva aplicación

Permisos necesarios: read write

Guarda el Access Token generado.

---

Instalación

Clonar el repositorio:

git clone https://git.mapache.rocks/elenamusk/mapachedescribe.git
cd mapachedescribe

Crear entorno virtual:

python3 -m venv venv
source venv/bin/activate

Instalar dependencias:

pip install -r requirements.txt

---

Variables de entorno

Crear archivo .env en el directorio del proyecto:

MASTODON_BASE_URL=https://tuinstancia.social
MASTODON_ACCESS_TOKEN=TU_TOKEN

---

Ejecutar

python bot.py

La primera vez descargará los modelos automáticamente, lo que puede tardar unos minutos.

---

Servicio systemd (opcional)

Para mantener el bot corriendo en segundo plano, crea el archivo /etc/systemd/system/mapachedescribe.service:

[Unit]
Description=MapacheDescribe ALT bot
After=network.target

[Service]
User=usuario
WorkingDirectory=/home/usuario/mapachedescribe
ExecStart=/home/usuario/mapachedescribe/venv/bin/python bot.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Activar:

sudo systemctl daemon-reload
sudo systemctl enable mapachedescribe
sudo systemctl start mapachedescribe

Ver logs:

journalctl -u mapachedescribe -f

---

Comportamiento

El bot ignora:

• boosts
• sus propias menciones
• cuentas marcadas como bot
• publicaciones con las etiquetas #nobot, #noaltbot o #noimagebot

Cuando recibe una solicitud válida, marca la publicación con un favorito para indicar que ha sido añadida a la cola de procesamiento.

Visibilidad de las respuestas:

• unlisted por defecto
• private o direct si el toot original tiene esa visibilidad

---

Pedir ayuda

Menciona al bot con el texto ayuda o help para recibir instrucciones de uso.

---

Limitaciones conocidas

Los modelos de visión pueden describir mal escenas complejas, ignorar detalles o en ocasiones inventar objetos. Por eso el bot devuelve una sugerencia, no un ALT definitivo.

Quien publica la imagen debe revisar siempre el resultado antes de usarlo.

---

Procesado de texto

El bot aplica varias correcciones automáticas sobre la descripción traducida antes de enviarla:

• capitalización de oraciones internas, no solo la primera letra del texto
• protección de abreviaturas comunes (Dr., Sr., etc.) para evitar cortes incorrectos al dividir frases
• eliminación de frases interpretativas generadas por Florence ("se traduce como", "lo que significa", referencias a imgflip, etc.)
• normalización de expresiones redundantes ("La imagen muestra", "Se puede ver", etc.)
• corrección de menciones a Twitter/X hacia terminología neutra

---

Nota sobre los modelos

Este proyecto utiliza modelos distribuidos a través de Hugging Face. Los pesos están disponibles públicamente, pero no son software libre en sentido estricto. Para proyectos de accesibilidad en instancias pequeñas funcionan bien, pero conviene revisar las licencias de cada modelo antes de redistribuirlos.

---

Posibles mejoras futuras

• deduplicación de imágenes mediante hash
• cola persistente entre reinicios
• soporte para más idiomas
• integración con modelos alternativos

---

Licencia

Este proyecto se distribuye bajo licencia AGPL-3.0.