feat(eda): profile_level (lite/standard/full) en render_automatic_eda

Añade el parámetro profile_level a render_automatic_eda como preset de
consumo CPU/LLM que mapea a los flags existentes (run_models, run_series,
run_llm, sample). Tres niveles:

- lite (bajo consumo): run_llm=False, run_series=False, sample=2000 y modelos
  limitados a PCA + normalidad, SIN KMeans ni IsolationForest (lo caro en CPU).
  Para un vistazo rápido y barato.
- standard (default): comportamiento histórico — modelos completos, serie,
  sin LLM.
- full: standard + narrativa LLM por capítulo.

Precedencia: un flag explícito del caller (run_llm=..., run_models=..., etc.)
siempre prima sobre el default que fija el preset; el preset solo aplica al
parámetro que se deja en None.

Cableado del modo lite sin tocar profile_table (lo tocan otros agentes en
paralelo): profile_table NO corre los modelos (evita pagar KMeans +
IsolationForest); este pipeline los corre con run_eda_models(run_kmeans=False,
run_isolation=False) reusando ctx['raw_numeric'], y quita raw_numeric del ctx
para que el capítulo modelos no reproyecte clusters KMeans en vivo
(project_clusters_2d). geo_points ya queda derivado, así que geospatial no se
afecta.

Cambio aditivo y retro-compatible: sin profile_level el comportamiento es
idéntico al de v1.0.0 (standard). Tests nuevos cubren lite/standard, la
precedencia flag-sobre-preset, y la equivalencia del default con el histórico.
Bump 1.0.0 -> 1.1.0 + growth log en el .md. Skill /eda documenta --lite/--full.

