theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/agente-scraper-datos/SKILL.md

@@ -0,0 +1,771 @@
+---
+name: agente-scraper-datos
+description: Construye un agente de recolección de datos totalmente automatizado para cualquier
+  fuente pública — bolsas de trabajo, precios, noticias, GitHub, deportes, lo que sea. Corre con
+  cronograma, enriquece los datos con un LLM, guarda resultados en Notion/Sheets/Supabase y aprende
+  del feedback del usuario. Corre gratis en GitHub Actions. Úsala cuando el usuario quiera
+  monitorear, recolectar o rastrear datos públicos automáticamente.
+---
+
+# Agente scraper de datos
+
+Construye un agente de recolección de datos listo para producción, potenciado con IA, para cualquier fuente de datos pública.
+Corre con cronograma, enriquece los resultados con un LLM, guarda en una base de datos y mejora con el tiempo.
+
+**Stack: Python · API de LLM (capa gratuita o de bajo costo) · GitHub Actions (gratis) · Notion / Sheets / Supabase**
+
+## Cuándo activarla
+
+- El usuario quiere recopilar o monitorear cualquier sitio web o API pública.
+- El usuario dice "construye un bot que revise...", "monitoréame X", "recolecta datos de...".
+- El usuario quiere rastrear empleos, precios, noticias, repos, marcadores deportivos, eventos, avisos.
+- El usuario pregunta cómo automatizar la recolección de datos sin pagar hosting.
+- El usuario quiere un agente que se vuelva más inteligente con base en sus decisiones.
+
+## Conceptos clave
+
+### Las tres capas
+
+Todo agente de recolección de datos tiene tres capas:
+
+```
+RECOLECTAR → ENRIQUECER → GUARDAR
+    │             │            │
+ Scraper       IA (LLM)     Base de datos
+ corre con     puntúa/       Notion /
+ cronograma    resume y      Sheets /
+               clasifica     Supabase
+```
+
+### Stack de bajo costo
+
+| Capa | Herramienta | Por qué |
+|---|---|---|
+| **Scraping** | `requests` + `BeautifulSoup` | Sin costo, cubre el 80 % de los sitios públicos |
+| **Sitios renderizados con JS** | `playwright` (gratis) | Cuando el fetch de HTML falla |
+| **Enriquecimiento con IA** | API REST de LLM del proveedor que configures | Muchos proveedores ofrecen capa gratuita o modelos ligeros muy baratos |
+| **Almacenamiento** | API de Notion | Capa gratuita, gran UI para revisar |
+| **Cronograma** | Cron de GitHub Actions | Gratis para repos públicos |
+| **Aprendizaje** | Archivo JSON de feedback en el repo | Cero infraestructura, persiste en git |
+
+### Cadena de fallback de modelos
+
+Construye el agente para hacer fallback automático entre modelos cuando se agote la cuota. Define la cadena en configuración, del modelo más ligero/barato al de respaldo:
+
+```
+modelo-ligero-preferido →
+modelo-ligero-alternativo →
+modelo-estandar →
+modelo-de-respaldo
+```
+
+### Llamadas a la API en lote para eficiencia
+
+Nunca llames al LLM una vez por ítem. Siempre agrupa:
+
+```python
+# MAL: 33 llamadas a la API para 33 ítems
+for item in items:
+    result = call_ai(item)  # 33 llamadas → golpea el límite de tasa
+
+# BIEN: 7 llamadas a la API para 33 ítems (lotes de 5)
+for batch in chunks(items, size=5):
+    results = call_ai(batch)  # 7 llamadas → se mantiene dentro de la capa gratuita
+```
+
+---
+
+## Flujo de trabajo
+
+### Paso 1: entiende el objetivo
+
+Pregunta al usuario:
+
+1. **Qué recolectar:** "¿Qué fuente de datos? ¿URL / API / RSS / endpoint público?"
+2. **Qué extraer:** "¿Qué campos importan? ¿Título, precio, URL, fecha, puntaje?"
+3. **Dónde guardar:** "¿A dónde van los resultados? ¿Notion, Google Sheets, Supabase o archivo local?"
+4. **Cómo enriquecer:** "¿Quieres que la IA puntúe, resuma, clasifique o empareje cada ítem?"
+5. **Frecuencia:** "¿Cada cuánto debe correr? ¿Cada hora, diario, semanal?"
+
+Ejemplos comunes para orientar:
+- Bolsas de trabajo → puntuar relevancia contra el CV
+- Precios de productos → alertar cuando bajen
+- Repos de GitHub → resumir releases nuevos
+- Feeds de noticias → clasificar por tema y sentimiento
+- Resultados deportivos → extraer estadísticas a un tracker
+- Calendario de eventos → filtrar por interés
+
+---
+
+### Paso 2: diseña la arquitectura de recolección
+
+Genera esta estructura de directorios para el usuario:
+
+```
+mi-agente/
+├── config.yaml              # El usuario personaliza esto (keywords, filtros, preferencias)
+├── profile/
+│   └── context.md           # Contexto del usuario que usa la IA (CV, intereses, criterios)
+├── scraper/
+│   ├── __init__.py
+│   ├── main.py              # Orquestador: scrapear → enriquecer → guardar
+│   ├── filters.py           # Pre-filtro por reglas (rápido, antes de la IA)
+│   └── sources/
+│       ├── __init__.py
+│       └── source_name.py   # Un archivo por fuente de datos
+├── ai/
+│   ├── __init__.py
+│   ├── client.py            # Cliente REST del LLM con fallback de modelos
+│   ├── pipeline.py          # Análisis de IA en lotes
+│   ├── jd_fetcher.py        # Traer el contenido completo desde las URL (opcional)
+│   └── memory.py            # Aprender del feedback del usuario
+├── storage/
+│   ├── __init__.py
+│   └── notion_sync.py       # O sheets_sync.py / supabase_sync.py
+├── data/
+│   └── feedback.json        # Historial de decisiones del usuario (auto-actualizado)
+├── .env.example
+├── setup.py                 # Creación de BD/esquema por única vez
+├── enrich_existing.py       # Rellenar puntajes de IA en filas antiguas
+├── requirements.txt
+└── .github/
+    └── workflows/
+        └── scraper.yml      # Cronograma de GitHub Actions
+```
+
+---
+
+### Paso 3: construye el conector de fuente
+
+Plantilla para cualquier fuente de datos:
+
+```python
+# scraper/sources/my_source.py
+"""
+[Nombre de la fuente] — recopila [qué] desde [dónde].
+Método: [API REST / scraping de HTML / feed RSS]
+"""
+import requests
+from bs4 import BeautifulSoup
+from datetime import datetime, timezone
+from scraper.filters import is_relevant
+
+HEADERS = {
+    "User-Agent": "Mozilla/5.0 (compatible; research-bot/1.0)",
+}
+
+
+def fetch() -> list[dict]:
+    """
+    Devuelve una lista de ítems con esquema consistente.
+    Cada ítem debe tener como mínimo: name, url, date_found.
+    """
+    results = []
+
+    # ---- Fuente de API REST ----
+    resp = requests.get("https://api.example.com/items", headers=HEADERS, timeout=15)
+    if resp.status_code == 200:
+        for item in resp.json().get("results", []):
+            if not is_relevant(item.get("title", "")):
+                continue
+            results.append(_normalise(item))
+
+    return results
+
+
+def _normalise(raw: dict) -> dict:
+    """Convierte los datos crudos de API/HTML al esquema estándar."""
+    return {
+        "name": raw.get("title", ""),
+        "url": raw.get("link", ""),
+        "source": "MySource",
+        "date_found": datetime.now(timezone.utc).date().isoformat(),
+        # agrega aquí campos específicos del dominio
+    }
+```
+
+**Patrón de fetch de HTML:**
+```python
+soup = BeautifulSoup(resp.text, "lxml")
+for card in soup.select("[class*='listing']"):
+    title = card.select_one("h2, h3").get_text(strip=True)
+    link = card.select_one("a")["href"]
+    if not link.startswith("http"):
+        link = f"https://example.com{link}"
+```
+
+**Patrón de feed RSS:**
+```python
+import xml.etree.ElementTree as ET
+root = ET.fromstring(resp.text)
+for item in root.findall(".//item"):
+    title = item.findtext("title", "")
+    link = item.findtext("link", "")
+```
+
+---
+
+### Paso 4: construye el cliente del LLM
+
+Cliente genérico contra un endpoint estilo *chat completions* (la mayoría de proveedores y pasarelas exponen uno compatible; configura URL, clave y modelos por variables de entorno):
+
+```python
+# ai/client.py
+import os, json, time, requests
+
+_last_call = 0.0
+
+# Cadena de fallback: del modelo más barato al de respaldo.
+# Se configura por entorno, p. ej. LLM_MODELS="modelo-lite,modelo-estandar"
+def _model_chain() -> list[str]:
+    raw = os.environ.get("LLM_MODELS", "")
+    return [m.strip() for m in raw.split(",") if m.strip()]
+
+
+def generate(prompt: str, model: str = "", rate_limit: float = 7.0) -> dict:
+    """Llama al LLM con fallback automático ante 429. Devuelve JSON parseado o {}."""
+    global _last_call
+
+    api_key = os.environ.get("LLM_API_KEY", "")
+    base_url = os.environ.get("LLM_API_URL", "")  # p. ej. https://<proveedor>/v1/chat/completions
+    if not api_key or not base_url:
+        return {}
+
+    elapsed = time.time() - _last_call
+    if elapsed < rate_limit:
+        time.sleep(rate_limit - elapsed)
+
+    chain = _model_chain()
+    models = [model] + [m for m in chain if m != model] if model else chain
+    _last_call = time.time()
+
+    for m in models:
+        payload = {
+            "model": m,
+            "messages": [{"role": "user", "content": prompt}],
+            "response_format": {"type": "json_object"},
+            "temperature": 0.3,
+            "max_tokens": 2048,
+        }
+        try:
+            resp = requests.post(
+                base_url,
+                json=payload,
+                headers={"Authorization": f"Bearer {api_key}"},
+                timeout=30,
+            )
+            if resp.status_code == 200:
+                return _parse(resp)
+            if resp.status_code in (429, 404):
+                time.sleep(1)
+                continue
+            return {}
+        except requests.RequestException:
+            return {}
+
+    return {}
+
+
+def _parse(resp) -> dict:
+    try:
+        text = (
+            resp.json()
+            .get("choices", [{}])[0]
+            .get("message", {})
+            .get("content", "")
+            .strip()
+        )
+        if text.startswith("```"):
+            text = text.split("\n", 1)[-1].rsplit("```", 1)[0]
+        return json.loads(text)
+    except (json.JSONDecodeError, KeyError):
+        return {}
+```
+
+---
+
+### Paso 5: construye el pipeline de IA (en lotes)
+
+```python
+# ai/pipeline.py
+import json
+import yaml
+from pathlib import Path
+from ai.client import generate
+
+def analyse_batch(items: list[dict], context: str = "", preference_prompt: str = "") -> list[dict]:
+    """Analiza ítems en lotes. Devuelve los ítems enriquecidos con campos de IA."""
+    config = yaml.safe_load((Path(__file__).parent.parent / "config.yaml").read_text())
+    model = config.get("ai", {}).get("model", "")
+    rate_limit = config.get("ai", {}).get("rate_limit_seconds", 7.0)
+    min_score = config.get("ai", {}).get("min_score", 0)
+    batch_size = config.get("ai", {}).get("batch_size", 5)
+
+    batches = [items[i:i + batch_size] for i in range(0, len(items), batch_size)]
+    print(f"  [IA] {len(items)} ítems → {len(batches)} llamadas a la API")
+
+    enriched = []
+    for i, batch in enumerate(batches):
+        print(f"  [IA] Lote {i + 1}/{len(batches)}...")
+        prompt = _build_prompt(batch, context, preference_prompt, config)
+        result = generate(prompt, model=model, rate_limit=rate_limit)
+
+        analyses = result.get("analyses", [])
+        for j, item in enumerate(batch):
+            ai = analyses[j] if j < len(analyses) else {}
+            if ai:
+                score = max(0, min(100, int(ai.get("score", 0))))
+                if min_score and score < min_score:
+                    continue
+                enriched.append({**item, "ai_score": score, "ai_summary": ai.get("summary", ""), "ai_notes": ai.get("notes", "")})
+            else:
+                enriched.append(item)
+
+    return enriched
+
+
+def _build_prompt(batch, context, preference_prompt, config):
+    priorities = config.get("priorities", [])
+    items_text = "\n\n".join(
+        f"Item {i+1}: {json.dumps({k: v for k, v in item.items() if not k.startswith('_')})}"
+        for i, item in enumerate(batch)
+    )
+
+    return f"""Analiza estos {len(batch)} ítems y devuelve un objeto JSON.
+
+# Ítems
+{items_text}
+
+# Contexto del usuario
+{context[:800] if context else "No provisto"}
+
+# Prioridades del usuario
+{chr(10).join(f"- {p}" for p in priorities)}
+
+{preference_prompt}
+
+# Instrucciones
+Devuelve: {{"analyses": [{{"score": <0-100>, "summary": "<2 oraciones>", "notes": "<por qué encaja o no>"}} por cada ítem en orden]}}
+Sé conciso. Puntaje 90+=encaje excelente, 70-89=bueno, 50-69=aceptable, <50=débil."""
+```
+
+---
+
+### Paso 6: construye el sistema de aprendizaje por feedback
+
+```python
+# ai/memory.py
+"""Aprende de las decisiones del usuario para mejorar la puntuación futura."""
+import json
+from pathlib import Path
+
+FEEDBACK_PATH = Path(__file__).parent.parent / "data" / "feedback.json"
+
+
+def load_feedback() -> dict:
+    if FEEDBACK_PATH.exists():
+        try:
+            return json.loads(FEEDBACK_PATH.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {"positive": [], "negative": []}
+
+
+def save_feedback(fb: dict):
+    FEEDBACK_PATH.parent.mkdir(parents=True, exist_ok=True)
+    FEEDBACK_PATH.write_text(json.dumps(fb, indent=2))
+
+
+def build_preference_prompt(feedback: dict, max_examples: int = 15) -> str:
+    """Convierte el historial de feedback en una sección de sesgo del prompt."""
+    lines = []
+    if feedback.get("positive"):
+        lines.append("# Ítems que al usuario le GUSTARON (señal positiva):")
+        for e in feedback["positive"][-max_examples:]:
+            lines.append(f"- {e}")
+    if feedback.get("negative"):
+        lines.append("\n# Ítems que el usuario OMITIÓ/RECHAZÓ (señal negativa):")
+        for e in feedback["negative"][-max_examples:]:
+            lines.append(f"- {e}")
+    if lines:
+        lines.append("\nUsa estos patrones para sesgar la puntuación de ítems nuevos.")
+    return "\n".join(lines)
+```
+
+**Integración con tu capa de almacenamiento:** después de cada corrida, consulta tu BD por ítems con estado positivo/negativo y llama a `save_feedback()` con los patrones extraídos.
+
+---
+
+### Paso 7: construye el almacenamiento (ejemplo con Notion)
+
+```python
+# storage/notion_sync.py
+import os
+from notion_client import Client
+from notion_client.errors import APIResponseError
+
+_client = None
+
+def get_client():
+    global _client
+    if _client is None:
+        _client = Client(auth=os.environ["NOTION_TOKEN"])
+    return _client
+
+def get_existing_urls(db_id: str) -> set[str]:
+    """Trae todas las URL ya guardadas — se usa para deduplicar."""
+    client, seen, cursor = get_client(), set(), None
+    while True:
+        resp = client.databases.query(database_id=db_id, page_size=100, **{"start_cursor": cursor} if cursor else {})
+        for page in resp["results"]:
+            url = page["properties"].get("URL", {}).get("url", "")
+            if url: seen.add(url)
+        if not resp["has_more"]: break
+        cursor = resp["next_cursor"]
+    return seen
+
+def push_item(db_id: str, item: dict) -> bool:
+    """Empuja un ítem a Notion. Devuelve True si tuvo éxito."""
+    props = {
+        "Name": {"title": [{"text": {"content": item.get("name", "")[:100]}}]},
+        "URL": {"url": item.get("url")},
+        "Source": {"select": {"name": item.get("source", "Unknown")}},
+        "Date Found": {"date": {"start": item.get("date_found")}},
+        "Status": {"select": {"name": "New"}},
+    }
+    # Campos de IA
+    if item.get("ai_score") is not None:
+        props["AI Score"] = {"number": item["ai_score"]}
+    if item.get("ai_summary"):
+        props["Summary"] = {"rich_text": [{"text": {"content": item["ai_summary"][:2000]}}]}
+    if item.get("ai_notes"):
+        props["Notes"] = {"rich_text": [{"text": {"content": item["ai_notes"][:2000]}}]}
+
+    try:
+        get_client().pages.create(parent={"database_id": db_id}, properties=props)
+        return True
+    except APIResponseError as e:
+        print(f"[notion] Falló el push: {e}")
+        return False
+
+def sync(db_id: str, items: list[dict]) -> tuple[int, int]:
+    existing = get_existing_urls(db_id)
+    added = skipped = 0
+    for item in items:
+        if item.get("url") in existing:
+            skipped += 1; continue
+        if push_item(db_id, item):
+            added += 1; existing.add(item["url"])
+        else:
+            skipped += 1
+    return added, skipped
+```
+
+---
+
+### Paso 8: orquesta en main.py
+
+```python
+# scraper/main.py
+import os, sys, yaml
+from pathlib import Path
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from scraper.sources import my_source          # agrega tus fuentes
+
+# NOTA: este ejemplo usa Notion. Si storage.provider es "sheets" o "supabase",
+# reemplaza este import por storage.sheets_sync o storage.supabase_sync y actualiza
+# la variable de entorno y la llamada a sync() en consecuencia.
+from storage.notion_sync import sync
+
+SOURCES = [
+    ("Mi fuente", my_source.fetch),
+]
+
+def ai_enabled():
+    return bool(os.environ.get("LLM_API_KEY"))
+
+def main():
+    config = yaml.safe_load((Path(__file__).parent.parent / "config.yaml").read_text())
+    provider = config.get("storage", {}).get("provider", "notion")
+
+    # Resuelve el identificador del destino de almacenamiento desde el entorno según el proveedor
+    if provider == "notion":
+        db_id = os.environ.get("NOTION_DATABASE_ID")
+        if not db_id:
+            print("ERROR: NOTION_DATABASE_ID no está definido"); sys.exit(1)
+    else:
+        # Extiende aquí para sheets (SHEET_ID) o supabase (SUPABASE_TABLE), etc.
+        print(f"ERROR: el proveedor '{provider}' aún no está cableado en main.py"); sys.exit(1)
+
+    all_items = []
+
+    for name, fetch_fn in SOURCES:
+        try:
+            items = fetch_fn()
+            print(f"[{name}] {len(items)} ítems")
+            all_items.extend(items)
+        except Exception as e:
+            print(f"[{name}] FALLÓ: {e}")
+
+    # Deduplicar por URL
+    seen, deduped = set(), []
+    for item in all_items:
+        if (url := item.get("url", "")) and url not in seen:
+            seen.add(url); deduped.append(item)
+
+    print(f"Ítems únicos: {len(deduped)}")
+
+    if ai_enabled() and deduped:
+        from ai.memory import load_feedback, build_preference_prompt
+        from ai.pipeline import analyse_batch
+
+        # load_feedback() lee data/feedback.json escrito por tu script de sync de feedback.
+        # Para mantenerlo al día, implementa un feedback_sync.py aparte que consulte tu
+        # proveedor de almacenamiento por ítems con estados positivos/negativos y llame a save_feedback().
+        feedback = load_feedback()
+        preference = build_preference_prompt(feedback)
+        context_path = Path(__file__).parent.parent / "profile" / "context.md"
+        context = context_path.read_text() if context_path.exists() else ""
+        deduped = analyse_batch(deduped, context=context, preference_prompt=preference)
+    else:
+        print("[IA] Omitida — LLM_API_KEY no está definida")
+
+    added, skipped = sync(db_id, deduped)
+    print(f"Listo — {added} nuevos, {skipped} existentes")
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+### Paso 9: workflow de GitHub Actions
+
+```yaml
+# .github/workflows/scraper.yml
+name: Agente scraper de datos
+
+on:
+  schedule:
+    - cron: "0 */3 * * *"  # cada 3 horas — ajústalo a tu necesidad
+  workflow_dispatch:        # permitir disparo manual
+
+permissions:
+  contents: write   # requerido para el paso de commit del historial de feedback
+
+jobs:
+  scrape:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - run: pip install -r requirements.txt
+
+      # Descomenta si Playwright está habilitado en requirements.txt
+      # - name: Instalar navegadores de Playwright
+      #   run: python -m playwright install chromium --with-deps
+
+      - name: Ejecutar agente
+        env:
+          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
+          NOTION_DATABASE_ID: ${{ secrets.NOTION_DATABASE_ID }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_API_URL: ${{ secrets.LLM_API_URL }}
+          LLM_MODELS: ${{ secrets.LLM_MODELS }}
+        run: python -m scraper.main
+
+      - name: Commit del historial de feedback
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add data/feedback.json || true
+          git diff --cached --quiet || git commit -m "chore: actualizar historial de feedback"
+          git push
+```
+
+---
+
+### Paso 10: plantilla de config.yaml
+
+```yaml
+# Personaliza este archivo — sin cambios de código
+
+# Qué recolectar (pre-filtro antes de la IA)
+filters:
+  required_keywords: []      # el ítem debe contener al menos una
+  blocked_keywords: []       # el ítem no debe contener ninguna
+
+# Tus prioridades — la IA las usa para puntuar
+priorities:
+  - "ejemplo de prioridad 1"
+  - "ejemplo de prioridad 2"
+
+# Almacenamiento
+storage:
+  provider: "notion"         # notion | sheets | supabase | sqlite
+
+# Aprendizaje por feedback
+feedback:
+  positive_statuses: ["Saved", "Applied", "Interested"]
+  negative_statuses: ["Skip", "Rejected", "Not relevant"]
+
+# Configuración de IA
+ai:
+  enabled: true
+  model: ""                  # vacío = usar el primero de la cadena LLM_MODELS
+  min_score: 0               # descartar ítems por debajo de este puntaje
+  rate_limit_seconds: 7      # segundos entre llamadas a la API
+  batch_size: 5              # ítems por llamada a la API
+```
+
+---
+
+## Patrones comunes de scraping
+
+### Patrón 1: API REST (el más fácil)
+```python
+resp = requests.get(url, params={"q": query}, headers=HEADERS, timeout=15)
+items = resp.json().get("results", [])
+```
+
+### Patrón 2: scraping de HTML
+```python
+soup = BeautifulSoup(resp.text, "lxml")
+for card in soup.select(".listing-card"):
+    title = card.select_one("h2").get_text(strip=True)
+    href = card.select_one("a")["href"]
+```
+
+### Patrón 3: feed RSS
+```python
+import xml.etree.ElementTree as ET
+root = ET.fromstring(resp.text)
+for item in root.findall(".//item"):
+    title = item.findtext("title", "")
+    link = item.findtext("link", "")
+    pub_date = item.findtext("pubDate", "")
+```
+
+### Patrón 4: API paginada
+```python
+page = 1
+while True:
+    resp = requests.get(url, params={"page": page, "limit": 50}, timeout=15)
+    data = resp.json()
+    items = data.get("results", [])
+    if not items:
+        break
+    for item in items:
+        results.append(_normalise(item))
+    if not data.get("has_more"):
+        break
+    page += 1
+```
+
+### Patrón 5: páginas renderizadas con JS (Playwright)
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    page = browser.new_page()
+    page.goto(url)
+    page.wait_for_selector(".listing")
+    html = page.content()
+    browser.close()
+
+soup = BeautifulSoup(html, "lxml")
+```
+
+---
+
+## Antipatrones a evitar
+
+| Antipatrón | Problema | Corrección |
+|---|---|---|
+| Una llamada al LLM por ítem | Golpea los límites de tasa al instante | Lotes de 5 ítems por llamada |
+| Keywords hardcodeadas en el código | No reutilizable | Mover toda la config a `config.yaml` |
+| Scraping sin límite de tasa | Baneo de IP | Añadir `time.sleep(1)` entre peticiones |
+| Guardar secretos en el código | Riesgo de seguridad | Siempre `.env` + GitHub Secrets |
+| Sin deduplicación | Se acumulan filas duplicadas | Verificar siempre la URL antes de empujar |
+| Ignorar `robots.txt` | Riesgo legal/ético | Respetar las reglas de rastreo; usar APIs públicas cuando existan |
+| Sitios con JS usando `requests` | Respuesta vacía | Usar Playwright o buscar la API subyacente |
+| `max_tokens` demasiado bajo | JSON truncado, error de parseo | Usar 2048+ para respuestas en lote |
+
+---
+
+## Referencia de límites de capas gratuitas
+
+| Servicio | Límite gratuito | Uso típico |
+|---|---|---|
+| API de LLM (capa gratuita) | Depende del proveedor — verifica RPM/RPD antes de fijar `rate_limit_seconds` | ~56 llamadas/día a intervalos de 3 h con lotes de 5 |
+| GitHub Actions | Ilimitado (repos públicos) | ~20 min/día |
+| API de Notion | Ilimitado | ~200 escrituras/día |
+| Supabase | 500 MB de BD, 2 GB de transferencia | Suficiente para la mayoría de agentes |
+| API de Google Sheets | 300 req/min | Funciona para agentes pequeños |
+
+---
+
+## Plantilla de requirements
+
+```
+requests==2.31.0
+beautifulsoup4==4.12.3
+lxml==5.1.0
+python-dotenv==1.0.1
+pyyaml==6.0.2
+notion-client==2.2.1   # si usas Notion
+# playwright==1.40.0   # descomenta para sitios renderizados con JS
+```
+
+---
+
+## Checklist de calidad
+
+Antes de dar el agente por terminado:
+
+- [ ] `config.yaml` controla toda la configuración del usuario — sin valores hardcodeados
+- [ ] `profile/context.md` guarda el contexto del usuario para el matching con IA
+- [ ] Deduplicación por URL antes de cada push al almacenamiento
+- [ ] El cliente del LLM tiene cadena de fallback de modelos configurable
+- [ ] Tamaño de lote ≤ 5 ítems por llamada a la API
+- [ ] `max_tokens` ≥ 2048
+- [ ] `.env` está en `.gitignore`
+- [ ] `.env.example` provisto para el onboarding
+- [ ] `setup.py` crea el esquema de la BD en la primera corrida
+- [ ] `enrich_existing.py` rellena puntajes de IA en filas antiguas
+- [ ] El workflow de GitHub Actions hace commit de `feedback.json` tras cada corrida
+- [ ] El README cubre: setup en < 5 minutos, secretos requeridos, personalización
+
+---
+
+## Ejemplos del mundo real
+
+```
+"Constrúyeme un agente que monitoree Hacker News por noticias de financiamiento de startups de IA"
+"Scrapea precios de productos de 3 e-commerce y alerta cuando bajen"
+"Rastrea repos nuevos de GitHub con etiqueta 'llm' o 'agents' — resume cada uno"
+"Recolecta avisos de trabajo de Chief of Staff de LinkedIn y Cutshort hacia Notion"
+"Monitorea un subreddit por posts que mencionen mi empresa — clasifica el sentimiento"
+"Scrapea papers académicos nuevos de arXiv sobre un tema que me interesa, a diario"
+"Rastrea resultados de partidos y mantén una tabla al día en Google Sheets"
+"Construye un vigilante de avisos inmobiliarios — alerta sobre propiedades nuevas bajo cierto precio"
+```
+
+---
+
+## Implementación de referencia
+
+Un agente completo construido con esta misma arquitectura recolectaría de 4+ fuentes,
+agruparía las llamadas al LLM en lotes, aprendería de las decisiones Applied/Rejected guardadas en Notion
+y correría gratis en GitHub Actions. Sigue los pasos 1–9 de arriba para construir el tuyo.