first commit

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+documenti/
+.venv
+benchmarks
+data/

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+RUN useradd -m -u 1000 user
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN chown -R user:user /app
+
+USER user
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    STREAMLIT_SERVER_PORT=7860 \
+    STREAMLIT_SERVER_ADDRESS=0.0.0.0 \
+    STREAMLIT_SERVER_ENABLE_CORS=false \
+    STREAMLIT_SERVER_HEADLESS=true
+
+EXPOSE 7860
+
+CMD ["streamlit", "run", "app.py"]

Readme.MD

@@ -0,0 +1,104 @@
+---
+title: GeneticWFM
+emoji: 🧬
+colorFrom: indigo
+colorTo: green
+sdk: docker
+pinned: false
+short_description: Evolutionary AI solver for workforce management
+license: apache-2.0
+---
+
+
+# 🧬 AI Workforce Scheduler
+
+Questo progetto è un prototipo avanzato per l'ottimizzazione della pianificazione dei turni di lavoro (**Workforce Management**) basato su **Algoritmi Genetici** e accelerato tramite **Numba**. È progettato specificamente per gestire scenari complessi nel settore **BPO (Business Process Outsourcing)**, garantendo la copertura del fabbisogno operativo e il rispetto dei vincoli di legge e contrattuali.
+
+## 🚀 Caratteristiche Tecniche
+
+* **Motore Evolutivo ad Alte Prestazioni**: Utilizzo di **Numba (`njit`)** per la compilazione Just-In-Time e il calcolo parallelo della fitness, permettendo di gestire popolazioni numerose su centinaia di dipendenti in pochi secondi.
+* **Architettura Modulare**: Suddivisione netta tra motore genetico, modelli di dominio e logica di business per una facile scalabilità.
+* **Gestione Vincoli Avanzata**:
+  * Pause **VDT (Video Terminalista)** gestite dinamicamente tramite maschere di turno.
+  * Rispetto del **Mix Settimanale** (Giorni Lavorati vs Riposi).
+  * Gestione di vincoli **Hard** (Assenze, turni fissi) e **Soft** (Preferenze orarie).
+* **Vettorializzazione NumPy**: Tutta la logica di calcolo è ottimizzata per operare su matrici, riducendo al minimo i cicli Python nel core dell'algoritmo.
+
+## 📂 Struttura del Progetto
+
+Il progetto è organizzato secondo i principi della programmazione modulare:
+
+```
+.
+├── app.py                      # UI & Sandbox Evolutiva (Streamlit)
+├── src/
+│   ├── config.py               # Manager degli Iperparametri (Cascade L0/L1/L2)
+│   ├── config/
+│   │   └── engine_config.json  # Parametri dell'Ambiente Evolutivo (L1)
+│   ├── engine/                 # Motore Evolutivo e Operatori Genetici
+│   │   ├── crossover.py        # Ricombinazione Genica (Uniform Crossover vettorializzato)
+│   │   ├── evolution.py        # Ciclo Generazionale (Main JIT Solver)
+│   │   ├── mutation.py         # Perturbazione Stocastica (Mutazione Ibrida Day-Swap/Time-Shift)
+│   │   └── selection.py        # Pressione Selettiva (Tournament) e Funzione di Fitness (Loss)
+│   ├── models/                 
+│   │   └── individual.py       # Rappresentazione Cromosomica e mapping Genotipo/Fenotipo (VDT)
+│   ├── problems/               
+│   │   └── my_problem.py       # Definizione dello Spazio di Ricerca e dei Vincoli Ambientali
+│   └── utils/ 
+│       ├── demand_processing.py # Allineamento dei Target di Fitness (Time-series sanitization)
+│       ├── generator.py        # Generatore di Ambienti di Simulazione (Mock Scenarios)
+│       ├── health.py           # Metriche di Dinamica Popolazionale (IBE, Distanza di Hamming)
+│       ├── helpers.py          # Utility di decodifica dei tratti e structural analysis
+│       ├── hf_storage.py       # Conservazione del Pool Genetico e I/O su HF Datasets
+│       └── visualization.py    # Proiezione Fenotipica e rendering vettoriale dei risultati
+├── Dockerfile                  # Containerizzazione per HF Spaces
+├── requirements.txt            # Dipendenze del progetto
+└── README.md                   # Documentazione
+```
+
+## 🛠️ Installazione e Setup
+
+### Prerequisiti
+* Python 3.10 o superiore.
+* Si consiglia l'uso di un ambiente virtuale (`venv`).
+
+### Passaggi
+1. **Clona il repository**:
+   ```bash
+   git clone <repository-url>
+   cd workforce-scheduler
+   ```
+
+2. **Configura l'ambiente**:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # Su Windows: .venv\\Scripts\\activate
+   pip install -r requirements.txt
+   ```
+
+## 💻 Modalità d'Uso
+
+### Avvio Dashboard
+Per gestire le attività e avviare l'ottimizzazione tramite l'interfaccia web:
+```bash
+streamlit run app.py
+```
+
+## ⚙️ Sistema di Configurazione
+L'algoritmo adotta una gerarchia di parametri a tre livelli:
+1. **System Defaults**: Valori di sicurezza definiti nel codice.
+2. **Engine Config** (`src/config/engine_config.json`): Parametri standard per il comportamento dell'algoritmo.
+3. **Activity Config** (`data/activities/{nome}/activity_config.json`): Parametri specifici per la commessa, inclusi i **pesi della fitness**.
+
+## 📊 Visualizzazione Risultati
+L'applicazione genera automaticamente:
+* **Matrici di Copertura**: Grafici comparativi tra domanda e staff.
+* **Roster Visuale**: Tabellone dei turni settimanale.
+* **Report Qualità**: Analisi degli slot scoperti.
+
+## 🧪 Roadmap e Sviluppi Futuri
+* [ ] Integrazione di modelli di **Deep Learning** per la predizione della domanda.
+* [ ] Implementazione di strategie di mutazione basate su **Reinforcement Learning**.
+* [ ] Export dei roster in formato Excel/CSV.
+
+**Sviluppato come prototipo per soluzioni WFM avanzate.**

app.py

@@ -0,0 +1,764 @@
+import streamlit as st
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import datetime
+import traceback
+from src.config import cfg
+from src.utils.helpers import load_employees_from_json, check_hours_balance, minutes_to_time
+from src.utils.visualization import get_final_coverage_matrix
+from src.utils.health import calculate_ibe, interpret_ibe, analyze_convergence_quality
+from src.utils.demand_processing import sanitize_weekly_demand
+from src.utils.generator import generate_scenario_files
+from src.utils.hf_storage import load_json, save_json, list_activities
+from src.problems.my_problem import process_demand
+from src.engine.evolution import run_genetic_algorithm
+
+# --- SETUP INTERFACCIA ---
+st.set_page_config(page_title="AI Workforce Scheduler", layout="wide", page_icon="🧬")
+
+# ==============================================================================
+# 1. ROUTING E GESTIONE WORKSPACE (SIDEBAR)
+# ==============================================================================
+st.sidebar.title("🏢 Seleziona Attività")
+
+# Recupero dinamicamente la lista dei workspace dal repository remoto (HF Datasets)
+available_activities = list_activities()
+
+if not available_activities:
+    st.warning("⚠️ Nessuna attività trovata nel Dataset remoto.")
+    st.sidebar.info("Utilizza il Generatore per istanziare un nuovo workspace.")
+    st.stop()
+
+selected_activity = st.sidebar.selectbox("Attività da gestire:", available_activities)
+
+st.title(f"Gestione Turni: {selected_activity}")
+st.markdown("Pianificazione intelligente dei turni di lavoro tramite intelligenza artificiale evolutiva.")
+
+# Gestione dello stato di sessione: se l'utente cambia attività, forzo il ricaricamento 
+# del Singleton di configurazione e pulisco la cache dei risultati precedenti.
+if 'current_activity' not in st.session_state or st.session_state['current_activity'] != selected_activity:
+    try:
+        cfg.load_configurations(selected_activity)
+        st.session_state['current_activity'] = selected_activity
+        if 'ga_results' in st.session_state:
+            del st.session_state['ga_results']
+    except Exception as e:
+        st.error(f"Errore caricamento config per {selected_activity}: {e}")
+
+if st.sidebar.button("♻️ Ricarica App"):
+    st.cache_data.clear()
+    st.rerun()
+
+# ==============================================================================
+# 2. VIEWPORT & TAB ROUTING
+# ==============================================================================
+tab1, tab2, tab3, tab4, tab5 = st.tabs(["⚙️ Configurazione Attività", "👥 Dipendenti", "📈 Domanda (Fabbisogno)", "🚀 Esecuzione & Risultati", "⚡ Generatore"])
+
+# ------------------------------------------------------------------------------
+# TAB 1: PARAMETRI DI SISTEMA E BUSINESS (CONFIG L2)
+# ------------------------------------------------------------------------------
+with tab1:
+    st.header("⚙️ Parametri Generali")
+    
+    config_filename = "activity_config.json"
+    config_data = load_json(selected_activity, config_filename)
+    
+    if config_data:
+        client_settings = config_data.get('client_settings', {})
+        curr_slot = client_settings.get('planning_slot_minutes', 30)
+        
+        # --- 1. SETUP GRIGLIA TEMPORALE ---
+        st.subheader("🗓️ Calendario Operativo")
+        st.caption("Definisci la granularità della pianificazione e gli orari di apertura del servizio.")
+        
+        new_slot = st.selectbox(
+            "Granularità Pianificazione (minuti)", 
+            options=[15, 30, 60], 
+            index=[15, 30, 60].index(curr_slot) if curr_slot in [15, 30, 60] else 1,
+            key=f"{selected_activity}_slot_select"
+        )
+        
+        with st.expander("Modifica Orari di Apertura/Chiusura Settimanali"):
+            st.info("I turni generati dall'algoritmo non supereranno mai i limiti impostati qui. Seleziona 'Chiuso' per impedire la pianificazione in un giorno specifico.")
+            
+            # Costruisco i form per le regole orarie. Uso un dict temporaneo per raccogliere gli input.
+            day_names = ["Lunedì", "Martedì", "Mercoledì", "Giovedì", "Venerdì", "Sabato", "Domenica"]
+            user_schedule = {}
+            current_hours = config_data.get('operating_hours', {})
+            default_rule = current_hours.get('default', "09:00-18:00")
+            exceptions = current_hours.get('exceptions', {})
+            
+            for i, day_name in enumerate(day_names):
+                day_idx_str = str(i)
+                rule = exceptions.get(day_idx_str, default_rule)
+                is_closed_init = (rule == "CLOSED")
+                start_init, end_init = datetime.time(8, 0), datetime.time(20, 0)
+                
+                if not is_closed_init:
+                    try:
+                        s_str, e_str = rule.split('-')
+                        sh, sm = map(int, s_str.split(':'))
+                        eh, em = map(int, e_str.split(':'))
+                        start_init, end_init = datetime.time(sh, sm), datetime.time(eh, em)
+                    except: pass 
+
+                c1, c2, c3, c4 = st.columns([1, 1, 1, 1])
+                c1.markdown(f"**{day_name}**")
+                unique_key = f"{selected_activity}_day_{i}"
+                is_closed = c2.checkbox("Chiuso", value=is_closed_init, key=f"{unique_key}_closed")
+                start_t = c3.time_input("Apertura", value=start_init, key=f"{unique_key}_start", disabled=is_closed, step=900)
+                end_t = c4.time_input("Chiusura", value=end_init, key=f"{unique_key}_end", disabled=is_closed, step=900)
+                user_schedule[i] = {"closed": is_closed, "start": start_t, "end": end_t}
+                st.divider()
+
+        # --- 2. PESI DELLA LOSS FUNCTION ---
+        st.subheader("⚖️ Obiettivi di Business (Pesi)")
+        st.caption("Istruisci l'algoritmo su cosa è più importante. Valori più alti indicano una priorità maggiore.")
+        weights = config_data.get('weights', {})
+        wk = f"{selected_activity}_weights"
+        
+        # Espongo i pesi per permettere il fine-tuning degli obiettivi di business direttamente da UI
+        col_w1, col_w2 = st.columns(2)
+        with col_w1:
+            new_under = st.number_input("Peso Understaffing (Evita Buchi)", value=weights.get('understaffing', 1000.0), step=100.0, key=f"{wk}_under")
+            new_over = st.number_input("Peso Overstaffing (Evita Eccessi)", value=weights.get('overstaffing', 10.0), step=5.0, key=f"{wk}_over")
+        with col_w2:
+            new_homo = st.number_input("Peso Equità (Bilancia i Carichi)", value=weights.get('homogeneity', 20.0), step=5.0, key=f"{wk}_homo")
+            new_soft = st.number_input("Peso Preferenze (Accontenta gli Operatori)", value=weights.get('soft_preference', 50.0), step=5.0, key=f"{wk}_soft")
+
+        # --- 3. HYPER-PARAMETRI DEL MOTORE GENETICO ---
+        st.subheader("🧬 Motore Genetico")
+        st.caption("Configura le prestazioni dell'intelligenza artificiale.")
+        gen_params = config_data.get('genetic_params', {})
+        
+        c_gen1, c_gen2 = st.columns(2)
+        new_pop = c_gen1.number_input("Popolazione (Soluzioni per generazione)", value=gen_params.get('population_size', 500), step=100)
+        new_gen = c_gen2.number_input("Generazioni (Cicli di apprendimento)", value=gen_params.get('generations', 200), step=50)
+
+        # Nascondo i parametri avanzati dell'engine JIT in un expander per mantenere la UI pulita
+        with st.expander("🔧 Parametri Avanzati Algoritmo (Fine Tuning)"):
+            st.warning("⚠️ Modifica questi valori solo se sai cosa stai facendo. I default sono ottimizzati per scenari BPO standard. Valori errati possono bloccare l'algoritmo.")
+            ac1, ac2, ac3 = st.columns(3)
+            
+            p_mut = ac1.slider("Mutation Rate", 0.0, 1.0, gen_params.get('mutation_rate', 0.4))
+            p_cross = ac2.slider("Crossover Rate", 0.0, 1.0, gen_params.get('crossover_rate', 0.85))
+            p_elite = ac3.number_input("Elitism Rate (Protezione Migliori)", 0.0, 0.5, gen_params.get('elitism_rate', 0.02), step=0.01, format="%.2f")
+            
+            st.markdown("---")
+            bc1, bc2, bc3 = st.columns(3)
+            p_tourn = bc1.number_input("Tournament Size", 2, 20, gen_params.get('tournament_size', 5))
+            p_heur = bc2.slider("Heuristic Init Rate (Partenza Intelligente)", 0.0, 1.0, gen_params.get('heuristic_rate', 0.8))
+            p_noise = bc3.number_input("Heuristic Noise (Rumore iniziale)", 0.0, 1.0, gen_params.get('heuristic_noise', 0.2), step=0.1)
+            
+            st.markdown("---")
+            p_split = st.slider("Guided Mutation Split (Swap Giorno vs Cambio Orario)", 0.0, 1.0, gen_params.get('guided_mutation_split', 0.4))
+
+            st.markdown("---")
+            st.subheader("🧪 Analisi Pressione Evolutiva (IBE)")
+            
+            # Calcolo live dell'IBE (il mio indicatore custom) per dare un feedback 
+            # immediato sulla bontà dei parametri genetici scelti dall'utente.
+            curr_ibe = calculate_ibe(
+                pop_size=int(new_pop), generations=int(new_gen), 
+                p_cross=p_cross, p_mut=p_mut, p_heur=p_heur, p_elite=p_elite
+            )
+            status_msg, delta_color = interpret_ibe(curr_ibe)
+            
+            hc1, hc2, hc3 = st.columns([1, 1.5, 1])
+            hc1.metric(label="IBE Score", value=f"{curr_ibe:,.0f}".replace(",", "."), delta="Target: 1k-3k", delta_color=delta_color)
+            
+            if "OTTIMALE" in status_msg: hc2.success(f"**Stato:** {status_msg}")
+            elif "STALLO" in status_msg: hc2.warning(f"**Stato:** {status_msg}")
+            else: hc2.error(f"**Stato:** {status_msg}")
+            
+            with hc3.expander("Cos'è l'IBE?"):
+                st.caption("""
+                **Indice di Bilanciamento Evolutivo (IBE)**
+                È un indicatore di salute delle impostazioni che hai inserito.
+                Misura l'equilibrio tra la capacità dell'AI di esplorare nuove soluzioni (Mutazioni) 
+                e la tendenza a sfruttare quelle già trovate (Euristiche/Elitismo).
+                - **Troppo basso:** L'AI si "accontenta" subito della prima soluzione mediocre trovata.
+                - **Troppo alto:** L'AI continua a cercare a caso senza mai focalizzarsi su un piano stabile.
+                """)
+
+        # --- 4. PERSISTENZA I/O ---
+        st.divider()
+        if st.button("💾 Calcola e Salva Configurazione", type="primary"):
+            
+            # Costruisco la mappa delle regole
+            daily_rules_map = {}
+            min_h, max_h = 24, 0
+            for i in range(7):
+                d = user_schedule[i]
+                if d['closed']: daily_rules_map[str(i)] = "CLOSED"
+                else:
+                    s_str, e_str = d['start'].strftime("%H:%M"), d['end'].strftime("%H:%M")
+                    daily_rules_map[str(i)] = f"{s_str}-{e_str}"
+                    if d['start'].hour < min_h: min_h = d['start'].hour
+                    if d['end'].hour > max_h: max_h = d['end'].hour + (1 if d['end'].minute > 0 else 0)
+
+            # Trick per ottimizzare il payload JSON: calcolo l'orario più frequente 
+            # e lo imposto come 'default', salvando gli altri giorni come 'exceptions'.
+            from collections import Counter
+            vals = list(daily_rules_map.values())
+            most_common = Counter(vals).most_common(1)[0][0]
+            final_hours = {"default": most_common, "exceptions": {}}
+            for k, v in daily_rules_map.items():
+                if v != most_common: final_hours["exceptions"][k] = v
+            
+            # Aggiornamento dell'oggetto configurazione
+            if 'client_settings' not in config_data: config_data['client_settings'] = {}
+            config_data['client_settings']['planning_slot_minutes'] = new_slot
+            config_data['client_settings']['day_start_hour'] = int(min_h) if min_h < 24 else 8
+            config_data['client_settings']['day_end_hour'] = int(max_h) if max_h > 0 else 20
+            
+            config_data['operating_hours'] = final_hours
+            config_data['weights'] = {"understaffing": new_under, "overstaffing": new_over, "homogeneity": new_homo, "soft_preference": new_soft}
+            
+            config_data['genetic_params'] = {
+                "population_size": int(new_pop), "generations": int(new_gen),
+                "mutation_rate": p_mut, "crossover_rate": p_cross, "elitism_rate": p_elite,
+                "tournament_size": int(p_tourn), "heuristic_rate": p_heur,
+                "heuristic_noise": p_noise, "guided_mutation_split": p_split
+            }
+            
+            # Push sul cloud
+            save_json(selected_activity, config_filename, config_data)
+            cfg.load_configurations(selected_activity)
+            st.success("✅ Configurazione salvata e sincronizzata con successo.")
+
+    else:
+        st.error("Payload di configurazione mancante dal Dataset.")
+
+# ------------------------------------------------------------------------------
+# TAB 2: ANAGRAFICA E VINCOLI (HR MASTER DATA)
+# ------------------------------------------------------------------------------
+with tab2:
+
+    emp_filename = "employees.json"
+    emp_data = load_json(selected_activity, emp_filename)
+    
+    col_header, col_pie = st.columns([3, 1])
+    
+    with col_header:
+        st.header("👥 Gestione Personale")
+        st.caption("Gestisci i profili contrattuali, le regole di fairness settimanale e inserisci ferie, permessi o vincoli di orario.")
+
+    if emp_data is not None:
+        with col_pie:
+            # Rendering del mix contrattuale. Uso matplotlib con patch alpha=0.0
+            # per avere uno sfondo trasparente che si adatti al tema di Streamlit.
+            df_stats = pd.DataFrame(emp_data)
+            if not df_stats.empty and 'contract' in df_stats.columns:
+                counts = df_stats['contract'].value_counts()
+                fig_pie, ax_pie = plt.subplots(figsize=(1.5, 1.5))
+                colors = ['#3498db', '#e74c3c', '#f1c40f', '#9b59b6']
+                wedges, texts, autotexts = ax_pie.pie(
+                    counts, autopct='%1.0f%%', startangle=90, colors=colors[:len(counts)],
+                    textprops={'fontsize': 5, 'weight': 'bold', 'color': 'white'}, pctdistance=0.7 
+                )
+                ax_pie.axis('equal') 
+                fig_pie.patch.set_alpha(0.0) 
+                leg = ax_pie.legend(
+                    wedges, counts.index, title="Contratti", loc="center left",
+                    bbox_to_anchor=(1, 0, 0.5, 1), fontsize=5, title_fontsize=6, frameon=False, labelcolor='white' 
+                )
+                leg.get_title().set_color("white")
+                leg.get_title().set_fontweight("bold")
+                st.pyplot(fig_pie, width='content')
+
+        st.divider()
+
+        col_list, col_editor = st.columns([1, 2])
+        
+        with col_list:
+            st.subheader("Anagrafica Risorse")
+            emp_ids = [e['id'] for e in emp_data]
+            selected_id = st.selectbox("Seleziona il Dipendente da ispezionare:", emp_ids, index=0 if emp_ids else None)
+            
+            st.divider()
+            if st.button("💾 Salva Modifiche Anagrafica", type="primary"):
+                save_json(selected_activity, emp_filename, emp_data)
+                st.success("Anagrafica aggiornata in Cloud.")
+            
+            # Costruisco la preview tabellare
+            summary = []
+            for e in emp_data:
+                mix = e.get('shift_mix', {"WORK": 5, "OFF": 2})
+                summary.append({"ID": e['id'], "Contratto": e['contract'], "Mix": f"{mix.get('WORK',5)}W/{mix.get('OFF',2)}O"})
+            st.dataframe(summary, hide_index=True, width='stretch')
+
+        with col_editor:
+            # Editor del singolo dipendente: permette di iniettare override 
+            # hard/soft/absence direttamente sull'oggetto prima del salvataggio.
+            if selected_id:
+                emp_record = next((e for e in emp_data if e['id'] == selected_id), None)
+                if emp_record:
+                    st.subheader(f"✏️ Proprietà: {emp_record['id']}")
+                    
+                    c1, c2 = st.columns(2)
+                    emp_record['id'] = c1.text_input("ID Dipendente", value=emp_record['id'])
+                    ct = emp_record.get('contract', 'FT40')
+                    ct_idx = ["FT40", "PT30", "PT20"].index(ct) if ct in ["FT40", "PT30", "PT20"] else 0
+                    emp_record['contract'] = c2.selectbox("Tipologia Contratto", ["FT40", "PT30", "PT20"], index=ct_idx)
+                    
+                    cc1, cc2 = st.columns(2)
+                    emp_record['work_hours'] = cc1.number_input("Ore Lavorative Giornaliere", value=float(emp_record.get('work_hours', 8.0)))
+                    emp_record['break_duration'] = cc2.number_input("Minuti di Pausa/Pranzo", value=int(emp_record.get('break_duration', 0)))
+
+                    st.markdown("---")
+                    
+                    st.subheader("📅 Regole di Fairness Settimanale")
+                    st.caption("Imposta quanti giorni questa risorsa deve lavorare rispetto a quanti giorni deve riposare nella settimana.")
+                    curr_mix = emp_record.get('shift_mix', {"WORK": 5, "OFF": 2})
+                    
+                    cm1, cm2 = st.columns(2)
+                    w_days = cm1.number_input("Target Giorni Lavorativi", min_value=1, max_value=7, value=int(curr_mix.get("WORK", 5)))
+                    o_days = cm2.number_input("Target Giorni di Riposo", min_value=0, max_value=6, value=int(curr_mix.get("OFF", 2)))
+                    
+                    emp_record['shift_mix'] = {"WORK": w_days, "OFF": o_days}
+                    st.info(f"L'algoritmo cercherà in tutti i modi di programmare esattamente {w_days} giorni di lavoro e {o_days} di riposo. Le violazioni verranno penalizzate nel calcolo finale.")
+
+                    st.markdown("---")
+                    st.subheader("🔒 Vincoli Operativi (Assenze e Permessi)")
+                    st.caption("Aggiungi ferie, malattie o turni fissi inamovibili.")
+                    
+                    constraints = emp_record.get('constraints', {})
+                    day_map = {0: "Lunedì", 1: "Martedì", 2: "Mercoledì", 3: "Giovedì", 4: "Venerdì", 5: "Sabato", 6: "Domenica"}
+                    
+                    if constraints:
+                        cons_view = []
+                        for d, r in constraints.items():
+                            cons_view.append({"Giorno": day_map.get(int(d), d), "Tipo": r['type'].upper(), "Valore/Motivo": r.get('start_time', r.get('reason',''))})
+                        st.table(pd.DataFrame(cons_view))
+                        
+                        to_del = st.selectbox("Seleziona Giorno da sbloccare", options=list(constraints.keys()), format_func=lambda x: day_map.get(int(x), x))
+                        if st.button("🗑️ Rimuovi Vincolo"):
+                            del emp_record['constraints'][to_del]
+                            st.rerun()
+
+                    with st.expander("➕ Aggiungi una nuova regola per questo dipendente"):
+                        ac1, ac2 = st.columns(2)
+                        add_d = ac1.selectbox("Giorno della settimana", range(7), format_func=lambda x: day_map[x])
+                        add_t = ac2.selectbox("Tipologia di regola", ["absence", "hard", "soft"], format_func=lambda x: "Assenza" if x=="absence" else ("Turno Obbligato (Hard)" if x=="hard" else "Preferenza Oraria (Soft)"))
+                        
+                        new_rule = {"type": add_t}
+                        if add_t == "absence":
+                            new_rule["reason"] = st.selectbox("Motivo Assenza", ["FERIE", "MALATTIA", "PERMESSO"])
+                        else:
+                            t_val = st.time_input("Orario di inzio desiderato").strftime("%H:%M")
+                            new_rule["start_time"] = t_val
+                            
+                        if st.button("Conferma Inserimento"):
+                            if 'constraints' not in emp_record: emp_record['constraints'] = {}
+                            emp_record['constraints'][str(add_d)] = new_rule
+                            st.rerun()
+    else:
+        st.error("Payload anagrafico mancante o corrotto.")
+
+# ------------------------------------------------------------------------------
+# TAB 3: DEMAND TIME-SERIES (FABBISOGNO)
+# ------------------------------------------------------------------------------
+with tab3:
+    st.header("📈 Time-Series Fabbisogno Operativo")
+    st.caption("Visualizza e modifica la curva di traffico o il numero di operatori richiesti per ogni frazione oraria.")
+    
+    demand_filename = "demand.json"
+    conf = load_json(selected_activity, "activity_config.json")
+    raw_demand = load_json(selected_activity, demand_filename)
+    
+    if conf:
+        sett = conf.get('client_settings', {})
+        start_h = sett.get('day_start_hour', 8)
+        end_h = sett.get('day_end_hour', 20)
+        slot_min = sett.get('planning_slot_minutes', 30)
+
+        current_conf_for_alignment = {'client_settings': {'day_start_hour': start_h, 'day_end_hour': end_h, 'planning_slot_minutes': slot_min}}
+
+        total_min = (end_h - start_h) * 60
+        num_slots = int(total_min / slot_min)
+
+        # Allineamento dinamico della time-series: gestisco i cambi di granularità oraria
+        # troncando o paddando la matrice tramite l'helper apposito.
+        if raw_demand:
+            sanitized_list = sanitize_weekly_demand(raw_demand, current_conf_for_alignment)
+            target_demand = np.array(sanitized_list)
+        else:
+            target_demand = np.ones((7, num_slots), dtype=int) * 5
+        
+        days = ["Lun", "Mar", "Mer", "Gio", "Ven", "Sab", "Dom"]
+    
+        time_labels = []
+        curr_m = start_h * 60
+        end_m = end_h * 60
+        while curr_m < end_m:
+            h = int(curr_m // 60)
+            m = int(curr_m % 60)
+            time_labels.append(f"{h:02d}:{m:02d}")
+            curr_m += slot_min
+            
+        x = np.arange(len(time_labels))
+        
+        day_idx = st.selectbox("Ispeziona Giorno:", range(7), format_func=lambda x: days[x])
+        
+        # Rendering vettoriale del profilo di carico
+        fig, ax = plt.subplots(figsize=(10, 3))
+        daily_curve = target_demand[day_idx]
+        
+        ax.plot(x, daily_curve, color='#e74c3c', linestyle='--', marker='o', markersize=3, label="Target Staff (Richiesto)")
+        ax.fill_between(x, 0, daily_curve, color='#e74c3c', alpha=0.1)
+        
+        step_x = max(1, len(x) // 15) 
+        ax.set_xticks(x[::step_x])
+        ax.set_xticklabels(time_labels[::step_x], rotation=45, fontsize=8)
+        ax.set_title(f"Profilo di Carico: {days[day_idx]}")
+        ax.grid(True, linestyle='--', alpha=0.3)
+        ax.legend()
+        
+        st.pyplot(fig)
+        
+        st.divider()
+        
+        # Uso il data_editor nativo di Streamlit per permettere l'override manuale 
+        # della demand curva direttamente in UI, molto comodo per i planner.
+        st.subheader("✏️ Override Manuale (Modifica Volumi)")
+        st.caption("Fai doppio clic su una cella della tabella per alterare manualmente il numero di operatori richiesti.")
+        df_demand = pd.DataFrame(target_demand, index=days, columns=time_labels)
+        edited_df = st.data_editor(df_demand, width='stretch', height=300)
+        
+        if st.button("💾 Salva Modifiche Curva"):
+            final_json_structure = []
+            for i, row in enumerate(edited_df.values):
+                row_list = [f"Giorno_{i}"] + row.tolist()
+                final_json_structure.append(row_list)
+                
+            save_json(selected_activity, "demand.json", final_json_structure)
+            st.success("✅ Fabbisogno aggiornato e sincronizzato.")
+            st.rerun() 
+    else:
+        st.warning("Impossibile effettuare il render: payload mancante.")
+
+# ------------------------------------------------------------------------------
+# TAB 4: MOTORE DI OTTIMIZZAZIONE
+# ------------------------------------------------------------------------------
+with tab4:
+    st.header("🚀 Motore di Ottimizzazione")
+    st.caption("Avvia l'AI per calcolare l'incastro dei turni migliore in base ai parametri che hai inserito.")
+    
+    col_run, col_stat = st.columns([1, 2])
+    with col_run:
+        run_btn = st.button("✨ AVVIA IL CALCOLO DEI TURNI", type="primary")
+        
+    if run_btn:
+        prog_bar = st.progress(0)
+        status_text = st.empty()
+        
+        # Callback passata all'engine genetico per aggiornare l'interfaccia 
+        # asincronamente durante i pesanti cicli for loop su Numba.
+        def ui_callback(gen, tot, score, div):
+            prog_bar.progress(gen / tot)
+            status_text.markdown(f"🧬 Elaborazione in corso... Generazione: **{gen}/{tot}** | Punteggio Penalità: **{score:.0f}** | Esplorazione: **{div:.2f}%**" )
+            
+        with st.spinner("Compilazione codice macchina (JIT) e calcolo in corso. Potrebbe volerci qualche minuto..."):
+            try:
+                current_act = st.session_state.get('current_activity')
+                if not current_act: raise ValueError("Nessun contesto operativo attivo.")
+                
+                employees = load_employees_from_json(current_act)
+                raw_d = load_json(selected_activity, "demand.json")
+                target = process_demand(raw_d)
+
+                # Applichiamo le regole di business (le chiusure impostate in L2 config)
+                # azzerando forzatamente la domanda oraria per non far schedulare turni.
+                for d in range(7):
+                    closing_slot = cfg.get_closing_slot(d)
+                    if cfg.is_day_closed(d) or closing_slot == 0:
+                        target[d, :] = 0
+                    else:
+                        if closing_slot < target.shape[1]:
+                            target[d, closing_slot:] = 0
+                
+                hours_diff = check_hours_balance(employees, target)
+
+                if hours_diff >= 0:
+                    st.success(f"✅ Controllo Preliminare Superato: Lo staff disponibile copre matematicamente le ore richieste (Surplus: {hours_diff:.1f}h).")
+                else:
+                    st.error(f"⚠️ Attenzione - Sotto-dimensionamento Strutturale: Hai chiesto più ore di quelle contrattualizzate. Verranno generati dei buchi inevitabili (Deficit: {abs(hours_diff):.1f}h).")
+                    
+                # Esecuzione del kernel genetico core
+                top_solutions, div_history = run_genetic_algorithm(employees, target, progress_callback=ui_callback)
+
+                final_pop_sample = np.array([sol['schedule'] for sol in top_solutions])
+                final_diversity = div_history[-1] if div_history else 0.0
+                
+                # Caching dell'output generato nell'oggetto di sessione.
+                # Evita di perdere i risultati (o triggerare ricalcoli) se cambio tab.
+                st.session_state['ga_results'] = {
+                    'top_solutions': top_solutions, 
+                    'diversity_score': final_diversity,
+                    'diversity_history': div_history,
+                    'selected_idx': 0,              
+                    'employees': employees, 
+                    'target': target
+                }
+                
+                best_s = top_solutions[0]['total_score']
+                status_text.success(f"Ottimizzazione conclusa con successo! Miglior punteggio di penalità raggiunto: {best_s:.0f}")
+                
+            except Exception as e:
+                st.error(f"Errore di sistema durante il calcolo: {e}")
+                traceback.print_exc()
+
+    # Blocco di visualizzazione post-run
+    if 'ga_results' in st.session_state:
+        res = st.session_state['ga_results']
+        solutions = res['top_solutions']
+        div_hist = res.get('diversity_history', [res.get('diversity_score', 0.0)])
+        final_div = div_hist[-1]
+        
+        # Diagnostica algoritmica automatizzata (Controlla il drop-rate della diversità)
+        msg, color_code = analyze_convergence_quality(div_hist)
+        
+        st.markdown("### 🩺 Diagnostica e Validazione Scientifica")
+        kpi1, kpi2 = st.columns([1, 3])
+        
+        kpi1.metric("Diversità Genetica Finale", f"{final_div:.2f}%")
+        
+        if color_code == "success": kpi2.success(msg)
+        elif color_code == "normal": kpi2.info(msg)
+        else: kpi2.error(msg)
+            
+        with st.expander("Cos'è la Diversità e come interpretarla?"):
+            st.caption("""
+            La **Diversità** indica quante soluzioni "diverse" l'algoritmo stava ancora testando alla fine del processo.
+            - **Se è >40%:** L'AI non è riuscita a trovare un pattern vincente e ha continuato a sparare a caso (aumenta le Generazioni o diminuisci la Mutazione).
+            - **Se crolla subito a <5% (Convergenza Prematura):** L'AI si è "incastrata" su una soluzione mediocre e ha smesso di cercare (aumenta la Mutazione).
+            - **Se scende gradualmente (Matura):** È lo stato ideale. L'AI ha esplorato bene e poi ha "stretto" verso la soluzione perfetta.
+            """)
+        
+        if div_hist:
+            st.subheader("📉 Profilo Dinamico dell'Apprendimento")
+            
+            fig_div, ax_div = plt.subplots(figsize=(10, 3))
+            x_axis = [i * 5 for i in range(len(div_hist))]
+            
+            ax_div.plot(x_axis, div_hist, color='#2980b9', linewidth=2, label='Varianza di Popolazione (%)')
+            ax_div.axhspan(0, 5, color='#e74c3c', alpha=0.1, label='Rischio Collasso (<5%)')
+            ax_div.axhspan(40, 100, color='#e67e22', alpha=0.1, label='Rischio Divergenza (>40%)')
+            ax_div.axhspan(5, 40, color='#2ecc71', alpha=0.1, label='Fascia Ottimale')
+            
+            ax_div.set_ylabel("Hamming Dist (%)")
+            ax_div.set_xlabel("Epoche di Addestramento")
+            ax_div.set_ylim(0, max(50, max(div_hist) + 5)) 
+            ax_div.grid(True, linestyle='--', alpha=0.5)
+            ax_div.legend(loc='upper right', fontsize='small')
+            
+            st.pyplot(fig_div)
+            plt.close(fig_div)
+            
+            with st.expander("Come leggere questo grafico?"):
+                st.caption("""
+                Questo grafico racconta visivamente il lavoro dell'algoritmo:
+                1. **Fase Iniziale (Esplorazione):** Il grafico deve partire alto (fuori dal rosso basso). L'AI sta provando incastri creativi.
+                2. **Discesa (Sfruttamento):** La curva deve scendere dolcemente verso il basso.
+                3. **Atterraggio:** La curva dovrebbe stabilizzarsi nella **Fascia Verde Ottimale**. Se vedi crolli verticali improvvisi all'inizio, c'è un problema di configurazione nei parametri genetici.
+                """)
+            
+        st.divider()
+        st.subheader("🏆 Esplorazione delle Migliori Soluzioni Trovate")
+        st.caption("L'algoritmo ti propone le varianti più performanti. Lo SCORE TOTALE è la somma delle penalità (più è basso, meglio è).")
+        
+        comp_data = []
+        for i, s in enumerate(solutions):
+            comp_data.append({
+                "Candidato": f"Soluzione #{i+1}",
+                "SCORE TOTALE (Penalità)": int(s['total_score']),
+                "❌ Understaffing (Buchi)": int(s['understaffing']),
+                "⚖️ Inequità Weekend": int(s['equity']),
+                "⚡ Overstaffing (Eccessi)": int(s['overstaffing']),
+                "🎨 Pref. Ignorate": int(s['soft_preferences']),
+                "📝 Mix Contratti Violato": int(s['contract'])
+            })
+            
+        df_comp = pd.DataFrame(comp_data)
+        st.dataframe(
+            df_comp.style.background_gradient(cmap="RdYlGn_r", subset=["SCORE TOTALE (Penalità)", "❌ Understaffing (Buchi)"]),
+            width='stretch',
+            hide_index=True
+        )
+        
+        sel_opt = st.radio("Seleziona quale piano turni visualizzare in dettaglio:", 
+                           options=range(len(solutions)), 
+                           format_func=lambda x: f"Apri Dettaglio Soluzione #{x+1}",
+                           horizontal=True,
+                           index=st.session_state.get('selected_idx', 0))
+        
+        st.session_state['ga_results']['selected_idx'] = sel_opt
+        
+        chosen_sol = solutions[sel_opt]
+        best_sched = chosen_sol['schedule']
+        emps = res['employees']
+        tgt = res['target']
+
+        st.subheader(f"Dashboard Copertura: Soluzione #{sel_opt+1}")
+        st.caption("Confronto visivo tra le persone richieste (linea rossa tratteggiata) e le persone messe a turno (area blu).")
+        
+        d_tabs = st.tabs(["Lunedì", "Martedì", "Mercoledì", "Giovedì", "Venerdì", "Sabato", "Domenica"])
+        
+        # Proietto il genoma elaborato (best_sched) sulla matrice di copertura per le charts
+        cov_mat = get_final_coverage_matrix(best_sched, emps)
+        
+        for i, t in enumerate(d_tabs):
+            with t:
+                fig, ax = plt.subplots(figsize=(8, 2))
+                x = range(cfg.daily_slots)
+                ax.fill_between(x, cov_mat[i], alpha=0.3)
+                ax.plot(x, cov_mat[i], label="Staff Schedulato")
+                ax.plot(x, tgt[i], 'r--', label="Staff Richiesto (Target)")
+                tick_step = 4
+                lbls = [minutes_to_time(k * cfg.system_slot_minutes) for k in x[::tick_step]]
+                ax.set_xticks(list(x)[::tick_step])
+                ax.set_xticklabels(lbls, rotation=0, fontsize=4)
+                ax.legend()
+                st.pyplot(fig)
+                plt.close(fig)
+
+        st.subheader("Tabellone Turni (Export)")
+        data_rows = []
+        days = ["Lun", "Mar", "Mer", "Gio", "Ven", "Sab", "Dom"]
+        for idx, e in enumerate(emps):
+            row = {"Dipendente": e['id']}
+            for d in range(7):
+                s = best_sched[idx, d]
+                if s == -1: txt = "OFF"
+                elif s == -2: txt = "ABS"
+                else:
+                    start = s * cfg.system_slot_minutes
+                    end = start + (e['shift_len'] * cfg.system_slot_minutes)
+                    txt = f"{minutes_to_time(start)}-{minutes_to_time(end)}"
+                row[days[d]] = txt
+            data_rows.append(row)
+        st.dataframe(pd.DataFrame(data_rows), width='stretch')
+
+        st.markdown("---")
+        st.subheader("🔬 Ispezione Micro-Turno (Maschere VDT e Pause)")
+        st.caption("Verifica la corretta allocazione delle pause VDT all'interno dello spezzato del singolo operatore.")
+        
+        # Micro-rendering della maschera binaria per l'ispezione visiva dei sub-slot
+        c1, c2 = st.columns(2)
+        sel_emp = c1.selectbox("Seleziona Operatore", [e['id'] for e in emps])
+        sel_day = c2.selectbox("Seleziona Giorno", range(7), format_func=lambda x: days[x])
+        
+        e_idx = next(i for i,e in enumerate(emps) if e['id'] == sel_emp)
+        s_start = best_sched[e_idx, sel_day]
+        
+        if s_start >= 0:
+            mask = emps[e_idx]['mask']
+            html = ""
+            for k, bit in enumerate(mask):
+                t_str = minutes_to_time((s_start + k) * cfg.system_slot_minutes)
+                col = "#4CAF50" if bit else "#FF5252"
+                html += f"<div style='display:inline-block;width:35px;background:{col};color:white;font-size:10px;text-align:center;margin:1px;'>{t_str}</div>"
+            st.markdown(html, unsafe_allow_html=True)
+            st.caption("**Legenda:** [Verde] = Operatività a Terminale | [Rosso] = Pausa/Pranzo")
+        else:
+            st.info("Status per il giorno selezionato: RIPOSO o ASSENTE.")
+
+# ------------------------------------------------------------------------------
+# TAB 5: BOOTSTRAPPING DI MOCK SCENARIOS (GENERATORE)
+# ------------------------------------------------------------------------------
+with tab5:
+    st.header("⚡ Generatore Ambienti di Test (Mock Scenarios)")
+    st.markdown("""
+    Crea rapidamente nuovi scenari completi per testare come il motore AI reagisce a diverse 
+    composizioni della forza lavoro (es. alta rigidità vs alta flessibilità).
+    """)
+    
+    col_gen_L, col_gen_R = st.columns([1, 2])
+    
+    with col_gen_L:
+        st.subheader("1. Setup Spazio Dati")
+        new_scenario_name = st.text_input("Nome del nuovo Scenario", value="Nuovo_Test_BPO")
+        new_emp_count = st.number_input("Numero Dipendenti Fittizi", min_value=1, max_value=2000, value=300, step=10)
+        
+        st.markdown("---")
+        st.subheader("📊 Modello Matematico del Fabbisogno")
+        st.caption("Scegli una distribuzione che simuli fedelmente il traffico del servizio.")
+        
+        curve_options = {
+            "Doppia Campana (Tipico BPO Voice)": "double_bell",
+            "Campana Centrale (Es. Delivery/Pausa Pranzo)": "single_bell_center",
+            "Picco Mattutino (Es. Helpdesk IT)": "morning_peak",
+            "Piatto Costante (Es. Backoffice/Data Entry)": "steady_high"
+        }
+        
+        selected_curve_label = st.selectbox("Seleziona Modello di Carico:", options=list(curve_options.keys()), index=0)
+        curve_key = curve_options[selected_curve_label]
+        
+        st.caption("Anteprima Forma:")
+        
+        # Anteprima visiva matematica della distribuzione scelta
+        preview_x = np.linspace(8, 22, 50)
+        if curve_key == "double_bell":
+            preview_y = np.exp(-((preview_x - 11)**2)/4) + np.exp(-((preview_x - 16)**2)/4)
+        elif curve_key == "single_bell_center":
+            preview_y = np.exp(-((preview_x - 13)**2)/9)
+        elif curve_key == "morning_peak":
+            preview_y = np.exp(-((preview_x - 9.5)**2)/5)
+        else:
+            preview_y = np.ones_like(preview_x) * 0.8
+            
+        fig_curve_prev, ax_cp = plt.subplots(figsize=(4, 1.5))
+        ax_cp.plot(preview_x, preview_y, color='#2ecc71', lw=2)
+        ax_cp.fill_between(preview_x, preview_y, color='#2ecc71', alpha=0.2)
+        ax_cp.set_yticks([])
+        ax_cp.set_xticks([8, 12, 16, 20])
+        ax_cp.set_xlim(8, 22)
+        fig_curve_prev.patch.set_alpha(0.0)
+        ax_cp.patch.set_alpha(0.0)
+        st.pyplot(fig_curve_prev)
+
+    with col_gen_R:
+        st.subheader("2. Strategia HR (Mix Contrattuale)")
+        st.caption("Simula il livello di flessibilità del personale.")
+        
+        pct_ft40 = st.slider("🔵 Full Time (8h - Alta rigidità)", 0, 100, 60)
+        pct_pt30 = st.slider("🟡 Part Time (6h - Media flessibilità)", 0, 100, 20)
+        remaining = max(0, 100 - (pct_ft40 + pct_pt30))
+        pct_pt20 = st.slider("🔴 Part Time (4h - Alta flessibilità)", 0, 100, remaining)
+        
+        total_mix = pct_ft40 + pct_pt30 + pct_pt20
+        
+        if total_mix != 100:
+            st.warning(f"⚠️ La somma deve essere 100%. Attuale: {total_mix}%.")
+        else:
+            st.success("✅ Composizione valida.")
+            
+            fig_preview, ax_prev = plt.subplots(figsize=(3, 1.5))
+            data_prev, labels_prev, colors_prev = [pct_ft40, pct_pt30, pct_pt20], ['FT 8h', 'PT 6h', 'PT 4h'], ['#3498db', '#f1c40f', '#e74c3c']
+            d_clean, l_clean, c_clean = zip(*[(d, l, c) for d, l, c in zip(data_prev, labels_prev, colors_prev) if d > 0])
+            
+            wedges, texts, autotexts = ax_prev.pie(d_clean, labels=None, colors=c_clean, autopct='%1.0f%%', textprops={'color':"white", 'fontsize': 8, 'weight': 'bold'}, pctdistance=0.5)
+            ax_prev.axis('equal')
+            fig_preview.patch.set_alpha(0.0)
+            
+            leg = ax_prev.legend(wedges, l_clean, loc="center left", bbox_to_anchor=(1, 0, 0.5, 1), frameon=False, labelcolor='white', fontsize=7)
+            st.pyplot(fig_preview, width='content')
+
+    st.divider()
+    
+    btn_col, _ = st.columns([1, 3])
+    if btn_col.button("🚀 Inizializza Scenario su HF", type="primary", disabled=(total_mix != 100)):
+        if not new_scenario_name.strip():
+            st.error("Nome scenario non valido.")
+        else:
+            with st.spinner("Creazione dati fittizi e upload in corso..."):
+                mix_dict = {'FT40': pct_ft40, 'PT30': pct_pt30, 'PT20': pct_pt20}
+                success, msg = generate_scenario_files(new_scenario_name, new_emp_count, mix_dict, curve_key)
+                
+                if success:
+                    st.success(f"{msg}")
+                    st.info("🔄 Clicca su 'Ricarica App' nella barra laterale sinistra per gestire questo nuovo scenario.")
+                else:
+                    st.error(f"Errore di sistema: {msg}")

requirements.txt

@@ -0,0 +1,6 @@
+numpy
+matplotlib
+streamlit
+pandas
+numba
+huggingface_hub

src/config.py

@@ -0,0 +1,143 @@
+import json
+import os
+from src.utils.hf_storage import load_json
+
+class ConfigManager:
+    """
+    Singleton implementation for global configuration state management.
+    Gestisce il caricamento a cascata (Cascade Loading) dei parametri di sistema e di dominio.
+    """
+    _instance = None
+    
+    def __new__(cls, activity_name=None):
+        if cls._instance is None:
+            cls._instance = super(ConfigManager, cls).__new__(cls)
+            cls._instance.initialized = False
+        return cls._instance
+
+    def __init__(self, activity_name=None):
+        # Lazy Initialization: previene la sovrascrittura dello stato su chiamate multiple
+        if getattr(self, 'initialized', False) and not activity_name:
+            return
+
+        # --- L0: HARDCODED FALLBACKS (Safety Net) ---
+        self.activity_name = None
+        self.system_slot_minutes = 15
+        self.planning_slot_minutes = 30
+        self.expansion_factor = 2
+        self.daily_slots = 96  
+        
+        # Safe allocations per le strutture di dominio
+        self.client_settings = {"day_start_hour": 8, "day_end_hour": 20}
+        self.system_settings = {"vdt_interval_minutes": 120, "vdt_break_minutes": 15}
+        self.weights = {"understaffing": 1000, "overstaffing": 10, "homogeneity": 20, "soft_preference": 50}
+        
+        # Hyper-parametri di default per l'Engine Genetico
+        self.genetic_params = {
+            "population_size": 200, "generations": 100, "mutation_rate": 0.3,
+            "crossover_rate": 0.8, "elitism_rate": 0.02, "tournament_size": 5,          
+            "heuristic_rate": 0.8, "guided_mutation_split": 0.4, "heuristic_noise": 0.2
+        }
+        
+        # Inizializzazione sicura del routing orario
+        self.operating_hours = {"default": "09:00-18:00", "exceptions": {}}
+        self.hours = self.operating_hours 
+
+        if activity_name:
+            self.load_configurations(activity_name)
+        else:
+            print("[WARN] ConfigManager istanziato senza context. Approvvigionamento defaults (L0) completato.")
+            self.initialized = True 
+
+    def load_configurations(self, activity_name):
+        """Orchestratore del configuration loading a 3 livelli (L0 -> L1 -> L2)."""
+        self.activity_name = activity_name
+        base_path = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) 
+        
+        # --- L1: ENGINE CONFIG (Global System Overrides) ---
+        engine_path = os.path.join(base_path, "src", "config", "engine_config.json")
+        try:
+            if os.path.exists(engine_path):
+                with open(engine_path, 'r') as f:
+                    engine_data = json.load(f)
+                if 'system_settings' in engine_data:
+                    self.system_settings.update(engine_data['system_settings'])
+                    self.system_slot_minutes = self.system_settings.get('system_slot_minutes', 15)
+                if 'genetic_params' in engine_data:
+                    self.genetic_params.update(engine_data['genetic_params'])
+        except Exception as e:
+            print(f"[WARN] Impossibile risolvere L1 engine_config.json ({e}). Proceeding with L0.")
+
+        # --- L2: ACTIVITY CONFIG (Tenant/Domain Specifics via Object Storage) ---
+        activity_data = load_json(activity_name, "activity_config.json")
+        
+        if not activity_data:
+             print(f"[FATAL] Configurazione L2 mancante sul Dataset HF per l'attività '{activity_name}'.")
+             return
+            
+        # Merging dei layer applicativi
+        self.client_settings = activity_data.get('client_settings', self.client_settings)
+        self.planning_slot_minutes = self.client_settings.get('planning_slot_minutes', 30)
+        
+        if 'weights' in activity_data: 
+            self.weights = activity_data['weights']
+        if 'operating_hours' in activity_data:
+            self.operating_hours = activity_data['operating_hours']
+            self.hours = self.operating_hours
+        if 'genetic_params' in activity_data:
+            self.genetic_params.update(activity_data['genetic_params'])
+        
+        # --- DERIVED METRICS COMPUTATION ---
+        self.slot_minutes = self.system_slot_minutes
+        self.expansion_factor = int(self.planning_slot_minutes / self.system_slot_minutes)
+        if self.expansion_factor < 1: 
+            self.expansion_factor = 1
+        
+        # Calcolo dimensione tensore giornaliero
+        start = self.client_settings.get('day_start_hour', 8)
+        end = self.client_settings.get('day_end_hour', 20)
+        self.daily_slots = int((end - start) * 60 / self.system_slot_minutes)
+        if self.daily_slots <= 0: 
+            self.daily_slots = 96 
+        
+        self.initialized = True
+        print(f"[OK] State Sync completato: {activity_name} (Shift Bounds: {start}:00-{end}:00, Grid: {self.daily_slots} slots)")
+
+    def get_closing_slot(self, day_idx):
+        """Mappa l'orario di chiusura algebrico sull'indice dello slot di sistema."""
+        day_str = str(day_idx)
+        exceptions = self.hours.get('exceptions', {})
+        
+        # 1. Rule Extraction (Exception override vs Baseline)
+        if day_str in exceptions:
+            time_range = exceptions[day_str]
+        else:
+            time_range = self.hours.get('default', "09:00-18:00")
+            
+        # 2. Explicit closure flag
+        if str(time_range).strip().upper() == "CLOSED": 
+            return 0
+        
+        try:
+            # 3. Time-to-Slot Quantization
+            _, close_time = time_range.split('-')
+            h, m = map(int, close_time.split(':'))
+            
+            start_h = self.client_settings.get('day_start_hour', 8)
+            minutes_from_start = (h - start_h) * 60 + m
+            
+            divisor = self.system_slot_minutes if self.system_slot_minutes > 0 else 15
+            
+            slot_idx = int(minutes_from_start / divisor)
+            return max(0, slot_idx) 
+
+        except Exception as e:
+            # Failsafe: Parsing error mappato come hard closure per prevenire out-of-bounds nell'engine C/Numba
+            print(f"[ERROR] Constraint parsing fallito sul Day {day_idx} ('{time_range}'): {e}. Forzatura status CLOSED.")
+            return 0 
+
+    def is_day_closed(self, day_idx):
+        return self.get_closing_slot(day_idx) == 0
+
+# Istanza globale esportata per i moduli downstream
+cfg = ConfigManager()

src/config/engine_config.json

@@ -0,0 +1,18 @@
+{
+  "system_settings": {
+    "system_slot_minutes": 15,  
+    "vdt_interval_minutes": 120,   
+    "vdt_break_minutes": 15,
+    "version": "1.0"
+  },
+  "genetic_params": {
+    "population_size": 200,
+    "generations": 500,
+    "mutation_rate": 0.2,
+    "crossover_rate": 0.85,
+    "elitism_rate": 0.02,          
+    "tournament_size": 5,          
+    "heuristic_rate": 0.8,         
+    "guided_mutation_split": 0.4
+  }
+}

src/engine/crossover.py

@@ -0,0 +1,29 @@
+import numpy as np
+import random
+from src.config import cfg
+
+def crossover(parent1, parent2):
+    """
+    Operatore di Uniform Crossover vettorializzato.
+    Scambia le agende settimanali intere (righe) tra i due genitori 
+    per mantenere la coerenza dei vincoli e del target ore sul singolo dipendente.
+    """
+    rate = cfg.genetic_params.get('crossover_rate', 0.85)
+    
+    # Bypass dell'operatore in base alla probabilità (preservazione dei tratti parentali)
+    if random.random() > rate:
+        return parent1.copy(), parent2.copy()
+        
+    rows, _ = parent1.shape
+    
+    # Generazione di una maschera booleana 1D per l'estrazione delle righe (dipendenti)
+    mask = np.random.rand(rows) < 0.5
+    
+    child1 = parent1.copy()
+    child2 = parent2.copy()
+    
+    # Swap vettorializzato: incrociamo i genomi sovrascrivendo le righe mascherate
+    child1[mask] = parent2[mask]
+    child2[mask] = parent1[mask]
+    
+    return child1, child2

src/engine/evolution.py

@@ -0,0 +1,344 @@
+import numpy as np
+from numba import njit, prange
+from src.config import cfg
+from src.problems.my_problem import convert_employees_to_numpy
+from src.engine.selection import tournament_selection, calculate_population_fitness_parallel, calculate_fitness_numba, calculate_detailed_score, get_valid_start_slots_numba, CODE_OFF
+from src.engine.crossover import crossover
+from src.engine.mutation import mutate
+from src.utils.health import calculate_diversity_snapshot
+
+@njit(cache=True)
+def _generate_single_random_individual(num_emps, num_days, lengths, target_days_arr, cons_types, cons_vals, closing_slots, is_closed_arr):
+    """
+    Genera un individuo con assegnazioni di turni completamente casuali.
+    """
+    roster = np.full((num_emps, num_days), CODE_OFF, dtype=np.int64)
+    
+    for i in range(num_emps):
+        shift_len = lengths[i]
+        days_worked_indices = np.empty(7, dtype=np.int64) 
+        dw_ptr = 0
+        
+        # Assegnazione casuale degli slot validi
+        for d in range(num_days):
+            ctype = cons_types[i, d]
+            cval = cons_vals[i, d]
+            c_slot = closing_slots[d]
+            closed = is_closed_arr[d]
+            
+            valid = get_valid_start_slots_numba(d, shift_len, ctype, cval, c_slot, closed)
+            
+            if len(valid) > 0:
+                chosen = valid[np.random.randint(0, len(valid))]
+                roster[i, d] = chosen
+                if chosen >= 0:
+                    days_worked_indices[dw_ptr] = d
+                    dw_ptr += 1
+        
+        # Drop dei giorni in eccesso rispetto al target contrattuale
+        tgt = target_days_arr[i]
+        while dw_ptr > tgt:
+            idx_in_buffer = np.random.randint(0, dw_ptr)
+            day_to_remove = days_worked_indices[idx_in_buffer]
+            roster[i, day_to_remove] = CODE_OFF
+            
+            days_worked_indices[idx_in_buffer] = days_worked_indices[dw_ptr - 1]
+            dw_ptr -= 1
+            
+    return roster
+
+@njit(cache=True)
+def _generate_single_heuristic_individual(num_emps, num_days, lengths, target_days_arr, cons_types, cons_vals, closing_slots, is_closed_arr, target_demand, randomness):
+    """
+    Genera un individuo usando un approccio greedy basato sulla demand residua.
+    """
+    num_slots = target_demand.shape[1]
+    roster = np.full((num_emps, num_days), CODE_OFF, dtype=np.int64)
+    
+    # Copia locale della demand per aggiornare i residui
+    residual = target_demand.copy().astype(np.float64)
+    emp_order = np.random.permutation(num_emps)
+    
+    for i in emp_order:
+        shift_len = lengths[i]
+        tgt = target_days_arr[i]
+        
+        # Calcolo dei giorni con maggior necessità operativa
+        daily_needs = np.zeros(num_days, dtype=np.float64)
+        for d in range(num_days):
+            s = 0.0
+            for k in range(num_slots):
+                s += residual[d, k]
+            daily_needs[d] = s
+            
+        if randomness > 0:
+            noise = np.random.randn(num_days) * (np.mean(daily_needs) * randomness)
+            daily_needs += noise
+            
+        sorted_days = np.argsort(daily_needs)
+        start_idx = max(0, num_days - tgt)
+        preferred_days = sorted_days[start_idx:]
+        
+        # Assegnazione dello slot migliore sul giorno scelto
+        for day in preferred_days:
+            ctype = cons_types[i, day]
+            cval = cons_vals[i, day]
+            c_slot = closing_slots[day]
+            closed = is_closed_arr[day]
+            
+            valid = get_valid_start_slots_numba(day, shift_len, ctype, cval, c_slot, closed)
+            
+            if len(valid) == 0:
+                roster[i, day] = CODE_OFF
+                continue
+                
+            # Torneo limitato a 5 candidati per ridurre l'overhead
+            n_cand = len(valid)
+            limit = 5
+            if n_cand <= limit:
+                candidates = valid
+            else:
+                candidates = np.empty(limit, dtype=np.int64)
+                for k in range(limit):
+                    candidates[k] = valid[np.random.randint(0, n_cand)]
+            
+            best_slot = candidates[0]
+            best_score = -1e9
+            
+            for slot in candidates:
+                if slot < 0: continue
+                end = min(slot + shift_len, num_slots)
+                score = 0.0
+                for k in range(slot, end):
+                    score += residual[day, k]
+                if score > best_score:
+                    best_score = score
+                    best_slot = slot
+            
+            roster[i, day] = best_slot
+            
+            if best_slot >= 0:
+                end = min(best_slot + shift_len, num_slots)
+                for k in range(best_slot, end):
+                    val = residual[day, k] - 1.0
+                    if val < 0: val = 0.0
+                    residual[day, k] = val
+                    
+    return roster
+
+@njit(parallel=True, cache=True)
+def initialize_population_fast_wrapper(pop_size, heuristic_limit, numpy_data, target_demand, randomness, closing_slots, is_closed_arr):
+    """
+    Wrapper JIT parallelo per la generazione massiva della popolazione.
+    """
+    _, lengths, target_days_arr, cons_types, cons_vals = numpy_data
+    num_emps = len(lengths)
+    num_days = 7
+
+    population = np.zeros((pop_size, num_emps, num_days), dtype=np.int64)
+    
+    for p in prange(pop_size):
+        if p < heuristic_limit:
+            population[p] = _generate_single_heuristic_individual(
+                num_emps, num_days, lengths, target_days_arr, cons_types, cons_vals, 
+                closing_slots, is_closed_arr, target_demand, randomness
+            )
+        else:
+            population[p] = _generate_single_random_individual(
+                num_emps, num_days, lengths, target_days_arr, cons_types, cons_vals, 
+                closing_slots, is_closed_arr
+            )
+            
+    return population
+
+def initialize_population_numba(pop_size, numpy_data, target_demand, cfg):
+    heuristic_rate = cfg.genetic_params.get('heuristic_rate', 0.8)
+    heuristic_noise = cfg.genetic_params.get('heuristic_noise', 0.2)
+    
+    num_heuristic = int(pop_size * heuristic_rate)
+    
+    print(f"[*] Inizializzazione popolazione: {num_heuristic} greedy, {pop_size - num_heuristic} random")
+    
+    # Passaggio array espliciti per bypassare le limitazioni di Numba sugli oggetti custom
+    closing_slots = np.array([cfg.get_closing_slot(d) for d in range(7)], dtype=np.int64)
+    is_closed_arr = np.array([1 if cfg.is_day_closed(d) else 0 for d in range(7)], dtype=np.int64)
+    
+    return initialize_population_fast_wrapper(
+        pop_size, num_heuristic, numpy_data, target_demand, heuristic_noise, closing_slots, is_closed_arr
+    )
+
+def precompute_slots_cache_numba(numpy_data):
+    """Pre-calcolo della cache degli slot validi per velocizzare le mutazioni."""
+    masks, lengths, target_days_arr, cons_types, cons_vals = numpy_data
+    num_emps = len(lengths)
+    cache = []
+    for i in range(num_emps):
+        emp_days = []
+        shift_len = lengths[i]
+        for d in range(7):
+            ctype = cons_types[i, d]
+            cval = cons_vals[i, d]
+            closing_slot = cfg.get_closing_slot(d)
+            is_closed = cfg.is_day_closed(d)
+            slots = get_valid_start_slots_numba(d, shift_len, ctype, cval, closing_slot, is_closed)
+            emp_days.append(slots)
+        cache.append(emp_days)
+    return cache
+
+def run_genetic_algorithm(employees, target_demand, progress_callback=None):
+    print("[*] Conversione dati in tensori NumPy...")
+    numpy_data = convert_employees_to_numpy(employees)
+    
+    if numpy_data[0] is None:
+        return []
+
+    print("[*] Generazione cache degli slot...")
+    slots_cache = precompute_slots_cache_numba(numpy_data)
+    
+    pop_size = cfg.genetic_params['population_size']
+    generations = cfg.genetic_params['generations']
+    
+    population = initialize_population_numba(pop_size, numpy_data, target_demand, cfg)
+    
+    weights_arr = np.array([
+        cfg.weights['understaffing'],
+        cfg.weights['overstaffing'],
+        cfg.weights['homogeneity'],
+        cfg.weights['soft_preference'],
+        0.0 
+    ], dtype=np.float64)
+    
+    daily_slots_scalar = int(cfg.daily_slots)
+    elitism_rate = cfg.genetic_params.get('elitism_rate', 0.02)
+    
+    masks, lengths, target_days_arr, cons_types, cons_vals = numpy_data
+    
+    best_score = float('inf')
+    best_coverage = None
+    best_overall = None 
+
+    diversity_history = []
+    current_diversity = 0.0
+
+    print(f"[*] Avvio evoluzione: {generations} generazioni, size {len(population)}")
+    
+    for gen in range(generations):
+        
+        # 1. Valutazione Fitness
+        scores = calculate_population_fitness_parallel(
+            population, 
+            masks, lengths, target_days_arr, cons_types, cons_vals, 
+            target_demand, weights_arr, daily_slots_scalar
+        )
+        
+        min_curr = np.min(scores)
+        best_idx = np.argmin(scores)
+        
+        if min_curr < best_score:
+            best_score = min_curr
+            best_overall = population[best_idx].copy()
+            _, best_coverage = calculate_fitness_numba(
+                population[best_idx], masks, lengths, target_days_arr, cons_types, cons_vals, 
+                target_demand, weights_arr, daily_slots_scalar
+            )
+
+        if gen % 5 == 0 or gen == generations - 1:
+            sample_rate = 0.20 
+            dynamic_sample = int(len(population) * sample_rate)
+            
+            # Clamp del sample size per bilanciare significatività statistica e overhead Numba
+            sample_size = max(20, min(dynamic_sample, 200))
+            sample_size = min(sample_size, len(population))
+            
+            indices = np.random.choice(len(population), sample_size, replace=False)
+            pop_sample = population[indices]
+            
+            current_diversity = calculate_diversity_snapshot(pop_sample)
+            diversity_history.append(current_diversity)
+            
+        if progress_callback:
+            progress_callback(gen + 1, generations, best_score, current_diversity)
+            
+        # 2. Setup Deficit per le mutazioni guidate
+        if best_coverage is None:
+            current_gap = target_demand
+        else:
+            current_gap = target_demand - best_coverage
+        
+        daily_deficit = np.sum(np.maximum(current_gap, 0), axis=1)
+        total_deficit = np.sum(daily_deficit)
+        if total_deficit > 0:
+            daily_deficit_probs = daily_deficit / total_deficit
+        else:
+            daily_deficit_probs = np.ones(7) / 7.0
+
+        # 3. Next Gen & Elitismo
+        new_pop = []
+        n_elites = max(2, int(len(population) * elitism_rate))
+        elite_indices = np.argsort(scores)[:n_elites]
+        for idx in elite_indices:
+            new_pop.append(population[idx].copy())
+            
+        while len(new_pop) < len(population):
+            p1 = tournament_selection(population, scores)
+            p2 = tournament_selection(population, scores)
+            c1, c2 = crossover(p1, p2)
+            new_pop.append(mutate(c1, slots_cache, daily_deficit_probs))
+            if len(new_pop) < len(population):
+                new_pop.append(mutate(c2, slots_cache, daily_deficit_probs))
+        
+        population = np.array(new_pop)
+
+    print("[*] Estrazione top 5 soluzioni uniche...")
+    final_scores = calculate_population_fitness_parallel(
+        population, masks, lengths, target_days_arr, cons_types, cons_vals, 
+        target_demand, weights_arr, daily_slots_scalar
+    )
+    
+    sorted_indices = np.argsort(final_scores)
+    top_solutions = []
+    seen_hashes = set()
+    
+    for idx in sorted_indices:
+        ind = population[idx]
+        ind_hash = ind.tobytes()
+        if ind_hash in seen_hashes: continue
+        seen_hashes.add(ind_hash)
+        
+        details = calculate_detailed_score(
+            ind, masks, lengths, target_days_arr, cons_types, cons_vals, 
+            target_demand, weights_arr, daily_slots_scalar
+        )
+        
+        sol_data = {
+            "schedule": ind.copy(),
+            "total_score": details[0],
+            "understaffing": details[1],
+            "overstaffing": details[2],
+            "homogeneity": details[3],
+            "soft_preferences": details[4],
+            "contract": details[5],
+            "equity": details[6]
+        }
+        top_solutions.append(sol_data)
+        
+        if len(top_solutions) >= 5: break
+            
+    # Fallback in caso di mancata convergenza su soluzioni uniche
+    if not top_solutions and best_overall is not None:
+         details = calculate_detailed_score(
+            best_overall, masks, lengths, target_days_arr, cons_types, cons_vals, 
+            target_demand, weights_arr, daily_slots_scalar
+        )
+         top_solutions.append({
+            "schedule": best_overall,
+            "total_score": details[0],
+            "understaffing": details[1],
+            "overstaffing": details[2],
+            "homogeneity": details[3],
+            "soft_preferences": details[4],
+            "contract": details[5],
+            "equity": details[6]
+        })
+
+    return top_solutions, diversity_history

src/engine/mutation.py

@@ -0,0 +1,66 @@
+import numpy as np
+import random
+from src.config import cfg
+
+CODE_OFF = -1
+
+def mutate(individual, slots_cache, daily_deficit_probs):
+    """
+    Applica operatore di mutazione con logica ibrida (Guided/Random).
+    """
+    mut_rate = cfg.genetic_params.get('mutation_rate', 0.4) 
+    split_rate = cfg.genetic_params.get('guided_mutation_split', 0.4) 
+    
+    # Early exit se non triggeriamo la mutazione (risparmio computazionale)
+    if random.random() > mut_rate:
+        return individual
+
+    mutated = individual.copy()
+    num_emps, num_days = mutated.shape
+    emp_idx = random.randint(0, num_emps - 1)
+    
+    if random.random() < split_rate: 
+        # --- MUTATION STRATEGY 1: Day Swap (Guided) ---
+        # Sposta un turno da un giorno all'altro cercando di coprire i deficit operativi
+        row = mutated[emp_idx]
+        days_worked = np.where(row >= 0)[0]
+        days_off = np.where(row == CODE_OFF)[0]
+        
+        if len(days_worked) > 0 and len(days_off) > 0:
+            
+            # 1. Selezione del giorno da riempire (pesata sul deficit)
+            try:
+                probs_off = daily_deficit_probs[days_off]
+                if np.sum(probs_off) > 0:
+                    probs_off = probs_off / np.sum(probs_off)
+                    day_to_fill = np.random.choice(days_off, p=probs_off)
+                else:
+                    day_to_fill = np.random.choice(days_off)
+            except:
+                # Safe check in caso di anomalie nei tensori
+                day_to_fill = np.random.choice(days_off)
+            
+            # 2. Selezione del giorno da svuotare (inversamente proporzionale al deficit)
+            try:
+                probs_work = 1.0 - daily_deficit_probs[days_worked]
+                probs_work = probs_work + 0.01 # Smoothing per evitare probabilità nulle
+                probs_work = probs_work / np.sum(probs_work)
+                day_to_empty = np.random.choice(days_worked, p=probs_work)
+            except:
+                day_to_empty = np.random.choice(days_worked)
+            
+            # Esegue lo swap solo se esistono slot validi nella cache pre-calcolata
+            valid_slots = slots_cache[emp_idx][day_to_fill]
+            if len(valid_slots) > 0:
+                mutated[emp_idx, day_to_fill] = np.random.choice(valid_slots)
+                mutated[emp_idx, day_to_empty] = CODE_OFF
+    else:
+        # --- MUTATION STRATEGY 2: Time Shift ---
+        # Perturba randomicamente l'orario di inizio turno sullo stesso giorno
+        day_idx = random.randint(0, 6)
+        if mutated[emp_idx, day_idx] >= 0:
+            valid = slots_cache[emp_idx][day_idx]
+            if len(valid) > 0:
+                mutated[emp_idx, day_idx] = np.random.choice(valid)
+                
+    return mutated

src/engine/selection.py

@@ -0,0 +1,272 @@
+import numpy as np
+from numba import njit, prange
+from src.config import cfg
+
+# Costanti di dominio (mapping per la vettorializzazione)
+CODE_OFF = -1
+CODE_ABSENCE = -2
+CONS_TYPE_HARD = 1
+CONS_TYPE_SOFT = 2
+CONS_TYPE_ABSENCE = 3
+
+@njit(cache=True)
+def get_valid_start_slots_numba(day_idx, shift_len, cons_type, cons_val, closing_slot, is_closed):
+    """
+    Calcolo degli slot di inizio turno validi. 
+    JIT-compiled per massimizzare il throughput. Ritorna strictly un ndarray.
+    """
+    # 1. Vincoli Hard (Assenze e Turni Fissi)
+    if cons_type == CONS_TYPE_ABSENCE:
+        return np.array([CODE_ABSENCE], dtype=np.int64)
+        
+    if cons_type == CONS_TYPE_HARD:
+        target_slot = cons_val
+        # Boundary check per evitare sforamenti oltre l'orario di chiusura
+        if is_closed or (target_slot + shift_len > closing_slot):
+            return np.array([CODE_OFF], dtype=np.int64)
+        return np.array([target_slot], dtype=np.int64)
+
+    # 2. Assegnazione Standard
+    if is_closed:
+        return np.empty(0, dtype=np.int64) 
+
+    max_start = closing_slot - shift_len
+    if max_start < 0:
+        return np.empty(0, dtype=np.int64)
+        
+    # Generazione array di slot contigui validi
+    return np.arange(0, max_start + 1, dtype=np.int64)
+
+@njit(cache=True)
+def calculate_fitness_numba(individual, masks, lengths, target_days_arr, cons_types, cons_vals, target_demand, weights, daily_slots):
+    """
+    Motore core di valutazione della fitness. 
+    Aggrega i vincoli operativi (contratti, weekend, preferenze) e vettorializza le penalità.
+    """
+    num_emps = len(lengths)
+    num_days = 7
+    num_slots = daily_slots
+    
+    current_coverage = np.zeros((num_days, num_slots), dtype=np.int64)
+    
+    homogeneity_penalty = 0.0
+    soft_pref_penalty = 0.0
+    contract_penalty = 0.0
+    equity_penalty = 0.0
+    
+    W_UNDER = weights[0]
+    W_OVER  = weights[1]
+    W_HOMO  = weights[2]
+    W_SOFT  = weights[3]
+    
+    PENALTY_PER_DAY_MISMATCH = W_UNDER * 2.0 
+
+    sum_wk_work = 0.0
+    sum_sq_wk_work = 0.0
+
+    # Scansione matrice turni per estrazione metriche operative
+    for i in range(num_emps):
+        mask_len = lengths[i]
+        real_mask = masks[i, :mask_len]
+        
+        days_worked_count = 0 
+        weekend_days = 0
+        
+        sum_slots = 0.0
+        sum_sq_slots = 0.0
+        count_slots = 0
+
+        for day in range(num_days):
+            start = individual[i, day]
+            
+            if start >= 0:
+                days_worked_count += 1
+                sum_slots += start
+                sum_sq_slots += start**2
+                count_slots += 1
+                if day >= 5: weekend_days += 1
+                
+                end = min(start + mask_len, num_slots)
+                real_len = end - start
+                
+                # Proiezione del fenotipo (maschera VDT) sulla coverage matrix
+                if real_len > 0:
+                    current_coverage[day, start:end] += real_mask[:real_len]
+            
+            # Valutazione desiderata (Soft Constraint)
+            if cons_types[i, day] == CONS_TYPE_SOFT and start >= 0:
+                target_slot = cons_vals[i, day]
+                if start != target_slot:
+                    soft_pref_penalty += abs(start - target_slot)
+
+        # Check target contrattuale (mix lavorativi vs riposi)
+        tgt = target_days_arr[i]
+        if days_worked_count != tgt:
+            contract_penalty += (abs(days_worked_count - tgt) * PENALTY_PER_DAY_MISMATCH)
+
+        # Calcolo varianza per penalizzare pattern orari troppo frammentati
+        if count_slots > 1:
+            mean = sum_slots / count_slots
+            var = (sum_sq_slots / count_slots) - (mean**2)
+            if var > 0: homogeneity_penalty += np.sqrt(var)
+
+        sum_wk_work += weekend_days
+        sum_sq_wk_work += weekend_days**2
+
+    # Equità aziendale: bilanciamento dei carichi sui weekend tra dipendenti
+    if num_emps > 1:
+        mean_wk = sum_wk_work / num_emps
+        var_wk = (sum_sq_wk_work / num_emps) - (mean_wk**2)
+        if var_wk > 0:
+            equity_penalty = np.sqrt(var_wk) * W_HOMO * 10.0
+
+    # Calcolo delta rispetto al fabbisogno (Demand vs Coverage)
+    diff = current_coverage - target_demand
+    
+    under_score = 0.0
+    flattened_diff = diff.flatten()
+    for val in flattened_diff:
+        if val < 0: under_score += abs(val)
+    under_score *= W_UNDER
+    
+    over_score = 0.0
+    safe_target = target_demand.flatten()
+    for k in range(len(flattened_diff)):
+        val = flattened_diff[k]
+        if val > 0:
+            tgt_val = safe_target[k]
+            if tgt_val == 0: tgt_val = 1
+            over_score += (val / tgt_val)
+    over_score *= (W_OVER * 10.0)
+
+    # Aggregazione Loss Function
+    total_score = (under_score + 
+                   over_score + 
+                   (homogeneity_penalty * W_HOMO) +
+                   (soft_pref_penalty * W_SOFT) +
+                   contract_penalty + 
+                   equity_penalty)
+    
+    return total_score, current_coverage
+
+@njit(parallel=True, cache=True) 
+def calculate_population_fitness_parallel(population, masks, lengths, target_days_arr, cons_types, cons_vals, target_demand, weights, daily_slots):
+    """
+    Valutazione massiva della popolazione. Sfrutta il multithreading (prange) di Numba.
+    """
+    pop_size = len(population)
+    scores = np.zeros(pop_size, dtype=np.float64)
+    for i in prange(pop_size):
+        sc, _ = calculate_fitness_numba(
+            population[i], 
+            masks, lengths, target_days_arr, cons_types, cons_vals, 
+            target_demand, weights, daily_slots
+        )
+        scores[i] = sc
+    return scores
+
+def tournament_selection(population, fitness_scores):
+    """Selezione a torneo standard."""
+    k = cfg.genetic_params.get('tournament_size', 5)
+    indices = np.random.choice(len(population), k, replace=False)
+    best_idx = indices[np.argmin(fitness_scores[indices])]
+    return population[best_idx]
+
+@njit(cache=True)
+def calculate_detailed_score(individual, masks, lengths, target_days_arr, cons_types, cons_vals, target_demand, weights, daily_slots):
+    """
+    Versione verbosa del calcolo fitness usata post-convergenza 
+    per l'estrazione delle metriche finali di business da mostrare in UI.
+    """
+    num_emps = len(lengths)
+    num_days = 7
+    num_slots = daily_slots
+    
+    current_coverage = np.zeros((num_days, num_slots), dtype=np.int64)
+    
+    homogeneity_penalty = 0.0
+    soft_pref_penalty = 0.0
+    contract_penalty = 0.0
+    equity_penalty = 0.0
+    
+    W_UNDER = weights[0]
+    W_OVER  = weights[1]
+    W_HOMO  = weights[2]
+    W_SOFT  = weights[3]
+    
+    PENALTY_PER_DAY_MISMATCH = W_UNDER * 2.0 
+
+    sum_wk_work = 0.0
+    sum_sq_wk_work = 0.0
+
+    for i in range(num_emps):
+        mask_len = lengths[i]
+        real_mask = masks[i, :mask_len]
+        days_worked_count = 0 
+        weekend_days = 0
+        sum_slots = 0.0
+        sum_sq_slots = 0.0
+        count_slots = 0
+
+        for day in range(num_days):
+            start = individual[i, day]
+            if start >= 0:
+                days_worked_count += 1
+                sum_slots += start
+                sum_sq_slots += start**2
+                count_slots += 1
+                if day >= 5: weekend_days += 1
+                
+                end = min(start + mask_len, num_slots)
+                real_len = end - start
+                if real_len > 0:
+                    current_coverage[day, start:end] += real_mask[:real_len]
+            
+            if cons_types[i, day] == CONS_TYPE_SOFT and start >= 0:
+                target_slot = cons_vals[i, day]
+                if start != target_slot:
+                    soft_pref_penalty += abs(start - target_slot)
+
+        tgt = target_days_arr[i]
+        if days_worked_count != tgt:
+            contract_penalty += (abs(days_worked_count - tgt) * PENALTY_PER_DAY_MISMATCH)
+
+        if count_slots > 1:
+            mean = sum_slots / count_slots
+            var = (sum_sq_slots / count_slots) - (mean**2)
+            if var > 0: homogeneity_penalty += np.sqrt(var)
+
+        sum_wk_work += weekend_days
+        sum_sq_wk_work += weekend_days**2
+
+    if num_emps > 1:
+        mean_wk = sum_wk_work / num_emps
+        var_wk = (sum_sq_wk_work / num_emps) - (mean_wk**2)
+        if var_wk > 0:
+            equity_penalty = np.sqrt(var_wk) * W_HOMO * 10.0
+
+    diff = current_coverage - target_demand
+    
+    under_score = 0.0
+    flattened_diff = diff.flatten()
+    for val in flattened_diff:
+        if val < 0: under_score += abs(val)
+    under_score *= W_UNDER
+    
+    over_score = 0.0
+    safe_target = target_demand.flatten()
+    for k in range(len(flattened_diff)):
+        val = flattened_diff[k]
+        if val > 0:
+            tgt_val = safe_target[k]
+            if tgt_val == 0: tgt_val = 1
+            over_score += (val / tgt_val)
+    over_score *= (W_OVER * 10.0)
+
+    cost_homo = homogeneity_penalty * W_HOMO
+    cost_soft = soft_pref_penalty * W_SOFT
+    
+    total = under_score + over_score + cost_homo + cost_soft + contract_penalty + equity_penalty
+    
+    # Ritorna l'array esploso delle loss per i grafici
+    return np.array([total, under_score, over_score, cost_homo, cost_soft, contract_penalty, equity_penalty])

src/models/individual.py

@@ -0,0 +1,76 @@
+import numpy as np
+from src.config import cfg
+
+class ShiftPatterns:
+    """
+    Modellazione del fenotipo dei turni. 
+    Mappa le regole contrattuali e i vincoli normativi (es. pause VDT) in tensori 1D 
+    che verranno successivamente proiettati sulla matrice di coverage.
+    """
+    def __init__(self):
+        # Parametri normativi (es. Pausa ogni 2 ore per i video-terminalisti)
+        self.vdt_interval_min = cfg.system_settings.get('vdt_interval_minutes', 120)
+        self.vdt_break_min = cfg.system_settings.get('vdt_break_minutes', 15)
+        
+        # Quantizzazione: trasformazione dai minuti agli slot di sistema
+        self.max_work_slots = int(self.vdt_interval_min / cfg.system_slot_minutes)
+        self.vdt_slots = max(1, int(self.vdt_break_min / cfg.system_slot_minutes))
+
+    def _create_block_inside_vdt(self, duration_minutes, flip_strategy=False):
+        """
+        Genera un macro-blocco lavorativo iniettando le micro-pause VDT obbligatorie.
+        """
+        total_slots = int(round(duration_minutes / cfg.system_slot_minutes))
+        mask = np.ones(total_slots, dtype=int)
+        
+        # Early exit: se il turno è più corto dell'intervallo VDT, niente pause
+        if total_slots <= self.max_work_slots:
+            return mask
+            
+        # Sliding window per "scavare" gli slot di pausa all'interno della maschera booleana
+        cursor = 0
+        while cursor < total_slots:
+            break_start_idx = cursor + self.max_work_slots
+            if break_start_idx >= total_slots:
+                break
+            break_end_idx = min(break_start_idx + self.vdt_slots, total_slots)
+            mask[break_start_idx : break_end_idx] = 0
+            cursor = break_end_idx
+
+        # Il flip garantisce varianza fenotipica a parità di orario (es. pausa all'inizio vs alla fine)
+        return np.flip(mask) if flip_strategy else mask
+
+    def get_mask_dynamic(self, work_hours, lunch_minutes, variant_seed=0):
+        """
+        Costruisce la firma oraria completa (fenotipo) del dipendente.
+        Gestisce dinamicamente split-shift e variazioni deterministiche tramite seed.
+        """
+        total_contract_min = work_hours * 60
+        lunch_slots = int(round(lunch_minutes / cfg.system_slot_minutes))
+        
+        # Decodifica bit a bit del seed per alterare la struttura delle pause
+        # mantenendo un output deterministico per lo stesso ID dipendente
+        flip_p1 = (variant_seed % 2) != 0
+        flip_p2 = ((variant_seed >> 1) % 2) != 0
+        
+        # Vincolo normativo: i turni lunghi richiedono uno spezzato (es. mattina / pomeriggio)
+        if work_hours > 6:
+            first_part_min = 4 * 60  # Blocco standard pre-pranzo
+            second_part_min = total_contract_min - first_part_min
+            has_lunch = (lunch_slots > 0)
+        else:
+            first_part_min = total_contract_min
+            second_part_min = 0
+            has_lunch = False
+
+        mask_part1 = self._create_block_inside_vdt(first_part_min, flip_strategy=flip_p1)
+        mask_part2 = self._create_block_inside_vdt(second_part_min, flip_strategy=flip_p2) if second_part_min > 0 else np.array([], dtype=int)
+
+        # Assemblaggio vettoriale del turno completo
+        components = [mask_part1]
+        if has_lunch:
+            components.append(np.zeros(lunch_slots, dtype=int))
+        if len(mask_part2) > 0:
+            components.append(mask_part2)
+            
+        return np.concatenate(components)

src/problems/my_problem.py

@@ -0,0 +1,93 @@
+import numpy as np
+from src.config import cfg
+
+# Mapping dei constraint per la vettorializzazione (flag numerici per il motore JIT)
+CONS_TYPE_NONE = 0
+CONS_TYPE_HARD = 1
+CONS_TYPE_SOFT = 2
+CONS_TYPE_ABSENCE = 3
+
+def process_demand(raw_data):
+    """
+    Upsampling della demand operativa.
+    Espande la granularità di business (es. slot da 30/60 min) 
+    sul clock interno di sistema (es. 15 min) per il calcolo matriciale.
+    """
+    weekly_demand = np.zeros((7, cfg.daily_slots), dtype=int)
+    ratio = int(cfg.expansion_factor)
+    
+    for day_idx, day_data in enumerate(raw_data):
+        # Cast robusto dei valori input (fallback a 0 per dati sporchi/missing)
+        input_vals = [int(x) if str(x).isdigit() else 0 for x in day_data[1:]]
+        
+        curr_sys_slot = 0
+        for val in input_vals:
+            end_sys_slot = curr_sys_slot + ratio
+            # Boundary check per evitare out-of-bounds se l'orario di chiusura varia
+            if end_sys_slot <= cfg.daily_slots:
+                weekly_demand[day_idx, curr_sys_slot:end_sys_slot] = val
+            curr_sys_slot += ratio
+            
+    return weekly_demand
+
+def convert_employees_to_numpy(employees):
+    """
+    Tensorizzazione dell'anagrafica.
+    Estrae le liste di dizionari e crea array contigui in memoria (ndarrays)
+    per bypassare l'overhead degli oggetti Python dentro i loop di Numba.
+    """
+    num_emps = len(employees)
+    
+    # Fallback di sicurezza se l'anagrafica è vuota
+    if num_emps == 0: 
+        return None, None, None, None, None
+
+    # Ricerca dinamica della shift mask più lunga per dimensionare il tensore 2D
+    max_len = max(len(e['mask']) for e in employees)
+    
+    # Inizializzazione tensori pre-allocati
+    masks_matrix = np.zeros((num_emps, max_len), dtype=int)
+    lengths_array = np.zeros(num_emps, dtype=int)
+    target_days_array = np.zeros(num_emps, dtype=int)
+    
+    cons_type_matrix = np.zeros((num_emps, 7), dtype=int)
+    cons_val_matrix = np.full((num_emps, 7), -1, dtype=int)
+    
+    def _to_slot(t_str):
+        """Quantizzazione del timestamp testuale in indice slot di sistema."""
+        try:
+            h, m = map(int, t_str.split(':'))
+            minutes = (h - cfg.client_settings['day_start_hour']) * 60 + m
+            return int(minutes / cfg.system_slot_minutes)
+        except: 
+            return -1 # Fallback error code
+
+    # Compilazione massiva delle matrici
+    for i, emp in enumerate(employees):
+        curr_len = len(emp['mask'])
+        
+        # Inserimento maschera con zero-padding implicito a destra
+        masks_matrix[i, :curr_len] = emp['mask']
+        lengths_array[i] = curr_len
+        
+        # Recupero target contrattuale
+        target_days_array[i] = emp.get('target_days', 5)
+        
+        # Mapping spaziale dei constraint (Hard/Soft/Assenze)
+        constraints = emp.get('constraints', {})
+        for day_str, rule in constraints.items():
+            d = int(day_str)
+            if d < 0 or d > 6: 
+                continue
+            
+            rtype = rule.get('type')
+            if rtype == 'hard':
+                cons_type_matrix[i, d] = CONS_TYPE_HARD
+                cons_val_matrix[i, d] = _to_slot(rule.get('start_time', '00:00'))
+            elif rtype == 'soft':
+                cons_type_matrix[i, d] = CONS_TYPE_SOFT
+                cons_val_matrix[i, d] = _to_slot(rule.get('start_time', '00:00'))
+            elif rtype == 'absence':
+                cons_type_matrix[i, d] = CONS_TYPE_ABSENCE
+
+    return masks_matrix, lengths_array, target_days_array, cons_type_matrix, cons_val_matrix

src/utils/demand_processing.py

@@ -0,0 +1,60 @@
+import numpy as np
+
+def align_demand_to_grid(raw_demand_row, current_config):
+    """
+    Allinea la time-series della demand giornaliera alla griglia oraria di configurazione.
+    Gestisce dinamicamente truncation e padding in base a shift operativi di start/end.
+    """
+    # Estrazione parametri di quantizzazione temporale
+    start_h = current_config['client_settings']['day_start_hour']
+    end_h = current_config['client_settings']['day_end_hour']
+    slot_min = current_config['client_settings']['planning_slot_minutes']
+    
+    slots_per_day = int((end_h - start_h) * 60 / slot_min)
+    
+    # Fallback strutturale per payload mancanti o corrotti
+    if not raw_demand_row:
+        return np.ones(slots_per_day, dtype=int)
+
+    # Early exit se la dimensionalità è già coerente con il setup
+    if len(raw_demand_row) == slots_per_day:
+        return np.array(raw_demand_row, dtype=int)
+        
+    # --- RESHAPING PIPELINE ---
+    # Inizializzazione target array con baseline di staff (safety net = 1)
+    adjusted_demand = np.ones(slots_per_day, dtype=int)
+    
+    # Euristica "Best Effort" per il mapping dei dati storici sulla nuova griglia.
+    # Assunto: invarianza del delta temporale (slot_min). 
+    # TODO: In caso di mutazione della granularità (es. 15m -> 30m) serve un resampler/interpolatore.
+    limit = min(len(raw_demand_row), slots_per_day)
+    adjusted_demand[:limit] = raw_demand_row[:limit]
+    
+    return adjusted_demand
+
+def sanitize_weekly_demand(weekly_demand, current_config):
+    """
+    Pipeline di sanitizzazione massiva per l'intera matrice settimanale.
+    Esegue stripping delle label testuali ed enforcing della consistenza dimensionale (7xN).
+    """
+    sanitized = []
+    
+    # Enforcing del vincolo a 7 giorni operativi
+    for i in range(7):
+        if i < len(weekly_demand):
+            row_data = weekly_demand[i]
+            
+            # Stripping della label descrittiva se presente (es. "Giorno_0")
+            if isinstance(row_data[0], str):
+                row_vals = row_data[1:]
+            else:
+                row_vals = row_data
+                
+            aligned = align_demand_to_grid(row_vals, current_config)
+            sanitized.append(aligned)
+        else:
+            # Imputazione di una curva flat di fallback per le giornate out-of-bounds
+            dummy = align_demand_to_grid([], current_config)
+            sanitized.append(dummy)
+            
+    return sanitized

src/utils/generator.py

@@ -0,0 +1,153 @@
+import numpy as np
+import random
+from src.utils.hf_storage import list_activities, upload_new_scenario
+
+def generate_demand_curve(slots_per_day, planning_slot, peak_staff, shape_type):
+    """
+    Generatore di workload sintetico basato su distribuzioni Gaussiane.
+    Modella profili di carico tipici dei settori BPO e Operations su base slot.
+    """
+    daily_req = []
+    
+    for s in range(slots_per_day):
+        hour = 8 + (s * planning_slot / 60) # Offset dalle 08:00
+        
+        if shape_type == "double_bell":
+            # Distribuzione Bimodale (M-Shape): Tipica dell'Inbound Voice BPO (Picchi 11:00 e 16:00)
+            val = np.exp(-((hour - 11)**2) / 4) + np.exp(-((hour - 16)**2) / 4)
+            val = val * 0.8 # Normalizzazione euristica
+            
+        elif shape_type == "single_bell_center":
+            # Unimodale centrata: Tipica del settore Delivery/Food o Customer Care pausa pranzo
+            val = np.exp(-((hour - 13)**2) / 9) 
+            
+        elif shape_type == "morning_peak":
+            # Skewed left: Supporto Tecnico B2B o Helpdesk IT (Picco decrescente dalle 09:30)
+            val = np.exp(-((hour - 9.5)**2) / 5)
+            
+        elif shape_type == "steady_high":
+            # Workload Flat: Backoffice, Data Entry o Processi Asincroni
+            # Iniezione di white noise per evitare un rettangolo artificiale
+            noise = np.random.normal(0, 0.05)
+            val = 0.8 + noise
+            
+        else: # Fallback
+            val = 0.5
+
+        # Scaling del volume basato sulla capacity massima
+        staff_needed = int(val * peak_staff)
+        
+        # Lower-bound di sicurezza: previene divisioni per zero o matrici vuote nei layer a valle
+        daily_req.append(max(5, staff_needed))
+        
+    return daily_req
+
+def generate_scenario_files(scenario_name, num_employees, mix_ratios, curve_shape="double_bell"):
+    """
+    Orchestratore per il bootstrap di scenari di test.
+    Istanzia anagrafiche, time-series della demand e hyper-parametri standard, 
+    pushandoli direttamente sul Data Lake (HF Dataset).
+    """
+    
+    # 1. State check sul repository remoto
+    existing_activities = list_activities()
+    if scenario_name in existing_activities:
+        return False, f"Esiste già uno scenario con nome '{scenario_name}'."
+    
+    PLANNING_SLOT = 30
+
+    # 2. Iniezione Configurazione Base (Default Engine Params)
+    activity_conf = {
+        "client_settings": {
+            "planning_slot_minutes": PLANNING_SLOT,
+            "day_start_hour": 8,
+            "day_end_hour": 22 
+        },
+        "operating_hours": {
+            "default": "08:00-22:00",
+            "exceptions": {}
+        },
+        "weights": {
+            "understaffing": 1000.0,
+            "overstaffing": 10.0,
+            "homogeneity": 400.0,
+            "soft_preference": 50.0
+        },
+        "genetic_params": {
+            "population_size": 1000,
+            "generations": 350,
+            "mutation_rate": 0.45,
+            "crossover_rate": 0.85,
+            "elitism_rate": 0.02,
+            "tournament_size": 2,
+            "heuristic_rate": 0.4,
+            "heuristic_noise": 0.5
+        }
+    }
+
+    # 3. Campionamento Anagrafica (Contract Mix)
+    employees = []
+    contracts_def = {
+        "FT40": {"wh": 8, "bd": 30},
+        "PT30": {"wh": 6, "bd": 0},
+        "PT20": {"wh": 4, "bd": 0}
+    }
+    
+    contract_pool = []
+    for c_type, pct in mix_ratios.items():
+        count = int(num_employees * (pct / 100.0))
+        contract_pool.extend([c_type] * count)
+        
+    # Padding contrattuale per gestire eventuali sfridi degli arrotondamenti percentuali
+    while len(contract_pool) < num_employees:
+        contract_pool.append("FT40")
+    
+    random.shuffle(contract_pool)
+
+    for i, c_type in enumerate(contract_pool):
+        specs = contracts_def[c_type]
+        # Assegnazione probabilistica dei pattern di flessibilità settimanale (Work vs Off)
+        if c_type == "FT40":
+            mix = {"WORK": 5, "OFF": 2}
+        else:
+            mix = {"WORK": 6, "OFF": 1} if random.random() < 0.3 else {"WORK": 5, "OFF": 2}
+
+        emp = {
+            "id": f"User_{i:03d}_{c_type}",
+            "contract": c_type,
+            "work_hours": float(specs["wh"]),
+            "break_duration": specs["bd"],
+            "shift_mix": mix,
+            "constraints": {}
+        }
+        
+        # Iniezione randomica di soft-constraints (es. preferenza oraria)
+        if random.random() < 0.2: 
+            emp["constraints"]["0"] = {"type": "soft", "start_time": "09:00"}
+            
+        employees.append(emp)
+
+    # 4. Generazione Time-Series della Demand
+    slots_per_day = int((22 - 8) * 60 / PLANNING_SLOT)
+    weekly_demand = []
+    
+    # Baseline calcolata sul 70% della forza lavoro (forza un understaffing strutturale per sfidare il motore)
+    peak_staff = int(num_employees * 0.7) 
+    
+    base_daily_curve = generate_demand_curve(slots_per_day, PLANNING_SLOT, peak_staff, curve_shape)
+    
+    for day in range(7):
+        # Data Augmentation: applicazione di rumore (+/- 10%) per sfasare i pattern giornalieri
+        daily_req_noisy = []
+        for val in base_daily_curve:
+            noise_factor = random.uniform(0.9, 1.1)
+            daily_req_noisy.append(int(val * noise_factor))
+            
+        weekly_demand.append([f"Giorno_{day}"] + daily_req_noisy)
+
+    # 5. Pipeline I/O verso HF Hub
+    try:
+        upload_new_scenario(scenario_name, activity_conf, employees, weekly_demand)
+        return True, f"Scenario '{scenario_name}' inizializzato con successo (Shape: {curve_shape})."
+    except Exception as e:
+        return False, str(e)

src/utils/health.py

@@ -0,0 +1,104 @@
+from numba import njit
+
+# --- 1. METRICHE PRE-FLIGHT: Indice di Bilanciamento Evolutivo (IBE) ---
+def calculate_ibe(pop_size, generations, p_cross, p_mut, p_heur, p_elite):
+    """
+    Calcola l'Indice di Bilanciamento Evolutivo (IBE), una metrica euristica 
+    per stimare il trade-off tra esplorazione (crossover/mutazione) e 
+    sfruttamento o pressione selettiva (euristiche/elitismo).
+    
+    Target empirico di stabilità: 1000 - 3000.
+    """
+    # Energia cinetica (Generazione di nuova varianza)
+    numerator = (p_cross * pop_size) + (p_mut * pop_size * generations)
+    
+    # Fattori frenanti (Scaling 0-100 per bilanciare l'ordine di grandezza del numeratore)
+    h_val_score = max(p_heur * 100.0, 1.0)      
+    e_val_score = max(p_elite * 100.0, 0.1)
+    denominator = h_val_score * e_val_score
+    
+    return numerator / denominator
+
+def interpret_ibe(ibe_value):
+    """Valuta il setup dei parametri rispetto al regime di stabilità ottimale."""
+    if 1000 <= ibe_value <= 3000: 
+        return "OTTIMALE (Bilanciato)", "normal"
+    elif ibe_value < 1000:
+        return "RISCHIO STALLO (Eccessiva pressione selettiva)", "off"
+    else:
+        return "RISCHIO CAOS (Esplorazione incontrollata)", "inverse"
+
+
+# --- 2. METRICHE POST-FLIGHT: Distanza di Hamming & Convergenza ---
+@njit(cache=True)
+def calculate_diversity_snapshot(population):
+    """
+    Calcola la diversità genetica della popolazione tramite Distanza di Hamming.
+    Implementazione JIT con campionamento stocastico per evitare l'overhead O(N^2).
+    """
+    pop_size, num_emps, num_days = population.shape
+    if pop_size < 2: return 0.0
+    
+    # Clamp del sample size per limitare il costo computazionale
+    sample_size = min(50, pop_size)
+    total_diffs = 0
+    total_comparisons = 0
+    
+    genome_len = num_emps * num_days
+    
+    # Valutazione differenziale cross-individuo
+    for i in range(sample_size):
+        for j in range(i + 1, pop_size):
+            diff_count = 0
+            for e in range(num_emps):
+                for d in range(num_days):
+                    if population[i, e, d] != population[j, e, d]:
+                        diff_count += 1
+            
+            total_diffs += diff_count
+            total_comparisons += 1
+            
+    if total_comparisons == 0: return 0.0
+    
+    avg_diff = total_diffs / total_comparisons
+    
+    # Normalizzazione % rispetto allo spazio di ricerca del singolo fenotipo
+    diversity_percentage = (avg_diff / genome_len) * 100.0
+    return diversity_percentage
+
+def analyze_convergence_quality(history):
+    """
+    Analizza la time-series della diversità per classificare il regime di convergenza
+    (Matura, Prematura o Divergente).
+    """
+    if not history:
+        return "Dati insufficienti", "off"
+        
+    final_diversity = history[-1]
+    
+    # 1. Divergenza di sistema (Assenza di convergenza locale o globale)
+    if final_diversity > 40.0:
+        return "⚠️ CRITICO: Caos (Assenza di convergenza)", "inverse"
+        
+    # 2. Regime esplorativo ancora attivo
+    if final_diversity >= 5.0:
+        return f"✅ SANO: Diversità Attiva ({final_diversity:.2f}%)", "normal"
+        
+    # 3. Analisi del drop-rate per rilevare 'Premature Convergence' (Collasso genotipico)
+    threshold_idx = -1
+    for i, val in enumerate(history):
+        if val < 5.0:
+            threshold_idx = i
+            break
+            
+    total_steps = len(history)
+    
+    # Se la diversità fisiologica si è mantenuta intatta fino all'ultimo delta
+    if threshold_idx == -1: 
+        return "✅ SANO: Convergenza in corso", "normal"
+        
+    # Classificazione basata sull'epoca del collasso (< 20% delle generazioni totali = prematuro)
+    if threshold_idx < (total_steps * 0.20):
+        return "⚠️ CRITICO: Convergenza Prematura (Collasso genotipico)", "inverse"
+    else:
+        return "🏆 ECCELLENTE: Convergenza Matura (Consenso Raggiunto)", "success"

src/utils/helpers.py

@@ -0,0 +1,92 @@
+import zlib
+import numpy as np
+from src.models.individual import ShiftPatterns
+from src.config import cfg
+from src.utils.hf_storage import load_json
+
+
+def load_employees_from_json(activity_folder):
+    """
+    Hydration del modello di dominio anagrafico.
+    Recupera i dati dal Dataset remoto e istanzia i fenotipi dei turni (maschere VDT).
+    """
+    data = load_json(activity_folder, "employees.json")
+    
+    if not data:
+        return []
+
+    employees = []
+    patterns = ShiftPatterns()
+    
+    for record in data:
+        w_hours = float(record.get('work_hours', 8.0))
+        l_min = int(record.get('break_duration', 0))
+        
+        # Hashing deterministico dell'ID per garantire che la stessa singola risorsa 
+        # mantenga sempre la stessa firma fenotipica (riproducibilità degli spezzati)
+        seed = zlib.adler32(record['id'].encode('utf-8'))
+        
+        mask = patterns.get_mask_dynamic(w_hours, l_min, variant_seed=seed)
+        
+        # Parsing flessibile del target contrattuale (backward compatibility)
+        mix = record.get('shift_mix', record.get('weekly_mix', {"WORK": 5, "OFF": 2}))
+        target_days = int(mix["WORK"]) if "WORK" in mix else 7 - int(mix.get("OFF", 2))
+            
+        employees.append({
+            "id": record['id'],
+            "contract": record['contract'],
+            "mask": mask,
+            "shift_len": len(mask),
+            "target_days": target_days,
+            "constraints": record.get("constraints", {})
+        })
+    return employees
+
+def check_hours_balance(employees, target_matrix):
+    """
+    Validazione strutturale pre-ottimizzazione.
+    Calcola la capacità produttiva netta (escludendo shrinkage come pause VDT/Pranzo)
+    e la confronta con il total workload richiesto dalla Demand.
+    """
+    slot_hours = cfg.system_slot_minutes / 60.0
+    total_demand_slots = target_matrix.sum()
+    total_demand_hours = total_demand_slots * slot_hours
+    
+    total_capacity_slots = 0
+    
+    for emp in employees:
+        # Calcolo della capacità netta computando solo i flag attivi (1) nella maschera booleana
+        work_slots = np.sum(emp['mask']) 
+        days_per_week = emp.get('target_days', 5)
+        total_capacity_slots += (work_slots * days_per_week)
+        
+    total_capacity_hours = total_capacity_slots * slot_hours
+    
+    print("\n[*] Analisi Strutturale: Bilancio Capacity vs Demand")
+    print(f" ├─ Target Workload: {total_demand_hours:,.1f} h")
+    print(f" ├─ Net Capacity:    {total_capacity_hours:,.1f} h")
+    
+    diff = total_capacity_hours - total_demand_hours
+    
+    if diff >= 0:
+        surplus_perc = (diff / total_demand_hours) * 100
+        print(f" └─ STATO: [OK] Surplus Teorico (+{diff:.1f}h / +{surplus_perc:.1f}%)")
+    else:
+        deficit_perc = (abs(diff) / total_demand_hours) * 100
+        print(f" └─ STATO: [WARN] Deficit Strutturale (-{abs(diff):.1f}h / -{deficit_perc:.1f}%)")
+        
+    return diff
+
+def minutes_to_time(slot_minutes_count):
+    """
+    Utility per la conversione dello slot offset in timestamp leggibile (HH:MM).
+    """
+    start_h = cfg.client_settings.get('day_start_hour', 8)
+    total_minutes = (start_h * 60) + slot_minutes_count
+    
+    # Safe check per il wrap-around della mezzanotte (modulo 24h) per turni notturni
+    total_minutes = total_minutes % (24 * 60)
+    
+    h = int(total_minutes // 60)
+    m = int(total_minutes % 60)
+    return f"{h:02d}:{m:02d}"

src/utils/hf_storage.py

@@ -0,0 +1,138 @@
+import os
+import json
+from huggingface_hub import HfApi, hf_hub_download
+from huggingface_hub.utils import EntryNotFoundError
+
+DATASET_REPO_ID = "NextGenTech/geneticWFM-activities"
+
+# --- ENVIRONMENT DETECTION ---
+# Switch dinamico Dev/Prod basato sull'injection di SPACE_ID da parte del container HF
+IS_LOCAL = os.environ.get("SPACE_ID") is None
+
+# Risoluzione dinamica della project root per gestire l'I/O in local fallback
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+LOCAL_BASE_PATH = os.path.join(PROJECT_ROOT, "data", "activities")
+
+def get_hf_api():
+    """Istanzia il client HF sfruttando i secrets di environment."""
+    return HfApi(token=os.environ.get("HF_TOKEN"))
+
+def list_activities():
+    """
+    Discovery dinamica dei workspace operativi.
+    Implementa routing Dev (OS Locale) / Prod (HF Datasets API).
+    """
+    if IS_LOCAL:
+        if not os.path.exists(LOCAL_BASE_PATH):
+            return []
+        return sorted([d for d in os.listdir(LOCAL_BASE_PATH) if os.path.isdir(os.path.join(LOCAL_BASE_PATH, d))])
+    
+    # --- PROD LOGIC ---
+    api = get_hf_api()
+    try:
+        files = api.list_repo_files(repo_id=DATASET_REPO_ID, repo_type="dataset")
+        activities = set()
+        for f in files:
+            parts = f.split("/")
+            if len(parts) > 2 and parts[0] == "activities":
+                activities.add(parts[1])
+        return sorted(list(activities))
+    except Exception as e:
+        print(f"[ERROR] Discovery attività fallita sul layer HF: {e}")
+        return []
+
+def load_json(activity_name, filename):
+    """
+    I/O Read: Deserializzazione del payload JSON.
+    """
+    if IS_LOCAL:
+        path = os.path.join(LOCAL_BASE_PATH, activity_name, filename)
+        if os.path.exists(path):
+            with open(path, 'r') as f:
+                return json.load(f)
+        return None
+
+    # --- PROD LOGIC ---
+    repo_path = f"activities/{activity_name}/{filename}"
+    try:
+        downloaded_path = hf_hub_download(
+            repo_id=DATASET_REPO_ID,
+            repo_type="dataset",
+            filename=repo_path,
+            token=os.environ.get("HF_TOKEN")
+        )
+        with open(downloaded_path, 'r') as f:
+            return json.load(f)
+    except EntryNotFoundError:
+        # Silenziamo l'errore se il file semplicemente non esiste ancora
+        return None
+    except Exception as e:
+        print(f"[ERROR] API Download fallito per {repo_path}: {e}")
+        return None
+
+def save_json(activity_name, filename, data):
+    """
+    I/O Write: Serializzazione su disco e successiva replica su object storage.
+    """
+    if IS_LOCAL:
+        path = os.path.join(LOCAL_BASE_PATH, activity_name, filename)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, 'w') as f:
+            json.dump(data, f, indent=2)
+        return
+
+    # --- PROD LOGIC ---
+    repo_path = f"activities/{activity_name}/{filename}"
+    local_tmp_path = f"/tmp/{activity_name}_{filename}"
+    
+    # Scrittura su layer effimero del container (/tmp)
+    os.makedirs(os.path.dirname(local_tmp_path), exist_ok=True)
+    with open(local_tmp_path, 'w') as f:
+        json.dump(data, f, indent=2)
+        
+    api = get_hf_api()
+    api.upload_file(
+        path_or_fileobj=local_tmp_path,
+        path_in_repo=repo_path,
+        repo_id=DATASET_REPO_ID,
+        repo_type="dataset",
+        commit_message=f"Sync {filename} -> {activity_name}"
+    )
+
+def upload_new_scenario(activity_name, activity_conf, employees, weekly_demand):
+    """
+    Commit massivo (atomic push) di un nuovo scenario generato.
+    Evita commit parziali raggruppando Config, Anagrafica e Demand.
+    """
+    if IS_LOCAL:
+        base_path = os.path.join(LOCAL_BASE_PATH, activity_name)
+        os.makedirs(base_path, exist_ok=True)
+        with open(os.path.join(base_path, "activity_config.json"), 'w') as f:
+            json.dump(activity_conf, f, indent=2)
+        with open(os.path.join(base_path, "employees.json"), 'w') as f:
+            json.dump(employees, f, indent=2)
+        with open(os.path.join(base_path, "demand.json"), 'w') as f:
+            json.dump(weekly_demand, f, indent=2)
+        return
+
+    # --- PROD LOGIC ---
+    api = get_hf_api()
+    local_dir = f"/tmp/activities/{activity_name}"
+    os.makedirs(local_dir, exist_ok=True)
+    
+    # Scrittura layer effimero
+    with open(os.path.join(local_dir, "activity_config.json"), 'w') as f:
+        json.dump(activity_conf, f, indent=2)
+    with open(os.path.join(local_dir, "employees.json"), 'w') as f:
+        json.dump(employees, f, indent=2)
+    with open(os.path.join(local_dir, "demand.json"), 'w') as f:
+        json.dump(weekly_demand, f, indent=2)
+        
+    # Push massivo della cartella temporanea
+    api.upload_folder(
+        folder_path=local_dir,
+        path_in_repo=f"activities/{activity_name}",
+        repo_id=DATASET_REPO_ID,
+        repo_type="dataset",
+        commit_message=f"Init workspace: {activity_name}"
+    )

src/utils/visualization.py

@@ -0,0 +1,33 @@
+import numpy as np
+from src.config import cfg
+
+def get_final_coverage_matrix(schedule, employees):
+    """
+    Proietta il genoma ottimizzato (la schedule finale) sulla matrice temporale.
+    Genera il tensore 2D di copertura reale (Staffing effettivo) 
+    utilizzato per il rendering grafico su UI e l'analisi finale degli scostamenti.
+    """
+    num_days = 7
+    num_slots = cfg.daily_slots
+    
+    # Inizializzazione matrice globale di copertura
+    coverage = np.zeros((num_days, num_slots), dtype=int)
+    
+    for i, emp in enumerate(employees):
+        # Estrazione del fenotipo (firma oraria comprensiva di pause VDT)
+        mask = emp['mask']
+        
+        for day in range(num_days):
+            start = schedule[i, day]
+            
+            # Applicazione solo se il dipendente è schedulato (esclude OFF/Assenze)
+            if start >= 0:
+                # Boundary check: tronca la maschera se il turno sforerebbe la griglia oraria del giorno
+                end = min(start + len(mask), num_slots)
+                real_len = end - start
+                
+                # Proiezione algebrica della maschera operativa sulla coverage globale
+                if real_len > 0: 
+                    coverage[day, start:end] += mask[:real_len]
+                    
+    return coverage