meta-optimizer-formacion/CLAUDE.md

Meta Optimizer Formación — Documentación del Proyecto

Agente autónomo de optimización de campañas Meta Ads (Facebook/Instagram) para los cursos de formación (RoiFormacion_*), hermano de meta-optimizer (que gestiona las campañas VIVIFUL_* de la misma cuenta de Meta).

A diferencia de Viviful, aquí el modelo de negocio no es "CPL objetivo por vertical" sino PPL (precio por lead) + capping mensual por curso, el mismo modelo que usa leads-optimizer para gestionar los mismos cursos en Google Ads.

---

Por qué existe este proyecto (y no una copia más de Viviful)

• El número que sigue a RoiFormacion_ en el nombre de la campaña de Meta (RoiFormacion_884_Curso_Desarrollador_leadads → 884) es el mismo CursoID que usa leads-optimizer en Airtable.
• Los leads de Meta ya llegan hoy a la tabla Leads Lake de Airtable (attr_utm_source='Lead ads', attr_cursoid resuelto) — el capping mensual por curso (CursoMes.Caping Admitido) ya se consume con leads de Meta y de Google combinados, aunque hasta ahora nada lo controlaba desde el lado de Meta.
• El campo Familia (desde Familias) en la tabla Cursos de Airtable ya da la segmentación temática que sustituye al concepto de "vertical" de Viviful.

Por eso la arquitectura se reparte en dos sistemas, no uno:

• Airtable (compartido con leads-optimizer, misma base): la capa de negocio — Cursos, Familias, CentroCurso, CursoMes (capping, solo lectura), Leads Lake (solo lectura), y las tablas nuevas específicas de Meta: Meta Ads Campaigns y MetaCampaignMes (análogas a Google Ads Campaigns / GACampaignMes). El capping es un recurso compartido entre canales — vive en un solo sitio para que Meta y Google no se pisen al consumirlo.
• Baserow (misma instancia self-hosted que Viviful, tablas nuevas): todo lo operativo específico de Meta que Google no tiene — desglose diario por adset/anuncio, propuestas de acción (incluida la pausa de anuncios individuales), análisis visual de creatividades, logs de ejecución.

---

Arquitectura general

Meta Ads API                          Airtable (compartido con leads-optimizer)
    │                                      │  Cursos / Familias / CentroCurso
    ▼                                      │  CursoMes (capping) / Leads Lake
run.py ──► agent.py (Claude Haiku) ◄───────┤  (solo lectura)
    │            │                         │
    │            ▼                         └─► Meta Ads Campaigns / MetaCampaignMes
    │      analyzer.py (PPL + capping,          (catálogo + estado mensual, r/w)
    │       urgencia/ritmo/margen)
    │
    └──────────────────────────────────► Baserow (snapshots, acciones, creatividades, logs)
                                                │
                                          Slack (informe + aprobación)
                                                │
                                    approval_server.py (FastAPI, puerto propio)
                                                │
                                           Baserow (ejecutar acción)
                                                │
                                         Meta Ads API (aplicar)

---

Componentes

run.py — Orquestador principal

1. Carga PPL/capping/familia por curso desde Airtable (build_campaign_lookups).
2. Sincroniza el catálogo Meta → Airtable (Meta Ads Campaigns, MetaCampaignMes).
3. Para cada campaña RoiFormacion_* ACTIVA en Meta:
   • Cuenta leads del mes vía Leads Lake (get_leads_this_month_meta).
   • analyzer.analyze() calcula urgencia/ritmo/margen/rentabilidad.
   • agent.decide() propone acción (PAUSE / REDUCE_BUDGET / INCREASE_BUDGET / MAINTAIN).
   • Analiza top-5 adsets (3d) y top-5 anuncios activos (3d+7d) — igual que Viviful.
   • Guarda snapshot diario en Baserow, actualiza MetaCampaignMes (consejo/criticidad/leads).
4. Envía informe a Slack agrupado por Familia.
5. Si DRY_RUN=false: ejecuta acciones aprobadas del día anterior.

Modo: DRY_RUN=true por defecto.

---

analyzer.py — Motor de negocio (puerto de leads-optimizer)

Fórmulas de capping/PPL/ritmo, agnósticas de canal:

• ratio_leads = leads_entregados / capping, ritmo = ratio_leads - ratio_mes.
• margen = (leads_entregados × PPL − gasto) / (leads_entregados × PPL).
• Urgencia: PAUSAR (cap consumido) → SPRINT (atrasado, quedan pocos días) → ACELERAR / FRENAR (según ritmo) → EN_RITMO.

agent.py — Agente de decisión (Claude Haiku/Sonnet)

