fix: write results to /tmp to avoid permission denied on HF mounted storage

README.md

@@ -7,17 +7,182 @@ sdk: docker
 pinned: false
 ---
 
+## Setup ed Esecuzione (Docker)
+
+### Prerequisiti
+
+- Docker e Docker Compose installati
+- File Excel con i dati dei progetti PNRR
+
+### Configurazione Ambiente
+
+1. **Crea il file di configurazione ambiente:**
+
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Configura la chiave API OpenAI nel file `.env`:**
+
+   ```
+   OPENAI_API_KEY='sk-xxxxxxxxxxxxxxxxxxxxxxx'
+   ```
+
+   Per ottenere una chiave API OpenAI:
+   - Registrati o accedi a [OpenAI Platform](https://platform.openai.com)
+   - Vai nella sezione "API Keys" nel tuo profilo
+   - Crea una nuova chiave API
+   - Copia la chiave e inseriscila nel file `.env`
+
+### Avvio dell'Applicazione
+
+```bash
+docker compose -f docker/compose.base.yaml up --build
+```
+
+L'applicazione sarà disponibile su: **http://localhost:8501**
+
+### Monitoraggio
+
+Per visualizzare i log del container:
+
+```bash
+docker container logs -f semantic_filter
+```
+
+## 🎯 Funzionalità dell'Applicazione
+
+### 🔍 Filtro Semantico
+
+**Scopo**: Identificare automaticamente progetti PNRR rilevanti basandosi su query in linguaggio naturale.
+
+**Come funziona**:
+
+- Utilizza modelli di AI per comprendere il significato semantico delle descrizioni dei progetti
+- Confronta la query dell'utente con il contenuto dei progetti per trovare corrispondenze concettuali
+- Assegna un punteggio di confidenza a ogni progetto basato sulla rilevanza
+
+**Come usarlo**:
+
+1. Carica il file Excel contenente i progetti PNRR
+2. Imposta la soglia di confidenza (0.0-1.0) per filtrare i risultati
+3. Scrivi una query descrittiva in linguaggio naturale (es. "progetti di digitalizzazione nelle scuole", "infrastrutture sostenibili", "riqualificazione urbana")
+4. Scegli se aggiungere i risultati come nuova colonna o creare un nuovo file
+5. Avvia la ricerca e scarica i risultati
+
+**Output**: File Excel con i progetti filtrati e punteggi di rilevanza
+
+### 🎯 Analisi Cluster
+
+**Scopo**: Raggruppare automaticamente progetti simili in cluster tematici per identificare pattern ricorrenti e aree di investimento comuni.
+
+**Come funziona**:
+
+- Analizza il contenuto testuale delle colonne selezionate usando tecniche di machine learning
+- Applica preprocessing intelligente rimuovendo stopwords italiane, termini PNRR comuni e parole personalizzate dall'utente
+- Raggruppa progetti con caratteristiche simili in cluster tematici usando embeddings semantici
+- Genera automaticamente titoli, descrizioni e parole chiave per ogni cluster tramite AI
+- Calcola statistiche di distribuzione dei progetti
+
+**Come usarlo**:
+
+1. Carica il file Excel contenente i progetti PNRR
+2. Seleziona le colonne testuali da utilizzare per il clustering (es. titolo progetto, descrizione, sintesi)
+3. Configura i parametri:
+   - **Automatico**: L'algoritmo determina il numero ottimale di cluster
+   - **Manuale**: Specifica un numero fisso di cluster
+4. **Personalizza la blacklist** (opzionale):
+   - Aggiungi parole specifiche da escludere dall'analisi
+   - Inserisci termini troppo generici o irrilevanti per il tuo contesto
+   - Le parole possono essere inserite separate da virgole o una per riga
+   - Esempi: nomi di enti frequenti, termini tecnici comuni, location ricorrenti
+5. Avvia l'analisi e attendi il completamento
+6. Esplora i risultati nei cluster generati
+7. **🆕 Visualizza il plot PCA**: Analizza la distribuzione spaziale dei cluster nel grafico interattivo
+8. Scarica i risultati:
+   - **Sommario Cluster**: File con titoli, descrizioni e statistiche
+   - **Dati con Cluster ID**: File originale con aggiunta dell'identificativo cluster
+
+**Output**:
+
+- Sommario dei cluster con titoli, descrizioni, parole chiave e progetti campione
+- Dataset originale arricchito con l'ID del cluster di appartenenza
+- Visualizzazioni della distribuzione dei progetti per cluster
+- **🆕 Plot PCA interattivo**: Visualizzazione bidimensionale dei cluster nello spazio degli embeddings
+
+### 📊 Visualizzazione PCA dei Cluster
+
+**Caratteristiche**:
+
+- **Riduzione dimensionale**: I complessi embeddings multidimensionali vengono ridotti a 2 dimensioni tramite PCA (Principal Component Analysis)
+- **Plot interattivo**: Visualizzazione Plotly con zoom, pan e informazioni al passaggio del mouse
+- **Codifica colori**: Ogni cluster ha un colore distintivo per facilitare l'identificazione
+- **Informazioni dettagliate**: Hover con titolo cluster, descrizione e numero di progetti
+- **Varianza spiegata**: Mostra quanto della variabilità originale è preservata nelle due componenti principali
+
+**Interpretazione**:
+
+- Punti vicini rappresentano progetti semanticamente simili
+- Gruppi di punti dello stesso colore mostrano la coesione del cluster
+- La distanza tra cluster indica quanto sono diversi tematicamente
+- La percentuale di varianza spiegata indica l'affidabilità della rappresentazione 2D
+
+### 🎯 Blacklist Personalizzata
+
+**Scopo**: Migliorare la qualità dei cluster escludendo parole irrilevanti specifiche del tuo dataset.
+
+**Benefici**:
+
+- **Cluster più precisi**: Rimuovendo parole generiche, i cluster si basano su termini realmente distintivi
+- **Controllo granulare**: Personalizza l'analisi in base al tuo contesto specifico
+- **Flessibilità**: Testa diverse configurazioni per ottimizzare i risultati
+
+**Esempi di parole da escludere**:
+
+- Termini troppo frequenti: "progetto", "attività", "servizio"
+- Nomi di enti ricorrenti: "comune", "regione", "asl"
+- Parole tecniche generiche: "sistema", "gestione", "sviluppo"
+- Location comuni nel dataset: "milano", "roma", "italia"
+
+## 📋 Formato File
+
+L'applicazione è **completamente flessibile** riguardo al formato del file Excel:
+
+### ✅ Requisiti Minimi
+
+- File in formato Excel (.xlsx)
+- Almeno una colonna contenente testo descrittivo
+
+### 🎯 Adattabilità
+
+- **Nomi colonne**: Possono essere qualsiasi, l'interfaccia mostrerà tutte le colonne disponibili
+- **Struttura dati**: Qualsiasi struttura è supportata
+- **Selezione dinamica**: L'utente sceglie quali colonne utilizzare per l'analisi
+
+### 🏆 Colonne Consigliate (Opzionali)
+
+Per progetti PNRR, colonne come queste migliorano la qualità dell'analisi:
+
+- **Titolo/Nome Progetto**: Identificazione del progetto
+- **Descrizione/Sintesi**: Contenuto descrittivo dettagliato
+- **Settore/Ambito**: Area tematica del progetto
+- **Soggetto/Ente**: Organizzazione responsabile
+- **Località**: Informazioni geografiche
+
+> **💡 Suggerimento**: Più contenuto testuale descrittivo è disponibile, migliore sarà la qualità dell'analisi semantica e del clustering, indipendentemente dai nomi delle colonne.
+
 # 🚀 Deploy su Hugging Face Spaces: PNRR Data Processor
 
 Questa guida descrive i passaggi necessari per configurare, pubblicare e aggiornare l'applicazione "PNRR Data Processor" su [Hugging Face Spaces](https://huggingface.co/spaces).
 
 ## 💻 Risorse di Sistema Necessarie
+
 L'applicazione utilizza modelli di embedding (`sentence-transformers`), indici vettoriali (`faiss-cpu`) e librerie di manipolazione dati (`pandas`, `scikit-learn`). Per funzionare correttamente senza errori di memoria (OOM), l'ambiente di hosting richiede:
 
-* **RAM:** Minimo 4 GB (Consigliati 16 GB per elaborazioni fluide di cluster numerosi).
-* **CPU:** Almeno 2 vCPU.
-* **Storage:** Archiviazione persistente per salvare i risultati generati nella cartella `/app/results`.
-* **Porta esposta:** Il container Docker deve obbligatoriamente esporre la porta **7860** (già configurata nel `Dockerfile`).
+- **RAM:** Minimo 4 GB (Consigliati 16 GB per elaborazioni fluide di cluster numerosi).
+- **CPU:** Almeno 2 vCPU.
+- **Storage:** Non è necessario storage persistente — i file generati vengono scritti in `/tmp` e scaricati direttamente dall'interfaccia.
+- **Porta esposta:** Il container Docker deve obbligatoriamente esporre la porta **7860** (già configurata nel `Dockerfile`).
 
 Il piano gratuito **"CPU Basic"** di Hugging Face Spaces (16 GB RAM, 2 vCPU) è perfettamente in grado di far girare l'applicazione.
 
@@ -26,30 +191,30 @@ Il piano gratuito **"CPU Basic"** di Hugging Face Spaces (16 GB RAM, 2 vCPU) è
 ## 🛠️ Fase 1: Creazione e Configurazione dello Space
 
 ### 1. Creazione Account e Space
+
 1. Crea un account gratuito su [Hugging Face](https://huggingface.co/).
 2. Vai in alto a destra (sulla tua immagine profilo) e seleziona **"New Space"**.
 3. Compila il modulo:
-   * **Space name:** `pnrr-data-processor` (o un nome a tua scelta).
-   * **License:** Seleziona *MIT* o lascia vuoto.
-   * **Select the Space SDK:** Scegli **Docker** e poi il template **Blank**.
-   * **Space Hardware:** Lascia il piano gratuito di default.
-   * **Visibility:** Imposta su **Public** (necessario per condividere l'app con i clienti tramite link senza richiedere il login ad HF).
+   - **Space name:** `pnrr-data-processor` (o un nome a tua scelta).
+   - **License:** Seleziona _MIT_ o lascia vuoto.
+   - **Select the Space SDK:** Scegli **Docker** e poi il template **Blank**.
+   - **Space Hardware:** Lascia il piano gratuito di default.
+   - **Visibility:** Imposta su **Public** (necessario per condividere l'app con i clienti tramite link senza richiedere il login ad HF).
 4. Clicca su **Create Space**.
 
 ### 2. Configurazione Credenziali (Secrets)
+
 L'applicazione è protetta da una schermata di login. Le password non sono nel codice sorgente e devono essere configurate nel cloud.
+
 1. Nella pagina del tuo Space, vai sulla tab **Settings**.
 2. Scorri fino a **Variables and secrets** e clicca su **New secret**.
 3. Aggiungi i seguenti segreti:
-   * `LOGIN_USER1` ➔ Valore: `nomeutente:password_scelta` (es. `admin:12345`)
-   * `OPENAI_API_KEY` ➔ Valore: `sk-...` (Inserisci la tua chiave API di OpenAI, se usata dai moduli dell'app).
+   - `LOGIN_USER1` ➔ Valore: `nomeutente:password_scelta` (es. `admin:12345`)
+   - `OPENAI_API_KEY` ➔ Valore: `sk-...` (Inserisci la tua chiave API di OpenAI, se usata dai moduli dell'app).
+
+### 3. Storage
 
-### 3. Configurazione Storage Persistente (Gratuito)
-Per evitare che i file CSV ed Excel generati vadano persi quando l'app va in standby:
-1. Sempre in **Settings**, scorri fino alla sezione **Storage**.
-2. Clicca su **Attach a storage bucket** (potrebbe chiederti di crearne uno nuovo, accetta).
-3. Alla voce **Mount path**, inserisci esattamente: `/app/results`.
-4. Salva. Ora l'app salverà i file in modo permanente.
+Non è necessario (né consigliato) attaccare uno storage persistente di HF Spaces. I file generati vengono scritti in `/tmp/results` all'interno del container e sono scaricabili direttamente tramite i pulsanti di download nell'interfaccia. Montare un bucket su `/app/results` causerebbe errori di permesso (Permission denied) perché il volume sovrascrive i permessi impostati nel Dockerfile.
 
 ---
 
@@ -58,12 +223,14 @@ Per evitare che i file CSV ed Excel generati vadano persi quando l'app va in sta
 Per inviare il codice dal tuo computer a Hugging Face senza sovrascrivere la tua repository principale (es. Bitbucket), configureremo HF come destinazione remota secondaria.
 
 ### 1. Generare un Access Token
+
 1. Vai su Hugging Face ➔ **Settings** ➔ **Access Tokens**.
 2. Clicca su **New token**.
 3. Nominalo `Deploy-App` e imposta il Type su **Write**.
 4. Copia il token generato (`hf_...`). **Attenzione:** non inserire MAI questo token nel codice sorgente.
 
 ### 2. Collegare il repository locale
+
 Apri il terminale nella cartella del progetto locale e aggiungi Hugging Face come `remote` (chiamato `hf`).
 Sostituisci `TUO_NOME_UTENTE`, `TUO_TOKEN` e `NOME_SPACE` con i tuoi dati reali:
 
@@ -78,21 +245,25 @@ git remote add hf [https://TUO_NOME_UTENTE:TUO_TOKEN@huggingface.co/spaces/TUO_N
 Ogni volta che fai una modifica al codice sul tuo computer e vuoi pubblicare l'aggiornamento sull'app in produzione, segui questi 3 passaggi nel terminale:
 
 **1. Registra le modifiche (Commit):**
+
 ```bash
 git add .
 git commit -m "Descrizione dell'aggiornamento"
 ```
 
 **2. Invia alla tua repository principale (es. Bitbucket):**
+
 ```bash
 git push origin main
 ```
 
 **3. Invia a Hugging Face per avviare il deploy:**
+
 ```bash
 git push hf main
 ```
-*(Nota: se il tuo branch locale principale si chiama `master`, usa il comando `git push hf master:main`).*
+
+_(Nota: se il tuo branch locale principale si chiama `master`, usa il comando `git push hf master:main`)._
 
 Non appena eseguito il comando `push hf`, Hugging Face rileverà il nuovo codice e inizierà automaticamente la ricostruzione del container Docker. L'app sarà online in circa 2-3 minuti.
 
@@ -100,6 +271,6 @@ Non appena eseguito il comando `push hf`, Hugging Face rileverà il nuovo codice
 
 ## ⚠️ Note Importanti e Limitazioni
 
-* **Sleep Mode:** Poiché l'app è ospitata sul piano gratuito, se non riceve traffico web per 48 ore consecutive, il server andrà in pausa ("Sleep"). Al primo accesso successivo, l'utente vedrà una schermata di caricamento per circa 1-2 minuti mentre il container si riavvia. Dopodiché, l'app tornerà fluida e responsiva.
-* **Link Diretto per Demo:** Per inviare l'app a un cliente offrendo un'esperienza a tutto schermo (nascondendo l'interfaccia di Hugging Face), usa l'URL diretto. Clicca sui tre puntini `...` in alto a destra sull'app in esecuzione ➔ **Embed this Space** ➔ Copia il **Direct URL**.
-* **Gestione Segreti:** Non committare mai token di Hugging Face, password in chiaro o chiavi API nei file di codice o nei Notebook Jupyter (`.ipynb`). Il sistema di sicurezza di HF bloccherà automaticamente il caricamento del codice in caso di leak.
+- **Sleep Mode:** Poiché l'app è ospitata sul piano gratuito, se non riceve traffico web per 48 ore consecutive, il server andrà in pausa ("Sleep"). Al primo accesso successivo, l'utente vedrà una schermata di caricamento per circa 1-2 minuti mentre il container si riavvia. Dopodiché, l'app tornerà fluida e responsiva.
+- **Link Diretto per Demo:** Per inviare l'app a un cliente offrendo un'esperienza a tutto schermo (nascondendo l'interfaccia di Hugging Face), usa l'URL diretto. Clicca sui tre puntini `...` in alto a destra sull'app in esecuzione ➔ **Embed this Space** ➔ Copia il **Direct URL**.
+- **Gestione Segreti:** Non committare mai token di Hugging Face, password in chiaro o chiavi API nei file di codice o nei Notebook Jupyter (`.ipynb`). Il sistema di sicurezza di HF bloccherà automaticamente il caricamento del codice in caso di leak.

modules/cluster_analysis.py

@@ -15,7 +15,7 @@ import plotly.express as px
 import plotly.graph_objects as go
 
 
-RESULTS_DIR = '/app/results'
+RESULTS_DIR = '/tmp/results'
 SAVE_PATH_CLUSTERS = os.path.join(RESULTS_DIR, 'cluster_results.xlsx')
 SAVE_PATH_ORIGINAL = os.path.join(RESULTS_DIR, 'data_with_clusters.xlsx')
 EMBEDDING_MODEL_NAME = 'sentence-transformers/all-MiniLM-L6-v2'

modules/semantic_filter.py

@@ -8,7 +8,7 @@ from modules import column_query_agent
 from langchain_huggingface import embeddings
 
 
-SAVE_PATH = 'semantic_filter_results.xlsx'
+SAVE_PATH = '/tmp/semantic_filter_results.xlsx'
 LLM_MODEL_NAME = 'gpt-4o-mini'
 EMBEDDING_MODEL_NAME = 'sentence-transformers/all-MiniLM-L6-v2'
 
@@ -56,7 +56,7 @@ def apply(
         df_reduced = chunk[relevant_columns]
         db = create.build_faiss(
             df_reduced,
-            index_path='faiss_index',
+            index_path='/tmp/faiss_index',
             embedder=embedder
         )
         results = search.multi_column(db, chunk, query_pairs, threshold)