# 🐦 Twitter Agent

Un agente personal para vigilar cuentas de X (Twitter), rankear sus tweets más
relevantes y generar un **resumen del TOP**. Pensado para uso personal, con las
fuentes de datos y el motor de IA **intercambiables** (sin tocar el código).

## Estado actual

- ✅ Dashboard web (Streamlit) con 3 pestañas: **TOP**, **Resumen** y **Cuentas**.
- ✅ Ranking por engagement + frescura + temas, totalmente configurable.
- ✅ Resumen extractivo sin IA (gratis).
- ✅ **Datos de ejemplo** (`mock`): coste 0, sin login, sin riesgo.
- ✅ **Datos reales** (`syndication`): tweets reales de X **sin login ni API key** (gratis).
- 🔜 Resúmenes con Claude.

## Cómo ejecutarlo

```bash
cd ~/Desktop/Twitter-Agent
python3.12 -m venv .venv        # ya creado; solo la primera vez
source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py
```

Se abrirá en el navegador (normalmente http://localhost:8501).

## Datos reales (gratis) con `syndication`

El proveedor `syndication` usa el endpoint público que X ofrece para incrustar
timelines. **No necesita login, ni API key, ni cuenta secundaria** → es gratis y
no toca tu cuenta personal.

Para activarlo: en la barra lateral del dashboard, cambia **Fuente de datos** a
`syndication` (o pon `provider: syndication` en `config.yaml`).

Pruébalo en vivo sin abrir el dashboard:

```bash
.venv/bin/python run_real.py
```

**Cosas a saber (limitaciones reales de esta vía gratuita):**

- **Frescura por cuenta:** X devuelve datos frescos para muchas cuentas, pero para
  algunas sirve un **caché antiguo**. Las cuentas "viejas" simplemente no aportan
  tweets a la ventana de tiempo (el dashboard te avisa de cuáles quedan vacías).
- **Rate-limit (429):** si pides muchas cuentas muy rápido, X corta temporalmente.
  Por eso hay una pausa entre peticiones (`syndication_delay_seconds`, 6s por
  defecto). Para un digest 1–2 veces al día no es problema.

## Configuración

Todo se ajusta en [`config.yaml`](config.yaml): proveedor, motor de resúmenes,
ventana de tiempo, cuántos TOP, peso de la frescura, temas y los ajustes de
`syndication`. Tu lista de cuentas vive en [`data/accounts.json`](data/accounts.json)
(editable también desde la pestaña **Cuentas**).

## Estructura

```
app.py                      # Dashboard Streamlit
run_real.py                 # Prueba en vivo del proveedor syndication
smoke_test.py               # Prueba del flujo con datos de ejemplo
test_syndication.py         # Test de parseo (sin red)
config.yaml                 # Ajustes
data/accounts.json          # Cuentas vigiladas
agent/
  models.py                 # Tweet, Account
  config.py                 # Carga de config
  ranking.py                # Puntuación y selección del TOP
  store.py                  # Guardar/cargar cuentas
  registry.py               # Elige proveedor y resumidor según config
  providers/
    base.py                 # Interfaz TweetProvider
    mock.py                 # Datos de ejemplo
    syndication.py          # Datos reales de X (sin login)
  summarizers/
    base.py                 # Interfaz Summarizer
    simple.py               # Resumen extractivo
```

## Hoja de ruta

1. **Resúmenes con Claude** — `ClaudeSummarizer` enchufable (mejor redacción).
2. **Refuerzo de datos** — para cuentas con caché viejo, `twikit` con cuenta
   secundaria (no la principal) como respaldo opcional.
3. **Fase 2: tu cuenta** — importar a quién sigues vía API oficial (OAuth).
4. **Envío automático** — un digest diario por email o a un archivo.
```