Data intake normalizer

Data Intake Normalizer

Pre-requisito global. Corre antes de cualquier science skill cuando el input es un archivo del cliente. Produce data_normalized.csv + validation_report.json. Si el reporte tiene nivel BLOCK → no ejecutar el skill downstream.

---

Cuándo activar

Cliente sube CSV/XLSX/XLS/TSV/JSON
        ↓
data-intake-normalizer  ← SIEMPRE primero
        ↓
validation_report.json
  OK   → ejecutar skill downstream con data_normalized.csv
  WARN → mostrar advertencias, ejecutar con caveats
  BLOCK → mostrar errores, solicitar corrección, ofrecer template

También activa cuando el usuario pide:

• "Dame la plantilla para [skill]"
• "¿Qué formato necesita el archivo?"
• "El script falla con mi CSV"

---

Schemas por skill — columnas requeridas / opcionales

Lee references/schemas.md para el schema completo de cada skill. Resumen ejecutivo:

Skill destino	Columnas requeridas	Columnas opcionales clave
customer-segmentation-clustering	customer_id, transaction_date, amount	category, brand, channel
customer-lifetime-value	customer_id, period, revenue, cost	retention_flag, channel, cohort
survival-analysis-marketing	customer_id, event_date, censored	discount, emails_sent, segment
response-uplift-modeling	customer_id, treatment, response	score, segment, spend, ltv
market-basket-analysis	transaction_id, item_id	amount, category, timestamp
price-demand-optimization	price, quantity	period, competitor_price, promotion
recommender-systems	user_id, item_id, rating	timestamp, context, category
mmm-modeling	date, kpi + ≥1 spend_[channel]	price_index, promo, seasonality
audience-segmentation-brief	customer_id, segment, ltv	channel, rfm_score, persona
media-routing-planner	channel, spend, impressions, conversions	cpm, cpa, roas, period
weekly-control-tower	date, kpi, actual, target	channel, campaign, segment
measurement-incrementality	date, group (test/control), kpi	spend, impressions, conversions
crm-journey-architect	customer_id, event, timestamp	channel, segment, value
scope-audit	Texto libre (RFP/SOW) — no normalización	—
margin-simulation	fee, fte_cost, vendor_cost, hours	segment, client, period

---

Workflow

Step 1 — Detectar archivo

python scripts/schema_detector.py \
    --file /mnt/user-data/uploads/[filename] \
    --output results/detection.json

Output: { target_skill, confidence, detected_columns, file_info }

Step 2 — Mapear columnas

python scripts/column_mapper.py \
    --file /mnt/user-data/uploads/[filename] \
    --target-skill [skill_name] \
    --output results/column_map.json

Output: { mappings: { client_col → os_col }, unmapped, missing_required }

Step 3 — Normalizar tipos + encoding

python scripts/type_coercer.py \
    --file /mnt/user-data/uploads/[filename] \
    --column-map results/column_map.json \
    --output results/data_typed.csv

Handles: fechas (≥15 formatos), montos (comas, símbolos), encodings (UTF-8/latin-1/CP1252/UTF-16)

Step 4 — Manejar nulos

python scripts/null_handler.py \
    --file results/data_typed.csv \
    --target-skill [skill_name] \
    --output results/data_normalized.csv

Estrategias por columna: drop / median / mode / forward-fill / flag

Step 5 — Reporte de validación

python scripts/validation_report.py \
    --normalized results/data_normalized.csv \
    --target-skill [skill_name] \
    --column-map results/column_map.json \
    --output results/validation_report.json

Step 6 — Mostrar resultado al usuario

[show_widget] validation dashboard — siempre antes de ejecutar skill downstream

Generar plantilla (modo alternativo)

python scripts/template_generator.py \
    --skill [skill_name] \
    --output /mnt/user-data/outputs/template_[skill_name].xlsx

---

Niveles de validación

Nivel	Condición	Acción
OK	Todas las columnas requeridas presentes, tipos correctos, nulos < 5%	Ejecutar skill downstream
WARN	Columnas opcionales faltantes, nulos 5–20%, mapeo fuzzy aplicado	Ejecutar con caveats visibles
BLOCK	Columnas requeridas faltantes, nulos > 20% en columna crítica, encoding irrecuperable	Detener. Mostrar errores. Ofrecer plantilla.

---

Output format — Visualization First

Dashboard panels (ver references/intake_dashboard_template.html):

1. Status banner — OK / WARN / BLOCK con color
2. File info — filas, columnas, encoding, tamaño, skill detectado
3. Column mapping table — cliente col → OS col, con status por columna
4. Issues list — errores y advertencias con descripción accionable
5. Preview — primeras 5 filas del archivo normalizado
6. Next step — botón sendPrompt() al skill downstream si OK/WARN

---

Marketer Insights Layer

Siempre incluir después del dashboard:

• Qué columnas se renombraron automáticamente y por qué
• Qué nulos se imputaron con qué estrategia
• Cuántas filas quedaron disponibles vs total original
• Si hay BLOCK: mensaje claro + "Descarga la plantilla correcta" + botón

---

Reglas de orquestación (OS rules)

Rule #19: ALWAYS run data-intake-normalizer before any science skill
          when input is CSV/XLSX. BLOCK if validation_report = BLOCK.
Rule #20: If client provides data in Google Drive → use Google Drive MCP
          read directly (no upload needed), still run normalization.
Rule #21: If normalization fails 2+ times on same file → offer template
          download for that specific skill automatically.

---

Reference files

• references/schemas.md — Schema completo por skill (columnas, tipos, constraints)
• references/type_rules.md — Reglas de coerción por tipo de dato
• references/null_strategies.md — Estrategia de imputación por columna y skill
• references/intake_dashboard_template.html — Dashboard HTML; inject SKILL_DATA_JSON
• templates/ — Plantillas XLSX pre-generadas por skill (generadas con template_generator.py)