Verificación: golden lite/standard/full sobre titanic — lite 4.8s (PCA+norm,
sin KMeans/iso/LLM/serie), standard 7.8s (modelos completos), full 38.3s
(+LLM). Suite render_automatic_eda + automatic_eda: 96 passed. fn index sin
error.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-30 18:20:17 +02:00
parent f2ac734ef7
commit 3be188a921
4 changed files with 334 additions and 34 deletions
@@ -34,21 +34,62 @@ from datascience import (
build_eda_render_ctx,
render_automatic_eda_pdf,
render_automatic_eda_pptx,
run_eda_models,
)
from pipelines.profile_table import profile_table
# Tokens de almacenamiento por backend (para la portada del informe).
_STORAGE = {"duckdb": "DuckDB", "postgres": "PostgreSQL"}
# Presets de consumo CPU/LLM: cada profile_level fija SOLO los DEFAULTS de los
# flags que controlan el coste (un flag explícito del caller siempre prima sobre
# el preset). model_opts != None marca el camino "modelos baratos" (lite): los
# modelos NO los corre profile_table (que ejecutaría KMeans + IsolationForest),
# sino run_eda_models con esa granularidad, de modo que el coste CPU de los
# multivariantes nunca se paga. model_opts None => modelos completos como hasta
# ahora (profile_table los corre con todos los algoritmos).
_PROFILE_PRESETS = {
# Bajo consumo: sin LLM, sin serie, sample reducido y modelos limitados a
# PCA + normalidad (sin KMeans ni IsolationForest, lo caro en CPU). Vistazo
# rápido y barato de una tabla.
"lite": {
"run_models": True,
"run_series": False,
"run_llm": False,
"sample": 2000,
"model_opts": {"run_kmeans": False, "run_isolation": False},
},
# Default: idéntico al comportamiento histórico del pipeline (modelos
# completos, serie temporal, sin LLM, sample 5000).
"standard": {
"run_models": True,
"run_series": True,
"run_llm": False,
"sample": 5000,
"model_opts": None,
},
# Máximo: standard + narrativa LLM (interpretación del perfil y de los
# capítulos modelos/geospatial/agregacion). Es la única parte que gasta
# tokens del modelo.
"full": {
"run_models": True,
"run_series": True,
"run_llm": True,
"sample": 5000,
"model_opts": None,
},
}
def render_automatic_eda(
db_path: str,
table: str,
backend: str = "duckdb",
sample: int = 5000,
run_models: bool = True,
run_series: bool = True,
run_llm: bool = False,
sample: int = None,
run_models: bool = None,
run_series: bool = None,
run_llm: bool = None,
profile_level: str = "standard",
out_dir: str = "reports",
basename: str = None,
ctx_extra: dict = None,
@@ -60,19 +101,39 @@ def render_automatic_eda(
table: nombre de la tabla a perfilar.
backend: "duckdb" (default) o "postgres".
sample: máximo de filas/valores muestreados por columna para el perfil
y para los datos crudos del ctx (LIMIT). Default 5000.
run_models: si True (default) corre los modelos baratos
y para los datos crudos del ctx (LIMIT). Default None => lo fija el
preset de profile_level (lite=2000, standard/full=5000).
run_models: corre los modelos baratos
(PCA/KMeans/IsolationForest/normalidad). Necesario para que el
capítulo `modelos` pinte los clusters sobre el plano PCA.
run_series: si True (default) calcula el análisis de serie temporal por
capítulo `modelos` pinte los clusters sobre el plano PCA. Default
None => lo fija el preset (True en los tres niveles); en `lite` los
modelos se limitan a PCA + normalidad (ver profile_level).
run_series: calcula el análisis de serie temporal por
columna numérica. Necesario para el análisis del capítulo
`timeseries` (la gráfica de evolución sale de los datos crudos del
ctx aunque run_series sea False).
run_llm: si True (default False) hace la interpretación LLM del perfil y
ctx aunque run_series sea False). Default None => lo fija el preset
(standard/full=True, lite=False).
run_llm: hace la interpretación LLM del perfil y
ACTIVA además la narrativa LLM de los capítulos modelos/geospatial/
agregacion (títulos de segmento, descripción de la zona, selección de
agregaciones). Con False esos capítulos usan su derivación
cuantitativa (siguen completos, sin llamadas de red).
cuantitativa (siguen completos, sin llamadas de red). Default None =>
lo fija el preset (full=True, lite/standard=False).
profile_level: preset de consumo CPU/LLM. Mapea a defaults de los flags
anteriores; un flag explícito SIEMPRE prima sobre el preset (el
preset solo fija el default cuando el flag se deja en None):
- "lite" bajo consumo: run_llm=False, run_series=False,
sample=2000 y modelos limitados a **PCA + normalidad** (SIN KMeans
ni IsolationForest, que es lo caro en CPU). Pensado para un vistazo
rápido y barato. El capítulo `modelos` sale con PCA + normalidad,
sin el scatter de clusters.
- "standard" (default): comportamiento histórico — modelos completos
(PCA/KMeans/IsolationForest/normalidad), serie temporal, sin LLM.
- "full" standard + narrativa LLM (run_llm=True).
Ejemplo de precedencia: profile_level="lite" con run_llm=True
explícito => el LLM SÍ se ejecuta (el flag explícito gana al preset).
out_dir: directorio de salida (se crea si no existe). Default "reports".
basename: nombre base de los archivos sin extensión. Default
"aeda_<table>_<timestamp>".
@@ -90,6 +151,24 @@ def render_automatic_eda(
En error: {"status": "error", "error": str}.
"""
try:
# 0) Resolución del preset: el profile_level fija los DEFAULTS de los
# flags de coste; cualquier flag que el caller haya pasado explícito
# (!= None) prima sobre el preset. Un profile_level desconocido cae a
# "standard" (comportamiento histórico), sin lanzar.
preset = _PROFILE_PRESETS.get(profile_level, _PROFILE_PRESETS["standard"])
sample = preset["sample"] if sample is None else sample
run_models = preset["run_models"] if run_models is None else run_models
run_series = preset["run_series"] if run_series is None else run_series
run_llm = preset["run_llm"] if run_llm is None else run_llm
model_opts = preset["model_opts"]
# En el camino "modelos baratos" (lite) profile_table NO corre los
# modelos: los ejecuta este pipeline con run_eda_models y la granularidad
# del preset, evitando pagar el coste CPU de KMeans + IsolationForest.
# En standard/full profile_table los corre completos como siempre.
lite_models = bool(run_models) and model_opts is not None
pt_run_models = bool(run_models) and not lite_models
# 1) Perfil base + modelos/serie opcionales. No escribe report propio
# (write_report=False): este pipeline emite su propio par PDF/PPTX.
pres = profile_table(
@@ -97,7 +176,7 @@ def render_automatic_eda(
table,
backend=backend,
sample=sample,
run_models=run_models,
run_models=pt_run_models,
run_llm=run_llm,
run_series=run_series,
emit_pdf=False,
@@ -131,6 +210,28 @@ def render_automatic_eda(
base_ctx=base_ctx,
)
# 2.5) Camino lite — modelos baratos (PCA + normalidad, sin KMeans ni
# IsolationForest). profile_table no corrió los modelos; aquí se corren
# con run_eda_models reusando la muestra numérica alineada por fila que
# build_eda_render_ctx ya trajo en ctx['raw_numeric'] (no se reimplementa
# la lógica de los modelos: se delega en run_eda_models con la
# granularidad del preset).
if lite_models:
raw_numeric = ctx.get("raw_numeric") if isinstance(ctx, dict) else None
if isinstance(raw_numeric, dict) and raw_numeric:
model_input = {
col: {"values": vals, "type": "numeric"}
for col, vals in raw_numeric.items()
}
prof["models"] = run_eda_models(model_input, **model_opts)
# Quita raw_numeric del ctx para que el capítulo `modelos` NO
# reproyecte clusters KMeans en vivo (project_clusters_2d ejecuta
# KMeans): en lite ese coste se evita. geo_points ya quedó derivado
# en ctx por build_eda_render_ctx, así que el capítulo geospatial no
# se ve afectado.
if isinstance(ctx, dict):
ctx.pop("raw_numeric", None)
# 3) Render a ambos formatos desde el MISMO documento por capítulos.
os.makedirs(out_dir, exist_ok=True)
ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")