Etna

1. Introduzione e Scopo

Etna è un progetto software per la creazione di una pipeline automatizzata per il monitoraggio multi-parametrico del Monte Etna. Lo scopo è acquisire dati da fonti aperte (sismici, infrasuoni, geochimici), elaborarli per estrarre caratteristiche significative e sperimentare l’uso di tecniche di Intelligenza Artificiale, come gli embeddings e i Large Language Models (LLM), per creare rappresentazioni “AI-ready” dei dati vulcanologici.

Il sistema gestisce l’intero ciclo di vita del dato:

2. Contesto e Motivazioni

Questo progetto non intende sostituire i sistemi di monitoraggio ufficiali dell’INGV. Nasce come un’esplorazione tecnica e didattica per affrontare le sfide legate al trattamento di dati eterogenei e per valutare come le moderne tecniche di AI possano arricchire l’analisi automatizzata e semi-automatizzata dei fenomeni vulcanici.

3. Architettura del Sistema

L’architettura è basata su microservizi containerizzati e orchestrati con docker-compose. Questa scelta garantisce modularità, scalabilità e portabilità.

I componenti principali sono:

4. Diagrammi UML — Dettagli Implementativi

Questa sezione fornisce una visione approfondita dell’architettura software e dei flussi di esecuzione attraverso diagrammi UML dettagliati.

4.1 Package Diagram — Dipendenze Moduli

Architettura del pacchetto `etna`: CLI, Scheduler, API, Monitoring e loro dipendenze verso fetch, processing, reporting, embeddings e telegram.

graph TD subgraph etna["📦 etna"] cli[cli] --> fetch[data.fetch] cli --> rms[processing.rms_processing] cli --> pol[processing.polarization] cli --> rep[reporting] cli --> tg[telegram.utils] rep --> emb[embeddings] sched[scheduler] --> cli sched --> alerts[monitoring.alerts] sched --> emb alerts --> emb api[api.api_server] --> cli api --> emb api --> rep end style cli fill:#ff6b35,color:#fff style sched fill:#f7931e,color:#fff style api fill:#ffcc00,color:#333

4.2 Sequence Diagram — CLI Main

Flusso di esecuzione principale della CLI: fetch dati RMS, processing orario, polarizzazione, generazione report PDF con interpretazione LLM, invio Telegram.

sequenceDiagram actor Scheduler participant CLI participant fetch participant rms as rms_processing participant pol as polarization participant rep as reporting participant tg as telegram.utils Scheduler->>CLI: main() CLI->>fetch: estrai_rms_settimanale_incrementale() CLI->>rms: aggregate_rms_hourly() CLI->>rms: aggregate_energy_hourly() CLI->>pol: run_polarization() CLI->>rep: get_llm_interpretation() CLI->>rep: create_pdf_report() alt Telegram enabled CLI->>tg: send_telegram_photo() CLI->>tg: send_telegram_document() end CLI-->>Scheduler: return critical_flag

4.3 Sequence Diagram — Scheduler

Gestione chiamate orarie e modalità critica: in condizioni normali esegue ogni ora, in finestra critica passa a frequenza 20 minuti per monitoraggio intensivo.

sequenceDiagram actor User participant Scheduler participant AsyncIO as AsyncIOScheduler participant CLI User->>Scheduler: /start or /report Scheduler->>AsyncIO: start() loop Monitoraggio Continuo Scheduler->>CLI: main() alt Critical window CLI->>Scheduler: _start_critical_mode() Note over Scheduler,CLI: Frequenza: ogni 20 min Scheduler->>CLI: main() [20min interval] else Normal mode Note over Scheduler,CLI: Frequenza: ogni ora Scheduler->>CLI: main() [hourly] end end

4.4 Class Diagram — Modello Autoencoder

Architettura LSTM Autoencoder per rilevazione anomalie: encoder/decoder LSTM, funzioni di utilità per preparazione sequenze, training, calcolo errori di ricostruzione.