• decide(analysis): traduce la urgencia/rentabilidad de analyzer.py a las mismas acciones que ya usa Viviful (PAUSE/REDUCE_BUDGET/INCREASE_BUDGET/MAINTAIN), para no tener que tocar baserow_client.py, slack_notifier.py ni approval_server.py.
• analyze_unit(metrics, level): igual que Viviful — granularidad táctica de adset/anuncio a 3d/7d, comparando contra cpa_maximo (= PPL × 0.70) en vez de max_cpl.
• analyze_creative / analyze_creative_deep / compare_adset_creatives: idénticas a Viviful, no dependen del modelo de negocio.

meta_ads_client.py

Copia casi literal de Viviful. Único añadido: get_all_campaigns() (lista completa de campañas RoiFormacion_* independientemente del gasto, necesaria para sincronizar el catálogo de Airtable).

airtable_client.py

Cliente de la base compartida con leads-optimizer. Solo lee Cursos / CentroCurso / CursoMes (el catálogo de cursos se mantiene externamente, igual que en leads-optimizer). Lee y escribe Meta Ads Campaigns y MetaCampaignMes.

extract_cursoid(campaign_name) — regex roiformaci[oó]n_?(\d+), tolerante a variantes sin guion bajo tras el número (RoiFormacion_1281Instaladores_...).

baserow_client.py

Igual que Viviful salvo que no existen las tablas campaigns ni verticals (sustituidas por Airtable). daily_snapshots usa el campo familia en vez de vertical.

slack_notifier.py

Mismo patrón multi-mensaje que Viviful, agrupado por Familia en vez de vertical. No hay un "CPL objetivo" único por familia (cada curso tiene su propio PPL), así que las tarjetas de campaña muestran urgencia, ritmo y leads-consumidos/capping en vez de "CPL vs objetivo".

approval_server.py

Copia literal de Viviful. Se despliega por separado, en otro puerto de roiserver.com, apuntando a las tablas Baserow de este proyecto.

---

Base de datos

Airtable (compartida con leads-optimizer)

Tabla	Uso	Acceso
Cursos	Catálogo de cursos, CursoID, Familia	solo lectura
CentroCurso	PPL y % invalidación por centro	solo lectura
CursoMes	Capping mensual por curso (compartido Meta+Google)	solo lectura
Leads Lake	Leads de todos los canales (attr_utm_source='Lead ads' = Meta)	solo lectura
Meta Ads Campaigns	Catálogo de campañas de Meta	lectura/escritura
MetaCampaignMes	Estado mensual: PPL, cap, coste, leads, consejo, criticidad	lectura/escritura

Aprovisionar con python setup_airtable_meta_tables.py (una sola vez; requiere token con scope schema.bases:write; ⚠️ modifica una base ya en producción).

Baserow (misma instancia self-hosted que Viviful, tablas nuevas)

Tabla	Contenido
proposed_actions	Acciones propuestas (campañas y anuncios). Estados: pending → approved/rejected → executed
creative_analyses	Análisis visual de creatividades
daily_snapshots	Snapshot diario por campaña: métricas + decisión + familia + adsets_json + ads_json
execution_logs	Log de cada ejecución

Aprovisionar con python setup_baserow.py (una sola vez).

---

Variables de entorno (.env)

Ver .env.example. Reutiliza las credenciales de Meta/Anthropic/Slack de meta-optimizer (misma cuenta de Meta, mismo bot de Slack con canal distinto) y las de Airtable de leads-optimizer (misma base).

---

Automatización (GitHub Actions)

.github/workflows/daily.yml — cron propuesto unas horas antes que el de Viviful para no competir por rate limit de la misma cuenta de Meta. schedule comentado por defecto (ejecución manual con workflow_dispatch).

---

Notas de implementación importantes

• Capping compartido entre canales: CursoMes.Caping Admitido lo consumen Meta y Google a la vez. Si un curso corre en ambos canales simultáneamente, cualquier cambio en cómo se cuenta el consumo debe revisarse en los dos proyectos (meta-optimizer-formacion y leads-optimizer).
• margin vs margen_pct: en run.py, margin (€) es un proxy diario tipo Viviful (leads × PPL − gasto) para las tablas de Slack/Baserow; margen_pct es la rentabilidad acumulada del mes que calcula analyzer.py ((ingreso − gasto) / ingreso). No son la misma magnitud, no sumar una con otra.
• send_slack_report.py reconstruye desde snapshots de Baserow, que no guardan urgencia/leads_mes/capping — al reenviar un informe esos campos salen con su valor por defecto (no es un bug, es una limitación conocida, igual que bid_config={} en la versión de Viviful).
• Regex de CursoID: roiformaci[oó]n_?(\d+) — tolera nombres sin guion bajo tras el número. Si aparecen nuevas variantes de nomenclatura, ajustar extract_cursoid() en airtable_client.py (usado también por run.py, backfill.py, send_slack_report.py, dashboard.py, analyze_creatives.py).