README.md

---
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.**