classDiagram class LSTMAutoencoder { +int input_size +int hidden_size +nn.LSTM encoder +nn.LSTM decoder +__init__(input_size=1, hidden_size=16) +forward(x: Tensor) Tensor } class AutoencoderUtils { +prepare_sequences(series, seq_len) ndarray +train_autoencoder(series, seq_len, epochs, lr) LSTMAutoencoder +reconstruction_errors(model, series, seq_len) ndarray +detect_anomalies(errors, threshold) ndarray } note for AutoencoderUtils "Python functions module" class nn_LSTM { +input_size +hidden_size +num_layers +batch_first } note for nn_LSTM "PyTorch LSTM" LSTMAutoencoder *-- nn_LSTM : encoder LSTMAutoencoder *-- nn_LSTM : decoder AutoencoderUtils ..> LSTMAutoencoder : istanzia e utilizza

4.5 Activity Diagram — Monitoraggio Allerte INGV

Flusso `check_ingv_alerts()`: verifica feed RSS o scraping pagina bollettini, download PDF, indicizzazione embeddings nel vector store, notifica Telegram.

flowchart TD Start([🚀 Avvio check_ingv_alerts]) --> CheckRSS{Feed RSS
disponibile?} CheckRSS -- Sì --> ParseRSS[📡 Parse ultima entry RSS] CheckRSS -- No --> CheckPage[🔍 Scraping Pagina Bollettini] ParseRSS --> CheckNew{È una nuova
allerta?} CheckPage --> FindLatest[📄 Trova link PDF più recente] FindLatest --> CheckNew CheckNew -- No --> End([✅ Fine]) CheckNew -- Sì --> Download[⬇️ Scarica PDF] Download --> Index[🧠 Indicizza Embeddings
Vector Store] Index --> Notify[📨 Invia Documento
su Telegram] Notify --> UpdateState[💾 Aggiorna .alerts_state] UpdateState --> End style Start fill:#ff6b35,color:#fff style End fill:#4caf50,color:#fff style Download fill:#f7931e,color:#fff style Notify fill:#2196f3,color:#fff

4.6 Component Diagram — API Server FastAPI

Endpoint REST esposti: events, stations activity/RMS/polarization/SSAM, correlations, anomaly detection, bulletins. Autenticazione via API key.

classDiagram class APIServer { +FastAPI app +verify_api_key(key: str) bool +startup_event() +shutdown_event() } class Endpoints { +GET_events() +GET_stations_activity() +GET_stations_rms() +GET_correlations() +GET_stations_polarization() +GET_stations_ssam() +POST_anomalies_detect() +GET_bulletins() } note for Endpoints "REST API endpoints" class InternalModules { +cli_report +processing_polarization +processing_rms_processing +models_autoencoder +embeddings +data_fetch } note for InternalModules "Python modules" class Security { +APIKeyHeader +HTTPException_401_403 } note for Security "Middleware layer" APIServer --> Endpoints : espone APIServer --> Security : applica Endpoints ..> InternalModules : invoca

5. Flusso di Lavoro (Pipeline)

Il scheduler è il motore della pipeline e scandisce le seguenti fasi:

  1. Acquisizione Dati:
    • Sismico e Infrasuoni: Vengono scaricati i dati in formato mseed dai server FDSN (es. INGV) per le stazioni configurate in config/stations.yaml.
    • Dati Gas: Vengono recuperati dati sulla composizione dei gas da fonti web pubbliche.
    • I dati vengono salvati localmente con una struttura a directory basata sulla data.
  2. Elaborazione e Feature Extraction:
    • I dati grezzi vengono pre-processati (filtraggio, detrending).
    • Vengono calcolate diverse feature, tra cui:
      • SSAM (Seismic Spectral Amplitude Measurement): Misura l’ampiezza spettrale media in diverse bande di frequenza.
      • RMS (Root Mean Square): Calcola l’energia del segnale nel tempo.
      • Analisi di Polarizzazione: Stima la direzionalità e la rettilinearità del segnale sismico.
      • Cross-correlazione: Analizza la somiglianza tra i segnali di diverse stazioni.
    • I risultati vengono salvati in formato Parquet per efficienza.
  3. Generazione di Embeddings:
    • Le feature elaborate (es. spettrogrammi o SSAM) vengono date in input a un Autoencoder basato su PyTorch.
    • L’output dello strato latente (encoder) del modello costituisce l’embedding: una rappresentazione vettoriale densa e a bassa dimensionalità del dato originale.
    • Gli embeddings sono progettati per catturare le caratteristiche essenziali del segnale e vengono usati per analisi di similarità, clustering e classificazione.
  4. Monitoraggio e Notifiche:
    • Il sistema controlla i valori delle ultime feature calcolate.
    • Se vengono superate soglie predefinite, vengono inviati alert tramite un bot Telegram, allegando grafici significativi.
  5. Reporting:
    • Periodicamente, vengono generati report di sintesi e visualizzazioni che vengono inviati via Telegram.

