feat(eda): render AutomaticEDA por capítulos sueltos con resolución de dependencias

Permite renderizar un SUBCONJUNTO de capítulos del informe AutomaticEDA
(only_chapters=[...]) para iterar/testear un capítulo concreto sin generar el
documento entero, garantizando que el capítulo pedido SIEMPRE llegue poblado.

- Nuevo módulo automatic_eda/chapter_deps.py: mapa central CHAPTER_DEPS (fuente
  de verdad) que declara, por capítulo de CHAPTER_ORDER, qué flags de cómputo
  (run_models/run_series/run_llm) y qué piezas de ctx (raw_numeric, timeseries_raw,
  geo_points, head_rows, db_path/table) necesita para no salir degradado. Helpers
  puros: resolve_requirements, resolve_profile_flags, needs_render_ctx,
  resolve_ctx_data_keys, validate_chapter_ids.
- build_document(profile, ctx, only=None): parámetro only opcional que restringe
  el cuerpo a esos capítulos (portada primera + glosario última siempre). Lee la
  clave reservada ctx['_only_chapters'] cuando only es None, para propagar la
  selección a través de los renderers sin modificarlos. Retrocompatible.
- render_automatic_eda(..., only_chapters=None): valida los ids (error claro
  dict-no-throw), resuelve las dependencias activando el cómputo necesario aunque
  el caller no lo pidiera (un flag explícito siempre prima) y construyendo solo
  las piezas de ctx que los capítulos pedidos leen (salta build_eda_render_ctx
  entero si ninguno necesita datos crudos). only_chapters=None produce el
  documento completo idéntico al de hoy.
- Tests: chapter_deps_test.py (resolución pura), build_document_only_test.py
  (filtro), render_automatic_eda_only_test.py (golden con DuckDB: outliers suelto
  con IsolationForest poblado por resolución; timeseries activa run_series;
  eficiencia geospatial sin modelos; edge cases).
- .md del pipeline: documenta only_chapters + emit_md; version 1.1.0 -> 1.2.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

python/functions/pipelines/render_automatic_eda.py

