MASSIVE

1. Visión General

MASSIVE es una plataforma de simulación social para modelar evolución de opinión, polarización y propagación de influencia en redes complejas.
El núcleo histórico (simulator.py) mantiene una API estable (simular, simular_multiples, run_with_schedule) y hoy convive con capas modernas: simulación integrada adaptativa (IntegratedSimulator), forecast temporal (forecast/) y selección de régimen con motor neuronal opcional CfC (cfc_router.py).

Su propósito actual es combinar ejecución operativa (simulación), diseño estratégico (Social Architect) y estimación de riesgo temporal en un flujo único, reproducible y ejecutable en hardware estándar.

2. Arquitectura y Áreas Clave

• Motor de simulación base (simulator.py)

  • Reglas principales: regla_lineal, regla_umbral, regla_memoria, regla_backlash, regla_hk, regla_homofilia, regla_replicador.
  • Métricas y utilidades: calculate_ews_metrics, detect_topological_change, resumen_historial.
  • API pública legacy preservada para compatibilidad.

• Orquestación dinámica (IntegratedSimulator en simulator.py)

  • Integra MassiveEngine y MultilayerEngine.
  • Añade drift contextual, saltos de Lévy, topología dinámica (dynamic_rewiring) y diagnóstico de divergencia (run_butterfly_diagnostic).

• Escalamiento computacional (massive_engine.py)

  • MassiveSimEngine implementa LOD por super-agentes (build_super_agents), cuantización (quantize_state) y ejecución event-driven (ActiveSet), con fallback de backend GPU/CPU.

• Dinámica multicapa (multilayer_engine.py)

  • MultilayerEngine modela capas social/digital/económica y atributos sociodemográficos.
  • Compresión de estado para poblaciones grandes mediante state_compression.py (compress_agent_states, decompress_agent_states).

• Diseño de estrategias (social_architect.py)

  • Bucle inverso con buscar_estrategia_inversa.
  • Optimización de fases con find_optimal_interventions + optimize_interventions (intervention_optimizer.py).

• Forecast temporal (forecast/)

  • API: forecast(...) con modos analytical y monte_carlo.
  • Configuración tipada con TemporalConfig.
  • Comparación de escenarios con compare_scenarios.

• Capa contractual backend/frontend

  • DTOs Pydantic v2 en backend/app/models/.
  • Generación tipada TypeScript con python scripts/gen_ts_types.py hacia frontend/src/types/api.generated.ts.
  • Adaptador estable massive_core/ para importaciones nuevas sin romper módulos legacy.

3. Características Vanguardistas

• Selección híbrida de régimen (CfC/LLM/heurístico) con fallback no disruptivo (CfCRouter).
• Motor temporal dual (analítico + Monte Carlo) con intervalos de confianza y horizonte configurable.
• Simulación integrada con topología dinámica y monitoreo de transición caótica (Lyapunov).
• Escalamiento para grandes poblaciones con LOD, cuantización y conjuntos activos event-driven.
• Contratos API estrictos (extra="forbid") y generación automática de tipos frontend para evitar deriva entre backend y UI.

4. Línea de Tiempo / Hitos

• Base del proyecto: consolidación del simulador social clásico con reglas múltiples y API estable (simular, simular_multiples).
• Calibración empírica: incorporación de empirical_config.py y empirical_calibration.py.
• Motor CfC: integración de cfc_engine.py, cfc_router.py, cfc_trainer.py como capa neuronal opcional.
• Forecast temporal: creación de forecast/ e integración en UI y Social Architect.
• Capa de contratos: incorporación de DTOs Pydantic v2, massive_core/ y pipeline de generación TS + validación CI.
• Simulación integrada reciente: commits recientes incorporan/refinan IntegratedSimulator, ajustes de constantes dinámicas y endurecimiento de hooks (historial reciente: PRs #41, #42, #43).

5. Pipeline de Validación y Datos

5.1 Validación Unificada (validate.py)

Tres modos de validación contra datos reales y sintéticos:

Modo	Objetivo	Comando
macro	Polarization index (E1-E6) vs cleaned real data	python scripts/validate.py --mode macro
micro	Polarization proxy desde micro-métricas (F1-F5)	python scripts/validate.py --mode micro
events	Deltas de métricas pre/post eventos (T1-T10)	python scripts/validate.py --mode events
all	Todos los anteriores	python scripts/validate.py --mode all

Eventos validados (T1-T10): 200/210 correctos (95.2%):

• ✅ 100%: T2 (conflicto_lider), T3 (noticia_positiva), T4 (noticia_negativa), T6 (cambio_estrategia), T7 (fatiga), T8 (sincronizacion_forzada), T10 (polarizacion_subgrupos)
• ✅ T1 (nuevo_miembro) 91%, T5 (mediacion) 87%, T9 (salida_miembro) 93%

Regla: MAE > 0.2 genera advertencia con explicación, nunca bloquea.

5.2 Recolectores de Datos

• GDELT (collect_gdelt.py): consulta gratuita v2 API, modo timelinetone → support/oppose, con retry logic (3 intentos, backoff exponencial). Best-effort, nunca bloquea.
• Reddit (collect_reddit_sentiment.py): 8 episodios corporativos vía PRAW, clasificación por palabras clave. --dry-run para CI sin credenciales.

5.3 CfC RegimeSelector

• train_cfc_calibrated.py entrena CfCRegimeSelector con episodios calibrados. Bug corregido: usaba h.get("_regla", 0) (siempre régimen 4) → reemplazado con target_regime explícito por scenario_type. Accuracy training: 18.7% → 100%.
• evaluate_cfc.py evalúa contra datos cleaned reales (confianza < 0.75 → fallback correcto a LLM).

5.4 Eventos Transversales (apply_events.py)

10 eventos aplicados a escenarios micro, con correcciones estructurales:

Evento	Fix aplicado
T1 nuevo_miembro	Posición en esquina opuesta al centroide + charge negativa → cohesión↓ conflicto↑
T2 conflicto_lider	Flip completo: -c - magnitude en vez de c - magnitude
T5 mediacion	Cargas positivas y negativas convergen a cero; mood mejora para todos
T7 fatiga	Reduce mood además de energía
T8 sincronizacion_forzada	Acopla varianza de mood + reduce media en 0.1
T9 salida_miembro	Elimina agente más lejano del centroide con estrategia más rara
T10 polarizacion_subgrupos	Agentes con signo opuesto se voltean (flip); mismo signo se polarizan más

5.5 CI/CD

.github/workflows/validation.yml: 6 pasos — collect_gdelt → collect_reddit (dry-run) → ingest → compute → validate (--mode all) → evaluate_cfc.

6. Guía de Inicio Rápido

pip install -r requirements.txt
streamlit run app.py
python -m pytest tests/