6. Componenti e Tecnologie

7. Deployment

Il deployment è interamente gestito tramite Docker e docker-compose. I servizi sono definiti nel file docker-compose.yml.

Diagramma di Deployment

@startuml
!theme plain
title Diagramma di Deployment Semplificato

cloud “GitHub / Docker Registry” as Registry {
package “etna-app:latest”
package “etna-scheduler:latest”
package “etna-api:latest”
}

node “Server (VPS, On-premise)” as Server {

artifact "docker-compose.yml" as ComposeFile  
file ".env (variabili d'ambiente)" as EnvFile  
  
node "Docker Engine" as Docker {  
    container "nginx" as NginxContainer  
    container "etna-app" as AppContainer  
    container "etna-api" as ApiContainer  
    container "etna-scheduler" as SchedulerContainer  
}  
  
database "Storage Locale (Volumi)" as FS {  
    folder "Dati"  
    folder "Config"  
}

ComposeFile ..\> Docker : orchestra  
EnvFile ..\> Docker : configura  
  
AppContainer \--u-\> FS  
ApiContainer \--d-\> FS  
SchedulerContainer \--d-\> FS

NginxContainer \--\> AppContainer  
NginxContainer \--\> ApiContainer   }

actor “Amministratore” as Admin

Admin --> Server : `docker-compose up`
Registry ..> Docker : `pull` delle immagini

@enduml

8. Interfaccia Conversazionale: GPT Expert Assistant

Un’applicazione avanzata del sistema è la possibilità di collegare un GPT Expert (come un Custom GPT di OpenAI) all’API REST per creare un assistente conversazionale specializzato.

🧠 GPT Expert: Etna Tremor Monitor Assistant

📝 Descrizione e Modalità Operativa (Prompt di sistema)

Sei un assistente AI avanzato, specializzato nell’analisi di eventi sismici e dati geofisici relativi al vulcano Etna. La tua missione è agire come un ponte intelligente tra gli esseri umani (ricercatori, tecnici, operatori di protezione civile) e i dati grezzi, trasformando le loro domande in linguaggio naturale in query precise verso le API REST.

Il tuo processo operativo è il seguente:

  1. Ascolto e Interpretazione: Analizzi la domanda dell’utente per comprendere l’intento, i parametri e i dati di interesse.
  2. Query alle API: Traduci la richiesta in una o più chiamate mirate agli endpoint disponibili.
  3. Analisi e Sintesi: Ricevi i dati in formato JSON, li analizzi, li aggreghi e identifichi le informazioni salienti.
  4. Risposta Contestualizzata: Fornisci una risposta sintetica, chiara e scientificamente corretta. Arricchisci la risposta con spiegazioni contestuali per aiutare l’utente a comprendere il significato dei dati.

Le tue potenzialità:

I tuoi limiti:

🧭 Guida all’Interazione: Come Chiedermi le Cose (Istruzioni per l’Utente)

Puoi dialogare con me in modo naturale. Per ottenere i risultati migliori e più rapidi, segui questi esempi e consigli.

📅 Ottenere gli eventi sismici recenti

📊 Conoscere quali stazioni sono più attive

📈 Visualizzare l’andamento RMS di una o più stazioni

🧭 Analizzare la direzione media delle onde (polarizzazione)

📡 Ottenere i dati di ampiezza spettrale (SSAM)

🔗 Eseguire analisi di correlazione

📄 Consultare i bollettini ufficiali INGV

🕵️ Rilevare anomalie

📜 Accedere alla politica sulla privacy

📚 Riepilogo Endpoint Principali (Per Utenti Tecnici)

Questa è una sintesi delle chiamate API che eseguo per risponderti. Conoscere questi dettagli può aiutarti a formulare richieste ancora più precise.

9. Sviluppi Futuri e Aree di Miglioramento

Link Correlati