Este módulo transforma contenido textual estructurado (temas e ideas) en artefactos didácticos reutilizables: mapas conceptuales (mindmaps en Mermaid), infraestructura de infografías (Infographic IR) y derivados como guiones de podcast o prompts para generación de imágenes. Su diseño prioriza determinismo y trazabilidad: cuando falta un LLM, genera salidas coherentes mediante reglas y plantillas; cuando hay LLM, lo usa para enriquecer textos, pero nunca depende exclusivamente de él.

Flujo de datos: desde state hasta la infografía

1. Entrada
   • state debe contener preferentemente grouped_themes (lista de temas con título, resumen y lista de ideas). Si no existe, el módulo intenta construir temas a partir de core_ideas (fallback determinista).
2. Normalización
   • Funciones como ensure_core_maps y la lógica en generate_infographic_ir normalizan identificadores y textos: crea core_map, reverse_core_map, theme_id (T1, T2), y idea_id (I1, I2 o T1_1).
3. Generación del mindmap (Mermaid)
   • build_mermaid_from_grouped_themes recorre grouped_themes, asigna ids canónicos y produce un bloque mermaid tipo mindmap con nodos root, Tn (temas) e In (ideas).
   • Actualiza state.core_map y state.reverse_core_map para mantener correspondencia entre texto e identificadores.
4. Metadatos del mindmap
   • Se construye (o puede construirse) mindmap_metadata: lista de nodos con campos como id, label, type, depth, parent_id, summary, visual_cues, importance, color_hint, layout_hint, example_prompt.
   • Este JSON es la puerta de enlace entre la estructura conceptual y la representación visual.
5. Generación de la Infraestructura de Infografías (Infographic IR)
   • generate_infographic_ir toma la normalización y el mindmap para producir un JSON con:
     • Entradas por tema: id, type: theme, title, description (texto pensado para un diseñador o modelo de imagen), suggested_layout, ideas (lista id/text).
     • Entradas por idea: id, type: idea, title, description (vignette), suggested_layout, parent_theme.
   • Guarda el JSON en disco con timestamp y lo adjunta a state (infographic_ir_path, infographic_images, theme_to_ideas).
6. Consumo
   • Nodos posteriores (generación de imágenes, composición de documento final, guion de podcast) consumen state.infographic_images y state.mindmap_metadata para alinear texto, visuales y layout.

Por qué los mindmaps son la base ideal para infografías

• Estructura jerárquica: los mindmaps representan relaciones padre-hijo (tema → idea → subidea) que se traducen directamente en secciones de una infografía (paneles, viñetas, viñetas secundarias).
• Identificadores canónicos: I1, T1 permiten referenciar elementos de forma inequívoca en prompts, plantillas de diseño y metadatos.
• Priorización y layout: campos derivados del mindmap (depth, importance, layout_hint) permiten decidir qué destacar visualmente (tamaño, color, posición).
• Generación de prompts: cada nodo puede incluir example_prompt o description listo para alimentar un generador de imágenes o un diseñador humano.
• Sincronización narrativa: el mindmap sirve como índice para el guion (podcast, texto) y para la secuencia visual (slide por tema, viñeta por idea).

Detalle técnico de las funciones clave (qué hacen y por qué importa)

• ensure_core_maps(state)
  • Normaliza core_map y reverse_core_map. Evita duplicados y genera ids nuevos cuando hace falta.
  • Importancia: mantiene consistencia entre mermaid, IR y cualquier referencia posterior.
• build_mermaid_from_grouped_themes(state)
  • Crea el bloque Mermaid mindmap con nodos y etiquetas.
  • Actualiza state.mermaid_map y state.core_map.
  • Importancia: produce el artefacto visual canónico que se incluye en artículos y sirve de referencia para la IR.
• generate_mindmap_descriptions(state) (sugerida/implementada)
  • Recorre grouped_themes y genera mindmap_metadata con visual_cues, importance, color_hint, example_prompt.
  • Importancia: convierte el mindmap en un contrato semántico para diseño y generación de imágenes.
• generate_infographic_ir(state)
  • Normaliza temas, crea theme_desc (texto para la infografía) y viñetas por idea; genera JSON con images y lo guarda.
  • Adjunta infographic_ir_path y infographic_images al state.
  • Importancia: produce el artefacto consumible por pipelines de imagen o por diseñadores, con trazabilidad (timestamp) y estructura clara.

Ejemplo de transformación (flujo conceptual → visual)

1. Entradapygrouped_themes = [ {"title":"Orígenes","summary":"Orígenes y cronología","ideas":[{"id":"I1","text":"Herramientas líticas"},{"id":"I2","text":"Yacimientos clave"}]}, {"title":"Cultura material","summary":"Cerámica y metalurgia","ideas":["Cerámica decorada","Técnicas metalúrgicas"]} ]
2. Mindmap (Mermaid)Codimindmap root("Concept Map") T1("1. Orígenes") I1("I1: Herramientas líticas") I2("I2: Yacimientos clave") T2("2. Cultura material") I3("I3: Cerámica decorada") I4("I4: Técnicas metalúrgicas")
3. Mindmap metadata (ejemplo)json{ "nodes":[{"id":"T1","type":"theme","importance":"high","example_prompt":"Infografía 'Orígenes' con timeline y mapa."}, ...] }
4. Infographic IR (tema T1)json{ "id":"T1", "type":"theme", "title":"Orígenes", "description":"Infografía representando 'Orígenes'. Resumen: Orígenes y cronología. Elementos: timeline; mapa; iconos de herramientas.", "suggested_layout":"title + timeline + 3 bullets", "ideas":[["I1","Herramientas líticas"],["I2","Yacimientos clave"]] }

Robustez, pruebas y recomendaciones para producción

• Fallback determinista: si falta grouped_themes, construir temas desde core_ideas por chunking garantiza salida mínima.
• Sanity checks: validar mermaid con _is_mermaid_sane antes de usarlo como fuente autoritativa.
• Pruebas unitarias:
  • Crear state con 2–4 temas y ejecutar build_mermaid_from_grouped_themes + generate_mindmap_descriptions + generate_infographic_ir.
  • Verificar: archivo JSON creado, state.infographic_images poblado, mindmap_metadata coherente con mermaid_map.
• Mejoras prácticas:
  • Añadir campos visuales opcionales: visual_style, color_palette, focal_point, aspect_ratio.
  • Limitar longitud de description para evitar prompts excesivos en LLMs o generadores de imágenes.
  • Versionar el JSON de IR (schema version) para compatibilidad con consumidores.

Conclusión: mindmaps como columna vertebral de la infografía

Los mindmaps generados por este módulo no son solo una representación visual: son la estructura canónica que alimenta la generación de infografías. Al convertir temas e ideas en nodos con identificadores, resúmenes y metadatos visuales, el sistema crea un contrato semántico que permite automatizar la creación de imágenes, diseñar layouts coherentes y sincronizar narración y visuales en documentos finales. Esto acelera la producción, mejora la trazabilidad y facilita la integración entre LLMs, motores de imagen y diseñadores humanos.