Como Funciona Todo, Fase por Fase

Cuando corre: 3 veces al dia — 8:00 AM (morning), 1:00 PM (midday), 6:00 PM (evening).

Que recibe: El nombre del slot (morning, midday, o evening) y la fecha del dia. Tambien necesita las cookies de sesion de tu cuenta de Twitter (@maurosicard) para autenticarse — es como si el script "abriera" Twitter logueado con tu cuenta.

Que hace: Abre tu timeline "For You" y hace 6 rondas de scroll, capturando ~20 tweets por ronda. Entre cada ronda espera 30 a 60 segundos al azar para simular comportamiento humano y no ser bloqueado por Twitter. De cada tweet extrae: texto, autor, likes, retweets, replies, URLs de imagenes, si tiene video, y fecha de publicacion.

Cuantos tweets: Cada pasada captura aproximadamente ~120 tweets brutos (6 rondas x 20). Con 3 pasadas al dia son ~360 brutos. Despues de eliminar duplicados (tweets que aparecen en mas de una pasada), el archivo final del dia tiene tipicamente entre 100 y 200 tweets unicos.

Que produce: Dos cosas:

• Un archivo individual de esa pasada (ej: 0800_morning.csv) — como un "recibo" de lo que se capturo en ese momento.
• Un archivo acumulado del dia (raw_feed.csv) — fusiona todas las pasadas del dia eliminando duplicados. Este archivo crece con cada pasada.

Cuando corre: Inmediatamente despues de cada scrape — ~8:10 AM, ~1:10 PM, ~6:10 PM.

Que recibe: El archivo acumulado del dia (raw_feed.csv) con todos los tweets recolectados hasta ese momento.

Que hace: Lee cada tweet y toma una decision simple: tiene imagen o no? Los separa en dos archivos distintos. Para los tweets que tienen imagen, descarga cada foto fisicamente al servidor desde los servidores de Twitter (pbs.twimg.com). Un tweet puede tener hasta 4 imagenes. Tambien marca los tweets que tienen video (pero no descarga el video, solo lo anota).

Detalle importante: Este script es seguro de correr multiples veces. Si ya descargo una imagen antes, no la descarga de nuevo. Si un tweet ya tenia una descripcion de imagen (de Phase 2), la preserva. Esto permite que corra despues de cada pasada sin perder trabajo previo.

Que produce: 4 cosas:

• Tweets sin imagen (no_images.csv) — ~55% de los tweets tipicamente. Incluye una nota si el tweet tiene video.
• Tweets con imagen (with_images.csv) — ~45% de los tweets. Incluye los nombres de las imagenes descargadas y un campo vacio para la descripcion (que llenara Phase 2).
• Carpeta de imagenes (images/) — Las fotos descargadas. En un dia tipico hay entre 25-50 imagenes. Nombres tipo: levelsio-tweetid-2006097888-image1.jpg.
• Inventario (manifest.json) — Un listado estructurado de todas las imagenes: cuantas hay, de que tweets vienen, cuales se descargaron exitosamente.

Cuando corre: Despues de cada procesamiento — ~8:10 AM, ~1:10 PM, ~6:10 PM (inmediatamente despues del procesador de Phase 1).

Que recibe: La fecha del dia. Internamente busca el inventario de imagenes (manifest.json) y el archivo de tweets con imagen (with_images.csv) de esa fecha.

Que hace: Ejecuta un ciclo repetitivo con 3 pasos:

1. Llamar al agente AI (z-ai) — Le pasa las imagenes que faltan por describir. El agente las mira y escribe descripciones. Cada intento tiene un limite de 20 minutos.
2. Aplicar descripciones — Toma las descripciones generadas y las inserta en el archivo de tweets con imagen.
3. Validar — Revisa si todas las imagenes del inventario ya tienen descripcion.

Si la validacion pasa, crea el archivo images_done.ok (el gate) y termina. Si faltan descripciones, espera 30 segundos y vuelve a intentar el ciclo. Repite indefinidamente hasta que todo este completo o se detenga manualmente.

Que produce: El archivo gate images_done.ok — la prueba de que todas las imagenes del dia tienen descripcion.

Quien es: Un modelo de AI (z-ai) que puede ver imagenes. Recibe un contrato escrito (CLAUDE.md) que le dice exactamente que hacer y que no hacer.

Que puede hacer: Leer imagenes, leer el inventario y las descripciones existentes, y solo escribir nuevas descripciones al final del archivo de descripciones. No puede modificar ningun CSV, no puede borrar descripciones anteriores, no puede acceder a internet.

