README.md

metadata

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:

   git clone <repository-url>
   cd workforce-scheduler
   

2. Configura l'ambiente:

   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:

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.