README UML Quick Start API Tutorial

Etna Tremor Monitor

Questo progetto Python monitora il tremore vulcanico del Monte Etna recuperando dati sismici, calcolando i valori RMS orari, generando report e inviando notifiche tramite Telegram. L'interpretazione basata sull'IA sfrutta un modello locale servito tramite Ollama.

Panoramica Architettura (UML) | Guida Rapida (Quick Start)

✨ Caratteristiche Principali

Acquisizione Dati Sismici

Scarica dati da stazioni sismiche intorno all'Etna tramite servizi web FDSN (INGV).

Download Incrementale

Gestisce un download efficiente e l'archiviazione locale di file miniSEED, scaricando solo dati nuovi.

Calcolo RMS

Elabora i dati grezzi per calcolare i valori RMS medi orari, un indicatore dell'ampiezza del tremore.

Interpretazione AI

Utilizza un modello Ollama locale per fornire un'analisi testuale dei pattern di tremore osservati.

Reportistica PDF

Crea un report PDF completo con grafici, tabelle, mappe di polarizzazione e analisi AI.

Notifiche Telegram

Invia grafici, riepiloghi, report PDF e file Excel a una chat Telegram specificata.

Embeddings dei Bollettini

Calcola gli embedding dei bollettini INGV per trovare i comunicati più pertinenti per le risposte AI.

Containerizzazione Docker

Fornito con un `docker-compose.yml` e un `Dockerfile` a più stadi per un deployment semplice.

Analisi di Polarizzazione

Elabora i 3 componenti sismici per calcolare il back-azimuth e la direzione di provenienza del segnale.

🚀 Setup e Avvio

1. Prerequisiti

Assicurarsi di avere installato Docker e Docker Compose. È necessario anche un bot Telegram e il servizio Ollama in esecuzione.

2. Configura le Variabili d'Ambiente

Copia il file .env.example in .env e personalizza le variabili (token, URL, etc.).

TELEGRAM_BOT_TOKEN=IL_TUO_TOKEN_BOT_TELEGRAM
TELEGRAM_CHAT_ID=IL_TUO_ID_CHAT_TELEGRAM
OLLAMA_MODEL=qwen3:1.7b
OLLAMA_URL=http://ollama:11434
# ... e altre variabili

3. Build e Avvia con Docker Compose

Il primo comando avvia il servizio LLM, il secondo avvia l'applicazione.

# Avvia il servizio Ollama e scarica il modello
docker-compose up --build -d ollama

# Avvia il servizio principale di Etna
docker-compose up -d etna-service

4. Controllare i Log (Opzionale)

Per visualizzare l'output dello script in esecuzione:

docker-compose logs -f etna-service

⚙️ Come Funziona

Lo script etna.cli, orchestrato da etna.scheduler, esegue un flusso di lavoro automatizzato per il monitoraggio.

1

Inizializzazione e Finestra Temporale

Carica la configurazione e definisce il periodo di analisi (es. ultimi 7 giorni).

2

Acquisizione e Calcolo RMS

Per ogni stazione, scarica i file miniSEED e calcola i valori RMS aggregandoli su base oraria.

3

Generazione Artefatti

Crea il grafico RMS, la mappa di polarizzazione e interroga il modello AI per un'interpretazione testuale.

4

Creazione Report PDF

Assembla tutti gli artefatti (grafici, tabelle, testo AI) in un unico report PDF completo.

5

Notifica

Invia il report, i grafici e i dati su Telegram, e infine pulisce i file temporanei.

🔧 Configurazione

La configurazione è gestita tramite variabili d'ambiente (nel file .env) e file di configurazione YAML.

Variabili d'Ambiente Principali

  • TELEGRAM_BOT_TOKEN: Token del bot Telegram.
  • TELEGRAM_CHAT_ID: ID della chat per le notifiche.
  • OLLAMA_MODEL: Modello LLM da utilizzare (es. qwen3:1.7b).
  • OLLAMA_URL: URL del servizio Ollama.
  • ETNA_CRON: Espressione cron per il report giornaliero (default 0 8 * * *).
  • STATIONS_CONFIG: Percorso del file di configurazione delle stazioni (default config/stations.yaml).
  • ETNA_HOST: Nome di dominio per il servizio API (usato da Nginx e Certbot).

🚧 Roadmap

  • ✅ Estendere `etna.cli` con analisi SSAM.
  • ✅ Supporto a 3 componenti sismiche con polarizzazione.
  • ⏳ Refactoring scientifico del codice con copertura di test.
  • ⏳ Integrazione dati infrasonici e flussi di gas (SO₂) (funzioni sperimentali presenti).
  • 📋 Creazione dashboard multiparametrica.
  • 📋 Correlazione RMS sismico + acustico + geochimico.
  • ⏳ Addestramento Autoencoder LSTM per rilevamento anomalie (funzioni sperimentali presenti).
  • 📋 Dataset supervisionati per classificazione stati vulcanici.
  • ✅ Gestione dataset di classificazione con il comando `etna dataset`.
  • 📋 Reti neurali per previsione probabilistica di eventi eruttivi.

📜 Disclaimer

I dati e le interpretazioni forniti da questo script sono intesi per scopo informativo e di monitoraggio personale. Per informazioni ufficiali e allerte sullo stato di attività del Monte Etna, fare sempre riferimento ai bollettini e ai comunicati emessi dall'Istituto Nazionale di Geofisica e Vulcanologia (INGV) - Osservatorio Etneo: www.ct.ingv.it.