Como describe: Para cada imagen, escribe una descripcion literal de 2-5 oraciones. Si la imagen tiene texto visible (capturas de pantalla, graficos), lo cita tal cual. Si tiene numeros o datos (benchmarks, tablas), los incluye. Nunca inventa contenido que no sea visible en la imagen.

Si falla: En vez de saltarse la imagen, escribe un registro de error (CAPTION_FAILED: razon) para que el sistema sepa que esa imagen necesita otro intento.

Que hace: Compara el inventario de imagenes (manifest.json) contra las descripciones generadas. Responde una pregunta simple: cada imagen del inventario tiene una descripcion valida?

Resultados posibles:

• Todo OK — Todas las imagenes tienen descripcion. El loop crea images_done.ok y termina.
• Incompleto — Faltan descripciones. El loop vuelve a intentar.
• Error critico — Algo esta roto (archivos corruptos, formato invalido). El pipeline se detiene.

De los ~100-200 tweets recolectados en Phase 1, el agente tiene que elegir los mejores para el digest. El proceso es determinista (siempre da el mismo resultado con los mismos datos):

1. Eliminar tweets invalidos — Los que no tienen ID, URL, o contenido se descartan.
2. Eliminar duplicados — Si un tweet aparecio mas de una vez, se queda solo con la primera aparicion.
3. Aplicar exclusiones globales — Se eliminan tweets sobre temas prohibidos: crypto, dating, fitness, drama politico, motivational fluff, etc. (definidos en INTEREST.md).
4. Aplicar minimos de likes — Cada categoria de interes tiene un umbral minimo. Ejemplo: tips de Claude Code necesitan al menos 50 likes, discusiones de AI necesitan 100+, pero noticias oficiales no tienen minimo.
5. Rankear por likes — Los tweets restantes se ordenan de mayor a menor likes. En caso de empate, gana el tweet mas reciente.
6. Distribuir en secciones — Los mejores tweets se agrupan en 3-5 secciones tematicas.

Si quedan menos de 3 tweets elegibles despues del filtrado, el agente declara fallo. No genera un digest medio vacio — prefiere no publicar nada.

Este archivo le dice al agente que temas te importan y cuales ignorar. Es tu perfil de preferencias. Hoy incluye 5 categorias de interes:

• Claude Code & AI Agents — Workflows, MCP servers, agentic coding. Min 50 likes para tips, 0 para noticias.
• AI & LLMs — Nuevos modelos, benchmarks, tecnicas. Min 100 likes para discusiones, 0 para anuncios oficiales.
• GenAI / Image & Video — Workflows practicos de generacion de imagenes/video. Min 50 likes.
• Apps & Developer Tools — macOS apps, CLI tools, self-hosted. Prioridad: self-hosted > one-time > subscription.
• Automation — n8n, Shortcuts, browser automation, scripting.

Detalle interesante: La pagina web del digest (Phase 4) tiene un formulario de feedback. Si al leer tu digest envias una sugerencia ("quiero mas contenido de X" o "deja de mostrarme Y"), esa sugerencia se agrega automaticamente a este archivo. El proximo digest ya toma en cuenta tu feedback.

El contrato define una estructura rigida para el digest.json:

• Titulo del dia — Un titulo editorial para el digest.
• 3-5 secciones tematicas — Cada una con icono, titulo, y tags.
• Bloques narrativos — Parrafos escritos por el agente que dan contexto y conectan los tweets.
• Bloques de tweets — Los tweets seleccionados con todos sus datos + un campo why que explica en 1-2 oraciones por que ese tweet fue elegido.
• Cierre editorial — Un parrafo de despedida.

Cada seccion tiene que tener al menos un bloque narrativo y un bloque de tweet. El agente tambien genera un checkpoint (digest_checkpoint.md) que es un reporte de status: que archivos leyo, que tweets selecciono, si hubo problemas, si el resultado es valido.

Que es: Un archivo PHP (index.php.template) que actua como plantilla universal. No es especifico de ninguna fecha — funciona para cualquier dia. Cuando se ejecuta, busca el archivo digest.json que esta en la misma carpeta y lo convierte en una pagina web completa.

Que muestra: El titulo del dia, cada seccion con sus narrativas y tweets, el cierre editorial, y un formulario de feedback al final. Los tweets se muestran con el contenido, nombre, username, likes, retweets, replies, y el campo why que explica por que se eligio.

Como se despliega: El orquestador (Phase 5) copia este template a la carpeta del dia como index.php. Al acceder a esa URL en el navegador, PHP lo ejecuta, lee el digest.json de la misma carpeta, y renderiza la pagina.

