Skip to content

About

News agent

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

⚡ News Agent — Agente Inteligente de Pauta Editorial

Curador automatizado de pauta periodística para La Chispa Sur, medio digital independiente de izquierda, crítico del modelo neoliberal.

El agente recolecta noticias desde canales RSS y scraping web, las filtra por una ventana temporal de 4 días (96 horas), enriquece los resúmenes cortos extrayendo el contenido completo de los artículos con trafilatura, y utiliza el modelo DeepSeek-Flash (vía API compatible con OpenAI SDK) para sintetizar cinco propuestas de pauta editorial semanal (tres de foco nacional y dos de foco internacional) con profundidad analítica, tono incisivo y narrativa ágil. Las propuestas internacionales priorizan hechos que conmocionan al mundo, pueblos oprimidos y políticas imperialistas que afectan la estabilidad mundial, con mirada antiimperialista desde el sur global. También permite escribir artículos completos (~1000 palabras) a partir de cualquiera de las propuestas generadas, con un sistema de referencias deterministas a fuentes que asegura que el redactor reciba el contenido completo de los artículos fuente correctos para cada propuesta.


🧠 Funcionalidades

1. Generación de pauta editorial semanal

Flujo automatizado que:

  1. Ingesta de noticias — Obtiene artículos desde múltiples fuentes configuradas en rss_feeds.json:
    • RSS: Usa feedparser para canales RSS/Atom tradicionales.
    • Scraping web: Usa requests + BeautifulSoup con selectores CSS configurables por sitio, para medios sin feed RSS.
    • Tolerancia a fallos individuales: si un feed o scraping falla, continúa con el siguiente.
  2. Enriquecimiento de contenido — Cuando el resumen RSS de un artículo es demasiado corto para un análisis de calidad (< 150 caracteres), el agente extrae el texto completo del artículo desde su URL usando trafilatura. Procesamiento paralelo con rate limiting por dominio y caché en archivo JSON para no re-descargar URLs ya visitadas. El enriquecimiento es best-effort: si falla, se conserva el resumen RSS original sin interrumpir el pipeline.
  3. Filtrado temporal — Descarta noticias con más de 4 días (96 horas) de antigüedad: una noticia anterior ya tiene desarrollos posteriores dentro de la ventana. Configurable.
  4. Limpieza HTML — Elimina etiquetas, comentarios, scripts y decodifica entidades HTML de los resúmenes.
  5. Truncado inteligente — Recorta resúmenes a 500 caracteres sin cortar palabras a la mitad.
  6. Guardado intermedio de depuración (opcional) — Con el flag --debug, guarda un archivo JSON con los artículos procesados (resumen RSS original, contenido extraído y resumen final) para comparar y ajustar el prompt.
  7. Análisis con IA — Envía los artículos filtrados a DeepSeek-Flash con un system prompt que define la identidad editorial de La Chispa Sur (izquierda independiente, rigor periodístico, distribución 3 propuestas nacionales + 2 internacionales, foco territorial en Villarrica y La Araucanía).
  8. Reporte Markdown — Genera un archivo pauta_semanal_AAAA_MM_DD.md con cinco propuestas estructuradas (tres nacionales y dos internacionales): título gancho, enfoque editorial, puntos clave a desarrollar y fuentes sugeridas para ampliar. La cabecera (fecha y cantidad de notas) se genera automáticamente desde el código para garantizar precisión.
  9. Companion JSON de fuentes — Extrae las fuentes sugeridas desde el texto de la pauta, las empareja determinísticamente con los artículos del pipeline por nombre de medio y similitud temática (keywords), enriquece los artículos emparejados con contenido completo y guarda un archivo pauta_semanal_AAAA_MM_DD_companion.json. Este archivo permite que el redactor de artículos reciba el contenido completo de las fuentes correctas.

2. Escritura de artículo completo con fuentes verificadas

Toma una propuesta específica de la pauta (1 a 5) y la expande a un artículo de ~1000 palabras con material de origen real y verificado:

  1. Parseo de la pauta — Extrae título, enfoque editorial, puntos clave y fuentes sugeridas desde el archivo markdown generado.
  2. Emparejamiento determinista de fuentes — En lugar de depender de números de artículo auto-reportados por el LLM (poco fiables), el sistema:
    • Extrae los nombres de medios y descripciones temáticas de la sección «Fuentes Sugeridas para Ampliar» de cada propuesta.
    • Empareja cada fuente con los artículos del pipeline por nombre del medio (comparación flexible: case-insensitive, parcial, por primera palabra) y similitud temática (solapamiento de keywords entre la descripción de la fuente y el título + contenido del artículo, usando índice Jaccard con bonus por keywords en el título).
    • Enriquece los artículos emparejados con contenido completo forzando extracción vía trafilatura si es necesario.
    • Guarda un archivo companion JSON (pauta_semanal_AAAA_MM_DD_companion.json) con el contenido completo de cada artículo fuente.
  3. Prompt enriquecido — El redactor recibe una sección ## Material de origen disponible con el contenido completo de los artículos fuente correctos para su propuesta, permitiéndole escribir con datos verificables en lugar de inventar o depender de memoria.
  4. Redacción del artículo — Usa un system prompt de redactor periodístico (identidad La Chispa Sur) que exige trazabilidad de cada dato a las fuentes proporcionadas.
  5. Editor de portada — Una segunda llamada, con rol de editor de portada, devuelve tres propuestas diferenciadas de titular y bajada: denuncia/tesis política, narrativo/humano y analítico/geopolítico. Los largos se validan en código (12-16 palabras el titular, 25-45 la bajada): si el modelo se desvía se reintenta una vez y, si vuelve a fallar, se recorta por código con aviso. La propuesta 1 se aplica como titular y bajada del artículo; las tres quedan en un apéndice ## 📰 Propuestas de portada al final del archivo para cambiarlas sin repetir la generación. Si esta etapa falla, la nota se guarda igual con el titular del redactor.
  6. Artículo final — Titular y bajada de portada, lead, desarrollo por secciones con subtítulos, fuentes citadas y el apéndice de propuestas. Guardado como articulo_N_slug-del-titulo.md. El apéndice está marcado como no publicable y el parser de RRSS lo excluye del material de origen.

