Cómo gestiona mintbot los archivos

Cuando envías una foto, un documento, una nota de voz, una hoja de cálculo, una captura o un PDF a tu agente mintbot — a través de Telegram, del panel web o de la API — el archivo no pasa por la infraestructura central de mintbot camino del modelo de lenguaje. Aterriza directamente en el VPS de tu propio agente, se queda allí todo el tiempo que tú quieras, y el LLM recibe una copia transformada y optimizada para él.

Es una decisión de diseño silenciosa con consecuencias ruidosas. Vale la pena explicarla, porque es uno de los puntos donde mintbot se aleja más del chat LLM de consumo.

El flujo, de punta a punta

1. La subida llega al VPS del agente. Una foto de Telegram, un PDF arrastrado al panel web, una nota de voz, una captura pegada al chat. La API local del agente acepta los bytes, olfatea la cabecera mágica para averiguar qué clase de archivo es realmente (los teléfonos y los navegadores etiquetan mal con sorprendente frecuencia), calcula su hash SHA-256 y lo escribe en /var/lib/mintbot-agent/uploads/<shard>/<sha256>.<ext> en el VPS de tu propio agente. En un catálogo local se añade una fila con la fuente (telegram / panel / api), el ID del subidor, el tipo MIME y el nombre de archivo original.

2. El original es sagrado. A partir de ese momento, nada dentro de mintbot vuelve a mutar el archivo almacenado. Los adaptadores que lo preparan para el LLM solo emiten copias de trabajo — JPEG redimensionados, texto transcodificado, miniaturas extraídas. El original, byte por byte, permanece en disco hasta que tú lo borres a través del gestor de archivos del agente. No hay bucket central, no hay temporizador de retención, no hay fugas entre agentes: el VPS de cada agente solo conoce las subidas de su propio dueño.

3. El modelo recibe una versión optimizada para LLM. Cuando el agente decide enseñarle el archivo al LLM, un pequeño dispatcher elige el adaptador correcto según el tipo MIME y la extensión, y el adaptador emite bloques de contenido que el modelo puede leer:

   Adaptador	Maneja	Salida
   Image	JPG, PNG, WebP, GIF, HEIC (iPhone), AVIF y cualquier otra cosa que Pillow pueda abrir	Reescalado a 1568 px en el lado largo, re-codificado a JPEG q85, inline en base64 en el contexto del modelo
   PDF	.pdf ≤ 32 MB	Inline en base64 como PDF nativo (los modelos de Anthropic lo leen directamente)
   Text	.md, .csv, .json, .yaml, código fuente (.py, .js, .ts, .go, .rs, …), logs, diffs	Decodificado en UTF-8 (latin-1 como respaldo), inline como texto hasta un límite de tamaño
   Audio	.mp3, .ogg, .opus, .m4a, .wav, .flac	Las notas de voz de Telegram ya las transcribe el bot inline; las subidas directas reciben de momento un marcador, con Whisper STT en una siguiente oleada
   Video	.mp4, .mov, .webm, .mkv	Marcador por ahora; extracción de keyframes con ffmpeg + transcripción de audio llegan en una siguiente oleada
   Office docs	.docx, .xlsx, .pptx, .odt, .ods, .odp	Marcador por ahora; la extracción de texto nativa (python-docx / openpyxl / python-pptx) llega en una siguiente oleada
   Unknown	Cualquier otra cosa	Marcador en texto: «el usuario adjuntó un archivo <mime>, está conservado en disco con el ID de subida <id>» — así el modelo al menos puede razonar sobre lo que se envió

   Cada transformación queda cacheada junto al original como <sha256>.cache/v<N>.json, de modo que la segunda vez que el modelo necesita ese archivo, la carga es instantánea. Subir la versión del adaptador invalida el caché automáticamente.

4. Nada de URLs que caduquen en el contexto del modelo. Cuando una imagen o un PDF va al LLM, viaja inline en base64 en el mismo turno — sin URL que pueda dar 404 más tarde, sin enlace firmado con temporizador. Para archivos más grandes en los que el modelo solo necesita un puntero, la URL es interna: https://agent<id>.<domain>/<panel_token>/api/local/uploads/<upload_id>/raw — protegida por el panel token de tu propio agente y válida mientras el archivo siga en disco.

Por qué esto le gana al chat LLM de consumo

Cuando subes una foto a ChatGPT o un PDF a Claude.ai, el archivo entra en el almacenamiento del proveedor, atado a esa conversación, y la política de retención del proveedor decide cuándo desaparece. Pasada cierta edad, el archivo se ha ido, aunque tú aún puedas ver la conversación en la que estaba. Cambiar de un proveedor a otro significa empezar de cero.

Un caso típico con los bots de Telegram pone el contraste muy claro. Telegram mantiene un file_id permanente para cada foto, pero los bots de terceros que piden un file_id de Telegram reciben una URL temporal que caduca a las 24 horas. Los bots viejos que referencian la foto de ayer devuelven un 404. mintbot arregla esto de una vez: la primera vez que ve un archivo de Telegram, vuelve a descargar los bytes a través del file_id eternamente válido y los copia en el archivo de tu agente. A partir de ese momento, la foto es tuya.

De este diseño se siguen tres cosas:

• Los archivos te pertenecen a ti, no al proveedor del LLM. Cambia de Claude a GPT-5 el mes que viene y tu historial de archivos se va contigo, intacto, porque está en tu VPS — no en el bucket de un proveedor.
• Puedes volver a preguntar más adelante. «Hace tres meses me analizaste un contrato — ¿puedes compararlo con este nuevo borrador?» funciona, porque el original sigue en disco. En el chat de consumo, el archivo viejo normalmente ya no está.
• El modelo siempre recibe la versión que mejor puede usar. Los modelos de visión reciben el JPEG redimensionado, los lectores de texto reciben UTF-8, los lectores de PDF reciben PDF nativo. Los teléfonos pueden subir HEIC y simplemente funciona — el plugin HEIF de Pillow se carga al arrancar, y el detector de bytes mágicos pilla a los teléfonos que etiquetan la subida como application/octet-stream.

Dónde gestionar tus archivos

El panel web del agente trae un gestor de archivos en la barra superior. Navega por todo el VPS del agente, y el archivo de subidas en /var/lib/mintbot-agent/uploads/ es la parte que tus conversaciones rellenan. Desde ahí puedes:

• Renombrar, borrar o mover archivos subidos
• Navegarlos por fecha, fuente o nombre
• Arrastrar y soltar nuevas subidas (chunked, soporta archivos de varios gigabytes)
• Editar archivos de texto pequeños inline

Borrar un archivo desde el panel quita tanto el blob como la fila del catálogo. El agente ya no podrá mostrárselo al LLM. Eso es lo que hace que el original sea «tuyo»: tú eres el único con autoridad para borrarlo.

Conclusión

La mayoría de los productos de chat LLM tratan tus subidas como contexto de conversación efímero. mintbot las trata como tus datos — guardadas en tu VPS, de tu propiedad, transformadas bajo demanda a la forma que el modelo necesite ese turno. Buena parte de las capacidades más interesantes de mintbot se apoyan en este cimiento.