Que es: La pagina web del digest tiene un formulario al final donde puedes escribir sugerencias en texto libre: "quiero ver mas contenido de Rust", "deja de mostrar gaming", etc.

Que pasa al enviar: Tu sugerencia se agrega automaticamente al archivo INTEREST.md (Phase 3) con la fecha y hora. La proxima vez que se genere un digest, el agente AI leera esas sugerencias y las tomara en cuenta para la seleccion y presentacion de tweets.

El ciclo: Lees el digest → envias feedback → el proximo digest se adapta → repites. Esto permite que el digest evolucione con tus intereses sin tener que editar archivos manualmente.

Cuando corre: Una vez al dia, tipicamente a las 10:00 PM, despues de que las 3 pasadas de scraping y captioning ya terminaron.

Que recibe: Solo la fecha (YYYY-MM-DD). Todo lo demas lo busca automaticamente en las carpetas del pipeline.

Que hace, paso a paso:

1. Verifica datos crudos — Si no existe raw_feed.csv, intenta fusionar las pasadas individuales. Si no hay nada, falla.
2. Corre el procesador (Phase 1) — Asegura que los tweets esten separados y las imagenes descargadas.
3. Corre captions (Phase 2) — Asegura que todas las imagenes tengan descripcion.
4. Verifica el gate — Si images_done.ok no existe despues de intentar captions, falla y se detiene.
5. Invoca al agente AI (Claude) — Le pasa el contrato de Phase 3 y los datos del dia. Claude genera digest.json y digest_checkpoint.md.
6. Valida el digest — Verifica que el JSON sea valido y que los archivos existan.
7. Copia el template web — Copia index.php.template (Phase 4) a la carpeta del dia como index.php.
8. Ajusta permisos — Asegura que los archivos sean legibles por el servidor web.
9. Envia notificacion Telegram (Phase 6) — Envia un mensaje con el link del digest.
10. Registra el dia — Agrega la fecha a COMPLETED-DAYS.md (ledger de dias publicados).
11. Marca como publicado — Crea published.ok como prueba de que todo termino bien.

Al completarse exitosamente, la carpeta del dia contiene:

• digest.json — El resumen estructurado con todos los tweets seleccionados, narrativas, y metadata.
• digest_checkpoint.md — Reporte de status: que leyo, que selecciono, si hubo problemas.
• index.php — La pagina web lista para ver en el navegador.
• published.ok — Archivo que confirma publicacion exitosa.

Y a nivel global:

• COMPLETED-DAYS.md — Lista de todas las fechas publicadas, una por linea. Funciona como historial.

Cuando corre: Automaticamente al final de Phase 5 (~10pm). Tambien puede correrse manualmente.

Que verifica antes de enviar:

• Que digest.json exista y sea JSON valido
• Que index.php exista (la pagina web esta lista)
• Que images_done.ok exista (todas las imagenes fueron descritas)

Que envia: Un mensaje HTML a tu chat de Telegram con la fecha y el link directo a la pagina del digest. Asi puedes abrirlo desde el telefono y leer tu resumen diario en el momento que quieras.

Que necesita: 3 variables de entorno configuradas en el servidor:

• TELEGRAM_BOT_TOKEN — El token de tu bot de Telegram.
• TELEGRAM_CHAT_ID — El ID del chat donde quieres recibir el mensaje.
• PUBLIC_BASE_URL — La URL base de tu servidor (ej: https://tudominio.com/twitter-digest).

Si algo falla: El script verifica que la API de Telegram responda con ok: true. Si no, reporta el error. El pipeline ya se completo — el digest esta publicado independientemente de si Telegram funciono o no.

Recoleccion (Phase 1):

• 8:00 AM — Scrape morning + procesar
• 1:00 PM — Scrape midday + procesar
• 6:00 PM — Scrape evening + procesar

Captioning (Phase 2):

• 8:10 AM — Caption imagenes del scrape de las 8
• 1:10 PM — Caption imagenes del scrape de la 1
• 6:10 PM — Caption imagenes del scrape de las 6

Publicacion (Phase 5 → 6):

• 10:00 PM — Correr el orquestador completo. Genera digest, publica, envia Telegram.

Cuando cron corra los scripts automaticamente, cada ejecucion dejara un archivo de log para poder revisar que paso si algo falla:

• Logs de scraping — Cuantos tweets se capturaron, errores de conexion, rate limits.
• Logs de procesamiento — Cuantas imagenes se descargaron, errores de descarga.
• Logs de captioning — Cuantas imagenes se describieron, intentos necesarios, timeouts.
• Logs de digest — Si el agente genero el JSON correctamente, errores de validacion.