¿Por qué matching determinista y no números de artículo? En pruebas reales, el LLM que genera la pauta frecuentemente asigna números de artículo incorrectos en el bloque de referencias (ej: mapear una propuesta sobre tala de bosque nativo en Villarrica a artículos sobre salmonicultura o conflictos en Líbano). El matching por nombre de medio + keywords extrae las fuentes directamente del texto de la pauta —que el LLM escribe de forma natural y confiable— y las cruza con los artículos del pipeline sin depender del auto-reporte del modelo.

3. Repurposing de artículos para redes sociales (RRSS)

Toma un artículo ya publicado (articulos/articulo_N_slug.md) y produce un bundle autocontenido con todo lo necesario para publicarlo en X, Facebook e Instagram:

  1. Parseo del artículo de origen — Separa titular, firma, lead, secciones, fuentes citadas, cifras detectadas y oraciones candidatas a cita. Todo lo que se genere después se valida contra este material.

  2. Copys estructurados (LLM) — En una sola llamada obtiene y valida:

    • Hooks: de 3 a 5 titulares alternativos de máximo 120 caracteres.
    • Síntesis ejecutiva: de 3 a 5 bullets.
    • Hilo de X: de 5 a 7 tweets, con el gancho como primer tweet y límite estricto de 280 caracteres por tweet, hashtags incluidos en el cierre.
    • Post de Facebook con gancho en la primera línea (lo único visible antes del "ver más") y cierre con pregunta.
    • Caption de Instagram con gancho de apertura, cuerpo breve y CTA.
    • Tarjeta de cita, cifras clave, llamado a la acción y textos alternativos por plataforma.
  3. Prompt visual (LLM) — Genera un prompt en inglés listo para Midjourney (proporción y flags de versión incluidos). El tratamiento se decide por columna: fotorrealista documental cuando el texto reporta hechos, lugares, objetos o escenas concretas que pueden mostrarse como una fotografía plausible, y caricatura editorial (ilustración) solo cuando la columna es abstracta —un argumento, una tendencia o una metáfora— y no hay una escena documentable. Los textos breves en español siguen permitidos cuando pertenecen a la escena (letreros, pancartas, carteles, pantallas y precios), y se escriben en mayúsculas y sin comillas (PENSIONES, -10,39%): el comando se pega tal cual en Midjourney, que no interpreta comillas escapadas ni JSON. Lo que se rechaza en código son los bloques de texto (párrafos, letra pequeña, titulares largos), porque los modelos de difusión los renderizan como ruido. La salida incluye el tratamiento elegido, su justificación en español, el prompt positivo, el prompt negativo de marca y el comando completo para Midjourney, además de un .txt con solo el comando, listo para pegar.

  4. Banners locales (Pillow) — Renderiza dos plantillas en cuatro formatos, sin depender de servicios externos:

    Plantilla Contenido Formatos por defecto
    headline_card Etiqueta de marca + titular del artículo + barra inferior X 1600×900, Facebook 1200×630, IG feed 1080×1080, IG story 1080×1920
    quote_card Comilla destacada + cita + atribución IG feed 1080×1080, IG story 1080×1920

    El diseño se parametriza por un factor de escala respecto de un ancho de referencia, así que una sola implementación sirve para los cuatro tamaños. En el formato vertical respeta las zonas seguras superior e inferior (la interfaz de la plataforma las tapa). Si la marca define un logo, se recorta su padding transparente, se escala según logo_height_ratio y se pega en la esquina superior derecha; el titular se desplaza hacia abajo si el logo es más alto que la etiqueta de marca.