@@ -99,6 +99,7 @@ def render_automatic_eda(
     basename: str = None,
     ctx_extra: dict = None,
     emit_md: bool = True,
+    only_chapters: list = None,
 ) -> dict:
     """Perfila una tabla y emite el informe AutomaticEDA completo (PDF + PPTX).
 
@@ -150,6 +151,29 @@ def render_automatic_eda(
             MISMO documento por capítulos (texto plano + tablas markdown, sin
             binarios), pensado para pegar a un LLM. Default True. La ruta sale en
             la clave de retorno ``aeda_md_path``. No altera las demás salidas.
+        only_chapters: lista opcional de ids de capítulo a renderizar (un
+            SUBCONJUNTO de CHAPTER_ORDER) para iterar/testear un capítulo concreto
+            sin generar el documento entero. Default None => documento COMPLETO,
+            idéntico al de hoy (retrocompatible). Cuando se pasa una lista:
+
+            - Se VALIDA contra CHAPTER_ORDER; un id desconocido devuelve un error
+              claro listando los válidos (dict-no-throw, no lanza). Lista vacía
+              ``[]`` también devuelve error (pasa al menos un capítulo o None).
+            - Se RESUELVEN las dependencias de cómputo de esos capítulos
+              (``automatic_eda.chapter_deps``): se activan los flags de coste que
+              necesiten (run_models / run_series / run_llm) AUNQUE el caller no
+              los pidiera, y se construyen SOLO las piezas de ``ctx`` que esos
+              capítulos leen. Así un capítulo suelto SIEMPRE llega poblado —
+              p.ej. ``only_chapters=['outliers']`` activa run_models y conserva
+              ``ctx['raw_numeric']`` para que el bloque IsolationForest salga
+              completo— y a la vez no se malgasta CPU/LLM en lo que ningún
+              capítulo pedido usa (pedir solo ``geospatial`` no corre modelos).
+            - El documento (PDF/PPTX/MD) y su manifest contienen SOLO esos
+              capítulos, MÁS la portada (primera) y el glosario (última), que se
+              incluyen siempre para que el documento sea válido y los términos
+              clicables tengan destino.
+            - Un flag explícito del caller (run_models/run_series/run_llm != None)
+              SIEMPRE prima sobre lo que resuelvan las dependencias.
 
     Returns:
         dict (nunca lanza). En éxito::
@@ -169,11 +193,56 @@ def render_automatic_eda(
         # "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"]
 
+        # 0.bis) Modo "capítulos sueltos": valida la selección y RESUELVE sus
+        # dependencias de cómputo. Es lo que garantiza que un capítulo pedido
+        # llegue completo (activa lo que necesita) sin malgastar en lo que no.
+        # Cuando only_chapters es None se conserva el camino histórico (preset).
+        if only_chapters is not None:
+            from datascience.automatic_eda import CHAPTER_ORDER
+            from datascience.automatic_eda.chapter_deps import (
+                needs_render_ctx,
+                resolve_ctx_data_keys,
+                resolve_requirements,
+                validate_chapter_ids,
+            )
+
+            if not isinstance(only_chapters, (list, tuple)):
+                return {"status": "error",
+                        "error": "only_chapters debe ser una lista de ids de "
+                                 "capítulo o None (documento completo)."}
+            only_chapters = [c for c in only_chapters]
+            if not only_chapters:
+                return {"status": "error",
+                        "error": "only_chapters=[] está vacío. Pasa al menos un "
+                                 "capítulo, o None para el documento completo. "
+                                 "Capítulos válidos: " + ", ".join(CHAPTER_ORDER)}
+            checked = validate_chapter_ids(only_chapters, CHAPTER_ORDER)
+            if checked["unknown"]:
+                return {"status": "error",
+                        "error": "only_chapters con ids desconocidos: "
+                                 + ", ".join(checked["unknown"])
+                                 + ". Capítulos válidos: "
+                                 + ", ".join(CHAPTER_ORDER)}
+            only_chapters = checked["valid"]
+
+            # Las dependencias fijan el DEFAULT de cada flag de coste (eficiencia:
+            # lo que ningún capítulo pedido necesita queda en False); un flag
+            # explícito del caller (!= None) sigue primando.
+            dep_flags = resolve_requirements(only_chapters)["profile_flags"]
+            run_models = ("run_models" in dep_flags) if run_models is None else run_models
+            run_series = ("run_series" in dep_flags) if run_series is None else run_series
+            run_llm = ("run_llm" in dep_flags) if run_llm is None else run_llm
+            # En capítulos sueltos no se usa el camino "modelos baratos" (lite),
+            # que poda ctx['raw_numeric']: un capítulo como outliers lo necesita
+            # para su multivariante en vivo. El preset solo gobierna `sample`.
+            model_opts = None
+        else:
+            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
+
         # 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.
@@ -217,10 +286,25 @@ def render_automatic_eda(
         if ctx_extra:
             base_ctx.update(ctx_extra)
 
-        ctx = build_eda_render_ctx(
-            db_path, table, prof, backend=backend, sample=sample,
-            base_ctx=base_ctx,
-        )
+        # En modo capítulos sueltos, si NINGÚN capítulo pedido necesita datos
+        # crudos del ctx, se salta build_eda_render_ctx por completo (ahorro real
+        # de I/O): solo se conservan presentación + db_path/table. Si sí los
+        # necesita, se construye el ctx y luego se PODAN las piezas de datos que
+        # ningún capítulo pedido usa (db_path/table nunca se podan).
+        if only_chapters is not None and not needs_render_ctx(only_chapters):
+            ctx = dict(base_ctx)
+            ctx["db_path"] = db_path
+            ctx["table"] = table
+        else:
+            ctx = build_eda_render_ctx(
+                db_path, table, prof, backend=backend, sample=sample,
+                base_ctx=base_ctx,
+            )
+            if only_chapters is not None and isinstance(ctx, dict):
+                keep = resolve_ctx_data_keys(only_chapters)
+                for k in ("head_rows", "raw_numeric", "timeseries_raw", "geo_points"):
+                    if k not in keep:
+                        ctx.pop(k, None)
 
         # 2.5) Camino lite — modelos baratos (PCA + normalidad, sin KMeans ni
         # IsolationForest). profile_table no corrió los modelos; aquí se corren
@@ -245,6 +329,13 @@ def render_automatic_eda(
                 ctx.pop("raw_numeric", None)
 
         # 3) Render a ambos formatos desde el MISMO documento por capítulos.
+        # En modo capítulos sueltos, la selección viaja a build_document por una
+        # clave reservada del ctx (los renderers llaman build_document sin pasar
+        # `only`): build_document filtra el cuerpo a esos capítulos y siempre
+        # añade portada (primera) + glosario (última). build_document la consume
+        # y la quita, así que no llega a los capítulos.
+        if only_chapters is not None and isinstance(ctx, dict):
+            ctx["_only_chapters"] = list(only_chapters)
         os.makedirs(out_dir, exist_ok=True)
         ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
         base = basename or f"aeda_{table}_{ts}"
@@ -283,6 +374,7 @@ def render_automatic_eda(
             "pdf_note": rpdf.get("note"),
             "pptx_note": rpptx.get("note"),
             "md_note": rmd.get("note"),
+            "only_chapters": only_chapters,
             "profile": prof,
         }
     except Exception as e:  # noqa: BLE001 — dict-no-throw: degradar, nunca lanzar.