¿Por qué se valida todo en código y no se confía en el LLM? Las reglas duras de cada plataforma se aplican de forma determinista: recorte al límite de caracteres, largo del hilo, topes de hashtags, normalización de hashtags (#La Araucania → #LaAraucania) y retiro de los que el modelo haya dejado dentro del cuerpo del texto para no duplicarlos en el tweet de cierre, verificación de que cada cifra exista en el artículo y de que la cita sea literal. Si el modelo entrega una cita inventada, el sistema la reemplaza por una oración verificada del propio artículo. El guardarraíl es también editorial: el prompt visual debe nombrar una paleta de color, usar el tratamiento declarado —fotorrealista con lenguaje fotográfico, caricatura con técnica de ilustración— y queda acotado a rótulos breves y cifras —los párrafos de texto se rechazan en código, porque los modelos de difusión los convierten en ruido—. El fotorrealismo es el camino por defecto y las figuras públicas solo aparecen dentro de una escena documental, sin deepfake ni gestos o escenarios inventados; las víctimas, menores y personas privadas se representan de forma anónima. La caricatura queda reservada para columnas abstractas.

4. Tríptico impreso en lenguaje simple

Toma la pauta semanal completa y la convierte en una hoja oficio doblada en tres —seis paneles, doble faz— con cinco mini-notas en lenguaje simple, una por propuesta, más un panel de portada:

  1. Material de origen — De cada propuesta toma el título, el enfoque editorial, los puntos clave y las fuentes sugeridas; y del companion JSON, el contenido de las noticias que la respaldan. Si el companion falta o está corrupto, la nota se redacta solo con la pauta y el flujo continúa.
  2. Redacción en lenguaje llano (LLM) — Una sola llamada devuelve un objeto JSON con la portada y las cinco notas. Cada nota trae título, cuerpo, tres datos clave y un bloque «por qué te importa».
  3. Tope físico verificado — El cuerpo de cada nota no puede pasar de una columna y media, y eso se traduce a caracteres: 24 caracteres por línea en una columna, 36 en columna y media, 59 líneas por columna y 2.124 caracteres de techo para el bloque completo. La medición se deriva de la geometría configurada, no de una estimación a ojo.
  4. Reglas de lenguaje simple — Frases de 15 palabras o menos, ninguna sigla sin explicar, nada de jerga, trato directo al lector y una estructura fija: qué pasó, por qué te importa, los datos que lo prueban.
  5. Bundle de salida — impresos/AAAA_MM_DD_pauta-semanal/ con el tríptico en JSON, el mismo contenido en Markdown panel por panel y un manifiesto con la medición de cada nota.

¿Por qué se advierte y no se recorta? Las reglas duras se aplican de forma determinista, pero el desborde nunca se recorta: una oración larga, una sigla sin explicar o un bloque que se pasa de columna y media quedan intactos y viajan como advertencia al Markdown y al manifiesto. Un recorte automático mutila la redacción, y el ajuste final de una pieza que se imprime lo hace una persona. Lo que sí aborta la escritura es un fallo estructural —que no lleguen cinco notas o que un cuerpo venga vacío—, para no dejar en disco una pieza impublicable.

La geometría del papel, el cuerpo de la tipografía y las reglas de estilo viven en triptych_config.json, validado al cargarse: cambiar la medida de la hoja o el tope de columnas no requiere tocar código, porque el presupuesto de caracteres se recalcula solo.

5. CLI por subcomandos

El punto de entrada python -m news_agent ofrece un CLI de subcomandos pensado para el uso diario. Cada paso del flujo es un comando propio y all los encadena en una sola ejecución:

Comando Qué hace
report Genera la pauta editorial semanal desde los feeds RSS.
article Escribe una nota completa desde una propuesta de la pauta.
social Genera los bundles de redes sociales de uno o varios artículos publicados.
print Genera el tríptico impreso desde la pauta semanal.
all Ejecuta la secuencia completa: pauta → nota → redes sociales → tríptico.
clean Elimina los artefactos generados con más de N días.
# Secuencia completa: pauta, nota, redes sociales y tríptico de una sola vez
python -m news_agent all --number 1

# O cada paso por separado
python -m news_agent report
python -m news_agent article --number 2
python -m news_agent social --platforms x,instagram
python -m news_agent print

# RRSS de varios artículos: uno elegido por la terminal, uno concreto por ruta
# o todos los que haya en articulos/
python -m news_agent social --select
python -m news_agent social --article articulos/articulo_3_slug.md
python -m news_agent social --all

# Limpieza de los artefactos con más de 90 días (pide confirmación)
python -m news_agent clean --days 90

Entradas implícitas: si no se indica la pauta o el artículo, el CLI toma el más reciente del directorio correspondiente (reportes/ o articulos/). Cuando article o all no reciben --number, preguntan por la terminal qué propuesta desarrollar, mostrando los cinco titulares; en un cron hay que pasar el número siempre, porque no hay terminal. social sigue la misma regla solo con --select: sin esa bandera toma el artículo más reciente y funciona igual en un cron.

Sin argumentos no se ejecuta nada: python -m news_agent a secas muestra la ayuda y sale con código 2. Antes arrancaba la generación de pauta completa —consumiendo tokens de la API— y escribía el resultado en el directorio actual.

Nunca escribe en el directorio actual: cuando se omite --output, cada flujo usa su carpeta por defecto (reportes/, articulos/, social/ o impresos/) y la crea si no existe; una ruta que apunte al directorio actual se rechaza con un error de uso. Así la raíz del proyecto no se llena de pautas ni de bundles sueltos.

Limpieza: clean solo considera los artefactos propios de la herramienta (pautas, companion JSON, notas y bundles AAAA_MM_DD_slug). La caché de contenido (cache/) y los assets de la marca (assets/) quedan siempre fuera de su alcance. La antigüedad se ajusta con --days, el alcance con --target (incluye --yes para automatizar y --dry-run para revisar qué se borraría sin eliminar nada).

Opciones por comando

Opción Comandos Descripción
--feeds RUTA report, all JSON de configuración de feeds RSS (por defecto rss_feeds.json).
--output DIR report, article, social, print Directorio de salida (por defecto reportes/, articulos/, social/ o impresos/).
--base DIR all, clean Directorio base del proyecto, del que se derivan reportes/, articulos/, social/ e impresos/ (por defecto .).
--pauta RUTA article, print Pauta a usar (por defecto, la más reciente de reportes/).
--article RUTA social Artículo de origen (por defecto, el más reciente de articulos/). Excluyente con --all y --select.
--all social Genera un bundle por cada artículo del directorio de origen. Si uno falla, continúa con los demás y termina con código 1.
--select social Pregunta por la terminal cuál artículo procesar (requiere TTY).
--articles-dir DIR social Directorio de artículos de origen para --all y --select (por defecto articulos/).
-n, --number N article, all Propuesta a desarrollar (1 a 5). Si se omite, se pregunta por la terminal.
--platforms LISTA social, all Plataformas separadas por comas (x,facebook,instagram). Por defecto, todas.
--social-config RUTA social, all JSON de marca y plantillas (por defecto social_config.json).
--triptych-config RUTA print, all JSON de geometría, tipografía y estilo del tríptico (por defecto triptych_config.json).
--skip-banners / --skip-prompts social, all Omite los banners o el prompt visual, y con ellos la llamada al modelo que los genera.
--days N / --target / --dry-run / -y clean Antigüedad mínima, alcance, simulación y omisión de la confirmación.
--debug report, all Guarda el JSON intermedio de artículos procesados para ajustar el prompt.
--verbose todos Activa logging nivel DEBUG para diagnóstico detallado.

Modos clásicos por banderas

Se mantienen por compatibilidad con los scripts y los cron ya desplegados:

Modo Comando
Generar pauta python -m news_agent --feeds rss_feeds.json --output ./reportes
Generar pauta + debug python -m news_agent --feeds rss_feeds.json --output ./reportes --debug
Escribir artículo python -m news_agent --write-article reportes/pauta_semanal_AAAA_MM_DD.md --article 1 --output ./articulos
Repurposing para RRSS python -m news_agent --socialize articulos/articulo_1_slug.md --output ./social

Flags de los modos clásicos:

  • --verbose: Activa logging nivel DEBUG para diagnóstico detallado.
  • --output: Directorio donde guardar los archivos generados. Si se omite se usa reportes/, articulos/ o social/ según el modo, y una ruta que apunte al directorio actual se rechaza: los modos clásicos tampoco escriben en el directorio actual. El tríptico impreso solo se genera desde el subcomando print (usa impresos/ por defecto).
  • --debug: Guarda un archivo JSON intermedio en debug/articulos_procesados_YYYY_MM_DD.json con los datos completos de cada artículo (resumen RSS, contenido extraído y resumen final enviado al LLM) para depuración y ajuste de prompts.
  • --socialize RUTA_ARTICULO: Activa el modo de repurposing para redes sociales. No se puede combinar con --feeds, --debug, --write-article ni --article.
  • --platforms LISTA: Plataformas a preparar, separadas por comas (x,facebook,instagram). Por defecto, todas. Filtra los Markdown y los banners generados.
  • --social-config RUTA: Ruta al JSON de marca y plantillas (por defecto social_config.json).
  • --skip-banners: Omite el renderizado de banners con Pillow.
  • --skip-prompts: Omite la generación del prompt visual en inglés.

🏗️ Arquitectura

assets/                     # Recursos gráficos de la marca (logo de los banners)
news_agent/
├── __main__.py            # Punto de entrada CLI (subcomandos + modos clásicos)
├── cli.py                 # CLI por subcomandos: report, article, social, print, all, clean
├── cleanup.py             # Detección y borrado de artefactos antiguos del comando clean
├── orchestrator.py        # Orquestador del pipeline completo
├── config.py              # Carga de .env, validación de API key, feeds JSON
├── rss_fetcher.py         # Ingesta RSS + despacho a scraping según método
├── scraper.py             # Scraping web con requests + BeautifulSoup (selectores CSS)
├── content_enricher.py    # Extracción de texto completo con trafilatura + caché
├── news_filter.py         # Ventana temporal (96h / 4 días), limpieza HTML, truncado
├── intermediate_writer.py # Escritura de archivo JSON intermedio para depuración
├── prompt_builder.py      # Construcción de system/user prompts editoriales (~740 líneas)
├── llm_client.py          # Cliente DeepSeek vía SDK OpenAI (modo compatible)
├── report_writer.py       # Escritura de reportes .md y artículos
├── article_writer.py      # Parseo de pauta + escritura de artículo completo
├── headline_editor.py     # Editor de portada: 3 propuestas de titular y bajada
├── source_references.py   # Emparejamiento determinista de fuentes y companion JSON
└── social/                # Subsistema de repurposing para redes sociales (RRSS)
    ├── orchestrator.py    # Flujo RRSS: copys → prompt visual → banners → bundle
    ├── article_source.py  # Parseo del artículo Markdown de origen
    ├── prompt_builder.py  # Prompts de copys (ES) y del prompt visual (EN)
    ├── copy_generator.py  # Copys validados contra los límites de plataforma
    ├── visual_prompts.py  # Prompt en inglés para Midjourney, con tratamiento y flags
    ├── banner_renderer.py # Renderizado local de banners con Pillow
    ├── platform_specs.py  # Límites y formatos por plataforma
    ├── text_utils.py      # Recorte por caracteres y normalización de hashtags
    ├── json_utils.py      # Extracción defensiva de JSON de las respuestas del LLM
    ├── models.py          # Dataclasses de los artefactos del subsistema
    └── writer.py          # Escritura del bundle de salida
└── triptych/              # Subsistema de tríptico impreso
    ├── orchestrator.py    # Flujo: pauta → material de origen → tríptico → bundle
    ├── pauta_source.py    # Propuestas de la pauta y su material de respaldo
    ├── specs.py           # Presupuesto de caracteres derivado de la geometría
    ├── text_utils.py      # Reglas de lenguaje simple (oraciones, siglas, jerga)
    ├── prompt_builder.py  # Prompts con el presupuesto y el esquema de salida
    ├── generator.py       # Generación, validación y medición del tríptico
    ├── models.py          # Dataclasses de los artefactos del subsistema
    └── writer.py          # Escritura del bundle y del Markdown por panel

Stack técnico

Capa Tecnología Propósito
Ingesta RSS feedparser Parseo de canales RSS/Atom
Scraping web requests + beautifulsoup4 Extracción de artículos desde sitios sin RSS con selectores CSS configurables
Enriquecimiento trafilatura Extracción del texto completo de artículos con resúmenes RSS insuficientes
Cliente LLM openai (SDK) Conexión con DeepSeek API en modo compatible
Renderizado de assets Pillow Generación local de banners promocionales, sin servicios externos
Lenguaje Python ≥ 3.10 stdlib + 6 dependencias
Configuración .env + rss_feeds.json + social_config.json + triptych_config.json Separación de credenciales, fuentes, marca y geometría de imprenta
Testing pytest, pytest-mock, freezegun Tests unitarios para todos los módulos

Parámetros del modelo

Parámetro Valor Descripción
model deepseek-flash Modelo principal (contexto 1M, salida hasta 384K tokens)
temperature 0.1 Baja temperatura para maximizar rigurosidad factual y minimizar alucinaciones
PAUTA_MAX_TOKENS 65536 Presupuesto compartido entre razonamiento y contenido para ~1000+ noticias semanales; ampliado para que quepan las cinco propuestas
ARTICLE_MAX_TOKENS 16384 Presupuesto compartido entre razonamiento y artículo (~1000 palabras)
CONTENT_RETRY_MAX_TOKENS 8192 Presupuesto del reintento sin razonamiento cuando la respuesta llega sin contenido visible
PAUTA_REASONING_EFFORT high Razonamiento de la pauta semanal (high mantiene la profundidad; el corte se evita con el presupuesto y con la detección de finish_reason)
ARTICLE_REASONING_EFFORT high Razonamiento independiente para redacción de artículos
base_url https://api.deepseek.com/v1 Endpoint compatible OpenAI

Modo thinking y distribución de tokens

DeepSeek-Flash opera con thinking mode activado (reasoning_effort configurable por flujo). En este modo, los tokens de salida se dividen en dos campos:

  • reasoning_content: cadena de razonamiento interna (CoT) que el modelo usa para estructurar el análisis.
  • content: respuesta final visible que se escribe en el archivo de salida.

El parámetro max_tokens es el presupuesto total compartido entre ambos campos. El razonamiento típicamente consume el 60-80% del presupuesto y, en casos exigentes, puede agotarlo por completo. Para la pauta semanal se usan 64K tokens (PAUTA_MAX_TOKENS) con un esfuerzo de razonamiento high (PAUTA_REASONING_EFFORT): el razonamiento sobre cientos de noticias consume buena parte del presupuesto, por lo que el resto debe alcanzar para las cinco propuestas. Para la escritura de artículos se usan 16K tokens (ARTICLE_MAX_TOKENS) con razonamiento high: el modelo razona sobre una sola propuesta, pero ese razonamiento puede ser largo y el presupuesto debe alcanzar también para el texto final.

Si el razonamiento agota el presupuesto y content queda vacío, el cliente no devuelve reasoning_content: el razonamiento interno no es texto publicable. En su lugar, reintenta la llamada con el razonamiento desactivado y un presupuesto ampliado (CONTENT_RETRY_MAX_TOKENS), de modo que todos los tokens se destinen al contenido. El mismo mecanismo se aplica cuando la respuesta llega truncada (finish_reason="length"): con contenido visible pero cortado a mitad de frase, el cliente reintenta sin razonamiento y, si el reintento vuelve a truncarse, falla de forma explícita en lugar de escribir una pauta incompleta. Si el reintento tampoco devuelve contenido visible, la ejecución falla con un error explícito en lugar de escribir notas internas en el archivo de salida.


🚀 Instalación y uso

Requisitos

1. Clonar el repositorio

git clone <repo-url> && cd news_agent

2. Crear entorno virtual e instalar

python -m venv .venv
source .venv/bin/activate
pip install -e .

3. Configurar API key

cp .env.example .env
# Editar .env y reemplazar con tu key real:
# DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3b. Configurar temas de interés (opcional)

Puedes acotar el foco de la pauta definiendo la variable de entorno MAIN_TOPICS en .env como un array JSON de textos (con comillas dobles):

MAIN_TOPICS=["genocidio en Gaza", "Agenda de seguridad", "Retrocesos laborales"]

Cuando está definida, el agente prioriza estos temas en la selección de las cinco propuestas, con prioridad absoluta sobre la distribución 3 nacionales / 2 internacionales (que puede flexibilizarse para cubrir un tema prioritario). No es un filtro estricto: si no hay material suficiente para un tema, el agente puede cubrir otro de alto impacto o marcar "Requiere investigación adicional". Si la variable no está definida o está vacía, el agente mantiene su comportamiento habitual.

4. Configurar fuentes

Edita rss_feeds.json para agregar, quitar o modificar las fuentes de noticias. Se soportan dos métodos de ingesta:

Fuentes RSS (por defecto)

[
    {
        "name": "Nombre del Medio",
        "url": "https://ejemplo.com/rss.xml"
    }
]

Fuentes con scraping web

Para medios que no disponen de feed RSS, usa "method": "scraping" con selectores CSS:

[
    {
        "name": "Nombre del Medio",
        "url": "https://www.medio.cl",
        "method": "scraping",
        "enrich": false,
        "selectors": {
            "article": "h2:has(a[href]), h3:has(a[href])",
            "title": "a[href]",
            "link": "a[href]",
            "summary": ".excerpt, .summary",
            "date": "time, .date"
        },
        "date_regex": "/(\\d{4})/(\\d{2})/(\\d{2})/",
        "date_format": "%Y/%m/%d",
        "link_prefix": "https://www.medio.cl",
        "request_headers": {}
    }
]
Campo Obligatorio Descripción
name ✅ Nombre descriptivo del medio
url ✅ URL del sitio web a scrapear
method ✅ Debe ser "scraping" para activar scraping
enrich ❌ Controla si se extrae el contenido completo de artículos con resúmenes cortos. Por defecto true. Usar false para medios donde el scraping ya obtiene resúmenes completos y no se justifica una petición HTTP adicional (ej: El Mostrador)
min_summary_length ❌ Umbral de longitud mínima de resumen (en caracteres) por debajo del cual se intenta enriquecer. Si no se especifica, usa el default global (150)
selectors.article ✅ Selector CSS para cada contenedor de artículo
selectors.title ✅ Selector CSS para el título (dentro del contenedor)
selectors.link ❌ Selector CSS para el enlace (por defecto usa el mismo que title)
selectors.summary ❌ Selector CSS para el resumen/extracto
selectors.date ❌ Selector CSS para la fecha de publicación
date_regex ❌ Regex para extraer la fecha desde la URL del artículo (ej: /(\\d{4})/(\\d{2})/(\\d{2})/)
date_format ❌ Formato strptime para parsear la fecha extraída
link_prefix ❌ Prefijo para resolver URLs relativas
request_headers ❌ Headers HTTP adicionales para la petición

Nota: Los selectores CSS deben coincidir con la estructura HTML real del sitio. Usa las herramientas de desarrollador del navegador para identificar los selectores correctos. Si el sitio cambia su estructura, solo necesitas actualizar los selectores en el JSON, sin tocar código.

5. Ejecutar

# Secuencia completa: pauta + nota + redes sociales (pregunta qué propuesta desarrollar)
python -m news_agent all

# Secuencia completa sin preguntas, para automatizar
python -m news_agent all --number 1 --platforms x,instagram

# Paso a paso
python -m news_agent report --feeds rss_feeds.json
python -m news_agent article --number 1
python -m news_agent social --platforms x,instagram

# Generar pauta con archivo de depuración intermedio
python -m news_agent report --debug

# Solo copys y Markdown, sin llamar al modelo para el prompt visual ni renderizar banners
python -m news_agent social --skip-prompts --skip-banners

# Preparar únicamente las piezas de Instagram
python -m news_agent social --platforms instagram

# Ver qué artefactos antiguos se eliminarían, sin borrar nada
python -m news_agent clean --days 90 --dry-run

# Eliminar sin confirmación (para cron)
python -m news_agent clean --days 90 --yes

5b. Configurar la marca para RRSS (opcional)

Edita social_config.json para ajustar la identidad visual sin tocar código:

{
  "brand": {
    "name": "La Chispa Sur",
    "handle": "@lachispasur",
    "tagline": "Periodismo crítico desde el sur",
    "website": "lachispasur.cl",
    "logo_path": "assets/logo_lachispasur.png",
    "logo_height_ratio": 0.11,
    "colors": { "background": "#0E0E10", "accent": "#DF3224" },
    "fonts": { "headline": null, "body": null, "kicker": null }
  }
}
Campo Obligatorio Descripción
brand.name ✅ Nombre de la marca, usado en las etiquetas de los banners
brand.colors ✅ Paleta del diseño (background, surface, text, muted, accent, accent_alt)
brand.handle, brand.website ❌ Barra inferior de los banners
brand.logo_path ❌ Ruta a un PNG con transparencia. Si es null o el archivo no existe, el banner se genera sin logo y se advierte en el log
brand.logo_height_ratio ❌ Alto del logo como fracción del ancho del lienzo (por defecto 0.11). El ancho se limita al 22% para que no invada la etiqueta de marca
brand.fonts.* ❌ Ruta a un .ttf por rol. Si es null, se resuelven fuentes del sistema (DejaVu, Liberation, Noto o Arial) y, como último recurso, la fuente por defecto de Pillow
platforms ❌ Límites por plataforma. Sobrescriben los valores por defecto de config.py
banners.templates, banners.sizes ✅ Matriz plantilla → formatos y tamaño de cada formato
banners.safe_zone ❌ Zonas seguras superior e inferior para los formatos verticales
visual_prompts.* ✅ Tratamientos, reglas de decisión, prompt negativo, proporción y sufijo de Midjourney

Los formatos de banner se nombran con el prefijo de su plataforma (instagram_feed, instagram_story), lo que permite filtrar por --platforms sin mantener un mapa adicional. Además, la variable de entorno SOCIAL_FONT_DIR permite apuntar a un directorio propio de fuentes.

6. Ejecutar tests

pip install -e ".[dev]"
pytest

⚙️ Configuración avanzada

Las constantes principales se encuentran en news_agent/config.py y pueden ajustarse según necesidades:

Constante Valor por defecto Descripción
DEEPSEEK_MODEL "deepseek-flash" Modelo a utilizar
TEMPERATURE 0.1 Temperatura de sampling (0.0–2.0). Valor bajo para privilegiar precisión factual
PAUTA_MAX_TOKENS 65536 Límite de tokens para generación de pauta semanal (razonamiento + cinco propuestas)
ARTICLE_MAX_TOKENS 16384 Presupuesto de escritura de artículo (~1000 palabras + razonamiento)
PAUTA_REASONING_EFFORT "high" Esfuerzo de razonamiento para la pauta ("high", "medium", "max", o None para deshabilitar)
ARTICLE_REASONING_EFFORT "high" Esfuerzo de razonamiento independiente para redacción de artículos
TIME_WINDOW_HOURS 96 Ventana de análisis en horas (4 días; una noticia anterior ya tiene desarrollos posteriores dentro de la ventana)
SUMMARY_MAX_CHARS 500 Caracteres máximos por resumen. Suficiente para lead, cifras y atribuciones (reglas de precisión factual)
NUM_PROPOSALS 5 Propuestas que genera el LLM por pauta (3 nacionales + 2 internacionales)
FULL_CONTENT_FETCH_ENABLED True Control global de enriquecimiento de contenido
MIN_SUMMARY_LENGTH 150 Si el resumen RSS tiene menos de esto, se intenta extraer el texto completo
FULL_CONTENT_TIMEOUT 15 Timeout HTTP (segundos) para cada extracción de artículo
FULL_CONTENT_DELAY 1.0 Pausa entre peticiones al mismo dominio (segundos)
FULL_CONTENT_MAX_WORKERS 4 Hilos paralelos para extracción de contenido
FULL_CONTENT_CACHE_DIR Ruta absoluta a cache/ Directorio para caché de contenido extraído (resuelto relativo al paquete, cron-safe)
SOURCE_ARTICLE_MAX_CHARS 2000 Caracteres máximos de contenido fuente por artículo en el prompt del redactor
COMPANION_MAX_ARTICLES_PER_SOURCE 3 Máximo de artículos del mismo medio incluidos en el companion JSON de fuentes
SOCIAL_MAX_TOKENS 8192 Límite de tokens para la generación de copys de RRSS
SOCIAL_TEMPERATURE 0.4 Temperatura de los copys: creativa, pero fiel a los hechos del artículo
SOCIAL_VISUAL_MAX_TOKENS 4096 Límite de tokens para la generación del prompt visual
SOCIAL_JSON_MAX_RETRIES 2 Reintentos cuando el LLM no devuelve un JSON válido o completo
DEFAULT_SOCIAL_OUTPUT_DIR "social" Directorio base de los bundles de RRSS
SOCIAL_CONFIG_PATH "social_config.json" Archivo de marca y plantillas del subsistema
SOCIAL_X_MAX_CHARS 280 Límite de caracteres por tweet (se verifica en código)
SOCIAL_X_THREAD_MIN_TWEETS / _MAX_TWEETS 5 / 7 Largo del hilo de X
SOCIAL_IG_MAX_HASHTAGS 25 Tope de hashtags de Instagram
SOCIAL_MIN_ARTICLE_WORDS 150 Por debajo de esto el artículo no da material suficiente: aborta antes de llamar a la API
SOCIAL_BANNER_BASE_WIDTH 1080 Ancho de referencia del diseño de banners
TRIPTYCH_MAX_TOKENS 8192 Presupuesto de la generación del tríptico (portada + cinco notas en un solo JSON)
TRIPTYCH_TEMPERATURE 0.3 Temperatura del tríptico: sobrio y fiel a la pauta, menos creativo que el copy de RRSS
TRIPTYCH_REASONING_EFFORT "high" Razonamiento para la redacción en lenguaje simple
TRIPTYCH_JSON_MAX_RETRIES 2 Reintentos cuando la respuesta del tríptico no trae un JSON válido
TRIPTYCH_NOTE_MIN_CHARS 250 Largo mínimo de una nota; por debajo es un fallo estructural que aborta la escritura
TRIPTYCH_BLOCK_MAX_COLUMNS 1.5 Tope físico de cada nota, en columnas de la hoja oficio (se advierte, nunca se recorta)
TRIPTYCH_BODY_TARGET_CHARS 700 Largo objetivo del cuerpo de cada nota
TRIPTYCH_MAX_WORDS_PER_SENTENCE 15 Máximo de palabras por oración (lenguaje simple); el exceso viaja como advertencia
DEFAULT_PRINT_OUTPUT_DIR "impresos" Directorio base de los bundles del tríptico
TRIPTYCH_CONFIG_PATH "triptych_config.json" Archivo de geometría, tipografía y estilo del tríptico
DEFAULT_REPORTS_DIR "reportes" Directorio de salida por defecto de la pauta
DEFAULT_ARTICLES_DIR "articulos" Directorio de salida por defecto de las notas
DEFAULT_CLEAN_MAX_AGE_DAYS 30 Antigüedad mínima, en días, que elimina clean cuando no se pasa --days

Automatización con cron

Para ejecutar el agente de forma semanal (recomendado: domingo a las 23:00 o lunes a las 07:00):

# Ejemplo: todos los lunes a las 07:00 hrs, con la secuencia completa
0 7 * * 1 cd /ruta/al/news_agent && /ruta/al/.venv/bin/python -m news_agent all --number 1

# Equivalente con los modos clásicos (solo la pauta)
0 7 * * 1 cd /ruta/al/news_agent && /ruta/al/.venv/bin/python -m news_agent --feeds rss_feeds.json --output ./reportes

# Limpieza mensual sin confirmación (día 1 a las 06:00)
0 6 1 * * cd /ruta/al/news_agent && /ruta/al/.venv/bin/python -m news_agent clean --days 90 --yes

En un cron no hay terminal: all y article necesitan --number N, y clean necesita --yes.


🛡️ Manejo de errores

El agente implementa fail-safe en cada etapa del pipeline:

  • Feed caído o scraping fallido → registra el error, continúa con el siguiente medio.
  • Extracción de contenido fallida → conserva el resumen RSS original. El enriquecimiento es best-effort y nunca interrumpe el pipeline.
  • Timeout en trafilatura → timeout configurable por hilo; si se excede, se descarta la extracción y se usa el resumen RSS.
  • 0 noticias en ventana → aborta antes de llamar a la API (ahorro de tokens).
  • API key ausente → error explícito de configuración al inicio.
  • API devuelve vacío → se reintenta la llamada sin razonamiento y con más presupuesto. Si el reintento tampoco devuelve contenido visible, aborta con un mensaje claro; el razonamiento interno nunca se usa como resultado.
  • Respuesta sin estructura de artículo → si el texto no trae titular de nivel 1 y subtítulos de sección, se descarta y se aborta sin escribir archivo, para no publicar contenido inválido.
  • Directorio de salida inexistente → IOError antes de escribir.
  • Configuración de scraping inválida → error descriptivo al cargar rss_feeds.json si faltan selectores obligatorios.
  • Respuesta sin JSON válido en RRSS → se reintenta la llamada con una nota de corrección, hasta SOCIAL_JSON_MAX_RETRIES veces; el JSON se extrae de forma defensiva (bloques de código, texto alrededor, comas finales sueltas).
  • Copys incompletos → se reintenta; si se agotan los intentos, aborta sin escribir un bundle a medias.
  • Prompts visuales fallidos → el bundle se escribe igualmente con los copys y los banners; el manifiesto registra que quedaron pendientes.
  • Banner que falla al renderizar → se registra el error y el bucle continúa; el manifiesto guarda esa pieza como pendiente.
  • Fuente tipográfica ausente → se usa la fuente por defecto de Pillow y se advierte en el log.
  • Artículo demasiado corto para RRSS → aborta antes de llamar a la API (ahorro de tokens).
  • Configuración de marca inválida → error descriptivo al cargar social_config.json si falta una sección, un tamaño o una plantilla apunta a un formato inexistente.

📝 Output de ejemplo

Pauta semanal (reportes/pauta_semanal_AAAA_MM_DD.md)

# ⚡ Pauta Editorial Sugerida - La Chispa Sur
**Fecha de Generación:** 2026-07-08
**Notas Procesadas:** 200

---

## 1. [TÍTULO GANCHO DEL ARTÍCULO 1]
*   **Enfoque Editorial:** [3-5 líneas explicando el valor agregado...]
*   **Puntos Clave a Desarrollar:**
    1. [Arista de investigación 1]
    2. [Arista de investigación 2]
    3. [Ángulo crítico, proyección o pregunta abierta]
*   **Fuentes Sugeridas para Ampliar:**
    *   [Medio 1]: [Qué aporta]
    *   [Medio 2]: [Qué aporta]

## 2. [TÍTULO GANCHO DEL ARTÍCULO 2]
...

## 3. [TÍTULO GANCHO DEL ARTÍCULO 3]
...

## 4. [TÍTULO GANCHO DEL ARTÍCULO 4]
...

## 5. [TÍTULO GANCHO DEL ARTÍCULO 5]
...

Archivo de depuración (debug/articulos_procesados_YYYY_MM_DD.json)

Al usar --debug, se genera un JSON con cada artículo procesado, permitiendo comparar:

  • summary_raw: resumen RSS original
  • full_content: contenido completo extraído (si se logró enriquecer)
  • summary_clean: resumen final enviado al LLM

Archivo companion de fuentes (reportes/pauta_semanal_AAAA_MM_DD_companion.json)

Se genera automáticamente junto con la pauta. Contiene, para cada propuesta, los artículos fuente emparejados con su contenido completo:

{
  "metadata": {
    "generated_at": "2026-07-09T12:00:00",
    "total_articles_in_pipeline": 200
  },
  "proposal_1": {
    "articles": [
      {
        "title": "Condenan a empresa por tala de bosque nativo en Villarrica",
        "source": "CIPER Chile",
        "link": "https://...",
        "summary": "Resumen limpio del artículo...",
        "content": "Contenido completo extraído con trafilatura (truncado a 2000 chars)..."
      }
    ]
  },
  "proposal_2": { "articles": [...] },
  ...
  "proposal_5": { "articles": [...] }
}

Este archivo es leído automáticamente por article_writer.py al redactar un artículo, inyectando el contenido como ## Material de origen disponible en el prompt del redactor.

Artículo completo (articulos/articulo_N_slug-del-titulo.md)

Artículo de ~1000 palabras con lead periodístico, desarrollo en 3 secciones con subtítulos, y fuentes citadas al final. Ver ejemplos reales en articulos/.

Bundle de RRSS (social/AAAA_MM_DD_slug-del-titulo/)

Cada ejecución de --socialize produce una carpeta autocontenida con todo lo necesario para publicar la pieza:

social/2026_09_14_criminalizacion-de-la-disidencia/
├── social_copy.json            # Copys estructurados por plataforma, hooks, síntesis, cita y cifras
├── visual_prompt.txt           # Comando de Midjourney en texto plano, listo para pegar
├── visual_prompts.json         # Metadatos: tratamiento, justificación, prompt y negativo
├── x_thread.md                 # Hilo listo para copiar, con conteo de caracteres por tweet
├── facebook_post.md            # Post con hashtags, texto alternativo y CTA
├── instagram_caption.md        # Caption, hashtags, tarjeta de cita y advertencia si la cita no es literal
├── manifest.json               # Qué se generó, qué falló y con qué artículo se produjo
└── assets/
    ├── headline_card_x.png                 # 1600×900
    ├── headline_card_facebook.png          # 1200×630
    ├── headline_card_instagram_feed.png    # 1080×1080
    ├── headline_card_instagram_story.png   # 1080×1920
    ├── quote_card_instagram_feed.png       # 1080×1080
    └── quote_card_instagram_story.png      # 1080×1920

El campo quote_card.verbatim de social_copy.json indica si la cita se verificó palabra por palabra contra el artículo de origen; el manifiesto lo repite en verified_quote. El directorio social/ está en .gitignore, mientras que el subsistema de código vive en news_agent/social/.

Bundle del tríptico impreso (impresos/AAAA_MM_DD_pauta-semanal/)

Cada ejecución de print produce una carpeta autocontenida con el tríptico listo para maquetar. La fecha de la carpeta es la de la pauta, no la de la ejecución:

impresos/2026_09_24_pauta-semanal/
├── triptych.json               # Portada y las cinco notas, con la medición de cada una
├── triptych.md                 # El tríptico panel por panel, con el reporte de largo y las advertencias
└── manifest.json               # Pauta de origen, formato, presupuesto de caracteres y totales

El Markdown encabeza con la edición, el formato (oficio, seis paneles, monospace 12 pt), el pliegue y el tope por nota; después viene la portada, un panel por nota y, si hay algo que ajustar, el bloque de advertencias pendientes. Incluye una nota de armado que recuerda que la imposición definitiva en la hoja se confirma con la imprenta.

Las notas que superan el tope de columna y media no se recortan: se miden, se reportan en el Markdown y el manifiesto, y el texto queda intacto para el ajuste manual. El directorio impresos/ está en .gitignore, mientras que el subsistema de código vive en news_agent/triptych/.


🧪 Desarrollo

# Instalar dependencias de desarrollo
pip install -e ".[dev]"

# Ejecutar tests
pytest

# Ejecutar tests con cobertura
pytest --cov=news_agent

About

News agent

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages